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 valid access token and make a GET call to the /v2/taxes/reportable-accounts endpoint. Include the following query parameters:

Parameter	Action
report_type Required, string	Set the type of tax report. Use 1099-K.
tax_year Required, string	Set the tax year. Example: 2024.
page integer	Set the page number for pagination. Default is 1.
page_size integer	Set the number of accounts per page. Default is 100.

Sample request

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

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

Parameter	Description	Further action
reportable_accounts[].id string	Unique identifier for the reportable account.	Get a reportable account or update tax data.

2. Get a reportable account

Use a valid access token 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 List reportable accounts 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.

Sample request

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

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

Parameter	Description	Further action
id string	Reportable account ID.	Update reportable account tax data.
tax_processing_status string	Status of tax processing. Possible values: NOT_STARTED - Tax processing has not started. TAX_DATA_NEED_APPROVAL - Tax data requires approval before report generation. TAX_DATA_CHANGE_IN_REVIEW - PayPal is reviewing submitted tax data changes. TAX_DATA_APPROVED - PayPal approved the tax data for report generation. REPORT_GENERATED - PayPal generated the tax report. REPORT_CORRECTION_IN_REVIEW - PayPal is reviewing the report correction. REPORT_CORRECTION_READY - Report correction is ready for processing. REPORT_CORRECTED - PayPal generated a new corrected report. REPORT_FILED - PayPal filed the report.	When REPORT_GENERATED, REPORT_CORRECTED, or REPORT_FILED, retrieve the tax report.
tax_data.editable boolean	Indicates whether the tax data can be modified.	Verify this is true before updating tax data.

3. Update reportable account tax data

Use a valid access token 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 List reportable accounts response.

Parameter	Action
op Required, string	Set the operation to perform. Supported values: add, replace, remove.
path Required, string	Slash-separated path that specifies the field to update. For example, /tax_data/account_profile/business_entity/type updates the business entity type.
value any	Set the new value for the field. Required for add and replace operations.

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.

Sample request - Update profile

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"
    }
]'

A successful call returns a 204 No Content response.