Guides
System Status

Credit memos

A credit memo is an adjustment on the amount owed by a customer.

In a credit memo, you can add credit memo line items to record details about a credit you want to apply for an individual good or service. In addition, you can apply credit memos to invoices.

See the /v3/credit-memos API for more information about the complete list of credit memo operations.

Create a credit memo

In your POST /v3/credit-memos request, set the required fields.

FieldDescription
customerIdBILL-generated ID of the customer. The value begins with 0cu.
referenceNumberUser-generated credit memo number. This value can be in your chosen number scheme.
creditDateCredit memo issued date. This value is in the yyyy-MM-dd format.
creditMemoLineItemsIn the creditMemoLineItems array, set the required information about the credit memo line items.

See the /v3/credit-memos API for more information about the other credit memo fields you can set.

Sample request

In this cURL example, a credit memo of $49.99 is created for the customer (customerId). A referenceNumber and creditDate is set for the credit memo.

BILL applies ratePercent to the sum of the amount values of all the line items above the ratePercent line item. In the example, three creditMemoLineItems are added. The amount sum of the first two line items is $79.98. The third line item is added to apply a 10% discount ($8) on the credit memo amount sum.

curl --request POST \
–-url 'https://gateway.stage.bill.com/connect/v3/invoices' \
--header 'content-type: application/json' \
--header 'devKey: {developer_key}' \
--header 'sessionId: {session_id}' \
--data '{
  "customerId": "{customed_id}",
  "creditDate": "2025-12-28",
  "creditMemoLineItems": [
    {
      "description": "Classic extreme drum sticks",
      "price": "14.99",
      "quantity": "2"
    },
    {
      "description": "Metal guitar picks (5-pack)",
      "price": "50.00",
      "quantity": "1"
    },
    {
       "description": "10% discount",
       "ratePercent": -10
    }
  ],
  "referenceNumber": "202502-creditmemo",
  "description": "Paperless Band Credit Memo 20251228"
}'

Response

In the response, a BILL-generated credit memo id is available. The value begins with ccr. The amount value is $71.98 ($79.98 total - $8 discount).

{
    "id": "{credit_memo_id}",
    "customerId": "{customer_id}",
    "referenceNumber": "202502-creditmemo",
    "creditDate": "2025-12-28",
    "description": "Paperless Band Credit Memo 20251228",
    "archived": false,
    "amount": 71.98,
    "appliedAmount": 0.00,
    "salesTaxTotal": 0.00,
    "salesTaxPercentage": 0,
    "status": "NOT_APPLIED",
    "createdTime": "2025-12-26T19:41:29.127+00:00",
    "updatedTime": "2025-12-26T19:41:29.127+00:00",
    "creditMemoLineItems": [
        {
            "id": "{creditMemoLineItem_id01}",
            "description": "Classic extreme drum sticks",
            "price": 14.99,
            "quantity": 2,
            "amount": 29.98,
            "taxable": false
        },
        {
            "id": "{creditMemoLineItem_id02}",
            "description": "Metal guitar picks (5-pack)",
            "price": 50.00,
            "quantity": 1,
            "amount": 50.00,
            "taxable": false
        },
        {
            "id": "{creditMemoLineItem_id03}",
            "description": "10% discount",
            "quantity": 1,
            "amount": -8.00,
            "ratePercent": -10,
            "taxable": false
        }
    ]
}

Apply a credit memo to an invoice

In your PATCH /v3/invoices/{invoiceId} request, set the required fields.

FieldDescription
invoiceIdBILL-generated ID of the invoice. The value begins with 00e.
creditAmountCredit amount applied to the invoice.

BILL applies the credit amount from the total of all the credit memos available for the customer.

❗️

IMPORTANT

When a credit memo amount is applied to an invoice, there are two updates to note.

  • The credit memo status is updated to PARTIALLY_APPLIED or FULLY_APPLIED depending on the credit memo amount.
  • The usage array lists the invoices that the credit amount is applied to.

Sample request

In this cURL example, a credit memo is applied to an existing invoice (invoiceId).

curl --request PATCH \
–-url 'https://gateway.stage.bill.com/connect/v3/invoices/{invoiceId}' \
--header 'content-type: application/json' \
--header 'devKey: {developer_key}' \
--header 'sessionId: {session_id}' \
--data '{
  "creditAmount": "10.00"
}'

Response

In the response, the invoice is updated based on the applied creditAmount.

  • creditAmount is set as the credit amount applied to the invoice.
  • dueAmount is is calculated by subtracting any applied credits (creditAmount), scheduled payment (scheduledAmount), and cleared payment from totalAmount.
  • The invoice status is set as PARTIAL_PAYMENT or PAID_IN_FULL depending on the invoice totalAmount.

See the /v3/credit-memos API for more information about the complete list of credit memo operations.

Updated 2 days ago