Subscriptions REST API: Subscriptions docs

The Chargezen Subscriptions REST API lets your own server find a customer, read their subscriptions and coming orders, change them (pause, resume, skip, swap, order now and more) and start new ones, with a workspace API key.

Base URL

https://api.chargezen.com/v1. Every path in these docs is relative to it. Requests and responses are JSON.

What it covers

The API works with subscriptions that run on Chargezen and Shopify subscription contracts. Subscriptions billed by Recharge or Stripe aren't included.

Each request does exactly what the matching subscription tool on Chargezen's MCP server does, so both make the same changes and refuse the same things. A key acts as the teammate who gave it access, with that teammate's current role, and its changes are recorded as that teammate, through an API key.

Quick start

Create a key that can read and change subscriptions (see Authentication and keys), put its key id and secret in CHARGEZEN_KEY_ID and CHARGEZEN_SECRET, then follow one customer from search to a pause and back.

1. Find the customer

GET /customers

curl -G "https://api.chargezen.com/v1/customers" \
  --data-urlencode "query=ada@example.com" \
  -H "X-Chargezen-Key-Id: $CHARGEZEN_KEY_ID" \
  -H "Authorization: Bearer $CHARGEZEN_SECRET"

{
  "customers": [
    {
      "customer_ref": { "type": "customer_modal", "id": "8f14e45f-ceea-467f-a0e6-0e1c2f4b9d3a" },
      "name": "Ada Lovelace",
      "email": "ada@example.com",
      "phone": "+15555550123",
      "address": { "address1": "12 Main St", "address2": null, "city": "Austin", "state": "TX", "zip_code": "78701", "country": "US" }
    }
  ],
  "has_more": false
}

The customer's customer_ref.id is the customer_id in every path below.

2. List their subscriptions

GET /customers/{customer_id}/subscriptions

curl "https://api.chargezen.com/v1/customers/8f14e45f-ceea-467f-a0e6-0e1c2f4b9d3a/subscriptions" \
  -H "X-Chargezen-Key-Id: $CHARGEZEN_KEY_ID" \
  -H "Authorization: Bearer $CHARGEZEN_SECRET"

Each subscription's subscription_ref.id (here 48213) is the id in its paths.

3. Read the coming orders

GET .../upcoming_orders

curl "https://api.chargezen.com/v1/customers/8f14e45f-ceea-467f-a0e6-0e1c2f4b9d3a/subscriptions/48213/upcoming_orders" \
  -H "X-Chargezen-Key-Id: $CHARGEZEN_KEY_ID" \
  -H "Authorization: Bearer $CHARGEZEN_SECRET"

4. Pause it until a date

POST .../pause

curl -X POST "https://api.chargezen.com/v1/customers/8f14e45f-ceea-467f-a0e6-0e1c2f4b9d3a/subscriptions/48213/pause" \
  -H "X-Chargezen-Key-Id: $CHARGEZEN_KEY_ID" \
  -H "Authorization: Bearer $CHARGEZEN_SECRET" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "resume_on": "2027-01-12" }'

{
  "provider": "internal",
  "subscription": { "id": "48213", "shopify_id": "30971223344", "provider": "internal", "status": "PAUSED", "resume_on": "2027-01-12" }
}

5. Resume it

POST .../resume

curl -X POST "https://api.chargezen.com/v1/customers/8f14e45f-ceea-467f-a0e6-0e1c2f4b9d3a/subscriptions/48213/resume" \
  -H "X-Chargezen-Key-Id: $CHARGEZEN_KEY_ID" \
  -H "Authorization: Bearer $CHARGEZEN_SECRET" \
  -H "Idempotency-Key: $(uuidgen)"

Endpoints

Method	Path	What it does	Key permission
GET	`/customers?query=`	Find customers by email, phone, name, order number or customer ID	`workspace:read`
GET	`/products?query=`	Find products and the product_selection of each variant	`workspace:read`
GET	`/subscription_plans`	List subscription plans priced for one product variant	`workspace:read`
GET	`/customers/{customer_id}/subscriptions`	List a customer's active subscriptions	`workspace:read`
GET	`/customers/{customer_id}/subscriptions/{id}`	Read one subscription, in any status	`workspace:read`
GET	`/customers/{customer_id}/subscriptions/{id}/upcoming_orders`	Read the coming orders and the skipped ones	`workspace:read`
GET	`/customers/{customer_id}/subscriptions/{id}/swap_options`	List the products each item can be swapped to	`workspace:read`
POST	`/customers/{customer_id}/subscriptions/{id}/{change}`	Pause, resume, cancel, skip, swap and 9 more changes	`subscriptions:write`
POST	`/customers/{customer_id}/subscriptions/{id}/order_now`	Charge and place the next order now	`subscriptions:write`
POST	`/customers/{customer_id}/subscriptions`	Start a subscription with a saved payment method	`subscriptions:create`
GET	`/subscription_creations/{id}`	Check whether a new subscription is ready	`workspace:read`

Read on: Errors and retries, Reading subscriptions, Changing subscriptions, Order now and Creating subscriptions.

Questions

How do I pause a Shopify subscription with an API?

Send POST https://api.chargezen.com/v1/customers/{customer_id}/subscriptions/{id}/pause with a workspace API key that can change subscriptions and an Idempotency-Key header. Add resume_on (YYYY-MM-DD) to have it resume by itself that day. It works for subscriptions that run on Chargezen and Shopify subscription contracts.

How do I place a subscription order early (order now) through an API?

Read the subscription's upcoming orders, then send POST https://api.chargezen.com/v1/customers/{customer_id}/subscriptions/{id}/order_now with the first order's cycle_index and scheduled_at. Chargezen charges the saved payment method and places that order now. Repeat the same request with the same Idempotency-Key until it answers placed; it never charges twice.

How do I authenticate to the Chargezen API?

Create a key in Chargezen under Settings → API keys and choose what it can do. Send its key id in the X-Chargezen-Key-Id header and its secret as Authorization: Bearer on every request. The secret is shown once, when you create the key.

Can an AI assistant manage Shopify subscriptions?

Yes. Connect ChatGPT, Claude or another assistant to Chargezen's MCP server at https://mcp.chargezen.com/mcp/subscriptions. It can find a customer's subscriptions and pause, resume, skip, swap, reschedule, order now or cancel them, as the teammate who connected it. Big changes ask you first.

Subscriptions REST API