List invoices

GET

/invoices

const url = 'https://api.brrndops.com/v1/invoices?limit=10&starting_after=inv_8f3c0e7e-5d2a-4c1b-9f43-2c1d0a9b7e11&status=open%2Csent';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://api.brrndops.com/v1/invoices?limit=10&starting_after=inv_8f3c0e7e-5d2a-4c1b-9f43-2c1d0a9b7e11&status=open%2Csent' \
  --header 'Authorization: Bearer <token>'

Returns invoices, newest first. Deleted invoices are hidden unless you ask for status=deleted.

Authorizations

apiKey

Parameters

Query Parameters

limit

integer

default: 10 >= 1 <= 100

starting_after

string

Example

inv_8f3c0e7e-5d2a-4c1b-9f43-2c1d0a9b7e11

An invoice ID; returns the invoices after it.

status

string

Example

open,sent

Comma-separated: draft, open, sent, paid, deleted.

external_ref

string

customer_email

string format: email

Case-insensitive exact match.

created_gte

string format: date-time

created_lt

string format: date-time

Responses

200

A page of invoices.

application/json

object

object

string

Allowed value: list

url

string

data

Array<object>

object

string

object

string

Allowed value: invoice

livemode

boolean

number

string

status

string

Allowed values: draft open sent paid deleted

currency

string

customer

object

name

string | null

<= 255 characters

email

string | null format: email

phone

string | null

<= 50 characters

address

string | null

<= 1000 characters

country_code

ISO 3166-1 alpha-2

string | null

issuer

object

name

string | null

<= 255 characters

email

string | null format: email

phone

string | null

<= 50 characters

address

string | null

<= 1000 characters

country_code

ISO 3166-1 alpha-2

string | null

line_items

Array<object>

object

string

object

string

Allowed value: line_item

description

string

quantity

integer

unit_amount

integer

amount

Quantity × unit_amount.

integer

subtotal

integer

tax_percent

number

tax_amount

integer

discount_percent

number

discount_amount

integer

total

Subtotal + tax_amount − discount_amount.

integer

issue_date

string format: date

due_date

string format: date

payment_terms

string | null

payment_details

object | null

template

string

branding

object

primary_color

string

secondary_color

string

font_family

string

<= 100 characters

logo_url

Must be https.

string | null format: uri

external_ref

string | null

metadata

object

key

additional properties

string

created_at

string format: date-time

updated_at

string format: date-time

has_more

boolean

next_cursor

string | null

Example

{
  "object": "list",
  "url": "/v1/invoices",
  "data": [
    {
      "id": "inv_8f3c0e7e-5d2a-4c1b-9f43-2c1d0a9b7e11",
      "object": "invoice",
      "number": "INV-001",
      "status": "draft",
      "customer": {
        "country_code": "NG"
      },
      "issuer": {
        "country_code": "NG"
      },
      "line_items": [
        {
          "id": "li_…",
          "object": "line_item"
        }
      ],
      "branding": {
        "primary_color": "#2388ff",
        "secondary_color": "#f7f8fc"
      }
    }
  ]
}

400

The request was invalid: a missing or malformed field (param says which), an unknown field, or a rule such as a disallowed status change.

application/json

object

error

required

object

type

required

string

Allowed values: authentication_error permission_error invalid_request_error rate_limit_error quota_error api_error

code

required

string

message

required

string

param

The request field the error relates to.

string

request_id

string

Example

{
  "error": {
    "type": "authentication_error",
    "code": "parameter_missing"
  }
}

401

Missing, invalid, expired or revoked API key.

application/json

object

error

required

object

type

required

string

Allowed values: authentication_error permission_error invalid_request_error rate_limit_error quota_error api_error

code

required

string

message

required

string

param

The request field the error relates to.

string

request_id

string

Example

{
  "error": {
    "type": "authentication_error",
    "code": "parameter_missing"
  }
}

403

The key lacks the required scope (insufficient_scope), or the business isn’t verified yet (account_not_verified, production keys only).

application/json

object

error

required

object

type

required

string

Allowed values: authentication_error permission_error invalid_request_error rate_limit_error quota_error api_error

code

required

string

message

required

string

param

The request field the error relates to.

string

request_id

string

Example

{
  "error": {
    "type": "authentication_error",
    "code": "parameter_missing"
  }
}