Identify

Enrich a merchant's Ranksy CRM record: send a Shopify access token and Ranksy pulls store metadata from the Admin API, or supply the shop data yourself on the data path.

Identify a merchant

curl -X POST https://ranksyapp.com/api/v1/apps/:app/identify \
  -H "Authorization: Bearer rk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "myshopify_domain": "store.myshopify.com",
    "shopify_access_token": "shpat_...",
    "contacts": [{ "name": "Sarah Chen", "email": "[email protected]", "label": "owner", "ip": "203.0.113.9", "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_5 like Mac OS X) AppleWebKit/605.1.15 Mobile/15E148 Safari/604.1" }],
    "tags": ["vip"],
    "custom_fields": { "plan_tier": "growth" }
  }'

{
  "identified": true,
  "shop_id": 68134502401,
  "plan": "Advanced Shopify",
  "is_shopify_plus": false,
  "admin_country": "US",
  "timezone": "America/Los_Angeles",
  "currency": "USD",
  "contacts_count": 1,
  "tags_count": 1,
  "custom_fields_count": 1
}

Response

A successful call returns identified: true with the resolved shop fields and the counts stored (see the 200 — Success example above). The token path can also degrade or fail; the data path never reaches these states, because there's no outbound call to fail.

When the Shopify fetch fails (token path only).

If Ranksy already knows this shop — it holds a shop record for this domain with a real shop_id, whether from an earlier /identify call on either path or from Ranksy's own Partner API sync picking up the shop independently — a failing token-path fetch degrades instead of failing outright. The response is HTTP 422 with identified: false and an error object, but the contacts / tags / custom_fields you sent in the same request are still stored:

{
  "identified": false,
  "shop_id": null,
  "plan": null,
  "is_shopify_plus": null,
  "admin_country": null,
  "timezone": null,
  "currency": null,
  "contacts_count": 1,
  "tags_count": 1,
  "custom_fields_count": 1,
  "error": {
    "type": "shopify_error",
    "code": "shopify_token_invalid",
    "message": "Shopify access token is invalid or expired. Generate a new token and retry."
  }
}

If Ranksy has no shop_id on record for this domain yet — a brand-new domain it has never resolved an identity for, whether via /identify or otherwise — there's nothing to attach the CRM data to, so the failure is returned as a hard error instead — nothing is stored. The HTTP status matches the underlying failure: 422 when the token itself is rejected, 502 when the Shopify Admin API can't be reached, returns a server error, or responds without a usable shop id:

{
  "error": {
    "type": "shopify_error",
    "code": "shopify_token_invalid",
    "message": "Shopify access token is invalid or expired. Generate a new token and retry.",
    "doc_url": "https://api.ranksyapp.com/errors#shopify_token_invalid"
  }
}

{
  "error": {
    "type": "shopify_error",
    "code": "shopify_api_error",
    "message": "Shopify API unavailable. Retry later.",
    "doc_url": "https://api.ranksyapp.com/errors#shopify_api_error"
  }
}

Retry with a working token, or switch to the data path — it never depends on Shopify being reachable.

What happens under the hood

Shop-admin data — the shop.* fields (plan, address, timezone, and the rest) — is stored per installation, scoped to the app that sent it. /identify itself only ever writes the shop's identity — shop_id and myshopify_domain — onto the shared record every app installed on that merchant has in common. That same shared record also carries basic merchant details (name, contact info, a profile image) that other Ranksy features keep up to date independently of /identify, and those ARE visible to every app installed on that merchant, not just yours. If two of your apps (or another partner's app) identify the same merchant, each keeps its own independent copy of the shop.* fields — your calls only ever read and write your own installation's data, never another app's — and neither shop_id nor myshopify_domain can be repointed to relabel a shop once it's set.

Token path:

1. Resolves the shop's identity by calling the Shopify Admin API shop query with your access token — the response's GID is the source of truth for shop_id
2. Looks up (or creates) the shared shop identity record — matched by shop_id first, falling back to myshopify_domain only when no shop_id match exists
3. Upserts your app's installation for this shop — creating a placeholder if Partner API hasn't synced yet — and sets last_seen_at to now
4. Stores contacts, tags, and custom fields per-application
5. Persists the fetched shop metadata to your installation (token discarded immediately) — a successful fetch is a complete, authoritative snapshot and replaces every stored shop.* column on your installation, including back to null

Data path:

1. Resolves the shop's identity from the shop_id you supplied
2. Looks up (or creates) the shared shop identity record — matched by shop_id first, falling back to myshopify_domain only when no shop_id match exists
3. Upserts your app's installation for this shop — creating a placeholder if Partner API hasn't synced yet — and sets last_seen_at to now
4. Stores contacts, tags, and custom fields per-application
5. If a shop object was sent, patches only the keys present in it on your installation — no outbound call is made, and omitted keys keep their previously stored value

Error codes

Rate limits

This endpoint uses the standard rate limits: 120 req/min, 50,000 req/day per key.

Notes

• No token storage. Shopify tokens are never persisted. The data path never sees one, and a token-path fetch uses its token once to call the Admin API, then discards it.
• Idempotent. Repeated calls produce the same state. Contacts upsert by email, custom fields merge by key, tags replace.
• Contact preservation. Contacts omitted from a subsequent /identify call are not deleted.
• Data path patches, token path replaces. A shop object on the data path only overwrites the keys you send. A token-path fetch is a full authoritative snapshot and replaces every shop.* column on each call, including back to null.
• shop_id is the identity key on the data path. Ranksy can't durably attach CRM data (contacts, tags, custom fields) to a shop it can't identify, which is why shop_id is required whenever you're not sending a token.