SalesDeliveryNote

Quick Links

Accounts Accounting Entries Products Customers Sales quotes Sales invoices Suppliers Purchase invoices

HTTP Operation Type Object DTO Why-DTOs?
Mutation Why 200? createSalesDeliveryNote SalesDeliveryNoteCreateGLDtoInput
Mutation Why 200? updateSalesDeliveryNote How to update? SalesDeliveryNoteUpdateGLDtoInput
Mutation Why 200? deleteSalesDeliveryNote SalesDeliveryNoteDeleteGLDtoInput
Query salesDeliveryNotes filtered by id Why?  
Query salesDeliveryNotes  
Query salesDeliveryNoteLines  
Quick Tips

It is possible to query either salesDeliveryNote or directly from salesDeliveryNoteLines.

  • Querying salesDeliveryNotes allows you to retrieve entire documents with all their associated line items.
    This is useful when you need the complete context of a document, including all details of the related lines.
  • Querying salesDeliveryNoteLines directly is beneficial when you want to filter or aggregate specific line item data across multiple documents, such as analyzing product sales, quantities, or prices.

More info API resources overview / 📝some Filter vs. Direct Line Filtering

Description

Both known as Sales delivery notes in the API context and in the product interface.
This resource is the backbone for organizing and managing the shipping and handling details associated with sales orders.
With the flexibility to incorporate both standard and customized fields, Sales Delivery Notes offer granular visibility into the logistical aspects of the order-to-cash process.
This is critical for ensuring timely and accurate deliveries to customers.

img

To see examples of mutations that include the adding of DeliveryNote :
download the Postman collection: Quick start / 5. Test your first query in Postman.

To change the Status of a salesDeliveryNote, refer to the global sales documents page, which details the available options depending on the document type. API resources overview / 📝 Update Document Status

graphQL Mutation
mutation ($values: SalesDeliveryNoteCreateGLDtoInput!) {  
  createSalesDeliveryNote(input: $values) {
    id
    operationalNumber
  }
}
graphQL Variables
{
  "values": {
    "customerId": "{customerId}",
    "documentDate": "2023-12-05",
    "lines": [
      {
        "productId": "{productId1}",
        "totalQuantity": 50,
        "unitPrice": 11,
        "firstDiscount": 5
      },
      {
        "productId": "{productId2}",
        "totalQuantity": 1,
        "unitPrice": 140
      }
    ]
  }
}
Example of Response
{
    "data": {
        "createSalesDeliveryNote": {
            "id": "e451aff7-074f-4e72-a6fb-4ea25e9d9c64",
            "operationalNumber": "0027"
        }
    }
}
Key Value
Authorization Bearer Current access Token How to find?
X-TenantId Current tenant id Why deprecated ?
X-OrganizationId Current organization Id How to find?
x-api-key Primary or secondary subscription key of your app How to find?

salesDeliveryNotes

Common to all documents

Fields Type Description Length
id UUID Id  
creationDate DateTime Creation Date  
modificationDate DateTime Modification Date  
sourceType
  • SALES
  • PUBLIC_API
 indicates the origin of the salesDeliveryNote (SALES=Manual entry)  
       
General Infos      
customer Customer Fields of Customer  
customerId UUID ID of the Customer entity. No mandatory for Quote  
documentDate DateTime Document Date  
operationalNumber String Document Number 50
operationalNumberPresetText OperationalNumberPresetText Fields of OperationalNumberPresetText  
operationalNumberPresetTextId UUID ID of the operational number preset text  
status String
  • Pending
  • Closed
 15
socialName String Social Name 50
contactName String Contact Name 50
contactPhone String Contact Phone 15
contactEmail String Contact Email 50
contactJobAreaId UUID Id of the Contact Job Area  
countryAcronym String Country Acronym 2
       
DeliveryNote Lines      
lines[] Array Document Lines  
       
Totals and discount      
totalNet Decimal Amount after discounts, before taxes.  
totalGross Decimal Total amount before discounts and taxes.  
totalDiscount Decimal Sum of all discounts applied.  
totalCustomerDiscount Decimal Discount specific to the customer.  
totalLiquid Decimal Final amount due, including taxes.  
totalVat Decimal Total Value Added Tax (VAT) applied.  
totalVatBase Decimal Total taxable base before VAT.  
totalFeeSurcharge Decimal Total equivalence surcharge applied, based on VAT.  
totalVatFee Decimal VAT amount used as the base for the surcharge.  
discount Decimal Specific discount applied.  
       
totalLiquidNoWithholding Decimal Total amount excluding withholding  
totalWithholding Decimal Total withholding amount  
       
