Update Customer

Updates an existing customer. Only the provided fields will be updated.

Endpoint

PATCH /v1/customers/:id

Authentication

Requires API key authentication via X-API-Key header.

Path Parameters

Parameter	Type	Description
id	string	The customer ID

Request Body

All fields are optional. Only provided fields will be updated.

Parameter	Type	Description
email	string	Customer's email address
name	string	Customer's full name
phone	string	Customer's phone number
address	object	Customer's address
address.line1	string	Street address line 1
address.line2	string	Street address line 2
address.city	string	City
address.state	string	State or province
address.postalCode	string	Postal or ZIP code
address.country	string	Two-letter country code
companyName	string	Company name (for B2B)
taxId	string	Tax ID or VAT number
description	string	Internal description or notes
metadata	object	Arbitrary key-value pairs (replaces existing metadata)

Example Request

curl -X PATCH https://api.example.com/v1/customers/cus_abc123def456 \
  -H "X-API-Key: sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "[phone]",
    "address": {
      "line1": "456 Oak Ave",
      "city": "Los Angeles",
      "state": "CA",
      "postalCode": "90001",
      "country": "US"
    },
    "metadata": {
      "tier": "platinum",
      "referral_code": "REF123"
    }
  }'

Example Response

{
  "id": "cus_abc123def456",
  "object": "customer",
  "email": "[email protected]",
  "name": "John Doe",
  "phone": "[phone]",
  "address": {
    "line1": "456 Oak Ave",
    "line2": null,
    "city": "Los Angeles",
    "state": "CA",
    "postalCode": "90001",
    "country": "US"
  },
  "companyName": "Acme Inc",
  "taxId": "12-3456789",
  "description": "VIP customer",
  "metadata": {
    "tier": "platinum",
    "referral_code": "REF123"
  },
  "created": 1706554800,
  "updated": 1706558400
}

Errors

Code	Description
400	Invalid request body
401	Invalid or missing API key
404	Customer not found or doesn't belong to your merchant account
409	Email already in use by another customer