> ## 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. # Retrieve tax reports You can retrieve Form 1099-K PDF documents for merchants who meet IRS reporting requirements. PayPal generates these reports annually and makes them available through the API by January 1 following the tax year. ## 1. List available tax reports Use a valid access token and make a GET call to the `/v2/taxes/reports` endpoint. Include the following query parameters: | Parameter | Action | | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `report_type`
Required, string | Set the type of tax report to retrieve. Use `1099-K`. | | `tax_year`
integer | Set the tax year. Example: `2024`. | | `exclude`
string | Set the comma-separated list of fields to exclude from response. Use `files_info` to retrieve only report metadata without file download links. | | `page`
integer | Set the page number for pagination. Default is `1`. | | `page_size`
integer | Set the number of reports per page. Default is `100`, maximum is `100`. | ```bash Sample request theme={null} curl -X GET 'https://api-m.sandbox.paypal.com/v2/taxes/reports?report_type=1099-K&tax_year=2024' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -H 'X-PAYPAL-SECURITY-CONTEXT: ' ``` ```json Sample response theme={null} { "reports": [ { "id": "11EF-CCBD-47F7C537-BADA-CB1E82FA8044", "account_id": "5U29WL78XSAE", "tax_year": 2024, "total_files": 1, "report_type": "1099-K", "corrected": false, "status": "GENERATION_COMPLETED", "create_time": "2025-01-07T06:04:51.101Z", "archive_time": "2035-01-05T06:04:51.101Z", "files_info": { "files": [ { "sequence": 1, "name": "1099K_2024_5074985856743188092_1736229880213.pdf", "links": [ { "href": "https://api.paypal.com/v2/content/documents/CMP-044-11ef-ccbd-4c4e9b80-bd01-b6a073d4df5f/files/1/download", "rel": "self", "method": "GET", "encType": "application/json" } ] } ], "total_items": 1, "links": [ { "href": "self", "rel": "https://api.paypal.com/v2/taxes/reports?file_info_page=1&file_info_page_size=10", "method": "GET" } ] }, "links": [ { "href": "https://api.paypal.com/v2/taxes/reports/11EF-CCBD-47F7C537-BADA-CB1E82FA8044", "rel": "self", "method": "GET" }, { "href": "https://api.paypal.com/v2/taxes/reports/11EF-CCBD-47F7C537-BADA-CB1E82FA8044/corrections", "rel": "correction", "method": "POST" } ] }, { "id": "11ED-DEDE-731E1268-918B-E8A6486BFD99", "account_id": "5U29WL78XSAE", "tax_year": 2023, "total_files": 1, "report_type": "1099-K", "corrected": false, "status": "GENERATED", "create_time": "2023-04-19T18:17:37.009Z", "archive_time": "2033-04-16T18:17:37.009Z", "files_info": { "files": [ { "sequence": 1, "name": "1099K_2023_5074985856743188092_1681928252161.pdf", "links": [ { "href": "https://api.paypal.com/v2/content/documents/CMP-044-1502b636-4eff-4f92-8be8-a1f5768115ac/files/1/download", "rel": "self", "method": "GET" } ] } ], "total_items": 1 }, "links": [ { "href": "https://api.paypal.com/v2/taxes/reports/11ED-DEDE-731E1268-918B-E8A6486BFD99", "rel": "self", "method": "GET" } ] } ], "links": [ { "rel": "self", "href": "https://api.paypal.com/v2/taxes/reports?page=1&page_size=100", "method": "GET" }, { "rel": "first", "href": "https://api.paypal.com/v2/taxes/reports?page=1&page_size=100", "method": "GET" }, { "rel": "next", "href": "https://api.paypal.com/v2/taxes/reports?page=2&page_size=100", "method": "GET" }, { "rel": "last", "href": "https://api.paypal.com/v2/taxes/reports?page=1&page_size=100", "method": "GET" } ] } ``` A successful call returns a `200 OK` response. The response includes the following parameters: | Parameter | Description | Further action | | ------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `reports[].id`
string | Unique identifier for the report. | Get specific report details or submit corrections. | | `reports[].corrected`
boolean | Indicates if the report was corrected. | Identify corrected reports and notify merchants. | | `reports[].status`
string | Current report status.

