## Overview

The **Shopify** integration finds a customer using the contact's email address or phone number and
shows store orders in the conversation. The lookup happens on demand: ConversaLabs does not persist the
Shopify customer record or order response.

This connection is separate from a **Catalog & Commerce source**. Use this integration for support
order lookup; use a commerce source for catalog sync, sales events, cards, and automations.

## Prerequisites

- The installation operator must configure `SHOPIFY_CLIENT_ID`, `SHOPIFY_CLIENT_SECRET`, and the
  public HTTPS origin for ConversaLabs. In development, HTTP is accepted only for loopback hosts.
- The installation operator must register the configured OAuth callback and the verified Shopify
  privacy webhook endpoint in the Shopify app settings before enabling the feature for accounts.
- **Shopify integration** must be enabled for the account.
- You must be an **Administrator** or have the native **Manage integrations** permission.
- You need store admin access and its permanent `your-store.myshopify.com` domain. Do not use the
  storefront's custom domain.

## Step by step

1. Open **Settings → Integrations → Shopify**.
2. Select **Connect store** or **Reconnect store**.
3. Enter only `your-store.myshopify.com`, without `https://`, a path, query, or port.
4. In Shopify, check the store and requested permissions, then authorize in the same browser.
5. Back in ConversaLabs, open a conversation whose contact has an email address or phone number and
   expand **Shopify orders**.

Reconnecting safely replaces the account credential and can refresh permissions or change stores.
Each attempt expires in about ten minutes, is bound to the initiating browser, and can be completed
only once. If you cancel, wait too long, or open the callback in another browser, start again from the
integration page.

## Settings & options

- The app requests only `read_customers` and `read_orders`.
- The contact's email/phone is sent to Shopify search; the UI response contains only order ID, date,
  amount, currency, financial/fulfillment status, and the admin link.
- By default, Shopify's API makes the last **60 days** of orders available. Longer history requires
  separate Shopify approval and is not requested by this integration.
- The token remains server-side and is never returned to the browser, Swagger, or MCP.
- Mandatory privacy webhooks are HMAC-verified. Customer/order data is transient, so customer access
  and redaction requests acknowledge that there is no local copy to erase. `shop/redact` deletes the
  saved connection for that store.

## Use cases

- Check order amount, date, and status without leaving the conversation.
- Open the correct Shopify admin order to handle a return, delivery, or refund.
- Reconnect the same store after its permissions change.
- Replace the store attached to the account without creating duplicate credentials.

## Tips, limits & best practices

On the Shopify integration page, choose **Disconnect** and confirm. Removal remains available if the
feature is disabled so an old credential can never become trapped. Also revoke the app in Shopify
admin when ending its use permanently.

Always use the permanent `.myshopify.com` domain, finish each attempt in the browser that started it,
and periodically review who has the **Manage integrations** permission.

## Troubleshooting

- **Invalid domain**: copy the `.myshopify.com` domain from Shopify **Settings → Domains**.
- **Integration disabled**: ask the operator to enable the feature for this account.
- **Callback error**: stay in the same browser, check the system clock, and start again; do not reuse
  an old link.
- **No orders**: ensure the contact matches an email address or phone number in Shopify and remember
  the default 60-day window.
- **Permissions changed**: choose **Reconnect store** and approve again.
- **Temporary failure**: use **Try again** in the order panel. Provider internals and credentials are
  never displayed in the error.

## See also

- [Integrations: providers, credentials, OAuth, webhooks, and API](/hc/ajuda/articles/administration-integracoes-en)
- [E-commerce lifecycle](/hc/ajuda/articles/catalog-commerce-commerce-lifecycle-en)
- [Custom roles and governance](/hc/ajuda/articles/administration-custom-roles-governanca-rbac-en)