POST /api/v1/coupons/verify
Validate a coupon code against a cart subtotal. Returns the discount details when the coupon is valid. Middleware:throttle:api.verificationAuthentication: Not required
Request body
Numeric tenant ID to scope the coupon lookup.
Coupon code string. Normalized to uppercase internally. Maximum 50 characters.
Current cart subtotal used to evaluate minimum spend requirements. Must be ≥ 0.
Response 200 OK
Coupon is valid. Response shape is determined by the coupon domain validation result.
Always
true on a 200 response.Calculated discount to subtract from the cart subtotal.
One of:
percentage, fixed, free_shipping.Response 422 Unprocessable Entity
Always
false on a 422 response.Human-readable error message.
Machine-readable rejection code. One of:
not_found, expired, not_started, usage_limit, user_limit, min_spend, already_used, inactive, product_excluded, category_excluded.Error responses
| Status | Cause |
|---|---|
422 | Missing or invalid fields |
422 | Coupon not found, expired, usage limit reached, minimum spend not met |
429 | Verification rate limit exceeded |
GET /api/v1/coupons
List all active public coupons for a tenant. Results are cached for 15 minutes. Middleware:throttle:apiAuthentication: Not required
Query parameters
Numeric tenant ID. Returns
400 when absent or zero.Response 200 OK
true on success.Array of valid coupon objects.
Error responses
| Status | Cause |
|---|---|
400 | tenant_id missing or zero |
POST /api/v1/checkout/validate-coupon
Validate a coupon in the checkout context. Used during the checkout flow to apply discounts to a session cart. Middleware:throttle:api.verificationAuthentication: Not required
This endpoint is handled by the
CheckoutController. It behaves identically to POST /api/v1/coupons/verify for validation purposes but operates within the checkout session context.POST /api/v1/checkout/remove-coupon
Remove a previously applied coupon from the checkout session. Middleware:throttle:apiAuthentication: Not required
Response 200 OK
Confirmation that the coupon was removed from the session.
POST /api/v1/checkout/cart-summary
Sync a checkout session cart to the server and return a summary including subtotal. Used to keep server-side cart state consistent with the client before placing an order. Middleware:throttle:apiAuthentication: Optional (pass
Authorization header if logged in)
Request body
Client-generated session identifier for the cart.
Array of cart line items.
Calculated cart subtotal from the client.
Response 200 OK
trueCart synchronized successfullyEchoed subtotal value.
POST /api/v1/checkout/hold-inventory
Reserve stock for cart items during the checkout process. Prevents overselling by locking inventory quantities for a short window while the customer completes payment. Route name:checkout.hold-inventoryMiddleware:
throttle:apiAuthentication: Not required
Request body
Cart line items to hold. Each item must include
product_id and quantity.UUID of the location to hold inventory from. When omitted, the tenant’s active primary location is used automatically.
Response 200 OK
trueConfirmation that inventory holds were applied.
Response 400 Bad Request
Returned when no active primary location can be found for the tenant.
Error responses
| Status | Cause |
|---|---|
400 | Missing or unresolvable tenant ID |
400 | No active primary location found |
422 | Validation failure on items structure |