# Shopify and Meta one-click connections

## Tenant administrator experience

### Shopify

1. Open **Setup & system health**.
2. Enter the permanent store address, such as `my-store.myshopify.com`.
3. Select **Install / connect Shopify**.
4. Sign in to Shopify and approve the requested read access.
5. Return to Subset and use **Fetch Shopify orders** or **Fetch inventory and suppliers**.

The tenant never enters an Admin API token, client ID, client secret, or webhook
secret. Subset stores the Shopify offline access token encrypted. It remains
usable until the app is uninstalled or access is revoked.

### Meta Ads

1. Open **Integrations & risk**.
2. Select **Meta Ads**.
3. Select **Connect Meta**.
4. Sign in to Facebook and approve access to advertising information.
5. Select the discovered ad account.
6. Choose a date range and select **Sync ad spend**.

Subset imports daily campaign spend into P&L. Re-syncing a period replaces the
previous Meta rows for that period, preventing duplicates.

Meta long-lived user authorization normally expires and can also be revoked.
Subset displays its expected expiry date. The tenant reconnects by selecting
**Reconnect Meta**; no token is copied manually.

## Subset platform configuration

These credentials are configured once for the whole Subset installation. They
must never be entered by a tenant.

### Shopify app

```text
SUBSET_SHOPIFY_OAUTH_CLIENT_ID=your-shopify-app-client-id
SUBSET_SHOPIFY_OAUTH_CLIENT_SECRET=your-shopify-app-client-secret
SUBSET_SHOPIFY_OAUTH_REDIRECT_URI=https://your-domain/api/v1/integrations/shopify/oauth/callback
SUBSET_SHOPIFY_OAUTH_SCOPES=read_orders,read_products,read_inventory,read_locations
```

Add the exact redirect URL to the Shopify app configuration. Configure Shopify
webhook topics for the Subset endpoint:

```text
https://your-domain/api/v1/webhooks/shopify
```

Access to orders older than 60 days also requires Shopify approval for
`read_all_orders`; add that scope only after approval.

### Meta app

```text
SUBSET_META_OAUTH_CLIENT_ID=your-meta-app-id
SUBSET_META_OAUTH_CLIENT_SECRET=your-meta-app-secret
SUBSET_META_OAUTH_REDIRECT_URI=https://your-domain/api/v1/meta-ads/oauth/callback
SUBSET_META_GRAPH_API_VERSION=v23.0
```

Add the exact redirect URL to the Meta app's valid OAuth redirect URIs. The app
requests `ads_read` and `business_management`. Production use by people outside
the app's test roles requires the appropriate Meta app review and business
verification.

## Local Mac testing

OAuth providers must redirect to a URL they can reach. `localhost` can be used
for developer-mode tests where the provider permits it. For realistic webhook
and multi-device testing, use a stable HTTPS tunnel and place its callback URLs
in both provider dashboards.