BiasDocs

Credit notes

A credit note lowers what a customer owes or paid on an invoice, for example to refund part of a bill or correct an overcharge. Its line items describe what’s credited. The invoicing guide covers how its amounts are settled.

The CreditNote object

Name
object
Type
"credit_note",
Description
The object's type.
Name
id
Type
string,
Description
Unique identifier for the object.
Name
live
Type
boolean,
Description
true if the object is live, or false if it's in a sandbox.
Name
created_at
Type
integer,
Description
When the object was created, in milliseconds since the Unix epoch.
Name
credit_amount
Type
integer,
Description
The part added to the customer's balance.
Name
customer
Type
string or Customer,
Description
Expandable. The customer of the credited invoice.
Name
invoice
Type
string or Invoice,
Description
Expandable. The invoice this credit note credits.
Name
line_items
Type
array of object or null,
Description
Expandable. The line items included in this credit note.
Properties
Name
memo
Type
string or null,
Description
A memo shown in the credit note email.
Name
metadata
Type
object,
Description
Your own key-value data on the object.
Name
out_of_band_amount
Type
integer,
Description
The part settled outside Bias.
Name
pre_payment_amount
Type
integer,
Description
The part that lowers what's owed on the invoice.
Name
reason
Type
enum,
Description
Why the credit note was issued.
Properties
Name
refund_amount
Type
integer,
Description
The part refunded to the invoice's payments.
Name
refunds
Type
array of object,
Description
The refunds that settle refund_amount.
Properties
Name
status
Type
enum,
Description
The status of the credit note.
Properties
Name
subtotal
Type
integer,
Description
The sum of the line items' subtotals, before tax.
Name
tax_total
Type
integer,
Description
The tax credited.
Name
total
Type
integer,
Description
The total credited, including taxes. Sum of pre_payment_amount, refund_amount, credit_amount and out_of_band_amount.
Name
updated_at
Type
integer,
Description
When the object was last updated, in milliseconds since the Unix epoch.

The CreditNote object

{
  "object": "credit_note",
  "live": false,
  "id": "cn_hxUznDJdC6eOs4OcqeVP83",
  "created_at": 1750000000000,
  "updated_at": 1750000000000,
  "invoice": "inv_2bA3FSNtE8Qmpg2ufwPmC2",
  "customer": "cus_aB4DEXqbFGOlpEOxwp0Fx1",
  "status": "issued",
  "reason": "other",
  "line_items": [
    {
      "object": "credit_note_line_item",
      "id": "cnli_GHkHeA2p80fum3yG9mbpc3",
      "name": "Refund: consulting",
      "description": null,
      "unit_amount": 10000,
      "quantity": 1,
      "taxes": [
        {
          "percentage": 8.75,
          "display_name": "CA Sales Tax"
        }
      ],
      "tax_amounts": [
        {
          "amount": 875,
          "taxable_amount": 10000,
          "display_name": "CA Sales Tax",
          "percentage": 8.75
        }
      ],
      "line_item": null,
      "period": null,
      "subtotal": 10000,
      "total": 10875
    }
  ],
  "subtotal": 10000,
  "tax_total": 875,
  "total": 10875,
  "pre_payment_amount": 10875,
  "refund_amount": 0,
  "credit_amount": 0,
  "out_of_band_amount": 0,
  "refunds": [],
  "memo": null,
  "metadata": {}
}

The CreditNoteLineItem object

A credit note’s line_items are the amounts it credits. They’re set when creating or updating the credit note.