Notes      
comments String Notes for the customer/recipient of the document (plain text, personalised introduction) 1000
remarks String Internal notes for the document (plain text, not visible to the customer) 1000
externalReference String External customer reference provided to facilitate communication and tracking 20
       
Customer Information      
documentId String Identification Number 20
documentLanguage
  • ENGLISH
  • FRENCH
  • GERMAN
  • SPANISH
 Language used in sales Document Pdf 20
documentType DocumentType Fields of DocumentType used for identification purposes  
documentTypeId UUID Identifier of the document type  
vatNumber String Vat Number 20
invoiceEmail String Invoice Email 50
hasEquivalenceSurcharge Boolean Subject to the equivalence surcharge regime  
mainAddress ObjectType Main Address  
deliveryAddress ObjectType Delivery Address  
salesDiscountGroup SalesDiscountGroup Fields of SalesDiscount  
salesDiscountGroupId UUID Sales Discount ID  
salesTariff SalesTariff Fields of SalesTariff  
salesTariffId UUID Sales tariff ID  

Specific to sales delivery note documents

Fields Type Description
updateDocumentStatus
  • CLOSE
 Allows changing the status of the quote.
Info
  • customerId: A unique identifier (UUID) for the Customer entity.
  • operationalNumberPresetTextId: Applies a prefix to the document number (operationalNumber) once you choose a value from operationalNumberPresetText.
  • totalGross: Represents the total amount before any discounts or taxes are applied. It includes the sum of all item prices at their full value.
  • totalDiscount: The aggregated discount amount applied to the document, including all types of discounts that reduce the gross total.
  • totalNet: The total amount after applying discounts but before adding taxes. It represents the taxable base amount.
  • discount: Represents a specific discount amount applied within the document. This can be a percentage or a fixed amount reduction.
  • totalCustomerDiscount: A discount specifically applied based on customer-specific conditions, such as loyalty discounts or promotional offers tailored to the customer.
  • totalLiquid: The total payable amount, which includes taxes and any additional fees. This represents the final amount due.
  • totalVat: The total Value Added Tax (VAT) calculated on the taxable base. This amount represents the sum of all VAT applied across items in the document.
  • totalVatBase: The total taxable base amount before VAT is applied. This is the sum of all net amounts subject to VAT.
  • totalLiquidNoWithholding:
  • totalWithholding:
    • Unused (Spain only).

    The following fields are specific to the Spanish legislation (IRPF):

    • totalLiquidNoWithholding:
      Total amount excluding withholding tax.
      This represents the taxable base before applying IRPF withholding.
    • totalWithholding:
      Total withholding amount (IRPF) calculated at document level.
    • Unused (Spain only).
  • hasEquivalenceSurcharge:
  • totalFeeSurcharge:
  • totalVatFee:
    • unused for the French market

    Indicates whether a customer is subject to the equivalence surcharge regime.

    The equivalence surcharge (totalFeeSurcharge), as applied in Spain, is a form of simplified VAT for retail traders who cannot recover VAT.
    The rates of the equivalence surcharge vary according to the VAT rate applicable to the products, with surcharge rates of 5.2% for products with a general VAT of 21%, 1.4% for products with a reduced VAT of 10%, and other rates for different products or categories. The equivalence surcharge is calculated on amount of general VAT (totalVatFee).

    • unused for the German market
  • socialName :

    mandatory for the French market

    no mandatory for the Spanish market

    no mandatory for the Germany market

  • externalReference: Allows entering an external reference provided by the customer to facilitate communication and tracking.

  • vatNumber : An EU VAT Number is a unique identifier for tax purposes within the European Union, used primarily for cross-border transactions. It starts with a two-letter country code followed by a series of numbers and sometimes letters, varying by country.

    mandatory for VIES customers

    no mandatory for Spanish market

    no mandatory for Germany market

  • invoiceEmail:
  • documentId : Identification number, value formats may differ depending on legislationCode.
    • For a French , you can fill any SIREN of 9 characters or any SIRET of 14 characters.
      The value is not mandatory.
    • For a German , you may enter either a Steuer-IdNr with exactly 11 characters or another value ranging from 11 to 14 characters.
      The value is not mandatory.
    • For a Spanish , you need to fill a valid NIF/DNI/NIE number.
      The value is mandatory.
  • documentLanguage: Applies to section titles and column headers in sales documents PDFs.
  • documentTypeId: This functionality determines the corresponding document type based on the document number provided.
    This determination is vital for verifying the real existence of a customer, thereby ensuring their authenticity and compliance with regulations.

Specific to sales delivery documents

  • Status:
    • Pending: The delivery note is in progress and can be modified.
    • Closed: The delivery can no longer be modified; it has either been transferred to an invoice or it has been closed.

salesDeliveryNotes/lines or directly from salesDeliveryNoteLines

