Idempotency

Retry a creating request safely, without doing the work twice.

Overview

An Idempotency-Key is a value of your own that marks a request as one action, however many times you send it.

Why it matters

If a connection drops after you send a request, you cannot tell whether O2M received it. An Idempotency-Key lets you send it again safely: O2M does the work once and gives every retry the first answer.

How to use it

Add the header with a value of your own, up to 200 characters. Use something tied to the action, such as your order number. A new action needs a new value.

cURL

curl -X POST "https://api.o2m.in/api/v1/goods-receipts" \
  -H "X-Access-Key: $O2M_ACCESS_KEY" \
  -H "X-Secret-Key: $O2M_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: receipt-INV-88" \
  -d '{
  "warehouse_code": "BLR",
  "invoice_no": "INV-88",
  "note": "From the factory",
  "lines": [
    {
      "sku": "MUG-BLUE",
      "qty": 100,
      "lot_no": "L-2026-10",
      "expiry_date": "2027-10-01"
    }
  ]
}'

A retry with the same value changes nothing and answers with the saved copy, marked by the header Idempotent-Replay: true.

Endpoint	Accepts Idempotency-Key
`POST /orders`	Yes. It is also safe without one: the same `order_id` on the same channel never makes a second order.
`POST /adjustments`	Yes. Always send one: without it, a retry changes stock twice.
`POST /goods-receipts`	Yes. Always send one: without it, a retry receives the goods twice.
`POST /orders/{id}/cancel`	Not needed. Cancelling an order twice is harmless.

Rules

O2M remembers a value for 30 days.
Values are shared across your company, so two keys must not use the same value for different actions.
A refused request is not remembered: fix it and send it again with the same value.

Errors

Status	Code	Message	What to do
409	—	The first request with this Idempotency-Key is still running: try again shortly	Wait a moment and retry with the same value.
422	—	This Idempotency-Key was used for another request	Use a new value for this action.
422	—	Idempotency-Key is at most 200 characters	Use a shorter value.