SalesQuote

Quick Links

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

HTTP	Operation	Type	Object	DTO Why-DTOs?
POST	Create	Mutation Why 200?	`createSalesQuote`	`SalesQuoteCreateGLDtoInput`
POST	Update	Mutation Why 200?	`updateSalesQuote` How to update?	`SalesQuoteUpdateGLDtoInput`
POST	Delete	Mutation Why 200?	`deleteSalesQuote`	`SalesQuoteDeleteGLDtoInput`
POST	Read	Query	`salesQuotes filtered by id` Why?
POST	List	Query	`salesQuotes`
POST	List	Query	`salesQuoteLines`

Quick Tips

It is possible to query either salesQuote or directly from salesQuoteLines.

Querying salesQuotes 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 salesQuoteLines 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 quotes in the API context and in the product interface.
This resource serves as the blueprint for creating, modifying, and tracking sales quotes within the sales pipeline.
It leverages standard and customized data fields to accurately represent quotes for customers, which are crucial for managing and closing sales opportunities.

Note that it is possible to enter quotes for leads by providing the lead’s identification information within the context of the quote.
This avoids the need to always create a customer in advance.
However, this possibility is limited to the quote; as soon as a quote is won and generates an order, a customer becomes mandatory.

Explore the Must-See Sage Active Public API V2 Quoting Example!

Dive into the invaluable resource of our front-end app example!
This example showcases the practical use of Sage Active Public API for efficient quote management.

It’s a perfect demonstration of how you can leverage the API’s capabilities in real-world scenarios, significantly simplifying the quoting process.

Now, this application also allows you to import a complete set of demo data into the current company if it does not yet have any data.

Click here to access the example : Sample quotes

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

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

Would you like to see an example of how to add a quote?

graphQL Mutation

mutation ($values: SalesQuoteCreateGLDtoInput!) {  
  createSalesQuote(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": {
        "createSalesQuote": {
            "id": "e451aff7-074f-4e72-a6fb-4ea25e9d9c64",
            "operationalNumber": "0027"
        }
    }
}

Key	Value
`Authorization`	Bearer Current access Token How to find?
~~`X-TenantId`~~ DeprThis field is now deprecated, and we recommend using an alternative solution	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?

salesQuotes

Common to all documents

Fields	Type	Description	Length
id SSystem field that cannot be assigned	UUID	Id
creationDate SSystem field that cannot be assigned	DateTime	Creation Date
modificationDate SSystem field that cannot be assigned	DateTime	Modification Date
sourceType SSystem field that cannot be assigned	SALES PUBLIC_API	indicates the origin of the salesQuote (SALES=Manual entry)

*General Infos*
customer DATALOADERUtilize the DATALOADER feature to enrich your query by adding additional resource fields directly in the query.	Customer	Fields of Customer
customerId *The value of the field or object is mandatory NThe value of this field cannot be modified after the record is created	UUID	ID of the Customer entity. No mandatory for Quote See InfoAdditional information is available in the Info block below
documentDate DateThe GraphQL field type is DateTime, but only the date value is considered, the time value is ignored if provided.	DateTime	Document Date
operationalNumber	String	Document Number	50
operationalNumberPresetText DATALOADERUtilize the DATALOADER feature to enrich your query by adding additional resource fields directly in the query. NEWNew Feature Recently Added. (Introduced in the last version as well as in the previous version)	OperationalNumberPresetText	Fields of OperationalNumberPresetText
operationalNumberPresetTextId NEWNew Feature Recently Added. (Introduced in the last version as well as in the previous version)	UUID	ID of the operational number preset text See InfoAdditional information is available in the Info block below
status RThis field is read-only, its value cannot be assigned	String	See InfoAdditional information is available in the Info block below Pending Closed Declined	15
socialName	String	Social Name See InfoAdditional information is available in the Info block below	50
contactName	String	Contact Name	50
contactPhone	String	Contact Phone	15
contactEmail	String	Contact Email	50
contactJobAreaId NThe value of this field cannot be modified after the record is created	UUID	Id of the Contact Job Area
countryAcronym	String	Country Acronym	2

*Quote Lines*
lines[] *The value of the field or object is mandatory	Array	Document Lines

