SalesInvoice

NEWNew Feature Recently Added. (Introduced in the last version as well as in the previous version)

It is now possible to set the invoice number using the operationalNumber field during invoice creation.
This enhancement allows users to import an invoice already issued by another software while keeping its original number.

If operationalNumber is provided with a non-empty value, the invoice is automatically set to Closed status.
If operationalNumber is not specified or left empty, the invoice is created without a number and remains in Draft status.

HTTP	Operation	Type	Object	DTO Why-DTOs?
POST	Create	Mutation	`createSalesInvoice`	`SalesInvoiceCreateGLDtoInput`
POST	Update	Mutation	`updateSalesInvoice`	`SalesInvoiceUpdateGLDtoInput`
POST	Delete	Mutation	`deleteSalesInvoice`	`SalesInvoiceDeleteGLDtoInput`
POST	Read	Query	`salesInvoices filtered by id` Why?
POST	List	Query	`salesInvoices`
POST	List	Query	`salesInvoiceLines`

Quick Tips

It is possible to query either salesInvoice or directly from salesInvoiceLines.

Querying salesInvoice 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 salesInvoiceLines 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 Invoices in the API context and in the product interface.
This resource is pivotal for invoicing customers after order fulfillment and serves as a legally binding request for payment.
The Sales Invoices entity leverages both standard and custom fields, allowing businesses to create detailed invoices that include necessary information like customer codes, discounts, product lines, and tax details.
This ensures compliance and contributes to a smoother accounts receivable process.

Workflow

Create the Invoice and Optionally View or Modify It: Start by creating a sales invoice using the SalesInvoice service.
Once created, you can view and make any necessary modifications to the invoice before finalizing it.
Close the Invoice to Prevent Further Modifications: Use the CloseSalesInvoice service to confirm the invoice.
This action locks the invoice, ensuring that its content cannot be changed. This step is essential for securing the invoice details before posting.
Post the Invoice to Generate Accounting Entries: After closing, proceed with posting the invoice using the PostSalesInvoice service.
Posting the invoice will generate the necessary accounting entries, making the invoice part of the company’s financial records.
View the Invoice’s Payment Due Dates: Check the payment due dates and related information using the SalesInvoiceOpenItems service.
This allows you to see when payments are expected and track outstanding amounts for the invoice.
Apply Partial or Full Payments to the Invoice: Manage the payments on the invoice by using the SalesOpenItemSettlement service.
You can apply both partial and full payments, keeping track of amounts paid and any remaining balances.
Generate a Credit Note if Necessary: In case of returns, refunds, or corrections, you can issue a credit note related to the invoice using the generateCreditNote service.

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

Would you like to see an example of how to add an invoice?

graphQL Mutation

mutation ($values: SalesInvoiceCreateGLDtoInput!) {  
    createSalesInvoice(input: $values) {
    id
  }
}

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": {
        "createSalesInvoice": {
            "id": "e451aff7-074f-4e72-a6fb-4ea25e9d9c64"
        }
    }
}

For salesInvoices, the operationalNumber is not assigned at the time of creation, unlike other document types.
It is only assigned after the CloseSalesInvoice operation.

{
    "data": {
        "closeSalesInvoice": {
            "id": "e451aff7-07f0-4e72-a6fb-4ea25e9d9c64",
            "operationalNumber": "0037"
        }
    }
}

Key	Value
`Authorization`	Bearer Current access Token How to find?
`X-TenantId`	Current tenant id How to find?
`X-OrganizationId`	Current organization Id How to find?
`x-api-key`	Primary or secondary subscription key of your app How to find?

salesInvoices

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

*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	DateTime DateThe GraphQL field type is DateTime, but only the date value is considered, the time value is ignored if provided.	Document Date
operationalNumber	String	Document Number	50
status	String	See InfoAdditional information is available in the Info block below Pending Closed Posted PartiallyCollected Collected	15
socialName NThe value of this field cannot be modified after the record is created	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
countryAcronym	String	Country Acronym	2

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

