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.

Sample request

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

Sample request

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 <ACCESS-TOKEN>' \
-H 'X-PAYPAL-SECURITY-CONTEXT: <SECURITY-CONTEXT>'

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.

Sample request

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 <ACCESS-TOKEN>' \
-H 'X-PAYPAL-SECURITY-CONTEXT: <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).

TAXES.REPORTS.GENERATED (Regular report)

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

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.