Brainerce
Help CenterPricingResourcesDashboard
API ReferenceEndpointsCustomersUpdate a customer address

Update a customer address

Supports Idempotency-Key header for safe retries.

PATCH
/v1/customers/{id}/addresses/{addressId}

Authorization

AuthorizationBearer <token>

Admin API key (server-to-server). Issue via the dashboard at Settings → API keys. Plain-text key is shown once — store in a secret manager. Format: Authorization: Bearer brainerce_xxxxxxxxx.

In: header

Path Parameters

idstring

Customer ID

addressIdstring

Address ID

Header Parameters

Idempotency-Key?string

Client-supplied key (a UUID v4 is the recommended form, max 255 characters) that makes this mutation safe to retry.

  • Replay window: 24 hours. The first response for a key is cached; a retry inside the window with the same request body returns the original status and body without re-running the handler.
  • Reusing a key with a different body returns 409 Conflict with code: "IDEMPOTENCY_KEY_REUSED". The request fingerprint (method + path + body hash) is compared against the stored one; a mismatch is refused rather than served the old response.
  • Keys are scoped to the calling credential and store — two API keys may safely use the same key value.
  • Error responses are cached too, so a retry of a request that failed validation returns the same 400 immediately.
  • Sending this header on a GET returns 400 with code: "IDEMPOTENCY_KEY_NOT_SUPPORTED" — GETs are already idempotent.
  • Support is per-route and this parameter is the authoritative signal: a key sent to a route that does not declare it is accepted and silently ignored.

See /docs/api/idempotency.

Lengthlength <= 255

Request Body

label?string

Friendly label.

firstName?string

First name.

lastName?string

Last name.

company?string

Company.

line1?string

Street line 1.

line2?string

Street line 2.

city?string

City.

region?string

State / Province.

postalCode?string

Postal / ZIP.

country?string

ISO country code.

phone?string

Phone.

isDefault?boolean

Promote this address to be the customer's default.

curl -X PATCH "https://api.brainerce.com/api/v1/customers/string/addresses/string" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{}'
{
  "id": "addr_abc123",
  "label": "Home",
  "firstName": "Jane",
  "lastName": "Doe",
  "company": "Acme Inc",
  "line1": "123 Main St",
  "line2": "Apt 4B",
  "city": "San Francisco",
  "region": "CA",
  "postalCode": "94103",
  "country": "US",
  "phone": "+14155552671",
  "isDefault": true,
  "createdAt": "2025-08-01T09:00:00.000Z",
  "updatedAt": "2026-05-12T11:24:08.000Z"
}

{
  "statusCode": 400,
  "code": "VALIDATION_FAILED",
  "message": "name should not be empty, price must be a positive number",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/customers/{id}/addresses/{addressId}"
}

{
  "statusCode": 401,
  "code": "UNAUTHORIZED",
  "message": "Invalid or expired credential",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/customers/{id}/addresses/{addressId}"
}

{
  "statusCode": 403,
  "code": "INSUFFICIENT_SCOPE",
  "message": "API key does not have the required scope: products:write",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/customers/{id}/addresses/{addressId}"
}

{
  "statusCode": 404,
  "code": "RESOURCE_NOT_FOUND",
  "message": "Resource not found",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/customers/{id}/addresses/{addressId}"
}

{
  "statusCode": 429,
  "code": "RATE_LIMITED",
  "message": "Too many requests",
  "details": {
    "retryAfterSeconds": 12
  },
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/store"
}

Add a customer address

Add a customer address. POST /v1/customers/{id}/addresses in the Brainerce API.

Delete a customer address

Delete a customer address. DELETE /v1/customers/{id}/addresses/{addressId} in the Brainerce API.