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"
}
'

import requests

url = "https://store.salesive.com/api/v1/coupons/apply"

payload = {
    "orderId": "67890abcdef1234567890abc",
    "code": "SUMMER20"
}
headers = {
    "Authorization": "Bearer <token>",
    "x-shop-id": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <token>',
    'x-shop-id': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({orderId: '67890abcdef1234567890abc', code: 'SUMMER20'})
};

fetch('https://store.salesive.com/api/v1/coupons/apply', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://store.salesive.com/api/v1/coupons/apply",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'orderId' => '67890abcdef1234567890abc',
    'code' => 'SUMMER20'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "x-shop-id: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://store.salesive.com/api/v1/coupons/apply"

	payload := strings.NewReader("{\n  \"orderId\": \"67890abcdef1234567890abc\",\n  \"code\": \"SUMMER20\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("x-shop-id", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://store.salesive.com/api/v1/coupons/apply")
  .header("Authorization", "Bearer <token>")
  .header("x-shop-id", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"orderId\": \"67890abcdef1234567890abc\",\n  \"code\": \"SUMMER20\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://store.salesive.com/api/v1/coupons/apply")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["x-shop-id"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"orderId\": \"67890abcdef1234567890abc\",\n  \"code\": \"SUMMER20\"\n}"

response = http.request(request)
puts response.read_body

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

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"
}
'

import requests

url = "https://store.salesive.com/api/v1/coupons/apply"

payload = {
    "orderId": "67890abcdef1234567890abc",
    "code": "SUMMER20"
}
headers = {
    "Authorization": "Bearer <token>",
    "x-shop-id": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <token>',
    'x-shop-id': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({orderId: '67890abcdef1234567890abc', code: 'SUMMER20'})
};

fetch('https://store.salesive.com/api/v1/coupons/apply', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://store.salesive.com/api/v1/coupons/apply",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'orderId' => '67890abcdef1234567890abc',
    'code' => 'SUMMER20'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "x-shop-id: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://store.salesive.com/api/v1/coupons/apply"

	payload := strings.NewReader("{\n  \"orderId\": \"67890abcdef1234567890abc\",\n  \"code\": \"SUMMER20\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("x-shop-id", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://store.salesive.com/api/v1/coupons/apply")
  .header("Authorization", "Bearer <token>")
  .header("x-shop-id", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"orderId\": \"67890abcdef1234567890abc\",\n  \"code\": \"SUMMER20\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://store.salesive.com/api/v1/coupons/apply")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["x-shop-id"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"orderId\": \"67890abcdef1234567890abc\",\n  \"code\": \"SUMMER20\"\n}"

response = http.request(request)
puts response.read_body

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

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

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

Order is updated with the coupon ID and discount amount
Coupon usage count is incremented globally
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

Show child attributes

Verify coupon Subscribe to newsletter

Overview

Authentication

Banners

Blogs

Cart

Comments

Country

Coupons

Newsletter

Orders

Payments

Products

Push Subscriptions

Reviews

Shipping

Shipping address

Shop

User

Wishlist

Apply coupon to order

Request

Headers

Body parameters

Successful response

Response fields

Validation checks

Side effects

Error responses

Order not found

Unauthorized access

Coupon already applied

Invalid order status

Invalid coupon

Best practices

Authorizations

Headers

Body

Response

​Request

​Headers

​Body parameters

​Successful response

​Response fields

​Validation checks

​Side effects

​Error responses

​Order not found

​Unauthorized access

​Coupon already applied

​Invalid order status

​Invalid coupon

​Best practices

Authorizations

Headers

Body

Response

Request

Headers

Body parameters

Successful response

Response fields

Validation checks

Side effects

Error responses

Order not found

Unauthorized access

Coupon already applied

Invalid order status

Invalid coupon

Best practices