Prep API Reference: Endpoints, Webhooks, Schemas

Overview

Base URL: https://api.profitpath.app
API version: 2026-11-01
Authentication: Bearer ppk_…

A webhook prep-center connection links a ProfitDesk account to warehouse software you run yourself. Building software for many sellers? See prep-providers-v1.openapi.yaml (external prep providers).

ProfitDesk → you: announcements, cancellations and updates arrive as signed webhook events at the URL you configured (see webhooks below). Missed events can be replayed with GET /v1/prep/events.
You → ProfitDesk: report goods received (POST /v1/prep/inbounds/{id}/receipts) and what you ship out (POST /v1/prep/outbounds), and pull inbounds, items and events.

Identifiers

Every id carries a type prefix: pur_ purchase, itm_ item (one per SKU), inb_ inbound, inl_ inbound line (one per purchase in an inbound), out_ outbound, pcn_ connection, wh_ warehouse, evt_ event. Wherever a path takes an inbound or outbound {id}, you may pass ext:<external_id> instead to address it by your own reference.

A seller can hold several webhook connections, for example one per warehouse setup; each has its own pcn_ id, signing secret and API key, and a key only sees its own connection.

Authentication

Authorization: Bearer ppk_… with the API key shown once when the connection was created or its key rotated. Missing, unknown or revoked keys get 401.

Rate limit

2 requests per second per key, bursts up to 10. Beyond that: 429 with Retry-After: 1.

Idempotency

Every POST/PUT may carry an idempotency key, either event_id in the body or the Idempotency-Key header (the body wins). It is required for receipts and outbounds. Repeating a request with the same key and the identical method, path and body returns the stored response with "duplicate": true and has no further effect. The same key with a different request is 409 idempotency_conflict. Failed requests are not stored, so a key that got a 4xx can be retried after fixing the request. Keys are scoped to the connection and kept for 30 days.

Ordering

Receipts and outbounds carry occurred_at (RFC 3339, default: now). A line or outbound is only changed by an event newer than the last one applied to it; older events are reported as stale and change nothing, so out-of-order delivery is safe.

Webhook events

ProfitDesk POSTs a signed JSON envelope to your endpoint URL. The full request and response definition of every event is in the Webhooks section at the bottom of this page; the schemas are under Schemas.

Event	Sent when	`data`	Default
`inbound.announced`	Goods are on their way to you	`inbound`, `traces`	on
`inbound.updated`	Tracking numbers added, an FNSKU became known, your `external_id` changed, or lines of a shared inbound were cancelled/restored	`inbound`, `traces`, `changes` (+ `reason` when a line was cancelled)	on
`inbound.cancelled`	The whole inbound is cancelled (purchase cancelled or deactivated, warehouse changed, re-announced)	`inbound`, `traces`, `reason`, `replaced_by_inbound_id`?	on
`inbound.restored`	A cancelled inbound is active again (if you never received the inbound, a reactivation arrives as `inbound.announced`)	`inbound`, `traces`	on
`inbound.received`	Echo of a receipt you reported	`inbound`, `traces`	off
`outbound.recorded`	Echo of an outbound you reported	`outbound`, `traces`	off
`ping`	"Send test" in ProfitDesk	`message`	always

The seller picks the events in the connection settings; the echo events are off by default because they only repeat what you reported yourself. GET /v1/prep/events returns every event type regardless of the subscription.

Your response: any 2xx within 10 s counts as delivered; for inbound.announced the body may be {"external_id": "<your id>"}; it is stored without an inbound.updated event. Timeouts, 408, 429 and 5xx are retried until 72 h after the event was queued, 3xx and other 4xx (410 included) fail immediately; only a failed attempt after 72 h without any successful delivery disables the endpoint. A purchase counts as announced only once its inbound.announced was delivered.

Order and skips: events of the same inbound are delivered in order, one at a time. If an inbound is cancelled before you received any of its events, all its open deliveries, the cancel included, are skipped; a later reactivation then arrives as inbound.announced. An event is never delivered after an inbound.cancelled of its inbound that you already received. Skipped events stay in GET /v1/prep/events, which is ordered so that a cursor never skips an event.

Errors

Every non-2xx response has the body {"error": {"code", "message", "details"}}. Codes: unauthorized (401), rate_limited (429), invalid_request / invalid_json / idempotency_key_required (400), payload_too_large (413), inbound_not_found / outbound_not_found (404), inbound_cancelled / idempotency_conflict / external_id_conflict (409), line_not_found (422), internal_error (500). Request bodies are limited to 1 MB; unknown JSON fields are ignored.

Inbounds

List inbounds announced to the connection

GET/v1/prep/inbounds

Parameters

Name	In	Type	Required	Description
`status`	query	string	No	One of: `open`, `received`, `cancelled`.
`updated_since`	query	string (date-time)	No	Only inbounds changed after this instant (including tracking and FNSKU updates).
`cursor`	query	string	No	`next_cursor` of the previous page.
`limit`	query	integer	No	Default: `50`. Minimum 1. Maximum 100.

Responses

Status	Description	Body
`200`	Inbounds ordered by id. An inbound whose lines were all removed (the purchase moved to another warehouse or was re-announced) is not listed; find it through `GET /v1/prep/events`.	object
`default`	Error	Error

Response 200

Field	Type	Required	Description
`data`	array of InboundView	Yes
`next_cursor`	string \| null	Yes	Pass as `cursor` for the next page; null on the last page.

Example response

{
  "data": [
    {
      "connection_id": "pcn_812",
      "inbound": {
        "id": "inb_2000000123",
        "external_id": "WMS-IN-5521",
        "batch_id": null,
        "status": "open",
        "name": "amazon.de | Bosch GSR 18V-55 Drill Driver | 302-1234567-1234567",
        "notes": "Fragile, please bubble-wrap\nFulfillment: FBA",
        "fulfillment": "FBA",
        "warehouse": {
          "id": "wh_12",
          "name": "Warehouse South"
        },
        "order": {
          "numbers": [
            "302-1234567-1234567"
          ],
          "supplier_host": "amazon.de",
          "purchased_at": "2026-11-02"
        },
        "tracking_numbers": [
          "1Z999AA10123456784"
        ],
        "lines": [
          {
            "id": "inl_99",
            "purchase_id": "pur_4711",
            "item": {
              "id": "itm_17",
              "sku": "AB-123",
              "fnsku": "X00ABCDEFG",
              "asin": "B0ABCDEFGH",
              "ean": "4006381333931",
              "title": "Bosch GSR 18V-55 Drill Driver",
              "image_url": "https://m.media-amazon.com/images/I/61Xf3kqcQhL.jpg"
            },
            "quantity_expected": 6,
            "quantity_received": 0,
            "quantity_damaged": 0,
            "status": "open"
          }
        ],
        "created_at": "2026-11-03T10:15:00Z"
      },
      "traces": [
        {
          "purchase_id": "pur_4711",
          "inbound_id": "inb_2000000123",
          "inbound_line_id": "inl_99",
          "item_id": "itm_17",
          "sku": "AB-123",
          "fnsku": "X00ABCDEFG",
          "asin": "B0ABCDEFGH",
          "order_number": "302-1234567-1234567",
          "batch_id": null,
          "outbound_ids": [],
          "amazon_shipment_ids": []
        }
      ]
    }
  ],
  "next_cursor": "inb_2000000123"
}

Get one inbound with its lines and traces

GET/v1/prep/inbounds/{id}

For an inbound whose lines were removed (the purchase moved to another warehouse or was re-announced), returns the inbound as of its latest event with status: cancelled and every line cancelled. 404 inbound_not_found means the id was never announced to this connection.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	`inb_…` or `ext:<external_id>`

Responses

Status	Description	Body
`200`	The inbound.	InboundView
`default`	Error	Error

Example response

{
  "connection_id": "pcn_812",
  "inbound": {
    "id": "inb_2000000123",
    "external_id": "WMS-IN-5521",
    "batch_id": null,
    "status": "open",
    "name": "amazon.de | Bosch GSR 18V-55 Drill Driver | 302-1234567-1234567",
    "notes": "Fragile, please bubble-wrap\nFulfillment: FBA",
    "fulfillment": "FBA",
    "warehouse": {
      "id": "wh_12",
      "name": "Warehouse South"
    },
    "order": {
      "numbers": [
        "302-1234567-1234567"
      ],
      "supplier_host": "amazon.de",
      "purchased_at": "2026-11-02"
    },
    "tracking_numbers": [
      "1Z999AA10123456784"
    ],
    "lines": [
      {
        "id": "inl_99",
        "purchase_id": "pur_4711",
        "item": {
          "id": "itm_17",
          "sku": "AB-123",
          "fnsku": "X00ABCDEFG",
          "asin": "B0ABCDEFGH",
          "ean": "4006381333931",
          "title": "Bosch GSR 18V-55 Drill Driver",
          "image_url": "https://m.media-amazon.com/images/I/61Xf3kqcQhL.jpg"
        },
        "quantity_expected": 6,
        "quantity_received": 0,
        "quantity_damaged": 0,
        "status": "open"
      }
    ],
    "created_at": "2026-11-03T10:15:00Z"
  },
  "traces": [
    {
      "purchase_id": "pur_4711",
      "inbound_id": "inb_2000000123",
      "inbound_line_id": "inl_99",
      "item_id": "itm_17",
      "sku": "AB-123",
      "fnsku": "X00ABCDEFG",
      "asin": "B0ABCDEFGH",
      "order_number": "302-1234567-1234567",
      "batch_id": null,
      "outbound_ids": [],
      "amazon_shipment_ids": []
    }
  ]
}

