API endpoints — API/SDK advanced
The attribution, discount and billing operations available through the v1 API for API/SDK advanced integrations.
Updated August 3, 2026
These endpoints are for API/SDK advanced integrations. Stripe automatic uses the selected Payment Link and AffiHQ-managed Stripe Connect deliveries instead; it does not need product keys or these endpoints for connected Stripe payment facts. In API/SDK advanced, all request bodies are JSON. Timestamps use RFC 3339 with an explicit offset and monetary values are non-negative integers in the currency’s minor unit.
/api/v1/references/validatePreviews an opaque link reference or manual code and returns eligibility plus the effective discount instruction.
Validation does not reserve or lock an attribution. Include the product-scoped customer fingerprint when you need self-referral protection.
/api/v1/attributionsLocks the first qualified affiliate for a product and opaque merchant customer ID.
The response contains immutable commission and discount snapshots. Replaying the same intent returns the existing attribution; a later reference cannot replace it.
/api/v1/attributions/{id}/discount?billingCycle=monthlyReturns the discount instruction frozen when the attribution was created.
Your application translates this instruction to Stripe or its own billing provider. AffiHQ does not create or redeem coupons.
/api/v1/billing-eventsAccepts verified custom or non-native payments, refunds and disputes with a required idempotency key.
For API/SDK advanced, authenticate the original provider webhook first. Use this endpoint for custom or non-native billing facts. Stripe automatic delivers connected Stripe events to AffiHQ itself; never forward the same events or duplicate them through this endpoint. An accepted payment event can create a commission; a signup by itself cannot.
Status codes
| Status | Meaning |
|---|---|
200 | Read, validation or idempotent replay |
201 | Attribution created |
202 | Financial event accepted |
400 | Invalid JSON or contract |
401 | Missing or invalid product key |
404 | Reference or attribution not found |
409 | Attribution or idempotency conflict |
422 | Reference known but not eligible |
429 | Rate limited; retry with backoff |
5xx | Temporary failure; retry with backoff |