Skip to content
Dukkan DevelopersDocs
العربيةSign in

Inventory

2 operations

GET/inventory/movements#

List append-only inventory movements

inventory:read

Parameters

NameTypeDescription
cursorquerystring
limitqueryinteger
Default:50

Responses

200

Movement page

NameTypeDescription
dataRequiredMovement[]
next_cursorRequirednullablestring

Pass back as cursor to fetch the next page; null on the last page.

  • 401

    Missing, invalid, expired, or revoked token

  • 403

    Required live scope is missing

  • 429

    Token budget exhausted (180 requests/minute, 60 writes/minute per install)

Request
curl -X GET "https://dukkan.one/platform-api/v1/inventory/movements?limit=50" \
  -H "Authorization: Bearer $DUKKAN_ACCESS_TOKEN"
Response
{
  "data": [
    {
      "id": "6f1d2c3b-4a59-4e8f-9b70-2d1c3e4f5a6b",
      "sequence": 1661,
      "variant_id": "6f1d2c3b-4a59-4e8f-9b70-2d1c3e4f5a6b",
      "location_id": "6f1d2c3b-4a59-4e8f-9b70-2d1c3e4f5a6b",
      "delta": -2,
      "stock_after": 38,
      "reason": "correction",
      "occurred_at": "2026-08-18T16:00:00Z"
    }
  ],
  "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wOC0xOFQxNjowMDowMFoifQ"
}

POST/inventory/movements#

Append an inventory movement; absolute stock writes are forbidden

inventory:writeIdempotent

The response never includes the resulting absolute stock; read the movement list or the product for that.

Parameters

NameTypeDescription
Idempotency-KeyheaderRequiredstring

Unique per logical write, at most 200 characters, remembered for 24 hours. Replaying the same key with the same body returns the recorded response; the same key with a different body answers 409.

Request body Required

Append an inventory movement.

NameTypeDescription
variant_idRequiredstring
location_idRequiredstring
deltaRequiredinteger

Signed quantity change. Absolute stock writes are forbidden.

reasonRequiredstring
Values:correctioninitialreturndamage
notenullablestring

Responses

201

Movement appended

No response body.

  • 400

    Invalid request

  • 401

    Missing, invalid, expired, or revoked token

  • 403

    Required live scope is missing

  • 404

    Resource not found in the token-bound store

  • 409

    State transition, inventory, refund, or idempotency conflict

  • 429

    Token budget exhausted (180 requests/minute, 60 writes/minute per install)

Request
curl -X POST "https://dukkan.one/platform-api/v1/inventory/movements" \
  -H "Authorization: Bearer $DUKKAN_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "variant_id": "6f1d2c3b-4a59-4e8f-9b70-2d1c3e4f5a6b",
  "location_id": "6f1d2c3b-4a59-4e8f-9b70-2d1c3e4f5a6b",
  "delta": -2,
  "reason": "correction",
  "note": "Stock count 2026-08-18"
}'
Response
{
  "error": {
    "code": "invalid_request",
    "message": "A human-readable explanation",
    "request_id": "req_01J8Z1K5X9",
    "details": {}
  }
}