> ## Documentation Index
> Fetch the complete documentation index at: https://paypal-sb-staging.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Prepare merchant tax data

You can retrieve and update tax data for merchants before PayPal generates tax reports. Merchants who exceed IRS thresholds for Form 1099-K have reportable accounts.

## 1. List reportable accounts

Use a <a href="/developer/how-to/api/get-started#2-get-an-access-token" target="_blank" rel="noopener noreferrer">valid access token</a> and make a GET call to the `/v2/taxes/reportable-accounts` endpoint. Include the following query parameters:

| <span style={{textAlign: 'left', display: 'block'}}>Parameter</span>                                                                                      | <span style={{textAlign: 'left', display: 'block'}}>Action</span> |
| --------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| `report_type`<br /><span style={{color: 'red', fontSize: 'smaller'}}>Required</span>, <span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span> | Set the type of tax report. Use `1099-K`.                         |
| `tax_year`<br /><span style={{color: 'red', fontSize: 'smaller'}}>Required</span>, <span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span>    | Set the tax year. Example: `2024`.                                |
| `page`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>integer</span>                                                                          | Set the page number for pagination. Default is `1`.               |
| `page_size`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>integer</span>                                                                     | Set the number of accounts per page. Default is `100`.            |

<CodeGroup>
  ```bash Sample request theme={null}
  curl -X GET 'https://api-m.sandbox.paypal.com/v2/taxes/reportable-accounts?report_type=1099-K&tax_year=2024' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS-TOKEN>' \
  -H 'X-PAYPAL-SECURITY-CONTEXT: <SECURITY-CONTEXT>'
  ```

  ```json Sample response theme={null}
  {
      "reportable_accounts": [
          {
              "id": "11EF-CCBD-47F7C537-BADA-CB1E82FA8044",
              "tax_year": "2024",
              "report_type": "1099-K",
              "payer_id": "5U29WL78XSAE",
              "eligible": true,
              "tax_processing_status": "NOT_STARTED",
              "links": [
                  {
                      "href": "https://api.paypal.com/v2/taxes/reportable-accounts/11EF-CCBD-47F7C537-BADA-CB1E82FA8044",
                      "rel": "self",
                      "method": "GET"
                  },
                  {
                      "href": "https://api.paypal.com/v2/taxes/reportable-accounts/11EF-CCBD-47F7C537-BADA-CB1E82FA8044",
                      "rel": "edit",
                      "method": "PATCH"
                  }
              ]
          },
          {
              "id": "11ED-DEDE-731E1268-918B-E8A6486BFD99",
              "tax_year": "2024",
              "report_type": "1099-K",
              "payer_id": "7X38KM92RTBC",
              "eligible": true,
              "tax_processing_status": "TAX_DATA_APPROVED",
              "links": [
                  {
                      "href": "https://api.paypal.com/v2/taxes/reportable-accounts/11ED-DEDE-731E1268-918B-E8A6486BFD99",
                      "rel": "self",
                      "method": "GET"
                  }
              ]
          }
      ],
      "total_items": 2,
      "total_pages": 1,
      "links": [
          {
              "rel": "self",
              "href": "https://api.paypal.com/v2/taxes/reportable-accounts?page=1&page_size=100",
              "method": "GET"
          },
          {
              "rel": "first",
              "href": "https://api.paypal.com/v2/taxes/reportable-accounts?page=1&page_size=100",
              "method": "GET"
          },
          {
              "rel": "last",
              "href": "https://api.paypal.com/v2/taxes/reportable-accounts?page=1&page_size=100",
              "method": "GET"
          }
      ]
  }
  ```
</CodeGroup>

A successful call returns a `200 OK` response. The response includes the following parameter:

| <span style={{textAlign: 'left', display: 'block'}}>Parameter</span>                                | <span style={{textAlign: 'left', display: 'block'}}>Description</span> | <span style={{textAlign: 'left', display: 'block'}}>Further action</span>                                                                  |
| --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `reportable_accounts[].id`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span> | Unique identifier for the reportable account.                          | <a href="#2-get-a-reportable-account">Get a reportable account</a> or <a href="#3-update-reportable-account-tax-data">update tax data</a>. |

