Orders
Some promotions might depend on the purchase history of customers. To model these scenarios in Voucherify, you can use the Order object. An order stores the cart structure (products and SKUs), the total amount of a transaction, and status: CREATED
, PAID
, CANCELED
, FULFILLED
. You can track orders in the dashboard and with the API.
Object definition
Mapping your order workflow
We designed the order entity so that it helps you map your e-commerce process. Go through these concepts to understand how you can integrate orders into your workflow.
Order identifier
Similarly to the customer object, you can use source_id
field to identify orders using your system id (external id). Besides source_id
, Voucherify automatically assigns a unique internal id to each created order.
Once you pass a new order, it is saved in Voucherify. You can refer to the particular order using its id
or source_id
Create order
An order can be created in two ways:
- By passing
order
as payload in redemption request. - With create order endpoint. You can later link this order to a corresponding redemption with
id
orsource_id
. In this case, it's not necessary to provide the payload again – if you do so, however, the object will be upserted.
Order status
If you provide the status field in the redemption payload, it will override a linked order status.
- If a redemption request is successful, Voucherify will set a related order to
PAID
. - Otherwise, the status will remain the same or will get the value from the request payload.
- A successful rollback operation will set the order to
CANCELED
. - If this behavior is not expected, you should pass the status field (e.g.
PAID
) in the request body of the rollback request.
Order-based validation rules
Validation rules can work with orders twofold:
- Introduce thresholds on cart structure and volume.
- Count the number of purchases in a timeframe or total amount of these purchases.
See this guide for more details.
Stacking discounts
Voucherify lets you apply many discounts to the same order. It comes down to the following steps:
- Redeem the first discount by calling the redemption API and pass order details in the request body. In response, Voucherify returns a unique order id with an applied discount.
- To apply the 2nd and further discounts, you need to redeem each discount using a separate API call with the same order id in the request body.
Read more about Stacking discounts.
Order session
Each time you use particular order in your requests, the API automatically triggers a new session linked to the order id. The session is active during the request and ends asynchronously after the request is completed. The session mechanism provides that the particular order id can be used in one API request at once.
Updated 6 days ago