Set your own reference on an inbound

PUT/v1/prep/inbounds/{id}/external-id

Unique per connection (409 external_id_conflict); afterwards the inbound is addressable as ext:<external_id>. A changed value emits inbound.updated with changes: ["external_id"]. A cancelled inbound answers 409 inbound_cancelled. The idempotency key is optional here; without one, event_id is null in the response.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	`inb_…` or `ext:<external_id>`
`Idempotency-Key`	header	string	No	Used when the body carries no `event_id`. Max length 200.

Request body

Field	Type	Required	Description
`event_id`	string	No	Max length 200.
`external_id`	string	Yes	Min length 1. Max length 200.

Example request

{
  "external_id": "WMS-IN-5521"
}

Responses

Status	Description	Body
`200`	The inbound after the change.	ExternalIdResponse
`default`	Error	Error

Example response

{
  "event_id": null,
  "duplicate": false,
  "connection_id": "pcn_812",
  "inbound": {
    "id": "inb_2000000123",
    "external_id": "WMS-IN-5521",
    "batch_id": null,
    "status": "open",
    "name": "amazon.de | Bosch GSR 18V-55 Drill Driver | 302-1234567-1234567",
    "notes": "Fragile, please bubble-wrap\nFulfillment: FBA",
    "fulfillment": "FBA",
    "warehouse": {
      "id": "wh_12",
      "name": "Warehouse South"
    },
    "order": {
      "numbers": [
        "302-1234567-1234567"
      ],
      "supplier_host": "amazon.de",
      "purchased_at": "2026-11-02"
    },
    "tracking_numbers": [
      "1Z999AA10123456784"
    ],
    "lines": [
      {
        "id": "inl_99",
        "purchase_id": "pur_4711",
        "item": {
          "id": "itm_17",
          "sku": "AB-123",
          "fnsku": "X00ABCDEFG",
          "asin": "B0ABCDEFGH",
          "ean": "4006381333931",
          "title": "Bosch GSR 18V-55 Drill Driver",
          "image_url": "https://m.media-amazon.com/images/I/61Xf3kqcQhL.jpg"
        },
        "quantity_expected": 6,
        "quantity_received": 0,
        "quantity_damaged": 0,
        "status": "open"
      }
    ],
    "created_at": "2026-11-03T10:15:00Z"
  },
  "traces": [
    {
      "purchase_id": "pur_4711",
      "inbound_id": "inb_2000000123",
      "inbound_line_id": "inl_99",
      "item_id": "itm_17",
      "sku": "AB-123",
      "fnsku": "X00ABCDEFG",
      "asin": "B0ABCDEFGH",
      "order_number": "302-1234567-1234567",
      "batch_id": null,
      "outbound_ids": [],
      "amazon_shipment_ids": []
    }
  ]
}

Report goods received for an announced inbound

POST/v1/prep/inbounds/{id}/receipts

quantity_received is the absolute count for the line, so a correction downwards is just a smaller number. Address a line by line_id (exact) or by sku within this inbound; several lines of the same SKU are filled in order up to their expected quantity, any surplus goes to the last. status is required. receiving is the count so far: a line closes when it reaches its expected quantity and opens again if a later receiving count is lower. status: received closes every line of the inbound, also lines counted short or not at all. Only announced goods are accepted: an inbound never announced to the key's connections is 404 inbound_not_found, a line or SKU that is not part of the inbound is 422 line_not_found, a cancelled inbound (also one whose lines were removed because the purchase moved or was re-announced) is 409 inbound_cancelled. A receipt that changed anything emits inbound.received.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	`inb_…` or `ext:<external_id>`
`Idempotency-Key`	header	string	No	Used when the body carries no `event_id`. Max length 200.

Request body

Schema: ReceiptRequest

Field	Type	Required	Description
`event_id`	string	No	Idempotency key; or send the Idempotency-Key header. Max length 200.
`occurred_at`	string (date-time)	No
`status`	string	Yes	One of: `receiving`, `received`.
`lines`	array of object	No	May be empty only with `status: received`. Each line may be addressed once per request.
`lines[].line_id`	string	No	`inl_…`; takes precedence over `sku`.
`lines[].sku`	string	No
`lines[].quantity_received`	integer	Yes	Absolute count. Minimum 0.
`lines[].quantity_damaged`	integer	No	Stored and returned; omitted keeps the previous value. Minimum 0.

Example request

{
  "event_id": "rcpt-8812",
  "occurred_at": "2026-11-05T08:01:00Z",
  "status": "receiving",
  "lines": [
    {
      "line_id": "inl_120",
      "quantity_received": 5,
      "quantity_damaged": 1
    },
    {
      "sku": "CD-456",
      "quantity_received": 2
    }
  ]
}

Responses

Status	Description	Body
`200`	Applied, or replayed with `duplicate: true`.	ReceiptResponse
`default`	Error	Error

Example response

{
  "event_id": "rcpt-8812",
  "duplicate": false,
  "connection_id": "pcn_812",
  "inbound": {
    "id": "inb_2000000131",
    "external_id": "WMS-IN-5530",
    "batch_id": "0d1f6a2e-4b7c-4c11-9a3e-5f2b8c7d9e10",
    "status": "open",
    "name": "amazon.de | Bosch GSR 18V-55 Drill Driver +1 | 302-1234567-1234567, 302-7654321-7654321",
    "notes": "Fragile, please bubble-wrap\nFulfillment: FBA",
    "fulfillment": "FBA",
    "warehouse": {
      "id": "wh_12",
      "name": "Warehouse South"
    },
    "order": {
      "numbers": [
        "302-1234567-1234567",
        "302-7654321-7654321"
      ],
      "supplier_host": "amazon.de",
      "purchased_at": "2026-11-02"
    },
    "tracking_numbers": [
      "1Z999AA10123456784"
    ],
    "lines": [
      {
        "id": "inl_120",
        "purchase_id": "pur_4720",
        "item": {
          "id": "itm_17",
          "sku": "AB-123",
          "fnsku": "X00ABCDEFG",
          "asin": "B0ABCDEFGH",
          "ean": "4006381333931",
          "title": "Bosch GSR 18V-55 Drill Driver",
          "image_url": "https://m.media-amazon.com/images/I/61Xf3kqcQhL.jpg"
        },
        "quantity_expected": 6,
        "quantity_received": 5,
        "quantity_damaged": 1,
        "status": "open"
      },
      {
        "id": "inl_121",
        "purchase_id": "pur_4721",
        "item": {
          "id": "itm_18",
          "sku": "CD-456",
          "fnsku": "X00BCDEFGH",
          "asin": "B0BCDEFGHI",
          "ean": "4059952513164",
          "title": "Bosch GBA 18V 4.0Ah Battery",
          "image_url": "https://m.media-amazon.com/images/I/51Zk2mN8pRL.jpg"
        },
        "quantity_expected": 2,
        "quantity_received": 2,
        "quantity_damaged": 0,
        "status": "received"
      }
    ],
    "created_at": "2026-11-03T10:15:00Z"
  },
  "traces": [
    {
      "purchase_id": "pur_4720",
      "inbound_id": "inb_2000000131",
      "inbound_line_id": "inl_120",
      "item_id": "itm_17",
      "sku": "AB-123",
      "fnsku": "X00ABCDEFG",
      "asin": "B0ABCDEFGH",
      "order_number": "302-1234567-1234567",
      "batch_id": "0d1f6a2e-4b7c-4c11-9a3e-5f2b8c7d9e10",
      "outbound_ids": [],
      "amazon_shipment_ids": []
    },
    {
      "purchase_id": "pur_4721",
      "inbound_id": "inb_2000000131",
      "inbound_line_id": "inl_121",
      "item_id": "itm_18",
      "sku": "CD-456",
      "fnsku": "X00BCDEFGH",
      "asin": "B0BCDEFGHI",
      "order_number": "302-7654321-7654321",
      "batch_id": "0d1f6a2e-4b7c-4c11-9a3e-5f2b8c7d9e10",
      "outbound_ids": [],
      "amazon_shipment_ids": []
    }
  ],
  "lines": [
    {
      "line_id": "inl_120",
      "result": "applied"
    },
    {
      "line_id": "inl_121",
      "result": "applied"
    }
  ]
}

Outbounds

Create, update, ship or cancel an outbound

POST/v1/prep/outbounds

