List Subscriptions

GET/v2/subscriptions

Authorization

AuthorizationBearer token · headerrequired

Merchant API key scoped to one merchant and environment. Read operations require api:read, normal write operations require api:write, and broadcast mutations also require explicit broadcasts:write.

Query parameters

statusstring

default: "all"

Allowed:trialingactiverenewinggrace_periodpast_duecanceledall

customerIdstring<uuid>

limitinteger

min 1 · max 100 · default: 25

cursorstring

matches ^\d+$

Header parameters

x-request-idstring

Optional caller-provided request correlation ID.

min length 1

Responses

200OK

subscriptionsobject[]required

Show properties

Array of object

idstring<uuid>required

merchantIdstring<uuid>required

environmentstringrequired

Allowed:sandboxproduction

customerIdstring<uuid>required

planIdstring<uuid>required

planSnapshotobjectrequired

Show properties

planIdstring<uuid>required

planVersionIdstring<uuid> | anyrequired

Show properties

Any of:

string<uuid>

string<uuid>

any

any

planVersionNumberinteger | anyrequired

Show properties

Any of:

integer

integer

any

any

productIdstring<uuid>required

namestringrequired

min length 1 · max length 160

descriptionstring | anyrequired

Show properties

Any of:

string

string

any

any

amountHalalasintegerrequired

min -9007199254740991 · max 9007199254740991

currencyanyrequired

intervalstringrequired

Allowed:monthyear

cadenceobjectrequired

Show properties

intervalUnitstringrequired

Allowed:dayweekmonthyear

intervalCountintegerrequired

min -9007199254740991 · max 9007199254740991

trialDaysintegerrequired

min 0 · max 365

couponobject | anyrequired

Show properties

Any of:

object

Any of:

object

codestringrequired

max length 64 · matches ^[A-Z0-9_-]{1,64}$

discountTypeanyrequired

percentOffBpsintegerrequired

min 1 · max 10000

amountOffHalalasany

object

codestringrequired

max length 64 · matches ^[A-Z0-9_-]{1,64}$

discountTypeanyrequired

amountOffHalalasintegerrequired

min -9007199254740991 · max 2147483647

percentOffBpsany

any

any

billingAnchorPolicystring | anyrequired

Show properties

Any of:

string

string

any

any

billingAnchorAtstring<date-time> | anyrequired

Show properties

Any of:

string<date-time>

string<date-time>

any

any

capturedAtstring<date-time>required

statusstringrequired

Allowed:trialingactiverenewinggrace_periodpast_duecanceled

revisionintegerrequired

min -9007199254740991 · max 9007199254740991

originalBillingAnchorAtstring<date-time>required

currentPeriodStartedAtstring<date-time>required

currentPeriodEndsAtstring<date-time>required

nextBillingAtstring<date-time> | anyrequired

Show properties

Any of:

string<date-time>

string<date-time>

any

any

scheduledCancellationAtstring<date-time> | anyrequired

Show properties

Any of:

string<date-time>

string<date-time>

any

any

trialStartedAtstring<date-time> | anyrequired

Show properties

Any of:

string<date-time>

string<date-time>

any

any

trialEndsAtstring<date-time> | anyrequired

Show properties

Any of:

string<date-time>

string<date-time>

any

any

graceStartedAtstring<date-time> | anyrequired

Show properties

Any of:

string<date-time>

string<date-time>

any

any

graceEndsAtstring<date-time> | anyrequired

Show properties

Any of:

string<date-time>

string<date-time>

any

any

canceledAtstring<date-time> | anyrequired

Show properties

Any of:

string<date-time>

string<date-time>

any

any

endedAtstring<date-time> | anyrequired

Show properties

Any of:

string<date-time>

string<date-time>

any

any

scheduledCancellationReasonstring | anyrequired

Show properties

Any of:

string

string

any

any

createdAtstring<date-time>required

updatedAtstring<date-time>required

customerobjectrequired

Show properties

idstring<uuid>required

namestring | anyrequired

