---
title: "List all coupons"
method: GET
path: "/v1/coupons"
---

# List all coupons

`GET /v1/coupons`

Returns a list of your coupons.

## Query parameters

- `created` union
  - object
    - `gt` integer
    - `gte` integer
    - `lt` integer
    - `lte` integer
  - integer
- `ending_before` string
- `expand` string[]
- `limit` integer
- `starting_after` string

## Response `200`

Successful response.

- object
  - `data` Coupon[], required
    - `amount_off` integer, nullable — Amount (in the `currency` specified) that will be taken off the subtotal of any invoices for this customer.
    - `applies_to` CouponAppliesTo
      - `products` string[], required — A list of product IDs this coupon applies to
    - `created` integer, required — Time at which the object was created. Measured in seconds since the Unix epoch.
    - `currency` string, currency, nullable — If `amount_off` has been set, the three-letter [ISO code for the currency](https://stripe.com/docs/currencies) of the amount to take off.
    - `currency_options` object — Coupons defined in each available currency option. Each key must be a three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) and a [supported currency](https://stripe.com/docs/currencies).
    - `duration` 'forever' | 'once' | 'repeating', required — One of `forever`, `once`, or `repeating`. Describes how long a customer who applies this coupon will get the discount.
    - `duration_in_months` integer, nullable — If `duration` is `repeating`, the number of months the coupon applies. Null if coupon `duration` is `forever` or `once`.
    - `id` string, required — Unique identifier for the object.
    - `livemode` boolean, required — Has the value `true` if the object exists in live mode or the value `false` if the object exists in test mode.
    - `max_redemptions` integer, nullable — Maximum number of times this coupon can be redeemed, in total, across all customers, before it is no longer valid.
    - `metadata` object, nullable — Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
    - `name` string, nullable — Name of the coupon displayed to customers on for instance invoices or receipts.
    - `object` 'coupon', required — String representing the object's type. Objects of the same type share the same value.
    - `percent_off` number, nullable — Percent that will be taken off the subtotal of any invoices for this customer for the duration of the coupon. For example, a coupon with percent_off of 50 will make a $ (or local equivalent)100 invoice $ (or local equivalent)50 instead.
    - `redeem_by` integer, nullable — Date after which the coupon can no longer be redeemed.
    - `times_redeemed` integer, required — Number of times this coupon has been applied to a customer.
    - `valid` boolean, required — Taking account of the above properties, whether this coupon can still be applied to a customer.
  - `has_more` boolean, required — True if this list has another page of items after this one that can be fetched.
  - `object` 'list', required — String representing the object's type. Objects of the same type share the same value. Always has the value `list`.
  - `url` string, required — The URL where this list can be accessed.

## Other responses

- `default` — Error response.

---

[API](https://skmtc.net/stainless-api/apis/stripe-api.md) · [All operations](https://skmtc.net/stainless-api/apis/stripe-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/stainless-api/stripe-api/versions/d7db5d2f2f83/schema)