Skip to content

Create a customer

Open .md

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

v1Operation ID v1_public_customer_store

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: true to 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_primary says.
  • 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.

Permission

Needs the Manage Customers permission (either level can create customers).

Business rules

  • is_external and external_type are 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_invoice and is_primary. A phone needs phone_country and must be a valid number for that country.
  • Each address needs label, address1, country_code and is_primary. For US and CA, state and state_code must 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_id is 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.created webhook.
  • 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

  • team_slugstringrequired

    Your team slug, shown as Team ID next to your API key in Profile.

    • Example your-team

Request body

application/json, required.

  • customerobjectrequired
    Child fields (11)
    • namestringrequired

      The customer's name, usually the company. Names need not be unique.

    • tax_exemptbooleanrequired

      True when no sales tax applies to this customer.

    • false creates the customer with the Customer Portal off: its contacts can't open the portal. Leave it out, or send true or null, for on.

    • Whether the customer can pay online in the customer portal. Leave it out to follow the team setting.

      • One of: "ENABLED", "DISABLED"
    • A payment term id. New sales orders for this customer use it.

    • hideboolean

      True creates the customer archived. Not checked on create: send a JSON boolean.

    • Notes for your team only.

    • The 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"
    • The customer's tax number (Tax number in YoPrint).

    • websitestring

      The website address.

  • billingarray of objects

    Billing addresses. At most one may have is_primary: true.

    Fields of each item (11)
    • 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".

    • 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.

    • 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.

  • contactarray of objects

    The customer's contacts. At most one may have is_primary: true.

    Fields of each item (10)
    • first_namestringrequired

      Required. The contact's first name.

    • is_primarybooleanrequired

      Required.

    • send_invoicebooleanrequired

      Required. Stored with the contact and returned as send_invoice.

    • When 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.

    • faxstring

      Checked as a real number for fax_country.

    • Two-letter country code of fax.

    • last_namestring

      The contact's last name.

    • phonestring

      Checked as a real number for phone_country. Send phone_country with it.

    • Two-letter country code of phone, such as US. Required with phone.

  • shippingarray of objects

    Shipping addresses. At most one may have is_primary: true.

More examples (1)

Just the required fields

