Understanding the sub_token

Where to find the sub_token

The sub_token is available in three places:

• Foxy admin: Go to the Foxy admin, go to Subscriptions, click on the desired subscription, and copy the Sub Token URL

• Subscription XML Datafeed: The token is included in the subscription datafeed payload

• API: Available via the Foxy API on the subscription resource

How the sub_token works

When a sub_token is passed to the cart, it empties any existing cart contents and loads the subscription as a template — showing the subscription's current products, frequency, and dates. The customer (or admin using UOE) can then modify the contents and proceed through checkout to update the subscription.

Visual indication is shown on both the cart and checkout pages when a sub_token is active, so the customer knows they are modifying an existing subscription rather than placing a new order.

Any new subscription products added to the cart via a sub_token will automatically have their sub_startdate set to the next scheduled date for that subscription, preventing the customer from being charged again for the current period.

Common uses

Updating billing information or paying past due amounts

Combine the sub_token with cart=checkout to send the customer directly to checkout, bypassing the cart. This is how Foxy's default receipt email links work. The customer's email address is pre-filled, and they can update their payment information or pay any past due amount.

https://YOURSTORE.foxycart.com/cart?sub_token=TOKEN&cart=checkout

Modifying subscription contents

Pair the sub_token with a redirect parameter to send the customer to a page on your website where they can add or change products. Once they proceed through checkout, the subscription is updated.

https://YOURSTORE.foxycart.com/cart?sub_token=TOKEN&redirect=https://YOURSTORE.com/products

Cancelling a subscription

Combine the sub_token with sub_cancel=true or sub_cancel=next_transaction_date to load the subscription ready for cancellation. See Cancel a subscription for details.

Replacing a subscription entirely

Combine the sub_token with sub_modify=replace to completely replace the subscription's products. See Upgrade or downgrade a subscription for details.

Collecting payment immediately

Combine the sub_token with sub_restart=true or sub_restart=auto to charge the customer immediately rather than waiting for the next scheduled billing date. sub_restart=auto only collects payment if the subscription has a past due amount greater than zero.

Automating past due collection via API

To automate past due collection programmatically, pass the sub_token to the process_past_due_subscription endpoint at your store's domain:

https://YOURSTORE.foxycart.com/process_past_due_subscription?sub_token=TOKEN

The response is JSON with the following fields:

{
  "result": "",         // "OK" if successful, "ERROR" if unsuccessful
  "transaction_id": "", // integer
  "processor_response": "",         // string
  "processor_response_details": "", // string
  "receipt_url": ""     // URL
}

For full details see the Foxy API documentation.

Notes

• The sub_token is unique per subscription, not per customer. A customer with multiple subscriptions will have a different token for each.

• If you are using PayPal Express (non-Reference Transactions), subscription modification via sub_token is not supported. Foxy strongly recommends using the Reference Transaction option for PayPal Express Checkout.