Skip to content
YoPrintDevelopers

Create or update a customer contact by email or phone

Open .md

POST/v1/api/store/{team_slug}/customer/{hash_id}/contact/upsert

v1Operation ID v1_public_customer_contact_upsert

Updates the customer's contact that has this email or phone, or adds a new contact.

With perform_upsert: true YoPrint looks among the customer's live contacts for one whose email equals yours or whose phone equals yours, and updates the first it finds with the fields you send. Otherwise, or with perform_upsert: false, it adds a new contact (primary only when the customer has no other live contact). Returns the contact.

Permission

Any member of the team.

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.
  • With perform_upsert: true, send email or phone. With neither, the customer's first contact is updated.
  • A matched contact synced from Shopify is refused (422 "Shopify-managed customer contacts are read-only. Manage changes from Shopify.").
  • 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.").
  • 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.
  • This operation can't send portal_email_scope or portal_reconnect_confirmed. When it changes the email of a matched contact that gives someone Customer Portal access, and the change needs either, it answers 409: make the change with Update a customer contact.

Side effects

  • Sends customer_contact.updated for a match, or customer_contact.created for a new contact.
  • 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.
  • A matched contact whose email changes moves its Customer Portal access as Update a customer contact describes, with portal_email_scope all_customers.

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.

  • perform_upsertbooleanrequired

    True to match by email or phone first. False always adds.

  • default_receive_smsboolean
  • emailstring (email)

    Matched exactly.

  • faxstring

    Checked as a real number for fax_country.

  • fax_countrystring
  • first_namestring

    Not required here, but send it when the contact may be new.

  • is_primaryboolean

    Not used. Use Set the primary contact.

  • last_namestring

    The contact's last name.

  • phonestring

    Matched exactly as stored. Send phone_country with it.

  • phone_countrystring

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

  • send_invoiceboolean

    Stored with the contact and returned as send_invoice.

Response

200Successful response.

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 customer with this id in the team. Deleted customers are found here, so this also works on a deleted customer. 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 matched contact's new email needs a choice this operation can't send (error.code customer_portal_email_scope_required or customer_portal_email_reconnect_required), or the account on the new email is unavailable (customer_portal_account_unavailable).
    Fix
    Change the email with Update a customer contact, sending portal_email_scope or portal_reconnect_confirmed.

  • 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
    perform_upsert is missing, or a phone is not valid for its country. error.code is validation_failed.
    Fix
    Send perform_upsert, and phone_country with phone.
    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.

AI agents: read /llms.txt; add .md to any page URL for its Markdown. Guides and concepts in one file: /llms-full.txt.

Download the OpenAPI specSupport: support@yoprint.comyoprint.com