---
title: "Check Coupons"
method: GET
path: "/users/check_coupons"
tags: ["accepts-api-key"]
---

# Check Coupons

`GET /users/check_coupons`

## Request

- Base URL: `https://api.tellers.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.tellers.ai/users/check_coupons`
- Auth: none declared

## Query parameters

- `coupon_code` string, required: Stripe promotion code to validate.
- `currency` string, nullable: Lowercase ISO currency the prices are shown in (the checkout `currency`). An amount discount is then described in it, and a coupon that can't be charged in it comes back invalid.

## Headers

- `x-api-key` string, nullable
- `authorization` string, nullable

## Response `200`

Successful Response

- CouponCheckResponse
  - `coupon_code` string, required
  - `is_valid` boolean, required
  - `name` string, nullable, required
  - `description` string, nullable, required
  - `discount` CouponCheckDiscount: What a valid coupon takes off, to price it the way checkout will.
    - `percent_off` number, nullable: Percent off each eligible line (e.g. 20 for 20%).
    - `amount_off_cents` integer, nullable: Fixed amount off the eligible lines' total, in cents of `currency`. Set instead of `percent_off`.
    - `currency` string, nullable: Lowercase ISO currency of `amount_off_cents`.
    - `duration` 'once' | 'repeating' | 'forever', nullable: How many invoices it discounts: the first only, the first `duration_in_months` months, or every one.
    - `duration_in_months` integer, nullable
    - `applies_to_price_ids` string[], nullable: Stripe price ids from GET /billing/catalog this coupon discounts; null when it discounts every line. An empty list means none of the catalog's lines are eligible.
  - `expires_at` string, date-time, nullable: UTC time after which the code can no longer be redeemed (the earlier of the promotion code's expiry and the coupon's `redeem_by`); null when it doesn't expire. Also set, with nothing else, when the code has expired. Clients show it in the user's own time zone.
  - `is_expired` boolean: True when the code exists but has expired (`expires_at` says when); `is_valid` is then false and no other detail is given.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/tellers/apis/tellers-api.md) - [All operations](https://skmtc.dev/tellers/apis/tellers-api/llms.txt) - [OpenAPI document](https://skmtc.dev/tellers/apis/tellers-api/revisions/fdaa0fa44a26?raw)