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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.fuul.xyz/core-concepts/tax-information.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.