Upserts by external_id; the lines you send replace the stored ones, and cancelled clears them. Each line is matched to a purchase, in this priority: line_id (exact), purchase_id (exact, must belong to an inbound of the outbound's connection), item_id or sku (first received first, capped at what was received minus what other open or shipped outbounds already hold). Quantities that cannot be matched are returned in unresolved; only when nothing at all matches is the request refused with 422 line_not_found.

Outbounds are a trace: they do not change any stock or forwarded quantity (FBA shipments are booked from Amazon). Every request that is not stale emits outbound.recorded.

Parameters

Name	In	Type	Required	Description
`Idempotency-Key`	header	string	No	Used when the body carries no `event_id`. Max length 200.

Request body

Schema: OutboundRequest

Field	Type	Required	Description
`event_id`	string	No	Max length 200.
`external_id`	string	Yes	Your outbound id. Min length 1. Max length 200.
`occurred_at`	string (date-time)	No
`status`	string	Yes	One of: `created`, `shipped`, `cancelled`.
`destination`	object	Yes
`destination.type`	string	Yes	Required; missing or empty is `400 invalid_request`. One of: `fba`, `fbm`, `other`.
`destination.amazon_shipment_id`	string	No	Max length 64. Example: `FBA15XYZ`.
`destination.marketplace`	string	No	Max length 8. Example: `DE`.
`tracking_numbers`	array of string	No
`lines`	array of object	No
`lines[].line_id`	string	No
`lines[].purchase_id`	string	No
`lines[].item_id`	string	No
`lines[].sku`	string	No
`lines[].quantity`	integer	Yes	Minimum 1.

Example request

{
  "event_id": "out-311-v3",
  "external_id": "OUT-311",
  "occurred_at": "2026-11-06T14:00:00Z",
  "status": "shipped",
  "destination": {
    "type": "fba",
    "amazon_shipment_id": "FBA15XYZ",
    "marketplace": "DE"
  },
  "tracking_numbers": [
    "1Z999AA10123456784"
  ],
  "lines": [
    {
      "line_id": "inl_120",
      "quantity": 4
    },
    {
      "sku": "CD-456",
      "quantity": 2
    }
  ]
}

Responses

Status	Description	Body
`200`	Stored (or `stale: true` when a newer event was already applied), or replayed with `duplicate: true`.	OutboundResponse
`default`	Error	Error

{
  "event_id": "out-311-v3",
  "duplicate": false,
  "stale": false,
  "connection_id": "pcn_812",
  "outbound": {
    "id": "out_55",
    "external_id": "OUT-311",
    "status": "shipped",
    "destination": {
      "type": "fba",
      "amazon_shipment_id": "FBA15XYZ",
      "marketplace": "DE"
    },
    "tracking_numbers": [
      "1Z999AA10123456784"
    ],
    "shipped_at": "2026-11-06T14:00:00Z",
    "lines": [
      {
        "purchase_id": "pur_4720",
        "inbound_line_id": "inl_120",
        "quantity": 4,
        "resolved_by": "line_id"
      },
      {
        "purchase_id": "pur_4721",
        "inbound_line_id": "inl_121",
        "quantity": 2,
        "resolved_by": "sku_fifo"
      }
    ]
  },
  "unresolved": []
}

{
  "event_id": "out-312-v1",
  "duplicate": false,
  "stale": false,
  "connection_id": "pcn_812",
  "outbound": {
    "id": "out_56",
    "external_id": "OUT-312",
    "status": "created",
    "destination": {
      "type": "fba",
      "amazon_shipment_id": "FBA15XZA",
      "marketplace": "DE"
    },
    "tracking_numbers": [],
    "shipped_at": null,
    "lines": [
      {
        "purchase_id": "pur_4720",
        "inbound_line_id": "inl_120",
        "quantity": 2,
        "resolved_by": "sku_fifo"
      }
    ]
  },
  "unresolved": [
    {
      "index": 0,
      "line_id": null,
      "purchase_id": null,
      "item_id": null,
      "sku": "AB-123",
      "quantity": 2,
      "reason": "insufficient_received_quantity"
    }
  ]
}

Get one outbound with its purchase allocation

GET/v1/prep/outbounds/{id}

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	`out_…` or `ext:<external_id>`

Responses

Status	Description	Body
`200`	The outbound.	object
`default`	Error	Error

Response 200

Field	Type	Required	Description
`connection_id`	string	Yes	Example: `pcn_812`.
`outbound`	Outbound	Yes

Example response

{
  "connection_id": "pcn_812",
  "outbound": {
    "id": "out_55",
    "external_id": "OUT-311",
    "status": "shipped",
    "destination": {
      "type": "fba",
      "amazon_shipment_id": "FBA15XYZ",
      "marketplace": "DE"
    },
    "tracking_numbers": [
      "1Z999AA10123456784"
    ],
    "shipped_at": "2026-11-06T14:00:00Z",
    "lines": [
      {
        "purchase_id": "pur_4720",
        "inbound_line_id": "inl_120",
        "quantity": 4,
        "resolved_by": "line_id"
      },
      {
        "purchase_id": "pur_4721",
        "inbound_line_id": "inl_121",
        "quantity": 2,
        "resolved_by": "sku_fifo"
      }
    ]
  }
}

Items

List the connection's articles (one per SKU)

GET/v1/prep/items

image_url is not filled in this list; the inbound payloads carry it.

Parameters

Name	In	Type	Required	Description
`sku`	query	string	No	Exact SKU.
`cursor`	query	string	No	`next_cursor` of the previous page.
`limit`	query	integer	No	Default: `50`. Minimum 1. Maximum 100.

Responses

Status	Description	Body
`200`	Items ordered by id.	object
`default`	Error	Error

Response 200

Field	Type	Required	Description
`data`	array of ItemView	Yes
`next_cursor`	string \| null	Yes

Example response

{
  "data": [
    {
      "id": "itm_17",
      "sku": "AB-123",
      "fnsku": "X00ABCDEFG",
      "asin": "B0ABCDEFGH",
      "ean": "4006381333931",
      "title": "Bosch GSR 18V-55 Drill Driver",
      "image_url": null,
      "connection_id": "pcn_812",
      "created_at": "2026-11-03T10:15:00Z",
      "updated_at": "2026-11-03T10:15:00Z"
    },
    {
      "id": "itm_18",
      "sku": "CD-456",
      "fnsku": "X00BCDEFGH",
      "asin": "B0BCDEFGHI",
      "ean": "4059952513164",
      "title": "Bosch GBA 18V 4.0Ah Battery",
      "image_url": null,
      "connection_id": "pcn_812",
      "created_at": "2026-11-03T10:15:00Z",
      "updated_at": "2026-11-04T07:30:00Z"
    }
  ],
  "next_cursor": null
}

Events

Replay the connection's webhook events

GET/v1/prep/events

Returns the same envelopes that are delivered to your URL, whether or not your endpoint is subscribed to the type and whether the delivery succeeded, failed or was skipped. Events are kept for 90 days.

The feed is ordered by the transaction that created each event, and an event shows up once every transaction that started before it has finished (usually within a second, at most ten minutes), so no event is ever inserted behind a next_cursor you already have. Poll with since set to the last next_cursor you processed and deduplicate by id.

Resume with an evt_… id: that position is exact. An RFC 3339 instant is compared with the time the event was stored, which can differ from the envelope's created_at by milliseconds, so the window starts one second early and can repeat events you already have. Always deduplicate by id.

Parameters

Name	In	Type	Required	Description
`since`	query	string	No	An event id of this feed (`evt_…`, exclusive, recommended; unknown ids are `400`) or an RFC 3339 instant (starts one second early; may repeat events).
`types`	query	string	No	Comma-separated event types. Example: `inbound.announced,inbound.cancelled`.
`limit`	query	integer	No	Default: `50`. Minimum 1. Maximum 100.

Responses

Status	Description	Body
`200`	Events in feed order.	object
`default`	Error	Error

Response 200

Field	Type	Required	Description
`data`	array of Envelope	Yes
`next_cursor`	string \| null	Yes	Id of the last event returned; null when none was.
`has_more`	boolean	Yes

Example response

{
  "data": [
    {
      "id": "evt_0193a1b2-7c4d-7e8f-9a0b-1c2d3e4f5a01",
      "type": "inbound.announced",
      "api_version": "2026-11-01",
      "occurred_at": "2026-11-03T10:15:00Z",
      "created_at": "2026-11-03T10:15:01Z",
      "connection_id": "pcn_812",
      "data": {
        "inbound": {
          "id": "inb_2000000123",
          "external_id": null,
          "batch_id": null,
          "status": "open",
          "name": "amazon.de | Bosch GSR 18V-55 Drill Driver | 302-1234567-1234567",
          "notes": "Fragile, please bubble-wrap\nFulfillment: FBA",
          "fulfillment": "FBA",
          "warehouse": {
            "id": "wh_12",
            "name": "Warehouse South"
          },
          "order": {
            "numbers": [
              "302-1234567-1234567"
            ],
            "supplier_host": "amazon.de",
            "purchased_at": "2026-11-02"
          },
          "tracking_numbers": [
            "1Z999AA10123456784"
          ],
          "lines": [
            {
              "id": "inl_99",
              "purchase_id": "pur_4711",
              "item": {
                "id": "itm_17",
                "sku": "AB-123",
                "fnsku": null,
                "asin": "B0ABCDEFGH",
                "ean": "4006381333931",
                "title": "Bosch GSR 18V-55 Drill Driver",
                "image_url": "https://m.media-amazon.com/images/I/61Xf3kqcQhL.jpg"
              },
              "quantity_expected": 6,
              "quantity_received": 0,
              "quantity_damaged": 0,
              "status": "open"
            }
          ],
          "created_at": "2026-11-03T10:15:00Z"
        },
        "traces": [
          {
            "purchase_id": "pur_4711",
            "inbound_id": "inb_2000000123",
            "inbound_line_id": "inl_99",
            "item_id": "itm_17",
            "sku": "AB-123",
            "fnsku": null,
            "asin": "B0ABCDEFGH",
            "order_number": "302-1234567-1234567",
            "batch_id": null,
            "outbound_ids": [],
            "amazon_shipment_ids": []
          }
        ],
        "changes": null,
        "reason": null,
        "replaced_by_inbound_id": null
      }
    }
  ],
  "next_cursor": "evt_0193a1b2-7c4d-7e8f-9a0b-1c2d3e4f5a01",
  "has_more": true
}

Connections

The key's own connection

GET/v1/prep/connections

Returns the key's connection in the list shape shared with prep providers. seller.name is the workspace name, customer_reference is always null for an own-software connection.

Parameters

Name	In	Type	Required	Description
`cursor`	query	string	No	`next_cursor` of the previous page.
`limit`	query	integer	No	Default: `50`. Minimum 1. Maximum 100.

Responses

Status	Description	Body
`200`	Connections ordered by id.	object
`default`	Error	Error

Response 200

Field	Type	Required	Description
`data`	array of Connection	Yes
`next_cursor`	string \| null	Yes

Example response

{
  "data": [
    {
      "id": "pcn_812",
      "status": "active",
      "seller": {
        "name": "Sample Trading",
        "customer_reference": null,
        "seller_id": "A1B2C3D4E5F6G7"
      },
      "created_at": "2026-11-01T09:00:00Z"
    }
  ],
  "next_cursor": null
}

Webhooks

ProfitDesk sends these events as signed POST requests to the endpoint URL of the connection. Headers, body and the responses ProfitDesk expects from you.

inbound.announced

POSTyour endpoint URL

Goods are on their way to you

Delivered as POST to your endpoint URL with these headers:

Header	Value
`X-Webhook-Event`	the envelope `id` (`evt_…`), for deduplication
`X-Webhook-Event-Type`	e.g. `inbound.announced`
`X-Webhook-Timestamp`	Unix seconds of the attempt
`X-Webhook-Signature`	`sha256=<hex>`; during a secret rotation two, comma-separated
`User-Agent`	`ProfitDesk-Webhooks/1`

Verify the signature before trusting the body: compute hex(HMAC-SHA256(secret, timestamp + "." + rawBody)) with your signing secret (whsec_…, used as-is as the HMAC key) over the raw request body, and accept the request if it equals any sha256= entry of the header (compare in constant time). Reject timestamps more than five minutes from your clock. After a rotation the previous secret stays valid for 24 hours.

Respond with any 2xx within 10 seconds. Timeouts, 408, 429 and 5xx are retried after 1 min, 5 min, 15 min, 1 h, 3 h, 6 h, then every 12 h until 72 h after the event was queued; 3xx and other 4xx fail at once (410 included); only 72 h without any success disables the endpoint.

You may answer {"external_id": "<your id>"}; it is stored like PUT …/external-id, but without an inbound.updated event. It must be unique within your connection; a value another inbound already uses is not stored (the delivery still counts). The purchase only counts as announced once you answered 2xx. Events of the same inbound are delivered in order, one at a time. If the inbound is cancelled before you received any of its events, they are all skipped; a reactivation of such an inbound also arrives as inbound.announced.

inbound.received and outbound.recorded echo your own API calls and are off unless you subscribe to them.

Headers

Name	In	Type	Required
`X-Webhook-Event`	header	string	Yes
`X-Webhook-Event-Type`	header	string	Yes
`X-Webhook-Timestamp`	header	string	Yes
`X-Webhook-Signature`	header	string	Yes

Request body

Schema: InboundEventEnvelope

Field	Type	Required	Description
`id`	string	Yes	Example: `evt_0193a1b2-7c4d-7e8f-9a0b-1c2d3e4f5a01`.
`type`	string	Yes	One of: `inbound.announced`, `inbound.updated`, `inbound.cancelled`, `inbound.restored`, `inbound.received`, `outbound.recorded`, `ping`.
`api_version`	string	Yes	Example: `2026-11-01`.
`occurred_at`	string (date-time)	Yes
`created_at`	string (date-time)	Yes
`connection_id`	string	Yes	Example: `pcn_812`.
`data`	InboundEventData	Yes

Example request

{
  "id": "evt_0193a1b2-7c4d-7e8f-9a0b-1c2d3e4f5a01",
  "type": "inbound.announced",
  "api_version": "2026-11-01",
  "occurred_at": "2026-11-03T10:15:00Z",
  "created_at": "2026-11-03T10:15:01Z",
  "connection_id": "pcn_812",
  "data": {
    "inbound": {
      "id": "inb_2000000123",
      "external_id": null,
      "batch_id": null,
      "status": "open",
      "name": "amazon.de | Bosch GSR 18V-55 Drill Driver | 302-1234567-1234567",
      "notes": "Fragile, please bubble-wrap\nFulfillment: FBA",
      "fulfillment": "FBA",
      "warehouse": {
        "id": "wh_12",
        "name": "Warehouse South"
      },
      "order": {
        "numbers": [
          "302-1234567-1234567"
        ],
        "supplier_host": "amazon.de",
        "purchased_at": "2026-11-02"
      },
      "tracking_numbers": [
        "1Z999AA10123456784"
      ],
      "lines": [
        {
          "id": "inl_99",
          "purchase_id": "pur_4711",
          "item": {
            "id": "itm_17",
            "sku": "AB-123",
            "fnsku": null,
            "asin": "B0ABCDEFGH",
            "ean": "4006381333931",
            "title": "Bosch GSR 18V-55 Drill Driver",
            "image_url": "https://m.media-amazon.com/images/I/61Xf3kqcQhL.jpg"
          },
          "quantity_expected": 6,
          "quantity_received": 0,
          "quantity_damaged": 0,
          "status": "open"
        }
      ],
      "created_at": "2026-11-03T10:15:00Z"
    },
    "traces": [
      {
        "purchase_id": "pur_4711",
        "inbound_id": "inb_2000000123",
        "inbound_line_id": "inl_99",
        "item_id": "itm_17",
        "sku": "AB-123",
        "fnsku": null,
        "asin": "B0ABCDEFGH",
        "order_number": "302-1234567-1234567",
        "batch_id": null,
        "outbound_ids": [],
        "amazon_shipment_ids": []
      }
    ],
    "changes": null,
    "reason": null,
    "replaced_by_inbound_id": null
  }
}

Responses

Status	Description	Body
`200`	Delivered. Any 2xx works.	object
`4XX`	3xx (redirects are not followed) and any other 4xx except 408/429, 410 included: the delivery fails at once, without retry; the endpoint stays enabled. For `inbound.announced` the seller sees the announcement as failed.
`5XX`	Retried after 1 min, 5 min, 15 min, 1 h, 3 h, 6 h, then every 12 h, until 72 h after the event was queued. Timeouts (10 s), connection errors, 408 and 429 are treated the same. After 72 h without any successful delivery, a failed attempt disables the endpoint.

inbound.updated

POSTyour endpoint URL

Tracking numbers, an FNSKU, your external id or line states changed (see data.changes)

Same headers, signature, response and retry rules as inbound.announced.

Headers

Name	In	Type	Required
`X-Webhook-Event`	header	string	Yes
`X-Webhook-Event-Type`	header	string	Yes
`X-Webhook-Timestamp`	header	string	Yes
`X-Webhook-Signature`	header	string	Yes

Request body

Schema: InboundEventEnvelope

Field	Type	Required	Description
`id`	string	Yes	Example: `evt_0193a1b2-7c4d-7e8f-9a0b-1c2d3e4f5a01`.
`type`	string	Yes	One of: `inbound.announced`, `inbound.updated`, `inbound.cancelled`, `inbound.restored`, `inbound.received`, `outbound.recorded`, `ping`.
`api_version`	string	Yes	Example: `2026-11-01`.
`occurred_at`	string (date-time)	Yes
`created_at`	string (date-time)	Yes
`connection_id`	string	Yes	Example: `pcn_812`.
`data`	InboundEventData	Yes

{
  "id": "evt_0193a1b2-7c4d-7e8f-9a0b-1c2d3e4f5a02",
  "type": "inbound.updated",
  "api_version": "2026-11-01",
  "occurred_at": "2026-11-04T07:30:00Z",
  "created_at": "2026-11-04T07:30:01Z",
  "connection_id": "pcn_812",
  "data": {
    "inbound": {
      "id": "inb_2000000123",
      "external_id": "WMS-IN-5521",
      "batch_id": null,
      "status": "open",
      "name": "amazon.de | Bosch GSR 18V-55 Drill Driver | 302-1234567-1234567",
      "notes": "Fragile, please bubble-wrap\nFulfillment: FBA",
      "fulfillment": "FBA",
      "warehouse": {
        "id": "wh_12",
        "name": "Warehouse South"
      },
      "order": {
        "numbers": [
          "302-1234567-1234567"
        ],
        "supplier_host": "amazon.de",
        "purchased_at": "2026-11-02"
      },
      "tracking_numbers": [
        "1Z999AA10123456784",
        "JJD000390007754321"
      ],
      "lines": [
        {
          "id": "inl_99",
          "purchase_id": "pur_4711",
          "item": {
            "id": "itm_17",
            "sku": "AB-123",
            "fnsku": "X00ABCDEFG",
            "asin": "B0ABCDEFGH",
            "ean": "4006381333931",
            "title": "Bosch GSR 18V-55 Drill Driver",
            "image_url": "https://m.media-amazon.com/images/I/61Xf3kqcQhL.jpg"
          },
          "quantity_expected": 6,
          "quantity_received": 0,
          "quantity_damaged": 0,
          "status": "open"
        }
      ],
      "created_at": "2026-11-03T10:15:00Z"
    },
    "traces": [
      {
        "purchase_id": "pur_4711",
        "inbound_id": "inb_2000000123",
        "inbound_line_id": "inl_99",
        "item_id": "itm_17",
        "sku": "AB-123",
        "fnsku": "X00ABCDEFG",
        "asin": "B0ABCDEFGH",
        "order_number": "302-1234567-1234567",
        "batch_id": null,
        "outbound_ids": [],
        "amazon_shipment_ids": []
      }
    ],
    "changes": [
      "tracking_numbers",
      "fnsku"
    ],
    "reason": null,
    "replaced_by_inbound_id": null
  }
}

{
  "id": "evt_0193a1b2-7c4d-7e8f-9a0b-1c2d3e4f5a03",
  "type": "inbound.updated",
  "api_version": "2026-11-01",
  "occurred_at": "2026-11-04T12:00:00Z",
  "created_at": "2026-11-04T12:00:01Z",
  "connection_id": "pcn_812",
  "data": {
    "inbound": {
      "id": "inb_2000000131",
      "external_id": "WMS-IN-5530",
      "batch_id": "0d1f6a2e-4b7c-4c11-9a3e-5f2b8c7d9e10",
      "status": "open",
      "name": "amazon.de | Bosch GSR 18V-55 Drill Driver +1 | 302-1234567-1234567, 302-7654321-7654321",
      "notes": "Fragile, please bubble-wrap\nFulfillment: FBA",
      "fulfillment": "FBA",
      "warehouse": {
        "id": "wh_12",
        "name": "Warehouse South"
      },
      "order": {
        "numbers": [
          "302-1234567-1234567",
          "302-7654321-7654321"
        ],
        "supplier_host": "amazon.de",
        "purchased_at": "2026-11-02"
      },
      "tracking_numbers": [
        "1Z999AA10123456784"
      ],
      "lines": [
        {
          "id": "inl_120",
          "purchase_id": "pur_4720",
          "item": {
            "id": "itm_17",
            "sku": "AB-123",
            "fnsku": "X00ABCDEFG",
            "asin": "B0ABCDEFGH",
            "ean": "4006381333931",
            "title": "Bosch GSR 18V-55 Drill Driver",
            "image_url": "https://m.media-amazon.com/images/I/61Xf3kqcQhL.jpg"
          },
          "quantity_expected": 6,
          "quantity_received": 0,
          "quantity_damaged": 0,
          "status": "open"
        },
        {
          "id": "inl_121",
          "purchase_id": "pur_4721",
          "item": {
            "id": "itm_18",
            "sku": "CD-456",
            "fnsku": "X00BCDEFGH",
            "asin": "B0BCDEFGHI",
            "ean": "4059952513164",
            "title": "Bosch GBA 18V 4.0Ah Battery",
            "image_url": "https://m.media-amazon.com/images/I/51Zk2mN8pRL.jpg"
          },
          "quantity_expected": 2,
          "quantity_received": 0,
          "quantity_damaged": 0,
          "status": "cancelled"
        }
      ],
      "created_at": "2026-11-03T10:15:00Z"
    },
    "traces": [
      {
        "purchase_id": "pur_4720",
        "inbound_id": "inb_2000000131",
        "inbound_line_id": "inl_120",
        "item_id": "itm_17",
        "sku": "AB-123",
        "fnsku": "X00ABCDEFG",
        "asin": "B0ABCDEFGH",
        "order_number": "302-1234567-1234567",
        "batch_id": "0d1f6a2e-4b7c-4c11-9a3e-5f2b8c7d9e10",
        "outbound_ids": [],
        "amazon_shipment_ids": []
      },
      {
        "purchase_id": "pur_4721",
        "inbound_id": "inb_2000000131",
        "inbound_line_id": "inl_121",
        "item_id": "itm_18",
        "sku": "CD-456",
        "fnsku": "X00BCDEFGH",
        "asin": "B0BCDEFGHI",
        "order_number": "302-7654321-7654321",
        "batch_id": "0d1f6a2e-4b7c-4c11-9a3e-5f2b8c7d9e10",
        "outbound_ids": [],
        "amazon_shipment_ids": []
      }
    ],
    "changes": [
      "lines"
    ],
    "reason": "purchase_cancelled",
    "replaced_by_inbound_id": null
  }
}

Responses

Status	Description	Body
`200`	Delivered. Any 2xx works.	object
`4XX`	3xx (redirects are not followed) and any other 4xx except 408/429, 410 included: the delivery fails at once, without retry; the endpoint stays enabled. For `inbound.announced` the seller sees the announcement as failed.
`5XX`	Retried after 1 min, 5 min, 15 min, 1 h, 3 h, 6 h, then every 12 h, until 72 h after the event was queued. Timeouts (10 s), connection errors, 408 and 429 are treated the same. After 72 h without any successful delivery, a failed attempt disables the endpoint.

inbound.cancelled

POSTyour endpoint URL

The whole inbound is cancelled (see data.reason)

Same headers, signature, response and retry rules as inbound.announced. Skipped (never sent) if you received none of the inbound's events before.

Headers

Name	In	Type	Required
`X-Webhook-Event`	header	string	Yes
`X-Webhook-Event-Type`	header	string	Yes
`X-Webhook-Timestamp`	header	string	Yes
`X-Webhook-Signature`	header	string	Yes

Request body

Schema: InboundEventEnvelope

Field	Type	Required	Description
`id`	string	Yes	Example: `evt_0193a1b2-7c4d-7e8f-9a0b-1c2d3e4f5a01`.
`type`	string	Yes	One of: `inbound.announced`, `inbound.updated`, `inbound.cancelled`, `inbound.restored`, `inbound.received`, `outbound.recorded`, `ping`.
`api_version`	string	Yes	Example: `2026-11-01`.
`occurred_at`	string (date-time)	Yes
`created_at`	string (date-time)	Yes
`connection_id`	string	Yes	Example: `pcn_812`.
`data`	InboundEventData	Yes

Example request

{
  "id": "evt_0193a1b2-7c4d-7e8f-9a0b-1c2d3e4f5a04",
  "type": "inbound.cancelled",
  "api_version": "2026-11-01",
  "occurred_at": "2026-11-04T15:00:00Z",
  "created_at": "2026-11-04T15:00:01Z",
  "connection_id": "pcn_812",
  "data": {
    "inbound": {
      "id": "inb_2000000123",
      "external_id": "WMS-IN-5521",
      "batch_id": null,
      "status": "cancelled",
      "name": "amazon.de | Bosch GSR 18V-55 Drill Driver | 302-1234567-1234567",
      "notes": "Fragile, please bubble-wrap\nFulfillment: FBA",
      "fulfillment": "FBA",
      "warehouse": {
        "id": "wh_12",
        "name": "Warehouse South"
      },
      "order": {
        "numbers": [
          "302-1234567-1234567"
        ],
        "supplier_host": "amazon.de",
        "purchased_at": "2026-11-02"
      },
      "tracking_numbers": [
        "1Z999AA10123456784"
      ],
      "lines": [
        {
          "id": "inl_99",
          "purchase_id": "pur_4711",
          "item": {
            "id": "itm_17",
            "sku": "AB-123",
            "fnsku": "X00ABCDEFG",
            "asin": "B0ABCDEFGH",
            "ean": "4006381333931",
            "title": "Bosch GSR 18V-55 Drill Driver",
            "image_url": "https://m.media-amazon.com/images/I/61Xf3kqcQhL.jpg"
          },
          "quantity_expected": 6,
          "quantity_received": 0,
          "quantity_damaged": 0,
          "status": "cancelled"
        }
      ],
      "created_at": "2026-11-03T10:15:00Z"
    },
    "traces": [
      {
        "purchase_id": "pur_4711",
        "inbound_id": "inb_2000000123",
        "inbound_line_id": "inl_99",
        "item_id": "itm_17",
        "sku": "AB-123",
        "fnsku": "X00ABCDEFG",
        "asin": "B0ABCDEFGH",
        "order_number": "302-1234567-1234567",
        "batch_id": null,
        "outbound_ids": [],
        "amazon_shipment_ids": []
      }
    ],
    "changes": null,
    "reason": "reannounced",
    "replaced_by_inbound_id": "inb_2000000140"
  }
}

Responses

Status	Description	Body
`200`	Delivered. Any 2xx works.	object
`4XX`	3xx (redirects are not followed) and any other 4xx except 408/429, 410 included: the delivery fails at once, without retry; the endpoint stays enabled. For `inbound.announced` the seller sees the announcement as failed.
`5XX`	Retried after 1 min, 5 min, 15 min, 1 h, 3 h, 6 h, then every 12 h, until 72 h after the event was queued. Timeouts (10 s), connection errors, 408 and 429 are treated the same. After 72 h without any successful delivery, a failed attempt disables the endpoint.

inbound.restored

POSTyour endpoint URL

A cancelled inbound is active again

Same headers, signature, response and retry rules as inbound.announced. If you never received the inbound, a reactivation arrives as inbound.announced instead.

Headers

Name	In	Type	Required
`X-Webhook-Event`	header	string	Yes
`X-Webhook-Event-Type`	header	string	Yes
`X-Webhook-Timestamp`	header	string	Yes
`X-Webhook-Signature`	header	string	Yes

Request body

Schema: InboundEventEnvelope

Field	Type	Required	Description
`id`	string	Yes	Example: `evt_0193a1b2-7c4d-7e8f-9a0b-1c2d3e4f5a01`.
`type`	string	Yes	One of: `inbound.announced`, `inbound.updated`, `inbound.cancelled`, `inbound.restored`, `inbound.received`, `outbound.recorded`, `ping`.
`api_version`	string	Yes	Example: `2026-11-01`.
`occurred_at`	string (date-time)	Yes
`created_at`	string (date-time)	Yes
`connection_id`	string	Yes	Example: `pcn_812`.
`data`	InboundEventData	Yes

Example request

{
  "id": "evt_0193a1b2-7c4d-7e8f-9a0b-1c2d3e4f5a05",
  "type": "inbound.restored",
  "api_version": "2026-11-01",
  "occurred_at": "2026-11-04T16:00:00Z",
  "created_at": "2026-11-04T16:00:01Z",
  "connection_id": "pcn_812",
  "data": {
    "inbound": {
      "id": "inb_2000000123",
      "external_id": "WMS-IN-5521",
      "batch_id": null,
      "status": "open",
      "name": "amazon.de | Bosch GSR 18V-55 Drill Driver | 302-1234567-1234567",
      "notes": "Fragile, please bubble-wrap\nFulfillment: FBA",
      "fulfillment": "FBA",
      "warehouse": {
        "id": "wh_12",
        "name": "Warehouse South"
      },
      "order": {
        "numbers": [
          "302-1234567-1234567"
        ],
        "supplier_host": "amazon.de",
        "purchased_at": "2026-11-02"
      },
      "tracking_numbers": [
        "1Z999AA10123456784"
      ],
      "lines": [
        {
          "id": "inl_99",
          "purchase_id": "pur_4711",
          "item": {
            "id": "itm_17",
            "sku": "AB-123",
            "fnsku": "X00ABCDEFG",
            "asin": "B0ABCDEFGH",
            "ean": "4006381333931",
            "title": "Bosch GSR 18V-55 Drill Driver",
            "image_url": "https://m.media-amazon.com/images/I/61Xf3kqcQhL.jpg"
          },
          "quantity_expected": 6,
          "quantity_received": 0,
          "quantity_damaged": 0,
          "status": "open"
        }
      ],
      "created_at": "2026-11-03T10:15:00Z"
    },
    "traces": [
      {
        "purchase_id": "pur_4711",
        "inbound_id": "inb_2000000123",
        "inbound_line_id": "inl_99",
        "item_id": "itm_17",
        "sku": "AB-123",
        "fnsku": "X00ABCDEFG",
        "asin": "B0ABCDEFGH",
        "order_number": "302-1234567-1234567",
        "batch_id": null,
        "outbound_ids": [],
        "amazon_shipment_ids": []
      }
    ],
    "changes": null,
    "reason": null,
    "replaced_by_inbound_id": null
  }
}

Responses

Status	Description	Body
`200`	Delivered. Any 2xx works.	object
`4XX`	3xx (redirects are not followed) and any other 4xx except 408/429, 410 included: the delivery fails at once, without retry; the endpoint stays enabled. For `inbound.announced` the seller sees the announcement as failed.
`5XX`	Retried after 1 min, 5 min, 15 min, 1 h, 3 h, 6 h, then every 12 h, until 72 h after the event was queued. Timeouts (10 s), connection errors, 408 and 429 are treated the same. After 72 h without any successful delivery, a failed attempt disables the endpoint.

inbound.received

POSTyour endpoint URL

Echo of a receipt you reported (off unless subscribed)

Same headers, signature, response and retry rules as inbound.announced.

Headers

Name	In	Type	Required
`X-Webhook-Event`	header	string	Yes
`X-Webhook-Event-Type`	header	string	Yes
`X-Webhook-Timestamp`	header	string	Yes
`X-Webhook-Signature`	header	string	Yes

Request body

Schema: InboundEventEnvelope

Field	Type	Required	Description
`id`	string	Yes	Example: `evt_0193a1b2-7c4d-7e8f-9a0b-1c2d3e4f5a01`.
`type`	string	Yes	One of: `inbound.announced`, `inbound.updated`, `inbound.cancelled`, `inbound.restored`, `inbound.received`, `outbound.recorded`, `ping`.
`api_version`	string	Yes	Example: `2026-11-01`.
`occurred_at`	string (date-time)	Yes
`created_at`	string (date-time)	Yes
`connection_id`	string	Yes	Example: `pcn_812`.
`data`	InboundEventData	Yes

Example request

{
  "id": "evt_0193a1b2-7c4d-7e8f-9a0b-1c2d3e4f5a06",
  "type": "inbound.received",
  "api_version": "2026-11-01",
  "occurred_at": "2026-11-05T09:30:00Z",
  "created_at": "2026-11-05T09:30:01Z",
  "connection_id": "pcn_812",
  "data": {
    "inbound": {
      "id": "inb_2000000123",
      "external_id": "WMS-IN-5521",
      "batch_id": null,
      "status": "received",
      "name": "amazon.de | Bosch GSR 18V-55 Drill Driver | 302-1234567-1234567",
      "notes": "Fragile, please bubble-wrap\nFulfillment: FBA",
      "fulfillment": "FBA",
      "warehouse": {
        "id": "wh_12",
        "name": "Warehouse South"
      },
      "order": {
        "numbers": [
          "302-1234567-1234567"
        ],
        "supplier_host": "amazon.de",
        "purchased_at": "2026-11-02"
      },
      "tracking_numbers": [
        "1Z999AA10123456784"
      ],
      "lines": [
        {
          "id": "inl_99",
          "purchase_id": "pur_4711",
          "item": {
            "id": "itm_17",
            "sku": "AB-123",
            "fnsku": "X00ABCDEFG",
            "asin": "B0ABCDEFGH",
            "ean": "4006381333931",
            "title": "Bosch GSR 18V-55 Drill Driver",
            "image_url": "https://m.media-amazon.com/images/I/61Xf3kqcQhL.jpg"
          },
          "quantity_expected": 6,
          "quantity_received": 6,
          "quantity_damaged": 1,
          "status": "received"
        }
      ],
      "created_at": "2026-11-03T10:15:00Z"
    },
    "traces": [
      {
        "purchase_id": "pur_4711",
        "inbound_id": "inb_2000000123",
        "inbound_line_id": "inl_99",
        "item_id": "itm_17",
        "sku": "AB-123",
        "fnsku": "X00ABCDEFG",
        "asin": "B0ABCDEFGH",
        "order_number": "302-1234567-1234567",
        "batch_id": null,
        "outbound_ids": [],
        "amazon_shipment_ids": []
      }
    ],
    "changes": null,
    "reason": null,
    "replaced_by_inbound_id": null
  }
}

Responses

Status	Description	Body
`200`	Delivered. Any 2xx works.	object
`4XX`	3xx (redirects are not followed) and any other 4xx except 408/429, 410 included: the delivery fails at once, without retry; the endpoint stays enabled. For `inbound.announced` the seller sees the announcement as failed.
`5XX`	Retried after 1 min, 5 min, 15 min, 1 h, 3 h, 6 h, then every 12 h, until 72 h after the event was queued. Timeouts (10 s), connection errors, 408 and 429 are treated the same. After 72 h without any successful delivery, a failed attempt disables the endpoint.

outbound.recorded

POSTyour endpoint URL

Echo of an outbound you reported (off unless subscribed)

Same headers, signature, response and retry rules as inbound.announced.

Headers

Name	In	Type	Required
`X-Webhook-Event`	header	string	Yes
`X-Webhook-Event-Type`	header	string	Yes
`X-Webhook-Timestamp`	header	string	Yes
`X-Webhook-Signature`	header	string	Yes

Request body

Schema: OutboundEventEnvelope

Field	Type	Required	Description
`id`	string	Yes	Example: `evt_0193a1b2-7c4d-7e8f-9a0b-1c2d3e4f5a01`.
`type`	string	Yes	One of: `inbound.announced`, `inbound.updated`, `inbound.cancelled`, `inbound.restored`, `inbound.received`, `outbound.recorded`, `ping`.
`api_version`	string	Yes	Example: `2026-11-01`.
`occurred_at`	string (date-time)	Yes
`created_at`	string (date-time)	Yes
`connection_id`	string	Yes	Example: `pcn_812`.
`data`	OutboundEventData	Yes

Example request

{
  "id": "evt_0193a1b2-7c4d-7e8f-9a0b-1c2d3e4f5a07",
  "type": "outbound.recorded",
  "api_version": "2026-11-01",
  "occurred_at": "2026-11-06T14:00:00Z",
  "created_at": "2026-11-06T14:00:01Z",
  "connection_id": "pcn_812",
  "data": {
    "outbound": {
      "id": "out_55",
      "external_id": "OUT-311",
      "status": "shipped",
      "destination": {
        "type": "fba",
        "amazon_shipment_id": "FBA15XYZ",
        "marketplace": "DE"
      },
      "tracking_numbers": [
        "1Z999AA10123456784"
      ],
      "shipped_at": "2026-11-06T14:00:00Z",
      "lines": [
        {
          "purchase_id": "pur_4720",
          "inbound_line_id": "inl_120",
          "quantity": 4,
          "resolved_by": "line_id"
        },
        {
          "purchase_id": "pur_4721",
          "inbound_line_id": "inl_121",
          "quantity": 2,
          "resolved_by": "sku_fifo"
        }
      ]
    },
    "traces": [
      {
        "purchase_id": "pur_4720",
        "inbound_id": "inb_2000000131",
        "inbound_line_id": "inl_120",
        "item_id": "itm_17",
        "sku": "AB-123",
        "fnsku": "X00ABCDEFG",
        "asin": "B0ABCDEFGH",
        "order_number": "302-1234567-1234567",
        "batch_id": "0d1f6a2e-4b7c-4c11-9a3e-5f2b8c7d9e10",
        "outbound_ids": [
          "out_55"
        ],
        "amazon_shipment_ids": [
          "FBA15XYZ"
        ]
      },
      {
        "purchase_id": "pur_4721",
        "inbound_id": "inb_2000000131",
        "inbound_line_id": "inl_121",
        "item_id": "itm_18",
        "sku": "CD-456",
        "fnsku": "X00BCDEFGH",
        "asin": "B0BCDEFGHI",
        "order_number": "302-7654321-7654321",
        "batch_id": "0d1f6a2e-4b7c-4c11-9a3e-5f2b8c7d9e10",
        "outbound_ids": [
          "out_55"
        ],
        "amazon_shipment_ids": [
          "FBA15XYZ"
        ]
      }
    ]
  }
}

Responses

Status	Description	Body
`200`	Delivered. Any 2xx works.	object
`4XX`	3xx (redirects are not followed) and any other 4xx except 408/429, 410 included: the delivery fails at once, without retry; the endpoint stays enabled. For `inbound.announced` the seller sees the announcement as failed.
`5XX`	Retried after 1 min, 5 min, 15 min, 1 h, 3 h, 6 h, then every 12 h, until 72 h after the event was queued. Timeouts (10 s), connection errors, 408 and 429 are treated the same. After 72 h without any successful delivery, a failed attempt disables the endpoint.

ping

POSTyour endpoint URL

"Send test" in ProfitDesk; sent once, not stored, not replayable

Same headers and signature as inbound.announced. Sent once while the seller waits for the result; not retried.

Headers

Name	In	Type	Required
`X-Webhook-Event`	header	string	Yes
`X-Webhook-Event-Type`	header	string	Yes
`X-Webhook-Timestamp`	header	string	Yes
`X-Webhook-Signature`	header	string	Yes

Request body

Schema: PingEventEnvelope

Field	Type	Required	Description
`id`	string	Yes	Example: `evt_0193a1b2-7c4d-7e8f-9a0b-1c2d3e4f5a01`.
`type`	string	Yes	One of: `inbound.announced`, `inbound.updated`, `inbound.cancelled`, `inbound.restored`, `inbound.received`, `outbound.recorded`, `ping`.
`api_version`	string	Yes	Example: `2026-11-01`.
`occurred_at`	string (date-time)	Yes
`created_at`	string (date-time)	Yes
`connection_id`	string	Yes	Example: `pcn_812`.
`data`	object	Yes
`data.message`	string	Yes

Example request

{
  "id": "evt_0193a1b2-7c4d-7e8f-9a0b-1c2d3e4f5a08",
  "type": "ping",
  "api_version": "2026-11-01",
  "occurred_at": "2026-11-03T09:00:00Z",
  "created_at": "2026-11-03T09:00:00Z",
  "connection_id": "pcn_812",
  "data": {
    "message": "Test event from ProfitDesk"
  }
}

Responses

Status	Description	Body
`200`	The test succeeded. Any 2xx works.
`default`	The seller sees the status code and the start of your response body.

Schemas

Every object of the API, field by field. Nested fields are listed with their path, e.g. lines[].id.

Error

Field	Type	Required	Description
`error`	object	Yes
`error.code`	string	Yes	Example: `line_not_found`.
`error.message`	string	Yes
`error.details`	array of any	Yes	Empty unless the code fills it: `line_not_found` (unknown lines, or the `unresolved` entries of an outbound), `inbound_cancelled` for one line.

Envelope

Field	Type	Required	Description
`id`	string	Yes	Example: `evt_0193a1b2-7c4d-7e8f-9a0b-1c2d3e4f5a01`.
`type`	string	Yes	One of: `inbound.announced`, `inbound.updated`, `inbound.cancelled`, `inbound.restored`, `inbound.received`, `outbound.recorded`, `ping`.
`api_version`	string	Yes	Example: `2026-11-01`.
`occurred_at`	string (date-time)	Yes
`created_at`	string (date-time)	Yes
`connection_id`	string	Yes	Example: `pcn_812`.
`data`	object	Yes

InboundEventEnvelope

Body of every inbound.* webhook event.

Field	Type	Required	Description
`id`	string	Yes	Example: `evt_0193a1b2-7c4d-7e8f-9a0b-1c2d3e4f5a01`.
`type`	string	Yes	One of: `inbound.announced`, `inbound.updated`, `inbound.cancelled`, `inbound.restored`, `inbound.received`, `outbound.recorded`, `ping`.
`api_version`	string	Yes	Example: `2026-11-01`.
`occurred_at`	string (date-time)	Yes
`created_at`	string (date-time)	Yes
`connection_id`	string	Yes	Example: `pcn_812`.
`data`	InboundEventData	Yes

OutboundEventEnvelope

Body of outbound.recorded.

Field	Type	Required	Description
`id`	string	Yes	Example: `evt_0193a1b2-7c4d-7e8f-9a0b-1c2d3e4f5a01`.
`type`	string	Yes	One of: `inbound.announced`, `inbound.updated`, `inbound.cancelled`, `inbound.restored`, `inbound.received`, `outbound.recorded`, `ping`.
`api_version`	string	Yes	Example: `2026-11-01`.
`occurred_at`	string (date-time)	Yes
`created_at`	string (date-time)	Yes
`connection_id`	string	Yes	Example: `pcn_812`.
`data`	OutboundEventData	Yes

Connection

Field	Type	Required	Description
`id`	string	Yes	Example: `pcn_812`.
`status`	string	Yes	One of: `active`, `removed`.
`seller`	object	Yes
`seller.name`	string \| null	Yes	The seller's workspace name; null if none is set.
`seller.customer_reference`	string \| null	Yes	Always null for an own-software connection.
`seller.seller_id`	string \| null	Yes	The Amazon selling partner id of the account owner; null if no Amazon account is connected.
`created_at`	string (date-time)	Yes

PingEventEnvelope

Body of ping.

Field	Type	Required	Description
`id`	string	Yes	Example: `evt_0193a1b2-7c4d-7e8f-9a0b-1c2d3e4f5a01`.
`type`	string	Yes	One of: `inbound.announced`, `inbound.updated`, `inbound.cancelled`, `inbound.restored`, `inbound.received`, `outbound.recorded`, `ping`.
`api_version`	string	Yes	Example: `2026-11-01`.
`occurred_at`	string (date-time)	Yes
`created_at`	string (date-time)	Yes
`connection_id`	string	Yes	Example: `pcn_812`.
`data`	object	Yes
`data.message`	string	Yes

OutboundEventData

Field	Type	Required	Description
`outbound`	Outbound	Yes
`traces`	array of Trace	Yes	One per purchase on the outbound.

InboundEventData

Field	Type	Required	Description
`inbound`	Inbound	Yes
`traces`	array of Trace	Yes	One per line, in the order of `inbound.lines`.
`changes`	array of string \| null	Yes	`null` except on `inbound.updated`: the fields that changed. `lines` means some lines of a shared inbound were cancelled or restored while the inbound stays open; read each line's `status`. `external_id` is sent only for a changed value set with `PUT …/external-id`.
`reason`	string \| null	Yes	`null` except on `inbound.cancelled`, and on `inbound.updated` when a line was cancelled. `offer_deleted` is reserved. One of: `purchase_cancelled`, `purchase_deactivated`, `warehouse_changed`, `reannounced`, `offer_deleted`.
`replaced_by_inbound_id`	string \| null	Yes	`null` except on `inbound.cancelled` / `inbound.updated` with reason `reannounced`: the new inbound that takes over the goods.

InboundView

Field	Type	Required	Description
`connection_id`	string	Yes	Example: `pcn_812`.
`inbound`	Inbound	Yes
`traces`	array of Trace	Yes

ExternalIdResponse

Field	Type	Required	Description
`connection_id`	string	Yes	Example: `pcn_812`.
`inbound`	Inbound	Yes
`traces`	array of Trace	Yes
`event_id`	string \| null	Yes	The idempotency key; null without one.
`duplicate`	boolean	Yes

Inbound

Field	Type	Required	Description
`id`	string	Yes	Example: `inb_2000000123`.
`external_id`	string \| null	Yes
`batch_id`	string \| null	Yes	Purchases announced together arrive together.
`status`	string	Yes	`received` once every line is received or cancelled and at least one is received; `cancelled` once every line is cancelled. One of: `open`, `received`, `cancelled`.
`name`	string	Yes	`<supplier> \| <product> \| <order numbers>`; the product (first 30 characters, `+N` for more lines) only if the seller transfers product names. If none is known: the inbound id. Max length 255.
`notes`	string	Yes	Seller notes (if transferred) plus a final line `Fulfillment: FBA` or `Fulfillment: FBM`.
`fulfillment`	string	Yes	One of: `FBA`, `FBM`.
`warehouse`	object \| null	Yes	The seller's warehouse the goods are sent to. A move between warehouses of the same connection sends no event; the next payload carries the new warehouse.
`warehouse.id`	string	Yes	Example: `wh_12`.
`warehouse.name`	string	Yes
`order`	object	Yes
`order.numbers`	array of string	Yes
`order.supplier_host`	string \| null	Yes	Example: `amazon.de`.
`order.purchased_at`	string \| null (date)	Yes
`tracking_numbers`	array of string	Yes	Inbound parcel tracking codes known so far, sorted; new ones arrive with `inbound.updated`. Codes are normalised: the text is split at whitespace (also Unicode spaces) and at `, ; : \| / \`; every character other than A–Z, a–z, 0–9 is removed from each part (`DE-LPLV-0GLI` → `DELPLV0GLI`); parts without a digit (carrier labels such as `DHL`) are dropped; duplicates are compared case-insensitively, the first spelling is kept.
`lines`	array of InboundLine	Yes	One line per purchase.
`created_at`	string (date-time)	Yes

InboundLine

Field	Type	Required	Description
`id`	string	Yes	Example: `inl_99`.
`purchase_id`	string	Yes	Example: `pur_4711`.
`item`	Item	Yes
`quantity_expected`	integer	Yes	Units announced.
`quantity_received`	integer	Yes	Absolute count you reported.
`quantity_damaged`	integer	Yes	Damaged units you reported.
`status`	string	Yes	One of: `open`, `received`, `cancelled`.

Item

Field	Type	Required	Description
`id`	string \| null	Yes	Example: `itm_17`.
`sku`	string	Yes	The seller's Amazon SKU; one item per SKU and connection.
`fnsku`	string \| null	Yes	Amazon label barcode; may be null at announcement and follow with `inbound.updated` (changes contains `fnsku`).
`asin`	string \| null	Yes
`ean`	string \| null	Yes
`title`	string \| null	Yes
`image_url`	string \| null	Yes

ItemView

Field	Type	Required	Description
`id`	string \| null	Yes	Example: `itm_17`.
`sku`	string	Yes	The seller's Amazon SKU; one item per SKU and connection.
`fnsku`	string \| null	Yes	Amazon label barcode; may be null at announcement and follow with `inbound.updated` (changes contains `fnsku`).
`asin`	string \| null	Yes
`ean`	string \| null	Yes
`title`	string \| null	Yes
`image_url`	string \| null	Yes
`connection_id`	string	Yes	Example: `pcn_812`.
`created_at`	string (date-time)	Yes
`updated_at`	string (date-time)	Yes

Trace

Every id known for one inbound line, from purchase to FBA shipment.

Field	Type	Required	Description
`purchase_id`	string	Yes
`inbound_id`	string \| null	Yes
`inbound_line_id`	string \| null	Yes
`item_id`	string \| null	Yes
`sku`	string \| null	Yes
`fnsku`	string \| null	Yes
`asin`	string \| null	Yes
`order_number`	string \| null	Yes
`batch_id`	string \| null	Yes
`outbound_ids`	array of string	Yes	`out_…` of non-cancelled outbounds that carry units of this purchase.
`amazon_shipment_ids`	array of string	Yes

ReceiptRequest

Field	Type	Required	Description
`event_id`	string	No	Idempotency key; or send the Idempotency-Key header. Max length 200.
`occurred_at`	string (date-time)	No
`status`	string	Yes	One of: `receiving`, `received`.
`lines`	array of object	No	May be empty only with `status: received`. Each line may be addressed once per request.
`lines[].line_id`	string	No	`inl_…`; takes precedence over `sku`.
`lines[].sku`	string	No
`lines[].quantity_received`	integer	Yes	Absolute count. Minimum 0.
`lines[].quantity_damaged`	integer	No	Stored and returned; omitted keeps the previous value. Minimum 0.

ReceiptResponse

Field	Type	Required	Description
`connection_id`	string	Yes	Example: `pcn_812`.
`inbound`	Inbound	Yes
`traces`	array of Trace	Yes
`event_id`	string	Yes
`duplicate`	boolean	Yes
`lines`	array of object	Yes	Every line the receipt addressed or closed.
`lines[].line_id`	string	Yes
`lines[].result`	string	Yes	`stale`: a receipt at or after `occurred_at` was already applied to the line. One of: `applied`, `unchanged`, `stale`.

OutboundRequest

Field	Type	Required	Description
`event_id`	string	No	Max length 200.
`external_id`	string	Yes	Your outbound id. Min length 1. Max length 200.
`occurred_at`	string (date-time)	No
`status`	string	Yes	One of: `created`, `shipped`, `cancelled`.
`destination`	object	Yes
`destination.type`	string	Yes	Required; missing or empty is `400 invalid_request`. One of: `fba`, `fbm`, `other`.
`destination.amazon_shipment_id`	string	No	Max length 64. Example: `FBA15XYZ`.
`destination.marketplace`	string	No	Max length 8. Example: `DE`.
`tracking_numbers`	array of string	No
`lines`	array of object	No
`lines[].line_id`	string	No
`lines[].purchase_id`	string	No
`lines[].item_id`	string	No
`lines[].sku`	string	No
`lines[].quantity`	integer	Yes	Minimum 1.

OutboundResponse

Field	Type	Required	Description
`event_id`	string	Yes
`duplicate`	boolean	Yes
`stale`	boolean	Yes	A newer event was already applied; nothing changed.
`connection_id`	string	Yes	Example: `pcn_812`.
`outbound`	Outbound	Yes
`unresolved`	array of object	Yes
`unresolved[].index`	integer	Yes	Position in the request's `lines`.
`unresolved[].line_id`	string \| null	Yes
`unresolved[].purchase_id`	string \| null	Yes
`unresolved[].item_id`	string \| null	Yes
`unresolved[].sku`	string \| null	Yes
`unresolved[].quantity`	integer	Yes	The part that could not be matched.
`unresolved[].reason`	string	Yes	One of: `line_not_found`, `purchase_not_found`, `item_not_found`, `sku_not_found`, `insufficient_received_quantity`, `invalid_reference`.

Destination

Field	Type	Required	Description
`type`	string	Yes	One of: `fba`, `fbm`, `other`.
`amazon_shipment_id`	string \| null	Yes	Max length 64. Example: `FBA15XYZ`.
`marketplace`	string \| null	Yes	Max length 8. Example: `DE`.

Outbound

Field	Type	Required	Description
`id`	string	Yes	Example: `out_55`.
`external_id`	string	Yes
`status`	string	Yes	One of: `created`, `shipped`, `cancelled`.
`destination`	Destination	Yes
`tracking_numbers`	array of string	Yes
`shipped_at`	string \| null (date-time)	Yes	Set the first time the status is `shipped`; kept afterwards.
`lines`	array of object	Yes
`lines[].purchase_id`	string	Yes
`lines[].inbound_line_id`	string \| null	Yes
`lines[].quantity`	integer	Yes
`lines[].resolved_by`	string	Yes	One of: `line_id`, `purchase_id`, `item_id`, `sku_fifo`.

Overview#

Identifiers#

Authentication#

Rate limit#

Idempotency#

Ordering#

Webhook events#

Errors#

Inbounds#

List inbounds announced to the connection#

Parameters#

Responses#

Get one inbound with its lines and traces#

Parameters#

Responses#

Set your own reference on an inbound#

Parameters#

Request body#

Responses#

Report goods received for an announced inbound#

Parameters#

Request body#

Responses#

Outbounds#

Create, update, ship or cancel an outbound#

Parameters#

Request body#

Responses#

Get one outbound with its purchase allocation#

Parameters#

Responses#

Items#

List the connection's articles (one per SKU)#

Parameters#

Responses#

Events#

Replay the connection's webhook events#

Parameters#

Responses#

Connections#

The key's own connection#

Parameters#

Responses#

Webhooks#

inbound.announced#

Headers#

Request body#

Responses#

inbound.updated#

Headers#

Request body#

Responses#

inbound.cancelled#

Headers#

Request body#

Responses#

inbound.restored#

Headers#

Request body#

Responses#

inbound.received#

Headers#

Request body#

Responses#

outbound.recorded#

Headers#

Request body#

Responses#

ping#

Headers#

Request body#

Responses#

Schemas#

Error#

Envelope#

InboundEventEnvelope#

OutboundEventEnvelope#

Connection#

PingEventEnvelope#

OutboundEventData#

Overview

Identifiers

Authentication

Rate limit

Idempotency

Ordering

Webhook events

Errors

Inbounds

List inbounds announced to the connection

Parameters

Responses

Get one inbound with its lines and traces

Parameters

Responses

Set your own reference on an inbound

Parameters

Request body

Responses

Report goods received for an announced inbound

Parameters

Request body

Responses

Outbounds

Create, update, ship or cancel an outbound

Parameters

Request body

Responses

Get one outbound with its purchase allocation

Parameters

Responses

Items

List the connection's articles (one per SKU)

Parameters

Responses

Events

Replay the connection's webhook events

Parameters

Responses

Connections

The key's own connection

Parameters

Responses

Webhooks

inbound.announced

Headers

Request body

Responses

inbound.updated

Headers

Request body

Responses

inbound.cancelled

Headers

Request body

Responses

inbound.restored

Headers

Request body

Responses

inbound.received

Headers

Request body

Responses

outbound.recorded

Headers

Request body

Responses

ping

Headers

Request body

Responses

Schemas

Error

Envelope

InboundEventEnvelope

OutboundEventEnvelope

Connection

PingEventEnvelope

OutboundEventData