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.

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	GET	/item_fulfillments	Returns a page of item fulfillments.
Create an item fulfillment	POST	/item_fulfillments	Records items sent against a sale invoice’s lines and returns the fulfillment.
Retrieve an item fulfillment	GET	/item_fulfillments/{fulfillment_id}	Returns one item fulfillment by its id.
Update an item fulfillment	PATCH	/item_fulfillments/{fulfillment_id}	Changes an item fulfillment, such as its tracking number, and returns a short record.
Create an item fulfillment note	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	DELETE	/item_fulfillments/{fulfillment_id}	Deletes an item fulfillment. A successful call returns 204 with no body.
Delete an item fulfillment note	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	GET	/item_fulfillments/{fulfillment_id}/notes	Returns a page of the notes on a fulfillment’s sale invoice.
Retrieve an item fulfillment note	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. 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.