Invoices

Methods

GET

Retrieve Single Invoice

/backend/api/v1/invoices/ID - fetch invoice with specified ID.

• Set the Accept header to application/pdf to request the PDF bill, rather than the JSON description.

List Invoices

/backend/api/v1/invoices/ - list all invoices.

/backend/api/v1/customers/ID/invoices/ - list raised invoices belonging to customer with specified ID.

By default only raised invoices are shown.

Additional Query Parameters

Parameter	Type	Required	Description
invoiceNumber	string	No	Search for an invoice by exact invoice number
unsent	flag	No	Show unsent invoices
includeUnsent	flag	No	Show all invoices, including unsent
undelivered	flag	No	Show only invoices that have not been delivered (not emailed, downloaded, printed, or marked as delivered)
minDate	date	No	Only show invoices dated on or after
maxDate	date	No	Only show invoices dated on or before
minDueDate	date	No	Only show invoices due on or after
maxDueDate	date	No	Only show invoices due on or before

Search Example:

# Find invoice by invoice number
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "/backend/api/v1/invoices?invoiceNumber=C12345/123"

Search Notes:

• The invoiceNumber parameter performs an exact match
• Invoice number format depends on system configuration
• Returns an array containing a single invoice (or empty array if not found)
• Invoice numbers are unique, so only one result is expected
• Optimised for performance using indexed fields

Note: The min/maxDate filters use the date of the invoice, and the standard createdSince filter uses the time the invoice was created in the platform. These will often be the same, but this is not guaranteed.

POST

/backend/api/v1/customers/ID/invoices/ - add a new invoice to the specified customer, the newly-added invoice will be returned.

• A default cutoffDate of the beginning of the current month will be used if no value is passed in.
• You may optionally specify a transactionCutoffDate to control non-call charge inclusion by transaction date. When set, the bill date advance/arrears mechanism does not apply to non-call charges.
• You may specify a list of transactions to include on the invoice with the _includeTransactionIDs value.

PATCH

/backend/api/v1/invoices/ID - update invoice with specified ID. The modified invoice will be returned.

DELETE

/backend/api/v1/invoices/ID - delete invoice with specified ID.

Actions

Available Actions

email

Email an invoice to the customer or other recipients. The invoice must be approved before it can be emailed.

Parameters:

• email (optional) - An array of email addresses to send the invoice to. If not provided, the invoice is sent to the email addresses on the customer record and appropriate contacts. Addresses can also be passed as comma or semicolon-separated strings.
• billStyle (optional) - The name of the invoice format to attach (e.g. “Full”).
• message (optional) - The name of the email message template to use.
• attachments (optional) - Extra documents to attach. An array of attachment names.
• invoiceUsageReportCustomerProfileID (optional) - The name of the usage report profile to include.

Example:

curl -X POST https://example.com/backend/api/v1/invoices/123?action=email \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": ["accounts@example.com", "billing@example.com"]
  }'

emailCdrs

Email the CDR (call detail record) files for an invoice. The invoice must be approved and CDR files must exist.

Parameters:

• email (optional) - An array of email addresses to send the CDRs to. If not provided, the CDRs are sent to the addresses on the generated CDR record.

Example:

curl -X POST https://example.com/backend/api/v1/invoices/123?action=emailCdrs \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": ["accounts@example.com"]
  }'

recreate

Regenerate the invoice outputs (PDF). Use this when the invoice template has changed or the original output is corrupted.

Parameters: No required parameters.

Example:

curl -X POST https://example.com/backend/api/v1/invoices/123?action=recreate \
  -H "Authorization: Bearer YOUR_API_TOKEN"

updateCallTransactions

Update the call transactions on an unsent invoice. Only works on invoices that have not yet been sent (no invoice number assigned).

Parameters: No required parameters.

Example:

curl -X POST https://example.com/backend/api/v1/invoices/123?action=updateCallTransactions \
  -H "Authorization: Bearer YOUR_API_TOKEN"

reapplyDiscountPlans

Recalculate discount plan allowances and reapply them to this invoice.

Parameters: No required parameters.

Example:

curl -X POST https://example.com/backend/api/v1/invoices/123?action=reapplyDiscountPlans \
  -H "Authorization: Bearer YOUR_API_TOKEN"

generateDownloadLink

Generate a secure, time-limited download link for an invoice. The invoice must be approved.

Parameters:

• expiryHours (optional) - How long the link stays valid, in hours. Defaults to 168 (7 days). Accepted values: 1, 6, 24, 72, 168, 336, 720.
• maxUses (optional) - Maximum number of times the link can be used. Defaults to 1, maximum 2.

Example:

curl -X POST https://example.com/backend/api/v1/invoices/123?action=generateDownloadLink \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "expiryHours": 72,
    "maxUses": 2
  }'

Response:

{
    "success": true,
    "download_url": "https://example.com/download/invoice/abc123",
    "token": "abc123",
    "expires_at": "2025-01-27T14:30:00+00:00",
    "max_uses": 2
}

linkToXero

Manually link an invoice to a Xero invoice by ID. Requires the Xero module to be active. Updating an existing link requires expert level 5.

