put

Updates mutable fields on an existing subscription: the product variations it bills, its billing schedule, its status, address/billing details, and total amount. Only the fields you include in the request body are changed; omitted fields are left as-is.

Changes to productVariations and schedule take effect on the next renewal. The renewal worker reads the subscription's current productVariations and schedule fresh each time a renewal is generated, so an update made between cycles is applied automatically to the next order — no manual intervention is required. Updating a subscription does not charge the customer; payment is only collected when a renewal order is created.

Request body

All fields are optional. Send only the fields you want to change.

Product variations

productVariations is a full replacement — the array you send becomes the subscription's complete new set of variations. To switch a subscription from one variation to another, send a single-element array containing the new variation.

Each element:

Schedule

The nextPayment date is derived from these fields; you don't set it directly here. To move only the next renewal date without changing cadence, use PUT /v2/ecommerceSubscriptions/{id}/actions/setRenewalDate.

Pricing

When you send productVariations without a totalAmount, the recurring total is recalculated as the sum of pricePerUnitOverride (falling back to the variation's regularPrice) × quantity across all variations. Send an explicit totalAmount to override this.

Common pattern: switching a plan across billing cycles

Because variation changes apply to the next renewal, your system can move a subscription through a pricing progression — for example an introductory variation for the first cycle, a standard variation for subsequent cycles, and later a bundle variation — entirely through this endpoint, without manual intervention.

Switch from an intro variation to the standard variation before the next renewal:

{
  "productVariations": [
    { "variationId": "epvt::sema-month-2plus", "quantity": 1 }
  ]
}

The next renewal order will bill the standard variation. Repeat as needed for later cycles.

Switch to a bundle that also changes billing cadence (e.g. monthly → quarterly):

{
  "productVariations": [
    { "variationId": "epvt::sema-quarterly-bundle", "quantity": 1 }
  ],
  "schedule": {
    "interval": "month",
    "intervalCount": 3
  }
}

If you need the cadence change to take effect from a specific date, follow up with setRenewalDate to align the next renewal.

Response 200

{
  "success": true,
  "message": "Subscription updated successfully",
  "data": {
    "id": "esub::123"
  }
}

To read back the applied product variations and schedule, call GET /v2/ecommerceSubscriptions/{id}.

Errors

Required role

Affiliate token required. The subscription must belong to the authenticated affiliate.