Customers

A customer is an organization that pays you for goods and services you provide. Vendors and customers using BILL can be connected to each other in the BILL network. Network connections between vendors and customers enable electronic payments between them.

See the /v3/customers API for the complete list of available operations.

Create a customer

In your POST /v3/customers request, set the required fields.

Field	Description
`name`	Customer name
`email`	Customer email address
`invoiceCurrency`	Customer invoice currency. This field specifies the currency with which an international customer pays invoices. This field is required for creating an international customer.

Field

Description

name

Customer name

email

Customer email address

invoiceCurrency

Customer invoice currency. This field specifies the currency with which an international customer pays invoices.

This field is required for creating an international customer.

See the POST /v3/customers API for more information about the other customer fields you can set.

Sample request

In this cURL example, a customer is created with the specified details. The contact and billingAddress details are added to maintain customer contact information.

curl --request POST \
--url 'https://gateway.stage.bill.com/connect/v3/customers' \
--header 'content-type: application/json' \
--header 'devKey: {developer_key}' \
--header 'sessionId: {session_id}' \
--data '{
  "name": "Paperless Band", 
  "companyName": "Paperless Band LLC",
  "contact": {
    "firstName": "Check",
    "lastName": "Mailworth"
  },
  "email": "[email protected]", 
  "accountType": "BUSINESS",
  "phone": "9998887654",
  "billingAddress": {
    "line1": "987 Side Street",
    "city": "San Jose",
    "stateOrProvince": "CA",
    "zipOrPostalCode": "95002",
    "country": "US"
  }
}'

Response

In the response, a BILL-generated customer id is available. The value begins with 0cu. You can use this customer id for other BILL operations.

In addition, a balance value is available. This value is updated when invoices are created for this customer.

{
  "id": "{customer_id}",
  "archived": false,
  "name": "Paperless Band",
  "companyName": "Paperless Band LLC",
  "contact": {
      "firstName": "Check",
      "lastName": "Mailworth"
  },
  "email": "[email protected]",
  "phone": "9998887654",
  "invoiceCurrency": "USD",
  "accountType": "BUSINESS",
  "billingAddress": {
    "line1": "987 Side Street",
    "city": "San Jose",
    "stateOrProvince": "CA",
    "zipOrPostalCode": "95002",
    "country": "US"
  },
  "balance": {
    "amount": {
      "value": 0.00
      }
  },
  "createdTime": "2025-12-30T23:25:27.127+00:00",
  "updatedTime": "2025-12-30T23:25:28.127+00:00"
}

See the /v3/customers API for the complete list of available operations.

Create a customer bank account

Use POST /v3/customers/{customerId}/bank-accounts to add a customer bank account. When you add customer bank account information, you can charge the customer for invoices with your BILL account.

The customer billAddress information is required before you can create a customer bank account. You can add the billingAddress for an existing customer with PATCH /v3/customers/{customerId}.

👍
Contact the support team to get access to the Create a customer bank account feature
Contact the BILL support team to get access to the Create a customer bank account feature with the API. If the feature is not enabled for your sandbox BILL organization, you will get the Current user or organization does not have valid permissions. error in the response.

In your POST /v3/customers/{customerId}/bank-accounts request, set the required fields.

Field	Description
`nameOnAccount`	Customer bank account name
`routingNumber`	Customer bank routing number
`accountNumber`	Customer bank account number
`type`	Customer bank account type (`CHECKING` or `SAVINGS`)
`ownerType`	Customer bank account owner type (`BUSINESS` or `PERSONAL`)

See the POST /v3/customers/{customerId}/bank-accounts API for more information about the other fields you can set.

Sample request

In this cURL example, a customer bank account is added for an existing customer.

curl --request POST \
--url 'https://gateway.stage.bill.com/connect/v3/customers/{customerId}/bank-accounts' \
--header 'content-type: application/json' \
--header 'devKey: {developer_key}' \
--header 'sessionId: {session_id}' \
--data '{
  "nameOnAccount": "Clark Spenderson", 
  "routingNumber": "074000010",
  "accountNumber": "9876543210", 
  "type": "CHECKING",
  "ownerType": "BUSINESS"
}'

Response

In the response, a BILL-generated ID of the customer bank account is available. The value begins with cba.

See the /v3/customers API for the complete list of available operations.