Update a contact by id (PATCH)

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

v1Operation ID v1_public_contact_update_patch

Changes the fields you send on a customer or vendor contact, and returns it.

Use PUT: it checks the fields. PATCH takes the same body but checks nothing. Prefer Update a customer contact or Update a vendor contact when you know the owner.

For a customer contact that gives someone Customer Portal access, a changed email moves that access, as Update a customer contact describes; send portal_email_scope and portal_reconnect_confirmed the same way.

Permission

Any member of the team. Moving the Customer Portal access of a customer contact (a changed email) also needs Manage Customers on the customers it covers.

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.
• Contacts synced from Shopify are read-only (422 "Shopify-managed customer contacts are read-only. Manage changes from Shopify.").
• Only the contact itself is checked: unlike Update a customer contact, this route doesn't refuse contacts of Shopify or system customers.
• send_invoice and default_receive_sms are saved but not checked here, even with PUT: send JSON booleans.
• For a customer contact, portal_email_scope and portal_reconnect_confirmed are checked with PUT and PATCH alike.
• is_primary is not changed here.
• Customer contacts: 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.
• Customer contacts: 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.
• To clear a text field, send an empty string; null is ignored (it is dropped before the request is read).

Side effects

• For a customer contact, sends the customer_contact.updated webhook.
• Customer contacts: 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.
• Customer contacts: 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
• idstringrequired

  The contact's id: a customer or vendor contact. 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)
• 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

  Customer contacts only. 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

  Customer contacts only. 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

  Customer contacts.

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.

• 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 contact with this id. error.code is null and error.message names the record type.

  Fix

  Check the id.

• 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

  The contact is synced from Shopify (validation_error).

  Fix

  Change Shopify contacts in Shopify.

  When

  A phone is not valid for its country, or on a customer contact portal_email_scope or portal_reconnect_confirmed has a wrong value. 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.

Related

• PATCHUpdate a customer contact (PATCH)/v1/api/store/{team_slug}/customer/{hash_id}/contact/{id}
• PATCHUpdate a vendor contact (PATCH)/v1/api/store/{team_slug}/vendor/{hash_id}/contact/{id}

Example request

curl

curl -X PATCH 'https://secure.yoprint.com/v1/api/store/your-team/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",    "first_name": "Alex"  }'

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
}