---
title: "Changing subscriptions: Subscriptions docs | Chargezen"
description: "Pause, resume, cancel, skip, reschedule, swap, change quantities, cadence, address and discounts on Shopify subscriptions with the Subscriptions REST API."
url: "https://chargezen.com/docs/subscriptions/api/changing-subscriptions"
lang: "en"
updated: "2026-11-09"
---

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

# Changing subscriptions

Pause, resume, cancel, skip, reschedule, swap, change quantities, cadence, address and discounts on Shopify subscriptions with the Subscriptions REST API.

Last updated: 2026-11-09

To change a subscription, send `POST /customers/{customer_id}/subscriptions/{id}/{change}` with the change's fields as JSON. You need a key that can change subscriptions (`subscriptions:write`), a teammate who can manage subscriptions, and an `Idempotency-Key`.

## Every change

| Change | Body | What it does |
| --- | --- | --- |
| pause | resume\_on (YYYY-MM-DD, optional) | Stops billing and deliveries. With resume\_on, after today and within a year, it resumes by itself that day; otherwise it stays paused until resumed. |
| resume | next\_billing\_date (optional), notify\_customer (default true) | Restarts a paused or cancelled subscription, optionally from a new next charge date. Send notify\_customer false to skip the resumed email and text. |
| cancel | None | Cancels right away. There is no cancel at the end of the period. A subscription that is already cancelled stays as it is. |
| skip\_next | next\_charge\_at (from the subscription) | Skips that charge. Keep the same value on a retry. |
| restore\_skipped\_order | scheduled\_at (from skipped\_orders) | Brings a skipped order back. If it comes before the next charge, it becomes the next charge. |
| reschedule\_next\_charge | next\_billing\_date (YYYY-MM-DD) | Moves the next charge and delivery. One-time items on the next order move with it. It doesn't resume a paused subscription. |
| update\_quantity | line\_id, quantity | Sets how many of one item every later order gets. |
| swap\_product | replacements: \[{ line\_id, variant\_id, expected\_unit\_price, currency, expected\_quantity }\] | Swaps the product on one or more items, keeping quantity, cadence, next charge date and plan. Copy the values from swap options. |
| remove\_item | line\_id | Removes an item from every later order. The last item can't be removed; cancel instead. |
| change\_next\_order\_item | billing\_occurrence: { cycle\_index, scheduled\_at }, line\_id, and quantity or remove: true | Changes one item on the next order only. remove works for a one-time item; the only item on an order can't be removed. |
| update\_frequency | interval (day, week, month or year), interval\_count | Changes how often it bills and delivers. Both move together. |
| update\_shipping\_address | address: { firstName, lastName, address1, address2, city, company, provinceCode, zip, countryCode, phone } | Sets the delivery address. Street and country are required. |
| apply\_discount | discount\_code | Applies a discount code to upcoming charges. Shopify checks the code; a code it refuses changes nothing. |
| request\_payment\_method\_update | None | Shopify emails the customer a secure link to update the card that pays for it. A retry with the same Idempotency-Key doesn't send again. |

Dates are YYYY-MM-DD. `line_id` comes from the subscription's `items`, upcoming orders or swap options. The customer gets your store's emails and texts for pauses, resumes, skips, swaps and cancellations, as your [notifications](https://chargezen.com/docs/subscriptions/notifications) are set up.

## What a change answers

A change answers with what Shopify confirmed: the subscription's `id`, its `status` and the facts that changed.

POST .../update\_quantity

```bash
curl -X POST "https://api.chargezen.com/v1/customers/8f14e45f-ceea-467f-a0e6-0e1c2f4b9d3a/subscriptions/48213/update_quantity" \
  -H "X-Chargezen-Key-Id: $CHARGEZEN_KEY_ID" \
  -H "Authorization: Bearer $CHARGEZEN_SECRET" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "line_id": "gid://shopify/SubscriptionLine/77104", "quantity": 3 }'

{
  "provider": "internal",
  "subscription": {
    "id": "48213",
    "shopify_id": "30971223344",
    "provider": "internal",
    "status": "ACTIVE",
    "line": { "id": "gid://shopify/SubscriptionLine/77104", "quantity": 3 }
  }
}
```

Use the change's response, not a read right after it

Reading the subscription right after a change can show the old values for a few seconds while Chargezen's stored copy catches up. The change's own response is what Shopify confirmed. In it, `status` is Shopify's spelling in capitals (`PAUSED`); reads show it in lower case.

## Skip the next charge

POST .../skip\_next

```bash
curl -X POST "https://api.chargezen.com/v1/customers/8f14e45f-ceea-467f-a0e6-0e1c2f4b9d3a/subscriptions/48213/skip_next" \
  -H "X-Chargezen-Key-Id: $CHARGEZEN_KEY_ID" \
  -H "Authorization: Bearer $CHARGEZEN_SECRET" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "next_charge_at": "2026-12-02T00:00:00Z" }'
```

## Swap a product

List swap options first, then send the replacement you chose: the item's `line_id`, and the replacement's `variant_id`, `unit_price` as `expected_unit_price`, `currency` and `quantity` as `expected_quantity`. If the price or availability changed since you listed them, nothing changes and you get `SUBSCRIPTION_SWAP_PRICE_CHANGED` or `SUBSCRIPTION_SWAP_OPTION_UNAVAILABLE`.

POST .../swap\_product

```bash
curl -X POST "https://api.chargezen.com/v1/customers/8f14e45f-ceea-467f-a0e6-0e1c2f4b9d3a/subscriptions/48213/swap_product" \
  -H "X-Chargezen-Key-Id: $CHARGEZEN_KEY_ID" \
  -H "Authorization: Bearer $CHARGEZEN_SECRET" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "replacements": [
      { "line_id": "gid://shopify/SubscriptionLine/77104", "variant_id": "44120",
        "expected_unit_price": "18.0", "currency": "USD", "expected_quantity": 2 }
    ]
  }'
```

## Change an item on the next order only

Take `cycle_index` and `scheduled_at` from the first order in upcoming orders. Every later order stays the same.

POST .../change\_next\_order\_item

```bash
curl -X POST "https://api.chargezen.com/v1/customers/8f14e45f-ceea-467f-a0e6-0e1c2f4b9d3a/subscriptions/48213/change_next_order_item" \
  -H "X-Chargezen-Key-Id: $CHARGEZEN_KEY_ID" \
  -H "Authorization: Bearer $CHARGEZEN_SECRET" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "billing_occurrence": { "cycle_index": 4, "scheduled_at": "2026-12-02T00:00:00Z" },
    "line_id": "gid://shopify/SubscriptionLine/77104",
    "quantity": 1
  }'
```

## Change the delivery address

POST .../update\_shipping\_address

```bash
curl -X POST "https://api.chargezen.com/v1/customers/8f14e45f-ceea-467f-a0e6-0e1c2f4b9d3a/subscriptions/48213/update_shipping_address" \
  -H "X-Chargezen-Key-Id: $CHARGEZEN_KEY_ID" \
  -H "Authorization: Bearer $CHARGEZEN_SECRET" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "address": { "firstName": "Ada", "lastName": "Lovelace", "address1": "40 Oak Ave", "city": "Austin",
                 "provinceCode": "TX", "zip": "78702", "countryCode": "US" }
  }'
```

### Related Articles

[

#### Reading subscriptions

Where line\_id, next\_charge\_at and orders come from



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

#### Order now

Charge and place the next order early



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

#### Errors and retries

Refusals and when to retry



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

Was this page helpful?

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