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.

Roles and permissions

To use the /delivery_notes* endpoints with an entity user token, this entity user must have a role with the delivery_note permission.

If using a partner-level token, no special permissions are needed.

Delivery note 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.

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

There are two ways to create delivery notes:

• create a standalone delivery note from scratch
• create from an existing invoice or quote

Create a standalone delivery note

Before creating a delivery note, you need to:

• Create the counterpart (customer).
• (Optional) Set up the product catalog.

To create a delivery note, call 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.

1
curl -X POST 'https://api.sandbox.monite.com/v1/delivery_notes' \
2
     -H 'X-Monite-Version: 2024-05-25' \
3
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4
     -H 'Authorization: Bearer ACCESS_TOKEN' \
5
     -H 'Content-Type: application/json' \
6
     -d '{
7
       "counterpart_id": "18a45457-377e-4b7c-b9a1-7b2e7f264d46",
8
       "counterpart_address_id": "9a0282e1-bae7-49c9-a6f3-152dbe6fe6b8",
9
       "delivery_date": "2025-03-10",
10
       "delivery_number": "INV-042",
11
       "line_items": [
12
         {
13
           "product": {
14
             "name": "LG WH1000XM Monitor"
15
           },
16
           "quantity": 10
17
         },
18
         {
19
           "product_id": "e0c21d00-6556-4536-8390-830c4d3cf4ca",
20
           "quantity": 5
21
         }
22
       ],
23
       "display_signature_placeholder": true
24
     }'

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 options. In the non-compliant mode, you can set the document_id manually.

Create a delivery note from an invoice or quote

To create a delivery note based on an existing invoice or quote, call POST /delivery_notes and specify the ID of the related invoice or quote in the based_on field in the request body:

1
curl -X POST 'https://api.sandbox.monite.com/v1/delivery_notes' \
2
     -H 'X-Monite-Version: 2024-05-25' \
3
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4
     -H 'Authorization: Bearer ACCESS_TOKEN' \
5
     -H 'Content-Type: application/json' \
6
     -d '{
7
       "based_on": "9525e2b7-8876-48b8-aa79-5256cb811ade"
8
     }'

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 options. In the non-compliant mode, 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.

1
curl -X PATCH 'https://api.sandbox.monite.com/v1/delivery_notes/19e0a...9cc' \
2
     -H 'X-Monite-Version: 2024-05-25' \
3
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4
     -H 'Authorization: Bearer ACCESS_TOKEN' \
5
     -H 'Content-Type: application/json' \
6
     -d '{
7
       "delivery_date": "2025-03-10",
8
       "delivery_number": "INT-042",
9
       "display_signature_placeholder": true
10
     }'

Download the 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:

1
{
2
  "id": "19e0a1d5-9255-4b32-90c0-c398f7f1f9cc",
3
  ...
4
  // Counterpart's version of a PDF delivery note
5
  "file_language": "nl",
6
  "file_url": "https://<bucketname>.s3.amazonaws.com/<random_UUID_1>/<random_UUID_2>.pdf",
7
  ...
8
  // Entity's version of a PDF delivery note
9
  "original_file_language": "en",
10
  "original_file_url": "https://<bucketname>.s3.amazonaws.com/<random_UUID_3>/<random_UUID_4>.pdf",
11
  ...
12
}

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.

PDF customization

PDF delivery notes are branded with the entity 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 at any time. For more information, see PDF templates.

Update a delivery note

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} with a request body containing the fields and values you want to update.

1
curl -X PATCH 'https://api.sandbox.monite.com/v1/delivery_notes/24d9a...589' \
2
     -H 'X-Monite-Version: 2024-05-25' \
3
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4
     -H 'Authorization: Bearer ACCESS_TOKEN' \
5
     -H 'Content-Type: application/json' \
6
     -d '{
7
       "delivery_date": "2025-03-17"
8
     }'

Mark a delivery note 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:

1
curl -X POST 'https://api.sandbox.monite.com/v1/delivery_notes/24d9a...589/mark_as_delivered' \
2
     -H 'X-Monite-Version: 2024-05-25' \
3
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4
     -H 'Authorization: Bearer ACCESS_TOKEN'

Cancel a delivery note

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:

1
curl -X POST 'https://api.sandbox.monite.com/v1/delivery_notes/24d9a...589/cancel' \
2
     -H 'X-Monite-Version: 2024-05-25' \
3
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4
     -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

The 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

Delivery notes in any status can be deleted. To do this, call DELETE /delivery_notes/{delivery_note_id}:

1
curl -X DELETE 'https://api.sandbox.monite.com/v1/delivery_notes/24d9a...589' \
2
     -H 'X-Monite-Version: 2024-05-25' \
3
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4
     -H 'Authorization: Bearer ACCESS_TOKEN'