Advance Invoice

Description

This page explains how to use the public API to create advance invoices and invoices with advance payment deductions.

In the Sage Active interface, from a quote or an order, it is possible to request the creation of an advance invoice.
A form allows defining the advance amount to be invoiced.
Then, when generating an invoice for the same customer, it is possible to deduct the amount of one or more advance invoices already issued to the customer.

Technically, Sage Active uses a product ADVANCE_PAYMENT which is not visible in the product list.
Note that this value depends on the legislation, e.g. ACOMPTE for the French Legislation.

An advance invoice will always include a line with this ADVANCE_PAYMENT product and the corresponding advance amount.
To deduct an advance payment from an invoice, Sage Active adds a line with a negative quantity associated with the ADVANCE_PAYMENT product, reflecting the amount to be deducted.

In the API context, the same mutation operation createSalesInvoice is used, just like for standard invoice creation.

The only distinction with a classical invoice is:

• Creating an advance invoice requires using the ADVANCE_PAYMENT product, with a quantity of 1 and the amount set to the advance payment value.
• Deducting an advance payment from an invoice involves adding one or multiple lines (in case of multiple advance payments) to the invoice with the ADVANCE_PAYMENT product, a quantity of -1, and the positive amount to be deducted.

Key Points to Know

• The field defaultPrepaymentAccountingAccount has been added to API resources overview / Customers, and the field defaultPrepaymentCustomerAccountId has been added to API resources overview / Organization Accounting Setup.
  They are used to post the accounting entry to an advance payment and deposit received account for advance invoices.

• The type of an advance invoice will automatically be set to PAYMENT_IN_ADVANCE.

  Fields	Type	Description
  type	NONE NORMAL CREDIT_NOTE PAYMENT_IN_ADVANCE	Document type

• The advance payment product can be found via a query on the Product entity by checking for the product that belongs to the CONCEPT category.

  Fields	Type	Description
  category	NOT_SPECIFIED PRODUCT SERVICE PRODUCT_AND_SERVICE CONCEPT	Product Category

    query {
    products(
        where:{category:{eq:CONCEPT}}
    )
    {
        edges {
        node {
            id
            code
            name
        }
        } 
    }  
    }
  

  Example response for the French Legislation

    {
        "data": {
            "products": {
                "edges": [
                    {
                        "node": {
                            "id": "f50af716-34ff-4c1b-8e65-dd08220a056b",
                            "code": "ACOMPTE",
                            "name": "Advance Payment"
                        }
                    }
                ]
            }
        }
    }
  

• The ADVANCE_PAYMENT product serves two purposes:
  1. Creating an advance invoice, where it is used with a quantity of 1 and the amount set to the advance payment value.
  2. Deducting an advance payment from an invoice, where one or multiple lines are added using the ADVANCE_PAYMENT product with a quantity of -1 and the positive amount to be deducted.

• Accounting Entries

  • When posting an advance invoice using postSalesInvoice, an accounting entry is generated, assigning the amount to the defaultPrepaymentAccountingAccount to record the advance payment.
  • When posting an invoice that includes one or multiple advance payment deductions using postSalesInvoice, two accounting entries are generated:
    1. A standard sales entry corresponding to the product lines of the invoice and their associated sales accounts.
    2. A counterpart entry offsetting the defaultPrepaymentAccountingAccount, which was initially assigned when the advance invoices were created.
  • To accommodate these two entries, the response of postSalesInvoice has been updated. In addition to returning the accountingEntryId and accountingEntryNumber for the first entry, it now includes an array of accounting entries containing the IDs and numbers of both generated entries.

  

Example of Creating an Advance Invoice

Here, a single line with the advance payment product ID, a quantity of 1, and the advance payment amount.

graphQL Mutation

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

graphQL Variables

{
  "values": {
    "customerId": "3ec1023d-96b4-4a9e-b536-2f8951d63ba0",
    "documentDate": "2025-02-10",
    "lines": [
      {
        "productId": "f50af716-34ff-4c1b-8e65-dd08220a056b",
        "productName": "Advance payment for Quote 0078", 
        "totalQuantity": 1,
        "unitPrice": 1000
      }
    ]
  }
}

Example of Creating an Invoice with Advance Payment Deduction

Here, the last line deducts the advance payment using the ID of the advance payment product.

graphQL Mutation

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

graphQL Variables

{
  "values": {
    "customerId": "3ec1023d-96b4-4a9e-b536-2f8951d63ba0",
    "documentDate": "2025-02-10",
    "lines": [
      {
        "productId": "f50af716-3200-4c1b-8e65-dd08220a056b",
        "totalQuantity": 50,
        "unitPrice": 11,
        "firstDiscount": 5
      },
      {
        "productId": "f50af716-3412-4c1b-8e65-dd08220a056b",
        "totalQuantity": 4,
        "unitPrice": 22,
        "firstDiscount": 0
      },
      {
        "productId": "f50af716-34ff-4c1b-8e65-dd08220a056b",
        "productName": "Advance payment for Quote 0078",
        "totalQuantity": -1,
        "unitPrice": 1000
      }
    ]
  }
}