Invoices | Rebill Help Centre

Invoices are the core resource in Rebill. Each invoice belongs to a client, contains one or more line items, and progresses through a status lifecycle from draft to paid.

Invoice statuses: draft · scheduled · sent · paid · paid_partial · cancelled

List invoices

GET /invoice

Returns invoices for your account. By default, only active invoices (draft, sent, paid_partial) are included.

Query parameter	Type	Description
include_paid	boolean	Include paid invoices (default: false)
include_cancelled	boolean	Include cancelled invoices (default: false)

curl "https://rebill-api-896466068278.africa-south1.run.app/invoice?include_paid=true" \
  -H "Authorization: Bearer sk_your_secret_key"

Response:

{
  "invoices": [
    {
      "id": "abc123",
      "number": "INV0001",
      "status": "sent",
      "client_id": "xyz789",
      "currency": "ZAR",
      "invoice_date": "2026-03-01T00:00:00Z",
      "due_date": "2026-03-15T00:00:00Z",
      "amount_due": 150000,
      "items": [...]
    }
  ]
}

Get an invoice

GET /invoice/:id

curl https://rebill-api-896466068278.africa-south1.run.app/invoice/abc123 \
  -H "Authorization: Bearer sk_your_secret_key"

Invoice object

Field	Type	Description
id	string	Unique identifier
public_id	string	Short ID used in public-facing payment links
created	timestamp	When the invoice was created
number	string	Human-readable invoice number (e.g. INV0001)
currency	string	ISO 4217 currency code
status	string	draft · scheduled · sent · paid · paid_partial · cancelled
client_id	string	ID of the client this invoice belongs to
invoice_date	timestamp	Invoice issue date
due_date	timestamp	Payment due date
amount_due	integer	Outstanding balance in cents
items	array	Line items (see Line item object)
notes	string	Notes printed on the invoice
bank_details	string	Bank account details for EFT payment
deposit_type	string	fixed or percentage (if applicable)
deposit_value	integer	Cents (fixed) or basis points (percentage)
deposit_amount	integer	Calculated deposit amount in cents
custom_fields	object	Key-value pairs of custom fields
vat_enabled	boolean	Whether VAT is shown on the invoice
scheduled_send_at	timestamp	When the invoice is scheduled to be sent (only present on scheduled invoices)

Line item object

Field	Type	Description
type	string	product · service · discount
name	string	Line item name
description	string	Description printed on the invoice
quantity	integer	Number of units
unit_price	integer	Price per unit in cents
vat_type	string	inclusive · exclusive · none
vat_rate	integer	VAT rate in basis points (1500 = 15%)

Discount items: set type to discount, unit_price to a negative value (e.g. -5000 for a R50 discount), quantity to 1, and vat_type to none.

Create an invoice

POST /invoice

Field	Required	Type	Description
client_id	Yes	string	ID of an existing client
invoice_date	Yes	date	Invoice issue date
due_date	Yes	date	Payment due date
items	Yes	array	At least one line item
currency	No	string	ISO 4217 code; defaults to your account currency
notes	No	string	Notes to print on the invoice
bank_details	No	string	Bank account details for EFT
deposit_type	No	string	fixed or percentage
deposit_value	No	integer	Cents (fixed) or basis points (percentage)
custom_fields	No	object	Additional key-value fields to display
scheduled_send_at	No	timestamp	ISO 8601 UTC datetime to schedule automatic email delivery (e.g. 2026-04-01T07:00:00Z). Creates the invoice with status scheduled instead of draft.

curl -X POST https://rebill-api-896466068278.africa-south1.run.app/invoice \
  -H "Authorization: Bearer sk_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "xyz789",
    "invoice_date": "2026-03-15",
    "due_date": "2026-03-30",
    "currency": "ZAR",
    "items": [
      {
        "type": "service",
        "name": "Web design",
        "description": "Homepage redesign",
        "quantity": 1,
        "unit_price": 500000,
        "vat_type": "exclusive",
        "vat_rate": 1500
      }
    ],
    "notes": "Payment due within 30 days."
  }'

Response (201 Created):

{
  "id": "abc123"
}

If scheduled_send_at is provided, the invoice is created with status scheduled and will be emailed automatically at the specified time. Otherwise it is created as draft. Fetch it by ID to get the full object including the assigned invoice number.

Update an invoice

PUT /invoice/:id

Updates an existing invoice. Accepts the same fields as create. Only draft invoices can be edited.

Delete an invoice

DELETE /invoice/:id

Permanently deletes an invoice. Only draft invoices can be deleted.

Mark an invoice as sent

POST /invoice/:id/mark_as_sent

Marks a draft invoice as sent without sending any email or WhatsApp message. Useful when you have delivered the invoice through another channel and just want to update its status.

curl -X POST https://rebill-api-896466068278.africa-south1.run.app/invoice/abc123/mark_as_sent \
  -H "Authorization: Bearer sk_your_secret_key"

Send an invoice

POST /invoice/:id/send

Sends the invoice to the client and marks it as sent. Works on draft and scheduled invoices. By default sends via email. Add ?whatsapp=true to send via WhatsApp instead (requires a WhatsApp-enabled account and sufficient credits).

# Send via email
curl -X POST https://rebill-api-896466068278.africa-south1.run.app/invoice/abc123/send \
  -H "Authorization: Bearer sk_your_secret_key"

# Send via WhatsApp
curl -X POST "https://rebill-api-896466068278.africa-south1.run.app/invoice/abc123/send?whatsapp=true" \
  -H "Authorization: Bearer sk_your_secret_key"

Cancel a scheduled invoice

POST /invoice/:id/cancel_schedule

Cancels the scheduled delivery of a scheduled invoice and reverts it to draft status. The invoice is not sent and can be edited, rescheduled, or sent manually.

curl -X POST https://rebill-api-896466068278.africa-south1.run.app/invoice/abc123/cancel_schedule \
  -H "Authorization: Bearer sk_your_secret_key"

Response (200 OK):

{
  "id": "abc123"
}

Mark an invoice as paid

POST /invoice/:id/mark_as_paid

Records a manual payment against the invoice and marks it as paid. A payment receipt email is sent to the client automatically.

Field	Required	Type	Description
received	Yes	date	Date the payment was received (YYYY-MM-DD)
method	Yes	string	Payment method (e.g. eft, cash, card, cheque)
reference	No	string	Payment reference or transaction ID

curl -X POST https://rebill-api-896466068278.africa-south1.run.app/invoice/abc123/mark_as_paid \
  -H "Authorization: Bearer sk_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "received": "2026-03-20",
    "method": "eft",
    "reference": "REF123456"
  }'

Partially paid invoices

Invoices with an existing online payment record (status paid_partial) cannot use this endpoint. Use POST /invoice/:id/capture_payment instead to record additional payments against them.