Skip to content

Update a customer

Open .md

PUT/v1/api/store/{team_slug}/customer/{hash_id}

v1Operation ID v1_public_customer_update_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.

Permission

Needs the Manage Customers permission: "Manage All" for any customer, or "Manage Assigned to User" for customers assigned to you.

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.
  • 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_id must be a current company location of the team.
  • A new default_pricing_group_id must 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_option and customer_portal_enabled can be cleared with null. Any other field sent as null is 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.updated webhook.
  • Open Customer Portal pages of this customer are told to refresh.

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.

  • false turns the Customer Portal off for this customer: its contacts can no longer open the portal, through existing links or signed-in sessions. true or null turns it back on. Its records and payment settings are kept.

  • Null goes back to the team setting.

    • One of: "ENABLED", "DISABLED"
  • A payment term id, or null to clear it.

  • A 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_id from a sales order or quote that uses the group (Get a sales order or quote), or default_pricing_group_id from another customer that has it.

  • A current company location (store location) id, or null to clear it. New sales orders for this customer ship from it.

  • hideboolean

    True archives the customer, false brings it back.

  • Notes for your team only.

  • namestring

    The customer's name, usually the company.

  • The customer's resale or tax certificate number.

  • tax_exemptboolean

    True when no sales tax applies to this customer.

  • default_carrier_account starts the customer's shipping labels on its default carrier account; none starts them with no third-party billing.

    • One of: "none", "default_carrier_account"
  • Tax number.

  • websitestring

    The website address.

More examples (2)

Set the defaults new orders use

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

  • 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 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.code is null and error.message names the record type.
    Fix
    Check the id. Find deleted customers with the trashed_only filter and restore them first.
  • 409default_warehouse_id names a company location that is deleted, synced from another system or redacted (blocked_external_or_compliance; current_address is that location), or one replaced by an edit (blocked_superseded_historical_address; current_address is its replacement). Not the usual error envelope: success: false, address_save_result and message (the save_mode); no status or error.

    When
    default_warehouse_id names a company location that was replaced by an edit (address_save_result.save_mode blocked_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 has success: false, address_save_result and message.
    Fix
    For blocked_superseded_historical_address, use address_save_result.current_address.id. For blocked_external_or_compliance, current_address is the same location: pick another current one from List company locations.
  • 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
    default_warehouse_id is not a company location of the team (error.code invalid_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_id can't be used: not one of the team's published groups (validation_error, "Choose one of your pricing groups." on default_pricing_group_id in error.fields), removed (pricing_group_removed, with error.pricing_group), or turned off (pricing_group_disabled, with error.pricing_group and error.fields).
    Fix
    Copy pricing_group_id from 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.code validation_error, with the reason in error.message).
    Fix
    Change Shopify customers in Shopify. System customers cannot be changed.