Dev Docs

Appearance

Subscriptions API ​

Manage recurring subscriptions including listing, cancellation, reactivation, payment method updates, and customer self-service operations.

Base URL: https://your-site.com/wp-json/fluent-cart/v2

All monetary values are in cents (e.g., $10.00 = 1000).

Admin Endpoints ​

Admin endpoints require an authenticated WordPress user with the appropriate FluentCart capability. Authorization is handled by the OrderPolicy.

List Subscriptions ​

GET /fluent-cart/v2/subscriptions

Retrieve a paginated list of subscriptions with optional filtering, sorting, and search.

  • Permission: subscriptions/view
  • Policy: OrderPolicy

Parameters ​

ParameterTypeLocationRequiredDescription
pageintegerqueryNoPage number for pagination
per_pageintegerqueryNoNumber of records per page (default: 10, max: 200)
searchstringqueryNoSearch term. Searches status, subscription ID (#123), customer email ([email protected]), parent order ID, item name, vendor subscription/customer/plan IDs, payment method, billing interval, and bill count. Also supports operator syntax (e.g., ID = 5)
sort_bystringqueryNoColumn to sort by (default: id). Must be a fillable column on the Subscription model
sort_typestringqueryNoSort direction: asc or desc (default: desc)
active_viewstringqueryNoTab filter. One of: active, pending, intended, paused, trialing, canceled, failing, expiring, expired
filter_typestringqueryNoFilter mode: simple (default) or advanced
advanced_filtersstring (JSON)queryNoJSON-encoded array of advanced filter groups (requires Pro). Supports filtering by subscription, transaction, product, and license properties
witharray/stringqueryNoEager-load relations. Supports relation names and {relation}Count for counts
selectarray/stringqueryNoComma-separated list of columns to select
scopesarrayqueryNoModel scopes to apply
include_idsarray/stringqueryNoComma-separated IDs that must always be included in results
limitintegerqueryNoLimit number of records (used with non-paginated queries)
offsetintegerqueryNoOffset for records
user_tzstringqueryNoUser timezone for date filtering (e.g., America/New_York)

Search Behavior ​

The search parameter supports several input formats:

Input FormatBehavior
#123Searches by subscription ID
[email protected]Searches by customer email
canceled or cancelledMatches canceled status
Any other stringSearches across parent_order_id, item_name, vendor_subscription_id, vendor_customer_id, vendor_plan_id, current_payment_method, billing_interval, and bill_count

Advanced Filter Options ​

When using filter_type=advanced, the following filter categories are available:

CategoryFilterTypeDescription
Subscriptionvendor_subscription_idtextFilter by vendor subscription ID
Subscriptionstatusselections (multiple)Filter by subscription status
Subscriptionvariationremote tree selectFilter by product variation / order items
Subscriptionbilling_intervalselections (multiple)Filter by billing interval: yearly, half_yearly, quarterly, monthly, weekly, daily
Subscriptioncurrent_payment_methodselections (multiple)Filter by payment method
Subscriptioncreated_atdatesFilter by creation date range
Subscriptionnext_billing_datedatesFilter by next billing date range
Subscriptionbill_countnumericFilter by bill count
Transactiontransaction_idtext (relation)Filter by transaction vendor charge ID
Transactioncurrent_payment_methodselections (multiple)Filter by transaction payment method
Productproductremote tree selectFilter by product variation
Licenselicense_keytext (relation)Filter by license key (Pro only)
Licenselicense_statusselections (multiple)Filter by license status: active, disabled, expired (Pro only)

Response ​

json
{
  "data": {
    "current_page": 1,
    "data": [
      {
        "id": 1,
        "uuid": "abc123-def456",
        "status": "active",
        "item_name": "Pro Plan",
        "parent_order_id": 10,
        "customer_id": 5,
        "product_id": 3,
        "variation_id": 7,
        "vendor_subscription_id": "sub_1234567890",
        "vendor_customer_id": "cus_abc123",
        "vendor_plan_id": "price_xyz789",
        "current_payment_method": "stripe",
        "billing_interval": "monthly",
        "recurring_amount": 2999,
        "bill_times": 0,
        "bill_count": 6,
        "next_billing_date": "2025-02-15 00:00:00",
        "created_at": "2025-01-15 10:30:00",
        "updated_at": "2025-01-15 10:35:00"
      }
    ],
    "per_page": 10,
    "total": 50,
    "last_page": 5
  }
}

Example ​

bash
curl -X GET "https://example.com/wp-json/fluent-cart/v2/subscriptions?page=1&per_page=10&active_view=active" \
  -u "username:app_password"

Get Subscription Details ​

GET /fluent-cart/v2/subscriptions/{subscriptionOrderId}

Retrieve the full details of a single subscription including customer addresses, labels, activities, and related orders.

  • Permission: subscriptions/view
  • Policy: OrderPolicy

Parameters ​

ParameterTypeLocationRequiredDescription
subscriptionOrderIdintegerpathYesThe subscription ID

Response ​

The response includes the subscription with eager-loaded relations:

  • labels -- associated labels
  • activities.user -- activity log with user info
  • customer.shipping_address -- customer's primary shipping address
  • customer.billing_address -- customer's primary billing address
  • order.billing_address -- parent order's billing address
  • order.shipping_address -- parent order's shipping address

Also includes:

  • related_orders -- the parent order and all renewal orders (with order items)
  • selected_labels -- array of label IDs applied to the subscription
json
{
  "subscription": {
    "id": 1,
    "uuid": "abc123-def456",
    "status": "active",
    "item_name": "Pro Plan",
    "parent_order_id": 10,
    "customer_id": 5,
    "product_id": 3,
    "variation_id": 7,
    "vendor_subscription_id": "sub_1234567890",
    "vendor_customer_id": "cus_abc123",
    "current_payment_method": "stripe",
    "billing_interval": "monthly",
    "recurring_amount": 2999,
    "bill_times": 0,
    "bill_count": 6,
    "next_billing_date": "2025-02-15 00:00:00",
    "billing_address": { ... },
    "shipping_address": { ... },
    "labels": [ ... ],
    "activities": [ ... ],
    "customer": {
      "id": 5,
      "shipping_address": { ... },
      "billing_address": { ... }
    },
    "related_orders": [
      {
        "id": 10,
        "order_items": [
          {
            "id": 1,
            "order_id": 10,
            "post_title": "Pro Plan",
            "title": "Pro Plan",
            "quantity": 1,
            "payment_type": "subscription",
            "line_meta": { ... }
          }
        ]
      }
    ]
  },
  "selected_labels": [1, 3, 5]
}

Example ​

bash
curl -X GET "https://example.com/wp-json/fluent-cart/v2/subscriptions/1" \
  -u "username:app_password"

Error Response (404) ​

json
{
  "message": "Subscription not found",
  "action_text": "Back to Subscription list",
  "action_url": "/subscriptions"
}

Cancel Subscription ​

PUT /fluent-cart/v2/orders/{order}/subscriptions/{subscription}/cancel

Cancel a subscription both locally and with the remote payment gateway.

  • Permission: subscriptions/manage
  • Policy: OrderPolicy

Parameters ​

ParameterTypeLocationRequiredDescription
orderintegerpathYesThe parent order ID
subscriptionintegerpathYesThe subscription ID
cancel_reasonstringbodyYesReason for cancellation. Sanitized with sanitize_text_field

Response ​

json
{
  "message": "Subscription has been cancelled successfully!",
  "subscription": {
    "id": 1,
    "status": "canceled",
    ...
  }
}

Error Responses ​

Missing cancel reason:

json
{
  "message": "Please select cancel reason!"
}

Remote cancellation failure (subscription still cancelled locally):

json
{
  "message": "Subscription cancelled locally. Vendor Response: <vendor error message>"
}

Example ​

bash
curl -X PUT "https://example.com/wp-json/fluent-cart/v2/orders/10/subscriptions/1/cancel" \
  -u "username:app_password" \
  -H "Content-Type: application/json" \
  -d '{"cancel_reason": "Customer requested cancellation"}'

Fetch Subscription from Remote ​

PUT /fluent-cart/v2/orders/{order}/subscriptions/{subscription}/fetch

Re-sync a subscription's data from the remote payment gateway (e.g., Stripe, PayPal). Useful for resolving data inconsistencies between local records and the payment provider.

  • Permission: subscriptions/view
  • Policy: OrderPolicy

Parameters ​

ParameterTypeLocationRequiredDescription
orderintegerpathYesThe parent order ID
subscriptionintegerpathYesThe subscription ID

Response ​

json
{
  "message": "Subscription fetched successfully from remote payment gateway!",
  "subscription": {
    "id": 1,
    "status": "active",
    "vendor_subscription_id": "sub_1234567890",
    ...
  }
}

Error Response ​

json
{
  "message": "<gateway error message>"
}

Example ​

bash
curl -X PUT "https://example.com/wp-json/fluent-cart/v2/orders/10/subscriptions/1/fetch" \
  -u "username:app_password"

Update Vendor IDs Opt-in ​

PUT /fluent-cart/v2/orders/{order}/subscriptions/{subscription}/vendor-ids

Correct the gateway identifiers on a gateway-billed (automatic) subscription. Writes only vendor_subscription_id / vendor_customer_id — no renewal is voided, no invoice re-synced, no status event dispatched, and the gateway is not called.

Disabled unless the site opts in:

php
add_filter('fluent_cart/subscription/vendor_id_editing_enabled', '__return_true');

Parameters ​

ParameterTypeLocationRequiredDescription
orderintegerpathYesThe parent order ID
subscriptionintegerpathYesThe subscription ID
vendor_subscription_idstringbodyNoMax 45 chars, ^[a-zA-Z0-9_.-]+$. Omit to leave untouched; send "" to clear
vendor_customer_idstringbodyNoSame constraints

At least one of the two body fields must be present. The new vendor_subscription_id is claimed atomically — no other subscription on the same payment method may already hold it.

Response ​

json
{
  "message": "Vendor IDs have been updated successfully!",
  "subscription": {
    "id": 1,
    "collection_method": "automatic",
    "current_payment_method": "stripe",
    "vendor_subscription_id": "sub_1P9xyzABCdef",
    "vendor_customer_id": "cus_NffrFeUfNV2Hib"
  }
}

Error Responses ​

json
{ "message": "Vendor IDs can only be edited on an active gateway-billed subscription." }
{ "message": "Another subscription on this payment method is already using this Vendor Subscription ID." }
{ "message": "No changes detected." }

Example ​

bash
curl -X PUT "https://example.com/wp-json/fluent-cart/v2/orders/10/subscriptions/1/vendor-ids" \
  -u "username:app_password" \
  -H "Content-Type: application/json" \
  -d '{"vendor_subscription_id": "sub_1P9xyzABCdef"}'

Verify Vendor IDs Opt-in ​

POST /fluent-cart/v2/orders/{order}/subscriptions/{subscription}/verify-vendor-ids

Read-only lookup of a candidate id at the payment gateway, used before saving a correction. Writes nothing anywhere. Requires the same opt-in filter, plus a gateway declaring the verify_vendor_ids capability — Stripe and PayPal; every other gateway answers "This payment method does not support subscription lookup."

  • Permission: subscriptions/manage
  • Policy: OrderPolicy

Parameters ​

ParameterTypeLocationRequiredDescription
orderintegerpathYesThe parent order ID
subscriptionintegerpathYesThe subscription ID
vendor_subscription_idstringbodyYesThe candidate subscription ID to look up
vendor_customer_idstringbodyNoSent because some gateways nest the subscription under its customer

Response ​

json
{
  "message": "Subscription found at the payment gateway.",
  "verification": {
    "id": "sub_1P9xyzABCdef",
    "status": "active",
    "customer_id": "cus_NffrFeUfNV2Hib",
    "amount": "29.00",
    "currency": "USD",
    "next_billing_date": "2026-09-01 00:00:00"
  }
}

A hit proves the id exists in the merchant account whose credentials this store holds — not that it belongs to this store, since one merchant account can back several stores. Verification is advisory; the duplicate check on save is the hard guard.

Example ​

bash
curl -X POST "https://example.com/wp-json/fluent-cart/v2/orders/10/subscriptions/1/verify-vendor-ids" \
  -u "username:app_password" \
  -H "Content-Type: application/json" \
  -d '{"vendor_subscription_id": "sub_1P9xyzABCdef"}'
POST /fluent-cart/v2/orders/{order}/subscriptions/{subscription}/early-payment-link

Generate a URL that allows early payment of remaining installments on an installment-based subscription.

  • Permission: subscriptions/manage
  • Policy: OrderPolicy

Parameters ​

ParameterTypeLocationRequiredDescription
orderintegerpathYesThe parent order ID
subscriptionintegerpathYesThe subscription ID

Conditions ​

This endpoint requires all of the following conditions to be met:

  • Early payment feature must be enabled on the site
  • The subscription must belong to the specified order (parent_order_id must match order.id)
  • The subscription must have a finite number of installments (bill_times > 0)
  • The subscription status must be active or trialing
  • There must be remaining installments (bill_times - bill_count > 0)

Response ​

json
{
  "message": "Early payment link generated.",
  "payment_url": "https://your-site.com/?fluent-cart=early-installment-payment&subscription_hash=abc123-def456"
}

Error Responses ​

Feature not enabled:

json
{
  "message": "Early payment is not enabled for this site."
}

Invalid subscription for order:

json
{
  "message": "Invalid subscription for the specified order."
}

Not an installment subscription:

json
{
  "message": "Early payment is only available for installment subscriptions."
}

Subscription not active:

json
{
  "message": "Subscription must be active to make early payments."
}

All installments already paid:

json
{
  "message": "All installments have already been paid."
}

Example ​

bash
curl -X POST "https://example.com/wp-json/fluent-cart/v2/orders/10/subscriptions/1/early-payment-link" \
  -u "username:app_password"

Reactivate Subscription ​

PUT /fluent-cart/v2/orders/{order}/subscriptions/{subscription}/reactivate

Reactivate a previously canceled or paused subscription.

  • Permission: subscriptions/manage
  • Policy: OrderPolicy

Not Yet Available. This endpoint is registered but currently returns a "Not available yet" error. It is reserved for future implementation.

Parameters ​

ParameterTypeLocationRequiredDescription
orderintegerpathYesThe parent order ID
subscriptionintegerpathYesThe subscription ID

Response ​

json
{
  "message": "Not available yet"
}

Pause Subscription ​

PUT /fluent-cart/v2/orders/{order}/subscriptions/{subscription}/pause

Pause an active subscription.

  • Permission: subscriptions/manage
  • Policy: OrderPolicy

Not Yet Available. This endpoint is registered but currently returns a "Not available yet" error. It is reserved for future implementation.

Parameters ​

ParameterTypeLocationRequiredDescription
orderintegerpathYesThe parent order ID
subscriptionintegerpathYesThe subscription ID

Response ​

json
{
  "message": "Not available yet"
}

Resume Subscription ​

PUT /fluent-cart/v2/orders/{order}/subscriptions/{subscription}/resume

Resume a paused subscription.

  • Permission: subscriptions/manage
  • Policy: OrderPolicy

Not Yet Available. This endpoint is registered but currently returns a "Not available yet" error. It is reserved for future implementation.

Parameters ​

ParameterTypeLocationRequiredDescription
orderintegerpathYesThe parent order ID
subscriptionintegerpathYesThe subscription ID

Response ​

json
{
  "message": "Not available yet"
}

Customer Portal Endpoints ​

Customer portal endpoints are authenticated via the logged-in WordPress user. The system resolves the customer from the current user session. Authorization is handled by the CustomerFrontendPolicy.

All customer portal subscription endpoints use the subscription's UUID (not the numeric ID) for identification.

List Customer Subscriptions ​

GET /fluent-cart/v2/customer-profile/subscriptions

Retrieve a paginated list of subscriptions belonging to the currently logged-in customer. Subscriptions with pending or intended status are excluded.

  • Policy: CustomerFrontendPolicy
  • Auth: Logged-in WordPress user

Parameters ​

ParameterTypeLocationRequiredDescription
pageintegerqueryNoPage number for pagination (default: 1)
per_pageintegerqueryNoNumber of records per page (default: 10)

Response ​

If the user is not logged in, the endpoint returns an empty result set rather than an error:

json
{
  "message": "Success",
  "subscriptions": {
    "data": [],
    "total": 0,
    "per_page": 10,
    "current_page": 1,
    "last_page": 1
  }
}

Successful response with data:

json
{
  "message": "Success",
  "subscriptions": {
    "data": [
      {
        "uuid": "abc123-def456",
        "status": "active",
        "item_name": "Pro Plan",
        "billing_interval": "monthly",
        "recurring_amount": 2999,
        "next_billing_date": "2025-02-15 00:00:00",
        "bill_times": 0,
        "bill_count": 6,
        ...
      }
    ],
    "total": 5,
    "per_page": 10,
    "current_page": 1,
    "last_page": 1
  }
}

Example ​

bash
curl -X GET "https://example.com/wp-json/fluent-cart/v2/customer-profile/subscriptions?page=1&per_page=10" \
  -H "X-WP-Nonce: <nonce>"

Get Customer Subscription Details ​

GET /fluent-cart/v2/customer-profile/subscriptions/{subscription_uuid}

Retrieve full details of a specific subscription for the currently logged-in customer, including transactions, upgrade eligibility, and payment method capabilities.

  • Policy: CustomerFrontendPolicy
  • Auth: Logged-in WordPress user

Parameters ​

ParameterTypeLocationRequiredDescription
subscription_uuidstringpathYesThe subscription UUID (alphanumeric with dashes)

Response ​

json
{
  "message": "Success",
  "subscription": {
    "uuid": "abc123-def456",
    "status": "active",
    "overridden_status": null,
    "vendor_subscription_id": "sub_1234567890",
    "next_billing_date": "2025-02-15 00:00:00",
    "billing_info": {
      "interval": "monthly",
      "interval_count": 1,
      "amount": 2999,
      "currency": "USD"
    },
    "current_payment_method": "stripe",
    "payment_method": "stripe",
    "payment_info": { ... },
    "bill_times": 0,
    "bill_count": 6,
    "variation_id": 7,
    "product_id": 3,
    "config": { ... },
    "reactivate_url": "https://your-site.com/?fluent-cart=reactivate&hash=abc123",
    "title": "Pro Plan",
    "subtitle": "Monthly",
    "can_upgrade": true,
    "can_switch_payment_method": true,
    "switchable_payment_methods": ["stripe", "paypal"],
    "can_update_payment_method": true,
    "order": {
      "uuid": "order-uuid-here"
    },
    "billing_addresses": [ ... ],
    "recurring_amount": 2999,
    "can_early_pay": false,
    "remaining_installments": 0,
    "transactions": [
      {
        "id": 1,
        "order_id": 10,
        "vendor_charge_id": "ch_abc123",
        "amount": 2999,
        "status": "completed",
        "created_at": "2025-01-15 10:30:00",
        "order": { ... }
      }
    ]
  }
}

Response Fields ​

FieldTypeDescription
uuidstringUnique subscription identifier
statusstringCurrent status: active, trialing, canceled, paused, failing, expiring, expired, completed, past_due
overridden_statusstring/nullOverridden status if manually set
vendor_subscription_idstringRemote gateway subscription ID
next_billing_datestringNext billing date in GMT
billing_infoobjectBilling interval and amount details
current_payment_methodstringCurrent payment method slug
payment_methodstringOriginal payment method slug
payment_infoobjectPayment method details (card brand, last4, etc.)
bill_timesintegerTotal number of billing cycles (0 = unlimited)
bill_countintegerNumber of completed billing cycles
variation_idintegerProduct variation ID
product_idintegerProduct ID
configobjectSubscription configuration
reactivate_urlstringURL for reactivating a canceled subscription
titlestringProduct title
subtitlestringVariation title (if applicable)
can_upgradebooleanWhether the subscription is eligible for plan upgrade
can_switch_payment_methodbooleanWhether the payment method can be switched to a different gateway
switchable_payment_methodsarrayList of available payment method slugs to switch to
can_update_payment_methodbooleanWhether the payment method can be updated (e.g., new card) within the same gateway
order.uuidstringParent order UUID
billing_addressesarrayBilling addresses associated with the subscription
recurring_amountintegerRecurring payment amount in cents
can_early_paybooleanWhether early installment payment is available
remaining_installmentsintegerNumber of remaining installments (0 if unlimited)
transactionsarrayAll transactions related to this subscription and its renewal orders

Example ​

bash
curl -X GET "https://example.com/wp-json/fluent-cart/v2/customer-profile/subscriptions/abc123-def456" \
  -H "X-WP-Nonce: <nonce>"

Get Setup Intent Remaining Attempts ​

GET /fluent-cart/v2/customer-profile/subscriptions/{subscription_uuid}/setup-intent-attempts

Check how many Stripe SetupIntent attempts remain for the customer. This is used to enforce rate limiting on payment method update attempts.

  • Policy: CustomerFrontendPolicy
  • Auth: Logged-in WordPress user
  • Stripe Only: Only works when current_payment_method is stripe

Parameters ​

ParameterTypeLocationRequiredDescription
subscription_uuidstringpathYesThe subscription UUID (alphanumeric with dashes)

Conditions ​

  • Customer must own the subscription
  • Subscription's current_payment_method must be stripe
  • Subscription must have a vendor_customer_id

Response ​

json
{
  "remaining": 5
}

Error Responses ​

Payment method not supported (non-Stripe subscription):

json
{
  "message": "Payment method not supported"
}

Example ​

bash
curl -X GET "https://example.com/wp-json/fluent-cart/v2/customer-profile/subscriptions/abc123-def456/setup-intent-attempts" \
  -H "X-WP-Nonce: <nonce>"

Update Payment Method ​

POST /fluent-cart/v2/customer-profile/subscriptions/{subscription_uuid}/update-payment-method

Update the payment method (e.g., replace the card on file) for an existing subscription within the same payment gateway.

  • Policy: CustomerFrontendPolicy
  • Auth: Logged-in WordPress user

Parameters ​

ParameterTypeLocationRequiredDescription
subscription_uuidstringpathYesThe subscription UUID (alphanumeric with dashes)
dataobjectbodyYesPayment method data object
data.methodstringbodyYesPayment gateway slug (e.g., stripe, paypal)

Additional fields inside data depend on the specific payment gateway implementation (e.g., Stripe token, PayPal billing agreement ID).

Response ​

The response depends on the gateway's cardUpdate implementation. On failure:

json
{
  "message": "Could not update payment method"
}

Example ​

bash
curl -X POST "https://example.com/wp-json/fluent-cart/v2/customer-profile/subscriptions/abc123-def456/update-payment-method" \
  -H "X-WP-Nonce: <nonce>" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "method": "stripe",
      "payment_method_id": "pm_1234567890"
    }
  }'

