🧾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 approved status to claim

• Affiliates 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:

Action	Endpoint
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

Status	Meaning
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.

Endpoint	Behavior
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

Action	Endpoint
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

Field	Description
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

Field	Description
require_tax_info	Whether affiliates must submit tax info before claiming
company_*	Company legal name, address, tax ID, contact email