> ## Documentation Index
> Fetch the complete documentation index at: https://exsited.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Item fulfillments

> Record items sent against a sale invoice's lines, then list, read, update and delete fulfillments and manage their notes.

An item fulfillment records items sent against the lines of a sale invoice. These endpoints create, list, read, update and delete fulfillments, and add, list, read and delete their notes. This area has 9 endpoints, each available in all seven SDKs.

> [!WARNING]
>
> **A fulfillment cannot be deleted once any of its stock has been sent.** The delete is refused with `400` `stock_committed`.

## At a glance

| Endpoint | Method | Path | What it does |
| - | - | - | - |
| [List item fulfillments](https://exsited.mintlify.site/api-reference/item-fulfillments/list-item-fulfillments.md) | GET | `/item_fulfillments` | Returns a page of item fulfillments. |
| [Create an item fulfillment](https://exsited.mintlify.site/api-reference/item-fulfillments/create-an-item-fulfillment.md) | POST | `/item_fulfillments` | Records items sent against a sale invoice's lines and returns the fulfillment. |
| [Retrieve an item fulfillment](https://exsited.mintlify.site/api-reference/item-fulfillments/retrieve-an-item-fulfillment.md) | GET | `/item_fulfillments/{fulfillment_id}` | Returns one item fulfillment by its `id`. |
| [Update an item fulfillment](https://exsited.mintlify.site/api-reference/item-fulfillments/update-an-item-fulfillment.md) | PATCH | `/item_fulfillments/{fulfillment_id}` | Changes an item fulfillment, such as its tracking number, and returns a short record. |
| [Create an item fulfillment note](https://exsited.mintlify.site/api-reference/item-fulfillments/create-an-item-fulfillment-note.md) | POST | `/item_fulfillments/{fulfillment_id}/notes` | Adds a note to a fulfillment, with optional files, and returns the note's id. |
| [Delete an item fulfillment](https://exsited.mintlify.site/api-reference/item-fulfillments/delete-an-item-fulfillment.md) | DELETE | `/item_fulfillments/{fulfillment_id}` | Deletes an item fulfillment. A successful call returns `204` with no body. |
| [Delete an item fulfillment note](https://exsited.mintlify.site/api-reference/item-fulfillments/delete-an-item-fulfillment-note.md) | DELETE | `/item_fulfillments/{fulfillment_id}/notes/{note_id}` | Deletes a note stored on the fulfillment itself. A successful call returns `204` with no body. |
| [List an item fulfillment's notes](https://exsited.mintlify.site/api-reference/item-fulfillments/list-an-item-fulfillments-notes.md) | GET | `/item_fulfillments/{fulfillment_id}/notes` | Returns a page of the notes on a fulfillment's sale invoice. |
| [Retrieve an item fulfillment note](https://exsited.mintlify.site/api-reference/item-fulfillments/retrieve-an-item-fulfillment-note.md) | GET | `/item_fulfillments/{fulfillment_id}/notes/{note_id}` | Returns one fulfillment note, under `item_fulfillment.note`. |

## Before you call

Register your API credentials once when your app starts, as shown in
[Authentication](https://exsited.mintlify.site/authentication.md). Every SDK sample on these pages then gets its client in one line.
With cURL, send the access token in an `Authorization` header: `Authorization: Bearer $ACCESS_TOKEN`.

## Things to know

* **Fulfillment creates and updates are wrapped in `item_fulfillment`.** A create names the sale invoice in `invoice_id` and lists `fulfillments`, each with an `invoice_line` id and a `fulfillment_quantity`.
* **Fulfillment ids start with `ifm_`, and note ids with `note_`.** Pass them in the paths as they are.
* **Notes are stored on the fulfillment's sale invoice.** The notes listing returns the invoice's notes, and a single note read comes back under `item_fulfillment.note`.
* **Deleting a note looks on the fulfillment itself.** A note added through the create note endpoint is stored on the invoice, so that delete does not find it.
* **A new fulfillment comes back with `fulfillment_status` `shipped`.** Each update raises its `version`.
* **The listing pages by cursor.** Pass `limit`, then send the `next_cursor` from `pagination` as `cursor` until `has_more` is `false`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.