Update a customer
AI agents: read /llms.txt; add .md to any page URL. This page as Markdown: /reference/customers/v1-customer-update-put.md. Index of every page and the rules for every call: /llms.txt. Guides and concepts in one file: /llms-full.txt. OpenAPI: /openapi.json.
PUT/
Changes the customer's own fields. Send only the fields you want to change. Contacts, addresses and brand profiles have their own operations.
Use PUT: it checks the fields below. PATCH takes the same body but checks nothing. Returns the customer with contacts.
Business rules
is_externalandexternal_typeare ignored on customers and their contacts: sending them (for example a value you read back) is not refused and changes nothing. Only the Shopify sync sets them. Other fields not listed here are not part of the API.- 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."). default_warehouse_idmust be a current company location of the team.- A new
default_pricing_group_idmust be one of the team's published pricing groups that is turned on. Sending the customer's current group again is fine even if it was turned off since. default_payment_term_id,default_pricing_group_id,default_warehouse_id,customer_portal_payment_optionandcustomer_portal_enabledcan be cleared withnull. Any other field sent asnullis dropped; send an empty string to blank a text field.- Changing the defaults affects new sales orders only; existing ones keep theirs.
Side effects
- Sends the
customer.updatedwebhook. - Open Customer Portal pages of this customer are told to refresh.
Path parameters
Your team slug, shown as Team ID next to your API key in Profile.
- Example
your-team
- Example
The customer's id (
idfrom List customers or Create a customer). A hash id from an earlier answer; unique keys and document numbers (such asPO0042) don't work here.- Example
EDhVUaC6jbLbed
- Example
Request body
application/json, required.
customer_portal_enabledboolean | nullfalseturns the Customer Portal off for this customer: its contacts can no longer open the portal, through existing links or signed-in sessions.trueor null turns it back on. Its records and payment settings are kept.customer_portal_payment_optionstring | nullNull goes back to the team setting.
- One of:
"ENABLED","DISABLED"
- One of:
default_payment_term_idstring | nullA payment term id, or null to clear it.
default_pricing_group_idstring | nullA pricing group id, or null to clear it. New sales orders for this customer use it. Pricing groups are not listed on the public API: copy
pricing_group_idfrom a sales order or quote that uses the group (Get a sales order or quote), ordefault_pricing_group_idfrom another customer that has it.default_warehouse_idstring | nullA current company location (store location) id, or null to clear it. New sales orders for this customer ship from it.
hidebooleanTrue archives the customer, false brings it back.
internal_notesstringNotes for your team only.
namestringThe customer's name, usually the company.
resale_numberstringThe customer's resale or tax certificate number.
tax_exemptbooleanTrue when no sales tax applies to this customer.
default_carrier_accountstarts the customer's shipping labels on its default carrier account;nonestarts them with no third-party billing.- One of:
"none","default_carrier_account"
- One of:
vat_numberstringTax number.
websitestringThe website address.
More examples (2)
Set the defaults new orders use
curl -X PUT 'https://secure.yoprint.com/v1/api/store/your-team/customer/EDhVUaC6jbLbed' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Accept: application/json' \ -H 'X-Yoprint-Decimal-Format: exact-v1' \ -H 'Content-Type: application/json' \ -d '{ "default_payment_term_id": "bONlIEdEsNFoAl", "default_pricing_group_id": "lRnxHMMGPGfVN3", "default_warehouse_id": "ILBTtiKrRcSSGA" }'Turn the Customer Portal off for a customer
curl -X PUT 'https://secure.yoprint.com/v1/api/store/your-team/customer/EDhVUaC6jbLbed' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Accept: application/json' \ -H 'X-Yoprint-Decimal-Format: exact-v1' \ -H 'Content-Type: application/json' \ -d '{ "customer_portal_enabled": false }'Response
200Successful response.
Child fields (45)
True when the customer is archived.
The customer id. Use it in paths and as
customer_idon sales orders and quotes.False for Shopify and system customers: they can't be changed through this API.
Null for a customer created by upsert without a name.
True when the customer is deleted.
account_warningobject | nullWhy YoPrint shows a warning next to the customer's name. Null when there is nothing to warn about.
Child fields (2)
The customer's payments under a dispute that is open or under review; null when there is none.
Child fields (2)
How many payments are disputed.
The total of the disputed payments, each counted once. Thousandths, an older encoding:
125000is 125.00. See Money and quantities.
What the customer owes back because
wallet_fundis negative, as a positive amount; null when it is not negative. Thousandths, an older encoding:125000is 125.00. See Money and quantities.
addressesarray of objectsBilling and shipping addresses that are not deleted, old copies replaced by an edit included (
is_current_source: false).Fields of each item (33)
False for deleted, replaced, Shopify or redacted addresses. Only current addresses can be picked for new documents or edited.
Goes up by one on every saved change. Send it back as
base_revision_numberwhen updating the address to protect against concurrent edits.billingorshippingfor customer addresses.address2string | nulladdress_family_idstring | nullShared by an address and the copies made when it was edited after use.
citystring | nullcopied_from_address_idstring | nullcountrystring | nullcountry_codestring | nullcustomer_idstringCustomer addresses only: the customer's id.
external_typestring | nullshopifyfor an address synced from Shopify.hold_stockbooleanCompany locations only; false for customer addresses.
is_default_warehousebooleanCompany locations only; false for customer addresses.
is_externalbooleanTrue for an address synced from Shopify; such addresses are read-only.
nexusbooleanCompany locations only; false for customer addresses.
notestring | nullowner_idstring | nullThe owner's id: for a customer address, the customer's id (the same as
customer_id).owner_typestringcustomerfor customer addresses.- One of:
"customer","team","unknown"
- One of:
postal_can_validatebooleanpostal_is_validbooleanpostal_validatedbooleanTrue once YoPrint has checked the address with its address validator.
postal_can_validatesays whether it could be checked andpostal_is_validgives the result. Any edit resets it to false.postcodestring | nullsourcestringcustomerfor customer addresses.- One of:
"customer","company_location","custom","unknown"
- One of:
statestring | nullstate_codestring | nullsuperseded_atstring (date-time) | nullsuperseded_by_address_idstring | nullSet on an old copy: the address that replaced it.
used_by_active_profilebooleanTrue when a brand profile uses it as Ship From. Sent on lists, reads, updates and customer answers; not on create or set-primary.
assigned_usersarray of objectsThe users assigned to the customer. Unlike List the users assigned to a customer, people who have left the team stay in this list.
Fields of each item (3)
contactsarray of objectsEvery contact, deleted ones included (
trashed).Fields of each item (18)
True when the contact is deleted.
customer_idstringCustomer contacts only.
default_receive_smsbooleanemailstring | nullexternal_typestring | nullfaxstring | nullfax_countrystring | nullis_externalbooleanTrue for a contact synced from Shopify; such contacts are read-only.
last_namestring | nullphonestring | nullphone_countrystring | nullsend_invoicebooleanCustomer contacts only.
vendor_idstringVendor contacts only.
customer_portal_enabledboolean | nullWhether the customer's contacts can open the Customer Portal (Portal settings > Customer portal in YoPrint).
false: the portal is off for this customer.true, or null (never set), means on.customer_portal_idstring | nullThe id used in the customer's portal address. Null for Shopify customers.
customer_portal_id_overridestring | nullAlways null: YoPrint no longer returns a portal sign-in link for the customer. The field stays for older integrations.
customer_portal_payment_optionstring | nullWhether the customer can pay online in the portal. Null follows the team setting (and is always null for Shopify customers).
- One of:
"ENABLED","DISABLED"
- One of:
customer_profilesarray of objectsBrand profiles.
Fields of each item (12)
The Ship From address, or null for a profile that has none.
New sales orders and quotes for the customer use the primary profile.
addressobject | nullThe Ship From address (an address, as in Customer addresses, without
used_by_active_profile), or null.- Same fields as
data.addresses.
- Same fields as
emailstring | nulllogoobject | nullThe newest logo file (a file, as in Customer files), or null.
Child fields (18)
Customer files:
tax_exemption,internal_fileorexternal_file. Vendor files:default,mockuporproduction_file.The display name.
Bytes.
custom_propertiesobject | arraycustomer_idstringCustomer files only.
dimensionsobject | nullPixel size of an image, read from its header; null for other files and for images uploaded before the size was recorded.
is_imagebooleanpositioninteger | nullWhere the file sorts.
previewobject | nullPreview image links
small,mediumandlarge(250, 800 and 1200 px), or null when there is no preview.preview_statestringready: the preview links work.processing: an image over 10 MB whose stored preview a worker is still making (seconds); read the file again, or in the web app wait formedia.preview_state_changedon the team channel.too_large: an image over 120 megapixels; it never gets a preview.failed: the worker gave up.none: not an image.- One of:
"ready","processing","too_large","failed","none"
- One of:
show_in_pdfboolean | nullsource_media_idstring | nullurlstring | nullWhere to download the file.
view_urlstring | nullA signed link to view the file. It expires: read it fresh, and don't store it.
phonestring | nullwebsitestring | null
default_payment_term_idstring | nulldefault_pricing_group_idstring | nulldefault_warehouse_idstring | nulldeposit_due_amountinteger | number | stringDeposits still due. Thousandths, an older encoding:
125000is 125.00. Usually a whole number; an amount finer than a thousandth comes back as a number with a fraction (1234.5is 1.2345), or as a string ("1234.5") when you sendX-Yoprint-Decimal-Format: exact-v1. See Money and quantities.The Customer Portal ID shown to people: the override when set, otherwise
customer_portal_id.-for Shopify customers.external_typestring | nullshopifyfor customers synced from Shopify.held_creditinteger | number | stringThe part of
wallet_fundheld while a payment is under an open dispute or a provider review: it can't be applied to orders or taken out until the hold ends. Never more thanwallet_fund; 0 whenwallet_fundis 0 or negative. Thousandths, an older encoding:125000is 125.00. Usually a whole number; an amount finer than a thousandth comes back as a number with a fraction (1234.5is 1.2345), or as a string ("1234.5") when you sendX-Yoprint-Decimal-Format: exact-v1. See Money and quantities.internal_notesstring | nulllast_ordered_datestring (date-time) | nullThe issue date of the customer's latest published sales order. Null when it has none.
mediaarray of objects- Same fields as
data.customer_profiles[].logo.
- Same fields as
ordered_amountinteger | number | stringTotal of the customer's published sales orders. Thousandths, an older encoding:
125000is 125.00. Usually a whole number; an amount finer than a thousandth comes back as a number with a fraction (1234.5is 1.2345), or as a string ("1234.5") when you sendX-Yoprint-Decimal-Format: exact-v1. See Money and quantities.overdue_amountinteger | number | stringUnpaid amounts past their payment due date. Thousandths, an older encoding:
125000is 125.00. Usually a whole number; an amount finer than a thousandth comes back as a number with a fraction (1234.5is 1.2345), or as a string ("1234.5") when you sendX-Yoprint-Decimal-Format: exact-v1. See Money and quantities.pdfobjectChild fields (1)
A link that downloads the customer's invoice statement PDF. Its token opens only this customer's statement and stops working 9,000 hours (about a year) after the answer was made. Anyone with the link can download the statement: don't share it.
quote_amountinteger | number | stringTotal of open quotes. Thousandths, an older encoding:
125000is 125.00. Usually a whole number; an amount finer than a thousandth comes back as a number with a fraction (1234.5is 1.2345), or as a string ("1234.5") when you sendX-Yoprint-Decimal-Format: exact-v1. See Money and quantities.resale_numberstring | nullshopify_compliance_deletionobject | nullsystem_typestring | nulltagsarray of objectsHow a shipping label for this customer is billed by default.
default_carrier_account: YoPrint's label and rate dialogs start on the customer's default carrier account (third-party billing).none: they start with no third-party billing.- One of:
"none","default_carrier_account"
- One of:
unpaid_amountinteger | number | stringWhat the customer still owes on published sales orders. Thousandths, an older encoding:
125000is 125.00. Usually a whole number; an amount finer than a thousandth comes back as a number with a fraction (1234.5is 1.2345), or as a string ("1234.5") when you sendX-Yoprint-Decimal-Format: exact-v1. See Money and quantities.vat_numberstring | nullThe customer's tax number (shown as Tax number in YoPrint).
wallet_currencyobjectThe team's default currency, the one
wallet_fundis in.isois its code.wallet_fundinteger | number | stringCustomer credit balance. Negative when the customer owes credit back, for example after a refund of a payment whose credit was already spent. Thousandths, an older encoding:
125000is 125.00. Usually a whole number; an amount finer than a thousandth comes back as a number with a fraction (1234.5is 1.2345), or as a string ("1234.5") when you sendX-Yoprint-Decimal-Format: exact-v1. See Money and quantities.websitestring | null
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, withunauthorizedoruser_is_not_authorized.- When
- Your role can't change this customer: it has no Manage Customers permission, or it manages only customers assigned to you and this one is not. This 403 has a short body,
{"message": "No Permission to update Customer"}. - Fix
- Ask for Manage Customers "Manage All", or to be assigned to the customer.
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 live customer with this id in the team: deleted customers are not found here.
error.codeis null anderror.messagenames the record type. - Fix
- Check the id. Find deleted customers with the
trashed_onlyfilter and restore them first.
409
default_warehouse_idnames a company location that is deleted, synced from another system or redacted (blocked_external_or_compliance;current_addressis that location), or one replaced by an edit (blocked_superseded_historical_address;current_addressis its replacement). Not the usual error envelope:success: false,address_save_resultandmessage(thesave_mode); nostatusorerror.- When
default_warehouse_idnames a company location that was replaced by an edit (address_save_result.save_modeblocked_superseded_historical_address), or one that was deleted, is synced from another system or was redacted (blocked_external_or_compliance). Not the usual error envelope: the body hassuccess: false,address_save_resultandmessage.- Fix
- For
blocked_superseded_historical_address, useaddress_save_result.current_address.id. Forblocked_external_or_compliance,current_addressis the same location: pick another current one from List company locations.
422The request was refused and changed nothing.
validation_failedlists what to fix inerror.fields; other codes name a business rule, explained inerror.message. A few checks answer with only{"message": "..."}. An operation that calls another service (a payment provider, a carrier, an accounting app) can answerconnect_timeout("Please retry again") when that service does not answer in time: the change may or may not have happened there, so read the record back before you retry.- When
default_warehouse_idis not a company location of the team (error.codeinvalid_default_warehouse), or a field has the wrong type (validation_failed).- Fix
- Use the id of a current company location from List company locations; check the field types.
- When
default_pricing_group_idcan't be used: not one of the team's published groups (validation_error, "Choose one of your pricing groups." ondefault_pricing_group_idinerror.fields), removed (pricing_group_removed, witherror.pricing_group), or turned off (pricing_group_disabled, witherror.pricing_groupanderror.fields).- Fix
- Copy
pricing_group_idfrom a sales order that uses a live group, or turn the group on in Pricing groups. - When
- The customer comes from Shopify, or is a system customer (
error.codevalidation_error, with the reason inerror.message). - Fix
- Change Shopify customers in Shopify. System customers cannot be changed.
Related
- GETGet a customer
/v1/ api/ store/ {team_slug}/ customer/ {hash_id} - PATCHUpdate a customer contact (PATCH)
/v1/ api/ store/ {team_slug}/ customer/ {hash_id}/ contact/ {id} - PUTUpdate a customer address
/v1/ api/ store/ {team_slug}/ customer/ {hash_id}/ address/ {id} - GETList company locations
/v1/ api/ store/ {team_slug}/ setting/ location - GETList payment terms
/v1/ api/ store/ {team_slug}/ setting/ payment_term