Show properties

Any of:

string

string

any

any

emailstring<email>required

mobilestring | anyrequired

Show properties

Any of:

string

string

any

any

avatarUrlstring<uri> | any

Show properties

Any of:

string<uri>

string<uri>

any

any

localestringrequired

Allowed:enar

nextCursorstring | anyrequired

Show properties

Any of:

string

string

any

any

401Standard Cipay error response.

errorobjectrequired

Show properties

codestringrequired

min length 1

messagestringrequired

min length 1

requestIdstringrequired

min length 1

detailsobject

403Standard Cipay error response.

errorobjectrequired

Show properties

codestringrequired

min length 1

messagestringrequired

min length 1

requestIdstringrequired

min length 1

detailsobject

404Standard Cipay error response.

errorobjectrequired

Show properties

codestringrequired

min length 1

messagestringrequired

min length 1

requestIdstringrequired

min length 1

detailsobject

409Standard Cipay error response.

errorobjectrequired

Show properties

codestringrequired

min length 1

messagestringrequired

min length 1

requestIdstringrequired

min length 1

detailsobject

422Standard Cipay error response.

errorobjectrequired

Show properties

codestringrequired

min length 1

messagestringrequired

min length 1

requestIdstringrequired

min length 1

detailsobject

429Standard Cipay error response.

errorobjectrequired

Show properties

codestringrequired

min length 1

messagestringrequired

min length 1

requestIdstringrequired

min length 1

detailsobject

500Standard Cipay error response.

errorobjectrequired

Show properties

codestringrequired

min length 1

messagestringrequired

min length 1

requestIdstringrequired

min length 1

detailsobject

Request

curl -X GET "https://api.cipay.net/v2/subscriptions" \
  -H "Authorization: Bearer YOUR_TOKEN"

const response = await fetch("https://api.cipay.net/v2/subscriptions", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN"
  }
});

Response

{
  "subscriptions": [
    {
      "id": "<uuid>",
      "merchantId": "<uuid>",
      "environment": "sandbox",
      "customerId": "<uuid>",
      "planId": "<uuid>",
      "planSnapshot": {
        "planId": "<uuid>",
        "planVersionId": "<uuid>",
        "planVersionNumber": 0,
        "productId": "<uuid>",
        "name": "string",
        "description": "string",
        "amountHalalas": 0,
        "currency": "SAR",
        "interval": "month",
        "cadence": {
          "intervalUnit": "day",
          "intervalCount": 0
        },
        "trialDays": 0,
        "coupon": {
          "code": "string",
          "discountType": "percent",
          "percentOffBps": 0,
          "amountOffHalalas": "string"
        },
        "billingAnchorPolicy": "keep_anchor",
        "billingAnchorAt": "2024-01-01T00:00:00Z",
        "capturedAt": "2024-01-01T00:00:00Z"
      },
      "status": "trialing",
      "revision": 0,
      "originalBillingAnchorAt": "2024-01-01T00:00:00Z",
      "currentPeriodStartedAt": "2024-01-01T00:00:00Z",
      "currentPeriodEndsAt": "2024-01-01T00:00:00Z",
      "nextBillingAt": "2024-01-01T00:00:00Z",
      "scheduledCancellationAt": "2024-01-01T00:00:00Z",
      "trialStartedAt": "2024-01-01T00:00:00Z",
      "trialEndsAt": "2024-01-01T00:00:00Z",
      "graceStartedAt": "2024-01-01T00:00:00Z",
      "graceEndsAt": "2024-01-01T00:00:00Z",
      "canceledAt": "2024-01-01T00:00:00Z",
      "endedAt": "2024-01-01T00:00:00Z",
      "scheduledCancellationReason": "string",
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-01T00:00:00Z",
      "customer": {
        "id": "<uuid>",
        "name": "string",
        "email": "<email>",
        "mobile": "string",
        "avatarUrl": "<uri>",
        "locale": "en"
      }
    }
  ],
  "nextCursor": "string"
}