2025-07 Customer API 2.0 Changes

Customer API 2.0 now supports tax identification management with the introduction of the tax_id field. Retailers can now associate specific tax configurations with individual customers.

API 2.0 Customer Endpoints

The following API 2.0 customer endpoints now support the tax_id field:

Create a new customer - POST /api/2.0/customers
Update a customer - PUT /api/2.0/customers/{customer_id}

Field Details

The tax_id field is optional and accepts a string value or null. The tax_id must match one of the taxes configured in the retailer's settings. This allows retailers to store and update tax identification information for individual customers.

Implementation Details

POST /api/2.0/customers

PUT /api/2.0/customers/{customer_id}

Request Body:

Accepts tax_id field
Value can be string or null
Backward compatible when tax_id field is not sent in the request

Validation:

Invalid tax ID format → returns 400 with error message indicating an invalid tax ID was provided
Tax ID does not match retailer's configured sale taxes → returns 400 with error message
Customer ID must be valid

Behavior:

If tax_id is null/empty, existing customer tax record is deleted and null is returned in response
If tax_id is a valid string, record is created/updated in vend_customer_tax table
If tax_id is not sent in the request, no update will be made to the customer tax

Response Format:

200 OK: Customer tax created/updated/deleted successfully. The response body includes the tax_id field
400 Bad Request: Validation error (e.g., invalid tax ID format, tax ID and/or customer ID is invalid)

Example Usage

API 2.0 Create Customer Request:

{
  "first_name": "John",
  "last_name": "Doe",
  "email": "[email protected]",
  "company_name": "Doe Enterprises",
  "tax_id": "123456789"
}

API 2.0 Update Customer Request:

{
  "tax_id": "987654321"
}

Setting tax_id to null (removes existing tax record):

{
  "tax_id": null
}

Error Responses

400 Bad Request - Invalid Data Type:

{
"errors": {
        "field": {
            "tax_id": "The value is not a valid string."
        }
    }
}

400 Bad Request - Invalid Tax ID:

{
    "errors": {
        "field": {
            "tax_id": "Invalid tax ID provided"
        }
    }
}

Migration Guide

For existing integrations:

No changes required - the tax_id field is optional and backward compatible
Existing customer records without tax ID will continue to function normally
Add tax_id field to your customer creation/update payloads when tax identification is needed

Retrieving Available Tax IDs:

Use /api/2.0/taxes endpoint to get all configured taxes for the retailer
Look for taxes with appropriate name and rate values that match your requirements