> For the complete documentation index, see [llms.txt](https://docs.fuul.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fuul.xyz/core-concepts/affiliates/tax-information.md).

# 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) |

{% hint style="warning" %}
W-8 forms (W-8BEN, W-8BEN-E) expire after 3 years. When expired, the affiliate must resubmit before claiming.
{% endhint %}

## 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.                                                                                         |

{% hint style="info" %}
End-user payout claims are never blocked — only affiliate claims are subject to the tax gate.
{% endhint %}

## 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      |