Quick Start: Your First Subscription

This guide walks you through creating your first subscription in just a few steps.

Step 1: Create a customer

Before creating a subscription, you need a customer. Submit a POST request to the /customers endpoint with the associated customer information. For more information, see our customers API reference.

Step 2: Create a subscription

Submit a POST request to the /subscriptions endpoint with the customer, product, and price details. Payment methods are optional at this stage — whether you include them determines the initial status of the subscription.

Option A: With payment methods

If you include payment_methods in the request, the subscription is created as active and billing begins immediately.

/subscriptions request:

{
  "customer_id": "c3e06b6f-bb52-4b2c-81a3-899860652240",
  "product": {
    "name": "Gold Plan",
    "description": "Monthly gold membership"
  },
  "price": {
    "usage_type": "fixed",
    "amount": 1999,
    "currency": "GBP",
    "cycle_details": {
      "interval": "month",
      "interval_count": 1,
      "limit": 12
    }
  },
  "payment_methods": [
    {
      "type": "card",
      "payment_method_id": "00cfdbdc-5e81-4ce2-adc1-14920120618f",
      "is_primary": true
    }
  ]
}

The subscription is created as active and the first bill is generated automatically.

For the quickest way to capture a payment_method_id, use a test card to complete payment via the Virtual Terminal in the Acquired test environment. Ensure the recurring payment journey is followed to save the card_id for future use.

Option B: Without payment methods

If you omit payment_methods, the subscription is created as incomplete. No billing occurs until the subscription is activated.

/subscriptions request:

{
  "customer_id": "c3e06b6f-bb52-4b2c-81a3-899860652240",
  "product": {
    "name": "Gold Plan",
    "description": "Monthly gold membership"
  },
  "price": {
    "usage_type": "fixed",
    "amount": 1999,
    "currency": "GBP",
    "cycle_details": {
      "interval": "month",
      "interval_count": 1,
      "limit": 12
    }
  }
}

The subscription is created as incomplete. To start billing, you must activate it by supplying payment methods via the /subscriptions/{subscription_id}/activate endpoint:

/subscriptions/{subscription_id}/activate request:

{
  "payment_methods": [
    {
      "type": "card",
      "payment_method_id": "00cfdbdc-5e81-4ce2-adc1-14920120618f",
      "is_primary": true
    }
  ]
}

Once activated, the subscription transitions to active and the first bill is created automatically.

For more information on the parameters involved, please refer to our subscriptions API reference.

Step 3: Capture customer's payment method & activate subscription

From a Components /payment-sessions request

When creating a Components /payment-sessions request, add the subscription_id. When the payment session completes successfully, the card_id will automatically be added to the subscription as the payment_method_id and the subscription will be activated.

For more details, see our Components guide.

Free trial period

If the subscription has a free trial period, then the Components /payment-sessions will default to a zero value authorisation (capture: false). When completed successfully, the subscription will be activated with the card_id and the first bill is created automatically.

Upfront payment (no free trial)

If the subscription does not have a free trial period, then the Components /payment-sessions will default to a sale (capture: true). When completed successfully, the subscription will be activated with the card_id, the first bill is created automatically with status paid immediately.

Step 4: Verify the subscription

Retrieve the subscription to confirm it was created successfully:

GET /subscriptions/{subscription_id} response:

{
  "id": "01HNY4G8G5ZMAXQB8T0Z1Y1ZMW",
  "status": "active",
  "customer_id": "c3e06b6f-bb52-4b2c-81a3-899860652240",
  "start_date": "2025-11-01T09:00:00Z",
  "created_at": "2025-11-01T09:00:00Z",
  "links": [
    {
      "rel": "self",
      "href": "/v1/subscriptions/01HNY4G8G5ZMAXQB8T0Z1Y1ZMW"
    },
    {
      "rel": "bills",
      "href": "/v1/subscriptions/01HNY4G8G5ZMAXQB8T0Z1Y1ZMW/bills"
    }
  ]
}

What happens next?

Once active, the subscription handles billing automatically:

• A bill is created for the first billing cycle with a status of draft.
• At the bill's due date, a payment is attempted against the stored payment method.
• If the payment succeeds, the bill transitions to paid and the next bill is created with a status of draft.
• When the cycle limit is reached (12 months in this example), the subscription is automatically cancelled.

To learn more, see Managing Subscriptions and Bills.