> ## Documentation Index
> Fetch the complete documentation index at: https://docs.salesive.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Apply coupon to order
> Apply a validated coupon code to a pending order and automatically calculate the discount.
## Request
```http theme={null}
POST /coupons/apply
Content-Type: application/json
x-shop-id: {shopId}
Authorization: Bearer {token}
{
"orderId": "67890abcdef1234567890abc",
"code": "SUMMER20"
}
```
## Headers
| Header | Type | Description |
| --------------- | ------ | ------------------------------------------------------ |
| `Content-Type` | string | Always set to `application/json`. |
| `x-shop-id` | string | Shop identifier to associate the user with your store. |
| `Authorization` | string | Bearer token for authenticated user (required). |
This endpoint requires authentication. Only the order owner can apply
coupons to their orders.
## Body parameters
| Field | Type | Required | Description |
| --------- | ------ | -------- | ---------------------------------------- |
| `orderId` | string | Yes | Order ID to apply the coupon to. |
| `code` | string | Yes | Coupon code to apply (case-insensitive). |
## Successful response
```json theme={null}
{
"status": 200,
"success": true,
"message": "Coupon applied successfully",
"data": {
"order": {
"_id": "67890abcdef1234567890abc",
"orderId": 1001,
"subtotal": 1000,
"shippingCost": 50,
"discount": 200,
"total": 850,
"coupon": {
"_id": "67890abcdef1234567890def",
"code": "SUMMER20",
"type": "percentage",
"discount": 20
}
}
}
}
```
### Response fields
| Field | Type | Description |
| -------------------- | ------ | --------------------------------------------------- |
| `order._id` | string | Order identifier. |
| `order.orderId` | number | Human-readable order number. |
| `order.subtotal` | number | Order subtotal before shipping and discount. |
| `order.shippingCost` | number | Shipping cost for the order. |
| `order.discount` | number | Discount amount applied by the coupon. |
| `order.total` | number | Final order total (subtotal + shipping - discount). |
| `order.coupon` | object | Applied coupon details. |
## Validation checks
The endpoint performs comprehensive validations before applying the coupon:
Order exists and belongs to the authenticated user
Order is in `pending` status (cannot apply to completed/cancelled orders)
Order does not already have a coupon applied
Coupon exists and is active
Coupon belongs to the specified shop
Coupon is within valid date range
Global usage limit has not been exceeded
Per-user usage limit has not been exceeded
Order meets minimum amount requirement
## Side effects
When a coupon is successfully applied:
1. **Order is updated** with the coupon ID and discount amount
2. **Coupon usage count is incremented** globally
3. **Order total is recalculated** with the discount applied
## Error responses
### Order not found
```json theme={null}
{
"status": 404,
"success": false,
"message": "Order not found"
}
```
### Unauthorized access
```json theme={null}
{
"status": 403,
"success": false,
"message": "Unauthorized access to order"
}
```
### Coupon already applied
```json theme={null}
{
"status": 400,
"success": false,
"message": "Order already has a coupon applied"
}
```
### Invalid order status
```json theme={null}
{
"status": 400,
"success": false,
"message": "Coupon can only be applied to pending orders"
}
```
### Invalid coupon
```json theme={null}
{
"status": 404,
"success": false,
"message": "Invalid coupon code"
}
```
## Best practices
Always call the `/coupons/verify` endpoint first to validate the coupon and
show the discount amount to the user before applying it to the order.
Once a coupon is applied to an order, it cannot be removed or replaced.
Ensure the user confirms the coupon application before calling this
endpoint.
## OpenAPI
````yaml POST /coupons/apply
openapi: 3.1.0
info:
title: Salesive Store API
description: >-
REST interface for querying products, categories, and merchandising banners
exposed by Salesive storefronts.
version: 1.0.0
servers:
- description: Production
url: https://store.salesive.com/api/v1
security:
- BearerAuth: []
ShopIdHeader: []
paths:
/coupons/apply:
post:
summary: Apply coupon to order
description: >-
Apply a validated coupon code to a pending order and automatically
calculate the discount.
parameters:
- $ref: '#/components/parameters/XShopIdHeader'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- orderId
- code
properties:
orderId:
type: string
description: Order ID to apply the coupon to.
example: 67890abcdef1234567890abc
code:
type: string
description: Coupon code to apply (case-insensitive).
example: SUMMER20
responses:
'200':
description: Coupon applied successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/ApplyCouponResponse'
'400':
description: Invalid request (order already has coupon, invalid status, etc.).
'401':
description: Authentication required.
'403':
description: Unauthorized access to order.
'404':
description: Order or coupon not found.
components:
parameters:
XShopIdHeader:
name: x-shop-id
in: header
description: >-
Optional identifier that scopes responses to a specific storefront when
the referer cannot be inferred.
required: false
schema:
type: string
schemas:
ApplyCouponResponse:
type: object
required:
- status
- success
- message
- data
properties:
status:
type: integer
example: 200
success:
type: boolean
example: true
message:
type: string
example: Coupon applied successfully
data:
type: object
properties:
order:
type: object
properties:
_id:
type: string
description: Order identifier.
orderId:
type: number
description: Human-readable order number.
subtotal:
type: number
description: Order subtotal before shipping and discount.
shippingCost:
type: number
description: Shipping cost for the order.
discount:
type: number
description: Discount amount applied by the coupon.
total:
type: number
description: Final order total (subtotal + shipping - discount).
coupon:
type: object
description: Applied coupon details.
properties:
_id:
type: string
description: Coupon identifier.
code:
type: string
description: Coupon code.
type:
type: string
enum:
- fixed
- percentage
description: Coupon type.
discount:
type: number
description: Discount value.
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: JWT issued by the Salesive Store API for authenticated shoppers.
ShopIdHeader:
type: apiKey
in: header
name: x-shop-id
description: >-
Optional storefront identifier sent as a header to scope responses to a
specific shop. Try It requests remember this value once provided.
````