Versions and If-Match

While your system works with a record, someone in the store can change it. A version in If-Match makes your change apply only to the record you read.

Loading the search index…

Versions and If-Match

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:

Request
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
}'
Response
HTTP/1.1 200 OK
ETag: "8"

If the record changed after you read it, the request changes nothing:

Request
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
}'
Response
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."
}
ResponseWhen
412 precondition_failedThe version is not current: the record changed after you read it.
428 precondition_requiredThere is no If-Match. * is not a version and is rejected too.

On 412

  1. Read the record again.
  2. Apply your change to what is there now — or decide that it is no longer needed.
  3. 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.

Next guideRate limits