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
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.
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.
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
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:
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.
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.
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 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.
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_ADDRESSpermissions:VIEWto read and list,CREATEto create,UPDATEto patch and to run the three actions, andDELETEto delete. The upsert needsCREATEandUPDATEtogether. PATCHcannot changecustomer_idorstatus. Create a new address under the right customer instead, and move the status withactivateanddeprecate.- Deleting is only for addresses that were never used or have been retired, and only once no subscription points at them. Deprecate an
ACTIVEaddress rather than trying to delete it. - A recipient’s
typeis not a free switch: changing it drops the sub-object of the old type rather than carrying the details over, so send the neworganizationorindividualin the same request. - Shipping addresses are API-only for now; there is no screen for them in Desk.