API: subscriptions

Retrieve and manage your subscriptions through these endpoints. You can list them and get specific subscription details. You can also cancel, pause and resume a subscription.

## GET /subscriptions

This method returns a list of subscriptions.

Resource URL

GET https://app.snipcart.com/api/subscriptions

Headers

Name Value Required? Description
Accept application/json Yes Our API only accepts application/json content type, so you must always specify Accept: application/json header in each request you make.

Parameters

Name Required? Type Description
limit No int The maximum number of items returned by the request. Default value is 20.
offset No int The number of items that will be skipped. Default value is 0.
from No datetime Filter subscriptions to return those that start on specified date.
to No datetime Filter subscriptions to return those that end on specified date.
userDefinedPlanName No string Filter subscriptions to return those matching the specified plan name.
status No enum Filter subscriptions to return those having the specified status. Possible values are: active, paused or canceled.
userDefinedCustomerNameOrEmail No string Filter subscriptions to return those belonging to the specified customer name or email.

Example request 

curl -H "Accept: application/json" \
  https://app.snipcart.com/api/subscriptions?limit=50&offset=0&status=active |
  -u {API_KEY}:

Example response 

{
    "userDefinedPlanName": null,
    "userDefinedCustomerNameOrEmail": null,
    "status": null,
    "from": null,
    "to": null,
    "totalItems": 58,
    "offset": 0,
    "limit": 20,
    "items": [
        {
            "user": {
                "id": "53d0c151-4005-4e72-ba02-8c12d7f41569",
                "email": "email@email.com"
            },
            "initialOrderToken": "3ce678ba-9c34-431e-8f92-b3e74b51bd59",
            "firstInvoiceReceivedOn": null,
            "schedule": {
                "interval": "Month",
                "intervalCount": 0,
                "trialPeriodInDays": null,
                "startsOn": "2017-10-24T00:00:00Z"
            },
            "itemId": "198520a0-d12d-44d6-b57f-6617299c5405",
            "id": "84983d03-775a-4e79-804a-af807f509700",
            "name": "Monthly subscription",
            "creationDate": "2017-10-13T14:26:56.11Z",
            "modificationDate": "2017-10-13T14:26:56.11Z",
            "cancelledOn": null,
            "amount": 20,
            "quantity": 1,
            "userDefinedId": "PLAN_1",
            "totalSpent": 20,
            "status": "Paid",
            "gatewayId": "sub_BZdOKYWblHCy0Z",
            "metadata": null,
            "cartId": null,
            "recurringShipping": true
        },
        {
            "user": {
                "id": "53d0c151-4005-4e72-ba02-8c12d7f41569",
                "email": "email@email.com"
            },
            "initialOrderToken": "ccd46b9b-e595-46ce-bc80-d11565e4a455",
            "firstInvoiceReceivedOn": null,
            "schedule": {
                "interval": "Month",
                "intervalCount": 0,
                "trialPeriodInDays": null,
                "startsOn": "2017-10-24T00:00:00Z"
            },
            "itemId": "e24ce7b1-632d-4c8c-898a-5a0a5cfa1a8c",
            "id": "b55f8a6d-6291-45b9-9ba2-4e134d36317f",
            "name": "Monthly subscription",
            "creationDate": "2017-10-12T21:57:14.637Z",
            "modificationDate": "2017-10-12T21:57:14.637Z",
            "cancelledOn": null,
            "amount": 20,
            "quantity": 1,
            "userDefinedId": "PLAN_1",
            "totalSpent": 20,
            "status": "Paid",
            "gatewayId": "sub_BZNQIG8RlhP3Io",
            "metadata": null,
            "cartId": null,
            "recurringShipping": true
        }
    ]
}
## GET /subscriptions/{id}

This method returns a subscription by its unique identifier.

Resource URL

GET https://app.snipcart.com/api/subscriptions/{id}

Headers

Name Value Required? Description
Accept application/json Yes Our API only accepts application/json content type, so you must always specify Accept: application/json header in each request you make.

Parameters

Name Required? Type Description
id No uniqueidentifier The unique ID of the subscription.

Example request 

curl -H "Accept: application/json" \
  https://app.snipcart.com/api/subscriptions/{id} \
  -u {API_KEY}:

Example response 

