> ## Documentation Index > Fetch the complete documentation index at: https://apidocs.taxwire.com/llms.txt > Use this file to discover all available pages before exploring further. # Upsert customers > Create or update up to 1000 customers in one request. Each customer is matched on its source, source account ID, and source ID, so you can safely send the same request again. Each customer succeeds or fails on its own. ## OpenAPI ````yaml POST /customers/batch openapi: 3.1.0 info: title: Taxwire Public API version: 0.1.0 servers: [] security: [] paths: /customers/batch: post: tags: - Customers summary: Upsert Customers description: >- Create or update up to 1000 customers in one request. Each customer is matched on its source, source account ID, and source ID, so you can safely send the same request again. Each customer succeeds or fails on its own. operationId: batch_upsert_customers_customers_batch_post requestBody: content: application/json: schema: $ref: '#/components/schemas/BatchUpsertCustomersRequest' examples: push: summary: Update one customer, create one, and reject one value: data: - source_id: CUS-1042 name: Acme Wholesale Inc. source_updated_at: '2026-09-15T08:30:00Z' - source_id: CUS-1043 name: Beta Corp email: billing@beta.example source_updated_at: '2026-09-15T08:29:41Z' - name: Gamma Supply required: true responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/BatchUpsertCustomersResponse' example: object: batch summary: created: 1 updated: 1 stale: 0 deleted: 0 failed: 1 data: - index: 0 status: updated customer: id: cust_01J9Z8Q4E7K2M3N4P5R6S7T8U9 source_id: CUS-1042 source: taxwire source_account_id: __default__ name: Acme Wholesale Inc. email: ap@acme.example source_updated_at: '2026-09-15T08:30:00Z' created_at: '2026-09-14T20:00:00Z' updated_at: '2026-09-15T08:30:05Z' - index: 1 status: created customer: id: cust_01J9ZB7V3M8N2K4P6Q1R5S7T9W source_id: CUS-1043 source: taxwire source_account_id: __default__ name: Beta Corp email: billing@beta.example source_updated_at: '2026-09-15T08:29:41Z' created_at: '2026-09-15T08:30:05Z' updated_at: '2026-09-15T08:30:05Z' - index: 2 status: failed errors: - status: '422' code: validation_required_field title: Missing source_id detail: >- Please provide a value for the required source_id field source: pointer: /data/attributes/data/2/source_id '413': description: Request Too Large - The request body is over the size limit. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: errors: - status: '413' code: request_too_large title: Request Too Large detail: >- The request body is 5242881 bytes; this API accepts at most 5242880. Split it into smaller requests. '422': description: >- Validation Error - The request is malformed or has more than 1000 customers. An invalid customer is reported as `failed` in a 200 response instead. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: errors: - status: '422' code: validation_error title: Validation Error detail: >- List should have at most 1000 items after validation, not 1001 source: pointer: /data/attributes/data '429': description: Rate limit exceeded. Try again later. headers: Retry-After: schema: type: string description: Time in seconds until the rate limit resets X-RateLimit-Limit: schema: type: string description: The rate limit ceiling for the given request X-RateLimit-Remaining: schema: type: string description: The number of requests remaining in the time window content: application/json: example: errors: - status: '429' code: rate_limit_error title: Too Many Requests detail: Rate limit exceeded schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal Server Error content: application/json: example: errors: - status: '500' code: system_internal_error title: Internal Error detail: An unexpected error occurred. Our team has been notified. schema: $ref: '#/components/schemas/ErrorResponse' security: - APIKeyHeader: [] - HTTPBearer: [] components: schemas: BatchUpsertCustomersRequest: properties: data: items: properties: source_id: type: string maxLength: 255 title: Source Id description: >- Identifier for the customer in the source system. Can't be blank. For a customer that a Taxwire integration also syncs, use the same `source_id` the integration stores, or a second customer is created. examples: - CUS-1042 source: type: string enum: - business_central - campfire - maxio - monetizenow - netsuite - quickbooks - rillet - salesbricks - shopify - stripe - taxwire - xero description: Source system of the customer. Defaults to `taxwire`. default: taxwire examples: - taxwire source_account_id: type: string maxLength: 255 title: Source Account Id description: >- Account in the source system that the customer belongs to. Required for sources that keep customers per account, and `__default__` for every other source. The wrong form returns `422` with the form the source needs. default: __default__ examples: - __default__ name: anyOf: - type: string maxLength: 500 - type: 'null' title: Name description: Name of the customer. examples: - Acme Wholesale email: anyOf: - type: string maxLength: 320 - type: 'null' title: Email description: Email address of the customer. Does not need to be unique. examples: - ap@acme.example source_updated_at: anyOf: - type: string format: date-time - type: 'null' title: Source Updated At description: >- Date at which the customer was last updated in the source system. Recommended for every source except `taxwire`. An update with an older date doesn't change the customer. examples: - '2026-09-14T19:58:12Z' additionalProperties: false type: object required: - source_id title: CreateCustomerRequest description: Create customer request model. type: array maxItems: 1000 title: Data description: >- List of customers to create or update, up to 1000 customers and 5 MB per request. Each customer takes the same fields as [Create customer](/api-reference/customers/create). For an existing customer, omitted fields and `null` values keep the current value. If the same customer appears more than once, every copy fails. additionalProperties: false type: object required: - data title: BatchUpsertCustomersRequest description: Upsert customers request model. BatchUpsertCustomersResponse: properties: object: type: string title: Object description: Always `batch`. default: batch summary: $ref: '#/components/schemas/BatchSummary' data: items: $ref: '#/components/schemas/BatchCustomerResult' type: array title: Data description: Results in the same order as the request. type: object required: - summary - data title: BatchUpsertCustomersResponse description: Upsert customers response model. ErrorResponse: properties: errors: items: $ref: '#/components/schemas/Error' type: array title: Errors type: object required: - errors title: ErrorResponse description: Standardized JSON:API error response model. BatchSummary: properties: created: type: integer title: Created default: 0 updated: type: integer title: Updated default: 0 stale: type: integer title: Stale default: 0 deleted: type: integer title: Deleted default: 0 failed: type: integer title: Failed default: 0 type: object title: BatchSummary description: Number of customers with each result. BatchCustomerResult: properties: index: type: integer title: Index description: Position of the customer in the request, starting at 0. examples: - 0 status: type: string enum: - created - updated - stale - deleted - failed title: Status description: >- Result for the customer: `created`, `updated`, `stale` (ignored because its `source_updated_at` is older than the current one), `deleted` (matched a customer deleted in the Taxwire app, so nothing changed), or `failed`. examples: - created customer: anyOf: - $ref: '#/components/schemas/CustomerResource' - type: 'null' description: >- Customer as stored after the request. Set for `created`, `updated`, and `stale`. errors: anyOf: - items: $ref: '#/components/schemas/Error' type: array - type: 'null' title: Errors description: Errors for the customer. Set for `failed`. examples: - null type: object required: - index - status title: BatchCustomerResult description: Result for one customer in the request. Error: properties: status: type: string title: Status code: type: string title: Code title: type: string title: Title detail: type: string title: Detail source: anyOf: - $ref: '#/components/schemas/ErrorSource' - type: 'null' meta: anyOf: - additionalProperties: true type: object - type: 'null' title: Meta type: object required: - status - code - title - detail title: Error description: Individual JSON:API error object. CustomerResource: properties: id: type: string title: Id description: Unique identifier for the customer. examples: - cust_01J9Z8Q4E7K2M3N4P5R6S7T8U9 source_id: type: string title: Source Id description: Identifier for the customer in the source system. examples: - CUS-1042 source: type: string enum: - business_central - campfire - maxio - monetizenow - netsuite - quickbooks - rillet - salesbricks - shopify - stripe - taxwire - xero description: >- Source system of the customer. `taxwire` for customers created in Taxwire rather than in another system. examples: - taxwire source_account_id: type: string title: Source Account Id description: >- Account in the source system that the customer belongs to. `__default__` if the source system has no account or tenant ID. examples: - __default__ name: anyOf: - type: string - type: 'null' title: Name description: Name of the customer. examples: - Acme Wholesale email: anyOf: - type: string - type: 'null' title: Email description: Email address of the customer. Does not need to be unique. examples: - ap@acme.example merged_into_customer_id: anyOf: - type: string - type: 'null' title: Merged Into Customer Id description: >- Unique identifier of the customer this customer was merged into, when the source system reports a merge. `null` otherwise. examples: - cust_01J9ZC4D7F2G8H3J5K6L9M1N0P - null source_updated_at: anyOf: - type: string format: date-time - type: 'null' title: Source Updated At description: >- Date at which the customer was last updated in the source system. `null` if unknown. examples: - '2026-09-14T19:58:12Z' created_at: type: string format: date-time title: Created At description: Date at which the customer record was created. examples: - '2026-09-14T20:00:00Z' updated_at: type: string format: date-time title: Updated At description: Date at which the customer record was last updated. examples: - '2026-09-14T20:00:00Z' additionalProperties: false type: object required: - id - source_id - source - source_account_id - created_at - updated_at title: CustomerResource description: Customer response model. ErrorSource: properties: pointer: anyOf: - type: string - type: 'null' title: Pointer type: object title: ErrorSource description: Identifies the source of the error, e.g., via a JSON Pointer. securitySchemes: APIKeyHeader: type: apiKey in: header name: X-API-Key HTTPBearer: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.