Get or Create Plan ​

POST /fluent-cart/v2/customer-profile/subscriptions/{subscription_uuid}/get-or-create-plan

Get or create a subscription plan on the remote payment gateway. This is typically used during the payment method switch flow to ensure the target gateway has a matching plan configured.

  • Policy: CustomerFrontendPolicy
  • Auth: Logged-in WordPress user

Parameters ​

ParameterTypeLocationRequiredDescription
subscription_uuidstringpathYesThe subscription UUID (alphanumeric with dashes)
dataobjectbodyYesPlan data object
data.methodstringbodyYesTarget payment gateway slug (e.g., stripe, paypal)
data.reasonstringbodyNoReason for creating the plan

Response ​

The response depends on the gateway's getOrCreateNewPlan implementation. On failure:

json
{
  "message": "Could not get or create plan"
}

Example ​

bash
curl -X POST "https://example.com/wp-json/fluent-cart/v2/customer-profile/subscriptions/abc123-def456/get-or-create-plan" \
  -H "X-WP-Nonce: <nonce>" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "method": "stripe",
      "reason": "switching_payment_method"
    }
  }'

Switch Payment Method ​

POST /fluent-cart/v2/customer-profile/subscriptions/{subscription_uuid}/switch-payment-method

Switch a subscription's payment method from one gateway to another (e.g., from Stripe to PayPal). This initiates the switch process, which may require a confirmation step depending on the target gateway.

  • Policy: CustomerFrontendPolicy
  • Auth: Logged-in WordPress user