{
    "user": {
        "id": "53d0c151-4005-4e72-ba02-8c12d7f41569",
        "email": "email@email.com"
    },
    "initialOrderToken": "3ce678ba-9c34-431e-8f92-b3e74b51bd59",
    "firstInvoiceReceivedOn": null,
    "schedule": {
        "interval": "Month",
        "intervalCount": 0,
        "trialPeriodInDays": null,
        "startsOn": "2017-10-24T00:00:00Z"
    },
    "itemId": "198520a0-d12d-44d6-b57f-6617299c5405",
    "id": "84983d03-775a-4e79-804a-af807f509700",
    "name": "Monthly subscription",
    "creationDate": "2017-10-13T14:26:56.11Z",
    "modificationDate": "2017-10-13T14:26:56.11Z",
    "nextBillingDate": "2017-10-23T14:26:56.11Z",
    "cancelledOn": null,
    "amount": 20,
    "quantity": 1,
    "userDefinedId": "PLAN_1",
    "totalSpent": 20,
    "status": "Paid",
    "gatewayId": "sub_BZdOKYWblHCy0Z",
    "metadata": null,
    "cartId": null,
    "recurringShipping": true
    }
## GET /subscriptions/{id}/invoices

This method gets you the list of invoices associated with a subscription.

Resource URL

GET https://app.snipcart.com/api/subscriptions/{id}/invoices

Headers

Name Value Required? Description
Accept application/json Yes Our API only accepts application/json content type, so you must always specify Accept: application/json header in each request you make.

Parameters

Name Required? Type Description
id No uniqueidentifier The unique ID of the subscription.

Example request 

curl -H "Accept: application/json" \
  https://app.snipcart.com/api/subscriptions/{id}/invoices \
  -u {API_KEY}:

Example response 

[
    {
        "id": "3ce678ba-9c34-431e-8f92-b3e74b51bd59",
        "orderToken": "3ce678ba-9c34-431e-8f92-b3e74b51bd59",
        "creationDate": "2017-10-13T14:26:52Z",
        "modificationDate": "2017-10-13T14:26:56Z",
        "subscriptionId": "84983d03-775a-4e79-804a-af807f509700",
        "amount": 31.5,
        "paid": true,
        "taxes": [],
        "number": "SNIP-1061",
        "total": 31.5
    }
]
## DELETE /subscriptions/{id}

This method can be used to cancel a subscription.

Resource URL

DELETE https://app.snipcart.com/api/subscriptions/{id}

Headers

Name Value Required? Description
Accept application/json Yes Our API only accepts application/json content type, so you must always specify Accept: application/json header in each request you make.

Parameters

Name Required? Type Description
id No uniqueidentifier The unique ID of the subscription.

Example request 

curl https://app.snipcart.com/api/subscriptions/{id} \
    -X DELETE \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -u {API_KEY} \

Example response 

{
    "user": {
        "id": "53d0c151-4005-4e72-ba02-8c12d7f41569",
        "email": "email@email.com"
    },
    "initialOrderToken": "3ce678ba-9c34-431e-8f92-b3e74b51bd59",
    "firstInvoiceReceivedOn": null,
    "schedule": {
        "interval": "Month",
        "intervalCount": 0,
        "trialPeriodInDays": null,
        "startsOn": "2017-10-24T00:00:00Z"
    },
    "itemId": "198520a0-d12d-44d6-b57f-6617299c5405",
    "id": "84983d03-775a-4e79-804a-af807f509700",
    "name": "Monthly subscription",
    "creationDate": "2017-10-13T14:26:56.11Z",
    "modificationDate": "2017-10-13T14:26:56.11Z",
    "cancelledOn": "2017-10-13T14:26:56.11Z",
    "amount": 20,
    "quantity": 1,
    "userDefinedId": "PLAN_1",
    "totalSpent": 20,
    "status": "Canceled",
    "gatewayId": "sub_BZdOKYWblHCy0Z",
    "metadata": null,
    "cartId": null,
    "recurringShipping": true
    }
## POST /subscriptions/{id}/pause

This method can be used to pause an active subscription. Under the hood, a 100% discount will be applied to the Stripe subscription.

Headers

Name Value Required? Description
Accept application/json Yes Our API only accepts application/json content type, so you must always specify Accept: application/json header in each request you make.

Parameters

Name Required? Type Description
id No uniqueidentifier The unique ID of the subscription.

Example request 

curl https://app.snipcart.com/api/subscriptions/{id}/pause \
    -X POST \
    -H "Accept: application/json"
    -u {API_KEY}

Example response 

{
    "user": {
        "id": "53d0c151-4005-4e72-ba02-8c12d7f41569",
        "email": "email@email.com"
    },
    "initialOrderToken": "3ce678ba-9c34-431e-8f92-b3e74b51bd59",
    "firstInvoiceReceivedOn": null,
    "schedule": {
        "interval": "Month",
        "intervalCount": 0,
        "trialPeriodInDays": null,
        "startsOn": "2017-10-24T00:00:00Z"
    },
    "itemId": "198520a0-d12d-44d6-b57f-6617299c5405",
    "id": "84983d03-775a-4e79-804a-af807f509700",
    "name": "Monthly subscription",
    "creationDate": "2017-10-13T14:26:56.11Z",
    "modificationDate": "2017-10-13T14:26:56.11Z",
    "cancelledOn": null,
    "amount": 20,
    "quantity": 1,
    "userDefinedId": "PLAN_1",
    "totalSpent": 20,
    "status": "Paused",
    "gatewayId": "sub_BZdOKYWblHCy0Z",
    "metadata": null,
    "cartId": null,
    "recurringShipping": true
    }