Name
object
Type
"credit_note_line_item",
Description
The object's type.
Name
id
Type
string,
Description
Unique identifier for the object.
Name
description
Type
string or null,
Description
The line's description.
Name
line_item
Type
string or null,
Description
The invoice line item this line credits, if any.
Name
name
Type
string,
Description
The line's display name.
Name
period
Type
object or null,
Description
The period of service the line credits, if any.
Properties
Name
quantity
Type
number,
Description
The quantity credited.
Name
subtotal
Type
integer,
Description
unit_amount × quantity, before tax.
Name
tax_amounts
Type
array of object,
Description
The tax credited on the line.
Properties
Name
taxes
Type
array of objects,
Description
The tax rates applied to the line.
Properties
Name
total
Type
integer,
Description
The line's total in cents, with tax.
Name
unit_amount
Type
integer,
Description
The unit amount credited in cents, before tax.

The CreditNoteLineItem object

{
  "object": "credit_note_line_item",
  "id": "cnli_GHkHeA2p80fum3yG9mbpc3",
  "name": "Refund: consulting",
  "description": null,
  "unit_amount": 10000,
  "quantity": 1,
  "taxes": [
    {
      "percentage": 8.75,
      "display_name": "CA Sales Tax"
    }
  ],
  "tax_amounts": [
    {
      "amount": 875,
      "taxable_amount": 10000,
      "display_name": "CA Sales Tax",
      "percentage": 8.75
    }
  ],
  "line_item": null,
  "period": null,
  "subtotal": 10000,
  "total": 10875
}

Get a credit note

Retrieve a credit note by its ID.

Required parameters

Name
id
Type
string,
Description
The ID of the credit note to retrieve.

Optional parameters

Name
expand
Type
object,
Properties

Returns

Returns the credit note object.

Get a credit note

const creditNote = await bias.creditNotes.get("id");

Response example

{
  "object": "credit_note",
  "live": false,
  "id": "cn_hxUznDJdC6eOs4OcqeVP83",
  "created_at": 1750000000000,
  "updated_at": 1750000000000,
  "invoice": "inv_2bA3FSNtE8Qmpg2ufwPmC2",
  "customer": "cus_aB4DEXqbFGOlpEOxwp0Fx1",
  "status": "issued",
  "reason": "other",
  "line_items": [
    {
      "object": "credit_note_line_item",
      "id": "cnli_GHkHeA2p80fum3yG9mbpc3",
      "name": "Refund: consulting",
      "description": null,
      "unit_amount": 10000,
      "quantity": 1,
      "taxes": [
        {
          "percentage": 8.75,
          "display_name": "CA Sales Tax"
        }
      ],
      "tax_amounts": [
        {
          "amount": 875,
          "taxable_amount": 10000,
          "display_name": "CA Sales Tax",
          "percentage": 8.75
        }
      ],
      "line_item": null,
      "period": null,
      "subtotal": 10000,
      "total": 10875
    }
  ],
  "subtotal": 10000,
  "tax_total": 875,
  "total": 10875,
  "pre_payment_amount": 10875,
  "refund_amount": 0,
  "credit_amount": 0,
  "out_of_band_amount": 0,
  "refunds": [],
  "memo": null,
  "metadata": {}
}

List all credit notes

Retrieve a paginated list of credit notes, most recently created first.

Optional parameters

Name
expand
Type
object,
Description
Related objects to expand in the response.
Properties
Name
ending_before
Type
string,
Description
The ID of the object to list before, for pagination.
Name
starting_after
Type
string,
Description
The ID of the object to list after, for pagination.
Name
limit
Type
integer, at least 1, at most 1000, default is 50
Description
The maximum number of objects to return, from 1 to 1000. Defaults to 50.
Name
filters
Type
object, object, or object,
Description
Filters for the list, combined with and and or.
Properties

Returns

Returns a list of credit note objects.

List all credit notes

const creditNote = await bias.creditNotes.list();

Response example

