---
title: "Create a subscription"
method: POST
path: "/subscriptions"
tags: ["Subscriptions"]
---

# Create a subscription

`POST /subscriptions`

Creates a new subscription.

## Query parameters

- `expand` string

## Request body

- SubscriptionCreate
  - `customer` object, required — The customer to associate with this subscription.
    - `customer_id` string, uuid, required — Unique ID assigned by Acquired to the customer when it is created.
  - `product` ProductCreateInline, required
    - `name` string, required — Display name for the product the subscription bills against.
    - `description` string, required — Longer-form description of the product.
  - `price` PriceCreate, required
    - `usage_type` 'fixed' | 'instalment' — - `fixed`: Standard recurring billing. `amount` is required. - `instalment`: Per-cycle amounts. `cycles` is required.
    - `amount` number, nullable — The recurring amount in major currency units. Required if usage_type is 'fixed'. Ignored if 'instalment'.
    - `cycles` PriceCycle[], nullable — Required if usage_type is 'instalment'. Defines the amount for each specific cycle (0-indexed).
      - `cycle` integer, required — The specific cycle sequence number (0-indexed). 0 represents the first bill.
      - `amount` number, required — The amount to bill for this specific cycle in major currency units.
    - `cycle_details` PriceCycleDetails, required — Details regarding the frequency and duration of the billing cycles.
      - `interval` 'day' | 'week' | 'month' | 'year', required — The unit of time for the billing cycle.
      - `interval_count` integer, required — The number of intervals between billing cycles.
      - `limit` integer, nullable — Total number of billing cycles before the subscription ends.
    - `currency` 'GBP' | 'USD' | 'EUR', required — The currency this price is denominated in.
  - `payment_methods` SubscriptionPaymentMethod[], nullable
    - `type` string, required — The kind of payment method, e.g. `card`.
    - `payment_method_id` string, required — Unique ID associated to a payment method within Acquired system, e.g.: card ID.
    - `is_primary` boolean, required — Whether this is the primary payment method used to bill the subscription. Exactly one payment method must be marked primary.
    - `transaction_id` string, uuid, nullable — Transaction ID from a previous payment. If provided on the primary payment method during creation, the first bill is marked as prepaid.
  - `trial_end` string, date-time, nullable — Set a specific date for the trial to end.
  - `transaction` object, nullable — Custom transaction data associated with the subscription. Passed through on each payment attempt.
    - `custom_data` string, nullable — Custom data. Must be a valid Base64 encoded string.
    - `custom1` string, nullable — Custom field 1.
    - `custom2` string, nullable — Custom field 2.
  - `payment` object, nullable — Payment configuration for the subscription.
    - `reference` string, nullable — Merchant payment reference passed to the payment gateway on each payment attempt. Maximum 18 characters. For a subscription with a free trial, the first bill charged after the trial ends automatically carries a `-Trial` suffix on this reference (to satisfy the card scheme's trial-end descriptor requirement). If the reference is longer than 12 characters it is truncated to 12 before the suffix is appended, keeping the result within the 18-character limit. The suffix applies only to that first post-trial bill — not to renewals, retries, or prepaid first bills.
  - `payment_failure_configuration` object, nullable — Opt-in configuration for how the subscription responds to failed bill payments. Controls automated payment recovery and, optionally, auto-cancellation after consecutive failures.
    - `recovery_strategy` string, nullable — Enrols the subscription in automated payment recovery using the named recovery strategy. When a bill payment fails, Acquired retries it on the schedule defined by the strategy. Omit, or send `none`, to leave the subscription unenrolled (failed payments are not automatically retried). Valid strategy names are provided to you as part of onboarding.
    - `incomplete_bills_before_cancellation` integer, nullable — Opt-in auto-cancellation threshold. When set, the subscription is automatically cancelled once this many consecutive most-recent bills are unpaid: before a new bill is charged the preceding bills are checked, and if all remain incomplete the new bill is voided and the subscription cancelled. Must be greater than or equal to 1. Omit to disable auto-cancellation. Can only be set at creation.
  - `webhook_url` string, nullable — URL for receiving status update callbacks when bill payment status changes.
  - `coupon_id` string, nullable — Apply a coupon at creation time. The coupon must be active and, for fixed_amount discounts, its currency must match the price currency.

## Response `200`

Subscription Created

- Subscription
  - `id` string, required — Unique ID assigned by Acquired to the subscription when it is created.
  - `status` 'trialing' | 'active' | 'incomplete' | 'paused' | 'cancelled' | 'past_due', required — Current lifecycle status of the subscription.
  - `customer` object, required — The customer associated with this subscription.
    - `customer_id` string, uuid, required — Unique ID assigned by Acquired to the customer.
  - `payment_methods` SubscriptionPaymentMethod[], nullable
    - `type` string, required — The kind of payment method, e.g. `card`.
    - `payment_method_id` string, required — Unique ID associated to a payment method within Acquired system, e.g.: card ID.
    - `is_primary` boolean, required — Whether this is the primary payment method used to bill the subscription. Exactly one payment method must be marked primary.
    - `transaction_id` string, uuid, nullable — Transaction ID from a previous payment. If provided on the primary payment method during creation, the first bill is marked as prepaid.
  - `product` union — The product associated with the subscription. **Expandable**: By default, this returns an object with only the `product_id`. Use the `expand` query parameter to include the full product object.
    - ProductRef — A reference to a product, containing only the product ID.
      - `product_id` string, required — Unique ID assigned by Acquired to the product.
    - ProductBase
      - `product_id` string, required — Unique ID assigned by Acquired to the product.
      - `name` string, required — Display name for the product.
      - `description` string, required — Longer-form description of the product.
      - `created_at` string, date-time, required — When the product was created.
  - `price` union — The price associated with the subscription. **Expandable**: By default, this returns an object with only the `price_id`. Use the `expand` query parameter to include the full price object.
    - PriceRef — A reference to a price, containing only the price ID.
      - `price_id` string, required — Unique ID assigned by Acquired to the price.
    - PriceBase
      - `price_id` string, required — Unique ID assigned by Acquired to the price.
      - `product_id` string, required — ID of the product this price belongs to.
      - `usage_type` 'fixed' | 'instalment', required — - `fixed`: Standard recurring billing. `amount` is required. - `instalment`: Instalment pricing for complex billing (e.g., Loans). `cycles` is required.
      - `amount` number, nullable — The recurring amount in major currency units for 'fixed' prices. Null if 'instalment'.
      - `cycles` PriceCycle[], nullable — A list of specific amounts per cycle. Required if usage_type is 'instalment'.
        - `cycle` integer, required — The specific cycle sequence number (0-indexed). 0 represents the first bill.
        - `amount` number, required — The amount to bill for this specific cycle in major currency units.
      - `cycle_details` PriceCycleDetails, required — Details regarding the frequency and duration of the billing cycles.
        - `interval` 'day' | 'week' | 'month' | 'year', required — The unit of time for the billing cycle.
        - `interval_count` integer, required — The number of intervals between billing cycles.
        - `limit` integer, nullable — Total number of billing cycles before the subscription ends.
      - `currency` 'GBP' | 'USD' | 'EUR', required — The currency this price is denominated in.
      - `created_at` string, date-time, required — When the price was created.
  - `discount` union — The discount applied to the subscription, if any. **Expandable**: By default, this returns an object with only the `coupon_id`. Use the `expand` query parameter to include the full discount object.
    - DiscountRef — A reference to a discount, containing only the coupon ID.
      - `coupon_id` string, required — ID of the coupon that defines this discount.
    - DiscountBase
      - `coupon_id` string, required — ID of the coupon that defines this discount.
      - `discount_type` 'percentage' | 'fixed_amount', required — Whether the discount applies a `percentage` or `fixed_amount` reduction.
      - `value` number, required — The discount value. For percentage: 20 = 20%. For fixed_amount: 5.00 = 5.00 in the subscription currency.
      - `remaining_cycles` integer, nullable — Number of remaining billing cycles the discount applies to. Null for 'forever' duration.
      - `applied_at` string, date-time, required — When the discount was applied to the subscription.
      - `effective_from` string, date-time, required — When the discount becomes active. Can be in the future for scheduled activation.
      - `end_date` string, date-time, nullable — When the discount expires.
  - `start_date` string, date-time, nullable — When the subscription was first activated. Null while the subscription is incomplete.
  - `trial_end` string, date-time, nullable — If set, the subscription is in 'trialing' status until this date.
  - `cancel_at_period_end` boolean, required — True when the subscription is scheduled to cancel when the next bill becomes due.
  - `transaction` object, nullable — Custom transaction data associated with the subscription.
    - `custom_data` string, nullable — Custom data. Base64 encoded string.
    - `custom1` string, nullable — Custom field 1.
    - `custom2` string, nullable — Custom field 2.
  - `payment` object, nullable — Payment configuration for the subscription.
    - `reference` string, nullable — Merchant payment reference. Passed to the payment gateway on each recurring payment attempt.
  - `payment_failure_configuration` object, required — The subscription's configuration for handling failed bill payments. Always present in the response; `recovery_strategy` is `none` when the subscription is not enrolled.
    - `recovery_strategy` string — The name of the recovery strategy the subscription is enrolled in. Returns `none` when the subscription is not enrolled in automated payment recovery.
    - `incomplete_bills_before_cancellation` integer, nullable — The number of consecutive unpaid bills after which the subscription is automatically cancelled. Null when auto-cancellation is not configured.
  - `webhook_url` string, nullable — URL for receiving status update callbacks when bill payment status changes.
  - `created_at` string, date-time, required — When the subscription record was created.
  - `links` object[], required
    - `rel` 'self' | 'customer'
    - `href` string — Link to the resource which should be appended to base URL.
    - `method` string — The HTTP method to use with the link.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `404` — Not Found — customer not found, or a `coupon_id` was supplied but the coupon was not found.

---

[API](https://skmtc.dev/acquired/apis/acquired-api.md) · [All operations](https://skmtc.dev/acquired/apis/acquired-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/acquired/acquired-api/revisions/7ae178a046f2/schema)