Parameters ​

ParameterTypeLocationRequiredDescription
subscription_uuidstringpathYesThe subscription UUID (alphanumeric with dashes)
dataobjectbodyYesPayment method switch data
data.newPaymentMethodstringbodyYesTarget payment gateway slug (e.g., paypal)
data.currentPaymentMethodstringbodyYesCurrent payment gateway slug (e.g., stripe)

Additional fields inside data depend on the specific payment gateway implementation.

Response ​

The response depends on the gateway's switchPaymentMethod implementation. May return a redirect URL or client secret for the new gateway. On failure:

json
{
  "message": "Could not switch payment method"
}

Example ​

bash
curl -X POST "https://example.com/wp-json/fluent-cart/v2/customer-profile/subscriptions/abc123-def456/switch-payment-method" \
  -H "X-WP-Nonce: <nonce>" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "newPaymentMethod": "paypal",
      "currentPaymentMethod": "stripe"
    }
  }'

Confirm Subscription Switch ​

POST /fluent-cart/v2/customer-profile/subscriptions/{subscription_uuid}/confirm-subscription-switch

Confirm a two-step payment method switch. After the initial switch-payment-method call creates a new subscription on the target gateway, this endpoint finalizes the switch by confirming the new subscription and deactivating the old one.

  • Policy: CustomerFrontendPolicy
  • Auth: Logged-in WordPress user

