Changing subscriptions: Subscriptions docs

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

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

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

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

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

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" }
  }'

Changing subscriptions

Every change

What a change answers

Skip the next charge

Swap a product

Change an item on the next order only

Change the delivery address

Related Articles

Reading subscriptions

Order now

Errors and retries