Discounts API

Manage discount codes and coupons for the authenticated store. Supports both percentage-based and fixed-amount discounts with optional expiry dates, usage limits, and minimum order values.

List Discounts

Retrieve a paginated list of discount codes.

GET /api/apps/v1/discounts

Scope

read:discounts

Query Parameters

Parameter	Type	Default	Description
`page`	integer	`1`	Page number
`limit`	integer	`50`	Items per page (max 250)
`is_active`	integer	--	Filter by status: `1` for active, `0` for inactive
`search`	string	--	Search by discount code

Example Request

curl -X GET "https://api.selorax.io/api/apps/v1/discounts?is_active=1&limit=20" \
  -H "Authorization: Bearer <token>"

Response

{
  "data": [
    {
      "discount_id": 5,
      "store_id": 22,
      "code": "SUMMER20",
      "is_amount": 0,
      "amount": 0,
      "percentage": 20,
      "free_shipping_on": 0,
      "minimum_order_value": 500,
      "maximum_discount_amount": 200,
      "is_active": 1,
      "total_use": 100,
      "use_per_user": 1,
      "starts_at": "2025-06-01T00:00:00.000Z",
      "ends_at": "2025-08-31T23:59:59.000Z",
      "created_at": "2025-05-28T10:00:00.000Z",
      "updated_at": "2025-05-28T10:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1
  },
  "status": 200
}

Response Fields

Field	Type	Description
`discount_id`	integer	Unique discount identifier
`code`	string	Discount code (uppercase)
`is_amount`	integer	`0` = percentage discount, `1` = fixed amount
`amount`	number	Fixed discount amount (when `is_amount = 1`)
`percentage`	number	Percentage off (when `is_amount = 0`)
`free_shipping_on`	integer	`1` if free shipping is included
`minimum_order_value`	number or null	Minimum cart total to apply
`maximum_discount_amount`	number or null	Cap on percentage discount
`is_active`	integer	`1` = active, `0` = inactive
`total_use`	integer or null	Maximum total uses (null = unlimited)
`use_per_user`	integer or null	Maximum uses per customer
`starts_at`	string or null	Start date (ISO 8601)
`ends_at`	string or null	Expiry date (ISO 8601)

Get Discount

Retrieve a single discount by ID.

GET /api/apps/v1/discounts/:discount_id

Scope

read:discounts

Create Discount

Create a new discount code.

POST /api/apps/v1/discounts

Scope

write:discounts

Request Body

Field	Type	Required	Description
`code`	string	Yes	Discount code (auto-uppercased, unique per store)
`is_amount`	integer	No	`0` = percentage (default), `1` = fixed amount
`amount`	number	Conditional	Required when `is_amount = 1`
`percentage`	number	Conditional	Required when `is_amount = 0`
`free_shipping_on`	integer	No	`1` to include free shipping
`minimum_order_value`	number	No	Minimum order value to apply
`maximum_discount_amount`	number	No	Maximum discount cap
`is_active`	integer	No	`1` = active (default), `0` = inactive
`total_use`	integer	No	Max total uses
`use_per_user`	integer	No	Max uses per customer
`starts_at`	string	No	Start date (ISO 8601)
`ends_at`	string	No	Expiry date (ISO 8601)

Example — Percentage Discount

curl -X POST "https://api.selorax.io/api/apps/v1/discounts" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "SUMMER20",
    "is_amount": 0,
    "percentage": 20,
    "minimum_order_value": 500,
    "maximum_discount_amount": 200,
    "total_use": 100,
    "use_per_user": 1,
    "starts_at": "2025-06-01T00:00:00Z",
    "ends_at": "2025-08-31T23:59:59Z"
  }'

Example — Fixed Amount Discount

curl -X POST "https://api.selorax.io/api/apps/v1/discounts" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "FLAT100",
    "is_amount": 1,
    "amount": 100,
    "minimum_order_value": 1000,
    "is_active": 1
  }'

Response (201)

Returns the full discount object.

Error Responses

Status	Meaning
400	Missing required fields
409	Discount code already exists

Update Discount

Update a discount's fields. Only provided fields are updated.

PUT /api/apps/v1/discounts/:discount_id

Scope

write:discounts

Request Body

Same fields as Create Discount, all optional.

Example Request

curl -X PUT "https://api.selorax.io/api/apps/v1/discounts/5" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "percentage": 25,
    "ends_at": "2025-09-30T23:59:59Z"
  }'

Delete Discount

Permanently delete a discount code.

DELETE /api/apps/v1/discounts/:discount_id

Scope

write:discounts

Validate Discount Code

Check if a discount code is valid (active, within date range).

GET /api/apps/v1/discounts/validate/:code

Scope

read:discounts

Example Request

curl -X GET "https://api.selorax.io/api/apps/v1/discounts/validate/SUMMER20" \
  -H "Authorization: Bearer <token>"

Response

{
  "data": {
    "discount_id": 5,
    "code": "SUMMER20",
    "is_amount": 0,
    "percentage": 20,
    "minimum_order_value": 500,
    "maximum_discount_amount": 200,
    "is_active": 1,
    "starts_at": "2025-06-01T00:00:00.000Z",
    "ends_at": "2025-08-31T23:59:59.000Z"
  },
  "valid": true,
  "issues": [],
  "status": 200
}

If the code is invalid:

{
  "data": { ... },
  "valid": false,
  "issues": ["Discount has expired."],
  "status": 200
}

Possible issues:

"Discount is inactive."
"Discount has not started yet."
"Discount has expired."