Important information on applying rewards to an order
The endpoint to call for applying a promotion to a customer's order is the Reward API /applyendpoint. Below are some key information you need to know when using this endpoint.
When you make a request to the /apply, you are, in effect, asking the system to apply promotions or rewards to a specific order. The response from this API call will include information about the promotions that were successfully applied to the order.
Below are some key concepts to understand:
Applied Promotions
The API response will contain information about all the promotions that have been applied to the order. This includes both automatic promotions that the order qualifies for and any promotions or coupon codes that you specified in your request.
Updating an Order
It is important to note that you should always pass back the array of applied promotions in the Order object with subsequent requests. This enables the system to revalidate the applied promotions against the updated cart or order. In other words, when you send a new request to apply promotions, you should include the list of previously applied promotions so that the system can check if they still qualify based on any changes made to the order.
Initial Request
When you make the first request to this endpoint, the applied promotion array will typically be empty because no promotions have been applied to the order yet. In such cases, the response will only contain information about any automatically applied promotions that the order qualifies for and any promotions applied based on the coupon code or promotion ID you provided in the request.
To ensure your integration supports automatic promotions, it is required that you send the Apply Reward request with the initial cart load and subsequent changes even if the customer has not attempted to apply a code. This allows the Reward API to apply any automatic promotions for which the order qualifies.
If no automatic promotions are found to be applicable and the customer doesn’t try to apply any new codes or promotions, the response will contain no applied promotions and no errors.
Removing Applied Promotions
If you need to remove a promotion from an order (for example, when a customer manually removes a promotion from their order), you can simply remove that specific promotion from the appliedPromotions array and then send the updated order with the next request to the apply endpoint. This will effectively remove the promotion from the order.
Cart Changes
It is recommended to call this endpoint as described above whenever the customer's cart is loaded or when changes are made to the order. This ensures that the order continues to meet the rules of each promotion, and any promotions that are no longer valid based on the changes are removed.
Reward Application Errors
When a request is made to the Apply Reward endpoint to apply a coupon code that does not meet the criteria of the promotion, the endpoint may return multiple errors in the errors array of the response.
This array will include errors for all parts of the rules that the order fails to meet as well as any other violations (e.g. "Promotion expired") or technical errors.
There are use cases whereby a single promotion has multiple criteria that a customer order must meet, such as minimum spend and customer 'type' rules. In this scenario, both errors will be returned so you are able to inform the customer of the violations at once (e.g. You must be a new customer and you must be spending at least $100 to
get this reward). In this specific example, there will be two errors with the errorId custom_rule_violation.
See Errors page for technical information about the different errors and their respective structure.