subscription
Description
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 limitiations 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.
Actions
- GET
- View a subscription
- PATCH
- Update a subscription (send only the properties you want to modify)
- PUT
- Replace a subscription (send the entire representation)
- HEAD
- Get just the header response
- OPTIONS
- Get a response explaining which HTTP methods are supported
Properties
Property | Description | Type | Constraints |
---|---|---|---|
start_date | The original date this subscription began or will begin if set in the future. | Date | Required. YYYY-MM-DD Format. |
next_transaction_date | The date for when this subscription will run again. | Date | Must be in the future. YYYY-MM-DD Format. |
end_date | If set, the date this subscription will end. The subscription will not run on this day. | Date | Must be in the future. YYYY-MM-DD Format. |
frequency | 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. | String | The format must be valid, such as 1m, 3w, 45d, etc |
error_message | 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. | String | 500 characters or less |
past_due_amount | 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. | Decimal | Numeric. |
first_failed_transaction_date | 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. | Date | |
is_active | 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 settings this to inactive. | Boolean | True or false. 1 or 0. |
third_party_id | If this subscription is using a third party subscription system such as PayPal Express, their identifier will be set here. | String | Read only |
cancellation_source | If this subscription has been cancelled, this will show what event caused it to cancel | String | Read only. mit_api, mit_admin, mit_dunning, mit_checkout, cit_checkout |
date_created | The date this resource was created. | Date | Read only |
date_modified | The date this resource was last modified. | Date | Read only |
Example Representation
{ "_links": { "curies": [ { "name": "fx", "href": "https://api.foxycart.com/rels/{rel}", "templated": true } ], "self": { "href": "https://api.foxycart.com/subscriptions/413", "title": "This Subscription" }, "fx:attributes": { "href": "https://api.foxycart.com/subscriptions/413/attributes", "title": "Attributes for This Subscription" }, "fx:store": { "href": "https://api.foxycart.com/stores/66", "title": "This Store" }, "fx:customer": { "href": "https://api.foxycart.com/customers/115", "title": "This Customer" }, "fx:send_webhooks": { "href": "https://api.foxycart.com/subscriptions/413/send_webhooks", "title": "Refeed webhooks v2 for this Subscription" }, "fx:last_transaction": { "href": "https://api.foxycart.com/transactions/2026722", "title": "Last Transaction" }, "fx:transactions": { "href": "https://api.foxycart.com/stores/66/transactions?subscription_id=413", "title": "Transactions for this Subscription" } "fx:transaction_template": { "href": "https://api.foxycart.com/carts/2028277", "title": "Transaction Template" }, "fx:sub_token_url": { "href": "https://example.foxycart.com/cart?sub_token=a2be406ad4672e0b6a1c4ca7ff46af4a", "title": "This Sub Token" } }, "next_transaction_date": "2014-05-01T00:00:00-0700", "start_date": "2010-09-15T00: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": "", "date_created": null, "date_modified": "2013-08-19T10:58:39-0700" }
<?xml version="1.0" encoding="UTF-8"?> <resource href="https://api.foxycart.com/subscriptions/413" rel="https://api.foxycart.com/rels/subscription"> <link rel="self" href="https://api.foxycart.com/subscriptions/413" title="This Subscription"/> <link rel="https://api.foxycart.com/rels/attributes" href="https://api.foxycart.com/subscriptions/413/attributes" title="Attributes for This Subscription"/> <link rel="https://api.foxycart.com/rels/store" href="https://api.foxycart.com/stores/66" title="This Store"/> <link rel="https://api.foxycart.com/rels/customer" href="https://api.foxycart.com/customers/115" title="This Customer"/> <link rel="https://api.foxycart.com/rels/last_transaction" href="https://api.foxycart.com/subscriptions/413/send_webhooks" title="Refeed webhooks v2 for this Subscription"/> <link rel="https://api.foxycart.com/rels/last_transaction" href="https://api.foxycart.com/transactions/2026722" title="Last Transaction"/> <link rel="https://api.foxycart.com/rels/transactions" href="https://api.foxycart.com/stores/66/transactions?subscription_id=413" title="Transactions for this Subscription"/> <link rel="https://api.foxycart.com/rels/transaction_template" href="https://api.foxycart.com/carts/2028277" title="Transaction Template"/> <link rel="https://api.foxycart.com/rels/sub_token_url" href="https://example.foxycart.com/cart?sub_token=a2be406ad4672e0b6a1c4ca7ff46af4a" title="This Sub Token"/> <next_transaction_date>2014-05-01T00:00:00-0700</next_transaction_date> <start_date>2010-09-15T00:00:00-0700</start_date> <end_date></end_date> <frequency>1m</frequency> <error_message></error_message> <past_due_amount>0</past_due_amount> <first_failed_transaction_date></first_failed_transaction_date> <is_active>false</is_active> <third_party_id></third_party_id> <date_created></date_created> <date_modified>2013-08-19T10:58:39-0700</date_modified> </resource>
{ "class": [ "subscription" ], "properties": { "next_transaction_date": "2014-05-01T00:00:00-0700", "start_date": "2010-09-15T00: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": "", "date_created": null, "date_modified": "2013-08-19T10:58:39-0700" }, "links": [ { "rel": [ "self" ], "href": "https://api.foxycart.com/subscriptions/413" }, { "rel": [ "https://api.foxycart.com/rels/attributes" ], "href": "https://api.foxycart.com/subscriptions/413/attributes" }, { "rel": [ "https://api.foxycart.com/rels/store" ], "href": "https://api.foxycart.com/stores/66" }, { "rel": [ "https://api.foxycart.com/rels/customer" ], "href": "https://api.foxycart.com/customers/115" }, { "rel": [ "https://api.foxycart.com/rels/last_transaction" ], "href": "https://api.foxycart.com/stores/66/transactions?subscription_id=413" }, { "rel": [ "https://api.foxycart.com/rels/send_webhooks" ], "href": "https://api.foxycart.com/subscriptions/413/send_webhooks" }, { "rel": [ "https://api.foxycart.com/rels/transactions" ], "href": "https://api.foxycart.com/transactions/2026722" }, { "rel": [ "https://api.foxycart.com/rels/transaction_template" ], "href": "https://api.foxycart.com/carts/2028277" }, { "rel": [ "https://api.foxycart.com/rels/sub_token_url" ], "href": "https://example.foxycart.com/cart?sub_token=a2be406ad4672e0b6a1c4ca7ff46af4a" } ] }
Zoomable Resources
The following related resources can be embedded within this resource by including a ?zoom=<child_resource>
parameter. You can also filter by child resources by ?child_resource:property=<property_value>
attributes
customer
original_transaction
last_transaction
transaction_template
transactions