Skip to content

Check a discount code

POST
/public/stores/{storeRef}/promotions/validate
curl --request POST \
--url https://apibase.ecomweb.app/api/v1/public/stores/example/promotions/validate \
--header 'Content-Type: application/json' \
--header 'x-storefront-api-key: <x-storefront-api-key>' \
--data '{ "code": "FREESHIP", "items": [ { "product_id": 12, "variant_id": 34, "quantity": 2, "price": 100000 } ], "subtotal": 100000, "shipping_fee": 30000 }'

Checks a discount code against the lines, subtotal and shipping fee you send, without creating an order or counting a use. A usable code answers success: true with the promotion and the shipping discount it gives. An unusable code still answers successfully, with success: false and a code saying why. The per-customer limit is not checked here; it is enforced when the order is placed. This route does not validate the body: send items with product_id, quantity and price, a numeric subtotal and shipping_fee, as a malformed body is not rejected with a 400.

storeRef
required
string

The store’s ref, as returned by GET /stores.

Media typeapplication/json
object
code
required

The discount code to check. Matched without regard to case.

string

Example

FREESHIP
items
required

The lines of the order, at least one.

Array<object>
object
product_id
required

ID of the product.

number

Example

12
variant_id

ID of the variant, when the product has variants.

number

Example

34
quantity
required

Quantity ordered.

number
>= 1

Example

2
price
required

Unit price in the smallest currency unit.

number

Example

100000
subtotal
required

Order subtotal, used for minimum-amount conditions.

number

Example

100000
shipping_fee
required

Shipping fee of the order, used to work out a shipping discount.

number

Example

30000
Media typeapplication/json
object
promotion

The promotion the code unlocked. Present only when success is true.

object
id
required

Promotion ID.

number
name
required

Promotion name.

string
type
required

Promotion type.

string
discount_method

PERCENTAGE or FIXED_AMOUNT, when the promotion has a discount.

string
discount_value

The discount value, when the promotion has one.

number
max_discount_amount

Cap on a percentage discount, when there is one.

number
min_amount

Minimum order amount the code needs, when there is one.

number
success
required

True when the code can be applied to the order.

boolean
code

Why the code was refused: PROMOTION_NOT_FOUND, PROMOTION_NOT_ACTIVE, PROMOTION_NOT_STARTED, PROMOTION_EXPIRED, PROMOTION_USAGE_LIMIT_REACHED, PROMOTION_NOT_APPLICABLE_TO_ITEMS, PROMOTION_MIN_AMOUNT_NOT_MET, PROMOTION_MIN_QUANTITY_NOT_MET or PROMOTION_VALIDATION_FAILED. Present only when success is false.

string
shipping_discount

Discount on the shipping fee that was sent in, in the same unit. Present only when success is true.

number
message

A readable explanation of why the code was refused, in Vietnamese. Present only when success is false.

string

Example generated

{
"promotion": {
"id": 1,
"name": "example",
"type": "example",
"discount_method": "example",
"discount_value": 1,
"max_discount_amount": 1,
"min_amount": 1
},
"success": true,
"code": "example",
"shipping_discount": 1,
"message": "example"
}

The key is missing, invalid, revoked or expired.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}

The key may not do this: a missing scope, a readonly key, a publishable key on a Store API route, or a disallowed origin.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}