Billing a different product each cycle
A sequenced price is a recurring price that bills a different product on each renewal, in an order you set. Use it when a subscription ships something different each time: box A in cycles 1, 3, 5… and box B in cycles 2, 4, 6…, or a rotation of three or more products.
You sell it like any recurring price. The customer buys the first price of the sequence, and ODUS bills the next product in the sequence on every renewal, repeating from the start after the last one.
Creating a sequenced price
Create the products first, one per step. Then send a
POST /v2/prices request for the first cycle's price
with followedBy, the products of the later cycles in order:
POST /v2/prices
{
"name": "Monthly box",
"type": "recurring",
"currency": "usd",
"amount": 3000,
"product": "prod_2QGNGy637hJ9MnD5cK7thAjSvPV",
"recurringSchedule": {
"intervalUnit": "month",
"intervalCount": 1
},
"followedBy": [{ "product": "prod_2R4dnVpZ3MfP8xLqK1wTzY6bHcN", "amount": 2000 }]
}
Each entry of followedBy takes:
product— the product that cycle bills. Required.amount— what that cycle charges, in the smallest currency unit. Defaults to theamountof the first price.name— the name of that step's price. Defaults to thenameof the first price.
Each entry becomes a price of its own, created together with the first one. It copies the first
price's currency, quantity, recurringSchedule and metadata. A sequence has at most 24 prices,
the first included, so followedBy takes 1 to 23 entries.
followedBy works only on a recurring price that uses recurringSchedule. A request that sends it
with billingSchedule, or on a one_time price, is refused.
The response is the first price, with sequence listing every price in order:
{
"id": "price_2R4e1fLm8QwBzT3vX9kPnY2aHdS",
"name": "Monthly box",
"type": "recurring",
"amount": 3000,
"sequenceParent": null,
"sequencePosition": null,
"sequence": [
{
"position": 1,
"price": "price_2R4e1fLm8QwBzT3vX9kPnY2aHdS",
"product": "prod_2QGNGy637hJ9MnD5cK7thAjSvPV",
"amount": 3000
},
{
"position": 2,
"price": "price_2R4e2xDqbww8ewmkIYWE1A6Zcfp",
"product": "prod_2R4dnVpZ3MfP8xLqK1wTzY6bHcN",
"amount": 2000
}
]
}
The other fields are those of any price; see the
POST /v2/prices reference.
Selling it
Put the first price in the cart of the payment that starts the subscription, as with any recurring price. See Creating subscriptions.
A later step's price is refused in a cart you send, as the price of a new subscription, and as the
new price of a plan change. The error names the first price to use instead. The one exception is a
renewal payment you create yourself with offSessionType: "recurring": its cart can name the step
that cycle bills.
What each renewal bills
The first cycle bills the first price. Each renewal bills the next price in sequence, and after the
last one the sequence starts again with the first. For the two-step price above:
| Cycle | Price billed | Product | Amount |
|---|---|---|---|
| 1 | position 1 | prod_2QGNGy637hJ9MnD5cK7thAjSvPV | 3000 |
| 2 | position 2 | prod_2R4dnVpZ3MfP8xLqK1wTzY6bHcN | 2000 |
| 3 | position 1 | prod_2QGNGy637hJ9MnD5cK7thAjSvPV | 3000 |
| 4 | position 2 | prod_2R4dnVpZ3MfP8xLqK1wTzY6bHcN | 2000 |
In general, cycle n bills position ((n − 1) mod length) + 1, where length is the number of
prices in sequence.
The renewal payment's line item names the price and product of the cycle it bills, so a renewal reaches your fulfillment, Order Management included, with the product to ship. A retry of a failed renewal keeps the product and amount of its first attempt.
The subscription's price stays the first price for its whole life. Read the renewal payment's line
item, not the subscription, to know which product a cycle bills.
If the price has a trial, the trial cycle charges the trial amount, as for any recurring price.
The steps take no trial of their own.
Changing a subscription onto a sequenced price
When you update a subscription's plan to a sequenced price, its next cycle bills the first price of the sequence, and the renewals after it continue from there.
Finding the prices of a sequence
GET /v2/prices lists every price, the
steps included. A step has sequenceParent, the ID of the first price, and sequencePosition, its
place from 2. Both are null on every other price, the first price of a sequence included.
Filter on sequenceParent to choose which you get:
GET /v2/prices?sequenceParent[eq]=null
GET /v2/prices?sequenceParent[eq]=price_2R4e1fLm8QwBzT3vX9kPnY2aHdS
An integration that lists prices to show customers what they can buy now also receives the steps of
every sequenced price. Add sequenceParent[eq]=null to that request, or a customer can be offered a
price that is then refused at checkout.
GET /v2/prices/{id} on the first price returns its
sequence. On a step, and on a price that is not sequenced, sequence is null.
The price webhook events, such as price.created, carry sequenceParent and sequencePosition too.
Changing or removing a sequence
The products and their order are fixed once the price is created. On any price in a sequence you can
still change name, amount, active and metadata with
POST /v2/prices/{id}. A request that changes anything
else, such as the product, the schedule or the quantity, is refused. To sell a different sequence,
create a new price and move subscriptions to it with a plan change.
To delete a sequence, delete its first price with
POST /v2/prices/{id}/delete: its steps are deleted
with it. A step cannot be deleted on its own, and a sequence cannot be deleted once any of its prices
has been used in a payment. To stop selling it instead, set active to false on the first price.
That hides it in the Dashboard, but the API still accepts it, so also take it out of anything your
integration offers customers. To list only prices still on sale, add active[eq]=true to the
GET /v2/prices request.