---
title: "List all subscriptions"
method: GET
path: "/subscriptions"
tags: ["Subscriptions"]
---

# List all subscriptions

`GET /subscriptions`

Returns a paginated list of subscriptions.

## Query parameters

- `customer_id` string, uuid
- `status` 'trialing' | 'active' | 'incomplete' | 'paused' | 'cancelled' | 'past_due'
- `offset` integer
- `limit` integer
- `expand` string

## Response `200`

List of subscriptions.

- SubscriptionListPaged
  - `meta` object
    - `count` integer — The number of records returned as part of the response.
    - `offset` integer — The starting record number.
    - `limit` integer — The maximum number of records that can be returned as part of the response.
    - `total` integer — The total number of records contained in the query response.
    - `links` object[]
      - `rel` 'self' | 'first' | 'last' | 'prev' | 'next'
      - `href` string — Link to the resource which should be appended to base URL.
      - `title` string — Description of the link.
  - `data` 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

---

[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)