*Totals and discount*
totalNet RThis field is read-only, its value cannot be assigned	Decimal	Amount after discounts, before taxes. See InfoAdditional information is available in the Info block below
totalGross RThis field is read-only, its value cannot be assigned	Decimal	Total amount before discounts and taxes. See InfoAdditional information is available in the Info block below
totalDiscount RThis field is read-only, its value cannot be assigned	Decimal	Sum of all discounts applied. See InfoAdditional information is available in the Info block below
totalCustomerDiscount RThis field is read-only, its value cannot be assigned	Decimal	Discount specific to the customer. See InfoAdditional information is available in the Info block below
totalLiquid RThis field is read-only, its value cannot be assigned	Decimal	Final amount due, including taxes. See InfoAdditional information is available in the Info block below
totalVat RThis field is read-only, its value cannot be assigned	Decimal	Total Value Added Tax (VAT) applied. See InfoAdditional information is available in the Info block below
totalVatBase RThis field is read-only, its value cannot be assigned	Decimal	Total taxable base before VAT. See InfoAdditional information is available in the Info block below
totalFeeSurcharge RThis field is read-only, its value cannot be assigned	Decimal	Total equivalence surcharge applied, based on VAT. See InfoAdditional information is available in the Info block below
totalVatFee RThis field is read-only, its value cannot be assigned	Decimal	VAT amount used as the base for the surcharge. See InfoAdditional information is available in the Info block below
discount	Decimal	Specific discount applied. See InfoAdditional information is available in the Info block below

totalLiquidNoWithholding RThis field is read-only, its value cannot be assigned	Decimal	Total amount excluding withholding See InfoAdditional information is available in the Info block below
totalWithholding RThis field is read-only, its value cannot be assigned	Decimal	Total withholding amount See InfoAdditional information is available in the Info block below

*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 See InfoAdditional information is available in the Info block below	20

*Customer Information*
documentId	String	Identification Number See InfoAdditional information is available in the Info block below	20
documentLanguage	ENGLISH FRENCH GERMAN SPANISH	Language used in sales Document Pdf See InfoAdditional information is available in the Info block below	20
documentType DATALOADERUtilize the DATALOADER feature to enrich your query by adding additional resource fields directly in the query.	DocumentType	Fields of DocumentType used for identification purposes
documentTypeId RThis field is read-only, its value cannot be assigned	UUID	Identifier of the document type See InfoAdditional information is available in the Info block below
vatNumber	String	Vat Number See InfoAdditional information is available in the Info block below	20
invoiceEmail	String	Invoice Email See InfoAdditional information is available in the Info block below	50
hasEquivalenceSurcharge RThis field is read-only, its value cannot be assigned	Boolean	Subject to the equivalence surcharge regime See InfoAdditional information is available in the Info block below
mainAddress	ObjectType	Main Address
deliveryAddress	ObjectType	Delivery Address
salesDiscountGroup DATALOADERUtilize the DATALOADER feature to enrich your query by adding additional resource fields directly in the query.	SalesDiscountGroup	Fields of SalesDiscount
salesDiscountGroupId	UUID	Sales Discount ID
salesTariff DATALOADERUtilize the DATALOADER feature to enrich your query by adding additional resource fields directly in the query.	SalesTariff	Fields of SalesTariff
salesTariffId	UUID	Sales tariff ID

Specific to sales quote documents

Fields	Type	Description	Length
updateDocumentStatus MutThis field can only be used in mutations, not in queries UThis field is not available when creating the record. It can only be used when updating	PENDING DECLINED CLOSE	Allows changing the status of the quote.
declinedReason UThis field is not available when creating the record. It can only be used when updating	String	Indicates the reason why a quote was declined	100

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.
- This field is not applicable for customers that are not registered in the VIES system.
- For VIES customers, the format is described at this FAQ N° 11 https://ec.europa.eu/taxation_customs/vies/#/faq
mandatory for VIES customers

no mandatory for Spanish market

no mandatory for Germany market
invoiceEmail:
- Email address used when sending the Invoice PDF through DocumentPdfEmail.
  This email is required when creating a Sales Invoice and canGeneratePaymentLink is set to true, as it is used for online payment communication. See Generate Invoice with Online Payment.
- If not provided, the Invoice can still be created, but the online payment email workflow will not be available.
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 quotes

Status:
- Pending: The quote is in progress and can be modified.
- Closed: The quote can no longer be modified; it has either been transferred to an order or it has been closed.
- Declined: The quote is declined and can no longer be modified.
customerId : It is not mandatory to link an existing customer in Sage Active to a quote.
This allows for sending offers to prospects without the need to create a customer.
For this purpose, it is possible to directly specify the contact details of the third party in the quote, which will be specific to the current quote.
However, for other types of documents, linking the document to an existing customer is mandatory.
For this reason, through the Sage Active interface, when generating an order from a quote, if the quote is not associated with a customer, the creation of the customer will be required.

salesQuotes/lines or directly from salesQuoteLines

If the query targets salesQuotes, then use lines to get the details of the lines.
If the query targets salesQuoteLines, access the following fields directly, including the option to retrieve information on the parent salesQuote.

Common to all documents

