Invoices

Overview

Invoices bill a customer for one or more products. Every invoice is given a sequential document number on creation, a hosted PDF download link, and an optional online payment link that lets the customer pay the invoice by card.

Invoices are also generated automatically by other parts of the platform:

• Collections create an invoice per transaction when the collection was submitted with an invoice object.
• Subscriptions create an invoice per billing cycle.

Automatically generated invoices are linked back to their source through transaction_id and subscription_id. They are read-only apart from their status, and invoices linked to a subscription can not be edited at all.

Invoice status

NOTE

Only DRAFT, ISSUED and PAID may be set through the API. OVERDUE, UNCOLLECTABLE and VOID are managed by the platform.

Through update a PAID status may only be applied to an invoice that has already been issued; a draft must be issued first.

Payment collection

payment_collection determines how the invoice gets settled:

WARNING

AUTOCHARGE requires the customer to have a card stored through the card vault API, and the payment method supplied in default_payment_method_id must be the one the card was vaulted against. If the customer has no vaulted card the invoice can not be charged automatically and they will have to pay through the payment link instead, so leave is_payment_link set to true when using AUTOCHARGE.

Totals

Totals are always calculated by the platform from the line items and can not be supplied directly.

Each line is costed and taxed on its own, the way accounting software does it:

1. The line total excluding VAT is price × qty.
2. When is_tax is true, 15% VAT is charged on that line total and rounded to the nearest cent. tax is returned on every line item; when is_tax is false it is always 0.00.
3. The line's total is its total excluding VAT plus its tax.
4. total_excl is the sum of every line total excluding VAT, total_tax is the sum of every line's tax, and total_incl is the two added together.

Because VAT is rounded per line rather than on the subtotal, an invoice can differ by a cent or two from applying 15% to total_excl directly. Three lines of R10.10 each carry R1.52 of VAT, so the invoice totals R34.86 rather than the R34.85 that taxing the R30.30 subtotal would give. This matches how Xero and Sage total the same document, so invoices reconcile when they are synced across.

NOTE

Quantity is part of the line, not a repeat of it. One line of qty 3 at R10.10 is taxed once on R30.30 (R4.55 of VAT), where three separate lines of qty 1 are taxed three times on R10.10 (R4.56 in total).

total_tax and each line's tax always add up, so an invoice can be reconciled line by line. On an invoice that records a payment already collected, the amount taken is what the invoice must show, so the last line absorbs any rounding difference between it and the sum of the lines. That line's tax can therefore be a cent off 15% of its own total.

Document numbers

document_number is assigned when the invoice record is created (including drafts) and is unique and sequential per account. The format is INV-0000001, or INV-{PREFIX}-0000001 when a custom invoice prefix has been configured on your account. Numbers are never reused, including by deleted invoices.

Create

API call to create new invoices.

Path

POST /invoices/create

Request Body

{
  "records": [{
    "customer_id": "cus_Fjim5EFyD3mUcXWcaoOkP",
    "invoice_status": "DRAFT",
    "items": [{
      "product_id": "pro_MsAXh25ajSIv4s6k52vQn",
      "description": "Good for exercise",
      "price": 45.00,
      "qty": 2
    }],
    "is_tax": true,
    "due_days": 30,
    "payment_collection": "REQUEST_PAYMENT",
    "default_payment_method_id": null,
    "is_payment_link": true,
    "memo": "Thank you for your business.",
    "footer": "Please use the invoice number as your payment reference.",
    "metadata": { "my_key": "my_value" }
  }]
}

Recording an invoice that has already been settled:

{
  "records": [{
    "customer_id": "cus_Fjim5EFyD3mUcXWcaoOkP",
    "invoice_status": "PAID",
    "paid_at": "2026-09-07 14:32:10",
    "items": [{
      "product_id": "pro_MsAXh25ajSIv4s6k52vQn",
      "price": 45.00,
      "qty": 2
    }],
    "is_tax": true
  }]
}

Charging a vaulted card automatically on the due date:

{
  "records": [{
    "customer_id": "cus_Fjim5EFyD3mUcXWcaoOkP",
    "invoice_status": "ISSUED",
    "payment_collection": "AUTOCHARGE",
    "default_payment_method_id": "pam_YxK0zCtJpVpRzdBYTlxnm",
    "items": [{
      "product_id": "pro_MsAXh25ajSIv4s6k52vQn",
      "price": 45.00,
      "qty": 2
    }],
    "is_tax": true,
    "due_days": 30
  }]
}

Response Body

The response follows the same format as the list response

{
  "status": true,
  "records": [{
    "id": "inv_8OPF8BRIXPfaHbXglqVAy",
    "document_number": "INV-0000015",
    ...
  }, ...]
}

Request Parameters

Update

API call to update existing invoices.

What may be updated depends on the current status of the invoice:

