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 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.

Step 1: Create a payment with a recurring price

Send a POST /v2/payments 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 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 request.

If you are collecting payment details from a new customer (for example, a new card), use the Checkout SDK 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.

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}.

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 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}. The setupInvoice field on the subscription holds the ID of the first invoice. You can retrieve that invoice using GET /v2/invoices/{id} — 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 guide.