# Creating Subscriptions A subscription is not created by calling a dedicated endpoint. Instead, ODUS creates a subscription automatically when a payment that contains a recurring price succeeds. This guide explains how to set up that payment so a subscription is activated for your customer. ## Prerequisites * **A recurring price must exist.** A subscription can only be started from a price with `type: recurring`. If you have not set one up yet, follow [Creating products and prices](https://docs.odus.com/docs/guides/products/creating-products-and-prices.md) first. * **A customer.** The subscription is tied to a customer record. A returning customer already has one. A new customer gets one when they pay through the Checkout SDK — v2 has no endpoint to create a customer yourself. See [Managing customers](https://docs.odus.com/docs/guides/customers/managing-customers.md). ## Step 1: Create a payment with a recurring price Send a [`POST /v2/payments`](https://docs.odus.com/docs/api/core/v2/payment-controller-create) request and include the recurring price as a line item in `cart.items`. For a returning customer, set `customer` to their ID. For a new customer, leave `customer` out: the Checkout SDK collects their details when they pay, and the subscription is created for the customer record made from them. Creating a payment for a subscription ``` { "currency": "usd", "initiator": "customer", "customer": "cus_2R0uWz4tu9wxTMBXxj9CJfSE9vV", "cart": { "items": [ { "price": "price_2R4e2xDqbww8ewmkIYWE1A6Zcfp", "quantity": 1 } ] }, "paymentMethodOptions": { "card": { "mode": "cascade", "cascade": "cas_abc123" } } } ``` The `currency` must match the recurring price's currency. Set `initiator` to `customer` for sign-up flows. The `paymentMethodOptions` specify the gateway or cascade to use. See the [`POST /v2/payments`](https://docs.odus.com/docs/api/core/v2/payment-controller-create) reference for the full parameter list. important The `paymentMethodOptions` you provide here are stored as the subscription's **billing settings**. Every future renewal charge uses the same payment method type, gateway profile, and capture configuration. Set these values carefully. If the customer already has a saved payment method, you can charge it directly without involving the Checkout SDK: Creating a payment using a saved payment method ``` { "currency": "usd", "initiator": "customer", "customer": "cus_2R0uWz4tu9wxTMBXxj9CJfSE9vV", "paymentMethod": "pm_2S1xKp8qF0lA3mNvRt7czWuYhBd", "cart": { "items": [ { "price": "price_2R4e2xDqbww8ewmkIYWE1A6Zcfp", "quantity": 1 } ] }, "paymentMethodOptions": { "card": { "mode": "cascade", "cascade": "cas_abc123" } } } ``` ## Step 2: Authorize the payment After creating the payment, authorize it by sending a [`POST /v2/payments/{id}/authorize`](https://docs.odus.com/docs/api/core/v2/payment-controller-authorize) request. If you are collecting payment details from a new customer (for example, a new card), use the [Checkout SDK](https://docs.odus.com/docs/guides/checkout/drop-in/getting-started.md) to securely collect and submit the payment information. If you are charging a saved payment method directly via the API, include a valid `returnUrl` in case 3DS authentication is required: ``` { "context": { "returnUrl": "https://example.com/return" } } ``` For full details on both authorization paths, see [Making Payments](https://docs.odus.com/docs/guides/payments/making-payments.md). ## What happens after the payment succeeds After the payment succeeds, ODUS automatically: 1. Creates a subscription in `active` status, linked to the customer and the recurring price. 2. Creates a `setup` invoice of type `setup`, already marked as `paid`, linked to the payment. 3. Calculates the first billing period (`currentPeriodStart` and `currentPeriodEnd`) from the price's recurring schedule. 4. Schedules the first automatic renewal. The subscription's `startDate` is set to the moment the subscription was created. It cannot be set in advance through the API. ### When the subscription ID is available ODUS creates the subscription **after** the payment's status changes to `succeeded`, not at the same moment. Each recurring line item in the payment that starts the subscription gets its own subscription, and its ID is then written to that item's `cart.items[].subscription`. This usually happens within a second, but it can take longer. So a payment that is already `succeeded` can still show `subscription: null` on a recurring line item, both in the response that reported the success and in [`GET /v2/payments/{id}`](https://docs.odus.com/docs/api/core/v2/payment-controller-find-one). Only the payment that starts a subscription has its line items linked this way. A renewal payment that ODUS creates for an existing subscription also carries the recurring price in `cart.items`, but its `subscription` stays `null`. Don't treat a missing subscription as a failure on its own A `succeeded` payment with `cart.items[].subscription` still `null` is not by itself an error. Don't create a subscription yourself, retry the payment, or refund it because the field is empty. To get the subscription ID reliably: * **Listen for the [`subscription.active`](https://docs.odus.com/docs/api/core/v2/webhook-subscription-active) webhook.** It is sent once the subscription exists. Match it to the payment with its `setupLineItem` field, which is the ID of the line item in `cart.items[]` that started the subscription. * **Or read the payment again.** If you don't use webhooks, call `GET /v2/payments/{id}` again with increasing delays until every recurring line item has a `subscription`, and stop at a deadline your application sets. If a recurring line item still has no subscription an hour after the payment succeeded, contact ODUS support with the payment ID. Once set, `cart.items[].subscription` does not change. You can retrieve the new subscription by calling [`GET /v2/subscriptions/{id}`](https://docs.odus.com/docs/api/core/v2/subscription-controller-find-one). The `setupInvoice` field on the subscription holds the ID of the first invoice. You can retrieve that invoice using [`GET /v2/invoices/{id}`](https://docs.odus.com/docs/api/core/v2/invoice-controller-find-one) — it includes the associated payment and transaction details. Example response (partial) ``` { "id": "sub_2Q9fNQAs77Fhue9itgVFbUzq8NV", "status": "active", "autoBillingEnabled": true, "startDate": "2026-03-31T09:00:00.000Z", "currentPeriodStart": "2026-03-31T09:00:00.000Z", "currentPeriodEnd": "2026-04-30T09:00:00.000Z", "currentCycle": 1, "setupInvoice": "inv_2Q8mig1bCDKh4UrxAX0o3AHqQi1", "billingSettings": { "paymentMethodType": "card", "gatewayProfile": "gwp_2QUGPTQo8As1cNIvgKlSFDxjJDd", "captureMethod": "automatic" } } ``` ## Viewing the subscription in the Dashboard After the payment succeeds, the new subscription appears in **Subscriptions** in the Dashboard. You can view its status, current billing period, associated invoices, and billing settings from the subscription detail page. ## Next steps To understand what happens after the subscription is created — how it renews, how failures are handled, and what states it moves through — read the [Subscription Lifecycle](https://docs.odus.com/docs/guides/subscriptions/subscription-lifecycle.md) guide.