{
  "object": "list",
  "items": [
    {
      "object": "credit_note",
      "live": false,
      "id": "cn_hxUznDJdC6eOs4OcqeVP83",
      "created_at": 1750000000000,
      "updated_at": 1750000000000,
      "invoice": "inv_2bA3FSNtE8Qmpg2ufwPmC2",
      "customer": "cus_aB4DEXqbFGOlpEOxwp0Fx1",
      "status": "issued",
      "reason": "other",
      "line_items": [
        {
          "object": "credit_note_line_item",
          "id": "cnli_GHkHeA2p80fum3yG9mbpc3",
          "name": "Refund: consulting",
          "description": null,
          "unit_amount": 10000,
          "quantity": 1,
          "taxes": [
            {
              "percentage": 8.75,
              "display_name": "CA Sales Tax"
            }
          ],
          "tax_amounts": [
            {
              "amount": 875,
              "taxable_amount": 10000,
              "display_name": "CA Sales Tax",
              "percentage": 8.75
            }
          ],
          "line_item": null,
          "period": null,
          "subtotal": 10000,
          "total": 10875
        }
      ],
      "subtotal": 10000,
      "tax_total": 875,
      "total": 10875,
      "pre_payment_amount": 10875,
      "refund_amount": 0,
      "credit_amount": 0,
      "out_of_band_amount": 0,
      "refunds": [],
      "memo": null,
      "metadata": {}
    }
  ],
  "has_more": true
}

Create a credit note

A credit note on a draft, open or paid invoice lowers what the customer owes, or refunds or credits what they paid. Its refund_amount is refunded right away.

For a credit note on an open invoice, Bias emails the customer, unless Credit notes is off in Settings → Customer emails.

Required parameters

Name
invoice
Type
string,
Description
The invoice this credit note credits.
Name
line_items
Type
array of object or object,
Description
The line items for this credit note.
Properties

Optional parameters

Name
expand
Type
object,
Properties
Name
reason
Type
enum,
Description
Why the credit note is issued. Defaults to other.
Properties
Name
refund_amount
Type
integer, at least 0,
Description
The part to refund to the invoice's payments, newest first. Any part that can't be refunded becomes credit.
Name
credit_amount
Type
integer, at least 0,
Description
The part to add to the customer's balance.
Name
out_of_band_amount
Type
integer, at least 0,
Description
The part settled outside Bias.
Name
default_taxes
Type
array of objects,
Description
The taxes applied to line items without their own.
Properties
Name
memo
Type
string or null,
Description
A memo shown in the credit note email.
Name
metadata
Type
object or null,
Description
Your own key-value data on the object.

Returns

Returns the credit note object.

Create a credit note

const creditNote = await bias.creditNotes.create({
  invoice: "inv_2bA3FSNtE8Qmpg2ufwPmC2",
  line_items: [
    {
      name: "Refund: consulting",
      unit_amount: 10000,
      quantity: 1,
      taxes: [
        {
          percentage: 8.75,
          display_name: "CA Sales Tax"
        }
      ]
    }
  ]
});

Response example

{
  "object": "credit_note",
  "live": false,
  "id": "cn_hxUznDJdC6eOs4OcqeVP83",
  "created_at": 1750000000000,
  "updated_at": 1750000000000,
  "invoice": "inv_2bA3FSNtE8Qmpg2ufwPmC2",
  "customer": "cus_aB4DEXqbFGOlpEOxwp0Fx1",
  "status": "issued",
  "reason": "other",
  "line_items": [
    {
      "object": "credit_note_line_item",
      "id": "cnli_GHkHeA2p80fum3yG9mbpc3",
      "name": "Refund: consulting",
      "description": null,
      "unit_amount": 10000,
      "quantity": 1,
      "taxes": [
        {
          "percentage": 8.75,
          "display_name": "CA Sales Tax"
        }
      ],
      "tax_amounts": [
        {
          "amount": 875,
          "taxable_amount": 10000,
          "display_name": "CA Sales Tax",
          "percentage": 8.75
        }
      ],
      "line_item": null,
      "period": null,
      "subtotal": 10000,
      "total": 10875
    }
  ],
  "subtotal": 10000,
  "tax_total": 875,
  "total": 10875,
  "pre_payment_amount": 10875,
  "refund_amount": 0,
  "credit_amount": 0,
  "out_of_band_amount": 0,
  "refunds": [],
  "memo": null,
  "metadata": {}
}

