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.

Field	Description
`paymentDate`	Payment date. The value is in the `yyyy-MM-dd` format.
`paymentType`	Payment type (`CASH`, `CHECK`, `CREDIT_CARD`, `ACH`, `PAYPAL`, or `OTHER`)
`amount`	Payment amount
`invoices`	List of invoice payments. In the `invoices` array, set the required information. `id` `amount`

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": "2025-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.

{
  "id": "{received_payment_id}",
  "customerId": "{customer_id}",
  "paymentType": "CREDIT_CARD",
  "paymentDate": "2025-12-20",
  "amount": 100.00,
  "unappliedAmount": 100.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": "2025-12-20"
        }
      ]
    },
    {
      "id": "{invoice_id02}",
      "payments": [
        {
          "id": "{invoice_payment_id02}",
          "amount": 30.00,
          "status": "PAID",
          "date": "2025-12-20"
        }
      ]
    }
  ]
}

In this example, since an additional $20 is recorded, this $20 is added to the customer balance amount (available with GET /v3/customers/{customerId}).

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