SalesInvoice

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?
Mutation createSalesInvoice SalesInvoiceCreateGLDtoInput
Mutation updateSalesInvoice SalesInvoiceUpdateGLDtoInput
Mutation deleteSalesInvoice SalesInvoiceDeleteGLDtoInput
Query salesInvoices filtered by id Why?  
Query salesInvoices  
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.

img

Workflow

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

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

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

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

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

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

To change the Status of a salesInvoice, 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: 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 UUID Id  
creationDate DateTime Creation Date  
modificationDate DateTime Modification Date  
sourceType
  • null
  • PUBLIC_API
 indicates the origin of the salesInvoice (null=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
status String
  • Pending
  • Closed
  • Posted
  • PartiallyCollected
  • Collected
 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
       
Invoice 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.  
       
Notes      
comments String Notes for the customer/recipient of the document 1000
remarks String Internal notes for the document 1000
       
Customer Information      
documentID String Identification Number 20
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 SalesDiscount Fields of SalesDiscount  
salesDiscountGroupId UUID Sales Discount ID  
salesTariff SalesTariff Fields of SalesTariff  
salesTariffId UUID Sales tariff ID  

Specific to sales invoice documents

Fields Type Description Length
operationalNumber String Invoice Number 50
operationDate DateTime Date of operation (full fillement date)  
salesOrderNumber String External Order Number 250
type
  • NONE
  • NORMAL
  • CREDIT_NOTE
  • PAYMENT_IN_ADVANCE
 Document type  
hasCreditNote Boolean Indicates whether a credit note exists: true/false  
firstDueDate DateTime The first due date for payment of the invoice  
createdInSoftwareVersion String Links an invoice to the software release version 10
openItems[] Array open Items  
       
Payments      
paymentTermLines[] Array Payment Term Lines  

Specific to sales invoice documents type CREDIT_NOTE

Fields Type Description
sourceSalesInvoice 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.
  • 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.
  • 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).
    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”
  • createdInSoftwareVersion: This field links an invoice to the software release version that generated it.
    It is introduced to comply with anti-fraud regulations by ensuring traceability of the software version used for invoice creation.
  • status
    • 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
id UUID Id  
creationDate DateTime Date of creation  
modificationDate DateTime Last modification date  
       
salesInvoices Parent Information      
salesInvoices salesInvoice Fields of the parent salesInvoices 36
salesInvoiceId UUID salesInvoice ID  
       
Product Information      
product Product Fields of Product 36
productId UUID Product ID  
productCode String Product code 15
productName String Product name 2500
       
unitOfMeasurement Unit of Measurement 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.  
       
Discounts      
firstDiscount Decimal First discount percentage  

Specific to sales invoice document lines

Fields Type Description
AvailableForCreditNoteQuantity Decimal Quantity available for credit note

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 .

Specific to sales invoice document lines

  • AvailableForCreditNoteQuantity: The quantity from this sales invoice line that is still available to be credited via a credit note.

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.

img

Fields Type Description
id UUID Id
creationDate DateTime Creation Date
modificationDate DateTime Modification Date
     
amount Decimal Total amount of the item
paidAmountAccumulated Decimal Accumulated amount that has been paid
dueDate DateTime Due date for the payment
status
  • NOT_SPECIFIED
  • COLLECTED
  • PAID
  • PARTIAL
 Status of the payment
IsAdvanceInvoicePayment Boolean If the invoice is an Advance Invoice Payment
paymentMean 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 String 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 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.

salesInvoices/paymentTermLines

Only for Sales Invoice

Payment terms, used to define the list of payment terms for SalesInvoice
Example :

By default, payment terms are set based on those defined for the invoice’s customer.
However, when creating or editing an invoice, you can specify different payment terms that override the default ones.

Fields Type Description
id UUID Id
creationDate DateTime Creation Date
modificationDate DateTime Modification Date
     
order Int Classification of lines from 0 to n.
paymentMean PaymentMean Fields of PaymentMean
paymentMeanId UUID Id of the payment mean
type
  • NONE
  • PERCENTAGE
  • FIXED_AMOUNT
  • REMAINING_AMOUNT
 Type of calculation for the payment term line
value Decimal Numerical value used based on the type of calculation
condition
  • NONE
  • DAY_OF_PAYMENT
  • END_OF_MONTH
 To calculate due date
day Int Number of days
payDays[] Array Optional due days
Info
  • order : If REMAINING_AMOUNT, must always be last with the value 9999.
  • payDays : Array of optional due days. The day contained in the array closest to the number of days defined in day will be used to calculate the Due Date.
  • type : Defines the method used for payment term calculations. The interpretation of value depends on the selected type:
    • NONE : No specific calculation is applied.
    • PERCENTAGE : value represents a percentage of the total amount.
    • FIXED_AMOUNT : value is a fixed monetary amount.
    • REMAINING_AMOUNT : The remaining balance after all prior calculations. Must always be last in the order.
  • value : Represents the numerical input for the calculation based on type.
    • If type = PERCENTAGE, value should be between 0 and 100, indicating the percentage of the total amount.
    • If type = FIXED_AMOUNT, value is a fixed currency amount (e.g., 500 means a fixed payment of 500).
    • If type = REMAINING_AMOUNT, value is ignored, as the system automatically calculates the remaining balance.
    Examples:
    • If type = PERCENTAGE and value = 30, the payment term will cover 30% of the total amount.
    • If type = FIXED_AMOUNT and value = 500, the payment term will apply a fixed amount of 500.
    • If type = REMAINING_AMOUNT, the system will allocate the remaining balance after all prior lines are processed.
      In this case, order must always be set to 9999