Coupons API

Create promotional coupons, set discounts, and manage coupon usage.

Endpoints Overview

Method	Endpoint	Description
`GET`	`/v1/coupons`	List all coupons
`POST`	`/v1/coupons`	Create a new coupon
`GET`	`/v1/coupons/:id`	Get coupon details
`PATCH`	`/v1/coupons/:id`	Update a coupon
`DELETE`	`/v1/coupons/:id`	Delete a coupon
`POST`	`/v1/coupons/validate`	Validate a coupon code

List Coupons

GET /v1/coupons

Response

{
  "data": [
    {
      "id": "cpn_abc123",
      "code": "SAVE20",
      "discount_type": "percentage",
      "discount_value": 20,
      "min_order_amount": 10.00,
      "max_uses": 100,
      "used_count": 45,
      "expires_at": "2025-12-31T23:59:59Z",
      "is_active": true,
      "is_global": true,
      "product_ids": [],
      "group_ids": [],
      "created_at": "2025-01-01T00:00:00Z",
      "updated_at": "2025-01-01T00:00:00Z"
    }
  ],
  "meta": {
    "total": 10,
    "limit": 25,
    "offset": 0
  }
}

Create Coupon

POST /v1/coupons

Request Body

Field	Type	Required	Description
`code`	string	No	Coupon code (auto-generated if not provided)
`discount_type`	string	No	`percentage` or `fixed` (default: percentage)
`discount_value`	number	Yes	Discount amount (must be > 0)
`min_order_amount`	number	No	Minimum order amount (default: 0)
`max_uses`	integer	No	Maximum number of uses (null = unlimited)
`expires_at`	string	No	Expiration date (ISO 8601)
`is_global`	boolean	No	Apply to all products (default: true)
`product_ids`	array	No	Limit to specific product IDs
`group_ids`	array	No	Limit to specific group IDs

Example Request

curl -X POST "https://api.sellgate.cc/v1/coupons" \
  -H "Authorization: Bearer sg_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "SUMMER25",
    "discount_type": "percentage",
    "discount_value": 25,
    "max_uses": 500,
    "expires_at": "2025-08-31T23:59:59Z"
  }'

Response (201 Created)

{
  "data": {
    "id": "cpn_new123",
    "code": "SUMMER25",
    "discount_type": "percentage",
    "discount_value": 25,
    "min_order_amount": 0,
    "max_uses": 500,
    "expires_at": "2025-08-31T23:59:59Z",
    "is_global": true,
    "created_at": "2025-01-20T10:00:00Z"
  }
}

Update Coupon

PATCH /v1/coupons/:id

All fields are optional.

Example Request

curl -X PATCH "https://api.sellgate.cc/v1/coupons/cpn_abc123" \
  -H "Authorization: Bearer sg_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "is_active": false
  }'

Delete Coupon

DELETE /v1/coupons/:id

Validate Coupon

Check if a coupon code is valid and calculate the discount amount.

POST /v1/coupons/validate

Request Body

Field	Type	Required	Description
`code`	string	Yes	Coupon code to validate
`product_id`	string	No	Product ID to check coupon eligibility
`order_amount`	number	No	Order amount to calculate discount

Example Request

curl -X POST "https://api.sellgate.cc/v1/coupons/validate" \
  -H "Authorization: Bearer sg_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "SAVE20",
    "order_amount": 50.00
  }'

Response (Valid Coupon)

{
  "valid": true,
  "coupon": {
    "id": "cpn_abc123",
    "code": "SAVE20",
    "discount_type": "percentage",
    "discount_value": 20,
    "min_order_amount": 10.00,
    "discount_amount": 10.00
  }
}

Response (Invalid Coupon)

{
  "valid": false,
  "error": "Coupon has expired"
}

Discount Types

Type	Description
`percentage`	Percentage discount (e.g., 20 = 20% off)
`fixed`	Fixed amount discount (e.g., 5 = $5 off)

Coupon Targeting

Coupons can be scoped to specific products or groups:

Global (is_global: true): Applies to all products
Product-specific: Set product_ids array
Group-specific: Set group_ids array

If both product_ids and group_ids are set, the coupon applies to products in either list.

Coupons API

On this page