Web shop orders

Called with shop (retail) account keys. A key only sees its own account's data. Every example uses the same sample brand, order and item, so you can follow one item from call to call.

Base URL http://62.169.23.239:8001/api/v1Auth Bearer token10 endpoints

Endpoints

POST/retail/integrations/fulfillment/ordersCreate a web order
GET/retail/integrations/fulfillment/tasksList order tasks
GET/retail/integrations/fulfillment/tasks/{task_id}Retrieve an order task
POST/retail/integrations/fulfillment/tasks/{task_id}/shippedReport shipped
POST/retail/integrations/fulfillment/tasks/{task_id}/deliveredReport delivered
POST/retail/integrations/fulfillment/tasks/{task_id}/cancelCancel an order task
POST/retail/integrations/fulfillment/tasks/{task_id}/lostReport a lost parcel
POST/retail/integrations/fulfillment/tasks/{task_id}/returnStart a return
POST/retail/integrations/fulfillment/tasks/{task_id}/return-lostSettle a lost return
POST/retail/integrations/fulfillment/tasks/{task_id}/dispute-nondeliveryResolve a non-delivery dispute

Create a web order#

POST/retail/integrations/fulfillment/orders

Requires scope web_orders:write

A customer bought online: queue one task per unit to pick. Links no passport and transfers nothing. Lines already queued are skipped.

Request body

