2025-07 Customer Tax Bulk Update API

We've introduced a new bulk endpoint for updating customer tax assignments. The POST /api/2.0/customer_taxes/bulk endpoint allows you to assign or remove tax IDs from multiple customers in a single request, improving efficiency for bulk operations.

Endpoint Details

POST /api/2.0/customer_taxes/bulk

This endpoint processes up to 100 customer tax updates in a single transaction, providing detailed success and error reporting for each item.
Set tax_id to null or "" to remove tax assignment

Authentication

Required User Permission: Add and edit customers
Security: Requires valid authentication credentials

Request Format

Content-Type: application/json

{
  "customer_tax": [
    {
      "customer_id": "550e8400-e29b-41d4-a716-446655440000",
      "tax_id": "123e4567-e89b-12d3-a456-426614174000"
    },
    {
      "customer_id": "550e8400-e29b-41d4-a716-446655440001",
      "tax_id": null
    }
  ]
}

Request Parameters

Field	Type	Required	Description
`customer_tax`	array	Yes	Array of customer tax updates (1-100 items)
`customer_tax[].customer_id`	string	Yes	Valid customer ID
`customer_tax[].tax_id`	string or null	Yes	Valid tax ID or null to remove assignment

Response Format

The endpoint returns different status codes based on processing results:

200 OK: All items processed successfully
207 Multi-Status: Partial success (some items succeeded, some failed)
400 Bad Request: All items failed or validation errors
500 Internal Server Error: System error

Successful Response (200 OK)

{
  "data": {
    "successful": [
      {
        "index": 0,
        "customer_id": "550e8400-e29b-41d4-a716-446655440000",
        "tax_id": "123e4567-e89b-12d3-a456-426614174000",
        "created_at": "2025-01-15T10:30:00.000Z",
        "updated_at": "2025-01-15T10:30:00.000Z"
      }
    ],
    "failed": [],
    "summary": {
      "total_processed": 1,
      "success_count": 1,
      "error_count": 0
    }
  }
}

Partial Success Response (207 Multi-Status)

{
  "data": {
    "successful": [
      {
        "index": 0,
        "customer_id": "550e8400-e29b-41d4-a716-446655440000",
        "tax_id": "123e4567-e89b-12d3-a456-426614174000",
        "created_at": "2025-01-15T10:30:00.000Z",
        "updated_at": "2025-01-15T10:30:00.000Z"
      }
    ],
    "failed": [
      {
        "index": 1,
        "customer_id": "550e8400-e29b-41d4-a716-446655440001",
        "tax_id": "invalid-tax-id",
        "errors": [
          {
            "code": "INVALID_TAX_ID",
            "messages": ["Invalid tax ID provided"]
          }
        ]
      }
    ],
    "summary": {
      "total_processed": 2,
      "success_count": 1,
      "error_count": 1
    }
  }
}

Error Response (400 Bad Request)

{
  "data": {
    "successful": [],
    "failed": [
      {
        "index": 0,
        "customer_id": "invalid-customer-id",
        "tax_id": "123e4567-e89b-12d3-a456-426614174000",
        "errors": [
          {
            "code": "VALIDATION_ERROR",
            "messages": ["Customer ID must be provided in a valid format"]
          }
        ]
      }
    ],
    "summary": {
      "total_processed": 1,
      "success_count": 0,
      "error_count": 1
    }
  }
}

Error Codes

Code	Description
`VALIDATION_ERROR`	Request validation failed (missing fields, invalid format)
`INVALID_CUSTOMER_ID`	Customer ID does not exist or is invalid
`INVALID_TAX_ID`	Tax ID does not exist or is invalid
`CUSTOMER_TAX_UPDATE_ERROR`	Error occurred while updating customer tax assignment