Documentation version: 2026-11-16.2
Canonical: https://docs.creator.gg/guides/affiliate-manager.md

# Grow and report with referral partners

Use workspace_status, then affiliates_list to check Affiliate Manager access in this account. The capability starts as unknown, not verified available. AFFILIATE_ACCESS_UNAVAILABLE means access could not be verified; it does not mean zero records. Contact Creator Labs support with the result code, keeping your existing connection. Never supply an account override or financial credentials.

## Partners and campaigns

Discover partners with affiliates_list and affiliates_get. Use affiliate_campaigns_list and affiliate_campaigns_get for referral campaigns, not email campaigns. Campaign creation and editing stay in Creator Platform. affiliates_create can optionally enroll a new partner in an existing campaign. The underlying endpoint updates by duplicate email, so the tool scans the bounded account inventory for the exact email first and refuses a known duplicate. Concurrent same-email creation can still update an existing partner: there is no atomic create-only guarantee. Never use create as a profile-edit workaround or an access test. Enrollment may have native notification effects.

General profile replacement is not exposed as an API write. The endpoint clears omitted fields, and the read contract does not fully reconstruct enrollment and parent relationships. Use affiliate_native_actions with profile_replacement and edit in the native screen. affiliates_get omits tax IDs, tax forms and protected financial metadata; a returned profile is not a safe replacement body. affiliates_status_update separately activates or deactivates the partner.

Use affiliate_referral_validate for account-wide referral-ID availability, then affiliate_referral_update for an enrolled partner. Availability is not a reservation. IDs allow letters, digits and underscores, 3 to 64 characters. Changing one changes referral links.

affiliate_campaign_move requires sourceCampaignId, targetCampaignId, moveMode and confirmMoveEffects:true. Mode 1 retains recurring commissions in the old campaign. Mode 2 moves all data with the original partner ID. The target must be live and not already contain the partner. sendWelcomeEmail defaults to false; true explicitly requests the native welcome email if enabled on the target, not proof of delivery.

affiliate_campaign_suspension_update has financial effects: suspension cancels pending and denied payouts, commissions and transactions; reinstatement returns canceled items to pending. Only use it for explicit intent covering these effects, with confirmPayoutEffects:true. A boolean acknowledgment is not a substitute for user authorization.

## Referred leads and customers

Use affiliate_leads_validate to check a referred email, and affiliate_leads_create to create or update its lead and linked CRM record. Existing contactId is verified in this account. Creating a lead does not authorize marketing, imply consent, send messages or prove conversion. Read affiliate_customers_list for lead, customer or dropped states. Keep customer status separate from commission status. State update enables/disables a referral customer. Deletion is destructive and requires confirmDelete:true; this is not a separate CRM-contact deletion tool.

## Commissions and reporting

Read affiliate_commissions_list before a financial record change. Manual creation uses amount as the calculation base and native campaign rules determine commissionAmount. Do not call that base the amount paid or owed. Currency is required, and amounts in different currencies must not be combined. Missing amounts remain unavailable, not zero.

Create, status update, deny and delete require confirmCommissionChange:true and explicit financial intent. Status update and denial also change the associated payout; deletion requires confirmDelete:true. Marking a record paid does not transfer funds or establish bank settlement. These tools never initiate transfers.

affiliate_payouts_list is reporting only. pending, approved, paid, denied, canceled and payment_failed are distinct. inFlight:true selects processing payouts; false excludes in-flight items where the service supports it. gatewayState and gatewayProgress describe the reported gateway state. payment_failed is not paid, and processing, waiting_to_be_claimed, on_hold and unknown_status are not settlement. The tool omits opaque attempts, failure payloads, bank details, payout-method records and paid metadata. Use the native protected workflow for reconciliation or payment actions.

## Pagination and bounded ownership

Every list returns exactly one page plus pagination.skip, limit, total, hasMore, nextSkip, complete and coverage. Continue nextSkip with the same filters, dates and limit. Stop only when hasMore:false. total is a native count, not a computed revenue total; records may change between pages. complete is true only when that one page started at zero and included the full reported dataset. A final later page does not make earlier collection complete by itself. Null total or hasMore means coverage was not verified; report a partial result and use the native screen or support rather than assuming an empty or complete report. Never sum just the first page and call it all records.

Exact-ID actions without a documented read endpoint verify the selected record through account-scoped lists, at most 10 pages of 100 records. Missing/changing counts, repeated pages, missing ownership fields or an unresolved record stop the write. New-partner duplicate checks use the same bounded inventory, so an account above 1000 partners may need native creation. Larger or deeply nested media inventories may need the native screen. Current parent IDs can scope nested-media checks. These are safety limits, not missing-record claims. Provider-side changes can still race preflight; the API offers no general conditional-write version.

## Promotional media

affiliate_media_list reads promotional files and folders. showGlobal:true is read-only; records without explicit same-account ownership metadata fail closed, including global records that omit it. Use the native screen for those items. Update renames or moves owned media after parent-folder and bounded ancestry checks. Delete removes an owned file or folder and may remove its contents. It requires confirmDelete:true. Uploads remain native. Missing ownership metadata fails closed instead of permitting a global or foreign write.

## Protected work and recovery

Use affiliate_native_actions for bank_details, tax_forms, payout_methods, fund_transfer, profile_replacement, campaign_edit or media_upload. It returns HUMAN_ACTION_REQUIRED without submitting an action. The link opens the verified account root; go to Marketing > Affiliate Manager. Do not send bank numbers, payment credentials or tax documents to the agent.

Every mutation requires a stable 8 to 128 character requestId. Reuse it only for identical retries of the same intended effect. The service atomically claims the request and retains status plus safe record IDs, never a second partner/customer store or the request body. Identical retries return the receipt; conflicting arguments fail. A timeout, malformed confirmation or server failure can leave an unknown outcome, which is never automatically replayed. Check the referenced native record and receipt before deciding any further action. An accepted change does not establish notification delivery, referral revenue, conversion or settlement.

These are the currently implemented shared tools, subject to account access. Upstream API availability can change. Unavailable or denied reads are not zero activity, and documentation is not live account acceptance.
