External promotions
How to manage custom promotions via external services
Besides the promotion types that are supported out-of-the-box (percentage discount, fixed amount, free shipping, free gift, and fixed price) Commerce Layer lets you integrate any kind of promotional engine as an external promotion.
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.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:marketline_itemsline_items.itemshipping_addressbilling_address
{
"data": {
"id": "wBXVhKzrnq",
"type": "orders",
"links": { ... },
"attributes": { ... },
"relationships": { ... },
"meta": { ... }
},
"included": [
{
"id": "DvlGRmhdgX",
"type": "markets",
"links": { ... },
"attributes": { ... },
"relationships": { ... },
"meta": { ... }
},
{
"id": "kdPgtRXOKL",
"type": "line_items",
"links": { ... },
"attributes": { ... },
"relationships": { ... },
"meta": { ... }
},
{
"id": "XGZwpOSrWL",
"type": "skus",
"links": { ... },
"attributes": { ... },
"relationships": { ... },
"meta": { ... }
}
{
"id": "BgnguJvXmb",
"type": "addresses",
"links": { ... },
"attributes": { ... },
"relationships": { ... },
"meta": { ... }
},
{
"id": "AlrkugwyVW",
"type": "addresses",
"links": { ... },
"attributes": { ... },
"relationships": { ... },
"meta": { ... }
},
{ ... }
]
}
Your service response (or error) must match the format described in the example below.
Response
Error
The successful response must be a JSON object, returning the discount computed by the external logic, along with some additional information and metadata:
{
"success": true,
"data": {
"name": "My External Promotion",
"discount_cents": 1500,
"metadata": {
"foo": "bar"
}
}
}
On error, you must respond with an HTTP code >=
400. The response body must be a JSON object containing any other relevant error code and message:{
"success": false,
"error": {
"code": "YOUR-ERROR-CODE",
"message": "Your error message"
}
}
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.
Last modified 1yr ago