Submit signed affiliate install claims

What you need

An app-specific configured backend bridge, its production/test install key, an actual signed referral claim and independent Shopify install evidence. This key is separate from the workspace and affiliate REST keys.

Steps

1. In program Tracking choose Configure app backend bridge. Save the one-time production hcaip_ and test hcait_ keys in your backend’s secret storage.
2. Verify what the actual referral redirect delivers: hc_click and signed hc_claim are added to its listing destination. Explicitly preserve the actual signed claim through your real install/OAuth journey.
3. Once the authorized install succeeds, POST to https://heycrust.com/api/affiliate-platform/v1/install-claims using Authorization: Bearer <matching install key> and the body below.
4. Use digits-only Shopify numericAppId, permanent shop domain, actual installedAt and a stable idempotencyKey for the same install body. Replace the placeholder signedClaim with the received signature; an arbitrary string cannot establish attribution.
5. Inspect accepted/review/rejected status, reason and testMode. Independent Partner install proof is still required. Test and production readiness must be checked separately.

{
  "numericAppId": "123456789",
  "shopDomain": "example.myshopify.com",
  "installedAt": "2026-10-07T10:00:00Z",
  "signedClaim": "REPLACE_WITH_ACTUAL_HC_CLAIM",
  "idempotencyKey": "example-install-001"
}

Expected result

A claim receipt with its evidence status and mode, and a referral ID when attribution is accepted. Test claims do not create payable commission.

Body limits

numericAppId is digits-only; shopDomain is at most 255 characters; signedClaim is 1–2,000; idempotencyKey is 1–200 letters/digits/colon/underscore/dot/hyphen. Send installedAt as ISO datetime and do not claim a future install.

Troubleshooting

Do not assume Shopify forwards arbitrary query parameters into your app. If the real journey cannot preserve the claim, use the supported listing export path. Check signature, app/mode key, verified install, actual timestamp and same-body idempotency conflicts. No IP-based or synthetic fallback is promised.