Create a customer
AI agents: read /llms.txt; add .md to any page URL. This page as Markdown: /reference/customers/v1-customer-store.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.
POST/
Creates a customer, with its contacts and its billing and shipping addresses, in one request. Returns the new customer with contacts and addresses.
Only customer.name and customer.tax_exempt are required. A sales order names one of the customer's contacts and its billing and shipping addresses (customer_contact_id, billing_address_id, shipping_address_id), so send them here or add them later. A contact needs at least a first name.
- Mark one contact
is_primary: trueto make it the primary contact. If none is marked, the customer has no primary contact until you set one. - The first billing address and the first shipping address become primary, whatever
is_primarysays. - You are assigned to the new customer.
When you later create a sales order or quote for this customer, it takes the customer's primary brand profile, default payment term, default pricing group and default warehouse. A default pricing group that was removed since is skipped: the order gets the team's default group.
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.- Everything is saved together or not at all.
- Each contact needs
first_name,send_invoiceandis_primary. A phone needsphone_countryand must be a valid number for that country. - Each address needs
label,address1,country_codeandis_primary. ForUSandCA,stateandstate_codemust name a real state or province; YoPrint fills in the other half of the pair. - At most one contact, one billing address and one shipping address may be sent with
is_primary: true(422 "You cannot set more than 1 primary address"). - Nothing checks for duplicate customers: two customers may share a name, an email or a phone. To find or create by contact email or phone, use Create or update a customer by contact (
customer/upsert). - On a live customer (not a system or Shopify customer) a contact's email is saved trimmed and in lower case, and two live contacts of the customer can't have the same email (compared the same way). Other customers may use the same email. So two contacts in one request can't share an email.
- Only
customer.default_payment_term_idis read as an id on create. To set a default pricing group or default warehouse, create the customer, then update it.
Side effects
- Sends the
customer.createdwebhook. - Assigns you to the customer.
- When the contact's email already belongs to a Customer Portal account on your team that can't open this customer yet, saving the contact gives that account access to this customer (active when the account is set up with a verified email or a password, invited otherwise). No email is sent.
Path parameters
Your team slug, shown as Team ID next to your API key in Profile.
- Example
your-team
- Example
Request body
application/json, required.
Child fields (11)
The customer's name, usually the company. Names need not be unique.
True when no sales tax applies to this customer.
customer_portal_enabledboolean | nullfalsecreates the customer with the Customer Portal off: its contacts can't open the portal. Leave it out, or sendtrueor null, for on.customer_portal_payment_optionstring | nullWhether the customer can pay online in the customer portal. Leave it out to follow the team setting.
- One of:
"ENABLED","DISABLED"
- One of:
default_payment_term_idstring | nullA payment term id. New sales orders for this customer use it.
hidebooleanTrue creates the customer archived. Not checked on create: send a JSON boolean.
internal_notesstringNotes for your team only.
resale_numberstringThe customer's resale or tax certificate number.
How the customer's shipping labels are billed by default (see the customer object). Leave it out for
none.- One of:
"none","default_carrier_account"
- One of:
vat_numberstringThe customer's tax number (Tax number in YoPrint).
websitestringThe website address.
billingarray of objectsBilling addresses. At most one may have
is_primary: true.Fields of each item (11)
Required. Street line 1.
Required. Two-letter country code, such as
US.Required, but the first address of each role always becomes primary and later ones never do. Use the set-primary operation to change it.
Required. A name for the address, shown in pickers: "Head office".
address2stringStreet line 2, such as a suite or unit.
citystringThe city.
countrystringThe country name. Shown as the country of
country_codewhen blank.notestringA note kept with the address, such as delivery instructions.
postcodestringThe postal or ZIP code.
statestringThe state or province name, such as "Illinois". For US and Canada addresses, send either
stateorstate_code(or both matching): YoPrint resolves and stores both. For other countries, send the name instate. Sendingnullis ignored; omit the field to leave it unset.state_codestringThe two-letter state or province code, such as
ILorON. Used for US and Canada addresses: send eitherstate_codeorstate. Sendingnullis ignored; omit the field to leave it unset.
contactarray of objectsThe customer's contacts. At most one may have
is_primary: true.Fields of each item (10)
Required. The contact's first name.
Required.
Required. Stored with the contact and returned as
send_invoice.default_receive_smsbooleanWhen this contact is set on a sales order, it receives text messages about the order by default. Saved as sent; defaults to false.
emailstring (email)The contact's email. Messages you send to this contact go here.
faxstringChecked as a real number for
fax_country.fax_countrystringTwo-letter country code of
fax.last_namestringThe contact's last name.
phonestringChecked as a real number for
phone_country. Sendphone_countrywith it.phone_countrystringTwo-letter country code of
phone, such asUS. Required withphone.
shippingarray of objectsShipping addresses. At most one may have
is_primary: true.- Same fields as
billing.
- Same fields as
More examples (1)
Just the required fields
curl -X POST 'https://secure.yoprint.com/v1/api/store/your-team/customer' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Accept: application/json' \ -H 'X-Yoprint-Decimal-Format: exact-v1' \ -H 'Content-Type: application/json' \ -d '{ "customer": { "name": "Northwind Apparel", "tax_exempt": 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 cannot create customers. This 403 has a short body,
{"message": "Insufficient Permission"}, with nosuccessorerror. - Fix
- Ask a team owner for the Manage Customers permission.
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.409
- When
- Two contacts in the request have the same email, ignoring case and surrounding spaces (
error.codecustomer_portal_duplicate_contact_email). Nothing is saved. - Fix
- Send each email once.
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
- A required field is missing, a phone is not valid for its country, a US or Canadian state can't be matched, or two items in one list are primary.
error.codeisvalidation_failed. - Fix
- Fix each field named in
error.fields; its keys are paths such ascontact.0.first_nameorbilling(for two primaries). - When
- On a live customer, the email is longer than 191 characters or is not a valid address (
error.codecustomer_portal_email_invalid, "Enter a valid email address using supported characters."). - Fix
- Send a valid email of at most 191 characters.
Notes
- A field sent as
nullis dropped before the request is read, exceptcustomer.default_payment_term_id,customer.customer_portal_payment_optionandcustomer.customer_portal_enabled, which are saved as null.
Related
- POSTCreate or update a customer by contact
/v1/ api/ store/ {team_slug}/ customer/ upsert - PATCHUpdate a customer (PATCH)
/v1/ api/ store/ {team_slug}/ customer/ {hash_id} - POSTAdd a contact to a customer
/v1/ api/ store/ {team_slug}/ customer/ {hash_id}/ contact - POSTAdd an address to a customer
/v1/ api/ store/ {team_slug}/ customer/ {hash_id}/ address - GETList payment terms
/v1/ api/ store/ {team_slug}/ setting/ payment_term
