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"
        },
        "fx:charge_past_due": {
            "href": "https://api.foxycart.com/subscriptions/413/charge_past_due",
            "title": "Charge Past Due"
        }
    },
    "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