Attribloom
Agent setup prompts

Public agent guide

Agent onboarding for Attribloom merchants

A truthful handoff map for humans and coding agents launching Shopify, iOS, or custom attribution.

Published · Last reviewed

Authorization boundary

Act only on the merchant's explicit instructions. Do not accept legal terms, grant Shopify access, upload Apple credentials, choose commission economics, approve payouts, or publish changes without the merchant's authorization.

What requires a human

  • Create the Attribloom account and complete the Turnstile-protected signup form.
  • Choose campaign economics, affiliate eligibility, payout currency, hold policy, and refund policy.
  • Review and approve Shopify's OAuth consent screen for the canonical .myshopify.com store.
  • Authorize access to App Store Connect and decide whether an In-App Purchase key may be uploaded for one-click verification.
  • Review payout eligibility and confirm the program's operational payout policy before funds move.
  • Approve production code, theme, App Store Connect, and storefront changes before release.

What an agent can implement

  • Read the public setup prompts, guides, Markdown twins, and OpenAPI contract.
  • Prepare and test HMAC signing, conversion and refund postbacks, Shopify cart-attribute preservation, StoreKit binding, and ASSN forwarding.
  • Validate request examples locally, add tests, inspect HTTP responses, and report each observed link in the verification chain.
  • Guide the merchant through dashboard controls after asking what is visible, without inventing tenant state.

Management API boundary

Attribloom does not yet expose a public tenant-management API for account creation, campaigns, affiliates, connection state, balances, or payouts. Those actions remain dashboard workflows. A scoped management API is on the roadmap, but full autonomous tenant management is not available today.

Shared launch sequence

  1. 1

    Human creates the account

    Use /signup. Turnstile and the merchant's account details make this a human-attended step.

  2. 2

    Human defines the program

    Create the campaign and commission rule in the dashboard, then add or approve affiliates so their links and referral codes exist.

  3. 3

    Agent implements the runtime path

    Choose Shopify, iOS, or custom signed postback below. Keep secrets on the server and use integer minor units.

  4. 4

    Human authorizes external systems

    Complete Shopify OAuth, App Store Connect changes, and any production deployment approval.

  5. 5

    Agent and human verify together

    Run a paid/test conversion from the real trigger through the observed HTTP response and dashboard result. Record any unobserved link as assumed.

  6. 6

    Human reviews payouts

    Confirm pending versus matured balances, refunds, identity or tax requirements, and the program's operational payout policy. Review each affiliate's first payout before release.

Shopify checklist

  • Human: provide the canonical store-name.myshopify.com domain and approve Shopify OAuth.
  • Agent: add the Shopify `ref` cart-attribute recipe, or confirm the affiliate's validated discount code path.
  • Agent: prove the chosen referral value appears as the paid order's validated discount or ref note attribute.
  • Human: place or authorize a paid test order.
  • Agent: observe the attributed conversion, then refund it and observe the proportional clawback.

iOS checklist

  • Human: provide the exact bundle ID, numeric Apple app ID, environment, and App Store Connect authorization.
  • Agent: call /v1/app-store/bind or /v1/app-store/bind/deferred on first launch and persist Attribloom's appAccountToken.
  • Agent: pass that UUID to every StoreKit 2 purchase and forward each ASSN v2 signedPayload unchanged with the app's forwarding HMAC.
  • Human: approve the app build and App Store Connect notification configuration.
  • Agent: run the sandbox and production verification chain and use the ASV diagnostics when needed.

Custom postback checklist

  • Keep the surface secret in server-side secret storage.
  • Implement conversion and refund requests from the OpenAPI contract.
  • Sign the timestamp plus exact raw body and retry transient failures with a fresh timestamp and signature.
  • Use stable externalId and refundId values so replays remain idempotent.
  • Verify full and partial refund behavior in the signed webhook guide.
Open integration guides