Parameters:

• xeroID (required) - The Xero Invoice ID in UUID format (e.g. 00000000-0000-0000-0000-000000000000).

Example:

curl -X POST https://example.com/backend/api/v1/invoices/123?action=linkToXero \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "xeroID": "550e8400-e29b-41d4-a716-446655440000"
  }'

unlinkFromXero

Remove the link between an invoice and Xero. Requires the Xero module to be active and expert level 5. The invoice in Xero is not affected.

Parameters: No required parameters.

Example:

curl -X POST https://example.com/backend/api/v1/invoices/123?action=unlinkFromXero \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response Format

Actions return a JSON response. Most actions return the updated invoice object, except:

• email and emailCdrs return {"success": true, "message": "..."} on success
• generateDownloadLink returns the download URL, token, expiry, and max uses

Error Handling

If an action fails, the API returns an appropriate HTTP status code with error details:

{
    "error": "Invalid Action",
    "error_code": 400502,
    "hint": "The action was not performed"
}

Common error codes:

• 400501 - Action not recognised
• 400502 - Action failed
• 400503 - Missing required parameters
• 400701 - Recreate failed
• 400702 - Invalid email address
• 400703 - Unknown bill style
• 400704 - Unknown message template
• 400705 - Unknown attachment
• 400706 - Unknown usage report profile
• 400707 - No CDRs available for this invoice
• 403xxx - Permission denied
• 500601 - Email sending failed
• 500602 - CDR email sending failed
• 500701 - Download link generation failed

Fields

Field	Name	Type	Description
invoiceNumber	Invoice Number	Text	The unique invoice number displayed on the invoice document
billingRun	Billing Run	Preset Value	The billing run that generated this invoice
invoiceDate	Invoice Date	Date	The date when the invoice was created
cutoffDate	Cut-off Date	Date	The call cut-off date for charges included in this invoice
transactionCutoffDate	Transaction Cut-off Date	Date	Optional non-call cutoff date for charges included in this invoice by transaction date
dueDate	Due Date	Date	The date by which payment for this invoice is due
paidDate	Paid Date	Date	Date when the invoice was fully paid
paymentMethod	Payment Method	Preset Value	The method of payment for this invoice (defaults to customer method if not specified)
invoiceAmount	Invoice Amount	Currency	The net amount of the invoice before VAT
invoiceVAT	VAT Amount	Currency	The VAT amount applied to this invoice
invoiceReverseVAT	Reverse VAT Amount	Currency	The reverse charge VAT amount for this invoice
total	Total	Currency	The total amount of the invoice including VAT
paidAmount	Paid Amount	Currency	The amount that has been paid against this invoice
outstanding	Outstanding	Currency	Amount still to be paid on this invoice
invoiceCallCount	Calls	Number	Number of calls billed on this invoice (from transaction summaries)
invoiceCallMinutes	Minutes	Number	Total minutes (rounded to whole minutes) billed on this invoice (from transaction summaries)
invoiceChargesOneOff	One-Off Charges	Currency	Total one-off charges billed on this invoice
invoiceChargesRecurring	Recurring Charges	Currency	Total recurring charges billed on this invoice
invoiceChargesCalls	Call Charges	Currency	Total call charges billed on this invoice
invoiceChargesRefunds	Refunds	Currency	Total refunds billed on this invoice
invoiceChargesLate	Late Fees	Currency	Total late fees billed on this invoice
invoiceChargesInterest	Interest	Currency	Total interest charges billed on this invoice
invoiceChargesCarrierProvided	Carrier Provided Charges	Currency	Total carrier provided charges billed on this invoice
invoiceChargesManualBilling	Manual Billing Fees	Currency	Total manual billing fees billed on this invoice
invoiceChargesLowUsage	Low Usage Fees	Currency	Total low usage fees billed on this invoice
invoiceChargesManual	Manual Charges	Currency	Total manual charges billed on this invoice
invoiceChargesNonCall	Non-Call Charges	Currency	Total non-call charges billed on this invoice
status	Status Flags	Preset Value(s)	Array of status flags currently active for this invoice
billStyle	Bill Style	Preset Value	The style template used for rendering this invoice
invoiceMessage	Invoice Message	Preset Value	Message to display on the invoice
invoiceUsageReportCustomerProfile	Invoice Usage Report	Preset Value	Profile controlling how usage details are reported alongside the invoice
customerReference	Customer Reference	Text	Customer-provided reference to appear on the invoice
purchaseOrderNumber	Purchase Order Number	Text	Customer purchase order number to appear on the invoice
onlineBillType	Online Bill	Preset Value	Name of the bill type to generate for online viewing
emailBillType	Email Bill	Preset Value	Name of the bill type to generate for email delivery
postBillType	Post Bill	Preset Value	Name of the bill type to generate for postal delivery
faxBillType	Fax Bill	Preset Value	Name of the bill type to generate for fax delivery
id	Invoice ID	Text	The unique identifier for this invoice
customerID	Customer	Text	The ID of the customer this invoice is for
billTypes	Bill Types	Preset Value(s)	Types of bills to include with this invoice