external_order_idstringRequired
Your web shop's own order id. Skannit keys the order on it, so sending it twice does not create it twice.
order_referencestring | null
Order number your customer sees (for example #1001).
sourcestring
Defaults to web_shop
buyer_emailstringRequired
The passport goes to the Skannit account with this email on delivery.
buyer_namestring | null
Never returned in responses (always null).
buyer_phonestring | null
Stored only. Matching is by email. Never returned in responses (always null).
deadlinetimestamp | null
When the order is promised. Orders the pick queue.
linesarray of objectsRequired
Line items, one per variant.
+Show 6 child attributesHide child attributes
- line_idstringRequired
- product_idstring | null
  Skannit's product_id if the web shop knows it; otherwise ``sku`` is matched against the product's base SKU. No match → queued as unmatched.
- skustring | null
  Stock-keeping unit of the variant.
- variantstringRequired
  "Colour / Size", compared with the scanned unit at the pick.
- quantityinteger
  Number of units.
  Defaults to 1
- product_namestring | null

Returns

HTTP 201

itemsarray of objects
The objects on this page.
+Show 21 child attributesHide child attributes
- task_idstringRequired
  One unit of a web order to pick. An order with quantity 3 creates 3 tasks.
- sourcestringRequired
- order_referencestring | null
  Order number your customer sees (for example #1001).
- external_order_idstringRequired
  Your web shop's own order id. Skannit keys the order on it, so sending it twice does not create it twice.
- product_idstring | null
  Skannit's id for the product.
- product_namestring | null
- assigned_variantstring | null
  Colour / size the order line asks for.
- skustring | null
  Stock-keeping unit of the variant.
- quantityinteger
  Number of units.
  Defaults to 1
- buyer_emailstring | null
  GL-02: buyer identity is never sent out (always null); the order reference identifies the order. Kept in the schema only so the public v1 contract doesn't break. Stored on the task only to email the buyer.
- buyer_phonestring | null
  Stored only. Matching is by email. Never returned in responses (always null).
- buyer_namestring | null
  Never returned in responses (always null).
- deadlinetimestamp | null
  When the order is promised. Drives the queue's ordering; NULL when the provider sent no SLA.
- statusstring
  Current state of the object. See the allowed values.
  One ofpendingpickedshippeddeliveredcancelledrefusedlostreturn_requestedreturn_receivedreturnedreturn_rejected
  Defaults to pending
- linked_unit_tokenstring | null
  The unit whose passport is linked to this order (set by the pick scan).
- carrierstring | null
  Carrier name, for example PostNL or DHL.
- tracking_numberstring | null
  The carrier's tracking number.
- shipped_attimestamp | null
  When your web shop reported the parcel shipped.
- delivered_attimestamp | null
  When the parcel was reported delivered — the moment ownership moved.
- is_matchableboolean
  False when the external SKU matched no Skannit product. Such a task is visible to a worker but cannot be picked until it is mapped.
  Defaults to true
- created_attimestampRequired
  When the object was created (ISO 8601, UTC).
totalinteger
Total count.
Defaults to 0

POST /retail/integrations/fulfillment/orders

curl

curl -X POST http://62.169.23.239:8001/api/v1/retail/integrations/fulfillment/orders \
  -H "Authorization: Bearer $SKANNIT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "external_order_id": "1001",
    "order_reference": "#1001",
    "buyer_email": "customer@example.com",
    "deadline": "2026-10-11T17:00:00Z",
    "lines": [
      {
        "line_id": "line_1",
        "sku": "TT-100",
        "variant": "White / M",
        "quantity": 1,
        "product_name": "Trail Tee"
      }
    ]
  }'

201Response

json

{
  "items": [
    {
      "task_id": "266ac6a0-a008-5349-ae80-086961f95f9a",
      "source": "web_shop",
      "order_reference": "#1001",
      "external_order_id": "1001",
      "product_id": "f6abe715-90aa-5908-a0a6-12951a3a21cc",
      "product_name": "Trail Tee",
      "assigned_variant": "White / M",
      "sku": "TT-100-WHT-M",
      "quantity": 1,
      "buyer_email": null,
      "buyer_phone": null,
      "buyer_name": null,
      "deadline": null,
      "status": "pending",
      "linked_unit_token": null,
      "carrier": null,
      "tracking_number": null,
      "shipped_at": null,
      "delivered_at": null,
      "is_matchable": true,
      "created_at": "2026-10-09T09:30:00Z"
    }
  ],
  "total": 1
}

List order tasks#

GET/retail/integrations/fulfillment/tasks

Requires scope web_orders:read

Parameters

task_statusstringquery
One or more statuses, comma-separated
Defaults to pending

Returns

HTTP 200

itemsarray of objects
The objects on this page.
+Show 21 child attributesHide child attributes
- task_idstringRequired
  One unit of a web order to pick. An order with quantity 3 creates 3 tasks.
- sourcestringRequired
- order_referencestring | null
  Order number your customer sees (for example #1001).
- external_order_idstringRequired
  Your web shop's own order id. Skannit keys the order on it, so sending it twice does not create it twice.
- product_idstring | null
  Skannit's id for the product.
- product_namestring | null
- assigned_variantstring | null
  Colour / size the order line asks for.
- skustring | null
  Stock-keeping unit of the variant.
- quantityinteger
  Number of units.
  Defaults to 1
- buyer_emailstring | null
  GL-02: buyer identity is never sent out (always null); the order reference identifies the order. Kept in the schema only so the public v1 contract doesn't break. Stored on the task only to email the buyer.
- buyer_phonestring | null
  Stored only. Matching is by email. Never returned in responses (always null).
- buyer_namestring | null
  Never returned in responses (always null).
- deadlinetimestamp | null
  When the order is promised. Drives the queue's ordering; NULL when the provider sent no SLA.
- statusstring
  Current state of the object. See the allowed values.
  One ofpendingpickedshippeddeliveredcancelledrefusedlostreturn_requestedreturn_receivedreturnedreturn_rejected
  Defaults to pending
- linked_unit_tokenstring | null
  The unit whose passport is linked to this order (set by the pick scan).
- carrierstring | null
  Carrier name, for example PostNL or DHL.
- tracking_numberstring | null
  The carrier's tracking number.
- shipped_attimestamp | null
  When your web shop reported the parcel shipped.
- delivered_attimestamp | null
  When the parcel was reported delivered — the moment ownership moved.
- is_matchableboolean
  False when the external SKU matched no Skannit product. Such a task is visible to a worker but cannot be picked until it is mapped.
  Defaults to true
- created_attimestampRequired
  When the object was created (ISO 8601, UTC).
totalinteger
Total count.
Defaults to 0

GET /retail/integrations/fulfillment/tasks

curl

curl http://62.169.23.239:8001/api/v1/retail/integrations/fulfillment/tasks \
  -H "Authorization: Bearer $SKANNIT_TOKEN"

200Response

json

{
  "items": [
    {
      "task_id": "266ac6a0-a008-5349-ae80-086961f95f9a",
      "source": "web_shop",
      "order_reference": "#1001",
      "external_order_id": "1001",
      "product_id": "f6abe715-90aa-5908-a0a6-12951a3a21cc",
      "product_name": "Trail Tee",
      "assigned_variant": "White / M",
      "sku": "TT-100-WHT-M",
      "quantity": 1,
      "buyer_email": null,
      "buyer_phone": null,
      "buyer_name": null,
      "deadline": null,
      "status": "pending",
      "linked_unit_token": null,
      "carrier": null,
      "tracking_number": null,
      "shipped_at": null,
      "delivered_at": null,
      "is_matchable": true,
      "created_at": "2026-10-09T09:30:00Z"
    }
  ],
  "total": 1
}

Retrieve an order task#

GET/retail/integrations/fulfillment/tasks/{task_id}

Requires scope web_orders:read

Parameters

task_idstringpathRequired
One unit of a web order to pick. An order with quantity 3 creates 3 tasks.

Returns

HTTP 200

task_idstringRequired
One unit of a web order to pick. An order with quantity 3 creates 3 tasks.
sourcestringRequired
order_referencestring | null
Order number your customer sees (for example #1001).
external_order_idstringRequired
Your web shop's own order id. Skannit keys the order on it, so sending it twice does not create it twice.
product_idstring | null
Skannit's id for the product.
product_namestring | null
assigned_variantstring | null
Colour / size the order line asks for.
skustring | null
Stock-keeping unit of the variant.
quantityinteger
Number of units.
Defaults to 1
buyer_emailstring | null
GL-02: buyer identity is never sent out (always null); the order reference identifies the order. Kept in the schema only so the public v1 contract doesn't break. Stored on the task only to email the buyer.
buyer_phonestring | null
Stored only. Matching is by email. Never returned in responses (always null).
buyer_namestring | null
Never returned in responses (always null).
deadlinetimestamp | null
When the order is promised. Drives the queue's ordering; NULL when the provider sent no SLA.
statusstring
Current state of the object. See the allowed values.
One ofpendingpickedshippeddeliveredcancelledrefusedlostreturn_requestedreturn_receivedreturnedreturn_rejected
Defaults to pending
linked_unit_tokenstring | null
The unit whose passport is linked to this order (set by the pick scan).
carrierstring | null
Carrier name, for example PostNL or DHL.
tracking_numberstring | null
The carrier's tracking number.
shipped_attimestamp | null
When your web shop reported the parcel shipped.
delivered_attimestamp | null
When the parcel was reported delivered — the moment ownership moved.
is_matchableboolean
False when the external SKU matched no Skannit product. Such a task is visible to a worker but cannot be picked until it is mapped.
Defaults to true
created_attimestampRequired
When the object was created (ISO 8601, UTC).

GET /retail/integrations/fulfillment/tasks/{task_id}

curl

curl http://62.169.23.239:8001/api/v1/retail/integrations/fulfillment/tasks/266ac6a0-a008-5349-ae80-086961f95f9a \
  -H "Authorization: Bearer $SKANNIT_TOKEN"

200Response

json

{
  "task_id": "266ac6a0-a008-5349-ae80-086961f95f9a",
  "source": "web_shop",
  "order_reference": "#1001",
  "external_order_id": "1001",
  "product_id": "f6abe715-90aa-5908-a0a6-12951a3a21cc",
  "product_name": "Trail Tee",
  "assigned_variant": "White / M",
  "sku": "TT-100-WHT-M",
  "quantity": 1,
  "buyer_email": null,
  "buyer_phone": null,
  "buyer_name": null,
  "deadline": null,
  "status": "picked",
  "linked_unit_token": "Qm7xK2pL9vR4tY8wZ1nB3c",
  "carrier": null,
  "tracking_number": null,
  "shipped_at": null,
  "delivered_at": null,
  "is_matchable": true,
  "created_at": "2026-10-09T09:30:00Z"
}

Report shipped#

POST/retail/integrations/fulfillment/tasks/{task_id}/shipped

Requires scope web_orders:write

Parameters

task_idstringpathRequired
One unit of a web order to pick. An order with quantity 3 creates 3 tasks.

Request body

carrierstringRequired
Carrier name, for example PostNL or DHL.
tracking_numberstringRequired
The carrier's tracking number.

Returns

HTTP 200

task_idstringRequired
One unit of a web order to pick. An order with quantity 3 creates 3 tasks.
sourcestringRequired
order_referencestring | null
Order number your customer sees (for example #1001).
external_order_idstringRequired
Your web shop's own order id. Skannit keys the order on it, so sending it twice does not create it twice.
product_idstring | null
Skannit's id for the product.
product_namestring | null
assigned_variantstring | null
Colour / size the order line asks for.
skustring | null
Stock-keeping unit of the variant.
quantityinteger
Number of units.
Defaults to 1
buyer_emailstring | null
GL-02: buyer identity is never sent out (always null); the order reference identifies the order. Kept in the schema only so the public v1 contract doesn't break. Stored on the task only to email the buyer.
buyer_phonestring | null
Stored only. Matching is by email. Never returned in responses (always null).
buyer_namestring | null
Never returned in responses (always null).
deadlinetimestamp | null
When the order is promised. Drives the queue's ordering; NULL when the provider sent no SLA.
statusstring
Current state of the object. See the allowed values.
One ofpendingpickedshippeddeliveredcancelledrefusedlostreturn_requestedreturn_receivedreturnedreturn_rejected
Defaults to pending
linked_unit_tokenstring | null
The unit whose passport is linked to this order (set by the pick scan).
carrierstring | null
Carrier name, for example PostNL or DHL.
tracking_numberstring | null
The carrier's tracking number.
shipped_attimestamp | null
When your web shop reported the parcel shipped.
delivered_attimestamp | null
When the parcel was reported delivered — the moment ownership moved.
is_matchableboolean
False when the external SKU matched no Skannit product. Such a task is visible to a worker but cannot be picked until it is mapped.
Defaults to true
created_attimestampRequired
When the object was created (ISO 8601, UTC).

POST /retail/integrations/fulfillment/tasks/{task_id}/shipped

curl

curl -X POST http://62.169.23.239:8001/api/v1/retail/integrations/fulfillment/tasks/266ac6a0-a008-5349-ae80-086961f95f9a/shipped \
  -H "Authorization: Bearer $SKANNIT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "carrier": "PostNL",
    "tracking_number": "3SNWD1234567890"
  }'

200Response

json

{
  "task_id": "266ac6a0-a008-5349-ae80-086961f95f9a",
  "source": "web_shop",
  "order_reference": "#1001",
  "external_order_id": "1001",
  "product_id": "f6abe715-90aa-5908-a0a6-12951a3a21cc",
  "product_name": "Trail Tee",
  "assigned_variant": "White / M",
  "sku": "TT-100-WHT-M",
  "quantity": 1,
  "buyer_email": null,
  "buyer_phone": null,
  "buyer_name": null,
  "deadline": null,
  "status": "shipped",
  "linked_unit_token": "Qm7xK2pL9vR4tY8wZ1nB3c",
  "carrier": "PostNL",
  "tracking_number": "3SNWD1234567890",
  "shipped_at": "2026-10-09T09:30:00Z",
  "delivered_at": null,
  "is_matchable": true,
  "created_at": "2026-10-09T09:30:00Z"
}

Report delivered#

POST/retail/integrations/fulfillment/tasks/{task_id}/delivered

Requires scope web_orders:write

The carrier delivered the parcel: the passport and ownership move to the customer with the order's email. Safe to resend.

Parameters

task_idstringpathRequired
One unit of a web order to pick. An order with quantity 3 creates 3 tasks.

Request body

reasonstring | null

Returns

HTTP 200

task_idstringRequired
One unit of a web order to pick. An order with quantity 3 creates 3 tasks.
sourcestringRequired
order_referencestring | null
Order number your customer sees (for example #1001).
external_order_idstringRequired
Your web shop's own order id. Skannit keys the order on it, so sending it twice does not create it twice.
product_idstring | null
Skannit's id for the product.
product_namestring | null
assigned_variantstring | null
Colour / size the order line asks for.
skustring | null
Stock-keeping unit of the variant.
quantityinteger
Number of units.
Defaults to 1
buyer_emailstring | null
GL-02: buyer identity is never sent out (always null); the order reference identifies the order. Kept in the schema only so the public v1 contract doesn't break. Stored on the task only to email the buyer.
buyer_phonestring | null
Stored only. Matching is by email. Never returned in responses (always null).
buyer_namestring | null
Never returned in responses (always null).
deadlinetimestamp | null
When the order is promised. Drives the queue's ordering; NULL when the provider sent no SLA.
statusstring
Current state of the object. See the allowed values.
One ofpendingpickedshippeddeliveredcancelledrefusedlostreturn_requestedreturn_receivedreturnedreturn_rejected
Defaults to pending
linked_unit_tokenstring | null
The unit whose passport is linked to this order (set by the pick scan).
carrierstring | null
Carrier name, for example PostNL or DHL.
tracking_numberstring | null
The carrier's tracking number.
shipped_attimestamp | null
When your web shop reported the parcel shipped.
delivered_attimestamp | null
When the parcel was reported delivered — the moment ownership moved.
is_matchableboolean
False when the external SKU matched no Skannit product. Such a task is visible to a worker but cannot be picked until it is mapped.
Defaults to true
created_attimestampRequired
When the object was created (ISO 8601, UTC).

POST /retail/integrations/fulfillment/tasks/{task_id}/delivered

curl

curl -X POST http://62.169.23.239:8001/api/v1/retail/integrations/fulfillment/tasks/266ac6a0-a008-5349-ae80-086961f95f9a/delivered \
  -H "Authorization: Bearer $SKANNIT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Customer changed their mind"
  }'

200Response

json

{
  "task_id": "266ac6a0-a008-5349-ae80-086961f95f9a",
  "source": "web_shop",
  "order_reference": "#1001",
  "external_order_id": "1001",
  "product_id": "f6abe715-90aa-5908-a0a6-12951a3a21cc",
  "product_name": "Trail Tee",
  "assigned_variant": "White / M",
  "sku": "TT-100-WHT-M",
  "quantity": 1,
  "buyer_email": null,
  "buyer_phone": null,
  "buyer_name": null,
  "deadline": null,
  "status": "delivered",
  "linked_unit_token": "Qm7xK2pL9vR4tY8wZ1nB3c",
  "carrier": "PostNL",
  "tracking_number": "3SNWD1234567890",
  "shipped_at": "2026-10-09T09:30:00Z",
  "delivered_at": "2026-10-09T09:30:00Z",
  "is_matchable": true,
  "created_at": "2026-10-09T09:30:00Z"
}

Cancel an order task#

POST/retail/integrations/fulfillment/tasks/{task_id}/cancel

Requires scope web_orders:write

Parameters

task_idstringpathRequired
One unit of a web order to pick. An order with quantity 3 creates 3 tasks.

Request body

reasonstring | null

Returns

HTTP 200

task_idstringRequired
One unit of a web order to pick. An order with quantity 3 creates 3 tasks.
sourcestringRequired
order_referencestring | null
Order number your customer sees (for example #1001).
external_order_idstringRequired
Your web shop's own order id. Skannit keys the order on it, so sending it twice does not create it twice.
product_idstring | null
Skannit's id for the product.
product_namestring | null
assigned_variantstring | null
Colour / size the order line asks for.
skustring | null
Stock-keeping unit of the variant.
quantityinteger
Number of units.
Defaults to 1
buyer_emailstring | null
GL-02: buyer identity is never sent out (always null); the order reference identifies the order. Kept in the schema only so the public v1 contract doesn't break. Stored on the task only to email the buyer.
buyer_phonestring | null
Stored only. Matching is by email. Never returned in responses (always null).
buyer_namestring | null
Never returned in responses (always null).
deadlinetimestamp | null
When the order is promised. Drives the queue's ordering; NULL when the provider sent no SLA.
statusstring
Current state of the object. See the allowed values.
One ofpendingpickedshippeddeliveredcancelledrefusedlostreturn_requestedreturn_receivedreturnedreturn_rejected
Defaults to pending
linked_unit_tokenstring | null
The unit whose passport is linked to this order (set by the pick scan).
carrierstring | null
Carrier name, for example PostNL or DHL.
tracking_numberstring | null
The carrier's tracking number.
shipped_attimestamp | null
When your web shop reported the parcel shipped.
delivered_attimestamp | null
When the parcel was reported delivered — the moment ownership moved.
is_matchableboolean
False when the external SKU matched no Skannit product. Such a task is visible to a worker but cannot be picked until it is mapped.
Defaults to true
created_attimestampRequired
When the object was created (ISO 8601, UTC).

POST /retail/integrations/fulfillment/tasks/{task_id}/cancel

curl

curl -X POST http://62.169.23.239:8001/api/v1/retail/integrations/fulfillment/tasks/266ac6a0-a008-5349-ae80-086961f95f9a/cancel \
  -H "Authorization: Bearer $SKANNIT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Customer changed their mind"
  }'

200Response

json

{
  "task_id": "266ac6a0-a008-5349-ae80-086961f95f9a",
  "source": "web_shop",
  "order_reference": "#1001",
  "external_order_id": "1001",
  "product_id": "f6abe715-90aa-5908-a0a6-12951a3a21cc",
  "product_name": "Trail Tee",
  "assigned_variant": "White / M",
  "sku": "TT-100-WHT-M",
  "quantity": 1,
  "buyer_email": null,
  "buyer_phone": null,
  "buyer_name": null,
  "deadline": null,
  "status": "cancelled",
  "linked_unit_token": null,
  "carrier": "PostNL",
  "tracking_number": "3SNWD1234567890",
  "shipped_at": null,
  "delivered_at": null,
  "is_matchable": true,
  "created_at": "2026-10-09T09:30:00Z"
}

Report a lost parcel#

POST/retail/integrations/fulfillment/tasks/{task_id}/lost

Requires scope web_orders:write

Parameters

task_idstringpathRequired
One unit of a web order to pick. An order with quantity 3 creates 3 tasks.

Request body

reasonstring | null

Returns

HTTP 200

task_idstringRequired
One unit of a web order to pick. An order with quantity 3 creates 3 tasks.
sourcestringRequired
order_referencestring | null
Order number your customer sees (for example #1001).
external_order_idstringRequired
Your web shop's own order id. Skannit keys the order on it, so sending it twice does not create it twice.
product_idstring | null
Skannit's id for the product.
product_namestring | null
assigned_variantstring | null
Colour / size the order line asks for.
skustring | null
Stock-keeping unit of the variant.
quantityinteger
Number of units.
Defaults to 1
buyer_emailstring | null
GL-02: buyer identity is never sent out (always null); the order reference identifies the order. Kept in the schema only so the public v1 contract doesn't break. Stored on the task only to email the buyer.
buyer_phonestring | null
Stored only. Matching is by email. Never returned in responses (always null).
buyer_namestring | null
Never returned in responses (always null).
deadlinetimestamp | null
When the order is promised. Drives the queue's ordering; NULL when the provider sent no SLA.
statusstring
Current state of the object. See the allowed values.
One ofpendingpickedshippeddeliveredcancelledrefusedlostreturn_requestedreturn_receivedreturnedreturn_rejected
Defaults to pending
linked_unit_tokenstring | null
The unit whose passport is linked to this order (set by the pick scan).
carrierstring | null
Carrier name, for example PostNL or DHL.
tracking_numberstring | null
The carrier's tracking number.
shipped_attimestamp | null
When your web shop reported the parcel shipped.
delivered_attimestamp | null
When the parcel was reported delivered — the moment ownership moved.
is_matchableboolean
False when the external SKU matched no Skannit product. Such a task is visible to a worker but cannot be picked until it is mapped.
Defaults to true
created_attimestampRequired
When the object was created (ISO 8601, UTC).

POST /retail/integrations/fulfillment/tasks/{task_id}/lost

curl

curl -X POST http://62.169.23.239:8001/api/v1/retail/integrations/fulfillment/tasks/266ac6a0-a008-5349-ae80-086961f95f9a/lost \
  -H "Authorization: Bearer $SKANNIT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Customer changed their mind"
  }'

200Response

json

{
  "task_id": "266ac6a0-a008-5349-ae80-086961f95f9a",
  "source": "web_shop",
  "order_reference": "#1001",
  "external_order_id": "1001",
  "product_id": "f6abe715-90aa-5908-a0a6-12951a3a21cc",
  "product_name": "Trail Tee",
  "assigned_variant": "White / M",
  "sku": "TT-100-WHT-M",
  "quantity": 1,
  "buyer_email": null,
  "buyer_phone": null,
  "buyer_name": null,
  "deadline": null,
  "status": "lost",
  "linked_unit_token": "Qm7xK2pL9vR4tY8wZ1nB3c",
  "carrier": "PostNL",
  "tracking_number": "3SNWD1234567890",
  "shipped_at": null,
  "delivered_at": null,
  "is_matchable": true,
  "created_at": "2026-10-09T09:30:00Z"
}

Start a return#

POST/retail/integrations/fulfillment/tasks/{task_id}/return

Requires scope web_orders:write

Parameters

task_idstringpathRequired
One unit of a web order to pick. An order with quantity 3 creates 3 tasks.

Request body

reasonstring | null

Returns

HTTP 200

task_idstringRequired
One unit of a web order to pick. An order with quantity 3 creates 3 tasks.
sourcestringRequired
order_referencestring | null
Order number your customer sees (for example #1001).
external_order_idstringRequired
Your web shop's own order id. Skannit keys the order on it, so sending it twice does not create it twice.
product_idstring | null
Skannit's id for the product.
product_namestring | null
assigned_variantstring | null
Colour / size the order line asks for.
skustring | null
Stock-keeping unit of the variant.
quantityinteger
Number of units.
Defaults to 1
buyer_emailstring | null
GL-02: buyer identity is never sent out (always null); the order reference identifies the order. Kept in the schema only so the public v1 contract doesn't break. Stored on the task only to email the buyer.
buyer_phonestring | null
Stored only. Matching is by email. Never returned in responses (always null).
buyer_namestring | null
Never returned in responses (always null).
deadlinetimestamp | null
When the order is promised. Drives the queue's ordering; NULL when the provider sent no SLA.
statusstring
Current state of the object. See the allowed values.
One ofpendingpickedshippeddeliveredcancelledrefusedlostreturn_requestedreturn_receivedreturnedreturn_rejected
Defaults to pending
linked_unit_tokenstring | null
The unit whose passport is linked to this order (set by the pick scan).
carrierstring | null
Carrier name, for example PostNL or DHL.
tracking_numberstring | null
The carrier's tracking number.
shipped_attimestamp | null
When your web shop reported the parcel shipped.
delivered_attimestamp | null
When the parcel was reported delivered — the moment ownership moved.
is_matchableboolean
False when the external SKU matched no Skannit product. Such a task is visible to a worker but cannot be picked until it is mapped.
Defaults to true
created_attimestampRequired
When the object was created (ISO 8601, UTC).

POST /retail/integrations/fulfillment/tasks/{task_id}/return

curl

curl -X POST http://62.169.23.239:8001/api/v1/retail/integrations/fulfillment/tasks/266ac6a0-a008-5349-ae80-086961f95f9a/return \
  -H "Authorization: Bearer $SKANNIT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Customer changed their mind"
  }'

200Response

json

{
  "task_id": "266ac6a0-a008-5349-ae80-086961f95f9a",
  "source": "web_shop",
  "order_reference": "#1001",
  "external_order_id": "1001",
  "product_id": "f6abe715-90aa-5908-a0a6-12951a3a21cc",
  "product_name": "Trail Tee",
  "assigned_variant": "White / M",
  "sku": "TT-100-WHT-M",
  "quantity": 1,
  "buyer_email": null,
  "buyer_phone": null,
  "buyer_name": null,
  "deadline": null,
  "status": "return_requested",
  "linked_unit_token": "Qm7xK2pL9vR4tY8wZ1nB3c",
  "carrier": "PostNL",
  "tracking_number": "3SNWD1234567890",
  "shipped_at": null,
  "delivered_at": null,
  "is_matchable": true,
  "created_at": "2026-10-09T09:30:00Z"
}

Settle a lost return#

POST/retail/integrations/fulfillment/tasks/{task_id}/return-lost

Requires scope web_orders:write

A return lost on the way back, settled with the customer: the passport goes back to the shop, marked lost.

Parameters

task_idstringpathRequired
One unit of a web order to pick. An order with quantity 3 creates 3 tasks.

Request body

reasonstring | null

Returns

HTTP 200

task_idstringRequired
One unit of a web order to pick. An order with quantity 3 creates 3 tasks.
sourcestringRequired
order_referencestring | null
Order number your customer sees (for example #1001).
external_order_idstringRequired
Your web shop's own order id. Skannit keys the order on it, so sending it twice does not create it twice.
product_idstring | null
Skannit's id for the product.
product_namestring | null
assigned_variantstring | null
Colour / size the order line asks for.
skustring | null
Stock-keeping unit of the variant.
quantityinteger
Number of units.
Defaults to 1
buyer_emailstring | null
GL-02: buyer identity is never sent out (always null); the order reference identifies the order. Kept in the schema only so the public v1 contract doesn't break. Stored on the task only to email the buyer.
buyer_phonestring | null
Stored only. Matching is by email. Never returned in responses (always null).
buyer_namestring | null
Never returned in responses (always null).
deadlinetimestamp | null
When the order is promised. Drives the queue's ordering; NULL when the provider sent no SLA.
statusstring
Current state of the object. See the allowed values.
One ofpendingpickedshippeddeliveredcancelledrefusedlostreturn_requestedreturn_receivedreturnedreturn_rejected
Defaults to pending
linked_unit_tokenstring | null
The unit whose passport is linked to this order (set by the pick scan).
carrierstring | null
Carrier name, for example PostNL or DHL.
tracking_numberstring | null
The carrier's tracking number.
shipped_attimestamp | null
When your web shop reported the parcel shipped.
delivered_attimestamp | null
When the parcel was reported delivered — the moment ownership moved.
is_matchableboolean
False when the external SKU matched no Skannit product. Such a task is visible to a worker but cannot be picked until it is mapped.
Defaults to true
created_attimestampRequired
When the object was created (ISO 8601, UTC).

POST /retail/integrations/fulfillment/tasks/{task_id}/return-lost

curl

curl -X POST http://62.169.23.239:8001/api/v1/retail/integrations/fulfillment/tasks/266ac6a0-a008-5349-ae80-086961f95f9a/return-lost \
  -H "Authorization: Bearer $SKANNIT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Customer changed their mind"
  }'

200Response

json

{
  "task_id": "266ac6a0-a008-5349-ae80-086961f95f9a",
  "source": "web_shop",
  "order_reference": "#1001",
  "external_order_id": "1001",
  "product_id": "f6abe715-90aa-5908-a0a6-12951a3a21cc",
  "product_name": "Trail Tee",
  "assigned_variant": "White / M",
  "sku": "TT-100-WHT-M",
  "quantity": 1,
  "buyer_email": null,
  "buyer_phone": null,
  "buyer_name": null,
  "deadline": null,
  "status": "lost",
  "linked_unit_token": "Qm7xK2pL9vR4tY8wZ1nB3c",
  "carrier": "PostNL",
  "tracking_number": "3SNWD1234567890",
  "shipped_at": null,
  "delivered_at": null,
  "is_matchable": true,
  "created_at": "2026-10-09T09:30:00Z"
}

Resolve a non-delivery dispute#

POST/retail/integrations/fulfillment/tasks/{task_id}/dispute-nondelivery

Requires scope web_orders:write

The buyer says the order never arrived, raised after 'delivered' already moved the passport: reverses the transfer, passport goes back to the shop.

Parameters

task_idstringpathRequired
One unit of a web order to pick. An order with quantity 3 creates 3 tasks.

Request body

reasonstringRequired

Returns

HTTP 200

task_idstringRequired
One unit of a web order to pick. An order with quantity 3 creates 3 tasks.
sourcestringRequired
order_referencestring | null
Order number your customer sees (for example #1001).
external_order_idstringRequired
Your web shop's own order id. Skannit keys the order on it, so sending it twice does not create it twice.
product_idstring | null
Skannit's id for the product.
product_namestring | null
assigned_variantstring | null
Colour / size the order line asks for.
skustring | null
Stock-keeping unit of the variant.
quantityinteger
Number of units.
Defaults to 1
buyer_emailstring | null
GL-02: buyer identity is never sent out (always null); the order reference identifies the order. Kept in the schema only so the public v1 contract doesn't break. Stored on the task only to email the buyer.
buyer_phonestring | null
Stored only. Matching is by email. Never returned in responses (always null).
buyer_namestring | null
Never returned in responses (always null).
deadlinetimestamp | null
When the order is promised. Drives the queue's ordering; NULL when the provider sent no SLA.
statusstring
Current state of the object. See the allowed values.
One ofpendingpickedshippeddeliveredcancelledrefusedlostreturn_requestedreturn_receivedreturnedreturn_rejected
Defaults to pending
linked_unit_tokenstring | null
The unit whose passport is linked to this order (set by the pick scan).
carrierstring | null
Carrier name, for example PostNL or DHL.
tracking_numberstring | null
The carrier's tracking number.
shipped_attimestamp | null
When your web shop reported the parcel shipped.
delivered_attimestamp | null
When the parcel was reported delivered — the moment ownership moved.
is_matchableboolean
False when the external SKU matched no Skannit product. Such a task is visible to a worker but cannot be picked until it is mapped.
Defaults to true
created_attimestampRequired
When the object was created (ISO 8601, UTC).

POST /retail/integrations/fulfillment/tasks/{task_id}/dispute-nondelivery

curl

curl -X POST http://62.169.23.239:8001/api/v1/retail/integrations/fulfillment/tasks/266ac6a0-a008-5349-ae80-086961f95f9a/dispute-nondelivery \
  -H "Authorization: Bearer $SKANNIT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Customer changed their mind"
  }'

200Response

json

{
  "task_id": "266ac6a0-a008-5349-ae80-086961f95f9a",
  "source": "web_shop",
  "order_reference": "#1001",
  "external_order_id": "1001",
  "product_id": "f6abe715-90aa-5908-a0a6-12951a3a21cc",
  "product_name": "Trail Tee",
  "assigned_variant": "White / M",
  "sku": "TT-100-WHT-M",
  "quantity": 1,
  "buyer_email": null,
  "buyer_phone": null,
  "buyer_name": null,
  "deadline": null,
  "status": "pending",
  "linked_unit_token": "Qm7xK2pL9vR4tY8wZ1nB3c",
  "carrier": "PostNL",
  "tracking_number": "3SNWD1234567890",
  "shipped_at": null,
  "delivered_at": null,
  "is_matchable": true,
  "created_at": "2026-10-09T09:30:00Z"
}

NextWarehouse pick & returns→