subscription
Collection: subscriptions
A subscription is a recurring transaction. To create a subscription, you must first create the original transaction which will be run based on the item's subscription_frequency. Items on a transaction with the same subscription_frequency, subscription_startdate, and subscription_enddate will be grouped together to create a subscription. Multiple subscriptions can be created from the same original transaction.
If you create custom attributes for a subscription, they will automatically be included in the response as embedded resources without having to zoom in on them.
To modify the details of a subscription such as the items involved, the amount of the subscription, the discounts in use, etc, modify the cart details linked via the transaction_template link relationship. To modify when the subscription runs, modify the frequency, next transaction dates, end dates and such directly on the subscription.
If the subscription is integrated with a third party subscription system (such as PayPal Express), there may be limitations on what can be modified such as the next_transaction_date and frequency.
The sub_token_url link relationship will load up the subscription template into a full HTML cart for the store.
Required Scopes
store_full_access subscriptions_read subscriptions_write Actions
Properties (13)
start_date String · Required The original date this subscription began or will begin if set in the future.
Format: YYYY-MM-DD
next_transaction_date String The date for when this subscription will run again.
Must be in the future.
Format: YYYY-MM-DD
end_date String (nullable) If set, the date this subscription will end. The subscription will not run on this day.
Must be in the future.
Format: YYYY-MM-DD
frequency String This determines how often this subscription will be processed. The format is a number followed by a date type such as d (day), w (week), m (month), or y (year). You can also use .5m for twice a month.
The format must be valid, such as 1m, 3w, 45d, etc.
error_message String · max 500 If the last run of this subscription encountered an error, that error message will be saved here. It will also note if a past due payment was made.
past_due_amount Number If a subscription payment is missed, this amount will be increased by that payment. The next time the subscription runs, it will be charged automatically, depending on your store's subscription settings.
first_failed_transaction_date String (nullable) · Read-only If this subscription failed to process due to an error such as expired payment card, this field will show the first date the subscription failed to process. If it processes successfully at the next attempt, this field will be cleared.
is_active Boolean Determines whether or not this transaction is active or not. If you are using the subscription datafeed, it is best to set the end_date to tomorrow instead of setting this to inactive.
third_party_id String · Read-only If this subscription is using a third party subscription system such as PayPal Express, their identifier will be set here.
payment_type String (nullable) · Read-only The type of payment method used for this subscription.
plasticpaypalachamazonpurchase_order cancellation_source String · Read-only If this subscription has been cancelled, this will show what event caused it to cancel.
""mit_apimit_adminmit_dunningmit_checkoutcit_checkout date_created String (nullable) · Read-only The date this resource was created.
date_modified String (nullable) · Read-only The date this resource was last modified.
Link Relations (18)
self This Subscription Only present when the original transaction id is set.
fx:sub_token_url GET This Sub Token Only present when a sub_token_url is available for this subscription.
fx:charge_past_due POST Charge Past Due Only present when past_due_amount is greater than 0.
fx:sub_modification_url GET URL to modify this subscription Only present when a sub_token_url is available and the store has a subscription modification URL configured.
Zoomable Resources
Embed related resources using ?zoom=<resource>.
Filter with ?resource:property=value.
subscription on cart·fx:subscription on cart·fx:subscription on error_entry·fx:subscription on item·fx:subscription on subscription_event·fx:subscription on subscription_upcoming_item·fx:subscription on transaction Example Representation
{
"_links": {
"curies": [
{
"name": "fx",
"href": "https://api.foxycart.com/rels/{rel}",
"templated": true
}
],
"self": {
"href": "https://api.foxycart.com/subscriptions/123",
"title": "This Subscription"
},
"fx:attributes": {
"href": "https://api.foxycart.com/subscriptions/123/attributes",
"title": "Attributes for This Subscription"
},
"fx:store": {
"href": "https://api.foxycart.com/stores/456",
"title": "This Store"
},
"fx:customer": {
"href": "https://api.foxycart.com/customers/789",
"title": "This Customer"
},
"fx:original_transaction": {
"href": "https://api.foxycart.com/transactions/999",
"title": "Original Transaction"
},
"fx:last_transaction": {
"href": "https://api.foxycart.com/transactions/999",
"title": "Last Transaction"
},
"fx:transactions": {
"href": "https://api.foxycart.com/stores/456/transactions?subscription_id=123",
"title": "Transactions for this Subscription"
},
"fx:subscription_events": {
"href": "https://api.foxycart.com/subscriptions/123/subscription_events",
"title": "Events for this Subscription"
},
"fx:subscription_upcoming_items": {
"href": "https://api.foxycart.com/subscriptions/123/subscription_upcoming_items",
"title": "Upcoming Items for this Subscription"
},
"fx:transaction_template": {
"href": "https://api.foxycart.com/carts/999",
"title": "Transaction Template"
},
"fx:sub_token_url": {
"href": "https://mystore.foxycart.com/cart?sub_token=e38b9886405ff668f6d11c129e7fde1f8281f3e00dd34c819e0c9370ccb2bd56",
"title": "This Sub Token"
},
"fx:send_webhooks": {
"href": "https://api.foxycart.com/subscriptions/123/send_webhooks",
"title": "Refeed webhooks v2 for this Subscription"
},
"fx:charge_past_due": {
"href": "https://api.foxycart.com/subscriptions/123/charge_past_due",
"title": "Charge Past Due"
},
"fx:sub_modification_url": {
"href": "https://mystore.foxycart.com/cart?sub_token=e38b9886405ff668f6d11c129e7fde1f8281f3e00dd34c819e0c9370ccb2bd56&redirect=https://www.mydomain.com/subscription_modification.html",
"title": "URL to modify this subscription"
}
},
"start_date": "2010-09-15T00:00:00-0700",
"next_transaction_date": "2014-05-01T00:00:00-0700",
"end_date": null,
"frequency": "1m",
"error_message": "",
"past_due_amount": 0,
"first_failed_transaction_date": null,
"is_active": false,
"third_party_id": "",
"payment_type": null,
"cancellation_source": "",
"date_created": null,
"date_modified": "2013-08-19T10:58:39-0700"
}