*Totals and discount*
totalGross	Decimal	Total Gross
totalDiscount	Decimal	Total Discount
totalNet	Decimal	Total Net
discount	Decimal	Discount See InfoAdditional information is available in the Info block below
totalCustomerDiscount	Decimal	Total discount specific to the customer
totalLiquid	Decimal	Total amount due including taxes
totalVat	Decimal	Total Vat
totalVatBase	Decimal	Total Vat Base
totalFeeSurcharge	Decimal	Total Vat Surcharge See InfoAdditional information is available in the Info block below
totalVatFee	Decimal	Total Surcharge Base See InfoAdditional information is available in the Info block below

*Notes*
comments	String	Comments	1000
remarks	String	Remarks	1000

*Customer Information*
documentID	String	Identification Number See InfoAdditional information is available in the Info block below	20
vatNumber	String	Vat Number See InfoAdditional information is available in the Info block below	20
invoiceEmail	String	Invoice Email	50
hasEquivalenceSurcharge	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.	SalesDiscount	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 invoice documents

Fields	Type	Description	Length
operationalNumber	String	Invoice Number See InfoAdditional information is available in the Info block below	50
operationDate	DateTime DateThe GraphQL field type is DateTime, but only the date value is considered, the time value is ignored if provided.	Date of operation (full fillement date) See InfoAdditional information is available in the Info block below
salesOrderNumber	String	External Order Number See InfoAdditional information is available in the Info block below	250
type	NONE NORMAL CREDIT_NOTE	Document type
hasCreditNote	Boolean	Indicates whether a credit note exists: true/false
firstDueDate	DateTime DateThe GraphQL field type is DateTime, but only the date value is considered, the time value is ignored if provided.	The first due date for payment of the invoice
openItems[]	Array	open Items

Specific to sales invoice documents type CREDIT_NOTE

Fields	Type	Description
sourceSalesInvoice DATALOADERUtilize the DATALOADER feature to enrich your query by adding additional resource fields directly in the query.	UUID	Fields of salesInvoice if the type is CREDIT_NOTE
sourceSalesInvoiceId	UUID	ID of the invoice if the type is CREDIT_NOTE

Info

customerId: A unique identifier (UUID) for the Customer entity.
discount: Represents the total discount that has been applied to the document.
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

Specific to sales invoice documents

operationalNumber: It is possible to set the invoice number using this field during invoice creation.
- If is provided with a non-empty value, the invoice will automatically be set to Closed status.
- If is not specified or left empty, the invoice will be created without a number and remain in Draft status.
operationDate: This is the date on which the delivery of goods or the provision of services is carried out or completed.
It must necessarily be on or before the invoice date(Fulfillment date).
COMING SOON This feature is currently in development and will be available in the next version. It’s already documented to keep you informed about its upcoming availability In the next version, it will be possible to specify an operationDate when it differs from the invoice date, allowing more flexibility in tracking the actual operation date separately from the invoicing date.
salesOrderNumber: This field allows the entry of an order number that has not been entered in Sage Active. Additionally, this field can also accept an external invoice number in the context of importing invoices not entered in Sage Active.
Default value if not specified : “unspecified”
status UPDATEDModifications have been made to the properties or attributes of this object recently.
- Pending: (Draft) The invoice can be modified; it has not yet been transferred to accounting.
- Closed: (Unposted) The invoice can no longer be modified; it was supposed to be transferred to accounting, but the operation failed or was canceled.
- Posted: (Awaiting collection) The invoice can no longer be modified; it has been transferred to accounting.
- PartiallyCollected: (Partially collected) The invoice is partially settled. Payments are pending.
- Collected: (Collected) The invoice is fully settled.
Attention!

The Sage Active interface overrides the values Posted and PartiallyCollected of the status field with Overdue and PartiallyOverdue if the value of the firstDueDate field is earlier than the current date.
However, these values Overdue and PartiallyOverdue are not returned by the API, which instead returns Posted and PartiallyCollected, respectively.

