Guides

Quick Start: Your First Subscription

Create your first subscription end-to-end with the minimum required fields, so you can test the flow in just a few minutes.

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.

🚧

Before proceeding, decide which integration flow works for you and then follow the appropriate steps below:

Option A: Capture a customer's payment method, then create the subscription with the payment method details included to create and activate the subscription in one step.

Option B: Create subscription details first, then capture a customer's payment method and add it to the subscription. The integration of subscriptions with Acquired's Components payment-session ensures that the initial payment and free trial configuration always match the subscription details. Customer drop-off during the check out phase may result in orphaned subscription entries in the Acquired system.

Option A: Capture payment method, then create and activate subscription

Step 2: Capture customer's payment method details

Choose your integration method

Acquired offers a variety of integration options for capturing payment method details and taking payments from customers. See our Integration Options guide for more details.

Authorise a payment method

Once you have selected an integration option, you need to authorise a payment method to take future subscription payments from.

Create a Hosted Checkout payment-link or a Components payment-session with payment details that match the subscription the customer is checking out for.

  • Recurring should always be set to true on the request, via the is_recurring: true boolean
  • If a free trial is offered, the first payment should be a zero value authorisation with amount: 0, and capture: false
  • If an upfront payment is being taken, then capture: true to ensure funds are captured

When the payment session has completed successfully, store the payment_method_id (e.g.: card_id) and the transaction_id for the next step of creating and activating a subscription for the customer.

Step 3: Create and activate a subscription with payment method included

Submit a POST request to the Create Subscription /subscriptions endpoint with the customer, product, and price details.

If you include payment_methods in the request, the subscription is created and billing begins immediately. The first bill will be created in status: draft and due date set as per the subscription details.

If you include transaction_idof the first payment in the request (within the payment_methods object), when the subscription is created then the first bill will be created and marked as paid automatically, and the next bill will be created in status: draft and due date set as per the subscription details.

/subscriptions request

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

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.

{
  "customer": {
    "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"
}

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: Create subscription, then capture payment method and use to activate subscription

Step 2: Create a subscription

Submit a POST request to the Create Subscription 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.

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

Create Subscriptions /subscriptions request:

{
  "customer": {
    "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 with status: incomplete.

Step 3: Capturing payment methods and activating subscription

To start billing, you must activate a subscription.

Supplying payment methods via the Activate Subscription 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 in draft status. See the Bills guide for more details.

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

Supplying payment methods via 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.

Step 4: Verify the subscription

Retrieve the subscription to confirm it was created successfully:

GET /subscriptions/{subscription_id} response:

{
  "id": "01HNY4G8G5ZMAXQB8T0Z1Y1ZMW",
  "status": "active",
  "customer": {
    "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.