Skip to navigation
REST RPC APISubscriptions

Update

View as Markdown

Updates a subscription’s extra_data, price, components, offer and cancel_reason.

Only the Application API Scope can change price, components and offer. With the Storefront API Scope those fields are ignored: the request returns 200 and leaves them unchanged.

New bundle components can’t be changed here: for a subscription to a static or dynamic price bundle, sending components returns 422. Use Update Components instead.

Authentication

x-api-keystring

Application API Scope — server-to-server, sent in the x-api-key header. See Authentication.

OR
authorizationstring

Storefront API Scope — client-side, scoped to one customer, sent as a signature in the authorization header. See Authentication.

Path parameters

subscription_idstringRequired
Unique subscription ID

Request

This endpoint expects an object.
extra_datastringOptionalformat: "json"

JSON object that should be JSON.parse() as key/value store for any extra information.

pricestringOptional

Price, must be in decimal form ex: 10.00

componentslist of anyOptional

Array of JSON objects to set product IDs that are the legacy bundle components. For example: “components”: [ {“product”:“123”}, {“product”:“456”}, {“product”:“789”} ],

offerstringOptional
Public ID of the new offer.
cancel_reasonstringOptional

Pipe-delimited cancel reason code and cancel reason details, e.g. “4|Overstocked”

Response

200
customerstringOptional
merchantstringOptional
productstringOptional
paymentstringOptional
shipping_addressstring or nullOptional
offerstring or nullOptional
offer_profile_public_idstring or nullOptional
Public ID of the offer profile the subscription's offer belongs to. Returned only by List and Retrieve.
subscription_typestringOptional
raw_subscription_typestringOptional

The subscription type as stored. subscription_type reports IU replenishment and CSA replenishment as replenishment; this field keeps the original value.

componentslist of objectsOptional

Bundle components. Each has product; public_id and quantity are returned only when the merchant has multi-item bundles enabled.

extra_dataobjectOptional

Custom data stored on the subscription, as a JSON object. {} when the subscription has none. Ordergroove and your integrations can store their own keys here.

public_idstringOptional
product_attributeinteger or nullOptional
quantityintegerOptional
pricestring or nullOptional
frequency_daysintegerOptional
reminder_daysintegerOptional
everyintegerOptional
every_periodintegerOptional
start_datestringOptional
cancelledstring or nullOptional
cancel_reasonstring or nullOptional
cancel_reason_codeinteger or nullOptional
iterationinteger or nullOptional
sequenceinteger or nullOptional
session_idstringOptional
merchant_order_idstring or nullOptional
customer_repinteger or nullOptional
clubinteger or nullOptional
createdstringOptional
updatedstringOptional
livebooleanOptional
external_idstring or nullOptional
currency_codestring or nullOptional

Three-letter ISO currency code.

queued_actionslist of objectsOptional

Pending queued actions, in order. Returned only when the merchant has queued actions enabled; empty when the subscription isn’t live or has none.

prepaid_subscription_contextobject or nullOptional

Prepaid details. Returned only when the merchant has prepaid subscriptions enabled; null when this subscription isn’t prepaid.

granteeslist of objectsOptional
List of grantees associated with the subscription. Omitted if the subscription has no grantees.
free_trial_subscription_contextobjectOptional

Present only if the subscription has a free trial context (i.e. it was created for a product with a free trial configured); omitted otherwise.

Errors

400
Bad Request Error
403
Forbidden Error
404
Not Found Error