Skip to main content
The Coupons API allows you to create promotional codes with various discount types, usage restrictions, and customer assignments.

​
Features

  • Multiple Discount Types: Percentage, fixed amount, free items, category discounts, buy X get Y
  • Usage Limits: Control total uses and per-customer limits
  • Validity Periods: Set start and expiration dates
  • Customer Targeting: Assign coupons to specific customers
  • Validation: Real-time coupon validation before applying to orders

​
Authentication

Requires authentication and permissions:
  • loyalty:read - View and validate coupons
  • loyalty:create - Create, update, delete, and assign coupons

​
Base URL

https://api.restai.app/v1/coupons

​
Coupon Types

​
Percentage Discount

Applies a percentage off the order total.
  • Type: percentage
  • Fields: discountValue (e.g., 15 for 15% off)

​
Fixed Amount Discount

Subtracts a fixed amount from the order.
  • Type: fixed
  • Fields: discountValue (amount in cents)

​
Free Item

Gives a menu item for free.
  • Type: item_free
  • Fields: menuItemId

​
Item Discount

Discounts a specific menu item.
  • Type: item_discount
  • Fields: menuItemId, discountValue

​
Category Discount

Discounts all items in a category.
  • Type: category_discount
  • Fields: categoryId, discountValue

​
Buy X Get Y

Buy a quantity, get additional quantity free.
  • Type: buy_x_get_y
  • Fields: buyQuantity, getQuantity, menuItemId

​
Coupon Status

  • active - Currently valid and usable
  • inactive - Created but not yet active
  • expired - Past expiration date or manually expired

​
Create Coupon

Create a new promotional coupon.

​
Endpoint

POST /coupons

​
Request Body

​
code
string
required
Unique coupon code (1-50 characters, converted to uppercase)
​
name
string
required
Display name (1-255 characters)
​
description
string
Description (max 500 characters)
​
type
string
required
Discount type: percentage, fixed, item_free, item_discount, category_discount, buy_x_get_y
​
discountValue
number
Discount amount in cents (for percentage, fixed, item_discount, category_discount types)
​
menuItemId
string
Menu item UUID (for item_free, item_discount, buy_x_get_y types)
​
categoryId
string
Category UUID (for category_discount type)
​
buyQuantity
number
Buy quantity (for buy_x_get_y type, minimum: 1)
​
getQuantity
number
Get quantity free (for buy_x_get_y type, minimum: 1)
​
minOrderAmount
number
Minimum order amount in cents to use coupon
​
maxDiscountAmount
number
Maximum discount cap in cents
​
maxUsesTotal
number
Maximum total uses across all customers
​
maxUsesPerCustomer
number
Maximum uses per customer
​
startsAt
string
Start date/time in ISO 8601 format
​
expiresAt
string
Expiration date/time in ISO 8601 format

​
Example Request

curl -X POST https://api.restai.app/v1/coupons \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "SUMMER20",
    "name": "Summer Sale 20% Off",
    "description": "Get 20% off your entire order",
    "type": "percentage",
    "discountValue": 20,
    "minOrderAmount": 2000,
    "maxDiscountAmount": 1000,
    "maxUsesTotal": 100,
    "maxUsesPerCustomer": 1,
    "startsAt": "2026-06-01T00:00:00Z",
    "expiresAt": "2026-08-31T23:59:59Z"
  }'

​
List Coupons

Retrieve all coupons with optional filtering.

​
Endpoint

GET /coupons

​
Query Parameters

​
status
string
Filter by status: active, inactive, expired
​
type
string
Filter by type: percentage, fixed, item_free, etc.

​
Example Request

curl "https://api.restai.app/v1/coupons?status=active" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Get Coupon Details

Retrieve a specific coupon including redemption count.

​
Endpoint

GET /coupons/:id

​
Path Parameters

​
id
string
required
Coupon UUID

​
Response

Includes coupon details plus redemption_count field.

​
Update Coupon

Update coupon details.

​
Endpoint

PATCH /coupons/:id

​
Path Parameters

​
id
string
required
Coupon UUID

​
Request Body

All fields are optional - only provide fields to update.

​
Delete Coupon

Permanently delete a coupon.

​
Endpoint

DELETE /coupons/:id

​
Validate Coupon

Validate a coupon code before applying to an order.

​
Endpoint

POST /coupons/validate

​
Request Body

​
code
string
required
Coupon code to validate

​
Response

Returns coupon details if valid, or error if:
  • Coupon not found
  • Status is not active
  • Start date is in the future
  • Expiration date has passed
  • Usage limit reached

​
Example Request

curl -X POST https://api.restai.app/v1/coupons/validate \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"code": "SUMMER20"}'

​
Assign Coupon to Customers

Assign a coupon to specific customers.

​
Endpoint

POST /coupons/assign

​
Request Body

​
couponId
string
required
Coupon UUID
​
customerIds
array
required
Array of customer UUIDs (1-100 items)

​
Example Request

curl -X POST https://api.restai.app/v1/coupons/assign \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "couponId": "550e8400-e29b-41d4-a716-446655440000",
    "customerIds": [
      "660e8400-e29b-41d4-a716-446655440000",
      "770e8400-e29b-41d4-a716-446655440000"
    ]
  }'

​
Get Coupon Assignments

View which customers have been assigned a coupon.

​
Endpoint

GET /coupons/:id/assignments

​
Path Parameters

​
id
string
required
Coupon UUID

​
Response

Returns assignment records with customer info and usage timestamps.

Build docs developers (and LLMs) love

Get started for freeTalk to us