---
updatedAt: 2026-05-26T17:53:48.000Z
agentTools:
  projectIndex: https://developer.bill.com/v2/llms.txt
---

# Bulk update customers

Bulk update customer objects. The maximum number of objects you can set in a bulk operation is 100.

### What is a customer?
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.

You can create a new customer object with [`/v2/Crud/Create/Customer.json`](ref:ar-customermgmt-createcustomer).

Other customer features:
* Create additional customer contacts with [`/v2/Crud/Create/CustomerContact.json`](ref:ar-customermgmt-createcustomercontact). This is useful when the customer has multiple departments, such as purchasing, sales, and accounting.
* Add a customer bank account with [`/v2/Crud/Create/CustomerBankAccount.json`](ref:ar-customermgmt-createcustomerbankaccount).
* Authorize your organization to charge a customer with [`/v2/SetCustomerAuthorization.json`](ref:ar-customertransactions-setcustomerauthorization). This is required before you can charge the customer (with [`/v2/ChargeCustomer.json`](ref:ar-customertransactions-chargecustomer)).
* `invoiceCurrency` is a required additional field for creating an international customer. When this value is set, invoices can be created for receiving payments from the international customer.

# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "info": {
    "title": "AR | Customer management",
    "version": "2.0",
    "description": "BILL is a cloud-based cash flow management system for an organization's Accounts Payable (AP) and Accounts Receivable (AR) automation.\n * **AP**: Automate workflows to pay vendors bills at scale for the goods and services they provide. Pay vendors with a wide range of payment methods. Generate vendor credits, bill credits, and payment disbursement reports.\n * **AR**: Automate workflows to get paid by customers at scale for the goods and services you provide. Generate and send invoices on a schedule, generate customer and invoice credits, and seamlessly charge authorized customers.\n * **Organization**: Manage your bank accounts (for sending and receiving payments), users (with user roles), and sync with your choice of accounting software.\n\nIntegrate with the BILL API to send and receive payments for your business. See [Support Center](https://help.bill.com/hc/en-us) for resources about using the BILL web app.",
    "contact": {
      "email": "developerprogram@hq.bill.com"
    }
  },
  "servers": [
    {
      "url": "https://api-stage.bill.com/api/v2",
      "description": "Sandbox base URL"
    }
  ],
  "x-readme": {
    "samples-languages": [
      "curl",
      "java",
      "javascript",
      "python",
      "ruby"
    ]
  },
  "paths": {
    "/Bulk/Crud/Update/Customer.json": {
      "post": {
        "summary": "Bulk update customers",
        "operationId": "ar-customermgmt-bulkupdatecustomer",
        "description": "Bulk update customer objects. The maximum number of objects you can set in a bulk operation is 100.\n\n### What is a customer?\nA 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.\n\nYou can create a new customer object with [`/v2/Crud/Create/Customer.json`](https://developer.bill.com/reference/ar-customermgmt-createcustomer).\n\nOther customer features:\n* Create additional customer contacts with [`/v2/Crud/Create/CustomerContact.json`](https://developer.bill.com/reference/ar-customermgmt-createcustomercontact). This is useful when the customer has multiple departments, such as purchasing, sales, and accounting.\n* Add a customer bank account with [`/v2/Crud/Create/CustomerBankAccount.json`](https://developer.bill.com/reference/ar-customermgmt-createcustomerbankaccount).\n* Authorize your organization to charge a customer with [`/v2/SetCustomerAuthorization.json`](https://developer.bill.com/reference/ar-customertransactions-setcustomerauthorization). This is required before you can charge the customer (with [`/v2/ChargeCustomer.json`](https://developer.bill.com/reference/ar-customertransactions-chargecustomer)).\n* `invoiceCurrency` is a required additional field for creating an international customer. When this value is set, invoices can be created for receiving payments from the international customer.",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BulkUpdateCustomerResponse"
                }
              }
            }
          }
        },
        "requestBody": {
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "required": [
                  "devKey",
                  "sessionId",
                  "data"
                ],
                "properties": {
                  "devKey": {
                    "type": "string",
                    "description": "Developer key generated with your BILL developer account"
                  },
                  "sessionId": {
                    "type": "string",
                    "description": "API session ID generated with [`/v2/Login.json`](https://developer.bill.com/reference/auth-login)"
                  },
                  "data": {
                    "$ref": "#/components/schemas/BulkUpdateCustomerRequest"
                  }
                }
              }
            }
          }
        },
        "tags": [
          "Customers"
        ]
      },
      "parameters": []
    }
  },
  "components": {
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error_code": {
            "type": "string",
            "description": "Error code (only when `response_status` is `1`)"
          },
          "error_message": {
            "type": "string",
            "description": "Error message (only when `response_status` is `1`)"
          }
        }
      },
      "CreateCustomerResponse": {
        "type": "object",
        "properties": {
          "response_status": {
            "type": "integer",
            "description": "Response status.\n* `0`: Success response\n* `1`: Error response. Only `error_code` and `error_message` is returned in `response_data`."
          },
          "response_message": {
            "type": "string",
            "description": "Response status.\n* `Success`: Success response\n* `Error`: Error response. Only `error_code` and `error_message` is returned in `response_data`."
          },
          "response_data": {
            "type": "object",
            "allOf": [
              {
                "$ref": "#/components/schemas/ErrorResponse"
              }
            ],
            "properties": {
              "entity": {
                "type": "string",
                "description": "Object type. Set as `Customer`."
              },
              "id": {
                "type": "string",
                "description": "BILL-generated ID of the customer. The value begins with `0cu`."
              },
              "isActive": {
                "type": "string",
                "description": "Object visibility status. Inactive objects are hidden by default in the BILL web app.\n* `1`: Active\n* `2`: Inactive"
              },
              "createdTime": {
                "type": "string",
                "description": "Created date and time"
              },
              "updatedTime": {
                "type": "string",
                "description": "Updated date and time"
              },
              "name": {
                "type": "string",
                "description": "Unique customer name"
              },
              "shortName": {
                "type": "string",
                "description": "Name for identifying the customer in BILL and in your choice of accounting software"
              },
              "parentCustomerId": {
                "type": "string",
                "description": "BILL-generated ID of the parent customer. Set this value if the current customer ID is a child object."
              },
              "companyName": {
                "type": "string",
                "description": "Customer company name"
              },
              "contactFirstName": {
                "type": "string",
                "description": "Primary customer contact first name"
              },
              "contactLastName": {
                "type": "string",
                "description": "Primary customer contact last name"
              },
              "accNumber": {
                "type": "string",
                "description": "Additional customer account identification number. The number is available in customer invoices and in the BILL web app."
              },
              "billAddress1": {
                "type": "string",
                "description": "Customer billing address line 1"
              },
              "billAddress2": {
                "type": "string",
                "description": "Customer billing address line 2"
              },
              "billAddress3": {
                "type": "string",
                "description": "Customer billing address line 3"
              },
              "billAddress4": {
                "type": "string",
                "description": "Customer billing address line 4"
              },
              "billAddressCity": {
                "type": "string",
                "description": "Customer billing address city"
              },
              "billAddressState": {
                "type": "string",
                "description": "Customer billing address state"
              },
              "billAddressCountry": {
                "type": "string",
                "description": "Customer billing address country"
              },
              "billAddressZip": {
                "type": "string",
                "description": "Customer billing address zip code"
              },
              "shipAddress1": {
                "type": "string",
                "description": "Customer shipping address line 1"
              },
              "shipAddress2": {
                "type": "string",
                "description": "Customer shipping address line 2"
              },
              "shipAddress3": {
                "type": "string",
                "description": "Customer shipping address line 3"
              },
              "shipAddress4": {
                "type": "string",
                "description": "Customer shipping address line 4"
              },
              "shipAddressCity": {
                "type": "string",
                "description": "Customer shipping address city"
              },
              "shipAddressState": {
                "type": "string",
                "description": "Customer shipping address state"
              },
              "shipAddressCountry": {
                "type": "string",
                "description": "Customer shipping address country."
              },
              "shipAddressZip": {
                "type": "string",
                "description": "Customer shipping address zip code"
              },
              "email": {
                "type": "string",
                "description": "Customer email address"
              },
              "phone": {
                "type": "string",
                "description": "Customer phone number"
              },
              "altPhone": {
                "type": "string",
                "description": "Customer alternate phone number"
              },
              "fax": {
                "type": "string",
                "description": "Customer fax number"
              },
              "description": {
                "type": "string",
                "description": "Customer description"
              },
              "invoiceCurrency": {
                "type": "string",
                "description": "Customer bill currency. Three-letter abbreviation. This field is required for creating an international customer. When this value is set, invoices can be created for receiving payments from the international customer.\n\nSee [Country information for international payments](https://help.bill.com/hc/en-us/articles/360007172671) in the BILL Help Center for more information."
              },
              "printAs": {
                "type": "string",
                "description": "Customer name on check"
              },
              "mergedIntoId": {
                "type": "string",
                "description": "Parent customer ID that the current ID is merged into"
              },
              "hasAuthorizedToCharge": {
                "type": "boolean",
                "description": "Set as `true` if the customer has provided authorization for charging the customer"
              },
              "accountType": {
                "type": "string",
                "description": "Customer account type.\n* `0`: None\n* `1`: Business\n* `2`: Person"
              },
              "paymentTermId": {
                "type": "string",
                "description": "BILL-generated payment term ID for the customer. The payment term defines when a payment is sent."
              },
              "balance": {
                "type": "number",
                "description": "Current customer balance"
              },
              "availCredit": {
                "type": "number",
                "description": "Customer available credits"
              },
              "taxId": {
                "type": "string",
                "description": "Customer tax identification number"
              },
              "hasBankAccount": {
                "type": "boolean",
                "description": "Set as `true` if customer bank account is available"
              },
              "hasNetBankAccount": {
                "type": "boolean",
                "description": "Set as `true` if customer net bank account is available"
              },
              "hasBankAccountAutoPay": {
                "type": "boolean",
                "description": "Set as `true` if customer bank account autopay is available"
              },
              "defaultDeliveryMethod": {
                "type": "string",
                "description": "Default invoice delivery method.\n* `0`: Email\n* `1`: US Mail service"
              },
              "isAutoChargeDismissed": {
                "type": "boolean",
                "description": "Set as `true` if customer auto-charge is dismissed"
              },
              "isTaxLiable": {
                "type": "boolean",
                "description": "Set as `true` if the customer is liable for taxes"
              },
              "creationSource": {
                "type": "string",
                "description": "Customer creation source.\n* `0`: Unknown\n* `1`: BILL web app (UI)\n* `2`: BILL web app (UI) search"
              },
              "enabledInvoiceFinancing": {
                "type": "boolean",
                "description": "Set as `true` to enable invoice financing for the customer. See [Invoice Financing FAQs](https://help.bill.com/direct/s/article/10656399312525) in the BILL Help Center for more information."
              },
              "hasCustomerCard": {
                "type": "boolean",
                "description": "Set as `true` if customer credit card is stored for autopay"
              }
            }
          }
        }
      },
      "UpdateCustomerRequest": {
        "type": "object",
        "required": [
          "obj"
        ],
        "properties": {
          "obj": {
            "type": "object",
            "required": [
              "entity",
              "id",
              "name"
            ],
            "properties": {
              "entity": {
                "type": "string",
                "description": "Object type. Set as `Customer`.",
                "default": "Customer"
              },
              "id": {
                "type": "string",
                "description": "BILL-generated ID of the customer. The value begins with `0cu`."
              },
              "isActive": {
                "type": "string",
                "description": "Object visibility status. Inactive objects are hidden by default in the BILL web app.\n* `1`: Active\n* `2`: Inactive"
              },
              "name": {
                "type": "string",
                "description": "Unique customer name"
              },
              "shortName": {
                "type": "string",
                "description": "Name for identifying the customer in BILL and in your choice of accounting software"
              },
              "parentCustomerId": {
                "type": "string",
                "description": "BILL-generated ID of the parent customer. Set this value if the current customer ID is a child object."
              },
              "companyName": {
                "type": "string",
                "description": "Customer company name"
              },
              "contactFirstName": {
                "type": "string",
                "description": "Primary customer contact first name"
              },
              "contactLastName": {
                "type": "string",
                "description": "Primary customer contact last name"
              },
              "accNumber": {
                "type": "string",
                "description": "Additional customer account identification number. The number is available in customer invoices and in the BILL web app."
              },
              "billAddress1": {
                "type": "string",
                "description": "Customer billing address line 1"
              },
              "billAddress2": {
                "type": "string",
                "description": "Customer billing address line 2"
              },
              "billAddress3": {
                "type": "string",
                "description": "Customer billing address line 3"
              },
              "billAddress4": {
                "type": "string",
                "description": "Customer billing address line 4"
              },
              "billAddressCity": {
                "type": "string",
                "description": "Customer billing address city"
              },
              "billAddressState": {
                "type": "string",
                "description": "Customer billing address state. Two-letter abbreviation for a US state."
              },
              "billAddressCountry": {
                "type": "string",
                "description": "Customer billing address country.\n\nSee [Country information for international payments](https://help.bill.com/hc/en-us/articles/360007172671) in the BILL Help Center for more information."
              },
              "billAddressZip": {
                "type": "string",
                "description": "Customer billing address zip code"
              },
              "shipAddress1": {
                "type": "string",
                "description": "Customer shipping address line 1"
              },
              "shipAddress2": {
                "type": "string",
                "description": "Customer shipping address line 2"
              },
              "shipAddress3": {
                "type": "string",
                "description": "Customer shipping address line 3"
              },
              "shipAddress4": {
                "type": "string",
                "description": "Customer shipping address line 4"
              },
              "shipAddressCity": {
                "type": "string",
                "description": "Customer shipping address city"
              },
              "shipAddressState": {
                "type": "string",
                "description": "Customer shipping address state. Two-letter abbreviation for a US state."
              },
              "shipAddressCountry": {
                "type": "string",
                "description": "Customer shipping address country"
              },
              "shipAddressZip": {
                "type": "string",
                "description": "Customer shipping address zip code"
              },
              "email": {
                "type": "string",
                "description": "Customer email address"
              },
              "phone": {
                "type": "string",
                "description": "Customer phone number"
              },
              "altPhone": {
                "type": "string",
                "description": "Customer alternate phone number"
              },
              "fax": {
                "type": "string",
                "description": "Customer fax number"
              },
              "description": {
                "type": "string",
                "description": "Customer description"
              },
              "invoiceCurrency": {
                "type": "string",
                "description": "Customer bill currency. Three-letter abbreviation.\n\nSee [Country information for international payments](https://help.bill.com/hc/en-us/articles/360007172671) in the BILL Help Center for more information."
              },
              "printAs": {
                "type": "string",
                "description": "Customer name on check"
              },
              "accountType": {
                "type": "string",
                "description": "Customer account type.\n* `0`: None\n* `1`: Business\n* `2`: Person"
              },
              "paymentTermId": {
                "type": "string",
                "description": "BILL-generated payment term ID for the customer. The payment term defines when a payment is sent."
              },
              "defaultDeliveryMethod": {
                "type": "string",
                "description": "Default invoice delivery method.\n* `0`: Email\n* `1`: US Mail service"
              },
              "isAutoChargeDismissed": {
                "type": "boolean",
                "description": "Set as `true` if customer auto-charge is dismissed"
              },
              "isTaxLiable": {
                "type": "boolean",
                "description": "Set as `true` if the customer is liable for taxes"
              },
              "creationSource": {
                "type": "string",
                "description": "Customer creation source.\n* `0`: Unknown\n* `1`: BILL web app (UI)\n* `2`: BILL web app (UI) search"
              },
              "enabledInvoiceFinancing": {
                "type": "boolean",
                "description": "Set as `true` to enable invoice financing for the customer. See [Invoice Financing FAQs](https://help.bill.com/direct/s/article/10656399312525) in the BILL Help Center for more information."
              }
            }
          }
        }
      },
      "BulkUpdateCustomerRequest": {
        "type": "object",
        "required": [
          "bulk"
        ],
        "properties": {
          "bulk": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/UpdateCustomerRequest"
            }
          }
        }
      },
      "BulkUpdateCustomerResponse": {
        "type": "object",
        "properties": {
          "response_status": {
            "type": "integer",
            "description": "Response status.\n* `0`: Success response\n* `1`: Error response. Only `error_code` and `error_message` is returned in `response_data`."
          },
          "response_message": {
            "type": "string",
            "description": "Response status.\n* `Success`: Success response\n* `Error`: Error response. Only `error_code` and `error_message` is returned in `response_data`."
          },
          "response_data": {
            "type": "object",
            "allOf": [
              {
                "$ref": "#/components/schemas/ErrorResponse"
              }
            ],
            "properties": {
              "bulk": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/CreateCustomerResponse"
                }
              }
            }
          }
        }
      }
    }
  }
}
```