# Billing a different product each cycle

> These are the ODUS guides for Core API v2. Core API v1 was retired on 4 November 2026: its endpoints, under /v1 or unprefixed, now answer 410 Gone with code api\_version\_sunset, and Checkout SDK versions before 1.12.0, which call them, no longer work. See [Upgrading from v1 to v2](https://docs.odus.com/docs/guides/upgrading/v1-to-v2.md). Every page is listed in [llms.txt](https://docs.odus.com/llms.txt). To read your own ODUS data, [connect your AI assistant to the ODUS MCP server](https://docs.odus.com/docs/guides/ai-connector.md).

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`](https://docs.odus.com/docs/api/core/v2/price-controller-create) 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`](https://docs.odus.com/docs/api/core/v2/price-controller-create) 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](https://docs.odus.com/docs/guides/subscriptions/creating-subscriptions.md).

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](https://docs.odus.com/docs/guides/order-management/.md) 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](https://docs.odus.com/docs/guides/subscriptions/updating-plans.md) 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`](https://docs.odus.com/docs/api/core/v2/price-controller-find-all-paginated) 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}`](https://docs.odus.com/docs/api/core/v2/price-controller-find-one) 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}`](https://docs.odus.com/docs/api/core/v2/price-controller-update). 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`](https://docs.odus.com/docs/api/core/v2/price-controller-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.
