Billing

Get invoices

GET /v2/billing/invoices Bearer token

This endpoint retrieves invoice data for specified invoice IDs, with options for PDF/CSV export and filtering by status.

Request

Method: GET URL: https://api.sandbox.bobpay.co.za/v2/billing/invoices

Query parameters

Key Description Type Required
id Filter for a specific invoice ID. integer Conditional (if pdf=true)
ids A comma-separated list or array of invoice IDs to retrieve. integer or array No
account_id The unique identifier of the account whose invoices are being requested. integer No
pdf Boolean flag to return a PDF download link instead of the invoice data. Only takes effect when id is specified. boolean No
start_date Start date for the time period (format: YYYY-MM-DD HH:MM:SS). string (date/time) No
end_date End date for the time period (format: YYYY-MM-DD HH:MM:SS). string (date/time) No
status Filter invoices by their payment status (paid, partially-paid, unpaid). string No
csv Boolean flag. If true, the CSV is generated in the background and emailed to the authenticated user. boolean No

Response

Status code: 200 OK Content-Type: application/json

Response body (download PDF URL)

{
    "invoices": null,
    "download_url": {
        "url": "https://payments-backend-dev-infra-billing.s3.af-south-1.amazonaws.com/pdfs/invoice_108.pdf?...",
        "filename": "pdfs/invoice_108.pdf",
        "bucket": "payments-backend-dev-infra-billing",
        "file_size": 57925
    },
    "count": 1
}

Response fields

Key Description Type
invoices An array containing the retrieved invoice objects, or null when a PDF is requested. array of objects
id The unique identifier for the invoice. integer
account_id The account associated with the invoice. integer
invoice_date The date the invoice was issued. string (datetime)
sub_total The subtotal amount before VAT/tax. float
vat The VAT amount charged. float
vat_percentage The VAT percentage rate applied. float
total_amount The total amount of the invoice. float
outstanding_amount The outstanding (unpaid) amount on the invoice. float
status The payment status of the invoice (paid, partially-paid, unpaid). string
time_created Timestamp when the invoice was created. string (datetime)
time_modified Timestamp when the invoice was last modified. string (datetime)
metadata Object containing additional information (issuer details, billing info, etc). object
invoice_items Array of items included in the invoice. array of objects
payment_date The date and time the invoice was paid. string (datetime)
validated Additional validation status or information. string
download_url Object containing download link and metadata if pdf=true. object
count The total number of invoices returned in the response. integer

Note:

  • The metadata object contains issuer, account, and billing info, while invoice_items lists each billed item and its details.
  • When requesting a PDF (pdf=true), the download_url object is returned in place of the invoices array.
View as Markdown