## 2. Get a reportable account

Use a <a href="/developer/how-to/api/get-started#2-get-an-access-token" target="_blank" rel="noopener noreferrer">valid access token</a> and make a GET call to the `/v2/taxes/reportable-accounts/{id}` endpoint. Include the following parameters:

**Path parameter**: `id` is the reportable account identifier, retrieved from the <a href="#1-list-reportable-accounts">List reportable accounts</a> response.

**Query parameter**: `fields` is a comma-separated list of fields to include in the response. Possible values are `tax_data.account_profile`, `tax_data.aggregated_transactions`, and `tax_data.tax_properties`.

<CodeGroup>
  ```shell lines title="Sample request" theme={null}
  curl -X GET 'https://api-m.sandbox.paypal.com/v2/taxes/reportable-accounts/11EF-CCBD-47F7C537-BADA-CB1E82FA8044?fields=tax_data.account_profile,tax_data.aggregated_transactions,tax_data.tax_properties' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS-TOKEN>' \
  -H 'X-PAYPAL-SECURITY-CONTEXT: <SECURITY-CONTEXT>'
  ```

  ```json lines title="Sample response" theme={null}
  {
      "id": "11EF-CCBD-47F7C537-BADA-CB1E82FA8044",
      "tax_year": "2024",
      "report_type": "1099-K",
      "payer_id": "5U29WL78XSAE",
      "eligible": true,
      "tax_processing_status": "NOT_STARTED",
      "tax_data": {
          "editable": true
      },
      "links": [
          {
              "href": "https://api.paypal.com/v2/taxes/reportable-accounts/11EF-CCBD-47F7C537-BADA-CB1E82FA8044",
              "rel": "self",
              "method": "GET"
          },
          {
              "href": "https://api.paypal.com/v2/taxes/reportable-accounts/11EF-CCBD-47F7C537-BADA-CB1E82FA8044",
              "rel": "edit",
              "method": "PATCH"
          }
      ]
  }
  ```
</CodeGroup>

A successful call returns a `200 OK` response. The response includes the following parameters:

| <span style={{textAlign: 'left', display: 'block'}}>Parameter</span>                             | <span style={{textAlign: 'left', display: 'block'}}>Description</span>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | <span style={{textAlign: 'left', display: 'block'}}>Further action</span>                                                                                                                                 |
| ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span>                    | Reportable account ID.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | <a href="#3-update-reportable-account-tax-data">Update reportable account tax data</a>.                                                                                                                   |
| `tax_processing_status`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span> | Status of tax processing.<br /><br />**Possible values:**<br />`NOT_STARTED` - Tax processing has not started.<br />`TAX_DATA_NEED_APPROVAL` - Tax data requires approval before report generation.<br />`TAX_DATA_CHANGE_IN_REVIEW` - PayPal is reviewing submitted tax data changes.<br />`TAX_DATA_APPROVED` - PayPal approved the tax data for report generation.<br />`REPORT_GENERATED` - PayPal generated the tax report.<br />`REPORT_CORRECTION_IN_REVIEW` - PayPal is reviewing the report correction.<br />`REPORT_CORRECTION_READY` - Report correction is ready for processing.<br />`REPORT_CORRECTED` - PayPal generated a new corrected report.<br />`REPORT_FILED` - PayPal filed the report. | When `REPORT_GENERATED`, `REPORT_CORRECTED`, or `REPORT_FILED`, <a href="/limited-release/manage-tax-reports/retrieve-tax-reports" target="_blank" rel="noopener noreferrer">retrieve the tax report</a>. |
| `tax_data.editable`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>boolean</span>    | Indicates whether the tax data can be modified.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Verify this is `true` before <a href="#3-update-reportable-account-tax-data">updating tax data</a>.                                                                                                       |

## 3. Update reportable account tax data

Use a <a href="/developer/how-to/api/get-started#2-get-an-access-token" target="_blank" rel="noopener noreferrer">valid access token</a> and make a PATCH call to the `/v2/taxes/reportable-accounts/{id}` endpoint. Include the following parameters:

