# Agent onboarding for Attribloom merchants

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

> **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](https://api.attribloom.com/openapi.json).
- [ ] 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. **Human creates the account.** Use [/signup](/signup). Turnstile and the merchant's account details make this a human-attended step.
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. **Agent implements the runtime path.** Choose Shopify, iOS, or custom signed postback below. Keep secrets on the server and use integer minor units.
4. **Human authorizes external systems.** Complete Shopify OAuth, App Store Connect changes, and any production deployment approval.
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. **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](/guides/shopify.md), 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](/guides/ios-testing.md) and use the [ASV diagnostics](/guides/ios-errors.md) when needed.

## Custom postback checklist

- [ ] Keep the surface secret in server-side secret storage.
- [ ] Implement conversion and refund requests from the [OpenAPI contract](https://api.attribloom.com/openapi.json).
- [ ] 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](/guides/webhook.md).