List subscriptions

{
  "object": "list",
  "data": [
    {
      "id": "<string>",
      "object": "subscription",
      "customer": "<string>",
      "store_id": "<string>",
      "currency": "<string>",
      "description": "<string>",
      "items": [
        {
          "id": "<string>",
          "price_data": {
            "id": "<string>",
            "currency": "<string>",
            "product": "<string>",
            "unit_amount": 123,
            "recurring": {
              "interval_count": 123
            }
          },
          "quantity": 2,
          "metadata": {}
        }
      ],
      "payment_method_id": "<string>",
      "billing_cycle_anchor": 123,
      "current_period_start": 123,
      "current_period_end": 123,
      "canceled_at": 123,
      "cancel_at": 123,
      "latest_invoice": "<string>",
      "latest_invoice_object": {
        "id": "<string>",
        "object": "invoice",
        "subscription_id": "<string>",
        "customer": "<string>",
        "amount_due": 123,
        "amount_paid": 123,
        "amount_remaining": 123,
        "currency": "<string>",
        "billing_reason": "<string>",
        "period_start": 123,
        "period_end": 123,
        "created": 123,
        "frequency": "<string>",
        "recurring_interval_count": 123,
        "payment_id": "<string>",
        "paid_at": 123,
        "due_date": 123
      },
      "customer_object": {
        "id": "<string>",
        "object": "customer",
        "merchant_id": "<string>",
        "external_customer_id": "<string>",
        "email": "jsmith@example.com",
        "name": "<string>",
        "phone": "<string>",
        "default_payment_method": "<string>",
        "description": "<string>",
        "created": 123
      },
      "payment_method_object": {
        "id": "<string>",
        "object": "payment_method",
        "customer": "<string>",
        "merchant_id": "<string>",
        "type": "<string>",
        "currency": "<string>",
        "chain_type": 123,
        "mandate_id": "<string>",
        "metadata": {},
        "created": 123
      },
      "checkout_url": "<string>",
      "metadata": {},
      "created": 123
    }
  ],
  "has_more": true,
  "url": "<string>"
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "decline_code": "<string>",
    "request_log_url": "<string>",
    "charge": "<string>"
  },
  "request_id": "<string>",
  "timestamp": 123
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "decline_code": "<string>",
    "request_log_url": "<string>",
    "charge": "<string>"
  },
  "request_id": "<string>",
  "timestamp": 123
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "decline_code": "<string>",
    "request_log_url": "<string>",
    "charge": "<string>"
  },
  "request_id": "<string>",
  "timestamp": 123
}

GET

api

subscriptions

{
  "object": "list",
  "data": [
    {
      "id": "<string>",
      "object": "subscription",
      "customer": "<string>",
      "store_id": "<string>",
      "currency": "<string>",
      "description": "<string>",
      "items": [
        {
          "id": "<string>",
          "price_data": {
            "id": "<string>",
            "currency": "<string>",
            "product": "<string>",
            "unit_amount": 123,
            "recurring": {
              "interval_count": 123
            }
          },
          "quantity": 2,
          "metadata": {}
        }
      ],
      "payment_method_id": "<string>",
      "billing_cycle_anchor": 123,
      "current_period_start": 123,
      "current_period_end": 123,
      "canceled_at": 123,
      "cancel_at": 123,
      "latest_invoice": "<string>",
      "latest_invoice_object": {
        "id": "<string>",
        "object": "invoice",
        "subscription_id": "<string>",
        "customer": "<string>",
        "amount_due": 123,
        "amount_paid": 123,
        "amount_remaining": 123,
        "currency": "<string>",
        "billing_reason": "<string>",
        "period_start": 123,
        "period_end": 123,
        "created": 123,
        "frequency": "<string>",
        "recurring_interval_count": 123,
        "payment_id": "<string>",
        "paid_at": 123,
        "due_date": 123
      },
      "customer_object": {
        "id": "<string>",
        "object": "customer",
        "merchant_id": "<string>",
        "external_customer_id": "<string>",
        "email": "jsmith@example.com",
        "name": "<string>",
        "phone": "<string>",
        "default_payment_method": "<string>",
        "description": "<string>",
        "created": 123
      },
      "payment_method_object": {
        "id": "<string>",
        "object": "payment_method",
        "customer": "<string>",
        "merchant_id": "<string>",
        "type": "<string>",
        "currency": "<string>",
        "chain_type": 123,
        "mandate_id": "<string>",
        "metadata": {},
        "created": 123
      },
      "checkout_url": "<string>",
      "metadata": {},
      "created": 123
    }
  ],
  "has_more": true,
  "url": "<string>"
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "decline_code": "<string>",
    "request_log_url": "<string>",
    "charge": "<string>"
  },
  "request_id": "<string>",
  "timestamp": 123
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "decline_code": "<string>",
    "request_log_url": "<string>",
    "charge": "<string>"
  },
  "request_id": "<string>",
  "timestamp": 123
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "decline_code": "<string>",
    "request_log_url": "<string>",
    "charge": "<string>"
  },
  "request_id": "<string>",
  "timestamp": 123
}

Authorizations

Authorization

string

header

required

Bearer API Key, for example Bearer sk_live_xxx.

X-StablePay-Timestamp

string

header

required

Unix timestamp in seconds. Must be within 5 minutes of server time.

X-StablePay-Nonce

string

header

required

Replay-protection nonce, 16-64 characters. Use a fresh UUID per request.

X-StablePay-Signature

string

header

required

Lowercase hex HMAC-SHA256 of {timestamp}.{nonce}.{requestBody} signed with the merchant API Secret. For GET requests, requestBody is an empty string.

Headers

X-StablePay-Timestamp

string

required

Unix timestamp in seconds. Must be within 5 minutes of server time.

X-StablePay-Nonce

string

required

Replay-protection nonce, 16-64 characters. Use a fresh UUID per request.

Required string length: 16 - 64

X-StablePay-Signature

string

required

Lowercase hex HMAC-SHA256 of {timestamp}.{nonce}.{requestBody} signed with the merchant API Secret. For GET requests, requestBody is an empty string.

Query Parameters

customer

string

Filter by external customer ID.

status

enum<string>

Filter by subscription status. Subscription status.

Available options:

incomplete,

trialing,

active,

past_due,

canceled,

incomplete_expired

limit

integer

default:10

Number of records to return. Defaults to 10, maximum 100. Cursor pagination is not used by the current implementation.

Required range: 1 <= x <= 100

Response

Listed successfully.

object

string

Example:

"list"

data

object[]

Show child attributes

has_more

boolean

Whether more data may exist. The current implementation checks whether the returned count equals limit.

url

string

Current request URL.

Last modified on April 30, 2026

Retrieve subscription Cancel subscription

Getting Started

Payment API

Refund API

Subscription API

Invoice API

Authorizations

Headers

Query Parameters

Response