SellApp
API ReferenceSubscriptions

Read subscriptions

List, search, and retrieve canonical subscription records.

These responses include the canonical nested customer plus provider_subscription_id and provider_customer_id. The older subscription_id and customer_id provider fields remain available but are deprecated.

Lists are returned oldest first, ordered by ID. Subscriptions the store bills in house report internal as their provider and have no provider identifiers. Retrieve a subscription by the SellApp subscription record ID in productSubscription, the same identifier the lifecycle action endpoints take. A subscription belonging to another store returns 404.

GET
/v2/subscriptions

Authorization

AuthorizationBearer <token>

Provide your SellApp API key as a bearer token.

In: header

Query Parameters

limit?integer

Number of items to return per page.

Default15
Range1 <= value <= 100
page?integer

Page number to return.

Default1
Range1 <= value
pagination?boolean

Set to false to return at most 100 matching items in one data array without pagination links or metadata.

Defaulttrue
status[]?array<>

Filter by one or more subscription statuses. Repeat the parameter to select several; a single status=ACTIVE works too. A status outside the list is rejected with a validation error.

Header Parameters

X-STORE?string

Store slug. Required for OAuth access tokens. API keys may omit it to use their current store, or the first accessible store when no current store is selected.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://sell.app/api/v2/subscriptions" \  -H "X-STORE: launch-lab"
{
  "data": [
    {
      "id": 123,
      "invoice_id": 456,
      "provider": "stripe",
      "subscription_id": "sub_1QwertyExample",
      "customer_id": "cus_Example123",
      "provider_subscription_id": "sub_1QwertyExample",
      "provider_customer_id": "cus_Example123",
      "customer": {
        "id": 314,
        "email": "maya.chen@example.com",
        "external_id": "crm_314",
        "name": "Maya Chen",
        "locale": "en-GB",
        "metadata": {}
      },
      "customer_email": "maya.chen@example.com",
      "status": "ACTIVE",
      "current_period_start": "2026-03-01T00:00:00.000000Z",
      "current_period_end": "2026-04-01T00:00:00.000000Z",
      "trial_ends_at": null,
      "cancel_at_period_end": true,
      "cancellation_in_progress": false,
      "store_id": 1,
      "product_variant_id": 99,
      "current_plan_variant_id": 99,
      "auto_renew": false,
      "paused_at": null,
      "pause_resumes_at": null,
      "canceled_immediately_at": null,
      "payment_method_updated_at": "2026-03-15T09:30:00.000000Z",
      "last_customer_action_at": "2026-03-23T00:00:00.000000Z",
      "created_at": "2026-03-01T00:00:00.000000Z",
      "updated_at": "2026-03-23T00:00:00.000000Z"
    },
    {
      "id": 124,
      "invoice_id": 457,
      "provider": "internal",
      "subscription_id": null,
      "customer_id": null,
      "provider_subscription_id": null,
      "provider_customer_id": null,
      "customer": {
        "id": 315,
        "email": "noah.bennett@example.com",
        "external_id": null,
        "name": null,
        "locale": null,
        "metadata": {}
      },
      "customer_email": "noah.bennett@example.com",
      "status": "PAST_DUE",
      "current_period_start": "2026-03-05T00:00:00.000000Z",
      "current_period_end": "2026-04-05T00:00:00.000000Z",
      "trial_ends_at": null,
      "cancel_at_period_end": false,
      "cancellation_in_progress": false,
      "store_id": 1,
      "product_variant_id": 99,
      "current_plan_variant_id": 101,
      "auto_renew": true,
      "paused_at": null,
      "pause_resumes_at": null,
      "canceled_immediately_at": null,
      "payment_method_updated_at": null,
      "last_customer_action_at": "2026-03-20T10:15:00.000000Z",
      "created_at": "2026-02-05T00:00:00.000000Z",
      "updated_at": "2026-04-05T00:05:00.000000Z"
    },
    {
      "id": 125,
      "invoice_id": 458,
      "provider": "stripe",
      "subscription_id": "sub_1TrialExample",
      "customer_id": "cus_TrialExample",
      "provider_subscription_id": "sub_1TrialExample",
      "provider_customer_id": "cus_TrialExample",
      "customer": {
        "id": 316,
        "email": "sofia.rivera@example.com",
        "external_id": null,
        "name": "Sofia Rivera",
        "locale": null,
        "metadata": {}
      },
      "customer_email": "sofia.rivera@example.com",
      "status": "TRIALING",
      "current_period_start": "2026-03-28T00:00:00.000000Z",
      "current_period_end": "2026-04-04T00:00:00.000000Z",
      "trial_ends_at": "2026-04-04T00:00:00.000000Z",
      "cancel_at_period_end": false,
      "cancellation_in_progress": false,
      "store_id": 1,
      "product_variant_id": 99,
      "current_plan_variant_id": 99,
      "auto_renew": false,
      "paused_at": null,
      "pause_resumes_at": null,
      "canceled_immediately_at": null,
      "payment_method_updated_at": null,
      "last_customer_action_at": null,
      "created_at": "2026-03-28T00:00:00.000000Z",
      "updated_at": "2026-03-28T00:00:00.000000Z"
    }
  ],
  "links": {
    "first": "https://sell.app/api/v2/subscriptions?page=1",
    "last": "https://sell.app/api/v2/subscriptions?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "path": "https://sell.app/api/v2/subscriptions",
    "per_page": 15,
    "to": 3,
    "total": 3,
    "links": [
      {
        "url": null,
        "label": "&laquo; Previous",
        "active": false
      },
      {
        "url": "https://sell.app/api/v2/subscriptions?page=1",
        "label": "1",
        "active": true
      },
      {
        "url": null,
        "label": "Next &raquo;",
        "active": false
      }
    ]
  }
}
{
  "type": "invalid_request_error",
  "code": "bad_request",
  "message": "The request could not be understood.",
  "status": 400,
  "param": null,
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#bad-request"
}
{
  "type": "authentication_error",
  "code": "unauthenticated",
  "message": "Unauthenticated.",
  "status": 401,
  "param": null,
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#unauthenticated"
}
{
  "type": "authorization_error",
  "code": "forbidden",
  "message": "This action is unauthorized.",
  "status": 403,
  "param": null,
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#forbidden"
}
{
  "type": "validation_error",
  "code": "validation_failed",
  "message": "The selected product variant id is invalid.",
  "status": 422,
  "param": "product_variant_id",
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#validation-failed",
  "errors": {
    "product_variant_id": [
      "The selected product variant id is invalid."
    ]
  }
}
{
  "type": "rate_limit_error",
  "code": "rate_limit_exceeded",
  "message": "Too Many Attempts.",
  "status": 429,
  "param": null,
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#rate-limit-exceeded"
}
{
  "type": "api_error",
  "code": "api_error",
  "message": "Server Error",
  "status": 500,
  "param": null,
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#api-error"
}
POST
/v2/subscriptions/search

