openapi: 3.0.3
info:
title: Paypal Subscriptions Authorizations Orders 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: Orders
description: Use the `/orders` resource to create, update, retrieve, authorize, capture and track orders.
paths:
/v2/checkout/orders:
post:
summary: Paypal Create order
description: Creates an order. Merchants and partners can add Level 2 and 3 data to payments to reduce risk and payment processing costs. For more information about processing payments, see <a href="https://developer.paypal.com/docs/checkout/advanced/processing/">checkout</a> or <a href="https://developer.paypal.com/docs/multiparty/checkout/advanced/processing/">multiparty checkout</a>.<blockquote><strong>Note:</strong> For error handling and troubleshooting, see <a href="/api/rest/reference/orders/v2/errors/#create-order">Orders v2 errors</a>.</blockquote>
operationId: orders.create
responses:
'200':
description: A successful response to an idempotent request returns the HTTP `200 OK` status code with a JSON response body that shows order details.
content:
application/json:
schema:
$ref: '#/components/schemas/order'
'201':
description: 'A successful request returns the HTTP `201 Created` status code and a JSON response body that includes by default a minimal response with the ID, status, and HATEOAS links. If you require the complete order resource representation, you must pass the <a href="/docs/api/orders/v2/#orders-create-header-parameters"><code>Prefer: return=representation</code> request header</a>. This header value is not the default.'
content:
application/json:
schema:
$ref: '#/components/schemas/order'
examples:
orders_request_create:
value:
intent: CAPTURE
purchase_units:
- reference_id: d9f80740-38f0-11e8-b467-0ed5f89f718b
amount:
currency_code: USD
value: '100.00'
'400':
description: Request is not well-formed, syntactically incorrect, or violates schema.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/error_400'
- $ref: '#/components/schemas/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'
'422':
description: The requested action could not be performed, semantically incorrect, or failed business validation.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/error_422'
- $ref: '#/components/schemas/422'
default:
$ref: '#/components/responses/default'
parameters:
- $ref: '#/components/parameters/paypal_request_id'
- $ref: '#/components/parameters/paypal_partner_attribution_id'
- $ref: '#/components/parameters/paypal_client_metadata_id'
- $ref: '#/components/parameters/prefer'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/order_request'
examples:
order_request:
value:
intent: CAPTURE
purchase_units:
- reference_id: d9f80740-38f0-11e8-b467-0ed5f89f718b
amount:
currency_code: USD
value: '100.00'
payment_source:
paypal:
experience_context:
payment_method_preference: IMMEDIATE_PAYMENT_REQUIRED
payment_method_selected: PAYPAL
brand_name: EXAMPLE INC
locale: en-US
landing_page: LOGIN
user_action: PAY_NOW
return_url: https://example.com/returnUrl
cancel_url: https://example.com/cancelUrl
required: true
security:
- Oauth2:
- https://uri.paypal.com/services/payments/payment
- https://uri.paypal.com/services/payments/orders/client-side-integration
tags:
- Orders
/v2/checkout/orders/{id}:
get:
summary: Paypal Show order details
description: Shows details for an order, by ID.<blockquote><strong>Note:</strong> For error handling and troubleshooting, see <a href="/api/rest/reference/orders/v2/errors/#get-order">Orders v2 errors</a>.</blockquote>
operationId: orders.get
responses:
'200':
description: A successful request returns the HTTP `200 OK` status code and a JSON response body that shows order details.
content:
application/json:
schema:
$ref: '#/components/schemas/order'
'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'
'404':
description: The specified resource does not exist.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/error_404'
- $ref: '#/components/schemas/404'
default:
$ref: '#/components/responses/default'
parameters:
- $ref: '#/components/parameters/id'
- $ref: '#/components/parameters/fields'
security:
- Oauth2:
- https://uri.paypal.com/services/payments/payment
- https://uri.paypal.com/services/payments/orders/client-side-integration
tags:
- Orders
patch:
summary: Paypal Update order
description: 'Updates an order with a `CREATED` or `APPROVED` status. You cannot update an order with the `COMPLETED` status.<br/><br/>To make an update, you must provide a `reference_id`. If you omit this value with an order that contains only one purchase unit, PayPal sets the value to `default` which enables you to use the path: <code>\"/purchase_units/@reference_id==''default''/{attribute-or-object}\"</code>. Merchants and partners can add Level 2 and 3 data to payments to reduce risk and payment processing costs. For more information about processing payments, see <a href="https://developer.paypal.com/docs/checkout/advanced/processing/">checkout</a> or <a href="https://developer.paypal.com/docs/multiparty/checkout/advanced/processing/">multiparty checkout</a>.<blockquote><strong>Note:</strong> For error handling and troubleshooting, see <a href=\"/api/rest/reference/orders/v2/errors/#patch-order\">Orders v2 errors</a>.</blockquote>Patchable attributes or objects:<br/><br/><table><thead><th>Attribute</th><th>Op</th><th>Notes</th></thead><tbody><tr><td><code>intent</code></td><td>replace</td><td></td></tr><tr><td><code>payer</code></td><td>replace, add</td><td>Using replace op for <code>payer</code> will replace the whole <code>payer</code> object with the value sent in request.</td></tr><tr><td><code>purchase_units</code></td><td>replace, add</td><td></td></tr><tr><td><code>purchase_units[].custom_id</code></td><td>replace, add, remove</td><td></td></tr><tr><td><code>purchase_units[].description</code></td><td>replace, add, remove</td><td></td></tr><tr><td><code>purchase_units[].payee.email</code></td><td>replace</td><td></td></tr><tr><td><code>purchase_units[].shipping.name</code></td><td>replace, add</td><td></td></tr><tr><td><code>purchase_units[].shipping.address</code></td><td>replace, add</td><td></td></tr><tr><td><code>purchase_units[].shipping.type</code></td><td>replace, add</td><td></td></tr><tr><td><code>purchase_units[].soft_descriptor</code></td><td>replace, remove</td><td></td></tr><tr><td><code>purchase_units[].amount</code></td><td>replace</td><td></td></tr><tr><td><code>purchase_units[].items</code></td><td>replace, add, remove</td><td></td></tr><tr><td><code>purchase_units[].invoice_id</code></td><td>replace, add, remove</td><td></td></tr><tr><td><code>purchase_units[].payment_instruction</code></td><td>replace</td><td></td></tr><tr><td><code>purchase_units[].payment_instruction.disbursement_mode</code></td><td>replace</td><td>By default, <code>disbursement_mode</code> is <code>INSTANT</code>.</td></tr><tr><td><code>purchase_units[].payment_instruction.platform_fees</code></td><td>replace, add, remove</td><td></td></tr><tr><td><code>purchase_units[].supplementary_data.airline</code></td><td>replace, add, remove</td><td></td></tr><tr><td><code>purchase_units[].supplementary_data.card</code></td><td>replace, add, remove</td><td></td></tr><tr><td><code>application_context.client_configuration</code></td><td>replace, add</td><td></td></tr></tbody></table>'
operationId: orders.patch
responses:
'204':
description: A successful request returns the HTTP `204 No Content` status code with an empty object in the JSON response body.
'400':
description: Request is not well-formed, syntactically incorrect, or violates schema.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/error_400'
- $ref: '#/components/schemas/orders.patch-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'
'404':
description: The specified resource does not exist.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/error_404'
- $ref: '#/components/schemas/404'
'422':
description: The requested action could not be performed, semantically incorrect, or failed business validation.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/error_422'
- $ref: '#/components/schemas/orders.patch-422'
default:
$ref: '#/components/responses/default'
parameters:
- $ref: '#/components/parameters/id'
requestBody:
$ref: '#/components/requestBodies/patch_request'
security:
- Oauth2:
- https://uri.paypal.com/services/payments/payment
- https://uri.paypal.com/services/payments/orders/client-side-integration
tags:
- Orders
/v2/checkout/orders/{id}/confirm-payment-source:
post:
summary: Paypal Confirm the Order
description: Payer confirms their intent to pay for the the Order with the given payment source.
operationId: orders.confirm
responses:
'200':
description: A successful request indicates that the payment source was added to the Order. A successful request returns the HTTP `200 OK` status code with a JSON response body that shows order details.
content:
application/json:
schema:
$ref: '#/components/schemas/order'
'400':
description: Request is not well-formed, syntactically incorrect, or violates schema.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/error_400'
- $ref: '#/components/schemas/orders.confirm-400'
'403':
description: Authorization failed due to insufficient permissions.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/error_403'
- $ref: '#/components/schemas/403'
'422':
description: The requested action could not be performed, semantically incorrect, or failed business validation.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/error_422'
- $ref: '#/components/schemas/orders.confirm-422'
'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/paypal_client_metadata_id'
- $ref: '#/components/parameters/id'
- $ref: '#/components/parameters/prefer'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/confirm_order_request'
examples:
confirm_order_request:
value:
payment_source:
paypal:
name:
given_name: John
surname: Doe
email_address: customer@example.com
experience_context:
payment_method_preference: IMMEDIATE_PAYMENT_REQUIRED
payment_method_selected: PAYPAL
brand_name: EXAMPLE INC
locale: en-US
landing_page: LOGIN
shipping_preference: SET_PROVIDED_ADDRESS
user_action: PAY_NOW
return_url: https://example.com/returnUrl
cancel_url: https://example.com/cancelUrl
security:
- Oauth2:
- https://uri.paypal.com/services/payments/payment
- https://uri.paypal.com/services/payments/initiatepayment
tags:
- Orders
/v2/checkout/orders/{id}/authorize:
post:
summary: Paypal Authorize payment for order
description: Authorizes payment for an order. To successfully authorize payment for an order, the buyer must first approve the order or a valid payment_source must be provided in the request. A buyer can approve the order upon being redirected to the rel:approve URL that was returned in the HATEOAS links in the create order response.<blockquote><strong>Note:</strong> For error handling and troubleshooting, see <a href="/api/rest/reference/orders/v2/errors/#authorize-order">Orders v2 errors</a>.</blockquote>
operationId: orders.authorize
responses:
'200':
description: A successful response to an idempotent request returns the HTTP `200 OK` status code with a JSON response body that shows authorized payment details.
content:
application/json:
schema:
$ref: '#/components/schemas/order_authorize_response'
'201':
description: 'A successful response to a non-idempotent request returns the HTTP `201 Created` status code with a JSON response body that shows authorized payment details. If a duplicate response is retried, returns the HTTP `200 OK` status code. By default, the response is minimal. If you need the complete resource representation, you must pass the <a href="/docs/api/orders/v2/#orders-authorize-header-parameters"><code>Prefer: return=representation</code> request header</a>.'
content:
application/json:
schema:
$ref: '#/components/schemas/order_authorize_response'
'400':
description: Request is not well-formed, syntactically incorrect, or violates schema.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/error_400'
- $ref: '#/components/schemas/orders.authorize-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: The authorized payment failed due to insufficient permissions.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/error_403'
- $ref: '#/components/schemas/orders.authorize-403'
'404':
description: The specified resource does not exist.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/error_404'
- $ref: '#/components/schemas/404'
'422':
description: The requested action could not be performed, semantically incorrect, or failed business validation.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/error_422'
- $ref: '#/components/schemas/orders.authorize-422'
'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/paypal_request_id'
- $ref: '#/components/parameters/prefer'
- $ref: '#/components/parameters/paypal_client_metadata_id'
- $ref: '#/components/parameters/id'
- $ref: '#/components/parameters/paypal_auth_assertion'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/order_authorize_request'
security:
- Oauth2:
- https://uri.paypal.com/services/payments/payment
- https://uri.paypal.com/services/payments/orders/client-side-integration
tags:
- Orders
/v2/checkout/orders/{id}/capture:
post:
summary: Paypal Capture payment for order
description: Captures payment for an order. To successfully capture payment for an order, the buyer must first approve the order or a valid payment_source must be provided in the request. A buyer can approve the order upon being redirected to the rel:approve URL that was returned in the HATEOAS links in the create order response.<blockquote><strong>Note:</strong> For error handling and troubleshooting, see <a href="/api/rest/reference/orders/v2/errors/#capture-order">Orders v2 errors</a>.</blockquote>
operationId: orders.capture
responses:
'200':
description: A successful response to an idempotent request returns the HTTP `200 OK` status code with a JSON response body that shows captured payment details.
content:
application/json:
schema:
$ref: '#/components/schemas/order'
'201':
description: 'A successful response to a non-idempotent request returns the HTTP `201 Created` status code with a JSON response body that shows captured payment details. If a duplicate response is retried, returns the HTTP `200 OK` status code. By default, the response is minimal. If you need the complete resource representation, pass the <a href="/docs/api/orders/v2/#orders-authorize-header-parameters"><code>Prefer: return=representation</code> request header</a>.'
content:
application/json:
schema:
$ref: '#/components/schemas/order'
'400':
description: Request is not well-formed, syntactically incorrect, or violates schema.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/error_400'
- $ref: '#/components/schemas/orders.capture-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: The authorized payment failed due to insufficient permissions.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/error_403'
- $ref: '#/components/schemas/orders.capture-403'
'404':
description: The specified resource does not exist.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/error_404'
- $ref: '#/components/schemas/404'
'422':
description: The requested action could not be performed, semantically incorrect, or failed business validation.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/error_422'
- $ref: '#/components/schemas/orders.capture-422'
'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/paypal_request_id'
- $ref: '#/components/parameters/prefer'
- $ref: '#/components/parameters/paypal_client_metadata_id'
- $ref: '#/components/parameters/id'
- $ref: '#/components/parameters/paypal_auth_assertion'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/order_capture_request'
security:
- Oauth2:
- https://uri.paypal.com/services/payments/payment
- https://uri.paypal.com/services/payments/orders/client-side-integration
tags:
- Orders
/v2/checkout/orders/{id}/track:
post:
summary: Paypal Add tracking information for an Order.
description: Adds tracking information for an Order.
operationId: orders.track.create
responses:
'200':
description: A successful response to an idempotent request returns the HTTP `200 OK` status code with a JSON response body that shows tracker details.
content:
application/json:
schema:
$ref: '#/components/schemas/order'
'201':
description: A successful response to a non-idempotent request returns the HTTP `201 Created` status code with a JSON response body that shows tracker details. If a duplicate response is retried, returns the HTTP `200 OK` status code.
content:
application/json:
schema:
$ref: '#/components/schemas/order'
'400':
description: Request is not well-formed, syntactically incorrect, or violates schema.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/error_400'
- $ref: '#/components/schemas/orders.track.create-400'
'403':
description: Authorization failed due to insufficient permissions.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/error_403'
- $ref: '#/components/schemas/orders.track.create-403'
'404':
description: The specified resource does not exist.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/error_404'
- $ref: '#/components/schemas/404'
'422':
description: The requested action could not be performed, semantically incorrect, or failed business validation.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/error_422'
- $ref: '#/components/schemas/orders.track.create-422'
'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/paypal_auth_assertion'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/order_tracker_request'
required: true
security:
- Oauth2:
- https://uri.paypal.com/services/payments/payment
tags:
- Orders
components:
schemas:
processing_instruction:
type: string
title: Processing Instruction
description: The instruction to process an order.
default: NO_INSTRUCTION
minLength: 1
maxLength: 36
pattern: ^[0-9A-Z_]+$
enum:
- ORDER_COMPLETE_ON_PAYMENT_APPROVAL
- NO_INSTRUCTION
tracker:
type: object
title: Order Tracker Response.
description: The tracking response on creation of tracker.
allOf:
- properties:
id:
type: string
description: The tracker id.
readOnly: true
status:
$ref: '#/components/schemas/tracker_status'
items:
type: array
description: An array of details of items in the shipment.
items:
description: Items in a shipment.
$ref: '#/components/schemas/tracker_item'
links:
type: array
description: An array of request-related HATEOAS links.
readOnly: true
items:
$ref: '#/components/schemas/link_description'
description: A request-related [HATEOAS link](/api/rest/responses/#hateoas-links).
- $ref: '#/components/schemas/activity_timestamps'
shipping_detail:
type: object
description: The shipping details.
title: Shipping Details
properties:
name:
description: The name of the person to whom to ship the items. Supports only the `full_name` property.
$ref: '#/components/schemas/name'
type:
description: A classification for the method of purchase fulfillment (e.g shipping, in-store pickup, etc). Either `type` or `options` may be present, but not both.
type: string
minLength: 1
maxLength: 255
pattern: ^[0-9A-Z_]+$
enum:
- SHIPPING
- PICKUP_IN_PERSON
- PICKUP_IN_STORE
- PICKUP_FROM_PERSON
options:
type: array
description: An array of shipping options that the payee or merchant offers to the payer to ship or pick up their items.
minItems: 0
maxItems: 10
items:
description: The option that the payee or merchant offers to the payer to ship or pick up their items.
$ref: '#/components/schemas/shipping_option'
address:
description: The address of the person to whom to ship the items. Supports only the `address_line_1`, `address_line_2`, `admin_area_1`, `admin_area_2`, `postal_code`, and `country_code` properties.
$ref: '#/components/schemas/address_portable'
venmo_wallet_request:
type: object
title: Venmo payment request object
description: Information needed to pay using Venmo.
properties:
vault_id:
description: The PayPal-generated ID for the saved Venmo wallet payment_source. This ID should be stored on the merchant's server so the saved payment source can be used for future transactions.
$ref: '#/components/schemas/vault_id'
email_address:
description: The email address of the payer.
$ref: '#/components/schemas/email'
experience_context:
$ref: '#/components/schemas/venmo_wallet_experience_context'
attributes:
description: Additional attributes associated with the use of this wallet.
$ref: '#/components/schemas/venmo_wallet_attributes'
authorization_status_details:
title: Auhorization Status Details
description: The details of the authorized payment status.
type: object
properties:
reason:
description: The reason why the authorized status is `PENDING`.
type: string
minLength: 1
maxLength: 24
pattern: ^[A-Z_]+$
enum:
- PENDING_REVIEW
supplementary_data:
title: Supplementary Data
type: object
description: Supplementary data about a payment. This object passes information that can be used to improve risk assessments and processing costs, for example, by providing Level 2 and Level 3 payment data.
properties:
card:
description: Merchants and partners can add Level 2 and 3 data to payments to reduce risk and payment processing costs. For more information about processing payments, see <a href="https://developer.paypal.com/docs/checkout/advanced/processing/">checkout</a> or <a href="https://developer.paypal.com/docs/multiparty/checkout/advanced/processing/">multiparty checkout</a>.
$ref: '#/components/schemas/card_supplementary_data'
paypal_wallet_attributes:
type: object
title: PayPal Wallet Attributes
description: Additional attributes associated with the use of this PayPal Wallet.
properties:
customer:
$ref: '#/components/schemas/paypal_wallet_customer'
vault:
description: Attributes used to provide the instructions during vaulting of the PayPal Wallet.
$ref: '#/components/schemas/vault_paypal_wallet_base'
net_amount_breakdown_item:
type: object
title: Net Amount Breakdown Item
description: The net amount. Returned when the currency of the refund is different from the currency of the PayPal account where the merchant holds their funds.
properties:
payable_amount:
description: The net amount debited from the merchant's PayPal account.
readOnly: true
$ref: '#/components/schemas/money'
converted_amount:
description: The converted payable amount.
readOnly: true
$ref: '#/components/schemas/money'
exchange_rate:
description: The exchange rate that determines the amount that was debited from the merchant's PayPal account.
readOnly: true
$ref: '#/components/schemas/exchange_rate'
link_description:
type: object
title: Link Description
description: The request-related [HATEOAS link](/api/rest/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 pr
# --- truncated at 32 KB (395 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/paypal/refs/heads/main/openapi/paypal-orders-api-openapi.yml