**Possible values:**
`QUEUED` - Request received, processing not yet started
`GENERATION_IN_PROGRESS` - Report generation in progress
`GENERATION_COMPLETED` - File generated and available for download
`GENERATION_FAILED` - Generation encountered an error
`EXPIRED` - File no longer available | Download reports with `GENERATION_COMPLETED` status. | | `reports[].files_info.files[].links`
array | HATEOAS links for file operations. The link with `rel: "self"` provides the PDF download URL. | Download the PDF file using the `href` value. | ## 2. Get specific report details Use a valid access token and make a GET call to the `/v2/taxes/reports/{reportId}` endpoint. **Path parameter**: `reportId` is the unique identifier for the tax report, retrieved from the List available tax reports response. ```bash Sample request theme={null} curl -X GET 'https://api-m.sandbox.paypal.com/v2/taxes/reports/11EF-CCBD-47F7C537-BADA-CB1E82FA8044' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -H 'X-PAYPAL-SECURITY-CONTEXT: ' ``` ```json Sample response theme={null} { "id": "11EF-CCBD-47F7C537-BADA-CB1E82FA8044", "account_id": "5U29WL78XSAE", "tax_year": 2024, "total_files": 1, "report_type": "1099-K", "corrected": false, "status": "GENERATION_COMPLETED", "create_time": "2025-01-07T06:04:51.101Z", "archive_time": "2035-01-05T06:04:51.101Z", "files_info": { "files": [ { "sequence": 1, "name": "1099K_2024_5074985856743188092_1736229880213.pdf", "links": [ { "href": "https://api.paypal.com/v2/content/documents/CMP-044-11ef-ccbd-4c4e9b80-bd01-b6a073d4df5f/files/1/download", "rel": "self", "method": "GET", "encType": "application/json" }, { "href": "https://api.paypal.com/v2/content/documents/CMP-044-11ef-ccbd-4c4e9b80-bd01-b6a073d4df5f", "rel": "metadata", "method": "GET", "encType": "application/json" } ] } ], "total_items": 1, "links": [ { "href": "self", "rel": "https://api.paypal.com/v2/taxes/reports?file_info_page=1&file_info_page_size=10", "method": "GET" } ] }, "links": [ { "href": "https://api.paypal.com/v2/taxes/reports/11EF-CCBD-47F7C537-BADA-CB1E82FA8044", "rel": "self", "method": "GET" }, { "href": "https://api.paypal.com/v2/taxes/reports/11EF-CCBD-47F7C537-BADA-CB1E82FA8044/corrections", "rel": "correction", "method": "POST" } ] } ``` ## 3. Download tax report PDF Use a valid access token and make a GET call to the file download URL from the `files_info.files[].links` array. ```bash Sample request theme={null} curl -X GET 'https://api-m.sandbox.paypal.com/v2/content/documents/CMP-044-11ef-ccbd-4c4e9b80-bd01-b6a073d4df5f/files/1/download' \ -H 'Authorization: Bearer ' \ -H 'X-PAYPAL-SECURITY-CONTEXT: ' \ --output 1099K_2024.pdf ``` The PDF file contains: * Merchant's legal name and address. * Truncated TIN showing only the last 4 digits. * Monthly gross payment amounts for the tax year. * Total annual gross payment amount. * Payment card and third-party network transactions breakdown. * PayPal's information as the Payment Settlement Entity and filer. The merchant copy shows only the last 4 digits of the TIN for security purposes. Forms filed with the IRS and state agencies include the full 9-digit TIN. ## 4. Handle webhook notifications Configure your webhook handler to process tax reporting events and take appropriate action based on the event type. For webhook setup, see Set up webhook notifications. ### TAXES.REPORTS.GENERATED When you receive a `TAXES.REPORTS.GENERATED` webhook event, your webhook handler should: 1. Extract the `resource.id` value from the webhook payload. 2. Check the `resource.is_corrected` field to identify whether this is a regular or corrected report. 3. Use this report ID to Get specific report details. 4. Download the PDF file using the file download link from the response. 5. Deliver the form to your merchant through your platform. ### TAXES.REPORT\_COUNT\_UPDATED When you receive a `TAXES.REPORT_COUNT_UPDATED` webhook event, your webhook handler should: 1. Extract the `reportCounts` array from the webhook payload. 2. Track the `count_value` for each counter for billing and reconciliation purposes. 3. Use `counter_name`, `counter_type`, and `product_attributes` to identify the type of reports counted (electronic federal, paper state). ```json TAXES.REPORTS.GENERATED (Regular report) theme={null} { "id": "WH-COC11055RA711503B-4YM959094A144403T", "event_type": "TAXES.REPORTS.GENERATED", "resource_type": "TAX-REPORT", "resource": { "id": "11EF-C99C-DAB460D9-B5FE-CF39DF1DE4AF", "account_id": "5U29WL78XSAE", "report_type": "1099-K", "tax_year": 2024, "is_corrected": false, "status": "GENERATION_COMPLETED", "links": [ { "href": "/v2/taxes/reports/11EF-C99C-DAB460D9-B5FE-CF39DF1DE4AF", "rel": "self", "method": "GET" } ] } } ``` ```json TAXES.REPORTS.GENERATED (Corrected report) theme={null} { "id": "WH-XYZ99088AB822604C-9ZN070195B255514U", "event_type": "TAXES.REPORTS.GENERATED", "resource_type": "TAX-REPORT", "resource": { "id": "11ED-FAC1-508DB6F6-8C1B-42A3FDA7CBC5", "account_id": "5U29WL78XSAE", "report_type": "1099-K", "tax_year": 2024, "is_corrected": true, "status": "GENERATION_COMPLETED", "original_report_id": "11EF-A741-C86DDAC4-BE58-CF8F5BF706E8", "links": [ { "href": "/v2/taxes/reports/11ED-FAC1-508DB6F6-8C1B-42A3FDA7CBC5", "rel": "self", "method": "GET" } ] } } ``` ```json TAXES.REPORT_COUNT_UPDATED theme={null} { "specversion": "1.0", "id": "34957435872E", "type": "TAXES.REPORT_COUNT_UPDATED", "source": "tax-report-service", "time": "2024-10-27T10:00:00Z", "reportCounts": [ { "counter_name": "WIX_CORE_1099K_ELECTRONIC_FEDERAL", "counter_type": "YEARLY", "start_time": "2024-01-01T00:00:00+05:30", "report_type": "SUMMARY", "description": "Sales_1099-K", "count_value": 15000, "metadata": { "tenant": "PAYPAL", "partner": { "account_number": "5074670210318800555", "account_type": "BUSINESS", "country_code": "US" }, "merchant": {}, "product_attributes": { "fee_event_type": "TEN99K", "service_type": "NON_TRANSACTIONAL", "properties": [ { "name": "process_count", "value": "15000" }, { "name": "process_type", "value": "FEDERAL_FILING" }, { "name": "form_type", "value": "ELECTRONIC" }, { "name": "tax_year", "value": "2025" } ] } } } ], "extensions": { "correlationId": "some-correlation-id", "xPaypalSecurityContext": "some-security-context", "paypalTenantContext": "some-tenant-context", "paypalApplicationContext": "some-application-context" } } ``` ## Tax report lifecycle and availability * PayPal generates reports after the tax year ends and makes them available by January 1 of the year following the tax year. * PayPal retains reports for 10 years from the creation date. * PayPal generates a new report with `is_corrected: true` when you process corrections. The original report remains accessible. * You can access reports for multiple tax years through a single API endpoint.