Invoices API

The Invoices API provides full CRUD operations for managing customer invoices, including automatic generation from dossier revenue lines, finalization, and PDF download.

Required Scope: invoices:read, invoices:write, invoices:delete

List Invoices

Retrieve a paginated list of invoices with optional filters.


GET /api/v1/invoices

Query Parameters

Parameter	Type	Description
`status`	string	Filter by status: `draft`, `finalized`, `sent`, `paid`
`customer_code`	string	Filter by customer code
`invoice_number`	string	Filter by invoice number (partial match)
`dossier_id`	integer	Filter by dossier ID
`payment_term_group`	string	Filter by group: `handling`, `duties`, `disbursements`
`invoice_date_from`	date	Filter invoices on or after this date (`YYYY-MM-DD`)
`invoice_date_to`	date	Filter invoices on or before this date (`YYYY-MM-DD`)
`search`	string	Search across invoice number, customer code, notes
`sort`	string	Sort field: `id`, `invoice_number`, `invoice_date`, `due_date`, `status`, `total`, `customer_code`, `created_at` (default: `created_at`)
`direction`	string	Sort direction: `asc` or `desc` (default: `desc`)
`page`	integer	Page number (default: 1)
`per_page`	integer	Results per page (default: 25, max: 100)

Example Request


curl https://app.borderbolt.com/api/v1/invoices \
  -H "Authorization: Bearer {token}" \
  -G \
  --data-urlencode "status=sent" \
  --data-urlencode "customer_code=CUST001"

Example Response


{
  "data": [
    {
      "id": 4001,
      "invoice_number": "INV-2026-001",
      "customer_code": "CUST001",
      "status": "sent",
      "invoice_date": "2026-03-25",
      "due_date": "2026-04-24",
      "subtotal": 2500.00,
      "vat_amount": 525.00,
      "total": 3025.00,
      "currency": "EUR",
      "created_at": "2026-03-25T10:00:00.000000Z",
      "finalized_at": "2026-03-25T11:00:00.000000Z",
      "sent_at": "2026-03-25T12:00:00.000000Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 4,
    "per_page": 25,
    "total": 78
  }
}

Get Invoice

Retrieve a single invoice with all line items.


GET /api/v1/invoices/{id}


curl https://app.borderbolt.com/api/v1/invoices/4001 \
  -H "Authorization: Bearer {token}"

Example Response


{
  "data": {
    "id": 4001,
    "invoice_number": "INV-2026-001",
    "customer_code": "CUST001",
    "status": "sent",
    "invoice_date": "2026-03-25",
    "due_date": "2026-04-24",
    "payment_term_group": "handling",
    "currency": "EUR",
    "notes": "Thank you for your business",
    "lines": [
      {
        "id": 301,
        "description": "Customs clearance service - March 2026",
        "quantity": 5,
        "unit_price": 100.00,
        "vat_rate": 21.00,
        "vat_amount": 105.00,
        "amount": 500.00
      }
    ],
    "subtotal": 2500.00,
    "vat_amount": 525.00,
    "total": 3025.00,
    "created_at": "2026-03-25T10:00:00.000000Z",
    "finalized_at": "2026-03-25T11:00:00.000000Z",
    "sent_at": "2026-03-25T12:00:00.000000Z",
    "paid_at": null
  }
}

Create Invoice

Create a new invoice in draft status.


POST /api/v1/invoices

Request Body

Field	Required	Type	Description
`customer_code`	Yes	string	Customer code
`dossier_id`	No	integer	Link to a specific dossier
`payment_term_group`	No	string	`handling`, `duties`, or `disbursements` (default: `handling`)
`payment_term_days`	No	integer	Payment term in days (default: 30)
`notes`	No	string	Invoice notes/footer

Example Request


curl -X POST https://app.borderbolt.com/api/v1/invoices \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_code": "CUST001",
    "dossier_id": 3001,
    "payment_term_group": "handling",
    "payment_term_days": 30,
    "notes": "Thank you for your business"
  }'

Example Response


{
  "data": {
    "id": 4002,
    "invoice_number": null,
    "status": "draft",
    "customer_code": "CUST001",
    "created_at": "2026-03-25T14:00:00.000000Z"
  },
  "message": "Invoice created successfully"
}

HTTP 201 is returned on success.

Draft Invoices: Draft invoices don’t have an invoice number until finalized.

Update Invoice

Update a draft invoice. Only notes, due_date, and payment_term_group can be changed.


PUT /api/v1/invoices/{id}

Request Body

Field	Required	Type	Description
`notes`	No	string	Invoice notes
`due_date`	No	date	Override due date (`YYYY-MM-DD`)
`payment_term_group`	No	string	`handling`, `duties`, `disbursements`


