Skip to navigation

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 by customer_id. A customer can hold as many as you need, one of them marked as the default.

Create an address

Request
curl -X POST https://test.api.solvimon.com/v1/shipping-addresses \
-H "X-API-KEY: <apiKey>" \
-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
{
"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 unless you pass status. reference, customer_id, recipient and address are required; customer_id is immutable afterwards, so an address cannot be moved to another customer.

Pass "status": "ACTIVE" to create an address that is usable straight away, which is what an import from an ERP or an order system wants: the address is known to be good, and the extra activate call per record buys nothing. DEPRECATED is refused on create, with status must be DRAFT or ACTIVE on creation. The customer has to be open: creating an address under a CLOSED or ARCHIVED customer is refused on customer_id.

FieldRequiredDescription
referenceYesYour own identifier, unique within the platform. Also accepted in place of the id in every path.
customer_idYesThe customer the address belongs to. Cannot be changed.
descriptionNoFree text, for telling several addresses apart in a list.
recipientYesWho receives the goods. See below.
addressYesline1, line2, city, postal_code, state and country, the same shape used elsewhere in the API. country is an ISO 3166-1 alpha-2 code.
statusNoDRAFT (the default) or ACTIVE on create. Read-only afterwards: a PATCH that sends status is refused, and the status moves through activate and deprecate.
is_defaultRead-onlyWhether 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.

FieldDescription
typeORGANIZATION or INDIVIDUAL. Decides which sub-object applies.
organizationFor ORGANIZATION: company_name and an optional attention_name, the department or person to route it to internally.
individualFor INDIVIDUAL: a name with first_name, infix and last_name.
phone_numberThe number the carrier calls about this delivery.
emailWhere 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.

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

create create with status ACTIVE activate deprecate delete delete DRAFT ACTIVE DEPRECATED
StatusWhat it means
DRAFTCreated but not in use. Edit it freely; it cannot be made the default.
ACTIVEIn use. Can be set as the customer’s default.
DEPRECATEDRetired. 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. Each refuses any other starting status, so the two calls are not a general status setter.

A DELETE removes an address that is DRAFT or DEPRECATED, which keeps a live address from disappearing under an order that references it. Two refusals to expect:

RefusalWhen
ACTIVE shipping addresses can not be deleted, deprecate it firstThe address is ACTIVE.
shipping address is linked to a subscription, clear the subscription shipping address firstA subscription still points at it through default_shipping_address_id, whatever the address’s status.

The second one is the common surprise: deprecating an address does not detach it from the subscriptions that use it. Clear or repoint default_shipping_address_id on each of them first.

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
curl -X POST https://test.api.solvimon.com/v1/shipping-addresses/acme-warehouse-rotterdam/set-as-default \
-H "X-API-KEY: <apiKey>"

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.

Attach an address to a subscription

A subscription carries default_shipping_address_id, the address its goods go to. Set it on create or with a PATCH, and clear it by sending null.

Point a subscription at an address
curl -X PATCH https://test.api.solvimon.com/v1/pricing-plan-subscriptions/ppsu_8Hq2pqJnwo42rzGV7abcd \
-H "X-API-KEY: <apiKey>" \
-H "Content-Type: application/json" \
-d '{ "default_shipping_address_id": "shad_5RmXe2QbtKfYuA9DcNH3P" }'

The address has to be ACTIVE and belong to the subscription’s customer; a DRAFT or DEPRECATED one is refused with shipping address must be ACTIVE but is currently DRAFT, and an address under another customer with shipping address must belong to the subscription customer. A template subscription cannot hold one at all, since it has no customer to validate against.

An existing link survives the address being deprecated: the field keeps pointing at it, and only a request that sets the field again has to satisfy the ACTIVE rule. That is what keeps a running subscription working after you retire an address, and also what blocks the delete.

Collect the address during subscription initialisation

POST /v1/pricing-plan-subscriptions/init takes a shipping_address block alongside customer and pricing_plan_subscription, which covers the signup flow where the address arrives with the order rather than before it.

The shipping_address block
{
"customer": { "reference": "acme" },
"shipping_address": {
"reference": "acme-warehouse-rotterdam",
"description": "Central warehouse, goods inwards",
"recipient": {
"type": "ORGANIZATION",
"organization": { "company_name": "Acme Logistics BV" },
"phone_number": "+31101234567",
"email": "inwards@example.com"
},
"address": {
"line1": "Waalhaven 12",
"city": "Rotterdam",
"postal_code": "3087 BA",
"country": "NL"
}
},
"pricing_plan_subscription": { "reference": "acme-standard" }
}

The block upserts on reference against the customer the call resolves, activates the address if it was DRAFT, and links it to the subscription being created. Replaying the same order therefore updates the address instead of failing on a duplicate reference. It does not touch the customer’s default.

It is one or the other: sending shipping_address together with pricing_plan_subscription.default_shipping_address_id is refused with cannot be combined with pricing_plan_subscription.default_shipping_address_id. Use the block when the caller holds the address details, and the id when the address already exists in Solvimon.

Let the customer enter it in checkout

Set init_pricing_plan_subscription.use_shipping_addresses to true on a portal URL and hosted checkout asks the customer for a shipping address, so you do not have to hold one before the order exists. The flag can also be turned on or off on an existing portal URL.

The portal serves its own /shipping-addresses endpoints for that: list, create, read, update and deprecate. Every one of them checks that the address belongs to the signed-in portal user’s customer, so a portal session can only ever see and change that customer’s addresses. There is no activate, set-as-default or DELETE on the portal side: those stay with your own integration.

Find an address

GET /v1/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
curl -G https://test.api.solvimon.com/v1/shipping-addresses \
-H "X-API-KEY: <apiKey>" \
-d customer_id=cust_8Hq2pqJnwo42rzGV7abcd \
-d "statuses[]=ACTIVE"

A single address is read with GET /v1/shipping-addresses/{id}, 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 or status. Create a new address under the right customer instead, and move the status with activate and deprecate.
  • Deleting is only for addresses that were never used or have been retired, and only once no subscription points at them. Deprecate an ACTIVE address rather than trying to delete it.
  • A recipient’s type is not a free switch: changing it drops the sub-object of the old type rather than carrying the details over, so send the new organization or individual in the same request.
  • Shipping addresses are API-only for now; there is no screen for them in Desk.