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 must exist. The subscription is tied to a customer record. If you have not created one yet, see Managing customers.

Step 1: Create a payment with a recurring price

Send a POST /payments request and include the recurring price as a line item in cart.items. Set customer to the ID of the customer who will own the subscription.

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

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

You can retrieve the new subscription by calling GET /subscriptions/:id. The setupInvoice field on the subscription holds the ID of the first invoice. You can retrieve that invoice using GET /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.