Skip to main content
View as Markdown
Version: v2

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 the amount of the first price.
  • name — the name of that step's price. Defaults to the name of 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:

CyclePrice billedProductAmount
1position 1prod_2QGNGy637hJ9MnD5cK7thAjSvPV3000
2position 2prod_2R4dnVpZ3MfP8xLqK1wTzY6bHcN2000
3position 1prod_2QGNGy637hJ9MnD5cK7thAjSvPV3000
4position 2prod_2R4dnVpZ3MfP8xLqK1wTzY6bHcN2000

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:

Only prices a customer can buy: steps left out
GET /v2/prices?sequenceParent[eq]=null
The later steps of one sequence
GET /v2/prices?sequenceParent[eq]=price_2R4e1fLm8QwBzT3vX9kPnY2aHdS
warning

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.