API: subscriptions

The Subscriptions API lets you count, list, inspect, and cancel a store's subscriptions. It is version-agnostic: a single set of endpoints covers both v1 (legacy) and v3 subscriptions, selected per request with the version query parameter.

Requests are authenticated with your secret API key, sent as the HTTP Basic username with an empty password. With curl: -u {API_KEY}:. See Authentication for details.

Subscription versions

Most endpoints accept a version query parameter that tells the API which subscription engine to target. The featureVersion field returned on subscription objects reports the same value.

Value Description
V1 Legacy subscriptions (the v1/v2 subscription engine). Their id is a GUID. Default when version is omitted.
V3 Current subscriptions. Their id is the initial order token.

GET /subscriptions/count

Return the number of v3 subscriptions for the authenticated account that are in one of the given states, scoped to a mode. (This counter only considers v3 subscriptions.)

Resource URL

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

Query Parameters

Name Required Type Description
states Yes string[] One or more subscription states to count. Repeat the parameter for multiple values. Values: Active, Paused, Finished, Stopped, CancellationRequested.
mode No string Environment to count in. Values: Live, Test. Default: Live.

Example request 

curl -H "Accept: application/json" \
  "https://app.snipcart.com/api/subscriptions/count?states=Active&states=Paused&mode=Live" \
  -u {API_KEY}:

Example response 

12

GET /dashboard/subscriptions

Return a paginated list of the account's subscriptions (v1 + v3) for the current mode, newest first. By default only non-cancelled subscriptions are returned; pass status to change that.

Resource URL

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

Query Parameters

Name Required Type Description
offset No int Number of results to skip. Default: 0.
limit No int Number of results to fetch. Default: 20.
status No string Filter by status. Values: all, active, paused, canceled. When omitted, only non-cancelled subscriptions are returned; an unrecognized value falls back to all.
from No datetime Return subscriptions created on or after this date.
to No datetime Return subscriptions created on or before this date.
customerId No string Return only subscriptions belonging to this customer.
userDefinedPlanName No string Partial match on the plan name.
userDefinedCustomerNameOrEmail No string Partial match on the subscriber's email, first name, or name.
lastAttemptedInvoiceState No string Filter by the last invoice's state. Values: Unpaid, Declined, Paid, Void.

Response