**Path parameter**: `id` is the reportable account identifier, retrieved from the <a href="#1-list-reportable-accounts">List reportable accounts</a> response.

| <span style={{textAlign: 'left', display: 'block'}}>Parameter</span>                                                                               | <span style={{textAlign: 'left', display: 'block'}}>Action</span>                                                                                        |
| -------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `op`<br /><span style={{color: 'red', fontSize: 'smaller'}}>Required</span>, <span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span>   | Set the operation to perform. Supported values: `add`, `replace`, `remove`.                                                                              |
| `path`<br /><span style={{color: 'red', fontSize: 'smaller'}}>Required</span>, <span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span> | Slash-separated path that specifies the field to update. For example, `/tax_data/account_profile/business_entity/type` updates the business entity type. |
| `value`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>any</span>                                                                      | Set the new value for the field. Required for `add` and `replace` operations.                                                                            |

<Warning>
  You can only update tax data when `tax_data.editable` is `true`. PayPal restricts modifications based on business rules such as filing status, tax year closure, or review state.
</Warning>

<CodeGroup>
  ```shell lines title="Sample request - Update profile" theme={null}
  curl -X PATCH 'https://api-m.sandbox.paypal.com/v2/taxes/reportable-accounts/11EF-CCBD-47F7C537-BADA-CB1E82FA8044' \
  -H 'Content-Type: application/json-patch+json' \
  -H 'Authorization: Bearer <ACCESS-TOKEN>' \
  -H 'X-PAYPAL-SECURITY-CONTEXT: <SECURITY-CONTEXT>' \
  -d '[
      {
          "op": "replace",
          "path": "/tax_data/account_profile/business_entity/legal_name/business_name",
          "value": "Johnson Consulting & Advisory LLC"
      },
      {
          "op": "replace",
          "path": "/tax_data/account_profile/business_entity/legal_name/type",
          "value": "DOING_BUSINESS_AS"
      },
      {
          "op": "replace",
          "path": "/tax_data/account_profile/business_entity/type",
          "value": "LIMITED_LIABILITY_PARTNERSHIP"
      }
  ]'
  ```

  ```shell lines title="Sample request - Add transactions" theme={null}
  curl -X PATCH 'https://api-m.sandbox.paypal.com/v2/taxes/reportable-accounts/11EF-CCBD-47F7C537-BADA-CB1E82FA8044' \
  -H 'Content-Type: application/json-patch+json' \
  -H 'Authorization: Bearer <ACCESS-TOKEN>' \
  -H 'X-PAYPAL-SECURITY-CONTEXT: <SECURITY-CONTEXT>' \
  -d '[
      {
          "op": "add",
          "path": "/tax_data/aggregated_transactions/0",
          "value": {
              "transaction_classifications": [
                  {
                      "type": "RECV_MONEY",
                      "sub_type": "GOODS_AND_SERVICES"
                  }
              ],
              "start_time": "2024-09-01T00:00:00-07:00",
              "aggregation_window": "P1M",
              "total_amount_in_usd": {
                  "currency_code": "USD",
                  "value": "2500.00"
              }
          }
      }
  ]'
  ```

  ```shell lines title="Sample request - Set tax properties" theme={null}
  curl -X PATCH 'https://api-m.sandbox.paypal.com/v2/taxes/reportable-accounts/11EF-CCBD-47F7C537-BADA-CB1E82FA8044' \
  -H 'Content-Type: application/json-patch+json' \
  -H 'Authorization: Bearer <ACCESS-TOKEN>' \
  -H 'X-PAYPAL-SECURITY-CONTEXT: <SECURITY-CONTEXT>' \
  -d '[
      {
          "op": "add",
          "path": "/tax_data/tax_properties/0",
          "value": {
              "group": "IRS_1099K",
              "name": "ECONSENT_PAPER_DELIVERY",
              "value": "Y"
          }
      }
  ]'
  ```
</CodeGroup>

A successful call returns a `204 No Content` response.