Versions
Records that both the store and an integration change have a version that grows with every change: categories, products and variants, customers, draft orders, recommendation rules and webhook endpoints. A single record comes with it in the ETag header, ETag: "7"; in a list each record has version.
Variants share the version of their product: a change of the product or of any of its variants moves it. The version of a variant and of its product are the same number. Nested records work the same way: product photos are changed under the version of the product, customer addresses under the version of the customer. Customer tax details have a version of their own, separate from the customer.
Change under a version
A change or a deletion of a versioned record needs its version in If-Match. The response brings the new one:
curl -X PATCH "https://api.saleya.app/v1/variants/1042" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H 'If-Match: "7"' \
-H 'Idempotency-Key: 5d2c1f0e-8b7a-4c3d-9e2f-1a0b9c8d7e6f' \
-H "Content-Type: application/json" \
-d '{
"price": 129900
}'HTTP/1.1 200 OK
ETag: "8"If the record changed after you read it, the request changes nothing:
curl -X PATCH "https://api.saleya.app/v1/variants/1042" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H 'If-Match: "7"' \
-H 'Idempotency-Key: 9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d' \
-H "Content-Type: application/json" \
-d '{
"price": 129900
}'HTTP/1.1 412 Precondition Failed
{
"type": "precondition_failed",
"title": "The record has changed",
"status": 412,
"detail": "The version in If-Match does not match the record: it was changed after it was read, or the If-None-Match condition is false. Read the record again, apply your change to it and repeat the request with the new ETag."
}| Response | When |
|---|---|
412 precondition_failed | The version is not current: the record changed after you read it. |
428 precondition_required | There is no If-Match. * is not a version and is rejected too. |
On 412
- Read the record again.
- Apply your change to what is there now — or decide that it is no longer needed.
- Send it with the new
ETag.
Writing by external ID
Writing by external ID — the ID of the record in your system — such as PATCH /products/by-external-id/{external_id}, creates the record when there is none and changes it when there is. If-Match is optional here; with it, the record must exist in that version. If-None-Match: * means only create: an existing record gets 412.
Stock has no version
Stock changes too often for a version. Setting stock carries the quantity you counted against, expected_on_hand, and gets 409 stock_on_hand_changed if the stock moved. Receiving and writing off changes stock by an amount and needs no check.