Identify merchants from your backend

What you need

The private workspace key and app UUID. Use your app’s authenticated merchant context; obtain approval before forwarding Shopify access tokens.

Steps

1. Choose a contact path: send known authorized contact fields without a token, or use the approved post-OAuth identify hook with transient token enrichment/watch registration.
2. POST JSON to https://heycrust.com/api/identify with Authorization: Bearer <workspace key> and the body below. The required domain field is myshopifyDomain.
3. Include the HeyCrust appId for reliable app-specific observations. Optional email, phone, ownerName, country, shopifyPlan and accessToken can be omitted or null.
4. Keep the hook bounded and catch failures so merchant authentication is not broken by a reporting failure. On serverless hosts, use the host’s supported background lifecycle rather than assuming detached work survives.
5. Inspect the response and the app’s identification receipt, then verify the intended merchant contact record.

{
  "appId": "11111111-1111-4111-8111-111111111111",
  "myshopifyDomain": "example.myshopify.com",
  "email": "merchant@example.com",
  "ownerName": "Example Merchant",
  "country": "US",
  "shopifyPlan": "Basic"
}

Expected result

{"ok":true,"uninstallWatch":false} means contact upsert succeeded without a registered watch. A true watch flag means that path registered/found its watch. HTTP success is not a commission or install-attribution receipt.

Redaction

For an authorized shop-redact workflow, DELETE /api/identify using the workspace key and myshopifyDomain. It removes that domain’s customer/app-user/usage/custom-event records in the workspace and redacts affiliate merchant contact. It is not a promise to erase financial audit history. Validate your own compliance workflow and see Privacy.

See the Framework recipes for the actual app-generated hooks.

Troubleshooting

Check the workspace key, app ownership, domain field and contact formats. When accessToken is provided, missing email may trigger a transient Shopify contact read; watch registration also needs the correct app secret/context. Do not assume {ok:true} means the watch was established.