Parameters ​

ParameterTypeLocationRequiredDescription
subscription_uuidstringpathYesThe subscription UUID (alphanumeric with dashes)
dataobjectbodyYesConfirmation data
data.newVendorSubscriptionIdstringbodyYesThe new subscription ID from the target payment gateway
data.methodstringbodyYesThe target payment gateway slug (e.g., paypal)

Additional fields inside data depend on the specific payment gateway implementation.

Response ​

The response depends on the gateway's confirmSubscriptionSwitch implementation. On failure:

json
{
  "message": "Could not confirm subscription switch"
}

Example ​

bash
curl -X POST "https://example.com/wp-json/fluent-cart/v2/customer-profile/subscriptions/abc123-def456/confirm-subscription-switch" \
  -H "X-WP-Nonce: <nonce>" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "newVendorSubscriptionId": "I-ABC123DEF456",
      "method": "paypal"
    }
  }'

Cancel Auto-Renew ​

POST /fluent-cart/v2/customer-profile/subscriptions/{subscription_uuid}/cancel-auto-renew

Cancel auto-renewal for a subscription from the customer portal. The subscription is cancelled both locally and with the remote payment gateway. The cancellation reason is automatically set to cancelled_by_customer.

  • Policy: CustomerFrontendPolicy
  • Auth: Logged-in WordPress user

