PayPal Orders API
The PayPal Orders API lets merchants create, update, authorize, capture, and manage orders for accepting payments through PayPal Checkout.
OpenAPI Specification
openapi: 3.0.3
info:
title: Paypal Orders
description: An order represents a payment between two or more parties. Use the Orders API to create, update, retrieve, authorize, and capture orders.
version: '2.13'
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.
- name: Trackers
description: Use the `/trackers` resource to update and retrieve tracking information for PayPal orders.
externalDocs:
url: https://developer.paypal.com/docs/api/orders/v2/
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: [email protected]
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
"/v2/checkout/orders/{id}/trackers/{tracker_id}":
patch:
summary: Update or cancel tracking information for a PayPal order
description: Updates or cancels the tracking information for a PayPal order, by ID. Updatable attributes or objects:<br/><br/><table><thead><th>Attribute</th><th>Op</th><th>Notes</th></thead><tbody></tr><tr><td><code>items</code></td><td>replace</td><td>Using replace op for <code>items</code> will replace the entire <code>items</code> object with the value sent in request.</td></tr><tr><td><code>notify_payer</code></td><td>replace, add</td><td></td></tr><tr><td><code>status</code></td><td>replace</td><td>Only patching status to CANCELLED is currently supported.</td></tr></tbody></table>
operationId: orders.trackers.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.trackers.patch-400"
'403':
description: Authorization failed due to insufficient permissions.
content:
application/json:
schema:
allOf:
- "$ref": "#/components/schemas/error_403"
- "$ref": "#/components/schemas/orders.trackers.patch-403"
'404':
description: The specified resource does not exist.
content:
application/json:
schema:
allOf:
- "$ref": "#/components/schemas/error_404"
- "$ref": "#/components/schemas/orders.trackers.patch-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.trackers.patch-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/tracker_id"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/patch_request"
examples:
orders_patch_request:
value:
- op: replace
path: "/purchase_units/@reference_id=='PUHF'/shipping/address"
value:
address_line_1: 2211 N First Street
address_line_2: Building 17
admin_area_2: San Jose
admin_area_1: CA
postal_code: '95131'
country_code: US
security:
- Oauth2:
- https://uri.paypal.com/services/payments/payment
tags:
- Trackers
components:
requestBodies:
patch_request:
content:
application/json:
schema:
"$ref": "#/components/schemas/patch_request"
securitySchemes:
Oauth2:
type: oauth2
description: Oauth 2.0 authentication
flows:
clientCredentials:
tokenUrl: "/v1/oauth2/token"
scopes:
https://uri.paypal.com/services/payments/payment: Manage payments and checkout workflow.
https://uri.paypal.com/services/payments/payment/reference-transaction: Permission to initiate reference transaction
https://uri.paypal.com/services/payments/initiatepayment: Initiates payments and checkout workflows.
https://uri.paypal.com/services/payments/orders/client-side-integration: Allows client-side integration on Create, Get, Patch, Authorize & Capture Order endpoints.
responses:
default:
description: The default response.
content:
application/json:
schema:
"$ref": "#/components/schemas/error_default"
schemas:
'400':
properties:
details:
type: array
items:
anyOf:
- title: INVALID_ARRAY_MAX_ITEMS
properties:
issue:
type: string
enum:
- INVALID_ARRAY_MAX_ITEMS
description:
type: string
enum:
- The number of items in an array parameter is too large.
- title: INVALID_ARRAY_MIN_ITEMS
properties:
issue:
type: string
enum:
- INVALID_ARRAY_MIN_ITEMS
description:
type: string
enum:
- The number of items in an array parameter is too small.
- title: INVALID_COUNTRY_CODE
properties:
issue:
type: string
enum:
- INVALID_COUNTRY_CODE
description:
type: string
enum:
- Country code is invalid. Please refer to https://developer.paypal.com/api/rest/reference/country-codes/ for a list of supported country codes.
- title: INVALID_PARAMETER_SYNTAX
properties:
issue:
type: string
enum:
- INVALID_PARAMETER_SYNTAX
description:
type: string
enum:
# --- truncated at 32 KB (419 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/paypal/refs/heads/main/openapi/paypal-checkout-orders-openapi-original.yml