Contact shipping and billing addresses

The address APIs manage the same records as Contacts > select a contact > Overview.
Use them to import address books, keep CRM data in sync, or build address maintenance
into a support tool or customer portal. The overview has Add shipping address,
Change billing address, and a default shipping address selection in the contact
details. Read access requires Contacts read permission; changes require Contacts write
permission.

Address	API	Where it is used today
Shipping address book	List/create at `/api/v2/contacts/:contact_id/shipping/addresses`; read/update/delete at `/api/v2/shipping/addresses/:id`	Contact overview and the default shipping source for new non-external orders when order shipping fields are empty.
Single contact billing address	GET/POST/PATCH `/api/v2/contacts/:contact_id/billing_address`	Contact overview, Stripe customer sync, and billing-address updates on non-terminal Stripe orders.

Update a delivery address

Find or upsert the contact, then list their shipping entries. The list is paginated.
PATCH the matching entry's nested address, or POST a new entry with a complete
street. Repeated POSTs insert separate entries, so a recurring sync should match an
existing entry first.
Set default: true on the intended shipping entry. Confirm the selection through
default_shipping_address_id on the contact.

The first shipping entry becomes default. Selecting a new default moves the pointer.
Deleting the current default clears it without promoting another entry; new
non-external orders fall back to the newest remaining entry. Existing order, invoice
and fulfillment shipping snapshots are not rewritten by changing this address book.

Update the contact's billing address

A contact has zero or one billing address. GET the contact's billing-address URL;
an accessible contact with no billing address returns 404. POST that same URL to
create it. A second POST returns 422 with a PATCH hint. PATCH updates the existing
address and returns 404 if none is set. There is no billing-address list or delete
operation.

Create with a contacts_billing_address wrapper:

{
  "contacts_billing_address": {
    "address_one": "1 Main St",
    "city": "Boise",
    "region": "ID",
    "country_code": "US",
    "postal_code": "83702"
  }
}

PATCH accepts partial street fields with the same wrapper. Responses include
contact_id, postal-address id and public_id, street fields, and timestamps.
The URL determines the contact; clients do not send owner-type or owner-ID fields.
Unsupported and read-only fields are ignored. Country and region values are
validated, and invalid writes leave the saved address unchanged.

Checkout and order boundaries

API-created shipping entries are not checkout-authenticated, so they do not
automatically appear in saved-address checkout prefill. Billing prefill comes from
payment methods; updating the contact billing address does not replace a payment
method's billing address. Use these APIs for the contact's stored details without
promising automatic checkout prefill.

External order imports accept their own flat shipping and billing fields. The
Orders API does not take a shipping-entry ID or contact billing-address ID. An
integration can read a saved address and copy its fields into an imported order.
Changing a saved shipping entry does not redirect a shipment already created.

Using an AI agent

In MCP's Contacts category, use shipping_address for address-book CRUD.
Use contact_billing_address for fetch, create or update, with the contact public
ID as parent_id and no address id. Always pass the consented workspace_id.
The underlying street fields are passed flat under attributes for billing.

For request examples, default selection, geography and MCP arguments, use the
Contacts skill.