canonical: https://jentic.com/apis/getrewardful.com/getrewardful # Getrewardful Rewardful API Rewardful is an affiliate, referral, and partner-marketing platform for SaaS companies that bills through Stripe. The REST API exposes 14 endpoints covering affiliate enrolment and lookup, campaign management, referral tracking, and commission lifecycle including update and delete. It is the integration surface for embedding affiliate dashboards in customer portals, syncing referral data into a CRM, and automating commission adjustments based on refund or fraud signals. ## For AI agents Manage Rewardful affiliates, campaigns, referrals, and commissions, plus mint affiliate SSO links, through an HTTP basic-auth API key. ## Scope Does not handle payment processing, fraud screening, or email delivery - use for affiliate, referral, campaign, and commission management only. ## Capabilities - Enrol an affiliate into a specific campaign with their email and payout details - List referrals attributed to a campaign or affiliate over a date window - Adjust a commission's amount or state after a refund, chargeback, or dispute - Generate a one-time SSO magic link so an affiliate can land in their dashboard - Create and update campaigns to change reward percentages or cookie windows - Retrieve a single affiliate or commission for back-office reconciliation ## Use cases ### Embed an affiliate dashboard in your product SaaS companies surface affiliate stats inside the customer portal rather than sending users to Rewardful's hosted UI. The API returns affiliate, referral, and commission data, and the SSO magic-link endpoint lets users jump into the full Rewardful dashboard for actions such as updating payout details without re-authenticating. Example prompt: Fetch referrals for affiliate aff_123 in the current month and render a summary, then mint an SSO link to the full dashboard ### Refund-aware commission adjustment When Stripe issues a refund, the commission for that referral often needs voiding. An automation pulls the related commission, calls PATCH `/commissions/{commissionId}` to change its state, and logs the adjustment. This keeps payouts accurate without manual reconciliation in the Rewardful UI. Example prompt: When Stripe webhook charge.refunded fires, find the matching Rewardful commission and PATCH it to state 'void' ### Bulk affiliate onboarding from a partner programme A partnerships team imports a list of new affiliates from a CSV after an event or campaign launch. The API lets a script POST each affiliate with the right campaign id and email, returning the affiliate id used in subsequent referral tracking. This avoids the hosted sign-up flow when affiliates are pre-vetted. Example prompt: For each row in partners.csv, POST /affiliates with the email and campaign id and write the returned affiliate id back to the row ### AI agent for partner ops An ops agent connected through Jentic answers questions like 'how much do we owe Acme this quarter?' by listing commissions filtered by affiliate and date range, summing eligible amounts, and surfacing pending versus due payouts. Jentic handles the basic-auth credential so the agent never sees the raw API secret. Example prompt: List commissions for affiliate aff_acme over the last quarter and return total due and total paid ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | `/affiliates` | Enrol a new affiliate | | GET | `/affiliates` | List affiliates | | POST | `/affiliates/{affiliateId}/sso` | Generate an affiliate SSO magic link | | GET | `/referrals` | List referrals | | GET | `/commissions` | List commissions | | PATCH | `/commissions/{commissionId}` | Update a commission | | POST | `/campaigns` | Create a campaign | ## Key resources - **Affiliates** — Affiliate enrolment, retrieval, update, and SSO link minting - **Referrals** — Conversion records attributing customers to an affiliate and campaign - **Commissions** — Payouts owed on referrals with full update and delete support - **Campaigns** — Reward structures, cookie windows, and program lifecycle ## Why Jentic - **Setup:** Wiring Rewardful by hand means encoding its HTTP basic secret, paging over affiliates, referrals, and commissions, and shaping campaign and SSO payloads yourself. Through Jentic you install once, import the Rewardful API from the API Directory, store the secret once, and your agent calls it. - **Permission scoping:** Rewardful exposes affiliates, referrals, commissions, and campaigns as its resources, so you limit the agent to the operations it needs, such as listing commissions or reading referrals. Because you pick the operation set, changes like updating a commission or creating a campaign are not reachable unless you add them. - **Credential handling:** Your Rewardful API secret is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'list Rewardful commissions' or 'create an affiliate', and Jentic returns the matching Rewardful operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **ReferralCandy API** — Customer-referral programme platform aimed primarily at e-commerce stores - **Refersion API** — Affiliate and ambassador platform with strong e-commerce integrations - **Stripe API** — Rewardful tracks referrals against Stripe customers and subscriptions ## FAQ ### What authentication does the Rewardful API use? Rewardful uses HTTP basic authentication with your API secret as the username and a blank password. Through Jentic the secret is stored encrypted in the vault and the basic-auth header is built per request, so the raw key never enters agent context. ### Can I update a commission after it has been issued? Yes. PATCH `/commissions/{commissionId}` accepts updates to the commission state and amount, and DELETE on the same path removes it. This is the supported way to handle refund and chargeback adjustments without the Rewardful web UI. ### What are the rate limits for the Rewardful API? The OpenAPI spec does not declare hard rate limits. Treat the API as polite-use and paginate when listing affiliates, referrals, or commissions; for high-volume reconciliation jobs schedule them outside peak hours and back off on any 429 responses. ### How do I enrol an affiliate into a campaign through Jentic? Search Jentic for 'create rewardful affiliate', load the POST /affiliates schema, then execute with the email, first and last name, and campaign id. Jentic injects the basic-auth header automatically. ### Can I generate a one-click sign-in link for an affiliate? Yes. POST `/affiliates/{affiliateId}/sso` returns a single-use magic link that drops the affiliate directly into their Rewardful dashboard. This is the supported way to bridge from your product UI into Rewardful without asking the affiliate to log in again. ### Is the Rewardful API free? API access is bundled into all paid Rewardful plans and there is no separate API metering. Pricing scales with referral revenue rather than API call volume - check getrewardful.com/pricing for the current tiers. ### Can I limit what my agent is allowed to do with the Rewardful API? Yes. Because Jentic One is self-hosted, you decide which Rewardful operations the agent may call across its affiliates, referrals, commissions, and campaigns resources. You can grant read-only access, such as listing commissions or reading referrals, and leave out anything you have not approved. Write operations like updating a commission or creating a campaign stay unreachable unless you explicitly add them to the operation set, and your API secret is injected at execution time rather than exposed to the agent.