Fields	Type	Description	Length
idSSystem field that cannot be assigned	UUID	Id
creationDate SSystem field that cannot be assigned	DateTime	Date of creation
modificationDate SSystem field that cannot be assigned	DateTime	Last modification date

*salesQuotes Parent Information*
salesQuote DATALOADERUtilize the DATALOADER feature to enrich your query by adding additional resource fields directly in the query.	SalesQuote	Fields of the parent salesQuotes	36
salesQuoteId	UUID	salesQuote ID

*Product Information*
product DATALOADERUtilize the DATALOADER feature to enrich your query by adding additional resource fields directly in the query.	Product	Fields of Product	36
productId	UUID	Product ID See InfoAdditional information is available in the Info block below
productCode	String	Product code	15
productName	String	Product name	2500
order RThis field is read-only, its value cannot be assigned	Int	Classification of lines from 1 to n See InfoAdditional information is available in the Info block below

unitOfMeasurement DATALOADERUtilize the DATALOADER feature to enrich your query by adding additional resource fields directly in the query.	UnitOfMeasurement	Fields of Unit of Measurement
unitOfMeasurementId DIn creation, this field can have a default value automatically calculated	UUID	Unit of Measurement ID See InfoAdditional information is available in the Info block below

*Tax and Price Information*
totalQuantity	Decimal	Quantity product
unitPrice	Decimal	Unit price
vatPercentage RThis field is read-only, its value cannot be assigned	Decimal	VAT percentage See InfoAdditional information is available in the Info block below
equivalenceSurchargePercentageRThis field is read-only, its value cannot be assigned	Decimal	Surcharge percentage See InfoAdditional information is available in the Info block below

*Totals*
totalNet RThis field is read-only, its value cannot be assigned	Decimal	Amount after discounts, before taxes.
totalGross RThis field is read-only, its value cannot be assigned	Decimal	Total amount before discounts and taxes.
totalDiscount RThis field is read-only, its value cannot be assigned	Decimal	Sum of all discounts applied.
totalCustomerDiscount RThis field is read-only, its value cannot be assigned	Decimal	Discount specific to the customer.
totalLiquid RThis field is read-only, its value cannot be assigned	Decimal	Final amount due, including taxes.
totalVat RThis field is read-only, its value cannot be assigned	Decimal	Total Value Added Tax (VAT) applied.
totalVatBase RThis field is read-only, its value cannot be assigned	Decimal	Total taxable base before VAT.
totalFeeSurcharge RThis field is read-only, its value cannot be assigned	Decimal	Total equivalence surcharge applied, based on VAT.
totalVatFee RThis field is read-only, its value cannot be assigned	Decimal	VAT amount used as the base for the surcharge.

totalLiquidNoWithholding RThis field is read-only, its value cannot be assigned	Decimal	Line total excluding withholding See InfoAdditional information is available in the Info block below
totalWithholding RThis field is read-only, its value cannot be assigned	Decimal	Line withholding amount See InfoAdditional information is available in the Info block below
withholdingPercentage RThis field is read-only, its value cannot be assigned	Decimal	Withholding percentage applied to the line See InfoAdditional information is available in the Info block below

*Discounts*
firstDiscount	Decimal	First discount percentage See InfoAdditional information is available in the Info block below

Specific to sales quote document lines

Fields	Type	Description	Length
pendingQuantity RThis field is read-only, its value cannot be assigned	Decimal	Pending Quantity See InfoAdditional information is available in the Info block below
status	String	See InfoAdditional information is available in the Info block below Pending Completed Partial Declined	15

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 PATCH 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.

Specific to sales quote document lines

pendingQuantity: The quantity of the sales quote line that is still pending. This integer represents the amount of product yet to be fulfilled.
status: Indicates the current status of the Sales Quote Line, reflecting its progression in the sales process. Possible statuses include:
- Pending: The quote line is awaiting approval or further action.
- Completed: The quote line has been fully approved and is finalized.
- Partial: The quote line has been partially approved or is awaiting completion of certain conditions.
- Declined: The quote line is declined and can no longer be modified.

salesQuotes/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 DATALOADERUtilize the DATALOADER feature to enrich your query by adding additional resource fields directly in the query.	Country	Fields of Country
countryIsoCodeAlpha2	String	Country Code See InfoAdditional information is available in the Info block below	2
countryNameRThis field is read-only, its value cannot be assigned	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.

Quick Links

Quick Tips

Description

Explore the Must-See Sage Active Public API V2 Quoting Example!

Would you like to see an example of how to add a quote?

graphQL Mutation

graphQL Variables

Example of Response

Header

salesQuotes

Info

salesQuotes/lines or directly from salesQuoteLines

Info

Preserving line order during creation or update

salesQuotes/addresses

Info