Skip to navigation
REST RPC APISubscriptions

Change Product

View as Markdown

Changes the product that the subscription is tied to. Past orders are unchanged; items in unsent orders pick up the new product.

Returns 400 when:

  • product doesn’t exist for the merchant
  • The subscription isn’t live
  • The subscription is prepaid, has prepaid orders remaining, and the new product’s price differs from the current product’s

Merchants can ask Ordergroove support to allow prepaid swaps to a lower-priced product. Swaps to a higher-priced product stay blocked while prepaid orders remain.

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_public_idstringRequired
Unique subscription ID

Request

This endpoint expects an object.
productstringRequired
Product ID

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

403
Forbidden Error
404
Not Found Error