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 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.
  Once the advance invoice is created, store its returned ID, as it will be needed later when creating the final invoice.

• 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.
  For each deduction line (negative quantity), the originId field must be filled with the ID of the corresponding advance invoice that was previously stored.

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 CREDIT_NOTE NORMAL 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 CONCEPT FEE PRODUCT PRODUCT_AND_SERVICE SERVICE	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, the positive amount to be deducted, and the originId field referencing the advance invoice ID.

• 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", // Product belonging to the CONCEPT category
        "productName": "Advance payment for Quote 0078", 
        "totalQuantity": 1,  // always 1
        "unitPrice": 1000 // Amount of the advance payment
      }
    ]
  }
}

Example Response

{
  "data": {
    "createSalesInvoice": {
      //this ID is mandatory when creating the final invoice in order to deduct the advance payment.
      "id": "a4e6d9b2-2e41-4df0-9f83-c4d1a553fe24"  
    }
  }
}

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 and references the advance invoice ID via originId.

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, // always -1
        "unitPrice": 1000, // Optional as the system will always apply the exact amount from the corresponding advance invoice
        "originId": "a4e6d9b2-2e41-4df0-9f83-c4d1a553fe24" // ID of the advance invoice
      }
    ]
  }
}