Schedule Subscription Cancellation

POST/v2/subscriptions/{id}/schedule-cancellation

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.

Path parameters

idstring<uuid>required

Header parameters

idempotency-keystringrequired

Required for write endpoints that create records and need deterministic retry behavior.

min length 1 · max length 255

if-matchstringrequired

Strong entity revision ETag returned by the latest read or write.

matches ^\"[0-9]+\"$

x-request-idstring

Optional caller-provided request correlation ID.

min length 1

Request body

application/json

reasonstring

min length 1 · max length 500

Responses

200OK

subscriptionobjectrequired

Show properties

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

400Standard Cipay error response.

errorobjectrequired

Show properties

codestringrequired

min length 1

messagestringrequired

min length 1

requestIdstringrequired

min length 1

detailsobject

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

428Standard 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 POST "https://api.cipay.net/v2/subscriptions/%3Cuuid%3E/schedule-cancellation" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "idempotency-key: string" \
  -H "if-match: string" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "string"
}'

const response = await fetch("https://api.cipay.net/v2/subscriptions/%3Cuuid%3E/schedule-cancellation", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "idempotency-key": "string",
    "if-match": "string",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "reason": "string"
})
});

Response

{
  "subscription": {
    "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"
  }
}