Coupons
Visibility
POST /coupons/validate— Public validation endpoint
Authentication
x-api-key: sk_eco_...POST /coupons/validate
Validates coupon codes and returns both applied and available promotion context.
Request Body (CouponValidateRequest)
| Field | Type | Required | Description |
|---|---|---|---|
code | string? | No | Coupon code entered by customer |
cart_total | number? | No | Used for minimum amount checks |
items | object[]? | No | Cart items for targeting calculations |
Response Body (CouponValidateResponse)
| Field | Type | Description |
|---|---|---|
valid | boolean | Validation result for provided code |
applied_discounts | AppliedDiscountResponse[]? | Discounts currently applicable |
available_promotions | PromotionInfo[]? | Active promotions discoverable by client |
discount_amount | number? | Computed discount amount |
message | string? | User-facing validation guidance |
cURL
curl -X POST "https://api.ecommaps.com/api/v1/storefront/coupons/validate" \
-H "x-api-key: sk_eco_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"code":"DISCOUNT20","cart_total":10000,"items":[]}'SDK Example
const result = await ecommapsClient.store.coupons.validate({
code: "DISCOUNT20",
cart_total: 10000,
items: [],
});Error Matrix
| Status | Scenario |
|---|---|
400 | Invalid coupon payload |
401 | Missing/invalid API key |
422 | Validation failure |
500 | Promotion engine failure |