System status

Recording an AR payment

Use POST/v3/invoices/record-payment to record an invoice payment 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.

📘

NOTE

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

Set the required fields in your request.

FieldDescription
paymentDatePayment date. The value is in the yyyy-MM-dd format.
paymentTypePayment type (CASH, CHECK, CREDIT_CARD, ACH, PAYPAL, or OTHER)
amountPayment amount
invoicesList of invoices being paid. In the invoices array, set the required information.
- id
- amount

See the /v3/invoices/record-payment API for more information about the other invoice 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": "2024-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": "2024-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": "2024-12-20"
        }
      ]
    },
    {
      "id": "{invoice_id02}",
      "payments": [
        {
          "id": "{invoice_payment_id02}",
          "amount": 30.00,
          "status": "PAID",
          "date": "2024-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}).

Updated 9 days ago