Retrieve tax reports

DocsLimited

Last updated: Jan 22nd, 10:33pm

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.

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

Sample request
Sample response

1curl -X GET 'https://api-m.sandbox.paypal.com/v2/taxes/reports?report_type=1099-K&tax_year=2024' \
2-H 'Content-Type: application/json' \
3-H 'Authorization: Bearer <ACCESS-TOKEN>' \
4-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
`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 th `href` value.

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.

Sample request
Sample response

1curl -X GET 'https://api-m.sandbox.paypal.com/v2/taxes/reports/11EF-CCBD-47F7C537-BADA-CB1E82FA8044' \
2-H 'Content-Type: application/json' \
3-H 'Authorization: Bearer <ACCESS-TOKEN>' \
4-H 'X-PAYPAL-SECURITY-CONTEXT: <SECURITY-CONTEXT>'

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.

1curl -X GET 'https://api-m.sandbox.paypal.com/v2/content/documents/CMP-044-11ef-ccbd-4c4e9b80-bd01-b6a073d4df5f/files/1/download' \
2-H 'Authorization: Bearer <ACCESS-TOKEN>' \
3-H 'X-PAYPAL-SECURITY-CONTEXT: <SECURITY-CONTEXT>' \
4--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.

Note: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.

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:

Extract the resource.id value from the webhook payload.

Check the resource.corrected field to identify whether this is a regular or corrected report.

Use this report ID to get specific report details.

Download the PDF file using the file download link from the response.

Deliver the form to your merchant through your platform.

TAXES.REPORT.GENERATED (Regular report)
TAXES.REPORT.GENERATED (Corrected report)

1{
2     "id": "WH-7KS583797C273740K-4XG92085G17839137",
3     "event_version": "2.0",
4     "create_time": "2025-12-08T07:13:33.428Z",
5     "resource_type": "TAX-REPORT",
6     "resource_version": "2.0",
7     "event_type": "TAXES.REPORTS.GENERATED",
8     "summary": "TAX REPORT IS GENERATED.",
9     "resource": {
10          "account_id": "TMLTUT7USJQGY",
11          "create_time": "2025-12-08T07:13:28.661Z",
12          "files_info": {
13               "files": [
14                    {
15                         "sequence": 1,
16                         "name": "EXT-1764908915_1099K_2024_5328477226563214769_1765177982323.pdf",
17                         "links": [
18                              {
19                                   "href": "https://api.sandbox.paypal.com/v2/taxes/reports/11F0-D405-5519E21F-88AE-562A9B01F358?files_info_page=1&files_info_page_size=1",
20                                   "rel": "self",
21                                   "method": "GET",
22                                   "encType": "application/json"
23                              },
24                              {
25                                   "href": "https://api.sandbox.paypal.com/v2/content/documents/CMP-044-11f0-d405-58f79170-873f-e0533e70ab97/files/1/download",
26                                   "rel": "download",
27                                   "method": "GET",
28                                   "encType": "application/json"
29                              }
30                         ]
31                    }
32               ],
33               "total_items": 1,
34               "links": [
35                    {
36                         "href": "https://api.sandbox.paypal.com/v2/taxes/reports/11F0-D405-5519E21F-88AE-562A9B01F358?files_info_page=1&files_info_page_size=10&total_required=true",
37                         "rel": "self",
38                         "method": "GET",
39                         "encType": "application/json"
40                    },
41                    {
42                         "href": "https://api.sandbox.paypal.com/v2/taxes/reports/11F0-D405-5519E21F-88AE-562A9B01F358?files_info_page=1&files_info_page_size=10&total_required=true",
43                         "rel": "first",
44                         "method": "GET",
45                         "encType": "application/json"
46                    },
47                    {
48                         "href": "https://api.sandbox.paypal.com/v2/taxes/reports/11F0-D405-5519E21F-88AE-562A9B01F358?files_info_page=1&files_info_page_size=10&total_required=true",
49                         "rel": "prev",
50                         "method": "GET",
51                         "encType": "application/json"
52                    },
53                    {
54                         "href": "https://api.sandbox.paypal.com/v2/taxes/reports/11F0-D405-5519E21F-88AE-562A9B01F358?files_info_page=1&files_info_page_size=10&total_required=true",
55                         "rel": "next",
56                         "method": "GET",
57                         "encType": "application/json"
58                    },
59                    {
60                         "href": "https://api.sandbox.paypal.com/v2/taxes/reports/11F0-D405-5519E21F-88AE-562A9B01F358?files_info_page=1&files_info_page_size=10&total_required=true",
61                         "rel": "last",
62                         "method": "GET",
63                         "encType": "application/json"
64                    }
65               ]
66          },
67          "total_files": 1,
68          "archive_time": "2035-12-06T07:13:28.661Z",
69          "links": [
70               {
71                    "href": "https://api.sandbox.paypal.com/v2/taxes/reports/11F0-D405-5519E21F-88AE-562A9B01F358",
72                    "rel": "self",
73                    "method": "GET",
74                    "encType": "application/json"
75               },
76               {
77                    "href": "https://api.sandbox.paypal.com/v2/taxes/reports/11F0-D405-5519E21F-88AE-562A9B01F358/corrections",
78                    "rel": "correction",
79                    "method": "POST",
80                    "encType": "application/json"
81               }
82          ],
83          "id": "11F0-D405-5519E21F-88AE-562A9B01F358",
84          "report_type": "1099-K",
85          "tax_year": 2024,
86          "corrected": false,
87          "status": "GENERATION_COMPLETED"
88     },
89     "links": [
90          {
91               "href": "https://api.sandbox.paypal.com/v1/notifications/webhooks-events/WH-7KS583797C273740K-4XG92085G17839137",
92               "rel": "self",
93               "method": "GET"
94          },
95          {
96               "href": "https://api.sandbox.paypal.com/v1/notifications/webhooks-events/WH-7KS583797C273740K-4XG92085G17839137/resend",
97               "rel": "resend",
98               "method": "POST"
99          }
100     ]
101}

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 corrected: true when you process corrections. The original report remains accessible.

You can access reports for multiple tax years through a single API endpoint.