> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tranthor.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Shopify Integration

Tranthor Sync is a Shopify app that connects your store to Tranthor’s analytics pipeline. It syncs historical data (orders, customers, products) and streams real-time updates via Shopify webhooks.

## How It Works

1. You install the Tranthor Sync app in your Shopify admin.
2. You provide a Tranthor workspace ID and Write Key.
3. The app registers Shopify webhooks to Tranthor’s public webhook endpoint.
4. Tranthor ingests events into your workspace and updates analytics.

## Required Shopify Scopes

* `read_products`
* `read_customers`
* `read_orders`

> Note: Shopify requires Protected Customer Data approval for public apps to access orders and customers on non-development stores. Until approved, the app can sync products only.

## Webhook Topics

* `orders/create`
* `orders/updated`
* `orders/paid`
* `orders/fulfilled`
* `orders/cancelled`
* `customers/create`
* `customers/update`
* `products/update`
* Compliance: `customers/data_request`, `customers/redact`, `shop/redact`

## Webhook URL Format

```
https://api.tranthor.com/api/public/webhooks/shopify/<workspaceId>
```

Replace `<workspaceId>` with your Tranthor workspace ID.

## Tranthor Backend Requirements

Set the following environment variable so Tranthor can verify Shopify HMAC signatures:

```
SHOPIFY_APP_SECRET=your_shopify_app_secret
```

Optional hardening for sync handoff:

```
SHOPIFY_CONNECT_SHARED_SECRET=shared_secret_value
```

If set, configure the same value in the Shopify Sync app so `/api/public/shopify/connect/resolve` requires `x-tranthor-connect-shared-secret`.

## App Configuration

In the Shopify app settings UI, enter:

* Tranthor workspace ID
* Tranthor Write Key

The Tranthor Write Key is the base64-encoded `secretId:writeKeyValue` token shown
in the dashboard (Settings → Integrations → Shopify → Manual setup values). It is
not the raw secret value — the encoded token is required so Tranthor can resolve
the secret. The app prefixes it with the `Basic ` scheme itself when calling
Tranthor’s public ingestion API:

```
POST /api/public/apps/track
Authorization: Basic <write-key>
```

## Event Names in Tranthor

* `shopify_order_created`
* `shopify_order_updated`
* `shopify_order_paid`
* `shopify_order_fulfilled`
* `shopify_order_cancelled`
* `shopify_customer_created`
* `shopify_customer_updated`
* `shopify_product_updated`

## Support

If you need help onboarding your Shopify store, reach out to the Tranthor team through the dashboard support channel.