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": 19.99,
    "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
    }
  ],
  "payment": {
    "reference": "ORDER-12345"
  },
  "webhook_url": "https://example.com/webhooks/billing"
}

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

The transaction, payment, and webhook_url fields are optional. If provided, payment.reference is passed to the payment gateway on each recurring payment attempt, and webhook_url is used for status update callbacks when bill payment status changes.

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": 19.99,
    "currency": "GBP",
    "cycle_details": {
      "interval": "month",
      "interval_count": 1,
      "limit": 12
    }
  },
  "payment": {
    "reference": "ORDER-12345"
  },
  "webhook_url": "https://example.com/webhooks/billing"
}

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,
      "transaction_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }
  ]
}

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 full details on parameter inheritance, capture flag derivation, and validation rules, see the Components Integration 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"
  },
  "payment_methods": [
    {
      "type": "card",
      "payment_method_id": "00cfdbdc-5e81-4ce2-adc1-14920120618f",
      "is_primary": true
    }
  ],
  "product": {
    "id": "01HNY4G8G06M4J4J9P11CR3BCG"
  },
  "price": {
    "id": "01HNY4G8G2WJ6S7G8R9QAF3KZY"
  },
  "start_date": "2025-11-01T09:00:00Z",
  "payment": {
    "reference": "ORDER-12345"
  },
  "webhook_url": "https://example.com/webhooks/billing",
  "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.