Check a discount code
const url = 'https://apibase.ecomweb.app/api/v1/public/stores/example/promotions/validate';const options = { method: 'POST', headers: { 'x-storefront-api-key': '<x-storefront-api-key>', 'Content-Type': 'application/json' }, body: '{"code":"FREESHIP","items":[{"product_id":12,"variant_id":34,"quantity":2,"price":100000}],"subtotal":100000,"shipping_fee":30000}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}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.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”The store’s ref, as returned by GET /stores.
Request Bodyrequired
Section titled “Request Bodyrequired”object
The discount code to check. Matched without regard to case.
Example
FREESHIPThe lines of the order, at least one.
object
ID of the product.
Example
12ID of the variant, when the product has variants.
Example
34Quantity ordered.
Example
2Unit price in the smallest currency unit.
Example
100000Order subtotal, used for minimum-amount conditions.
Example
100000Shipping fee of the order, used to work out a shipping discount.
Example
30000Responses
Section titled “Responses”object
The promotion the code unlocked. Present only when success is true.
object
Promotion ID.
Promotion name.
Promotion type.
PERCENTAGE or FIXED_AMOUNT, when the promotion has a discount.
The discount value, when the promotion has one.
Cap on a percentage discount, when there is one.
Minimum order amount the code needs, when there is one.
True when the code can be applied to the order.
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.
Discount on the shipping fee that was sent in, in the same unit. Present only when success is true.
A readable explanation of why the code was refused, in Vietnamese. Present only when success is false.
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.
object
The HTTP status code.
What went wrong; validation failures list one message per problem.
The HTTP status text, such as Bad Request.
object
A stable, machine-readable error code.
A human-readable explanation.
Extra context about the error, when there is any.
object
When the error happened, as an ISO 8601 timestamp.
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.
object
The HTTP status code.
What went wrong; validation failures list one message per problem.
The HTTP status text, such as Bad Request.
object
A stable, machine-readable error code.
A human-readable explanation.
Extra context about the error, when there is any.
object
When the error happened, as an ISO 8601 timestamp.
Example generated
{ "statusCode": 1, "message": [ "example" ], "error": "example"}