Clearway Documentation
  • Home
  • Guides
  • Merchant API
  • Investor Read API
Back to Merchant APIInformation
Analytics
    Read analyticspost
Checkout
    Create checkout sessionspostCreate payment intentpost
Customers
    Manage customerspost
Orders
    Get orderpostRead orderspost
Payment links
    Create payment linkspostList payment linkspost
Payments
    Preview platform feespostProcess refundspostResolve embed displaypost
Products
    Write merchant couponspostWrite productspostDelete productpostGet productpostRead merchant couponspostRead productspostUpdate merchant couponpostUpdate productpost
Subscriptions
    Cancel subscriptionspostChange subscription planspostRead subscriptionspostPreview subscription plan changespost
Schemas
powered by Zudoku
Clearway Documentation
Clearway Documentation

Subscriptions

Download schema

Cancel subscriptions

POST
https://api-dev.clearway.to
/CANCEL_MERCHANT_SUBSCRIPTION

Cancel a payer subscription using your commerce cancel policy (immediate or at period end). Use the id field from LIST_MERCHANT_SUBSCRIPTIONS — not stripe_subscription_id.

Cancel subscriptions › Headers

x-cid
​string

Optional correlation id for support trails.

x-brand-id
​string

Optional platform brand slug for multi-brand merchants.

Idempotency-Key
​string

Stable key for safe retries on money-moving requests.

Cancel subscriptions › Request Body

id
​string
Additional properties are allowed

Cancel subscriptions › Responses

Success

MerchantApiSuccessEnvelope
success
​boolean · required
Additional properties are allowed
POST/CANCEL_MERCHANT_SUBSCRIPTION
curl https://api-dev.clearway.to/CANCEL_MERCHANT_SUBSCRIPTION \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <token>' \ --data '{ "id": "14635c65-b6ff-4b46-8eda-f5dbd8598f21" }'
Example Request Body
{ "id": "14635c65-b6ff-4b46-8eda-f5dbd8598f21" }
json
application/json
Example Responses
{ "success": true }
json
application/json

Change subscription plans

POST
https://api-dev.clearway.to
/CHANGE_MERCHANT_SUBSCRIPTION_PLAN

Apply a plan change for a payer subscription to another catalog product in the same plan family. Preview first. Use Clearway subscription id as subscriptionId. Sandbox-mode API keys return a simulated success via EXECUTE_API_SANDBOX_CALL (no live charge).

Change subscription plans › Headers

Idempotency-Key
​string · required

Stable key for safe retries on money-moving requests.

x-cid
​string

Optional correlation id for support trails.

x-brand-id
​string

Optional platform brand slug for multi-brand merchants.

Change subscription plans › Request Body

subscriptionId
​string
targetProductId
​string
Additional properties are allowed

Change subscription plans › Responses

Success

MerchantApiSuccessEnvelope
success
​boolean · required
Additional properties are allowed
POST/CHANGE_MERCHANT_SUBSCRIPTION_PLAN
curl https://api-dev.clearway.to/CHANGE_MERCHANT_SUBSCRIPTION_PLAN \ --request POST \ --header 'Content-Type: application/json' \ --header 'Idempotency-Key: <string>' \ --header 'Authorization: Bearer <token>' \ --data '{ "subscriptionId": "14635c65-b6ff-4b46-8eda-f5dbd8598f21", "targetProductId": "00000000-0000-4000-8000-000000000002" }'
Example Request Body
{ "subscriptionId": "14635c65-b6ff-4b46-8eda-f5dbd8598f21", "targetProductId": "00000000-0000-4000-8000-000000000002" }
json
application/json
Example Responses
{ "success": true }
json
application/json

Read subscriptions

POST
https://api-dev.clearway.to
/LIST_MERCHANT_SUBSCRIPTIONS

List payer subscriptions to your catalog products. Each row includes an id (Clearway UUID) — use that value in Cancel subscriptions, not stripe_subscription_id. Response includes totalCount, offset, limit, and capped when more rows exist than returned.

Read subscriptions › Headers

x-cid
​string

Optional correlation id for support trails.

x-brand-id
​string

Optional platform brand slug for multi-brand merchants.

Read subscriptions › Request Body

limit
​number
offset
​number
status
​string
productId
​string
q
​string
Additional properties are allowed

Read subscriptions › Responses

Success

MerchantApiSuccessEnvelope
success
​boolean · required
Additional properties are allowed
POST/LIST_MERCHANT_SUBSCRIPTIONS
curl https://api-dev.clearway.to/LIST_MERCHANT_SUBSCRIPTIONS \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <token>' \ --data '{ "limit": 50, "offset": 0, "status": "active", "productId": "00000000-0000-4000-8000-000000000001", "q": "payer@example.com" }'
Example Request Body
{ "limit": 50, "offset": 0, "status": "active", "productId": "00000000-0000-4000-8000-000000000001", "q": "payer@example.com" }
json
application/json
Example Responses
{ "success": true }
json
application/json

Preview subscription plan changes

POST
https://api-dev.clearway.to
/PREVIEW_MERCHANT_SUBSCRIPTION_PLAN_CHANGE

Preview proration / timing for moving a payer subscription to another catalog product in the same plan family. Use the Clearway subscription id from list subscriptions as subscriptionId.

Preview subscription plan changes › Headers

x-cid
​string

Optional correlation id for support trails.

x-brand-id
​string

Optional platform brand slug for multi-brand merchants.

Preview subscription plan changes › Request Body

subscriptionId
​string
targetProductId
​string
Additional properties are allowed

Preview subscription plan changes › Responses

Success

MerchantApiSuccessEnvelope
success
​boolean · required
Additional properties are allowed
POST/PREVIEW_MERCHANT_SUBSCRIPTION_PLAN_CHANGE
curl https://api-dev.clearway.to/PREVIEW_MERCHANT_SUBSCRIPTION_PLAN_CHANGE \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <token>' \ --data '{ "subscriptionId": "14635c65-b6ff-4b46-8eda-f5dbd8598f21", "targetProductId": "00000000-0000-4000-8000-000000000002" }'
Example Request Body
{ "subscriptionId": "14635c65-b6ff-4b46-8eda-f5dbd8598f21", "targetProductId": "00000000-0000-4000-8000-000000000002" }
json
application/json
Example Responses
{ "success": true }
json
application/json

Products