• Draft invoices may be edited or deleted. Every field accepted by create may be changed, the invoice may be issued by setting invoice_status to ISSUED, and it may be deleted by setting invoice_status to DELETED.
• Issued and overdue invoices may only be marked as paid by setting invoice_status to PAID. No other field may be changed.

Path

POST /invoices/update

Request Body

Only include fields you wish to change (besides id used to find the record).

Editing a draft:

{
  "records": [{
    "id": "inv_8OPF8BRIXPfaHbXglqVAy",
    "due_days": 14,
    "items": [{
      "product_id": "pro_MsAXh25ajSIv4s6k52vQn",
      "price": 45.00,
      "qty": 3
    }]
  }]
}

Deleting a draft:

{
  "records": [{
    "id": "inv_8OPF8BRIXPfaHbXglqVAy",
    "invoice_status": "DELETED"
  }]
}

Marking an issued invoice as paid:

{
  "records": [{
    "id": "inv_8OPF8BRIXPfaHbXglqVAy",
    "invoice_status": "PAID",
    "paid_at": "2026-09-07 14:32:10"
  }]
}

Response Body

The response follows the same format as the list response

{
  "status": true,
  "records": [{
    "id": "inv_8OPF8BRIXPfaHbXglqVAy",
    ...
  }, ...]
}

Request Parameters

WARNING

Invoices linked to a subscription can not be edited at all, only their status may be changed.

Deleting is only possible while the invoice is a draft. An issued invoice must be voided instead so that the document number remains on record, which can be done from the Kwik dashboard.

List

List invoices loaded on the platform, including the PDF download link and the online payment link.

Path

GET /invoices/list

Query Parameters

Response Body

{
  "status": true,
  "pagination": {
    "total": 215,
    "per_page": 100,
    "current_page": 1,
    "last_page": 3,
    "next_page": 2,
    "prev_page": null
  },
  "records": [{
    "id": "inv_8OPF8BRIXPfaHbXglqVAy",
    "created_at": "2026-09-07 10:30:00",
    "updated_at": null,
    "deleted_at": null,
    "archived_at": null,
    "document_number": "INV-0000015",
    "invoice_status": "ISSUED",
    "customer_id": "cus_Fjim5EFyD3mUcXWcaoOkP",
    "subscription_id": null,
    "transaction_id": null,
    "items": [{
      "product_id": "pro_MsAXh25ajSIv4s6k52vQn",
      "name": "Monthly Membership",
      "description": "Good for exercise",
      "price": 45.00,
      "qty": 2,
      "tax": 13.50,
      "total": 103.50
    }],
    "is_tax": true,
    "total_excl": 90.00,
    "total_tax": 13.50,
    "total_incl": 103.50,
    "due_days": 30,
    "due_date": "2026-10-07",
    "payment_collection": "REQUEST_PAYMENT",
    "default_payment_method_id": null,
    "is_payment_link": true,
    "download_link": "https://invoices.kwik.co.za/download/xDq1ZbW...",
    "payment_link": "https://pay.kwik.co.za/invoice/xDq1ZbW...",
    "email_cc": "accounts@mail.com",
    "date_send_scheduled": null,
    "date_invoice_sent": "2026-09-07 10:31:44",
    "paid_at": null,
    "memo": "Thank you for your business.",
    "footer": "Please use the invoice number as your payment reference.",
    "metadata": { "my_key": "my_value" }
  }, {
    ...
  }]
}

Response Parameters

Send

Email an invoice to your customer. The invoice email contains a link to view and download the invoice, and an online payment link when is_payment_link is true.

Sending a DRAFT invoice issues it, changing the status to ISSUED. Invoices that have already been sent can be sent again as a reminder, and paid invoices can be sent to provide the customer with a receipt.

Path

POST /invoices/send

Request Body

Send immediately to the customer's billing email address:

{
  "records": [{
    "id": "inv_8OPF8BRIXPfaHbXglqVAy"
  }]
}

Send with a copy to additional addresses, scheduled for a future date:

{
  "records": [{
    "id": "inv_8OPF8BRIXPfaHbXglqVAy",
    "cc_email": "accounts@mail.com, auditor@mail.com",
    "schedule": "2026-09-14"
  }]
}

Response Body

The response follows the same format as the list response

{
  "status": true,
  "records": [{
    "id": "inv_8OPF8BRIXPfaHbXglqVAy",
    "invoice_status": "ISSUED",
    "date_send_scheduled": "2026-09-14",
    "date_invoice_sent": null,
    ...
  }, ...]
}

Request Parameters

Recipient

The invoice is always emailed to the linked customer record, so the address can not be set per send. The billing_email on the customer is used when it is set, otherwise the customer's email is used. Update the customer through the customers API to change where invoices are delivered.

When the customer has neither a billing_email nor an email there is nowhere to send the invoice and the request fails with a validation error.

NOTE

A scheduled invoice is issued straight away but only emailed on the scheduled date, so date_invoice_sent stays null until it goes out. Send the invoice again without a schedule to cancel the schedule and email it immediately.