Update a customer contact (PATCH)

PATCH/v1/api/store/{team_slug}/customer/{hash_id}/contact/{id}

v1Operation ID v1_public_customer_contact_update_patch

Changes the fields you send and returns the contact. is_primary is not changed here: use Set the primary contact.

Use PUT: it checks the fields. PATCH takes the same body but checks nothing.

A contact can give someone access to the Customer Portal (a portal account with the contact's email). Changing that contact's email moves the access: portal_email_scope says whether the account's sign-in email changes on every customer it can open (all_customers) or only this customer's access moves (this_customer), and portal_reconnect_confirmed: true confirms moving it to an account that already uses the new email.

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

• is_external and external_type are ignored: sending them (for example a value you read back) is not refused and changes nothing. Only the Shopify sync sets them.
• 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.").
• Contacts synced from Shopify are read-only (422).
• 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.
• Changing the email of a contact that gives someone Customer Portal access moves that access with it: see portal_email_scope and portal_reconnect_confirmed. Sending email: "" clears the email and removes the contact's portal access for this customer.
• PUT checks that portal_email_scope is all_customers or this_customer and that portal_reconnect_confirmed is a boolean; PATCH doesn't.
• To clear a text field, send an empty string; null is ignored (it is dropped before the request is read).

Side effects

• Sends the customer_contact.updated webhook.
• Portal access moves with a changed email. With all_customers and no other account on the new email, the account's sign-in email changes, its password is cleared, its signed-in sessions end, its contacts on other customers get the same email (without webhooks), and the old address is emailed that the sign-in email changed. Otherwise the access (only this customer's with this_customer) moves to the account that uses the new email, which is created, invited, when there is none.
• 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
• 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
• idstringrequired

  The contact's id (id from List a customer's contacts, or from List a vendor's contacts). A hash id from an earlier answer; unique keys and document numbers (such as PO0042) don't work here.

  • Example uAu3dAKIaHyAYk

Request body

application/json, required.

• default_receive_smsboolean
• emailstring (email)

  Saved trimmed and in lower case. "" clears it.

• faxstring

  Checked as a real number for fax_country.

• fax_countrystring
• first_namestring

  The contact's first name.

• last_namestring

  The contact's last name.

• phonestring

  Send phone_country with it.

• phone_countrystring

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

• portal_email_scopestring

  Read only when you change the email of a contact that gives someone Customer Portal access. all_customers (the default) changes that portal account's sign-in email, and the email of its contacts on every customer it can open. this_customer moves only this customer's access to the account for the new email. Required when the account can open more than one customer.

  • One of: "all_customers", "this_customer"
• portal_reconnect_confirmedboolean

  Send true to confirm moving this contact's Customer Portal access to the account that already uses the new email. Defaults to false.

• send_invoiceboolean

  Stored with the contact and returned as send_invoice.

More examples (1)

Change the email of a contact with Customer Portal access, on every customer

curl

curl -X PATCH 'https://secure.yoprint.com/v1/api/store/your-team/customer/EDhVUaC6jbLbed/contact/uAu3dAKIaHyAYk' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{    "email": "alex@example.com",    "portal_email_scope": "all_customers"  }'

Response

200Successful response.

• dataobjectrequired
  Child fields (18)

  • created_atstring (date-time)required
  • first_namestring | nullrequired
  • idstringrequired
  • is_primarybooleanrequired
  • trashedbooleanrequired

    True when the contact is deleted.

  • updated_atstring (date-time)required
  • customer_idstring

    Customer contacts only.

  • default_receive_smsboolean
  • emailstring | null
  • external_typestring | null
  • faxstring | null
  • fax_countrystring | null
  • is_externalboolean

    True for a contact synced from Shopify; such contacts are read-only.

  • last_namestring | null
  • phonestring | null
  • phone_countrystring | null
  • send_invoiceboolean

    Customer contacts only.

  • vendor_idstring

    Vendor contacts only.

• 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

  The change moves portal access on a customer your role can't update: you need Manage Customers "Manage All", or "Manage Assigned to User" and to be assigned to every customer the change covers. This 403 has a short body, {"message": "You need permission to update every linked customer."}.

  Fix

  Ask a member who can update those customers, or send portal_email_scope: this_customer.

  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

  The contact is deleted, or belongs to another customer. error.code is null and error.message names the record type.

  Fix

  Restore it first, or check the ids.

• 409

  When

  Another live contact of this customer already has this email, ignoring case and surrounding spaces (error.code customer_portal_duplicate_contact_email, "This customer already has a contact with that email. Edit the existing contact or use a different email.").

  Fix

  Update the existing contact instead, or use another email.

  When

  The contact gives Customer Portal access to an account that can open several customers, and portal_email_scope was not sent (error.code customer_portal_email_scope_required).

  Fix

  Send portal_email_scope: all_customers or this_customer.

  When

  The new email already belongs to another Customer Portal account and portal_reconnect_confirmed is not true (customer_portal_email_reconnect_required), or that account is disabled or deleted (customer_portal_account_unavailable), or it already has another contact on this customer (customer_portal_duplicate_contact_email).

  Fix

  Send portal_reconnect_confirmed: true to move the access to that account, or use another email.

• 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 phone or fax is not valid for its country, a field has the wrong type, or portal_email_scope is not all_customers or this_customer. error.code is validation_failed.

  Fix

  Send the country code with the number.

  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.

  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.

Related

• PATCHSet the primary contact/v1/api/store/{team_slug}/customer/{hash_id}/contact/{id}/primary
• PATCHUpdate a contact by id (PATCH)/v1/api/store/{team_slug}/contact/{id}

Example request

curl

curl -X PATCH 'https://secure.yoprint.com/v1/api/store/your-team/customer/EDhVUaC6jbLbed/contact/uAu3dAKIaHyAYk' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{    "phone": "+1 201 555 0123",    "phone_country": "US"  }'

Example response 200

Response

{
  "data": {
    "created_at": "2026-11-01T09:00:00+00:00",
    "customer_id": "V4keXwwxMQyXw7",
    "default_receive_sms": false,
    "email": "alex@example.com",
    "external_type": null,
    "fax": null,
    "fax_country": null,
    "first_name": "Alex",
    "id": "cBoKHftCid2dDD",
    "is_external": false,
    "is_primary": true,
    "last_name": "Rivera",
    "phone": "+1 201 555 0123",
    "phone_country": "US",
    "send_invoice": true,
    "trashed": false,
    "updated_at": "2026-11-01T09:00:00+00:00"
  },
  "status": 200,
  "success": true
}