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 more information about the complete list of customer operations.

Creating 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.

See the /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": "2024-12-30T23:25:27.000Z",
  "updatedTime": "2024-12-30T23:25:28.000Z"
}

See the /v3/customers API for more information about the complete list of customer operations.