If the query targets salesDeliveryNotes, then use lines to get the details of the lines.
If the query targets salesDeliveryNoteLines, access the following fields directly, including the option to retrieve information on the parent salesDeliveryNote.

Common to all documents

Fields Type Description Length
id UUID Id  
creationDate DateTime Date of creation  
modificationDate DateTime Last modification date  
       
salesDeliveryNotes Parent Information      
salesDeliveryNote SalesDeliveryNote Fields of the parent salesDeliveryNotes 36
salesDeliveryNoteId UUID salesDeliveryNote ID  
       
Product Information      
product Product Fields of Product 36
productId UUID Product ID  
productCode String Product code 15
productName String Product name 2500
order Int Classification of lines from 1 to n  
       
unitOfMeasurement UnitOfMeasurement Fields of Unit of Measurement  
unitOfMeasurementId UUID Unit of Measurement ID  
       
Tax and Price Information      
totalQuantity Decimal Quantity product  
unitPrice Decimal Unit price  
vatPercentage Decimal VAT percentage  
equivalenceSurchargePercentage Decimal Surcharge percentage  
       
Totals      
totalNet Decimal Amount after discounts, before taxes.  
totalGross Decimal Total amount before discounts and taxes.  
totalDiscount Decimal Sum of all discounts applied.  
totalCustomerDiscount Decimal Discount specific to the customer.  
totalLiquid Decimal Final amount due, including taxes.  
totalVat Decimal Total Value Added Tax (VAT) applied.  
totalVatBase Decimal Total taxable base before VAT.  
totalFeeSurcharge Decimal Total equivalence surcharge applied, based on VAT.  
totalVatFee Decimal VAT amount used as the base for the surcharge.  
       
totalLiquidNoWithholding Decimal Line total excluding withholding  
totalWithholding Decimal Line withholding amount  
withholdingPercentage Decimal Withholding percentage applied to the line  
       
Discounts      
firstDiscount Decimal First discount percentage  
Info

  • unitOfMeasurementId: UUID specifying the ID of the unit of measurement associated with the product.

  • firstDiscount: Various levels of discounts applicable to the document line. These are optional fields and are usually filled in based on promotional schemes or contractual obligations.

  • productId: The unique identifier for the product. Automatically filled when selecting a product.

  • vatPercentage: The percentage of Value Added Tax (VAT) applicable to this line. Important for accounting and for generating accurate invoices.

  • equivalenceSurchargePercentage: The percentage of equivalence surcharge applied in Spain .

  • totalLiquidNoWithholding
  • totalWithholding:
  • withholdingPercentage:
    • Unused (Spain only).

    The following fields are specific to the Spanish legislation (IRPF):

    • totalLiquidNoWithholding:
      Line total amount excluding withholding tax.
    • totalWithholding:
      Withholding amount (IRPF) calculated for the document line.
    • withholdingPercentage:
      Withholding percentage (IRPF) applied to the line and used to calculate the withholding amount.
    • Unused (Spain only).

  • order: This field represents the position of a line within a document.
    It is read-only and is automatically calculated during creation or update.
    Its purpose is to reflect the order in which the user entered the lines, as shown in the Sage Active interface.

    Would you like more information about how the order field works?

    Preserving line order during creation or update

    Although the order field cannot be set manually, its value is inferred from the order of lines in the payload.

    • On creation: The position of lines in the payload determines their order.
      The first line gets order = 1, the second order = 2, etc.
      → Make sure to sort the lines in the desired order before sending the payload.

    • On update: Lines are re-ordered from 1 to n based on the payload.
      Since the update follows a logic, you may choose between:

      • Sending only the changes (modified lines, new lines, lines marked for deletion),
      • Or sending all the lines (including unchanged ones) in the desired order.

      In both cases:

      • Lines with requestedAction = DELETED are excluded from the new numbering since they will be removed. (More info updating records)
      • New lines are appended after the last remaining line and automatically numbered accordingly.

salesDeliveryNotes/addresses

Common to all documents

Do not use the addresses[] array.
Instead, use mainAddress for the primary address and deliveryAddress for the delivery address.
Each of these objects contains only one address, representing a singular primary or delivery address, respectively.

Fields Type Description Length
countryId UUID Country Id  
country Country Fields of Country  
countryIsoCodeAlpha2 String Country Code 2
countryName String CountryName  
name String Code 50
firstLine String First Line 35
secondLine String Second Line 35
city String Town 35
zipCode String Postal Code 9
province String Province / Region / Federal State 25
Info
  • countryIsoCodeAlpha2 : ISO2 country code.
    This field can be used for creation and serves as a simple alternative to assign the country of the address by using the ISO2 code directly, rather than the country ID in the Countries resource.