curl
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.

  • dataobjectrequired
    Child fields (45)
    • created_atstring (date-time)required
    • hidebooleanrequired

      True when the customer is archived.

    • idstringrequired

      The customer id. Use it in paths and as customer_id on sales orders and quotes.

    • is_editablebooleanrequired

      False for Shopify and system customers: they can't be changed through this API.

    • is_externalbooleanrequired
    • is_systembooleanrequired
    • namestring | nullrequired

      Null for a customer created by upsert without a name.

    • tax_exemptbooleanrequired
    • trashedbooleanrequired

      True when the customer is deleted.

    • updated_atstring (date-time)required
    • account_warningobject | null

      Why YoPrint shows a warning next to the customer's name. Null when there is nothing to warn about.

      Child fields (2)
      • open_disputeobject | nullrequired

        The customer's payments under a dispute that is open or under review; null when there is none.

        Child fields (2)
        • countintegerrequired

          How many payments are disputed.

        • payment_amountinteger | number | stringrequired

          The total of the disputed payments, each counted once. Thousandths, an older encoding: 125000 is 125.00. See Money and quantities.

      • owed_amountinteger | number | string | nullrequired

        What the customer owes back because wallet_fund is negative, as a positive amount; null when it is not negative. Thousandths, an older encoding: 125000 is 125.00. See Money and quantities.

    • addressesarray of objects

      Billing and shipping addresses that are not deleted, old copies replaced by an edit included (is_current_source: false).

      Fields of each item (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
      • countrystring | null
      • country_codestring | null
      • 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.

      • Company locations only; false for customer addresses.

      • 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).

      • customer for customer addresses.

        • One of: "customer", "team", "unknown"
      • 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
      • Set on an old copy: the address that replaced it.

      • True 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 objects

      The 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 objects

      Every contact, deleted ones included (trashed).

      Fields of each item (18)
    • Whether 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 | null

      The id used in the customer's portal address. Null for Shopify customers.

    • Whether the customer can pay online in the portal. Null follows the team setting (and is always null for Shopify customers).

      • One of: "ENABLED", "DISABLED"
    • customer_profilesarray of objects

      Brand profiles.

      Fields of each item (12)
      • address_idstring | nullrequired

        The Ship From address, or null for a profile that has none.

      • company_namestring | nullrequired
      • customer_idstringrequired
      • idstringrequired
      • is_primarybooleanrequired

        New sales orders and quotes for the customer use the primary profile.

      • trashedbooleanrequired
      • addressobject | null

        The Ship From address (an address, as in Customer addresses, without used_by_active_profile), or null.

      • emailstring | null
      • phonestring | null
      • websitestring | null
    • deposit_due_amountinteger | number | string

      Deposits still due. Thousandths, an older encoding: 125000 is 125.00. Usually a whole number; an amount finer than a thousandth comes back as a number with a fraction (1234.5 is 1.2345), or as a string ("1234.5") when you send X-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 | null

      shopify for customers synced from Shopify.

    • held_creditinteger | number | string

      The part of wallet_fund held 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 than wallet_fund; 0 when wallet_fund is 0 or negative. Thousandths, an older encoding: 125000 is 125.00. Usually a whole number; an amount finer than a thousandth comes back as a number with a fraction (1234.5 is 1.2345), or as a string ("1234.5") when you send X-Yoprint-Decimal-Format: exact-v1. See Money and quantities.

    • internal_notesstring | null
    • last_ordered_datestring (date-time) | null

      The issue date of the customer's latest published sales order. Null when it has none.

    • mediaarray of objects
    • ordered_amountinteger | number | string

      Total of the customer's published sales orders. Thousandths, an older encoding: 125000 is 125.00. Usually a whole number; an amount finer than a thousandth comes back as a number with a fraction (1234.5 is 1.2345), or as a string ("1234.5") when you send X-Yoprint-Decimal-Format: exact-v1. See Money and quantities.

    • overdue_amountinteger | number | string

      Unpaid amounts past their payment due date. Thousandths, an older encoding: 125000 is 125.00. Usually a whole number; an amount finer than a thousandth comes back as a number with a fraction (1234.5 is 1.2345), or as a string ("1234.5") when you send X-Yoprint-Decimal-Format: exact-v1. See Money and quantities.

    • pdfobject
      Child fields (1)
      • invoice_statementstringrequired

        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 | string

      Total of open quotes. Thousandths, an older encoding: 125000 is 125.00. Usually a whole number; an amount finer than a thousandth comes back as a number with a fraction (1234.5 is 1.2345), or as a string ("1234.5") when you send X-Yoprint-Decimal-Format: exact-v1. See Money and quantities.

    • resale_numberstring | null
    • system_typestring | null
    • tagsarray of objects
      Fields of each item (3)
    • How 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"
    • unpaid_amountinteger | number | string

      What the customer still owes on published sales orders. Thousandths, an older encoding: 125000 is 125.00. Usually a whole number; an amount finer than a thousandth comes back as a number with a fraction (1234.5 is 1.2345), or as a string ("1234.5") when you send X-Yoprint-Decimal-Format: exact-v1. See Money and quantities.

    • vat_numberstring | null

      The customer's tax number (shown as Tax number in YoPrint).

    • The team's default currency, the one wallet_fund is in. iso is its code.

      Child fields (6)
      • defaultbooleanrequired
      • idstringrequired
      • isostring | nullrequired

        The ISO 4217 code, such as USD.

      • namestring | nullrequired
      • symbolstring | nullrequired
      • trashedbooleanrequired
    • wallet_fundinteger | number | string

      Customer 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: 125000 is 125.00. Usually a whole number; an amount finer than a thousandth comes back as a number with a fraction (1234.5 is 1.2345), or as a string ("1234.5") when you send X-Yoprint-Decimal-Format: exact-v1. See Money and quantities.

    • websitestring | null
  • 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 cannot create customers. This 403 has a short body, {"message": "Insufficient Permission"}, with no success or error.
    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.code customer_portal_duplicate_contact_email). Nothing is saved.
    Fix
    Send each email once.
  • 422The request was refused and changed nothing. validation_failed lists what to fix in error.fields; other codes name a business rule, explained in error.message. A few checks answer with only {"message": "..."}. An operation that calls another service (a payment provider, a carrier, an accounting app) can answer connect_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.code is validation_failed.
    Fix
    Fix each field named in error.fields; its keys are paths such as contact.0.first_name or billing (for two primaries).
    When
    On a live customer, the email is longer than 191 characters or is not a valid address (error.code customer_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 null is dropped before the request is read, except customer.default_payment_term_id, customer.customer_portal_payment_option and customer.customer_portal_enabled, which are saved as null.