Apply voucher and coupon codes with the Booking API

Use this guide to add a code field to your cart. One mutation handles voucher numbers, coupon codes and promotion codes, so customers can enter any of them in the same field.

Before you start

• A cart and its cart token. The Booking API quickstart shows how to create one.
• A code to test with, such as the number of a voucher with remaining value.

Apply a code

Send the code exactly as the customer entered it, with the cart token as id.

mutation ApplyCode($input: RequestApplyCodeInput!) {
  requestApplyCode(input: $input) {
    request {
      vouchers {
        number
        value
      }
      discounts {
        label
        value
        coupon {
          number
        }
      }
      totalGrossValue
    }
    followUpProducts {
      id
      name
    }
    followUpPriceValue
    errors {
      key
      message
      messageTranslated
    }
  }
}

{ "input": { "id": "<cart token>", "code": "3278598764" } }

{
  "data": {
    "requestApplyCode": {
      "request": {
        "vouchers": [{ "number": "3278598764", "value": { "amount": -1000, "currency": "EUR" } }],
        "discounts": [],
        "totalGrossValue": { "amount": 1000, "currency": "EUR" }
      },
      "followUpProducts": null,
      "followUpPriceValue": null,
      "errors": null
    }
  }
}

Show the result from the returned cart:

When the code cannot be applied, the cart is unchanged and errors explains why. Show messageTranslated next to the code field, for example "This code cannot be used". Decide how to react from message.

Applying a voucher does not reserve its balance. Send each code mutation in its own request, and refresh the displayed totals from the returned cart.

Redeem a voucher for a product

Some vouchers are redeemed for a specific product, such as a guided tour. When the customer enters such a voucher, the response contains an error with the key requestItem and lists the products the voucher can be redeemed for in followUpProducts.

This first response only asks for the choice: the code is not applied yet, and request can be empty. Let the customer choose one of these products, then apply the code again with the product as requestItem, including offerableId, offerableType, and pricings with the price origin and quantity. KORONA Event adds the product to the cart as a new line and redeems the voucher for it.

followUpPriceValue is the price the voucher transfers to the chosen product. KORONA Event applies it when it adds the product, so do not send a price yourself. The Booking API cannot redeem a voucher for a line that is already in the cart.

{
  "input": {
    "id": "<cart token>",
    "code": "3278598764",
    "requestItem": {
      "offerableType": "PRODUCT",
      "offerableId": "<product id>",
      "pricings": [{ "quantity": 1, "priceOriginType": "PRODUCT", "priceOriginId": "<product id>" }]
    }
  }
}

Remove a code

Remove a voucher with its number, or a coupon with its coupon.number.

mutation RemoveCode($input: RequestRemoveCodeInput!) {
  requestRemoveCode(input: $input) {
    request {
      vouchers {
        number
      }
    }
    errors {
      key
      message
      messageTranslated
    }
  }
}

{ "input": { "id": "<cart token>", "code": "3278598764" } }

Related articles

• Booking API quickstart
• Complete checkout and take payment with the Booking API