## POST /subscriptions/{id}/resume

This method can be used to resume a paused subscription. Under the hood, the 100% discount previously created on Stripe's subscription will be deleted.

Headers

Name Value Required? Description
Accept application/json Yes Our API only accepts application/json content type, so you must always specify Accept: application/json header in each request you make.

Parameters

Name Required? Type Description
id No uniqueidentifier The unique ID of the subscription.

Example request 

curl https://app.snipcart.com/api/subscriptions/{id}/resume \
    -X POST \
    -H "Accept: application/json"
    -u {API_KEY}

Example response 

{
    "user": {
        "id": "53d0c151-4005-4e72-ba02-8c12d7f41569",
        "email": "email@email.com"
    },
    "initialOrderToken": "3ce678ba-9c34-431e-8f92-b3e74b51bd59",
    "firstInvoiceReceivedOn": null,
    "schedule": {
        "interval": "Month",
        "intervalCount": 0,
        "trialPeriodInDays": null,
        "startsOn": "2017-10-24T00:00:00Z"
    },
    "itemId": "198520a0-d12d-44d6-b57f-6617299c5405",
    "id": "84983d03-775a-4e79-804a-af807f509700",
    "name": "Monthly subscription",
    "creationDate": "2017-10-13T14:26:56.11Z",
    "modificationDate": "2017-10-13T14:26:56.11Z",
    "cancelledOn": null,
    "amount": 20,
    "quantity": 1,
    "userDefinedId": "PLAN_1",
    "totalSpent": 20,
    "status": "Active",
    "gatewayId": "sub_BZdOKYWblHCy0Z",
    "metadata": null,
    "cartId": null,
    "recurringShipping": true
    }
## PUT /subscriptions/{id}

This method can be used to update an existing subscription. If you change the interval or the interval count, the customer will be charged right away for the new subscription amount. If you only change the amount, the new price will be applied on planned, upcoming invoices only.

Headers

Name Value Required? Description
Accept application/json Yes Our API only accepts application/json content type, so you must always specify Accept: application/json header in each request you make.

Parameters

Name Required? Type Description
id Yes (URL parameter) uniqueidentifier The unique ID of the subscription.
amount Yes decimal The price of the recurring subsription.
nextBillingDate No datetime The date of the next payment, under the hood a trial period will be set on the subscription until the date specified in this parameter.
quantity No integer The quantity of products in the subscription. For example, 2 monthly subscriptions of 10$ will result into a monthly order of 20$.
schedule Yes object The schedule of the recurring subscription. More details on object parameters below.
metadata no object Custom information stored along with the subscription.

Schedule

Name Required? Type Description
interval yes enum The interval on which the subscription renews itself, possible values: Year, Month, Week, Day.
intervalCount No integer The interval count, for example if interval is Month and intervalCount is 2 then the subscription will renew itself every 2 months.

Example request 

curl https://app.snipcart.com/api/subscriptions/c7af6278-1c06-411d-b009-22a839efda75 -X PUT \
-H "Content-Type: application/json" \
-H "Accept: application/json" -u {YOUR_API_KEY}: \
-d "{'amount': 100, 'quantity': 1, 'schedule': { 'interval': 'Month', 'intervalCount': 2}}"

Example response 

{
    "user": {
        "id": "53d0c151-4005-4e72-ba02-8c12d7f41569",
        "email": "email@email.com"
    },
    "initialOrderToken": "3ce678ba-9c34-431e-8f92-b3e74b51bd59",
    "firstInvoiceReceivedOn": null,
    "schedule": {
        "interval": "Month",
        "intervalCount": 2,
        "trialPeriodInDays": null,
        "startsOn": "2019-03-06T00:00:00Z"
    },
    "itemId": "198520a0-d12d-44d6-b57f-6617299c5405",
    "id": "c7af6278-1c06-411d-b009-22a839efda75",
    "name": "Monthly subscription",
    "creationDate": "2019-03-06T14:26:56.11Z",
    "modificationDate": "2019-03-06T14:26:56.11Z",
    "cancelledOn": null,
    "amount": 20,
    "quantity": 1,
    "userDefinedId": "PLAN_1",
    "totalSpent": 20,
    "status": "Paid",
    "gatewayId": "sub_BZdOKYWblHCy0Z",
    "metadata": null,
    "cartId": null,
    "recurringShipping": true
    }

Was this article helpful?