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

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.

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

PHP Example

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

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

$signatureVerifier = new \BoltPay\SignatureVerifier(

$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');

if (@$requestData->type == 'discounts.code.apply') {
    $couponCode = @$requestData->discount_code;
    if ($couponCode == \BoltPay\Example\Data::VALID_COUPON) {

        $response = [
            'status' => 'success',
            'discount_code' => $couponCode,
            'discount_amount' => 1000,
            'description' => 'Discount (BOLT-DEMO)',
            'discount_type' => 'fixed_amount'

    } else {
        $error = new Exception("Coupon code is invalid");
        $response = [
            'status' => 'failure',
            'error' => [
                'code' => $error->getCode(),
                'message' => $error->getMessage(),


echo json_encode($response);


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.

  1. Open Bolt Checkout and enter a discount code.
  2. Bolt should hit your discount merchant API.
  3. If the discount is valid, check that Bolt applies the correct discount amount to the cart.
  4. 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.

Filter by Section
Filter by Topic