openapi: 3.0.3
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_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.
properties:
name:
type: string
enum:
- RESOURCE_NOT_FOUND
message:
type: string
enum:
- The specified resource does not exist.
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'
error_409:
type: object
title: Resource Conflict Error
description: The server has detected a conflict while processing this request.
properties:
name:
type: string
enum:
- RESOURCE_CONFLICT
message:
type: string
enum:
- The server has detected a conflict while processing this request.
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'
transactions_list:
title: List Transactions
description: The list transactions for a subscription request details.
type: object
properties:
transactions:
type: array
description: An array of transactions.
minItems: 0
maxItems: 32767
items:
$ref: '#/components/schemas/transaction'
total_items:
type: integer
description: The total number of items.
minimum: 0
maximum: 500000000
total_pages:
type: integer
description: The total number of pages.
minimum: 0
maximum: 100000000
links:
type: array
description: An array of request-related [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links).
readOnly: true
minItems: 1
maxItems: 10
items:
readOnly: true
$ref: '#/components/schemas/link_description'
'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.
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
error_403:
type: object
title: Not Authorized Error
description: 'The client is not authorized to access this resource, although it may have valid credentials. '
properties:
name:
type: string
enum:
- NOT_AUTHORIZED
message:
type: string
enum:
- Authorization failed due to insufficient permissions.
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'
error_422:
type: object
title: Unprocessable Entity Error
description: The requested action cannot be performed and may require interaction with APIs or processes outside of the current request. This is distinct from a 500 response in that there are no systemic problems limiting the API from performing the request.
properties:
name:
type: string
enum:
- UNPROCESSABLE_ENTITY
message:
type: string
enum:
- The requested action could not be performed, semantically incorrect, or failed business validation.
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'
capture_status:
type: object
title: Capture Status
description: The status of a captured payment.
properties:
status:
description: The status of the captured payment.
type: string
readOnly: true
enum:
- COMPLETED
- DECLINED
- PARTIALLY_REFUNDED
- PENDING
- REFUNDED
status_details:
description: The details of the captured payment status.
readOnly: true
$ref: '#/components/schemas/capture_status_details'
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
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
error_link_description:
title: Link Description
description: The request-related [HATEOAS link](/api/rest/responses/#hateoas-links) information.
type: object
required:
- href
- rel
properties:
href:
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.
type: string
minLength: 0
maxLength: 20000
pattern: ^.*$
rel:
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).
type: string
minLength: 0
maxLength: 100
pattern: ^.*$
method:
description: The HTTP method required to make the related call.
type: string
minLength: 3
maxLength: 6
pattern: ^[A-Z]*$
enum:
- GET
- POST
- PUT
- DELETE
- PATCH
transaction:
title: Transaction Details
description: The transaction details.
type: object
allOf:
- $ref: '#/components/schemas/capture_status'
- properties:
id:
type: string
description: The PayPal-generated transaction ID.
minLength: 3
maxLength: 50
readOnly: true
amount_with_breakdown:
$ref: '#/components/schemas/amount_with_breakdown'
payer_name:
description: The name of the customer.
readOnly: true
$ref: '#/components/schemas/name'
payer_email:
description: The email ID of the customer.
readOnly: true
$ref: '#/components/schemas/email_address'
time:
description: The date and time when the transaction was processed, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).
readOnly: true
$ref: '#/components/schemas/date_time'
required:
- id
- amount_with_breakdown
- time
error_default:
description: The default error response.
oneOf:
- $ref: '#/components/schemas/error_400'
- $ref: '#/components/schemas/error_401'
- $ref: '#/components/schemas/error_403'
- $ref: '#/components/schemas/error_404'
- $ref: '#/components/schemas/error_409'
- $ref: '#/components/schemas/error_415'
- $ref: '#/components/schemas/error_422'
- $ref: '#/components/schemas/error_500'
- $ref: '#/components/schemas/error_503'
error_location:
type: string
description: The location of the field that caused the error. Value is `body`, `path`, or `query`.
enum:
- body
- path
- query
default: body
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
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
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
'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_503:
type: object
title: Service Unavailable Error
description: The server is temporarily unable to handle the request, for example, because of planned maintenance or downtime.
properties:
name:
type: string
enum:
- SERVICE_UNAVAILABLE
message:
type: string
enum:
- Service Unavailable.
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: SERVICE_UNAVAILABLE
message: Service Unavailable.
debug_id: 90957fca61718
information_link: https://developer.paypal.com/docs/api/orders/v2/#error-SERVICE_UNAVAILABLE
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'
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
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'
'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.
error_415:
type: object
title: Unsupported Media Type Error
description: The server does not support the request payload's media type.
properties:
name:
type: string
enum:
- UNSUPPORTED_MEDIA_TYPE
message:
type: string
enum:
- The server does not support the request payload's media type.
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'
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
email_address:
type: string
description: The internationalized email address.<blockquote><strong>Note:</strong> Up to 64 characters are allowed before and 255 characters are allowed after the <code>@</code> sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted <code>@</code> sign exists.</blockquote>
format: ppaas_common_email_address_v2
minLength: 3
maxLength: 254
pattern: ^.+@[^"\-].+$
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})$
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.
incentive_detail:
type: object
title: Incentive Details
description: The incentive details.
properties:
incentive_type:
type: string
description: The type of incentive, such as a special offer or coupon.
minLength: 1
maxLength: 500
pattern: ^[a-zA-Z0-9_'\-., ":;\!?]*$
incentive_code:
type: string
description: The code that identifies an incentive, such as a coupon.
minLength: 1
maxLength: 200
pattern: ^[a-zA-Z0-9_'\-., ":;\!?]*$
incentive_amount:
$ref: '#/components/schemas/money'
description: The incentive amount.
incentive_program_code:
type: string
description: The incentive program code that identifies a merchant loyalty or incentive program.
minLength: 1
maxLength: 100
pattern: ^[a-zA-Z0-9_'\-., ":;\!?]*$
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>
# --- 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