Update a credit note

An issued credit note’s memo and metadata can change. Its line items can change only while it lowers what’s owed on a draft or open invoice.

Required parameters

Name
id
Type
string,

Optional parameters

Name
expand
Type
object,
Properties
Name
line_items
Type
array of object or object,
Description
The line items for this credit note. Replaces all existing line items.
Properties
Name
default_taxes
Type
array of objects,
Description
The taxes applied to line items without their own.
Properties
Name
memo
Type
string or null,
Description
A memo shown in the credit note email.
Name
metadata
Type
object or null,
Description
Your own key-value data on the object.

Returns

Returns the credit note object.

Update a credit note

const creditNote = await bias.creditNotes.update("id", {
  memo: "Updated credit note memo"
});

Response example

{
  "object": "credit_note",
  "live": false,
  "id": "cn_hxUznDJdC6eOs4OcqeVP83",
  "created_at": 1750000000000,
  "updated_at": 1750000000000,
  "invoice": "inv_2bA3FSNtE8Qmpg2ufwPmC2",
  "customer": "cus_aB4DEXqbFGOlpEOxwp0Fx1",
  "status": "issued",
  "reason": "other",
  "line_items": [
    {
      "object": "credit_note_line_item",
      "id": "cnli_GHkHeA2p80fum3yG9mbpc3",
      "name": "Refund: consulting",
      "description": null,
      "unit_amount": 10000,
      "quantity": 1,
      "taxes": [
        {
          "percentage": 8.75,
          "display_name": "CA Sales Tax"
        }
      ],
      "tax_amounts": [
        {
          "amount": 875,
          "taxable_amount": 10000,
          "display_name": "CA Sales Tax",
          "percentage": 8.75
        }
      ],
      "line_item": null,
      "period": null,
      "subtotal": 10000,
      "total": 10875
    }
  ],
  "subtotal": 10000,
  "tax_total": 875,
  "total": 10875,
  "pre_payment_amount": 10875,
  "refund_amount": 0,
  "credit_amount": 0,
  "out_of_band_amount": 0,
  "refunds": [],
  "memo": null,
  "metadata": {}
}

Void a credit note

Voiding undoes a credit note. Its credit comes off the customer’s balance, so credit they already used becomes an amount they owe. A credit note that refunded payments can’t be voided.

Required parameters

Name
id
Type
string,

Returns

Returns the credit note object.

Void a credit note

const creditNote = await bias.creditNotes.void("id");

Response example

{
  "object": "credit_note",
  "live": false,
  "id": "cn_hxUznDJdC6eOs4OcqeVP83",
  "created_at": 1750000000000,
  "updated_at": 1750000000000,
  "invoice": "inv_2bA3FSNtE8Qmpg2ufwPmC2",
  "customer": "cus_aB4DEXqbFGOlpEOxwp0Fx1",
  "status": "issued",
  "reason": "other",
  "line_items": [
    {
      "object": "credit_note_line_item",
      "id": "cnli_GHkHeA2p80fum3yG9mbpc3",
      "name": "Refund: consulting",
      "description": null,
      "unit_amount": 10000,
      "quantity": 1,
      "taxes": [
        {
          "percentage": 8.75,
          "display_name": "CA Sales Tax"
        }
      ],
      "tax_amounts": [
        {
          "amount": 875,
          "taxable_amount": 10000,
          "display_name": "CA Sales Tax",
          "percentage": 8.75
        }
      ],
      "line_item": null,
      "period": null,
      "subtotal": 10000,
      "total": 10875
    }
  ],
  "subtotal": 10000,
  "tax_total": 875,
  "total": 10875,
  "pre_payment_amount": 10875,
  "refund_amount": 0,
  "credit_amount": 0,
  "out_of_band_amount": 0,
  "refunds": [],
  "memo": null,
  "metadata": {}
}