Parameters ​

ParameterTypeLocationRequiredDescription
subscription_uuidstringpathYesThe subscription UUID (alphanumeric with dashes)

No request body is required. The cancellation reason and note are set automatically.

Response ​

json
{
  "message": "Your subscription has been successfully cancelled"
}

Error Responses ​

Customer not found:

json
{
  "message": "Customer not found"
}

Subscription not found (or does not belong to the customer):

json
{
  "message": "Subscription not found"
}

Example ​

bash
curl -X POST "https://example.com/wp-json/fluent-cart/v2/customer-profile/subscriptions/abc123-def456/cancel-auto-renew" \
  -H "X-WP-Nonce: <nonce>"

Initiate Early Payment ​

POST /fluent-cart/v2/customer-profile/subscriptions/{subscription_uuid}/initiate-early-payment

Generate a checkout URL for paying remaining installments early on an installment-based subscription.

  • Policy: CustomerFrontendPolicy
  • Auth: Logged-in WordPress user

Parameters ​

ParameterTypeLocationRequiredDescription
subscription_uuidstringpathYesThe subscription UUID (alphanumeric with dashes)

No request body is required.

Conditions ​

The early payment feature must be enabled, and the subscription must meet the following criteria:

  • Pro license must be active
  • bill_times > 0 (finite installments)
  • bill_count < bill_times (remaining installments exist)
  • Status must be active or trialing

