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",
    "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 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
    }