📍 Bolt Help / Platforms / Direct API / Custom Cart Integration / Apply Discounts

Apply Discounts

How to call the Merchant Callback API and verify discount codes submitted by a shopper.

Page Contents

Click to expand.

Use the Merchant Callback API to handle shopper’s coupons, promo codes, or other discounts added to their carts.

How to Use the Discounts API

The discounts.code.apply endpoint is called when a shopper enters a discount code; it is recalled whenever the cart or chosen shipping option is updated.

Implement the discount Merchant Callback API on your server.
Verify the authenticity of the request by confirming that it originated from Bolt.
Respond to Bolt’s discounts.code.apply POST request via your Merchant Callback API.

Request

The envelope and the cart encoding follow the Merchant Callback conventions. This event carries a full cart snapshot, so its amounts are objects rather than integers.

{
  "event": "discounts.code.apply",
  "data": {
    "discount_code": "BOLT-DEMO",
    "customer_name": "Jane Doe",
    "customer_email": "jane@example.com",
    "customer_phone": "+14155550199",
    "order_id": 811223,
    "cart": {
      "order_reference": "order_100",
      "total_amount": { "amount": 41200, "currency": "USD", "currency_symbol": "$" }
    }
  }
}

Response

Return the discount you are granting inside data. Unlike the cart amounts above, discount_amount is a plain integer in the currency’s minor units.

{
  "event": "discounts.code.apply",
  "status": "success",
  "data": {
    "discount_code": "BOLT-DEMO",
    "description": "Discount (BOLT-DEMO)",
    "discount_type": "fixed_amount",
    "discount_amount": 1000
  }
}

description is the label the shopper sees in the cart. Bolt reads description, not discount_description.

discount_type is one of:

Value	Meaning
`fixed_amount`	`discount_amount` is subtracted from the total
`percentage`	`discount_amount` is a percentage
`free_shipping`	Shipping cost is waived

To reject a code, set status to failure and return a single error object. Bolt rejects a failure payload for this event even when the HTTP status is 200, so a rejection here is a normal 200 response:

{
  "event": "discounts.code.apply",
  "status": "failure",
  "error": {
    "code": 2319,
    "message": "Order total must be more than $100 to apply this discount."
  }
}

PHP Example

<?php
require(dirname(__FILE__) . '/init_example.php');

$hmacHeader = @$_SERVER['HTTP_X_BOLT_HMAC_SHA256'];

$signatureVerifier = new \BoltPay\SignatureVerifier(
    \BoltPay\Bolt::$signingSecret
);

$requestJson = file_get_contents('php://input');

if (!$signatureVerifier->verifySignature($requestJson, $hmacHeader)) {
    throw new Exception("Failed HMAC Authentication");
}

$requestData = json_decode($requestJson);
header('Content-Type: application/json');

// Bolt wraps every callback as {event, data}.
if (@$requestData->event == 'discounts.code.apply') {
    $couponCode = @$requestData->data->discount_code;

    if ($couponCode == \BoltPay\Example\Data::VALID_COUPON) {
        $response = [
            'event' => 'discounts.code.apply',
            'status' => 'success',
            'data' => [
                'discount_code' => $couponCode,
                'description' => 'Discount (BOLT-DEMO)',
                'discount_type' => 'fixed_amount',
                'discount_amount' => 1000,
            ],
        ];
    } else {
        $response = [
            'event' => 'discounts.code.apply',
            'status' => 'failure',
            'error' => [
                'code' => 2319,
                'message' => 'Coupon code is invalid',
            ],
        ];
    }

    http_response_code(200);
    echo json_encode($response);
}

WARNING

Applying a discount amount that is more than the total order amount will result in an error. It is recommended you calculate a max allowable discount amount using the formula line item totals + tax + shipping = max allowable discount.

How to Test

To ensure this step is complete, precisely follow the instructions below.

Open Bolt Checkout and enter a discount code.
Bolt should hit your discount merchant API.
If the discount is valid, check that Bolt applies the correct discount amount to the cart.
Repeat the test with an invalid discount too ensure that Bolt:
- Does not apply any discount amount.
- Correctly alerts the user.

Handling Errors

To respond with specific errors in merchant api responses visit the error codes reference article.