Response ​

json
{
  "message": "Early payment URL generated.",
  "checkout_url": "https://your-site.com/?fluent-cart=early-installment-payment&subscription_hash=abc123-def456"
}

Error Responses ​

Early payment not available:

json
{
  "message": "Early payment is not available for this subscription."
}

Customer not found:

json
{
  "message": "Customer not found"
}

Subscription not found:

json
{
  "message": "Subscription not found"
}

Example ​

bash
curl -X POST "https://example.com/wp-json/fluent-cart/v2/customer-profile/subscriptions/abc123-def456/initiate-early-payment" \
  -H "X-WP-Nonce: <nonce>"

Subscription Statuses ​

StatusConstantDescription
pendingSUBSCRIPTION_PENDINGSubscription created but not yet activated
intendedSUBSCRIPTION_INTENDEDPayment intent created, awaiting completion
trialingSUBSCRIPTION_TRIALINGIn trial period
activeSUBSCRIPTION_ACTIVEActive and billing normally
pausedSUBSCRIPTION_PAUSEDTemporarily paused
failingSUBSCRIPTION_FAILINGPayment attempts are failing
expiringSUBSCRIPTION_EXPIRINGApproaching expiration
expiredSUBSCRIPTION_EXPIREDSubscription has expired
canceledSUBSCRIPTION_CANCELEDCancelled by admin or customer
past_dueSUBSCRIPTION_PAST_DUEPayment is overdue
completedSUBSCRIPTION_COMPLETEDAll installments paid
authenticatedSUBSCRIPTION_AUTHENTICATEDAuthentication completed (SCA flow)
createdSUBSCRIPTION_CREATEDCreated on the remote gateway

Hooks and Filters ​

HookTypeDescription
fluent_cart/subscription/viewfilterModify subscription data before returning in admin detail view
fluent_cart/customer_portal/subscription_datafilterModify subscription data before returning in customer portal detail view
fluent_cart/subscriptions_list_filter_queryfilterModify the subscription list query before execution
fluent_cart/subscriptions_filter/{provider}/{property}actionCustom advanced filter handler for subscription list

FluentCart developer documentation

Copyright © 2025 FluentCart