Skip to navigation
REST RPC APISubscriptions

Upgrade Subscription To Prepaid

View as Markdown

Upgrades a pay-as-you-go subscription to a prepaid subscription.

Returns 400, with the reason in detail, when the merchant doesn’t have prepaid subscriptions enabled, the subscription is already prepaid or isn’t live, orders_per_billing is missing or less than 2, or the subscription’s product isn’t prepaid-eligible (in the prepaid eligibility product group).

The upgraded subscription starts with prepaid_orders_remaining at 0, so its next order is a renewal. That order is repriced right away to orders_per_billing times the unit price, and the customer pays for the full prepaid cycle when it’s placed. Because the customer never receives an order they haven’t paid for, the upgrade can be offered directly in the Subscription Manager. If renewal_behavior is omitted, the merchant’s default renewal behavior applies, or autorenew if none is set.

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

Number of orders per prepaid billing cycle. Must be at least 2.

renewal_behaviorenumOptionalDefaults to autorenew
Allowed values:
offerstringOptional

Public ID of the offer to associate the subscription with after the upgrade, or live for the merchant’s currently live offer. When omitted, the subscription keeps its current offer.

Response

200
customerstringOptional
merchantstringOptional
productstringOptional
paymentstringOptional
shipping_addressstringOptional
offerstringOptional
subscription_typestringOptional
raw_subscription_typestringOptional
componentslist of objectsOptional
extra_dataobjectOptional
public_idstringOptional
quantityintegerOptionalDefaults to 0
pricestring or nullOptional
frequency_daysintegerOptionalDefaults to 0
reminder_daysintegerOptionalDefaults to 0
everyintegerOptionalDefaults to 0
every_periodintegerOptionalDefaults to 0
start_datestringOptional
cancelledstring or nullOptional
cancel_reasonstring or nullOptional
iterationanyOptional
sequenceanyOptional
session_idstringOptional
merchant_order_idstringOptional
createdstringOptional
updatedstringOptional
livebooleanOptionalDefaults to true
external_idstringOptional
product_attributeanyOptional
cancel_reason_codeinteger or nullOptional
customer_repinteger or nullOptional
clubanyOptional
queued_actionslist of objectsOptional
prepaid_subscription_contextobjectOptional

Errors

400
Bad Request Error