External promotions
How to manage custom promotions via external services
When an external promotion activates — i.e. its activation rules are met — Commerce Layer triggers a POST
request to the promotion_url
endpoint, sending the order payload (including its line items) in the request body.
Request
The request payload is a JSON:API compliant object you can query to perform your own computation. Aside from the target resource — orders
in the specific case — some relationships are also included to avoid useless API roundtrips:
market
customer
customer.tags
line_items
line_items.item
shipping_address
billing_address
In case the call to your external endpoint goes timeout, responds with an internal server error, or is blocked by the open circuit breaker, the API keeps responding with a 200 OK
status code. No promotion is added to the order and the circuit breaker internal counter (if closed) is incremented.
Response
Your service response (or error) must match the format described in the examples below.
Applying the discount to all taxable items of the order
The successful response must be a JSON object, returning the discount computed by the external logic, along with some additional information and metadata:
Applying the discount to specific taxable items
The successful response must be a JSON object, returning the discount computed by the external logic to be applied to the specified line items, along with some additional information and metadata:
Applying a specific discount to specific taxable items
The successful response must be a JSON object, returning a specific discount computed by the external logic to be applied to the specified line items, along with some additional information and metadata:
If you are going to specify the discount_cents
key for the single line items, make sure to do it for all of the elements of the line_items
array. Keep in mind that the promotion amount is computed and distributed only for the line items whose IDs are listed in the array with a discount_cents
key specified. In this case, avoid adding the discount_cents
key at order the level because it's ignored if there is any line item with a specific discount_cents
key set.
Security
When you create a new external promotion, a shared secret is generated. We recommend verifying the callback authenticity by signing the payload with that shared secret and comparing the result with the callback signature header.
Callbacks securityLast updated