# Bulk updates

POST `https://app.iteras.dk/api/customers/bulkupdates/`

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` (bool, 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.
- `exclude_from_webhooks` (bool, Defaults to `false`): Set to `true` to keep every event the request causes from being sent to webhooks, invoice and payment events included, e.g. `"exclude_from_webhooks": true`. The events are still added to the history. It covers all the operations in the request, so it goes here next to `operations`; inside an operation it is ignored.

The matching update endpoints and operation names are:

| Endpoint | Operation |
| --- | --- |
| post `/api/customers/createcustomer/` | `createcustomer` |
| post `/api/customers/updatecustomer/` | `updatecustomer` |
| post `/api/customers/deletecustomer/` | `deletecustomer` |
| post `/api/customers/generateonetimepassword/` | `generateonetimepassword` |
| post `/api/customers/createsubscription/` | `createsubscription` |
| post `/api/customers/updatesubscription/` | `updatesubscription` |
| post `/api/customers/switchsubscriptionplan/` | `switchsubscriptionplan` |
| post `/api/customers/cancelsubscription/` | `cancelsubscription` |
| post `/api/customers/restartsubscription/` | `restartsubscription` |
| post `/api/customers/assignproduct/` | `assignproduct` |
| post `/api/customers/updateproductassignment/` | `updateproductassignment` |
| post `/api/customers/cancelproductassignment/` | `cancelproductassignment` |
| post `/api/customers/createpayment/` | `createpayment` |
| post `/api/customers/invoice/` | `invoice` |
| post `/api/customers/registercomplaint/` | `registercomplaint` |
| post `/api/customers/createoverride/` | `createoverride` |
| post `/api/customers/updateoverride/` | `updateoverride` |
| post `/api/customers/deleteoverride/` | `deleteoverride` |

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:

```http
POST /api/customers/bulkupdates/ HTTP/1.1
Content-Type: application/json
```

```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:

```http
POST /api/customers/bulkupdates/ HTTP/1.1
Content-Type: application/json
```

```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 `createsubscription` operation can likewise attach to a subscription created earlier in the request without knowing its ID. Set `group_subscription_id` to `null` to use the group subscription created earlier in the request, or `addon_base_subscription_id` to `null` to use the add-on base subscription created earlier. The parameter must be present with `null`; leaving it out creates an independent subscription. If no matching subscription was created earlier, or its creation failed, the operation fails.

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:

```json
{
  "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.

```json
{
  "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.

## Errors

Invalid requests due to programming error return 400, e.g. invalid JSON, more than 1000 operations, an `exclude_from_webhooks` that isn't `true` or `false`, or a required parameter completely missing from an operation.