---
title: "Subscriptions REST API: Subscriptions docs | Chargezen"
description: "Manage Shopify subscriptions from your own server: find customers, read subscriptions and upcoming orders, then pause, skip, swap, order now or start new ones."
url: "https://chargezen.com/docs/subscriptions/api"
lang: "en"
updated: "2026-11-09"
---

Canonical URL: https://chargezen.com/docs/subscriptions/api

# Subscriptions REST API

Manage Shopify subscriptions from your own server: find customers, read subscriptions and upcoming orders, then pause, skip, swap, order now or start new ones.

Last updated: 2026-11-09

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](https://chargezen.com/developers/mcp) 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](https://chargezen.com/docs/subscriptions/api/authentication)), 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

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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](https://chargezen.com/docs/subscriptions/api/errors), [Reading subscriptions](https://chargezen.com/docs/subscriptions/api/reading-subscriptions), [Changing subscriptions](https://chargezen.com/docs/subscriptions/api/changing-subscriptions), [Order now](https://chargezen.com/docs/subscriptions/api/order-now) and [Creating subscriptions](https://chargezen.com/docs/subscriptions/api/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.

### Related Articles

[

#### Authentication and keys

Create a key and send it with each request



](https://chargezen.com/docs/subscriptions/api/authentication)[

#### Changing subscriptions

Every change and what it takes



](https://chargezen.com/docs/subscriptions/api/changing-subscriptions)[

#### Subscription changes with Concierge

Let customers make changes by chat



](https://chargezen.com/docs/subscriptions/concierge-subscription-changes)

Was this page helpful?

Need more help? [Contact support](https://chargezen.com/docs/checkoutos/troubleshooting/support)