Subscription Management

The Management group lets an authenticated customer mutate their own subscription contracts: pause/resume/cancel, swap products, change frequency, edit shipping and payment, manage lines, and act on billing cycles.

All paths are relative to the base URL:

https://<your-app-domain>/storefront-api/v1

Every management endpoint requires both auth layers on every request:

X-Joy-App-Id: <app-id>
X-Joy-Secret-Key: sk_live_xxx     # server-side only — never expose in the browser
X-Session-Id: <session-id>

The shopId is always derived from the session, never from a header. {contractId} is the numeric subscriptionContractId. Accessing a contract that is not owned by the authenticated customer returns 404 NOT_FOUND (this also covers contracts that do not exist, to prevent IDOR).

Write methods (POST / PUT / DELETE) are subject to the write rate-limit dimension (20 requests / 60s per customer, burst 5). Exceeding any limit returns 429 RATE_LIMITED. Many of these endpoints return { "success": true } with no data on success.

Endpoint summary

Status — pause / resume / cancel

PUT /subscriptions/{contractId}/status

Body

{ "status": "pause" }

Response

{ "success": true }

curl -X PUT "https://<your-app-domain>/storefront-api/v1/subscriptions/123456789/status" \
  -H "X-Joy-App-Id: <app-id>" \
  -H "X-Joy-Secret-Key: sk_live_xxx" \
  -H "X-Session-Id: <session-id>" \
  -H "Content-Type: application/json" \
  -d '{ "status": "pause" }'

Cancel with a reason

POST /subscriptions/{contractId}/cancel

Cancel with a structured reason. reasonCode is threaded into the outbound subscription_contracts/cancel webhook payload.

Body

{ "reasonCode": "too_expensive", "comment": "Found a cheaper option" }

Response

{ "success": true, "data": { "contractId": 123456789, "status": "cancelled" } }

Swap product / variant

PUT /subscriptions/{contractId}/product

Extra planData fields are forwarded verbatim to the swap service.

Body

{ "newVariantId": 4455667788, "lineId": "gid://shopify/SubscriptionLine/1" }

Response

{ "success": true }

Change frequency

PUT /subscriptions/{contractId}/frequency

Body

{ "input": { "interval": "MONTH", "intervalCount": 2 } }

Response

{ "success": true, "data": { } }

Shipping address

Get current address

GET /subscriptions/{contractId}/shipping-address

Returns the current delivery address (PII projection).

{
  "success": true,
  "data": {
    "firstName": "…", "lastName": "…",
    "address1": "…", "address2": null,
    "city": "…", "province": "…", "provinceCode": "…",
    "country": "…", "countryCode": "…",
    "zip": "…", "phone": "…", "company": null
  }
}

Update address

PUT /subscriptions/{contractId}/shipping-address

Body

{ "input": { "address1": "123 Main St", "city": "Hanoi", "zip": "100000" } }

Response

{ "success": true }

Payment method

Get masked metadata

GET /subscriptions/{contractId}/payment-method

Masked payment metadata only — never PAN/CVV.

{
  "success": true,
  "data": { "id": "…", "brand": "visa", "last4": "4242", "expiryMonth": 12, "expiryYear": 2027 }
}

Update payment method

PUT /subscriptions/{contractId}/payment-method

Assign a tokenized payment method.

Body

{ "input": { "paymentMethodId": "<payment-method-id>" } }

Response

{ "success": true }

Change shipping option

PUT /subscriptions/{contractId}/shipping-option

Body

{ "shippingOption": { "handle": "standard", "title": "Standard", "price": "5.00" } }

Response

{ "success": true }

Subscription discount

PUT /subscriptions/{contractId}/subscription-discount

Apply a subscription-level discount.

Merchant-gated: returns 403 FORBIDDEN unless the merchant enabled customerPortal.allowSubscriptionDiscount (disabled by default).

Body

{ "discountType": "PERCENTAGE", "discountValue": 10 }

Response

{ "success": true }

Recurring lines

Add a line

POST /subscriptions/{contractId}/lines

Body

{ "lines": [ { "variantId": 4455667788, "quantity": 1 } ] }

Response

{ "success": true, "data": { } }

Remove a line

DELETE /subscriptions/{contractId}/lines/{lineId}

lineId is a path param; the body carries optional metadata.

Body (optional)

Response

{ "success": true, "data": { } }

Billing cycle

PUT /subscriptions/{contractId}/billing-cycle

Skip / reschedule / resume / order-now a billing cycle.

Body

An unsupported type returns 400 INVALID_PARAM.

{ "type": "skip", "cycleIndex": 5 }

{ "type": "reschedule", "cycleIndex": 5, "newBillingDate": "2026-08-01T00:00:00.000Z" }

Response

{ "success": true, "data": { } }

Upcoming-order lines

Update an upcoming-order line

PUT /subscriptions/{contractId}/upcoming-orders/{cycleIndex}/lines/{lineId}

Edit a line on a specific upcoming order/cycle.

Path: contractId, cycleIndex (integer), lineId.

Body

{ "input": { "quantity": 2 } }

Response

{ "success": true, "data": { } }

Remove an upcoming-order line

DELETE /subscriptions/{contractId}/upcoming-orders/{cycleIndex}/lines/{lineId}

Remove a line from a specific upcoming order/cycle. No body.

Response

{ "success": true }

Add a one-off product to an upcoming order

POST /subscriptions/{contractId}/upcoming-orders/products

Body

{ "cycleIndex": 5, "lines": [ { "variantId": 4455667788, "quantity": 1 } ] }

Response

{ "success": true, "data": { } }

Discount code

Apply a discount code

POST /subscriptions/{contractId}/discount

Body

{ "discountCode": "SAVE10" }

Response

{ "success": true, "data": { } }

Remove an applied discount

DELETE /subscriptions/{contractId}/discount

Body

Response

{ "success": true }

Errors

Error envelope:

{ "success": false, "error": { "code": "NOT_FOUND", "message": "..." } }