To filter invoices that are overdue, you can use the following filter, replacing the date with the desired date (e.g., the current date or the current date minus a few days to allow for a grace period in overdue days):
```
query {
  salesInvoices(
    where: {
      status: { in: ["Posted","PartiallyCollected"] }
      firstDueDate: { lt: "2024-10-09" }
    }
  )
}
```
vatNumber :

mandatory for VIES customers

no mandatory for Spanish market

no mandatory for Germany market
documentId :

no mandatory for French market

mandatory for not VIES customers

no mandatory for Germany market

salesInvoices/lines or salesInvoiceLines

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

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

*salesInvoices Parent Information*
salesInvoices DATALOADERUtilize the DATALOADER feature to enrich your query by adding additional resource fields directly in the query.	salesInvoice	Fields of the parent salesInvoices	36
salesInvoiceId	UUID	salesInvoice 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

unitOfMeasurement DATALOADERUtilize the DATALOADER feature to enrich your query by adding additional resource fields directly in the query. COMING SOON This feature is currently in development and will be available in the next version. It’s already documented to keep you informed about its upcoming availability	Unit of Measurement	Fields of Unit of Measurement
unitOfMeasurementId DIn creation, this field can have a default value automatically calculated COMING SOON This feature is currently in development and will be available in the next version. It’s already documented to keep you informed about its upcoming availability	UUID	Unit of Measurement ID See InfoAdditional information is available in the Info block below

*Tax and Price Information*
totalQuantity	Int	Quantity product
unitPrice	Decimal	Unit price
totalNet	Decimal	Net 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

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

Info

unitOfMeasurementId: COMING SOON This feature is currently in development and will be available in the next version. It’s already documented to keep you informed about its upcoming availability 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 .

salesInvoices/openItems

An Open Item is a financial transaction that allows you to know if it has been fully settled or paid.
Each open item includes detailed information such as the total amount, accumulated amount paid, and the payment due date.

For a single invoice, there can be as many open items as there are different payment installments, which is why openItems is structured as an array to accommodate multiple entries per invoice.

The payment status provides insight into the progress of settling each item.
Additionally, the identifier of the payment method used is provided to track the settlement method.

Fields	Type	Description
idSSystem 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

amount	Decimal	Total amount of the item See InfoAdditional information is available in the Info block below
paidAmountAccumulated	Decimal	Accumulated amount that has been paid See InfoAdditional information is available in the Info block below
dueDate	DateTime	Due date for the payment See InfoAdditional information is available in the Info block below
status	NOT_SPECIFIED COLLECTED PAID PARTIAL	Status of the payment See InfoAdditional information is available in the Info block below
paymentMean DATALOADERUtilize the DATALOADER feature to enrich your query by adding additional resource fields directly in the query.	PaymentMean	Fields of PaymentMean
paymentMeanId	UUID	Identifier of the payment method used

Info

amount : Total amount due for the open item.
creationDate : Indicates when the item was initially created.
modificationDate : Timestamp of the last update to the item, null if no updates have been made.
paidAmountAccumulated : Total amount that has been paid towards the item up to the current date.
dueDate : Date by which the payment for the item is due.
status: Represents the current status of the payment, indicating the extent to which the item has been settled. The possible values are:
- NOT_SPECIFIED: No specific payment status has been detailed.
- COLLECTED: Payment has been fully collected from customers.
- PAID: Not used for Customers
- PARTIAL: Payment for the item has been made partially.

salesInvoices/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.	String	Fields of Country
countryIsoCodeAlpha2MutThis field can only be used in mutations, not in queries	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	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.

NEWNew Feature Recently Added. (Introduced in the last version as well as in the previous version)

Quick Tips

Description

Workflow

Would you like to see an example of how to add an invoice?

graphQL Mutation

graphQL Variables

Example of Response

Header

salesInvoices

Info

Attention!

salesInvoices/lines or salesInvoiceLines

Info

salesInvoices/openItems

Info

salesInvoices/addresses

Info