Skip to content
Brrndops Docs

Update an invoice

PATCH
/invoices/{id}
curl --request PATCH \
  --url https://api.brrndops.com/v1/invoices/inv_8f3c0e7e-5d2a-4c1b-9f43-2c1d0a9b7e11 \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: 7f1c0f54-3a2b-4d5e-8f9a-0b1c2d3e4f5a' \
  --data '{ "status": "paid" }'

Updates only the fields you send. Sending line_items replaces all line items. In metadata, set a key to "" to remove it.

Status can move draft → open → sent → paid (and open → paid). Use DELETE to delete, and POST /invoices/{id}/send to email it. Changing currency requires sending line_items too.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters”
id
required
string
Example
inv_8f3c0e7e-5d2a-4c1b-9f43-2c1d0a9b7e11

Header Parameters

Section titled “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 Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
number

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

string
<= 64 characters
currency

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

string
customer

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
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
Allowed values: draft open sent paid
Example
{
  "status": "paid"
}

Responses

Section titled “ Responses ”

200

Section titled “200”

The updated invoice.

Media typeapplication/json
object
id
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
id
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

Section titled “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.

Media typeapplication/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

Section titled “401”

Missing, invalid, expired or revoked API key.

Media typeapplication/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

Section titled “403”

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

Media typeapplication/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"
  }
}

404

Section titled “404”

No such resource in this account and environment.

Media typeapplication/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

Section titled “409”

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

Media typeapplication/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

Section titled “422”

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

Media typeapplication/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"
  }
}