> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.solvimon.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.solvimon.com/_mcp/server. # Shipping addresses Where a customer's goods go, as a resource of its own: any number of addresses per customer, each with a recipient that is independent of the customer you bill. --- ## Why this matters A customer has one billing address, and that is rarely where the parcel goes. Goods are delivered to a site, a warehouse, a department or an employee's home, and the person receiving them is not the person who pays. Keeping that on the customer means one address, one name and no way to say which site an order is for. A shipping address is therefore a top-level resource with its own identifier, reference and lifecycle, linked to a [customer](/platform-guides/customers-and-billing/customer) by `customer_id`. A customer can hold as many as you need, one of them marked as the default. ## Create an address **`Request`** ```bash Request curl -X POST https://test.api.solvimon.com/v1/shipping-addresses \ -H "X-API-KEY: " \ -H "Content-Type: application/json" \ -d '{ "reference": "acme-warehouse-rotterdam", "customer_id": "cust_8Hq2pqJnwo42rzGV7abcd", "description": "Central warehouse, goods inwards", "recipient": { "type": "ORGANIZATION", "organization": { "company_name": "Acme Logistics BV", "attention_name": "Goods inwards" }, "phone_number": "+31101234567", "email": "inwards@example.com" }, "address": { "line1": "Waalhaven 12", "line2": "Unit 4", "city": "Rotterdam", "postal_code": "3087 BA", "country": "NL" } }' ``` **`Response`** ```json Response { "object_type": "SHIPPING_ADDRESS", "id": "shad_5RmXe2QbtKfYuA9DcNH3P", "reference": "acme-warehouse-rotterdam", "customer_id": "cust_8Hq2pqJnwo42rzGV7abcd", "description": "Central warehouse, goods inwards", "status": "DRAFT", "is_default": false, "created_at": "2026-10-20T09:14:52Z" } ``` An address is created `DRAFT`. `reference`, `customer_id`, `recipient` and `address` are required; `customer_id` is immutable afterwards, so an address cannot be moved to another customer. | Field | Required | Description | | ------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `reference` | Yes | Your own identifier, unique within the platform. Also accepted in place of the id in every path. | | `customer_id` | Yes | The customer the address belongs to. Cannot be changed. | | `description` | No | Free text, for telling several addresses apart in a list. | | `recipient` | Yes | Who receives the goods. See below. | | `address` | Yes | `line1`, `line2`, `city`, `postal_code`, `state` and `country`, the same shape used elsewhere in the API. `country` is an ISO 3166-1 alpha-2 code. | | `status` | Read-only | `DRAFT`, `ACTIVE` or `DEPRECATED`. | | `is_default` | Read-only | Whether this is the customer's default address. Set it with `set-as-default`. | ### The recipient is not the customer `recipient` describes who the parcel is addressed to, which is why it carries its own contact details rather than reusing the customer's. | Field | Description | | -------------- | ------------------------------------------------------------------------------------------------------------------------ | | `type` | `ORGANIZATION` or `INDIVIDUAL`. Decides which sub-object applies. | | `organization` | For `ORGANIZATION`: `company_name` and an optional `attention_name`, the department or person to route it to internally. | | `individual` | For `INDIVIDUAL`: a `name` with `first_name`, `infix` and `last_name`. | | `phone_number` | The number the carrier calls about this delivery. | | `email` | Where delivery notifications go. | The two sub-objects are mutually exclusive. Sending `individual` on an `ORGANIZATION` recipient is refused with `recipient.individual`, and `organization` on an `INDIVIDUAL` recipient with `recipient.organization`, so a recipient can never carry a company and a person at the same time. > **Tip** > > `INDIVIDUAL` is what you want for delivery to an employee's home address. The customer stays the company you invoice, and the parcel is addressed to the person. ## The lifecycle ```mermaid stateDiagram-v2 [*] --> DRAFT: create DRAFT --> ACTIVE: activate ACTIVE --> DEPRECATED: deprecate DRAFT --> [*]: delete DEPRECATED --> [*]: delete ``` | Status | What it means | | ------------ | ---------------------------------------------------------------------- | | `DRAFT` | Created but not in use. Edit it freely; it cannot be made the default. | | `ACTIVE` | In use. Can be set as the customer's default. | | `DEPRECATED` | Retired. Its default flag is cleared when it is deprecated. | `POST /v1/shipping-addresses/{id}/activate` moves a `DRAFT` address to `ACTIVE`, and `POST /v1/shipping-addresses/{id}/deprecate` retires an `ACTIVE` one. A `DELETE` removes an address that is `DRAFT` or `DEPRECATED`, which keeps an address that is live from disappearing under an order that references it. ## The default address One address per customer can be the default, for the case where a request names a customer but no address. **`Set the default`** ```bash Set the default curl -X POST https://test.api.solvimon.com/v1/shipping-addresses/acme-warehouse-rotterdam/set-as-default \ -H "X-API-KEY: " ``` Only an `ACTIVE` address can be the default, and setting one clears the flag on the address that held it, so a customer never has two. Deprecating the default clears the flag without choosing a successor: a customer can be left with no default, and your integration should handle that rather than assume one exists. ## Find an address [GET /v1/shipping-addresses](https://docs.solvimon.com/api-docs/configuration-api/shipping-addresses/get-shipping-addresses) lists them, with `customer_id` to narrow to one customer and the repeatable `statuses[]` to leave out the addresses you retired. **`The active addresses of one customer`** ```bash The active addresses of one customer curl -G https://test.api.solvimon.com/v1/shipping-addresses \ -H "X-API-KEY: " \ -d customer_id=cust_8Hq2pqJnwo42rzGV7abcd \ -d "statuses[]=ACTIVE" ``` A single address is read with [GET /v1/shipping-addresses/\{id}](https://docs.solvimon.com/api-docs/configuration-api/shipping-addresses/get-shipping-addresses-by-resource-id-or-reference), which takes the id or the reference, as do `PATCH` and `DELETE` and the three actions. ## Keep a system of record in sync `PUT /v1/shipping-addresses` upserts on `reference`: it creates the address when the reference is new and updates it when it is not. An ERP or order system that already owns these addresses can therefore replay its own records without first asking whether Solvimon has seen them, and without keeping a map of Solvimon ids. ## Edge cases * The endpoints need the `SHIPPING_ADDRESS` permissions: `VIEW` to read and list, `CREATE` to create, `UPDATE` to patch and to run the three actions, and `DELETE` to delete. The upsert needs `CREATE` and `UPDATE` together. * `PATCH` cannot change `customer_id`. Create a new address under the right customer instead. * Deleting is only for addresses that were never used or have been retired. Deprecate an `ACTIVE` address rather than trying to delete it. * Shipping addresses are API-only for now; there is no screen for them in Desk. ---