This guide will lead you to buy a product and apply the promo once it is into the cart. We assume you have a promo configured properly for being applied to the product you bought.
Please make sure you read the Conventions before continuing with this guide.
Prerequisites
You will need an X-API-KEY and a username and password to authenticate.
Steps to complete a purchase
Follow steps 1 to 7 on making a reservation purchase
Auto-apply promos (optional)
Some promotions are configured in Inventory with auto apply. You do not need to call Find a promo or Apply the promo for those when the conditions below are met.
When a reservation (or other supported line) is added to the cart, Sales may load auto-apply promotions from Inventory and evaluate them while the line is priced. If a rule matches the trip, product, channel, and other rule constraints, the discount is applied immediately. On tickets and cart summaries, an applied auto promo is marked with autoApplied: true on the promo details so you can tell it was not typed in by the customer.
When auto-apply is evaluated
- The cart request must use a backoffice sales
channel(the samechannelyou send on the add to cart payload). Auto-apply lists are not loaded for other channels; for websales and similar channels, continue to apply codes explicitly (Apply the promo orPOST /cart/{cartId}/promos). - The line must not already be requesting specific promo codes. In practice, send an empty
promo/promoson the reservation item so Sales can load the auto-apply set from Inventory instead of resolving named codes first. - Promotions must be enabled for auto apply in Inventory for your provider, channel, and product (and, for multi-product trips, mapped segment products may load additional eligible promos).
If no auto-apply promo matches, pricing proceeds without a promo; you can still apply a manual code afterward as in the steps below.
Grouping lines with operationId
Include a stable operationId (singular; this is the field name on the cart JSON body) on each POST that should belong to the same checkout operation. All tickets added with the same operationId are grouped for cart logic (for example, promo rules that require a minimum number of passengers in the same operation, or requireSameOperation in Inventory, only count lines that share that id). If you omit operationId, the API generates a new one per request, which typically splits passengers into separate operations. See Working with the cart payload examples for where to place operationId.
8) Find a promo to apply
Find a promo that contains a rule that could be applied for your selected product, fares, origin, destination, and travel date(s).
From the results, select a single promo and remember it's name that is going to be used in the next step.
9) Add the promo to the cart
Apply the promo to the cart. The cart returned should contains the given promo applied to the item added on step 6.
10) Complete purchase
Continue with steps 8 to 11 from making a reservation purchase.
11) Postman resources
If you would like to use Postman to test the API, we have included a collection you can use as a starting point below.
This collection is designed to allow you to purchase a reservation and then apply a promo. In order to use it successfully, you will need your x-api-key, a valid promo for your product, and valid stations and routes set up. In this example, we create a customer, but you can use an existing customer if you prefer.
After importing the collection, and the environment, make sure your collection is using the new environment, and that you have set the values. Variables that start with "YOUR_" will need to be replaced with a value specific to your situation. If you are going to be using our API in sandbox, please change the {{basePath}} environment variable to https://sandbox-api.betterez.com.