Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Paypal Subscriptions Authorizations Transactions API
description: You can use billing plans and subscriptions to create subscriptions that process recurring PayPal payments for physical or digital goods, or services. A plan includes pricing and billing cycle information that defines the amount and frequency of charge for a subscription. You can also define a fixed plan, such as a $5 basic plan or a volume- or graduated-based plan with pricing tiers based on the quantity purchased. For more information, see <a href="/docs/subscriptions/">Subscriptions Overview</a>.
version: '1.6'
contact: {}
servers:
- url: https://api-m.sandbox.paypal.com
description: PayPal Sandbox Environment
- url: https://api-m.paypal.com
description: PayPal Live Environment
tags:
- name: Transactions
paths:
/v1/billing/subscriptions/{id}/transactions:
get:
summary: List transactions for subscription
description: Lists transactions for a subscription.
operationId: subscriptions.transactions
responses:
'200':
description: A successful request returns the HTTP `200 OK` status code and a JSON response body that shows subscription details.
content:
application/json:
schema:
$ref: '#/components/schemas/transactions_list'
'400':
description: Bad Request. Request is not well-formed, syntactically incorrect, or violates schema.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/error_400'
- $ref: '#/components/schemas/subscriptions.transactions-400'
'401':
description: Authentication failed due to missing authorization header, or invalid authentication credentials.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/error_401'
- $ref: '#/components/schemas/401'
'403':
description: Authorization failed due to insufficient permissions.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/error_403'
- $ref: '#/components/schemas/403'
'404':
description: The specified resource does not exist.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/error_404'
- $ref: '#/components/schemas/404'
'500':
description: An internal server error has occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/error_500'
default:
$ref: '#/components/responses/default'
parameters:
- $ref: '#/components/parameters/id'
- $ref: '#/components/parameters/start_time'
- $ref: '#/components/parameters/end_time'
security:
- Oauth2:
- https://uri.paypal.com/services/subscriptions
tags:
- Transactions
/v1/reporting/transactions:
get:
summary: Paypal List transactions
description: Lists transactions. Specify one or more query parameters to filter the transaction that appear in the response.<blockquote><strong>Notes:</strong> <ul><li>If you specify one or more optional query parameters, the <code>ending_balance</code> response field is empty.</li><li>It takes a maximum of three hours for executed transactions to appear in the list transactions call.</li><li>This call lists transaction for the previous three years.</li></ul></blockquote>
operationId: search.get
responses:
'200':
description: A successful request returns the HTTP `200 OK` status code and a JSON response body that lists transactions .
content:
application/json:
schema:
$ref: '#/components/schemas/search_response'
default:
$ref: '#/components/responses/default'
parameters:
- $ref: '#/components/parameters/transaction_id'
- $ref: '#/components/parameters/transaction_type'
- $ref: '#/components/parameters/transaction_status'
- $ref: '#/components/parameters/transaction_amount'
- $ref: '#/components/parameters/transaction_currency'
- $ref: '#/components/parameters/start_date'
- $ref: '#/components/parameters/end_date'
- $ref: '#/components/parameters/payment_instrument_type'
- $ref: '#/components/parameters/store_id'
- $ref: '#/components/parameters/terminal_id'
- $ref: '#/components/parameters/fields'
- $ref: '#/components/parameters/balance_affecting_records_only'
- $ref: '#/components/parameters/page_size'
- $ref: '#/components/parameters/page'
security:
- Oauth2:
- https://uri.paypal.com/services/reporting/search/read
tags:
- Transactions
components:
schemas:
error_500:
type: object
title: Internal Server Error
description: This is either a system or application error, and generally indicates that although the client appeared to provide a correct request, something unexpected has gone wrong on the server.
properties:
name:
type: string
enum:
- INTERNAL_SERVER_ERROR
message:
type: string
enum:
- An internal server error occurred.
debug_id:
type: string
description: The PayPal internal ID. Used for correlation purposes.
links:
description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
type: array
minItems: 0
maxItems: 10000
items:
$ref: '#/components/schemas/error_link_description'
example:
name: INTERNAL_SERVER_ERROR
message: An internal server error occurred.
debug_id: 90957fca61718
links:
- href: https://developer.paypal.com/api/orders/v2/#error-INTERNAL_SERVER_ERROR
rel: information_link
link_description:
type: object
title: Link Description
description: The request-related [HATEOAS link](/docs/api/reference/api-responses/#hateoas-links) information.
required:
- href
- rel
properties:
href:
type: string
description: The complete target URL. To make the related call, combine the method with this [URI Template-formatted](https://tools.ietf.org/html/rfc6570) link. For pre-processing, include the `$`, `(`, and `)` characters. The `href` is the key HATEOAS component that links a completed call with a subsequent call.
rel:
type: string
description: The [link relation type](https://tools.ietf.org/html/rfc5988#section-4), which serves as an ID for a link that unambiguously describes the semantics of the link. See [Link Relations](https://www.iana.org/assignments/link-relations/link-relations.xhtml).
method:
type: string
description: The HTTP method required to make the related call.
enum:
- GET
- POST
- PUT
- DELETE
- HEAD
- CONNECT
- OPTIONS
- PATCH
'404':
properties:
details:
type: array
items:
anyOf:
- title: INVALID_RESOURCE_ID
properties:
issue:
type: string
enum:
- INVALID_RESOURCE_ID
description:
type: string
enum:
- Specified resource ID does not exist. Please check the resource ID and try again.
transaction_detail:
type: object
title: Transaction Details
description: The transaction details.
properties:
transaction_info:
$ref: '#/components/schemas/transaction_info'
description: The transaction information.
payer_info:
$ref: '#/components/schemas/payer_info'
description: The payer information.
shipping_info:
$ref: '#/components/schemas/shipping_info'
description: The shipping information.
cart_info:
$ref: '#/components/schemas/cart_info'
description: The cart information.
store_info:
$ref: '#/components/schemas/store_info'
description: The store information.
auction_info:
$ref: '#/components/schemas/auction_info'
description: The auction information.
incentive_info:
$ref: '#/components/schemas/incentive_info'
description: The incentive information.
date_time:
type: string
description: The date and time, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). Seconds are required while fractional seconds are optional.<blockquote><strong>Note:</strong> The regular expression provides guidance but does not reject all invalid dates.</blockquote>
format: ppaas_date_time_v3
minLength: 20
maxLength: 64
pattern: ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])[T,t]([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)([.][0-9]+)?([Zz]|[+-][0-9]{2}:[0-9]{2})$
money:
type: object
title: Money
description: The currency and amount for a financial transaction, such as a balance or payment due.
properties:
currency_code:
$ref: '#/components/schemas/currency_code'
value:
type: string
description: The value, which might be:<ul><li>An integer for currencies like `JPY` that are not typically fractional.</li><li>A decimal fraction for currencies like `TND` that are subdivided into thousandths.</li></ul>For the required number of decimal places for a currency code, see [Currency Codes](/docs/integration/direct/rest/currency-codes/).
maxLength: 32
pattern: ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$
required:
- currency_code
- value
subscriptions.transactions-400:
properties:
details:
type: array
items:
anyOf:
- title: INVALID_PARAMETER_SYNTAX
properties:
issue:
type: string
enum:
- INVALID_PARAMETER_SYNTAX
description:
type: string
enum:
- The value of a field does not conform to the expected format.
- title: INVALID_PARAMETER_VALUE
properties:
issue:
type: string
enum:
- INVALID_PARAMETER_VALUE
description:
type: string
enum:
- The value of a field is invalid.
- title: MISSING_REQUIRED_PARAMETER
properties:
issue:
type: string
enum:
- MISSING_REQUIRED_PARAMETER
description:
type: string
enum:
- A required field is missing.
currency_code:
description: The [three-character ISO-4217 currency code](/docs/integration/direct/rest/currency-codes/) that identifies the currency.
type: string
format: ppaas_common_currency_code_v2
minLength: 3
maxLength: 3
amount_with_breakdown:
type: object
title: Amount with Breakdown
description: The breakdown details for the amount. Includes the gross, tax, fee, and shipping amounts.
properties:
gross_amount:
description: The amount for this transaction.
readOnly: true
$ref: '#/components/schemas/money'
total_item_amount:
description: The item total for the transaction.
readOnly: true
$ref: '#/components/schemas/money'
fee_amount:
description: The fee details for the transaction.
readOnly: true
$ref: '#/components/schemas/money'
shipping_amount:
description: The shipping amount for the transaction.
readOnly: true
$ref: '#/components/schemas/money'
tax_amount:
description: The tax amount for the transaction.
readOnly: true
$ref: '#/components/schemas/money'
net_amount:
description: The net amount that the payee receives for this transaction in their PayPal account. The net amount is computed as <code>gross_amount</code> minus the <code>paypal_fee</code>.
readOnly: true
$ref: '#/components/schemas/money'
required:
- gross_amount
error_400:
type: object
title: Bad Request Error
description: Request is not well-formed, syntactically incorrect, or violates schema.
properties:
name:
type: string
enum:
- INVALID_REQUEST
message:
type: string
enum:
- Request is not well-formed, syntactically incorrect, or violates schema.
details:
type: array
items:
$ref: '#/components/schemas/error_details'
debug_id:
type: string
description: The PayPal internal ID. Used for correlation purposes.
links:
description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
type: array
minItems: 0
maxItems: 10000
items:
$ref: '#/components/schemas/error_link_description'
shipping_info:
type: object
title: Shipping Information
description: The shipping information.
properties:
name:
type: string
description: The recipient's name.
minLength: 1
maxLength: 500
pattern: ^[a-zA-Z0-9_'\-., ":;\!?]*$
method:
type: string
description: The shipping method that is associated with this order.
minLength: 1
maxLength: 500
pattern: ^[a-zA-Z0-9_'\-., ":;\!?]*$
address:
$ref: '#/components/schemas/address'
description: The shipping address that is associated with this order.
secondary_shipping_address:
$ref: '#/components/schemas/address'
description: The secondary shipping address that is associated with this order.
error_details:
title: Error Details
type: object
description: The error details. Required for client-side `4XX` errors.
properties:
field:
type: string
description: The field that caused the error. If this field is in the body, set this value to the field's JSON pointer value. Required for client-side errors.
value:
type: string
description: The value of the field that caused the error.
location:
$ref: '#/components/schemas/error_location'
issue:
type: string
description: The unique, fine-grained application-level error code.
description:
type: string
description: The human-readable description for an issue. The description can change over the lifetime of an API, so clients must not depend on this value.
required:
- issue
'403':
properties:
details:
type: array
items:
anyOf:
- title: PERMISSION_DENIED
properties:
issue:
type: string
enum:
- PERMISSION_DENIED
description:
type: string
enum:
- You do not have permission to access or perform operations on this resource.
'401':
properties:
details:
type: array
items:
anyOf:
- title: INVALID_ACCOUNT_STATUS
properties:
issue:
type: string
enum:
- INVALID_ACCOUNT_STATUS
description:
type: string
enum:
- Account validations failed for the user.
error_401:
type: object
title: Unauthorized Error
description: Authentication failed due to missing Authorization header, or invalid authentication credentials.
properties:
name:
type: string
enum:
- AUTHENTICATION_FAILURE
message:
type: string
enum:
- Authentication failed due to missing authorization header, or invalid authentication credentials.
details:
type: array
items:
$ref: '#/components/schemas/error_details'
debug_id:
type: string
description: The PayPal internal ID. Used for correlation purposes.
links:
description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
type: array
minItems: 0
maxItems: 10000
items:
$ref: '#/components/schemas/error_link_description'
auction_info:
type: object
title: Auction Information
description: The auction information.
properties:
auction_site:
type: string
description: The name of the auction site.
minLength: 1
maxLength: 200
pattern: ^[a-zA-Z0-9_'\-., ":;\!?]*$
auction_item_site:
type: string
description: The auction site URL.
minLength: 1
maxLength: 4000
pattern: ^[a-zA-Z0-9_'\-., ":;\!?]*$
auction_buyer_id:
type: string
description: The ID of the buyer who makes the purchase in the auction. This ID might be different from the payer ID provided for the payment.
minLength: 1
maxLength: 500
pattern: ^[a-zA-Z0-9_'\-., ":;\!?]*$
auction_closing_date:
description: The date and time when the auction closes, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).
$ref: '#/components/schemas/date_time'
phone:
type: object
title: Phone
description: The phone number, in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en).
properties:
country_code:
type: string
description: The country calling code (CC), in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en). The combined length of the CC and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN).
minLength: 1
maxLength: 3
pattern: ^[0-9]{1,3}?$
national_number:
type: string
description: The national number, in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en). The combined length of the country calling code (CC) and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN).
minLength: 1
maxLength: 14
pattern: ^[0-9]{1,14}?$
extension_number:
type: string
description: The extension number.
minLength: 1
maxLength: 15
pattern: ^[0-9]{1,15}?$
required:
- country_code
- national_number
name:
type: object
title: Name
description: The name of the party.
properties:
prefix:
type: string
description: The prefix, or title, to the party's name.
maxLength: 140
given_name:
type: string
description: When the party is a person, the party's given, or first, name.
maxLength: 140
surname:
type: string
description: When the party is a person, the party's surname or family name. Also known as the last name. Required when the party is a person. Use also to store multiple surnames including the matronymic, or mother's, surname.
maxLength: 140
middle_name:
type: string
description: When the party is a person, the party's middle name. Use also to store multiple middle names including the patronymic, or father's, middle name.
maxLength: 140
suffix:
type: string
description: The suffix for the party's name.
maxLength: 140
alternate_full_name:
type: string
description: DEPRECATED. The party's alternate name. Can be a business name, nickname, or any other name that cannot be split into first, last name. Required when the party is a business.
maxLength: 300
full_name:
type: string
description: When the party is a person, the party's full name.
maxLength: 300
capture_status_details:
title: Capture Status Details
description: The details of the captured payment status.
type: object
properties:
reason:
description: The reason why the captured payment status is `PENDING` or `DENIED`.
type: string
enum:
- BUYER_COMPLAINT
- CHARGEBACK
- ECHECK
- INTERNATIONAL_WITHDRAWAL
- OTHER
- PENDING_REVIEW
- RECEIVING_PREFERENCE_MANDATES_MANUAL_ACTION
- REFUNDED
- TRANSACTION_APPROVED_AWAITING_FUNDING
- UNILATERAL
- VERIFICATION_REQUIRED
transaction_info:
type: object
title: Transaction Information
description: The transaction information.
properties:
paypal_account_id:
type: string
description: The ID of the PayPal account of the counterparty.
minLength: 1
maxLength: 24
pattern: ^[a-zA-Z0-9]*$
transaction_id:
type: string
description: The PayPal-generated transaction ID.
readOnly: true
minLength: 1
maxLength: 24
pattern: ^[a-zA-Z0-9]*$
paypal_reference_id:
type: string
description: The PayPal-generated base ID. PayPal exclusive. Cannot be altered. Defined as a related, pre-existing transaction or event.
minLength: 1
maxLength: 24
pattern: ^[a-zA-Z0-9]*$
paypal_reference_id_type:
type: string
description: The PayPal reference ID type.
minLength: 3
maxLength: 3
pattern: ^[a-zA-Z0-9]*$
enum:
- ODR
- TXN
- SUB
- PAP
transaction_event_code:
type: string
minLength: 1
maxLength: 5
pattern: ^[a-zA-Z0-9]*$
description: A five-digit transaction event code that classifies the transaction type based on money movement and debit or credit. For example, <code>T0001</code>. See [Transaction event codes](/docs/integration/direct/transaction-search/transaction-event-codes/).
transaction_initiation_date:
description: The date and time when work on a transaction began in the PayPal system, as expressed in the time zone of the account on this side of the payment. Specify the value in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).
$ref: '#/components/schemas/date_time'
transaction_updated_date:
description: The date and time when the transaction was last changed, as expressed in the time zone of the account on this side of the payment. Specify the value in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).
$ref: '#/components/schemas/date_time'
transaction_amount:
$ref: '#/components/schemas/money'
description: The all-inclusive gross transaction amount that was transferred between the sender and receiver through PayPal.
fee_amount:
$ref: '#/components/schemas/money'
description: The PayPal fee amount. All transaction fees are included in this amount, which is the record of fee associated with the transaction.<blockquote><strong>Note:</strong> This field contains a value only when a transaction fee is applied and processed for this transaction.</blockquote>
discount_amount:
$ref: '#/components/schemas/money'
description: The reduction in price offered for goods or services purchased.<blockquote><strong>Note:</strong> This discount is for a price reduction that is offered for other than that at a individual item level.</blockquote>
insurance_amount:
$ref: '#/components/schemas/money'
description: An insurance charge. Guarantees the quality or delivery of a product.
sales_tax_amount:
$ref: '#/components/schemas/money'
description: The PayPal- or merchant-reported sales tax amount for the transaction.
shipping_amount:
$ref: '#/components/schemas/money'
description: The PayPal- or merchant-reported shipping amount for the transaction.
shipping_discount_amount:
$ref: '#/components/schemas/money'
description: The discount on the shipping amount.
shipping_tax_amount:
$ref: '#/components/schemas/money'
description: The tax on the shipping service.
other_amount:
$ref: '#/components/schemas/money'
description: The special amount that is added to the transaction.
tip_amount:
$ref: '#/components/schemas/money'
description: The tip.
transaction_status:
type: string
description: A code that indicates the transaction status. Value is:<table><thead><tr><th>Status code</th><th>Description</th></tr></thead><tbody><tr><td><code>D</code></td><td>PayPal or merchant rules denied the transaction.</td></tr><tr><td><code>P</code></td><td>The transaction is pending. The transaction was created but waits for another payment process to complete, such as an ACH transaction, before the status changes to <code>S</code>.</td></tr><tr><td><code>S</code></td><td>The transaction successfully completed without a denial and after any pending statuses.</td></tr><tr><td><code>V</code></td><td>A successful transaction was fully reversed and funds were refunded to the original sender.</td></tr></tbody></table>
minLength: 1
maxLength: 1
pattern: ^[a-zA-Z0-9]*$
transaction_subject:
type: string
description: The subject of payment. The payer passes this value to the payee. The payer controls this data through the interface through which he or she sends the data.
minLength: 1
maxLength: 256
pattern: ^[a-zA-Z0-9_'\-., ":;\!?]*$
transaction_note:
type: string
description: A special note that the payer passes to the payee. Might contain special customer requests, such as shipping instructions.
minLength: 1
maxLength: 4000
pattern: ^[a-zA-Z0-9_'\-., ":;\!?]*$
payment_tracking_id:
type: string
description: The payment tracking ID, which is a unique ID that partners specify to either get information about a payment or request a refund.
minLength: 1
maxLength: 127
pattern: ^[a-zA-Z0-9]*$
bank_reference_id:
type: string
description: The bank reference ID. The bank provides this value for an ACH transaction.
minLength: 1
maxLength: 127
pattern: ^[a-zA-Z0-9]*$
ending_balance:
$ref: '#/components/schemas/money'
description: The ending balance.<blockquote><strong>Note:</strong> If you specify one or more optional query parameters, the <code>ending_balance</code> response field is empty.</blockquote>
available_balance:
$ref: '#/components/schemas/money'
description: The available amount of transaction currency during the completion of this transaction.
invoice_id:
type: string
description: The invoice ID that is sent by the merchant with the transaction.<blockquote><strong>Note:</strong> If an invoice ID was sent with the capture request, the value is reported. Otherwise, the invoice ID of the authorizing transaction is reported.</blockquote>
minLength: 1
maxLength: 127
pattern: ^[a-zA-Z0-9_'\-., ":;\!?]*$
custom_field:
type: string
description: The merchant-provided custom text.<blockquote><strong>Note:</strong> Usually, this field includes the unique ID for payments made with MassPay type transaction.</blockquote>
minLength: 1
maxLength: 127
pattern: ^[a-zA-Z0-9_'\-., ":;\!?]*$
protection_eligibility:
type: string
description: Indicates whether the transaction is eligible for protection. Value is:<ul><li><code>01</code>. Eligible.</li><li><code>02</code>. Not eligible</li><li><code>03</code>. Partially eligible.</li></ul>
minLength: 1
maxLength: 2
pattern: ^[a-zA-Z0-9]*$
credit_term:
type: string
description: The credit term. The time span covered by the installment payments as expressed in the term length plus the length time unit code.
minLength: 1
maxLength: 25
pattern: ^[a-zA-Z0-9.]*$
credit_transactional_fee:
$ref: '#/components/schemas/money'
description: The overall amount of the credit transaction fee.
credit_promotional_fee:
$ref: '#/components/schemas/money'
description: The overall amount of the credit promotional fee.
annual_percentage_rate:
$ref: '#/components/schemas/percentage'
description: The annual percentage rate (APR). Determines the amount of interest a consumer pays to finance a purchase at a merchant.
payment_method_type:
type: string
minLength: 1
maxLength: 20
pattern: ^[a-zA-Z0-9-]*$
description: The payment method that was used for a transaction. Value is <code>PUI</code>, <code>installment</code>, or <code>mEFT</code>.<blockquote><strong>Note:</strong> Appears only for pay upon invoice (PUI), installment, and mEFT transactions. Merchants and partners in the EMEA region can use this attribute to note transactions that attract turn-over tax.</blockquote>
instrument_type:
type: string
minLength: 1
maxLength: 64
description: A high-level classification of the type of financial instrument that was used to fund a payment. The pattern is not provided because the value is defined by an external party. E.g. PAYPAL, CREDIT_CARD, DEBIT_CARD, APPLE_PAY, BANK , VENMO ,Pay Upon Invoice, Pay Later or <a href="https://developer.paypal.com/docs/checkout/integration-features/alternative-payment-methods/" title="Link to available APM list">Alternative Payment Methods (APM)</a>.
instrument_sub_type:
type: string
minLength: 1
maxLength: 64
description: A finer-grained classification of the financial instrument that was used to fund a payment. For example, `Visa card` or a `Mastercard` for a credit card, BANKCARD ,DISCOVER etc. The pattern is not provided because the value is defined by an external party.
country_code:
type: string
description: The [two-character ISO 3166-1 code](/docs/integration/direct/rest/country-codes/) that identifies the country or region.<blockquote><strong>Note:</strong> The country code for Great Britain is <code>GB</code> and not <code>UK</code> as used in the top-level domain names for that country. Use the `C2` country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.</blockquote>
format: ppaas_common_country_code_v2
maxLength: 2
minLength: 2
pattern: ^([A-Z]{2}|C2)$
error_404:
type: object
title: Not found Error
description: The server has not found anything matching the request URI. This either means that the URI is incorrect or the resource is not available.
# --- truncated at 32 KB (65 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/paypal/refs/heads/main/openapi/paypal-transactions-api-openapi.yml