# Bulk updates

The /api/customers/bulkupdates/ endpoint processes an array of operations to be performed on customers and related subscriptions and product assignments. It is an alternative to performing the operations one at a time when you want to perform several in one request, e.g. when importing or synchronizing.

A single request may contain at most 1000 operations. Split larger imports and synchronizations into chunks across several requests.

# Parameters

• operations array required
  A JSON array of operation objects, at most 1000 per request. Each object has operation with the name of the operation to perform, and id as the ID of the customer to perform the operation on (except for the create customer operation where it is optional). For example: [{"operation": "updatecustomer", "id": "12345", "data": {"name": "Customer Name"}}].
• use_external_lookup boolean Defaults to true
  Set to false or 0 if you don't want e-invoice recipients, VAT organization IDs and similar to be validated via external services.

The matching update endpoints and operation names are:

To make an operation for an endpoint, collect the parameters for the endpoint in an object like if you were sending a request to the endpoint, then add the operation attribute with the operation name, like {"id": "12345", "data": {"name": "Customer Name"}} becomes {"operation": "updatecustomer", "id": "12345", "data": {"name": "Customer Name"}}.

# Examples

Update two customers in one request:

POST /api/customers/bulkupdates/ HTTP/1.1
Content-Type: application/json{
  "operations": [{
    "operation": "updatecustomer",
    "id": "12345",
    "data": {
      "name": "Customer Name"
    }
  }, {
    "operation": "updatecustomer",
    "id": "12346",
    "data": {
      "name": "Another Name"
    }
  }]
}

Create a customer and then a subscription for that customer, without knowing the customer's ID in advance:

POST /api/customers/bulkupdates/ HTTP/1.1
Content-Type: application/json{
  "operations": [{
    "operation": "createcustomer",
    "data": {
      "email": "someone@example.com"
    }
  }, {
    "operation": "createsubscription",
    "periods": [{
      "campaign_id": "3months"
    }]
  }]
}

# Combining operations

The operations are processed in the order they appear in the array. For instance when importing customers with associated subscriptions, it's convenient to submit a complete set of create operations, even though the IDs necessary to link subscriptions to customers are not yet known. Any operation requiring a customer ID can leave out the ID, and instead the ID from a preceding createcustomer operation is used. If there's no preceding create customer operation, an error is raised.

A runtime error in an operation skips just that operation; the following operations are still processed. An operation that depends on a failed one generally fails too: a createcustomer that fails to validate leaves no customer for a following createsubscription to attach to, so the subscription is not created either. Independent operations are unaffected, so a second createcustomer is still created.

# Return value

The return value is a JSON object with a summary of succeeded and failed operations and the errors, if any. A successful operation looks like this:

{
  "succeeded": 1,
  "failed": 0,
  "errors": [{}],
  "results": [{"id": "6493264"}]
}

The errors and results arrays are parallel to the operations array you passed in, with one object per operation. A successful operation has an empty error object. Field-specific errors use the field name as key; errors that are not specific to a field use the empty string as key. Take the example above with creating a customer and then a subscription for that customer: if the customer cannot be created, the subscription creation fails too, because there is no customer to attach it to.

{
  "succeeded": 0,
  "failed": 2,
  "errors": [
    {
      "email": ["This email address is already being used by a customer."]
    },
    {
      "": ["Customer does not exist."]
    }
  ],
  "results": [{}, {}]
}

Unlike the ordinary endpoints, these errors return with an HTTP 200 status code rather than 422. The bulk API reports user input and validation errors in the JSON above, even though the request succeeded as a whole.

Invalid requests due to programming error returns 400, e.g. invalid JSON, more than 1000 operations, or a required parameter completely missing from an operation.