Create an invoice

POST

/invoices

const url = 'https://api.brrndops.com/v1/invoices';
const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '7f1c0f54-3a2b-4d5e-8f9a-0b1c2d3e4f5a',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: '{"currency":"NGN","customer":{"name":"Bola Ade","email":"bola@example.com"},"line_items":[{"description":"Design work","quantity":2,"unit_amount":1500000}],"tax_percent":7.5,"due_date":"2026-10-31","external_ref":"order_123","metadata":{"order_id":"123"}}'
};

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

curl --request POST \
  --url https://api.brrndops.com/v1/invoices \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: 7f1c0f54-3a2b-4d5e-8f9a-0b1c2d3e4f5a' \
  --data '{ "currency": "NGN", "customer": { "name": "Bola Ade", "email": "bola@example.com" }, "line_items": [ { "description": "Design work", "quantity": 2, "unit_amount": 1500000 } ], "tax_percent": 7.5, "due_date": "2026-10-31", "external_ref": "order_123", "metadata": { "order_id": "123" } }'

Creates an invoice. Totals are calculated for you from line_items, tax_percent and discount_percent. If you don’t pass number, the next number is assigned (INV-001, INV-002…; sandbox uses TEST-INV-001…).

Authorizations

apiKey

Parameters

Header Parameters

Idempotency-Key

string

<= 255 characters

Example

7f1c0f54-3a2b-4d5e-8f9a-0b1c2d3e4f5a

A unique string (1–255 printable ASCII characters) that makes retries safe.

Request Body^required

application/json

object

number

Must be unique in the account. Leave out to auto-number.

string

<= 64 characters

currency

required

ISO 4217. Three-decimal currencies (KWD, BHD…) aren’t supported.

string

customer

required

Who you’re billing. name is required on create.

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

Who the invoice is from. Defaults to your business details.

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

required

Array<object>

>= 1 items <= 500 items

object

description

required

string

<= 1000 characters

quantity

integer

default: 1 >= 1 <= 1000000

unit_amount

required

Price per unit in minor units.

integer

tax_percent

At most two decimal places.

number

<= 100

discount_percent

number

<= 100

issue_date

Defaults to today (UTC).

string format: date

due_date

Defaults to issue_date.

string format: date

payment_terms

string | null

<= 2000 characters

payment_details

Bank or payment instructions printed on the invoice (max 8KB).

object | null

template

string

default: 1

Allowed values: 1 2 3 4

branding

object

primary_color

string

secondary_color

string

font_family

string

<= 100 characters

logo_url

Must be https.

string | null format: uri

external_ref

Your own ID for this invoice; filter lists by it.

string | null

<= 255 characters

metadata

Up to 50 keys of your own data.

object

<= 50 properties

key

additional properties

string

<= 500 characters

status

string

default: open

Allowed values: draft open

Example

{
  "currency": "NGN",
  "customer": {
    "name": "Bola Ade",
    "email": "bola@example.com"
  },
  "line_items": [
    {
      "description": "Design work",
      "quantity": 2,
      "unit_amount": 1500000
    }
  ],
  "tax_percent": 7.5,
  "due_date": "2026-10-31",
  "external_ref": "order_123",
  "metadata": {
    "order_id": "123"
  }
}

Responses

200

The created invoice.

application/json

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

Example

{
  "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"
  }
}

402

Production key on an account without an active plan (subscription_inactive). Sandbox keys keep working.

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"
  }
}

409

invoice_number_taken, or request_in_progress when a request with the same Idempotency-Key is still running.

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"
  }
}

413

Request body over 2MB.

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"
  }
}

422

The Idempotency-Key was already used with a different request.

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"
  }
}

Create an invoice

Authorizations

Parameters

Header Parameters

Example

Request Bodyrequired

Example

Responses

200

Example

400

Example

401

Example

402

Example

403

Example

409

Example

413

Example

422

Example

Request Body^required