Get Promotion Codes

Retrieve a list of promotion codes from your store.

Promotion codes are returned newest first. Narrow the list with the optional filters below — for example status=archived to surface archived codes (hidden by default), or discount_type=percent_off to return only percentage discounts. All filters combine with AND.

Request

GET /promotion-codes

Query Parameters

Parameter	Type	Required	Default	Description
`page`	integer	No	1	Page number for pagination
`status`	string	No	—	Filter by status. One of `active`, `inactive`, `expired`, `archived`. Archived codes are excluded from the default list — pass `status=archived` to surface them.
`discount_type`	string	No	—	Filter by discount type. One of `amount_off`, `percent_off`.
`query`	string	No	—	Partial (case-insensitive) match on `code` OR `name`.
`product_id`	string	No	—	Product UUID. Returns product-scoped codes for that product plus all global codes — the natural answer to "which promotion codes apply to product X?".
`created_from`	string	No	—	Only promotion codes created on or after this date (inclusive), `YYYY-MM-DD`.
`created_to`	string	No	—	Only promotion codes created on or before this date (inclusive), `YYYY-MM-DD`.

Omitting a filter or passing it empty means "no filter on that field". Passing a non-empty but unparseable value — an unknown status / discount_type, a malformed date, or a non-UUID product_id — returns a 400 (see Bad Request).

Example Request

curl -X GET "https://cart.easy.tools/api/v1/promotion-codes?status=active&discount_type=percent_off&page=1" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response

Success Response (200)

Returns a paginated list of promotion codes.

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440030",
      "code": "BLACKFRIDAY20",
      "name": "Black Friday 2026",
      "discount_type": "percent_off",
      "amount_off": null,
      "percent_off": 20,
      "currency": null,
      "duration": "once",
      "duration_in_months": null,
      "max_redemptions": 100,
      "times_redeemed": 14,
      "expires_at": "2026-12-31T23:59:59+00:00",
      "first_time_transaction": false,
      "minimum_amount": null,
      "minimum_amount_currency": null,
      "scope": {
        "type": "global"
      },
      "status": "active",
      "created_at": "2026-05-27T10:16:00+00:00",
      "updated_at": "2026-05-27T10:16:00+00:00"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440031",
      "code": "LAUNCH10",
      "name": null,
      "discount_type": "amount_off",
      "amount_off": 1000,
      "percent_off": null,
      "currency": "pln",
      "duration": "once",
      "duration_in_months": null,
      "max_redemptions": null,
      "times_redeemed": 3,
      "expires_at": null,
      "first_time_transaction": true,
      "minimum_amount": 5000,
      "minimum_amount_currency": "pln",
      "scope": {
        "type": "product",
        "product_id": "550e8400-e29b-41d4-a716-446655440000",
        "price_ids": [
          "550e8400-e29b-41d4-a716-446655440001"
        ]
      },
      "status": "active",
      "created_at": "2026-05-20T09:00:00+00:00",
      "updated_at": "2026-05-21T11:30:00+00:00"
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 3
  }
}

Response Fields

Field	Type	Nullable	Description
`id`	string	No	Unique identifier for the promotion code (UUID)
`code`	string	No	The redemption string customers type at checkout
`name`	string	Yes	Optional internal name shown in dashboards
`discount_type`	string	No	`amount_off` (fixed amount) or `percent_off` (percentage)
`amount_off`	integer	Yes	Fixed discount in minor units (e.g. cents/grosze). Set when `discount_type=amount_off`.
`percent_off`	number	Yes	Percentage discount (1–100). Set when `discount_type=percent_off`.
`currency`	string	Yes	Lowercase ISO currency code. Set for `amount_off` codes and for global codes that carry `minimum_amount`.
`duration`	string	No	How long the discount applies: `once`, `repeating`, or `forever`.
`duration_in_months`	integer	Yes	Number of months the discount applies. Set when `duration=repeating`.
`max_redemptions`	integer	Yes	Maximum total redemptions across all customers
`times_redeemed`	integer	No	How many times the code has already been redeemed
`expires_at`	string	Yes	When the code stops being redeemable (ISO 8601 format)
`first_time_transaction`	boolean	No	Whether the code is restricted to a customer's first purchase
`minimum_amount`	integer	Yes	Minimum transaction amount in minor units required for redemption
`minimum_amount_currency`	string	Yes	Lowercase ISO currency code for `minimum_amount`
`scope`	object	No	Either `{ "type": "global" }` or `{ "type": "product", "product_id": "…", "price_ids": [ … ] }`
`status`	string	No	Derived status: `active`, `inactive`, `expired`, or `archived`
`created_at`	string	No	When the promotion code was created (ISO 8601 format)
`updated_at`	string	No	When the promotion code was last updated (ISO 8601 format)

Error Responses

Bad Request (400)

Returned when a filter has a non-empty but unparseable value. The message names the offending field and the value received.

{
  "message": "Invalid value for 'discount_type': 'percentage'"
}

Unauthorized (401)

{
  "message": "Unauthenticated."
}

Request​

Query Parameters​

Example Request​

Response​

Success Response (200)​

Response Fields​

Error Responses​

Bad Request (400)​

Unauthorized (401)​