> This page is for version v2024-01-31. > For other versions, use one of these documentation indexes: > - v2024-05-25 (default): https://docs.monite.com/v-2024-05-25/llms.txt > - v2024-01-31: https://docs.monite.com/v2024-01-31/llms.txt > - v2023-09-01: https://docs.monite.com/v2023-09-01/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.monite.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.monite.com/_mcp/server. # Delivery notes ## Overview A **delivery note** (also known as a delivery slip, dispatch note, shipping note, goods delivery note, and similar names) is a document that accompanies the delivery of goods from a seller to a customer. It contains the list of items and their quantities shipped within a delivery. Delivery notes are often used in retail, e-commerce, construction, logistics, and supply chains to help ensure the correct items get delivered to customers and to provide customers with an overview of the shipment contents. Upon receiving the delivery, the customer can cross-check the contents of the shipment with the delivery note to make sure they match and nothing is missing. Unlike invoices, delivery notes do not contain financial information such as product prices and tax rates - only the product names and quantities being delivered. ![A delivery note](/_fern-img/17e6a5977264e57d2bbe67d81383a17cf927d71a4af76cbd6b6f9233fd8a30b8.webp) ## Roles and permissions \[#permissions] To use the `/delivery_notes*` endpoints with an [entity user token](../entities/users#get-entity-user-token), this entity user must have a [role](../entities/users#create-role) with the `delivery_note` permission. If using a [partner-level token](../get-started/credentials#generate-partner-token), no special permissions are needed. ## Delivery note statuses \[#statuses] Delivery notes move through a series of statuses as they are created and processed. The status determines the actions can be performed on a delivery note. ```mermaid stateDiagram classDef block fill: white, text-transform: lowercase %% classDef start color: blue, stroke: blue classDef start stroke: black classDef success color: green, stroke: green classDef failure color: red, stroke: red direction LR [*] --> created created --> delivered delivered --> deleted created --> deleted created --> canceled canceled --> deleted class created start class delivered success class canceled, deleted failure class created, delivered, canceled, deleted block ``` > **Note** > > Status updates of a delivery note have no effect on the status of the associated invoice or quote. ### `created` This is the initial status of all delivery notes. Documents in this status are considered finalized (ready to be sent to the counterparts) but can still be edited if needed. Unlike invoices, delivery notes do not have the `issued` status. The `created` status of delivery notes is an analog of both `draft` and `issued` statuses of invoices. ### `delivered` Use this status to indicate that the delivery note has been handed over to the counterpart. Delivered documents cannot be edited, but can be deleted. ### `canceled` If the delivery is canceled, you can mark the delivery note as canceled. Canceled delivery notes cannot be edited, but can be deleted. ### `deleted` Delivery notes in any status can be deleted. This cannot be undone. Deleted documents are not accessible via the API. ## Create a delivery note \[#create] There are two ways to create delivery notes: * [create a standalone delivery note from scratch](#create-standalone) * [create from an existing invoice or quote](#from-invoice-or-quote) > **Note** > > There is no way to link an existing delivery note to an invoice or quote. > Only newly created delivery notes can be associated with an invoice or quote. ### Create a standalone delivery note \[#create-standalone] Before creating a delivery note, you need to: * Create the [counterpart](../common/counterparts/index) (customer). * (Optional) Set up the [product catalog](../accounts-receivable/products). To create a delivery note, call [`POST /delivery_notes`](/v2024-01-31/api/delivery-notes/post-delivery-notes) with a request body countaining the counterpart details and at least one line item. Line items can either reference products from the catalog by `product_id` or specify the product `name` and other details inline. ```sh curl -X POST 'https://api.sandbox.monite.com/v1/delivery_notes' \ -H 'X-Monite-Version: 2024-01-31' \ -H 'X-Monite-Entity-Id: ENTITY_ID' \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "counterpart_id": "18a45457-377e-4b7c-b9a1-7b2e7f264d46", "counterpart_address_id": "9a0282e1-bae7-49c9-a6f3-152dbe6fe6b8", "delivery_date": "2025-03-10", "delivery_number": "INV-042", "line_items": [ { "product": { "name": "LG WH1000XM Monitor" }, "quantity": 10 }, { "product_id": "e0c21d00-6556-4536-8390-830c4d3cf4ca", "quantity": 5 } ], "display_signature_placeholder": true }' ``` Other relevant (but optional) fields in delivery notes are: * `delivery_date` - the date displayed on the PDF. * `delivery_number` * `display_signature_placeholder` - if `true`, the PDF delivery note will display a signature block so that the counterpart representative can sign the printed document. Default is `false`. The document number (`document_id`) of the delivery note is generated automatically based on the entity's [document number customization](../advanced/document-number-customization) options. In the [non-compliant mode](./regulatory-compliance/invoice-compliance), you can set the `document_id` manually. ### Create a delivery note from an invoice or quote \[#from-invoice-or-quote] To create a delivery note based on an existing invoice or quote, call [`POST /delivery_notes`](/v2024-01-31/api/delivery-notes/post-delivery-notes) and specify the ID of the related invoice or quote in the `based_on` field in the request body: ```sh {7} curl -X POST 'https://api.sandbox.monite.com/v1/delivery_notes' \ -H 'X-Monite-Version: 2024-01-31' \ -H 'X-Monite-Entity-Id: ENTITY_ID' \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "based_on": "9525e2b7-8876-48b8-aa79-5256cb811ade" }' ``` The created delivery note contains a copy of the invoice or quote data - except unit prices, tax rates, and other values not used in delivery notes. The ID and document number of the original invoice or quote are stored in the `based_on` and `based_on_document_id` fields of the delivery note, respectively. The document number (`document_id`) of the delivery note is generated automatically based on the entity's [document number customization](../advanced/document-number-customization) options. In the [non-compliant mode](./regulatory-compliance/invoice-compliance), you can update the `document_id` manually. The next step is to edit the created delivery note to add the `delivery_date`, `delivery_number`, and other relevant details. You can also adjust any other information - line items, counterpart address, memo, and other data - as necessary. ```sh curl -X PATCH 'https://api.sandbox.monite.com/v1/delivery_notes/19e0a...9cc' \ -H 'X-Monite-Version: 2024-01-31' \ -H 'X-Monite-Entity-Id: ENTITY_ID' \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "delivery_date": "2025-03-10", "delivery_number": "INT-042", "display_signature_placeholder": true }' ``` ## Download the PDF \[#pdf] Monite automatically generates the PDF version of delivery notes in the counterpart language and the entity language, and returns links to these files in the `file_url` and `original_file_url` fields of delivery note responses: ```json { "id": "19e0a1d5-9255-4b32-90c0-c398f7f1f9cc", ... // Counterpart's version of a PDF delivery note "file_language": "nl", "file_url": "https://.s3.amazonaws.com//.pdf", ... // Entity's version of a PDF delivery note "original_file_language": "en", "original_file_url": "https://.s3.amazonaws.com//.pdf", ... } ``` > **Info** > > If `file_url` or `original_file_url` is `null`, repeat the request to [GET /delivery\_notes/\{delivery\_note\_id}](/v2024-01-31/api/delivery-notes/get-delivery-notes-id) after some time. The PDF file is updated automatically if the delivery note is updated (for example, if new line items are added or the counterpart address is changed). Entity users can download the PDF document and print it to be shipped along with the delivered goods. ![A delivery note](/_fern-img/17e6a5977264e57d2bbe67d81383a17cf927d71a4af76cbd6b6f9233fd8a30b8.webp) ### PDF customization \[#customize-pdf] PDF delivery notes are branded with the [entity logo](../entities/index#logo) (if available). If the `display_signature_placeholder` field of a delivery note is true, the PDF file includes a block where the counterpart can add their signature in the printed document upon receiving the delivery. Monite also provides several built-in PDF templates for accounts receivable documents. Entities can [change their default template](../advanced/pdf-templates#default) at any time. For more information, see [PDF templates](../advanced/pdf-templates). ## Update a delivery note \[#update] While a delivery note is in the `created` status, you can edit it - change the counterpart, delivery adddress, stated delivery date, and other details. To do this, call [`PATCH /delivery_notes/{delivery_note_id}`](/v2024-01-31/api/delivery-notes/patch-delivery-notes-id) with a request body containing the fields and values you want to update. ```sh curl -X PATCH 'https://api.sandbox.monite.com/v1/delivery_notes/24d9a...589' \ -H 'X-Monite-Version: 2024-01-31' \ -H 'X-Monite-Entity-Id: ENTITY_ID' \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "delivery_date": "2025-03-17" }' ``` > **Updating line items** > > To add, delete, update, or reorder the line items of a delivery note, provide the `line_items` array containing the final list of line items. > In other words, the `line_items` array in PATCH requests *replaces* the previous line items. > > For example, consider a delivery note with 3 line items. > To remove the second item, send the `line_items` array containing just the remaining line items. ## Mark a delivery note as delivered \[#mark-as-delivered] After a delivery note has been handed over to the counterpart, you can change its status to `delivered`. To do this, call [`POST /delivery_notes/{delivery_note_id}/mark_as_delivered`](/v2024-01-31/api/delivery-notes/post-delivery-notes-id-mark-as-delivered): ```sh curl -X POST 'https://api.sandbox.monite.com/v1/delivery_notes/24d9a...589/mark_as_delivered' \ -H 'X-Monite-Version: 2024-01-31' \ -H 'X-Monite-Entity-Id: ENTITY_ID' \ -H 'Authorization: Bearer ACCESS_TOKEN' ``` > **Note** > > This only changes the `status` of the delivery note, but not its `delivery_date`. > The delivery date is defined by the user when the delivery note is created or updated. ## Cancel a delivery note \[#cancel] If a delivery has been canceled, you can mark the corresponding delivery note as canceled. To do this, call [POST /delivery\_notes/\{delivery\_note\_id}/cancel](/v2024-01-31/api/delivery-notes/post-delivery-notes-id-cancel): ```sh curl -X POST 'https://api.sandbox.monite.com/v1/delivery_notes/24d9a...589/cancel' \ -H 'X-Monite-Version: 2024-01-31' \ -H 'X-Monite-Entity-Id: ENTITY_ID' \ -H 'Authorization: Bearer ACCESS_TOKEN' ``` Only delivery notes in the `created` status can be canceled. Canceling a delivery note does not affect the status of the associated invoice or quote. ## Find and filter delivery notes \[#find-filter] The [`GET /delivery_notes`](/v2024-01-31/api/delivery-notes/get-delivery-notes) endpoint supports a variety of query parameters to refine the search results. Examples: * Bulk fetch multiple delivery notes by their IDs (spaces added for readability): ``` GET /delivery_notes? id__in=ID_1 & id__in=ID_2 & id__in=ID_3 ``` * Find a delivery note created from a specific invoice or quote: ``` GET /delivery_notes?based_on=INVOICE_OR_QUOTE_ID ``` * Find a delivery note by the document number of the associated invoice or quote (exact match, case-sensitive): ``` GET /delivery_notes?based_on_document_id=INV-00042 ``` Alternatively, use the `based_on_document_id__icontains` parameter for a partial document number match (case-insensitive). ## Delete a delivery note \[#delete] Delivery notes in any status can be deleted. To do this, call [DELETE /delivery\_notes/\{delivery\_note\_id}](/v2024-01-31/api/delivery-notes/delete-delivery-notes-id): ```sh curl -X DELETE 'https://api.sandbox.monite.com/v1/delivery_notes/24d9a...589' \ -H 'X-Monite-Version: 2024-01-31' \ -H 'X-Monite-Entity-Id: ENTITY_ID' \ -H 'Authorization: Bearer ACCESS_TOKEN' ``` > **Error** > > Deleting a document cannot be undone.