curl -X PUT https://app.borderbolt.com/api/v1/invoices/4002 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "notes": "Updated notes",
    "due_date": "2026-04-30"
  }'

Only draft invoices can be updated.

Delete Invoice

Delete a draft invoice.


DELETE /api/v1/invoices/{id}


curl -X DELETE https://app.borderbolt.com/api/v1/invoices/4002 \
  -H "Authorization: Bearer {token}"

Only draft invoices can be deleted.

Invoice Lines

Add Line

Add a line to a draft invoice.


POST /api/v1/invoices/{id}/lines

Request Body

Field	Required	Type	Description
`description`	Yes	string	Line description (max 255 chars)
`quantity`	Yes	number	Quantity (min 0.01)
`unit_price`	Yes	number	Unit price (min 0)
`vat_rate`	No	number	VAT percentage (default: 21.00)
`billable_item_id`	No	integer	Link to a billable item


curl -X POST https://app.borderbolt.com/api/v1/invoices/4002/lines \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Transit handling fee",
    "quantity": 2,
    "unit_price": 150.00,
    "vat_rate": 21.00
  }'

HTTP 201 is returned on success.

Update Line


PUT /api/v1/invoices/{id}/lines/{lineId}


curl -X PUT https://app.borderbolt.com/api/v1/invoices/4002/lines/301 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "unit_price": 160.00
  }'

Delete Line


DELETE /api/v1/invoices/{id}/lines/{lineId}


curl -X DELETE https://app.borderbolt.com/api/v1/invoices/4002/lines/301 \
  -H "Authorization: Bearer {token}"

Finalize Invoice

Finalize a draft invoice, assigning an invoice number and locking it from further edits.


POST /api/v1/invoices/{id}/finalize


curl -X POST https://app.borderbolt.com/api/v1/invoices/4002/finalize \
  -H "Authorization: Bearer {token}"

Example Response


{
  "data": {
    "id": 4002,
    "invoice_number": "INV-2026-002",
    "status": "finalized",
    "subtotal": 600.00,
    "vat_amount": 126.00,
    "total": 726.00,
    "finalized_at": "2026-03-25T15:00:00.000000Z"
  },
  "message": "Invoice finalized successfully"
}

Irreversible: Once finalized, invoices cannot be edited or deleted.

Mark as Sent

Mark a finalized invoice as sent to the customer.


POST /api/v1/invoices/{id}/mark-sent


curl -X POST https://app.borderbolt.com/api/v1/invoices/4002/mark-sent \
  -H "Authorization: Bearer {token}"

Mark as Paid

Mark a finalized invoice as paid.


POST /api/v1/invoices/{id}/mark-paid

Request Body

Field	Required	Type	Description
`payment_reference`	No	string	Bank/payment reference (max 255 chars)


curl -X POST https://app.borderbolt.com/api/v1/invoices/4002/mark-paid \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_reference": "BANK-REF-12345"
  }'

Generate from Dossier

Generate invoices from all pending (uninvoiced) revenue lines in a dossier. May produce multiple invoices if lines span different payment term groups.


POST /api/v1/invoices/generate-for-dossier

Request Body

Field	Required	Type	Description
`dossier_id`	Yes	integer	Dossier ID


curl -X POST https://app.borderbolt.com/api/v1/invoices/generate-for-dossier \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "dossier_id": 3001
  }'

Example Response


{
  "data": [
    {
      "id": 4003,
      "invoice_number": null,
      "status": "draft",
      "customer_code": "CUST001"
    }
  ],
  "message": "1 invoice(s) generated"
}

HTTP 201 is returned on success. HTTP 422 is returned if there are no pending lines.

Preview Dossier Generation

Preview what would be included in generated invoices before actually generating them.


POST /api/v1/invoices/preview-for-dossier

Request Body

Field	Required	Type	Description
`dossier_id`	Yes	integer	Dossier ID


curl -X POST https://app.borderbolt.com/api/v1/invoices/preview-for-dossier \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "dossier_id": 3001
  }'

Download PDF

Download a finalized invoice as PDF.


GET /api/v1/invoices/{id}/pdf


curl https://app.borderbolt.com/api/v1/invoices/4001/pdf \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/pdf" \
  --output INV-2026-001.pdf

Returns a PDF binary (Content-Type: application/pdf).

Only finalized invoices can be downloaded as PDF.

Status Workflow

Status	Description	Allowed Next Actions
`draft`	Editable, no invoice number	finalize, update, delete, add/edit/delete lines
`finalized`	Locked, invoice number assigned	mark-sent, mark-paid, pdf
`sent`	Sent to customer	mark-paid, pdf
`paid`	Payment received	—

Next Steps

Dossiers API — Manage dossiers and revenue lines
Customers API — Customer master data