A paginated result. items holds subscription summaries; the response also echoes the applied filters and adds totalDeclinedCount (the account's total number of subscriptions whose last invoice was declined). A Link header with rel="next" is included for pagination.

Each item:

Field Type Description
id string Subscription id (GUID for v1, order token for v3).
planName string Plan name.
creationDate datetime When the subscription was created.
subscriber string Subscriber email.
interval string Billing interval: daily, weekly, monthly, yearly.
intervalCount int? Number of intervals between charges.
price decimal Recurring amount.
totalSpent decimal Total amount billed so far.
nextBillingDate datetime? Next scheduled billing date.
lastAttemptedInvoiceState string? Unpaid, Paid, Declined, Void, or Pending.
featureVersion string V1 or V3.

Example request 

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

Example response 

{
  "totalItems": 2,
  "offset": 0,
  "limit": 20,
  "sort": [],
  "totalDeclinedCount": 1,
  "status": "active",
  "items": [
    {
      "id": "c7af6278-1c06-411d-b009-22a839efda75",
      "planName": "Monthly coffee",
      "creationDate": "2026-01-15T09:24:00Z",
      "subscriber": "geeks@snipcart.com",
      "interval": "monthly",
      "intervalCount": 1,
      "price": 49.00,
      "totalSpent": 245.00,
      "nextBillingDate": "2026-02-15T09:24:00Z",
      "lastAttemptedInvoiceState": "Paid",
      "featureVersion": "V3"
    }
  ]
}

GET /dashboard/subscriptions/{id}

Retrieve a single subscription's details.

Resource URL

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

Path Parameters

Name Required Type Description
id Yes string GUID for a v1 subscription, order token for a v3 one.

Query Parameters

Name Required Type Description
version No string V1 (default) or V3. See Subscription versions.

Responses

Status Description
200 OK The subscription details.
400 Bad Request version=V1 but id is not a valid GUID.
404 Not Found No such subscription, or it does not belong to the account.
409 Conflict The Subscriptions feature is not enabled for this store.

Subscription object

Field Type Description
id string Subscription id.
name string Subscription name.
cancelledOn datetime? Cancellation date. Omitted when the subscription is not cancelled.
state string Current state.
user object The subscriber: id, email, billingAddressName.
schedule object Billing schedule: interval, intervalCount.
nextBillingDate string Next scheduled billing date.
gatewayId string Payment gateway identifier for the subscription.
paymentStatus string Status of the latest payment.
upcomingPayments array Upcoming charges, each with subscriptionId, name, date.
featureVersion string V1 or V3.
amount decimal Recurring amount.
quantity int Quantity billed each cycle.

Example request 

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

Example response 

{
  "id": "c7af6278-1c06-411d-b009-22a839efda75",
  "name": "Monthly coffee",
  "state": "Active",
  "user": {
    "id": "a1b2c3d4-e5f6-47a8-9abc-def012345678",
    "email": "geeks@snipcart.com",
    "billingAddressName": "Marie Dubois"
  },
  "schedule": {
    "interval": "monthly",
    "intervalCount": 1
  },
  "nextBillingDate": "2026-02-15T09:24:00Z",
  "gatewayId": "sub_1Nabc...",
  "paymentStatus": "Paid",
  "upcomingPayments": [
    {
      "subscriptionId": "c7af6278-1c06-411d-b009-22a839efda75",
      "name": "Monthly coffee",
      "date": "2026-02-15T09:24:00Z"
    }
  ],
  "featureVersion": "V3",
  "amount": 49.00,
  "quantity": 1
}

DELETE /dashboard/subscriptions/{id}

Cancel a subscription.

  • For v1 subscriptions, this cancels the subscription with the payment gateway.
  • For v3 subscriptions, this requests cancellation: the subscription moves to CancellationRequested and is cancelled at its next billing date. The call is idempotent — deleting a v3 subscription that has already requested cancellation returns its current state without re-requesting.

Resource URL

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

Path Parameters

Name Required Type Description
id Yes string GUID for a v1 subscription, order token for a v3 one.

Query Parameters

Name Required Type Description
version No string V1 (default) or V3.

Responses

Status Description
200 OK The updated subscription details.
400 Bad Request version=V1 but id is not a valid GUID.
404 Not Found No such subscription, or it does not belong to the account.
409 Conflict The Subscriptions feature is not enabled for this store.

Example request 

curl -X DELETE "https://app.snipcart.com/api/dashboard/subscriptions/{id}?version=V3" \
  -H "Accept: application/json" \
  -u {API_KEY}:

Example response 

{
  "id": "c7af6278-1c06-411d-b009-22a839efda75",
  "name": "Monthly coffee",
  "state": "CancellationRequested",
  "nextBillingDate": "2026-02-15T09:24:00Z",
  "featureVersion": "V3",
  "amount": 49.00,
  "quantity": 1
}

GET /dashboard/subscriptions/{id}/invoices

Return the invoices (recurring orders) issued for a subscription.

Resource URL

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

Path Parameters

Name Required Type Description
id Yes string GUID for a v1 subscription, order token for a v3 one.

Query Parameters

Name Required Type Description
version No string V1 (default) or V3.

For v3 subscriptions the list always contains at least the initial invoice; an empty result means the subscription was not found (404 Not Found).

Response

An array of invoice objects:

Field Type Description
id string Invoice id (the order token).
orderToken string Token of the order backing the invoice.
creationDate datetime When the invoice (order) was completed.
modificationDate datetime Last modification date of the order.
subscriptionId string Id of the parent subscription.
amount decimal Invoice amount.
total decimal Same as amount.
paid bool true when the order's payment status is paid.
number string Invoice number.

Example request 

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

Example response 

[
  {
    "id": "c7af6278-1c06-411d-b009-22a839efda75",
    "orderToken": "c7af6278-1c06-411d-b009-22a839efda75",
    "creationDate": "2026-01-15T09:24:00Z",
    "modificationDate": "2026-01-15T09:24:05Z",
    "subscriptionId": "c7af6278-1c06-411d-b009-22a839efda75",
    "amount": 49.00,
    "total": 49.00,
    "paid": true,
    "number": "SNIP-1041"
  }
]

Was this article helpful?