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

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": ["[email protected]", "[email protected]"]
  }'

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": ["[email protected]"]
  }'

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