Coupons

Overview

Coupons allow you to create promotional discount codes that clients can apply during checkout. Each coupon can have usage limits, validity periods, and minimum purchase requirements.

Discount Types

percentage: Discount as a percentage of the purchase amount (e.g., 20% off)
fixed: Fixed amount discount (e.g., €10 off)

List Coupons

string

Search coupons by code or description

curl -X GET "https://your-domain.com/api/marketing/coupons?search=SUMMER" \
  -H "Authorization: Bearer YOUR_TOKEN"

coupon_id

string

required

Unique identifier for the coupon (UUID)

code

string

required

Unique coupon code that clients use at checkout

description

string

Internal description of the coupon purpose

discount_type

string

required

Type of discount: percentage or fixed

discount_value

number

required

Discount amount (percentage value or fixed amount in currency)

min_purchase

number

Minimum purchase amount required to use the coupon

max_uses

integer

Maximum number of times this coupon can be used (null for unlimited)

current_uses

integer

required

Number of times the coupon has been used

valid_from

datetime

Start date for coupon validity

valid_until

datetime

Expiration date for the coupon

status

string

required

Coupon status: activo (active) or inactivo (inactive)

created_at

datetime

required

Timestamp when the coupon was created

updated_at

datetime

required

Timestamp when the coupon was last updated

Create Coupon

curl -X POST "https://your-domain.com/api/marketing/coupons" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "SUMMER2026",
    "description": "Summer promotion 2026",
    "discount_type": "percentage",
    "discount_value": 20,
    "min_purchase": 50,
    "max_uses": 100,
    "valid_from": "2026-06-01T00:00:00Z",
    "valid_until": "2026-08-31T23:59:59Z",
    "status": "activo"
  }'

Request Body

code

string

required

Unique coupon code (must be unique across all coupons)

description

string

Description of the coupon for internal reference

discount_type

string

required

Discount type: percentage or fixed

discount_value

number

required

Discount value (0-100 for percentage, any positive number for fixed)

min_purchase

number

Minimum purchase amount required

max_uses

integer

Maximum uses allowed (omit for unlimited)

valid_from

datetime

When the coupon becomes valid (ISO 8601 format)

valid_until

datetime

When the coupon expires (ISO 8601 format)

status

string

default:"activo"

Initial status: activo or inactivo

Response

Returns the created coupon object with all fields including generated coupon_id.

Get Coupon

Retrieve a specific coupon by ID.

curl -X GET "https://your-domain.com/api/marketing/coupons/{coupon_id}" \
  -H "Authorization: Bearer YOUR_TOKEN"

Path Parameters

coupon_id

string

required

The unique identifier of the coupon

Response

Returns the complete coupon object.

Error Responses

statusCode

integer

HTTP status code

400: Coupon ID is required
404: Coupon not found

statusMessage

string

Error message describing the issue

Update Coupon

Update an existing coupon’s properties.

curl -X PUT "https://your-domain.com/api/marketing/coupons/{coupon_id}" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "inactivo",
    "max_uses": 150
  }'

Path Parameters

coupon_id

string

required

The unique identifier of the coupon to update

Request Body

All fields are optional. Only include the fields you want to update.

code

string

Update the coupon code (must remain unique)

description

string

Update the description

discount_type

string

Change discount type

discount_value

number

Change discount value

min_purchase

number

Update minimum purchase requirement

max_uses

integer

Update maximum uses (set to null for unlimited)

valid_from

datetime

Update validity start date

valid_until

datetime

Update expiration date

status

string

Update status

Response

Returns the updated coupon object.

Delete Coupon

Permanently delete a coupon.

curl -X DELETE "https://your-domain.com/api/marketing/coupons/{coupon_id}" \
  -H "Authorization: Bearer YOUR_TOKEN"

Path Parameters

coupon_id

string

required

The unique identifier of the coupon to delete

Response

success

boolean

Returns true if the deletion was successful

Validation Rules

Code Uniqueness

The code field must be unique across all coupons. Attempting to create a coupon with a duplicate code will result in an error.

Discount Value Validation

For percentage discount type: Value should be between 0 and 100
For fixed discount type: Value should be a positive number

Usage Tracking

current_uses is automatically incremented when a coupon is applied to a cart
When current_uses reaches max_uses, the coupon should no longer be accepted
This counter is read-only and managed by the system

Date Validation

valid_from must be before valid_until
Coupons can only be used between these dates
If valid_from is not set, the coupon is valid immediately
If valid_until is not set, the coupon never expires

Status Management

Only coupons with status activo can be used at checkout
Setting status to inactivo immediately disables the coupon
This allows temporary deactivation without deleting the coupon

Business Logic

Minimum Purchase Requirement

When min_purchase is set, the cart subtotal must meet or exceed this amount for the coupon to be valid.

Maximum Uses

The max_uses field limits how many times a coupon can be applied across all transactions. This is useful for limited-time promotions.

Percentage vs Fixed Discounts

Percentage: Applied as subtotal * (discount_value / 100)
Fixed: Applied as direct reduction up to the cart subtotal (never negative)

Cart Integration

Coupons are applied during checkout via the Cart API:

curl -X POST "https://your-domain.com/api/sales/carts/{cart_id}/apply-coupon" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "coupon_code": "SUMMER2026"
  }'

The applied coupon code is stored in the applied_coupon field of the Cart model, and the discount is reflected in the cart’s discount and total fields.

Authentication

Clients

Appointments

Catalog

Sales

Marketing

Reports

Users

Overview

Discount Types

List Coupons

Create Coupon

Request Body

Response

Get Coupon

Path Parameters

Response

Error Responses

Update Coupon

Path Parameters

Request Body

Response

Delete Coupon

Path Parameters

Response

Validation Rules

Code Uniqueness

Discount Value Validation

Usage Tracking

Date Validation

Status Management

Business Logic

Minimum Purchase Requirement

Maximum Uses

Percentage vs Fixed Discounts

Cart Integration

Build docs developers (and LLMs) love

Authentication

Clients

Appointments

Catalog

Sales

Marketing

Reports

Users

​Overview

​Discount Types

​List Coupons

​Create Coupon

​Request Body

​Response

​Get Coupon

​Path Parameters

​Response

​Error Responses

​Update Coupon

​Path Parameters

​Request Body

​Response

​Delete Coupon

​Path Parameters

​Response

​Validation Rules

​Code Uniqueness

​Discount Value Validation

​Usage Tracking

​Date Validation

​Status Management

​Business Logic

​Minimum Purchase Requirement

​Maximum Uses

​Percentage vs Fixed Discounts

​Cart Integration

Build docs developers (and LLMs) love

Overview

Discount Types

List Coupons

Create Coupon

Request Body

Response

Get Coupon

Path Parameters

Response

Error Responses

Update Coupon

Path Parameters

Request Body

Response

Delete Coupon

Path Parameters

Response

Validation Rules

Code Uniqueness

Discount Value Validation

Usage Tracking

Date Validation

Status Management

Business Logic

Minimum Purchase Requirement

Maximum Uses

Percentage vs Fixed Discounts

Cart Integration