Issue invoices using the API

Steps

1. Issue invoice

Issue an invoice from a seller account to a buyer account by calling POST /invoices with your own reference (reference), the invoice code (code) and the payment terms. At least a line item must be provided whether inside groups or as not grouped lines. The reference is meant to be used to pass your internal ID for the invoice.

The code of the invoice will be included in the generated document for the invoice and it is a public identifier shared with the buyer and meant to be used for accounting and tax purposes. Based on your jurisdiction you might have rules and restriction on the code value, we support the generation of sequential values for the code based on invoices series. Get in contact with us to know more about this feature, self-serving APIs to configure invoices series are coming soon.

The seller and buyer information needed to generate the invoice and create the invoice documents is retrieved from the accounts with the latest version of the account data.

The reference and metadata fields allow correlating the invoicing independently from the language of the invoice, while the name and notes fields are used to generate the invoice document localized in the language the buyer needs to receive it.

For additional details of the invoice, you can either use the external_links to include links to resources outside getpaid's solution or upload attached documents to getpaid and link them to the invoice.

The usage of webhooks is recommended to receive real-time notifications about the changes on the invoice and its payments. If you plan to use the invoices series and store the generated code, the usage of webhooks is required.

The response of the invoice creation contains:

• The id of the invoice
• The totals of the invoice including the taxes by group (reference) and percentage, and per line
• The issued_at if the code is provided and it is issued synchronously.
• The status of the invoice:
  • initiated if the code is generated, then the invoice will be issued asynchronously
  • issued if the code is provided, then the invoice has been issued

In this scenario:

• The code is generated using an invoices series.
• There is a configured email notification to the buyer.
• There is a configured pdf invoice document.
• There is a single line in a group that contains a disccount, taxes, and some custom notes.
• The payment.methods are set to external_bank_transfer where the payment_instrument_id is the ID of the external bank account associated to the platform account.
• There is an additional link to a resource outside getpaid's solution included in external_links.
• The webhook URL is configured to receive the notifications.

Request

POST /invoices

{
  "reference": "2ac5f67a-d621-4c1e-8dec-28c8f33d71b8",
  "code": {
    "type": "generated",
    "series_id": "ser_4ehg1mkv3mvt3256vcn8dspb4h"
  },
  "seller": {
    "id": "acc_96468af833b74501bd0415e797"
  },
  "buyer": {
    "id": "acc_44678r08jtm8zbt227tzhc4nw5",
    "notifications": [
      {
        "type": "email",
        "to": [
          "jane.doe@mail.com"
        ]
      }
    ]
  },
  "currency": "EUR",
  "groups": [
    {
      "reference": "pieces",
      "description": "Piezas",
      "lines": [
        {
          "item": {
            "reference": "1POC082709ABC",
            "name": "Filtro aceite",
            "amount": 1581,
            "unit": "item"
          },
          "quantity": 1,
          "discounts": [
            {
              "type": "percentage",
              "percent": 20
            }
          ],
          "taxes": [
            {
              "reference": "vat",
              "name": "IVA",
              "percent": 21
            }
          ],
          "notes": [
            "Filtro Bosch",
            "Descuento: 20%"
          ]
        }
      ]
    }
  ],
  "payment": {
    "terms": {
      "type": "deferred",
      "due_dates": [
        {
          "days": 30
        }
      ]
    },
    "methods": [
      {
        "type": "external_bank_transfer",
        "payment_instrument_id": "pai_42572e6cf7914e23b5b312d5b1"
      }
    ]
  },
  "documents": [
    {
      "format": "pdf"
    }
  ],
  "external_links": [
    {
      "name": "Order",
      "url": "https://platform.io/orders/ORD-202401091516-0023"
    }
  ],
  "urls": {
    "webhook": "https://webhooks.platform.io/getpaid/invoices/INV-202401091516-0023"
  }
}

Response

201 Created

{
  "id": "inv_4ehg1mkv3mvt3256vcn8dspb4h",
  "type": "standard",
  "status": "initiated",
  "groups": [
    {
      "reference": "pieces",
      "lines": [
        {
          "item": {
            "reference": "1POC082709ABC",
            "name": "Filtro aceite"
          },
          "base": 1265,
          "tax": 265,
          "total": 1530
        }
      ]
    }
  ],
  "payment": {
    "terms": {
      "type": "deferred",
      "due_dates": [
        {
          "id": "ptm_4567107zf94k842z8511n9c7dt",
          "number": 1,
          "days": 30,
          "amount": 1530
        }
      ]
    }
  },
  "totals": {
    "base": 1265,
    "tax": 265,
    "taxes": [
      {
        "reference": "vat",
        "percentages": [
          {
            "percent": 21,
            "tax": 265,
            "base": 1265
          }
        ],
        "sum": 265
      }
    ],
    "total": 1530
  }
}

2. Notify about invoice issued

Depending on the invoice code, provided or generated, the invoice is issued right after creation or asynchronously after the code is generated. In both cases a invoice_issued webhook notification in sent in the configured webhook URL.

It is particularly important when using invoices series to generated the invoice code since this webhook will contain the generated code value in its payload. You will have the option to use your own reference or our id to correlate the code value with the invoice.

3. Generate invoice document

getpaid generates the invoice document asynchronously once the invoice is issued.

It can be generated in various formats and provides and URL to download it.

4. Notify about document creation

Once the invoice document creation is completed in each of the formats needed, a invoice_document_created webhook notification per document generated is sent to the configured webhook URL.

5. Send invoice buyer notification

If the buyer notifications are configured, getpaid sends a newly issued invoice notification to the buyer with the invoice documents attached.

6. Notify about buyer notification sent

If the buyer notifications are configured, once the notification is sent, a invoice_buyer_notification_sent webhook notification is sent to the configured webhook URL.

7. Reconcile invoice payments

If external bank account is configured for reconciliation and used in the invoice, getpaid monitors the bank transactions to try to associate the receive payments to the issued invoices.

See receivables reconciliation section for more details.