Add an address to a customer

POST/v1/api/store/{team_slug}/customer/{hash_id}/address

v1Operation ID v1_public_customer_address_store

Adds a billing or shipping address and returns it.

The first address of each role becomes primary; later ones don't, whatever is_primary says. Use Set the primary address to change it.

Permission

Needs the Manage Customers permission ("Manage All" or "Manage Assigned to User"). Whether the customer is assigned to you is not checked.

Business rules

state_code and country_code are trimmed and upper-cased.
Works on a deleted customer too: the address is added to it.
For US and CA, state or state_code must name a real state or province; YoPrint stores the name and the code together.
Customers synced from Shopify are read-only here: changes are refused with 422 validation_error "External customers are read-only. Manage changes from Shopify." System customers (is_system: true) are refused the same way ("System customer cannot be modified or deleted.").

Path parameters

team_slugstringrequired
Your team slug, shown as Team ID next to your API key in Profile.
- Example your-team
hash_idstringrequired
The customer's id (id from List customers or Create a customer). A hash id from an earlier answer; unique keys and document numbers (such as PO0042) don't work here.
- Example EDhVUaC6jbLbed

Request body

application/json, required.

address1stringrequired
Required. Street line 1.
country_codestringrequired
Required. Two-letter country code, such as US.
is_primarybooleanrequired
Required, but the first address of each role always becomes primary and later ones never do. Use the set-primary operation to change it.
labelstringrequired
Required. A name for the address, shown in pickers: "Head office".
rolestringrequired
Required. What the address is for.
- One of: "billing", "shipping"
address2string
Street line 2, such as a suite or unit.
citystring
The city.
countrystring
The country name. Shown as the country of country_code when blank.
notestring
A note kept with the address, such as delivery instructions.
postcodestring
The postal or ZIP code.
statestring
The state or province name, such as "Illinois". For US and Canada addresses, send either state or state_code (or both matching): YoPrint resolves and stores both. For other countries, send the name in state. Sending null is ignored; omit the field to leave it unset.
state_codestring
The two-letter state or province code, such as IL or ON. Used for US and Canada addresses: send either state_code or state. Sending null is ignored; omit the field to leave it unset.

Response

200Successful response.

dataobjectrequired
Child fields (33)
- address1string | nullrequired
- idstringrequired
- is_current_sourcebooleanrequired
  False for deleted, replaced, Shopify or redacted addresses. Only current addresses can be picked for new documents or edited.
- is_primarybooleanrequired
- labelstring | nullrequired
- revision_numberintegerrequired
  Goes up by one on every saved change. Send it back as base_revision_number when updating the address to protect against concurrent edits.
- rolestringrequired
  billing or shipping for customer addresses.
- trashedbooleanrequired
- address2string | null
- address_family_idstring | null
  Shared by an address and the copies made when it was edited after use.
- citystring | null
- copied_from_address_idstring | null
- countrystring | null
- country_codestring | null
- customer_idstring
  Customer addresses only: the customer's id.
- external_typestring | null
  shopify for an address synced from Shopify.
- hold_stockboolean
  Company locations only; false for customer addresses.
- is_default_warehouseboolean
  Company locations only; false for customer addresses.
- is_externalboolean
  True for an address synced from Shopify; such addresses are read-only.
- nexusboolean
  Company locations only; false for customer addresses.
- notestring | null
- owner_idstring | null
  The owner's id: for a customer address, the customer's id (the same as customer_id).
- owner_typestring
  customer for customer addresses.
  - One of: "customer", "team", "unknown"
- postal_can_validateboolean
- postal_is_validboolean
- postal_validatedboolean
  True once YoPrint has checked the address with its address validator. postal_can_validate says whether it could be checked and postal_is_valid gives the result. Any edit resets it to false.
- postcodestring | null
- sourcestring
  customer for customer addresses.
  - One of: "customer", "company_location", "custom", "unknown"
- statestring | null
- state_codestring | null
- superseded_atstring (date-time) | null
- superseded_by_address_idstring | null
  Set on an old copy: the address that replaced it.
- used_by_active_profileboolean
  True when a brand profile uses it as Ship From. Sent on lists, reads, updates and customer answers; not on create or set-primary.
statusintegerrequired
successbooleanrequired

Errors

401The API key is missing or wrong (unauthenticated).
403You are not allowed to do this. api_access_not_in_plan: your team's plan doesn't include API access (Pro and above, with an active subscription or trial), so every request answers this until the team upgrades. When your role lacks the permission the operation needs, the body is only {"message": "Insufficient Permission"}. Other refusals use the error envelope, with unauthorized or user_is_not_authorized.
When
Your role has no Manage Customers permission. This 403 has a short body, {"message": "Insufficient Permission"}, with no success or error.
Fix
Ask a team owner to give your role Manage Customers.
404Not found. page_not_found: the team slug is unknown, you are not a member of the team, or an id in the path is not one of this team's. code: null, with a message that starts "No query results for": there is no record with that id.
When
No customer with this id in the team. Deleted customers are found here, so this also works on a deleted customer. error.code is null and error.message names the record type.
Fix
Check the id.
422Validation failed or external Shopify customers are read-only from this API.
When
role, label, address1, country_code or is_primary is missing, or a US or Canadian state can't be matched. error.code is validation_failed.
Fix
Fix each field named in error.fields; its keys are field paths such as contact.0.phone.
When
The customer comes from Shopify, or is a system customer (error.code validation_error, with the reason in error.message).
Fix
Change Shopify customers in Shopify. System customers cannot be changed.

PATCHSet the primary address/v1/api/store/{team_slug}/customer/{hash_id}/address/{id}/primary
PUTUpdate a customer address/v1/api/store/{team_slug}/customer/{hash_id}/address/{id}

Example request

curl

curl -X POST 'https://secure.yoprint.com/v1/api/store/your-team/customer/EDhVUaC6jbLbed/address' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{    "address1": "100 Example Street",    "address2": "Dock 9",    "city": "Springfield",    "country_code": "US",    "is_primary": false,    "label": "Second warehouse",    "postcode": "62701",    "role": "shipping",    "state_code": "IL"  }'

Example response 200

{
  "data": {
    "address1": "100 Example Street",
    "address2": "Dock 9",
    "address_family_id": null,
    "city": "Springfield",
    "copied_from_address_id": null,
    "country": "United States",
    "country_code": "US",
    "customer_id": "V4keXwwxMQyXw7",
    "external_type": null,
    "hold_stock": false,
    "id": "8mH5XMk0BBFeza",
    "is_current_source": true,
    "is_default_warehouse": false,
    "is_external": false,
    "is_primary": false,
    "label": "Second warehouse",
    "nexus": false,
    "note": null,
    "owner_id": "V4keXwwxMQyXw7",
    "owner_type": "customer",
    "postal_can_validate": false,
    "postal_is_valid": false,
    "postal_validated": false,
    "postcode": "62701",
    "revision_number": 1,
    "role": "shipping",
    "source": "customer",
    "state": "Illinois",
    "state_code": "IL",
    "superseded_at": null,
    "superseded_by_address_id": null,
    "trashed": false
  },
  "status": 200,
  "success": true
}

AI agents: read /llms.txt; add .md to any page URL for its Markdown. Guides and concepts in one file: /llms-full.txt.

Download the OpenAPI spec Support: support@yoprint.com yoprint.com