---
title: "List promotion codes"
method: GET
path: "/v1/promotion-codes"
tags: ["Coupons > Promotion codes"]
---

# List promotion codes

`GET /v1/promotion-codes`

Retrieve existing promotion codes.

## Query parameters

- `take` number, nullable
- `skip` number, nullable
- `coupon_id` string
- `coupon_id__not` string
- `coupon_id__isNull` string
- `coupon_id__isNotNull` string
- `coupon_id__equals` string
- `coupon_id__contains` string
- `coupon_id__startsWith` string
- `coupon_id__endWith` string

## Response `200`

- PaginatedPromotionCode
  - `meta` object, required
    - `total` number, required — Total of existing items.
    - `taken` number, required — Number of items returned.
    - `skipped` number, required — Number of items skipped.
  - `data` object[], required — List of PromotionCode.
    - `id` string, required — Promotion code ID.
    - `code` string, required — Promotion code.
    - `coupon_id` string, required — Coupon ID.
    - `client_id` string, required — Client ID.
    - `customer_id` string, nullable, required — If a `customer_id` is set, this promotion code will only be available to this customer.
    - `plan_id` string, nullable, required — If a `plan_id` is set, this promotion code will only be available for subscriptions with this plan ID.
    - `product_id` string, nullable, required — If a `product_id` is set, this promotion code will only be available for subscriptions with this product ID.
    - `created_at` string, date-time, required — Promotion code creation date. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
    - `updated_at` string, date-time, required — Promotion code last edition date. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
    - `expires_at` string, date-time, nullable, required — Date and time when the promotion code expires.
    - `max_redemptions` number, nullable, required — Maximum number of redemptions for the promotion code. Independent from coupon's max redemptions.
    - `current_redemptions` number, nullable, required — Current number of redemptions for the promotion code.
    - `duration_count` number, nullable, required — Duration count applied to the subscription for the promotion code. 0 or null for `once`
    - `duration_period` 'once' | 'days' | 'weeks' | 'months' | 'years', nullable, required — Duration period applied to the subscription for the promotion code for the promotion code. Valid values are `once`, `days`, `weeks`, `months`, `years`
    - `only_for_first_time_order` boolean, nullable, required — Whether the promotion code is only for first time orders. Defaults to `false`

---

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