Authorization

AuthorizationBearer <token>

Provide your SellApp API key as a bearer token.

In: header

Query Parameters

limit?integer

Number of items to return per page.

Default15
Range1 <= value <= 100
page?integer

Page number to return.

Default1
Range1 <= value
pagination?boolean

Set to false to return at most 100 matching items in one data array without pagination links or metadata.

Defaulttrue

Header Parameters

X-STORE?string

Store slug. Required for OAuth access tokens. API keys may omit it to use their current store, or the first accessible store when no current store is selected.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://sell.app/api/v2/subscriptions/search" \  -H "X-STORE: launch-lab" \  -H "Content-Type: application/json" \  -d '{    "search": {      "value": "maya.chen@example.com"    },    "filters": [      {        "field": "status",        "operator": "=",        "value": "ACTIVE"      }    ]  }'
{
  "data": [
    {
      "id": 123,
      "invoice_id": 456,
      "provider": "stripe",
      "subscription_id": "sub_1QwertyExample",
      "customer_id": "cus_Example123",
      "provider_subscription_id": "sub_1QwertyExample",
      "provider_customer_id": "cus_Example123",
      "customer": {
        "id": 314,
        "email": "maya.chen@example.com",
        "external_id": "crm_314",
        "name": "Maya Chen",
        "locale": "en-GB",
        "metadata": {}
      },
      "customer_email": "maya.chen@example.com",
      "status": "ACTIVE",
      "current_period_start": "2026-03-01T00:00:00.000000Z",
      "current_period_end": "2026-04-01T00:00:00.000000Z",
      "trial_ends_at": null,
      "cancel_at_period_end": true,
      "cancellation_in_progress": false,
      "store_id": 1,
      "product_variant_id": 99,
      "current_plan_variant_id": 99,
      "auto_renew": false,
      "paused_at": null,
      "pause_resumes_at": null,
      "canceled_immediately_at": null,
      "payment_method_updated_at": "2026-03-15T09:30:00.000000Z",
      "last_customer_action_at": "2026-03-23T00:00:00.000000Z",
      "created_at": "2026-03-01T00:00:00.000000Z",
      "updated_at": "2026-03-23T00:00:00.000000Z"
    }
  ],
  "links": {
    "first": "https://sell.app/api/v2/subscriptions/search?page=1",
    "last": "https://sell.app/api/v2/subscriptions/search?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "path": "https://sell.app/api/v2/subscriptions/search",
    "per_page": 15,
    "to": 1,
    "total": 1,
    "links": [
      {
        "url": null,
        "label": "&laquo; Previous",
        "active": false
      },
      {
        "url": "https://sell.app/api/v2/subscriptions/search?page=1",
        "label": "1",
        "active": true
      },
      {
        "url": null,
        "label": "Next &raquo;",
        "active": false
      }
    ]
  }
}
{
  "type": "invalid_request_error",
  "code": "bad_request",
  "message": "The request could not be understood.",
  "status": 400,
  "param": null,
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#bad-request"
}
{
  "type": "authentication_error",
  "code": "unauthenticated",
  "message": "Unauthenticated.",
  "status": 401,
  "param": null,
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#unauthenticated"
}
{
  "type": "authorization_error",
  "code": "forbidden",
  "message": "This action is unauthorized.",
  "status": 403,
  "param": null,
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#forbidden"
}
{
  "type": "validation_error",
  "code": "validation_failed",
  "message": "The selected product variant id is invalid.",
  "status": 422,
  "param": "product_variant_id",
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#validation-failed",
  "errors": {
    "product_variant_id": [
      "The selected product variant id is invalid."
    ]
  }
}
{
  "type": "rate_limit_error",
  "code": "rate_limit_exceeded",
  "message": "Too Many Attempts.",
  "status": 429,
  "param": null,
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#rate-limit-exceeded"
}
{
  "type": "api_error",
  "code": "api_error",
  "message": "Server Error",
  "status": 500,
  "param": null,
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#api-error"
}
GET
/v2/subscriptions/{productSubscription}

