---
title: "List coupons"
method: GET
path: "/coupons"
tags: ["Coupon"]
---

# List coupons

`GET /coupons`

This endpoint returns a list of all coupons for an account in a list format.

The list of coupons is ordered starting from the most recently created coupon. The response also includes
`pagination_metadata`, which lets the caller retrieve the next page of results if they exist.

## Query parameters

- `limit` integer — The number of items to fetch. Defaults to 20.
- `cursor` string, nullable — Cursor for pagination. This can be populated by the `next_cursor` value returned from the initial request.
- `show_archived` boolean, nullable — Show archived coupons as well (by default, this endpoint only returns active coupons).
- `redemption_code` string, nullable — Filter to coupons matching this redemption code.

## Response `200`

OK

- Coupons
  - `data` Coupon[], required
    - `id` string, required — Also referred to as coupon_id in this documentation.
    - `redemption_code` string, required — This string can be used to redeem this coupon for a given subscription.
    - `discount` union, required
      - PercentageDiscount
        - `discount_type` 'percentage', required
        - `applies_to_price_ids` string[], nullable — List of price_ids that this discount applies to. For plan/plan phase discounts, this can be a subset of prices.
        - `filters` PriceFilter[], nullable — The filters that determine which prices to apply this discount to.
          - `field` 'price_id' | 'item_id' | 'price_type' | 'currency' | 'pricing_unit_id', required — The property of the price to filter on.
          - `operator` 'includes' | 'excludes', required — Should prices that match the filter be included or excluded.
          - `values` string[], required — The IDs or values that match this filter.
        - `reason` string, nullable
        - `percentage_discount` number, required — Only available if discount_type is `percentage`. This is a number between 0 and 1.
      - AmountDiscount
        - `discount_type` 'amount', required
        - `applies_to_price_ids` string[], nullable — List of price_ids that this discount applies to. For plan/plan phase discounts, this can be a subset of prices.
        - `filters` PriceFilter[], nullable — The filters that determine which prices to apply this discount to.
          - `field` 'price_id' | 'item_id' | 'price_type' | 'currency' | 'pricing_unit_id', required — The property of the price to filter on.
          - `operator` 'includes' | 'excludes', required — Should prices that match the filter be included or excluded.
          - `values` string[], required — The IDs or values that match this filter.
        - `reason` string, nullable
        - `amount_discount` string, required — Only available if discount_type is `amount`.
    - `times_redeemed` integer, required — The number of times this coupon has been redeemed.
    - `duration_in_months` integer, nullable, required — This allows for a coupon's discount to apply for a limited time (determined in months); a `null` value here means "unlimited time".
    - `max_redemptions` integer, nullable, required — The maximum number of redemptions allowed for this coupon before it is exhausted; `null` here means "unlimited".
    - `archived_at` string, date-time, nullable, required — An archived coupon can no longer be redeemed. Active coupons will have a value of null for `archived_at`; this field will be non-null for archived coupons.
  - `pagination_metadata` PaginationMetadata, required
    - `has_more` boolean, required
    - `next_cursor` string, nullable, required

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `404` — Not Found
- `409` — Conflict
- `413` — Content Too Large
- `429` — Too Many Requests
- `500` — Internal Server Error

---

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