Advanced SubscriptionsPrepaid Subscriptions

Prepaid Subscriptions Overview

How prepaid subscription data is represented on a subscription, and what each field means
View as Markdown

A prepaid subscription bills the customer for several shipments at once, then delivers those shipments without charging again until the cycle renews.

Once prepaid subscriptions are enabled for your store, you can use the prepaid endpoints to read and control them.

Prepaid subscription data

Subscription objects carry a prepaid_subscription_context field describing what the customer prepaid for. On a subscription that isn’t prepaid, the field is null.

FieldTypeDescription
prepaid_orders_remainingintegerHow many shipments the customer is still owed before the subscription renews. When this reaches 0, the next order containing an item for this subscription renews it.
prepaid_orders_per_billingintegerThe length of the prepaid cycle, counted in shipments per charge. A value of 3 means the customer is billed for three shipments each time they’re charged, and receives the remaining two at no further charge.
renewal_behaviorstringWhat happens once the customer has received their last prepaid shipment. See Managing Prepaid Renewal Behaviors.
last_renewal_revenuefloatHow much the customer paid in the most recent prepaid renewal order. That order is either the checkout order that captured the initial funds, or a later prepaid renewal order.
prepaid_origin_merchant_order_idstringThe merchant order ID — your ecommerce platform’s order ID — for the order that captured the funds for the current prepaid cycle.

Renewal behavior

renewal_behavior takes one of three values:

  • autorenew — bills the customer for a full prepaid cycle once all orders are placed. The renewal happens when the first order of the next cycle is placed.
  • cancel — cancels the subscription once all orders are placed. Customers can reactivate it to start a new prepaid cycle.
  • downgrade — converts the subscription to a standard subscription once all orders are placed. The next order is priced as a single shipment.

New subscriptions use autorenew unless you’ve changed the default for your store. For how to set a different default, or a custom behavior on an individual subscription, see Managing Prepaid Renewal Behaviors.