SmoothProfitDocs
ProductStart free

Getting started

  • Introduction
  • Quickstart
  • Authentication
  • Errors & rate limits

Core concepts

  • Tenancy model
  • Attribution
  • Commission resolution
  • Payout lifecycle

Guides

  • Install the tracker
  • Connect a storefront
  • Affiliate storefronts

API reference

  • Context
  • Affiliates
  • Conversions
  • Landing pages
  • Coupons
  • Payouts
  • Providers
  • Tracking

Core concepts

Payout lifecycle

A commission passes through four states before it becomes money.

example
pending      Recorded. Holding period running.
approved     Agency accepted it. Eligible once the hold expires.
paid         Sent through the payout provider.
clawed_back  Reversed after a refund, cancellation, or dispute.

What makes a commission payable

Every one of these must hold. Preview them with payouts/pending.

  • Status is approved and the holding period has elapsed.
  • The affiliate is active.
  • Tax information is on file. Required regardless of provider — your payment processor's KYC does not substitute for the agency's own 1099 reporting obligation.
  • A payout account is connected (except on manual CSV, which has no account concept).
  • Their total is at or above the program's minimum payout threshold.
Affiliates who miss a check are skipped, not failed. Their conversions stay approved and roll into the next batch once they qualify. The preview endpoint returns each one with an explicit blockedReason — an agency needs to see why someone isn't getting paid, not just find them missing from a list.

Providers

  • Stripe Connect — hosted onboarding, automatic transfers. The default.
  • PayPal Payouts — sends to a receiver email. Note an unclaimed payout is held by PayPal for 30 days and then returned.
  • Wise — for international partners. Requires the recipient to already exist in Wise; SmoothProfit does not collect international bank details.
  • Manual CSV — records the disbursement and exports a remittance file. Money moves when you move it.

Batches

A dispatch groups every eligible commission into one payment per affiliate and records a batch with per-affiliate line items. One affiliate failing does not abort the rest — each gets its own result, and a batch reports as completed, partial, or failed.

Clawbacks after payment

Reversing an already-paid commission does not un-pay it — the money is gone. The conversion is marked clawed_back with the original amount preserved, and the clawback response returns alreadyPaidCents so you know what to recover. Silently refusing would leave the ledger claiming a refunded sale still earned.