Shopify connection

What it reads

Growth Dept MTA reads your store's orders: the order total and its parts (shipping, tax, discounts, tips and refunds), the line items with product ID, variant ID, SKU, title, quantity, unit price and discount, discount codes, tags, the sales channel, and whether the order was a test or was cancelled.

From each order it also keeps the landing page's host and tracking parameters (utm_* tags and click IDs such as fbclid, gclid, ttclid and msclkid), the referring site, and the visitor IDs that the landing-page script, the pixel or the theme write to the cart. Those tie the order to the visits that came before it.

The customer is kept only as a hash of Shopify's customer ID, made with a key that belongs to your brand. Names, emails, phone numbers and addresses are not stored.

Orders arrive two ways. Shopify sends a webhook when an order is created, updated or cancelled and when a refund is made, and a scheduled pull reads every order updated since the last one, about once an hour. Brands whose store Growth Dept manages connect through Growth Dept's own systems instead; that route has no webhooks, so the pull runs every 15 minutes.

When the store's currency differs from the brand's, each amount is converted at the European Central Bank rate for the order's local date.

Connecting

An owner or admin of the brand's organization connects the store from Settings > Connections, in one of two ways.

Install the Growth Dept MTA app

1. On the Shopify card, type the store's address into Store address, in the form your-store.myshopify.com.
2. Click Connect. Shopify asks you to approve the Growth Dept MTA app for that store.
3. Approve it. Back on Settings > Connections, the card shows the store and its last order sync.

The app asks Shopify for read_orders, read_customers (only for the customer ID, which is hashed straight away), read_products (for product and variant IDs on line items), write_pixels and read_customer_events. Orders older than 60 days also need read_all_orders, which Shopify gives only to apps it has approved for it (see Limits).

Use a token from a custom app

1. In Shopify admin, open Settings > Apps > Develop apps and open your custom app. Its Admin API token needs the read_orders scope.
2. Copy the Admin API access token, which starts with shpat_, and the app's API secret key.
3. On the Shopify card in Settings > Connections, open Use an Admin API token from a custom app instead, and fill in Store address, Admin API access token and API secret key.
4. Click Connect with token.

The token reads orders and the secret verifies the webhooks Shopify sends. Both are stored encrypted.

After connecting

Growth Dept MTA registers its webhooks with Shopify and starts a backfill of the orders created within the brand's lookback window (Settings > Lookback window).

Stores that are not on Shopify can send orders through the orders API.

How orders are mapped

Webhook orders and pulled orders go through the same rules. Amounts are in the store's own currency (Shopify's shop money) until any conversion.

So revenue equals gross sales plus shipping and tax, less discounts.

The sales channel is the online store, POS, a draft order, a subscription, or the app that created the order. An order counts as a subscription order when a line has a selling plan, when it comes from a subscription contract, or when it carries a tag listed in Settings > Subscription order tags.

Some orders are excluded from attribution. Each gets one reason, checked in this order: a test order, zero revenue, or a tag listed in Settings > Exclude orders by tag (an exact, case-sensitive match). Excluded orders are kept, with their revenue, rather than deleted. Cancelled orders are not excluded: they keep their credit, as the store's own totals count them.

A customer's first non-test order, by creation time, is their new-customer order. An update older than the version already stored is ignored, so a late webhook cannot roll an order back.

Privacy

Growth Dept MTA stores no customer names, emails, phone numbers or addresses from Shopify. It handles Shopify's three privacy webhooks:

• customers/redact removes the customer's hash, the visitor IDs on the named orders, the links between those orders and the customer, and the order IDs on their checkout events. The visitors' IDs on their pixel events and visits are replaced with random ones, and their identity records are deleted. A later update cannot restore any of it. The orders keep their money figures, so totals still add up, and their credit moves to Unattributed the next time attribution is recomputed.
• shop/redact deletes the store's orders, line items and refunds, the identity records, the pixel events and visits, each order's attribution and the files on the Documents page, then marks the connection redacted and deletes its tokens. Ad spend, settings and the daily report totals, which name no order or visitor, stay. Shopify sends this request 48 hours after the app is uninstalled.
• customers/data_request gets a JSON file of everything Growth Dept MTA holds for the named orders: the orders, their line items, the visits credited to them and the pixel events of the visitors tied to them. The file goes on the brand's Documents page for 30 days, the brand's owners and admins get an email saying it is there, and the brand's team passes it on to the customer. The audit log notes the request, with counts only.

Uninstalling the app from Shopify deletes the store's access token at once and stops syncing. The store's data stays until Shopify's shop/redact request arrives.

Shopify sends these webhooks only to the public Growth Dept MTA app, so a store connected with a custom-app token does not receive them.

Limits

• Shopify releases orders older than 60 days only to apps it has approved for read_all_orders. Without that approval the backfill stops at 60 days, however long the lookback window is.
• Only stored orders count toward a customer's history, so a customer whose earlier orders predate the backfill counts as new.
• Converting an order in another currency needs a European Central Bank rate for its date or one of the seven days before it. A currency the ECB does not quote cannot be converted.
• Stores connected through Growth Dept's own systems get no webhooks, so their orders arrive with the 15-minute pull.

Disconnecting

On the Shopify card, click Disconnect beside the store and confirm. Only owners and admins can. After that:

• Syncing stops.
• The stored access token and webhook secret are deleted.
• Orders already pulled stay in your reports.