Skip to main content
POST
/
coupons
/
apply
Apply coupon to order
curl --request POST \
  --url https://store.salesive.com/api/v1/coupons/apply \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-shop-id: <api-key>' \
  --data '
{
  "orderId": "67890abcdef1234567890abc",
  "code": "SUMMER20"
}
'
{
  "status": 200,
  "success": true,
  "message": "Coupon applied successfully",
  "data": {
    "order": {
      "_id": "<string>",
      "orderId": 123,
      "subtotal": 123,
      "shippingCost": 123,
      "discount": 123,
      "total": 123,
      "coupon": {
        "_id": "<string>",
        "code": "<string>",
        "discount": 123
      }
    }
  }
}

​
Request

POST /coupons/apply
Content-Type: application/json
x-shop-id: {shopId}
Authorization: Bearer {token}
{
  "orderId": "67890abcdef1234567890abc",
  "code": "SUMMER20"
}

​
Headers

HeaderTypeDescription
Content-TypestringAlways set to application/json.
x-shop-idstringShop identifier to associate the user with your store.
AuthorizationstringBearer token for authenticated user (required).
This endpoint requires authentication. Only the order owner can apply coupons to their orders.

​
Body parameters

FieldTypeRequiredDescription
orderIdstringYesOrder ID to apply the coupon to.
codestringYesCoupon code to apply (case-insensitive).

​
Successful response

{
    "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

FieldTypeDescription
order._idstringOrder identifier.
order.orderIdnumberHuman-readable order number.
order.subtotalnumberOrder subtotal before shipping and discount.
order.shippingCostnumberShipping cost for the order.
order.discountnumberDiscount amount applied by the coupon.
order.totalnumberFinal order total (subtotal + shipping - discount).
order.couponobjectApplied 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

{
    "status": 404,
    "success": false,
    "message": "Order not found"
}

​
Unauthorized access

{
    "status": 403,
    "success": false,
    "message": "Unauthorized access to order"
}

​
Coupon already applied

{
    "status": 400,
    "success": false,
    "message": "Order already has a coupon applied"
}

​
Invalid order status

{
    "status": 400,
    "success": false,
    "message": "Coupon can only be applied to pending orders"
}

​
Invalid coupon

{
    "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.

Authorizations

​
Authorization
string
header
required

JWT issued by the Salesive Store API for authenticated shoppers.

​
x-shop-id
string
header
required

Optional storefront identifier sent as a header to scope responses to a specific shop. Try It requests remember this value once provided.

Headers

​
x-shop-id
string

Optional identifier that scopes responses to a specific storefront when the referer cannot be inferred.

Body

application/json
​
orderId
string
required

Order ID to apply the coupon to.

Example:

"67890abcdef1234567890abc"

​
code
string
required

Coupon code to apply (case-insensitive).

Example:

"SUMMER20"

Response

Coupon applied successfully.

​
status
integer
required
Example:

200

​
success
boolean
required
Example:

true

​
message
string
required
Example:

"Coupon applied successfully"

​
data
object
required