Authorization

AuthorizationBearer <token>

Provide your SellApp API key as a bearer token.

In: header

Path Parameters

productSubscription*integer

The productSubscription path parameter.

Header Parameters

X-STORE?string

Store slug. Required for OAuth access tokens. API keys may omit it to use their current store, or the first accessible store when no current store is selected.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://sell.app/api/v2/subscriptions/123" \  -H "X-STORE: launch-lab"
{
  "data": {
    "id": 123,
    "invoice_id": 456,
    "provider": "stripe",
    "subscription_id": "sub_1QwertyExample",
    "customer_id": "cus_Example123",
    "provider_subscription_id": "sub_1QwertyExample",
    "provider_customer_id": "cus_Example123",
    "customer": {
      "id": 314,
      "email": "maya.chen@example.com",
      "external_id": "crm_314",
      "name": "Maya Chen",
      "locale": "en-GB",
      "metadata": {}
    },
    "customer_email": "maya.chen@example.com",
    "status": "ACTIVE",
    "current_period_start": "2026-03-01T00:00:00.000000Z",
    "current_period_end": "2026-04-01T00:00:00.000000Z",
    "trial_ends_at": null,
    "cancel_at_period_end": true,
    "cancellation_in_progress": false,
    "store_id": 1,
    "product_variant_id": 99,
    "current_plan_variant_id": 99,
    "auto_renew": false,
    "paused_at": null,
    "pause_resumes_at": null,
    "canceled_immediately_at": null,
    "payment_method_updated_at": "2026-03-15T09:30:00.000000Z",
    "last_customer_action_at": "2026-03-23T00:00:00.000000Z",
    "created_at": "2026-03-01T00:00:00.000000Z",
    "updated_at": "2026-03-23T00:00:00.000000Z"
  }
}
{
  "type": "invalid_request_error",
  "code": "bad_request",
  "message": "The request could not be understood.",
  "status": 400,
  "param": null,
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#bad-request"
}
{
  "type": "authentication_error",
  "code": "unauthenticated",
  "message": "Unauthenticated.",
  "status": 401,
  "param": null,
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#unauthenticated"
}
{
  "type": "authorization_error",
  "code": "forbidden",
  "message": "This action is unauthorized.",
  "status": 403,
  "param": null,
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#forbidden"
}
{
  "type": "not_found_error",
  "code": "resource_not_found",
  "message": "Not Found.",
  "status": 404,
  "param": null,
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#resource-not-found"
}
{
  "type": "validation_error",
  "code": "validation_failed",
  "message": "The selected product variant id is invalid.",
  "status": 422,
  "param": "product_variant_id",
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#validation-failed",
  "errors": {
    "product_variant_id": [
      "The selected product variant id is invalid."
    ]
  }
}
{
  "type": "rate_limit_error",
  "code": "rate_limit_exceeded",
  "message": "Too Many Attempts.",
  "status": 429,
  "param": null,
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#rate-limit-exceeded"
}
{
  "type": "api_error",
  "code": "api_error",
  "message": "Server Error",
  "status": 500,
  "param": null,
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#api-error"
}

Overview

Manage recurring subscription lifecycle actions across supported providers.

Cancel a subscription PATCH

Cancel an active subscription now or at the end of its billing period, or cancel one with a payment still owed now.