π§ΎTax Information
Projects can require affiliates to submit tax information (W-9, W-8BEN, or W-8BEN-E forms) before they can claim rewards. This is separate from the end-user claiming flow β only affiliate payouts are affected.
How It Works
When require_tax_info is enabled on a project:
Affiliates with at least one affiliate payout must have their tax info in
approvedstatus to claimAffiliates without any affiliate payouts (only end-user payouts) are not blocked
Claim flows return a restricted payload instead of a 403 error when the gate is active but not passed
Affiliate Self-Service
Affiliates manage their tax information through the affiliate portal:
Submit tax info
POST /api/v1/projects/:projectId/affiliate-portal/tax-info
View submitted info
GET /api/v1/projects/:projectId/affiliate-portal/tax-info
Check status
GET /api/v1/projects/:projectId/affiliate-portal/tax-status
Tax Status Values
not_required
Project does not require tax info
not_submitted
Required but affiliate hasn't submitted
submitted
Form submitted, pending review
approved
Approved β affiliate can claim
revoked
Revoked by admin
expired
W-8 form expired (W-8 forms typically expire after 3 years)
W-8 forms (W-8BEN, W-8BEN-E) expire after 3 years. When expired, the affiliate must resubmit before claiming.
Claim Blocking Behavior
When require_tax_info is true and the affiliate has at least one affiliate payout but their tax info is not approved, the claim endpoints return a restricted payload instead of the full data.
GET /api/v1/claim-checks
Returns HTTP 200 with the standard list shape. Restricted items include restriction_message and omit deadline_seconds.
POST /api/v1/claim-checks/claim
Returns HTTP 200 with restricted rows. Restricted rows include restriction_message and omit deadline, proof, and signatures.
POST /api/v1/claim-checks/close
Returns the full ClaimResponse on success.
End-user payout claims are never blocked β only affiliate claims are subject to the tax gate.
Admin Endpoints
View full tax info (unmasked)
GET /api/v1/projects/:projectId/affiliates/:userIdentifier/tax-status
List affiliates (includes tax_status)
GET /api/v1/projects/:projectId/affiliates
Update tax settings
PATCH /api/v1/projects/:projectId/tax-settings
Tax settings include require_tax_info, company legal name, address, tax ID, and contact email β all used for tax reporting purposes.
Tax info fields
Affiliate tax info
form_type
w9, w8ben, or w8bene
status
submitted, approved, revoked, expired
legal_name
Legal name of the individual or entity
country
Country of residence or incorporation
tax_id_number
Encrypted β SSN/EIN (W-9) or foreign TIN
signature_date
Date the form was signed
expires_at
Expiration date (W-8 forms)
revoked_reason
Reason for revocation (if revoked)
Project tax settings
require_tax_info
Whether affiliates must submit tax info before claiming
company_*
Company legal name, address, tax ID, contact email
Last updated