Billing

GET /billing/invoices lists the invoices Venly has issued to your company. It needs the view:billing scope, which is separate from everything else because the figures are commercially sensitive — ask Venly to grant it to the credential or dashboard user that needs it. Invoices never show the rates behind a charge; for those, contact Venly.

curl https://api-staging.venlyfinance.com/v1/billing/invoices \
  -H "Authorization: Bearer {access_token}"

Response (200)

{
  "success": true,
  "result": {
    "content": [
      {
        "id": "7f68c0d4-4d55-4bd8-9b0e-1cfb0255c554",
        "invoiceNumber": "INV-042",
        "status": "SENT",
        "paymentStatus": "PAID",
        "currency": "EUR",
        "netTotal": "1250.00",
        "totalTax": "262.50",
        "grossTotal": "1512.50",
        "issueDate": "2026-09-01",
        "dueDate": "2026-09-15",
        "billingPeriodStart": "2026-08-01",
        "billingPeriodEnd": "2026-08-31",
        "sequenceUrl": "https://billing.example.com/invoices/7f68c0d4-4d55-4bd8-9b0e-1cfb0255c554",
        "createdAt": "2026-09-01T06:00:00Z"
      }
    ],
    "pagination": { "size": 100, "hasNextPage": false, "hasPreviousPage": false }
  }
}

Invoices are read live from our billing system — Finance stores none. Only issued invoices (status: SENT) are visible; drafts and voided invoices are not. paymentStatus is the separate collection status: UNPAID, PARTIALLY_PAID, PAID or UNCOLLECTIBLE. sequenceUrl is Venly’s internal reference to the invoice, not a page you can open. To read your invoices, open the billing portal at billingUrl on your company profile, or download the PDF.

Two things that differ from other list endpoints

Cursor pagination. There is no page/size envelope. Send pagination.nextPageCursor or previousPageCursor back exactly as received; never construct one. A stale cursor is 400 invalid-cursor — restart from the first page.
422 billing-not-configured until Venly links your company to a billing customer. Once linked, a company with no invoices yet gets an empty content.

The PDF

GET /billing/invoices/{invoiceId}/download returns raw PDF bytes — not the JSON envelope — with a Content-Disposition filename derived from the invoice number. Errors still arrive as JSON. A 404 always means the invoice is not yours to read. An invoice you can read whose PDF cannot be produced is 500 billing-provider-error, so a rendering fault is never mistaken for a wrong id.

Errors

HTTP	`code`	Meaning
`400`	`invalid-cursor`	The cursor is stale or malformed; restart from the first page
`403`	`forbidden`	The token lacks `view:billing`
`404`	`invoice-not-found`	Unknown, foreign, unsent or voided invoice
`422`	`billing-not-configured`	Your company is not linked to a billing customer yet
`500`	`billing-provider-error`	The billing system rejected the request or could not render the PDF
`503`	`billing-provider-unavailable`	The billing system was unreachable. Retry

Next steps

List invoices

The endpoint reference, with every field.

Your company profile

Where billingUrl — your billing portal — lives.

Overview

Recipes

Onboarding & Verification

Core Concepts

Parties

Accounts

Virtual Bank Accounts

Supported Assets

Wallets

Transfers

Fiat to Crypto Payment Sessions

Pay-Ins

Payout Bank Accounts

Payout Routes

Payouts

Permits

Allowances

Webhooks

API Credentials

Company

Reference

Billing

Two things that differ from other list endpoints

The PDF

Errors

Next steps

List invoices

Your company profile

​Two things that differ from other list endpoints

​The PDF

​Errors

​Next steps

List invoices

Your company profile

Two things that differ from other list endpoints

The PDF

Errors

Next steps