Record AR payments

Use POST /v3/invoices/record-payment to record invoice payments received outside your BILL system. Apply the recorded payment amount to one or more invoices for a customer. Any recorded unapplied amount is an overpayment and is available as a customer balance in your BILL system.

See the /v3/invoices/record-payment API for more information.

👍

Invoices are listed for one customer at a time

The listed invoices must belong to the same customer in your POST/v3/invoices/record-payment request.

To record an AR payment, set the required fields in your request.

See the POST /v3/invoices/record-payment API for more information about the other fields you can set.

Sample request

In this cURL example, an AR payment of $100 is recorded. The paymentType is set as CREDIT_CARD. The invoices array lists two invoices ($50 and $30) to be paid. In the example, an additional $20 ($100 - $50 - $30) is recorded.

curl --request POST \
--url 'https://gateway.stage.bill.com/connect/v3/invoices/record-payment' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'devKey: {developer_key}' \
--header 'sessionId: {session_id}' \
--data '{
  "amount": "100",
  "customerId": "{customer_id}",
  "invoices": [
    {
      "amount": "50",
      "id": "{invoice_id01}"
    },
    {
      "amount": "30",
      "id": "{invoice_id02}"
    }
  ],
  "paymentDate": "2026-12-20",
  "paymentType": "CREDIT_CARD",
  "description": "Accepted credit card payment in store"
}'

Response

In the response, a BILL-generated received payment id is available. The value begins with 0rp. The listed invoices are marked as PAID.

👍

Any unapplied amount will be applied to future invoices after any credit memos

When you apply a creditAmount to a future invoice, BILL applies the credit amount from the total of all credit memos available for the customer. After all credit memos are used, BILL will apply the credit amount from any unappliedAmount values in the Record AR payment operation.

{
  "id": "{received_payment_id}",
  "customerId": "{customer_id}",
  "paymentType": "CREDIT_CARD",
  "paymentDate": "2026-12-20",
  "amount": 100.00,
  "unappliedAmount": 20.00,
  "status": "PAID",
  "description": "Accepted credit card payment in store",
  "invoices": [
    {
      "id": "{invoice_id01}",
      "payments": [
        {
          "id": "{invoice_payment_id01}",
          "amount": 50.00,
          "status": "PAID",
          "date": "2026-12-20"
        }
      ]
    },
    {
      "id": "{invoice_id02}",
      "payments": [
        {
          "id": "{invoice_payment_id02}",
          "amount": 30.00,
          "status": "PAID",
          "date": "2026-12-20"
        }
      ]
    }
  ]
}