External prices

Getting started API reference How-tos Changelog
Search…
External prices
How to manage prices via external services
Sometimes, you can decide not to manage prices within Commerce Layer but use an external service instead. The reason can be to support more dynamic pricing or just leverage an existing service that you want to keep as your system of records.
If you want to support external prices in a market, fill in the market's external_price_url field with your external service endpoint and make sure your service supports the specification described below.
Fetching external prices
When you add a line item to an order, set the _external_price attribute to true if you want the line item price to be provided by your external service, instead of Commerce Layer:
1
curl -g -X POST \
2
  'https://yourdomain.commercelayer.io/api/line_items' \
3
  -H 'Accept: application/vnd.api+json' \
4
  -H 'Authorization: Bearer your-access-token' \
5
  -H 'Content-Type: application/vnd.api+json' \
6
  -d '{
7
  "data": {
8
    "type": "line_items",
9
    "attributes": {
10
      "quantity": 2,
11
      "sku_code": "TSHIRTMM000000FFFFFFXLXX",
12
      "_external_price": true
13
    },
14
    "relationships": {
15
      "order": {
16
        "data": {
17
          "type": "orders",
18
          "id": "QWERtyUpBa"
19
        }
20
      }
21
    }
22
  }
23
}'
Copied!
Upon line item creation, Commerce Layer triggers a POST request to the specified external_price_url endpoint, sending the line item payload (including the order) 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 — line_items in the specific case — some relationships are also included to avoid useless API roundtrips:
order
order.market
item
1
{
2
  "data": {
3
    "id": "xYZkjABcde",
4
    "type": "line_items",
5
    "links": { ... },
6
    "attributes": {
7
      "quantity": 2,
8
      "sku_code": "TSHIRTMM000000FFFFFFXLXX",
9
      "_external_price": true
10
    },
11
    "relationships": { ... },
12
    "meta": { ... }
13
  },
14
  "included": [
15
    {
16
      "id": "wBXVhKzrnq",
17
      "type": "orders",
18
      "links": { ... },
19
      "attributes": { ... },
20
      "relationships": { ... },
21
      "meta": { ... }
22
    },
23
    {
24
      "id": "DvlGRmhdgX",
25
      "type": "markets",
26
      "links": { ... },
27
      "attributes": { ... },
28
      "relationships": { ... },
29
      "meta": { ... }
30
    },
31
    {
32
      "id": "XGZwpOSrWL",
33
      "type": "skus",
34
      "links": { ... },
35
      "attributes": { ... },
36
      "relationships": { ... },
37
      "meta": { ... }
38
    }
39
  ]
40
}
Copied!
Response
Your service response (or error) must match the format described in the example below.
Example
Response
Error
The successful response must be a JSON object, returning the unit price computed by the external logic and the SKU code of the related product, along with some additional information and metadata:
1
{
2
  "success": true,
3
  "data": {
4
    "sku_code": "TSHIRTMM000000FFFFFFXLXX",
5
    "unit_amount_cents": 4900,
6
    "metadata": {
7
      "foo": "bar"
8
    }
9
  }
10
}
Copied!
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:
1
{
2
  "success": false,
3
  "error": {
4
    "code": "YOUR-ERROR-CODE",
5
    "message": "Your error message"
6
  }
7
}
Copied!
SKUs availability
When you fetch a list of SKUs with a sales channel application, you only get those SKUs that have a price defined in the market's price list and at least a stock item in one of the market stock locations.
In case you manage prices externally, the price filter is not considered.
Security
When you activate external prices support for a market, 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 security
External payment gateways
External promotions
Last modified 1mo ago
Copy link
Contents
Fetching external prices