> ## Documentation Index > Fetch the complete documentation index at: https://docs.paypal.ai/llms.txt > Use this file to discover all available pages before exploring further. # Receive updated order information via callback URL > The documentation for this 'endpoint' is different from the other endpoints under v2 Orders. For this endpoint the role of client and server is reversed. The client sending the request is PayPal, and the server sending the response is the merchant. In the request, PayPal will send the buyer's redacted shipping address and selected shipping option to the callback URL defined the create order request. The response from the merchant will update the Orders resource. ## OpenAPI ````yaml /api-reference/openapi-orders.json post /v2/checkout/orders/order-update-callback openapi: 3.0.4 info: title: 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.32' servers: - url: https://api-m.paypal.com description: Server for https scheme. security: [] tags: - name: externalcallback description: >- PayPal will use the callback url defined in the create order request to send merchants shipping address and shipping options data while the buyer is in the PayPal checkout. - 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: ../doc/USERGUIDE.md paths: /v2/checkout/orders/order-update-callback: post: tags: - externalcallback summary: Receive updated order information via callback URL description: >- The documentation for this 'endpoint' is different from the other endpoints under v2 Orders. For this endpoint the role of client and server is reversed. The client sending the request is PayPal, and the server sending the response is the merchant. In the request, PayPal will send the buyer's redacted shipping address and selected shipping option to the callback URL defined the create order request. The response from the merchant will update the Orders resource. operationId: server.callback parameters: - $ref: '#/components/parameters/authorization' requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/order_update_callback_request' examples: orders_shippingOptionsExternalCallback_discount_code_callback_add_code: summary: Discount Code Callback Request - Adding a Discount Code description: >- The PayPal callback server sends a request with the discount code provided by the buyer, along with the buyer's address and purchase_units of the order, to the merchant listener URL. The request payload represents the event triggered when the buyer applies a discount code. The merchant responds with the updated order details, reflecting the discount applied successfully. value: id: 5O190127TN364715T shipping_address: country_code: US admin_area_1: TX admin_area_2: Dallas postal_code: '75001' purchase_units: - reference_id: d9f80740-38f0-11e8-b467-0ed5f89f718b amount: currency_code: USD value: '100.00' breakdown: item_total: currency_code: USD value: '90.00' tax_total: currency_code: USD value: '10.00' shipping: currency_code: USD value: '0.00' items: - name: T-Shirt description: Green XL sku: sku01 unit_amount: currency_code: USD value: '90.00' tax: currency_code: USD value: '10.00' quantity: '1' category: PHYSICAL_GOODS orders_shippingOptionsExternalCallback_discount_code_callback_add_code_no_address: summary: >- Discount Code Callback Request - Adding a Discount Code - No Address description: >- The PayPal callback server sends a request with the discount code provided by the buyer, along with the purchase_units of the order, to the merchant listener URL. The request payload represents the event triggered when the buyer applies a discount code to an order that does not require shipping. The merchant responds with the updated order details, reflecting the discount applied successfully. value: id: 5O190127TN364715T purchase_units: - reference_id: d9f80740-38f0-11e8-b467-0ed5f89f718b amount: currency_code: USD value: '100.00' breakdown: item_total: currency_code: USD value: '90.00' tax_total: currency_code: USD value: '10.00' shipping: currency_code: USD value: '0.00' items: - name: E-book description: Digital E-book sku: sku01 unit_amount: currency_code: USD value: '90.00' tax: currency_code: USD value: '10.00' quantity: '1' category: DIGITAL_GOODS orders_shippingOptionsExternalCallback_discount_code_callback_remove_code: summary: Discount Code Callback Request - Removing a Discount Code description: >- The PayPal callback server sends a request with the discount code the buyer wants to remove, along with the buyer's address and purchase_units of the order, to the merchant listener URL. The request payload represents the event triggered when the buyer removes a discount code. The merchant responds with the updated order details, reflecting the discount removal. value: id: 5O190127TN364715T shipping_address: country_code: US admin_area_1: TX admin_area_2: Dallas postal_code: '75001' purchase_units: - reference_id: d9f80740-38f0-11e8-b467-0ed5f89f718b amount: currency_code: USD value: '90.00' breakdown: item_total: currency_code: USD value: '90.00' tax_total: currency_code: USD value: '10.00' shipping: currency_code: USD value: '0.00' discount: currency_code: USD value: '10.00' items: - name: T-Shirt description: Green XL sku: sku01 unit_amount: currency_code: USD value: '90.00' tax: currency_code: USD value: '10.00' quantity: '1' category: PHYSICAL_GOODS orders_shippingOptionsExternalCallback_shipping_address_callback_address_alone: summary: >- Shipping Options Callback Request - Shipping Address Only Event description: >- The PayPal callback server sends request with a buyer's shipping address, and the purchase_units of the order, to the merchant listener URL. The request payload is an example of the event that will be sent as soon as the buyer is presented with the "PayPal Buyer Approval" page. The merchant responds with a the appropriate tax calculation for the shipping address, and a list of available shipping options. value: id: 8HFTASDATTV shipping_address: country_code: US admin_area_1: TX admin_area_2: Dallas postal_code: '75001' purchase_units: - reference_id: d9f80740-38f0-11e8-b467-0ed5f89f718b amount: currency_code: USD value: '100.00' orders_shippingOptionsExternalCallback_shipping_address_callback_with_address_and_options: summary: >- Shipping Options Callback Request - Shipping Address and Shipping Options Event description: >- The PayPal callback server sends request with a buyer's shipping address, the shipping option the buyer selected, and the purchase_units of the order, to the merchant listener URL. The merchant responds with a the appropriate tax calculation and breakdown for the given address and shipping option combination. value: id: 5O190127TN364715T shipping_address: country_code: US admin_area_1: TX admin_area_2: Dallas postal_code: '75001' purchase_units: - reference_id: d9f80740-38f0-11e8-b467-0ed5f89f718b amount: currency_code: USD value: '100.00' responses: '200': description: The callback to merchant was successful. content: application/json: schema: $ref: '#/components/schemas/order_update_callback_response' examples: orders_shippingOptionsExternalCallback_discount_code_callback_add_code: summary: Discount Code Callback Request - Adding a Discount Code description: >- The PayPal callback server sends a request with the discount code provided by the buyer, along with the buyer's address and purchase_units of the order, to the merchant listener URL. The request payload represents the event triggered when the buyer applies a discount code. The merchant responds with the updated order details, reflecting the discount applied successfully. value: id: 5O190127TN364715T purchase_units: reference_id: d9f80740-38f0-11e8-b467-0ed5f89f718b amount: currency_code: USD value: '90.00' breakdown: item_total: currency_code: USD value: '90.00' tax_total: currency_code: USD value: '10.00' shipping: currency_code: USD value: '0.00' discount: currency_code: USD value: '10.00' breakdown: - value: '10.00' currency_code: USD discount_code: SUMMER_SALE description: $10 off for summer sale items: - name: T-Shirt description: Green XL sku: sku01 unit_amount: currency_code: USD value: '90.00' tax: currency_code: USD value: '10.00' quantity: '1' category: PHYSICAL_GOODS shipping: options: - id: FEDEX amount: currency_code: USD value: '0.00' type: SHIPPING label: Free Shipping selected: true orders_shippingOptionsExternalCallback_discount_code_callback_add_code_no_address: summary: >- Discount Code Callback Request - Adding a Discount Code - No Address description: >- The PayPal callback server sends a request with the discount code provided by the buyer, along with the purchase_units of the order, to the merchant listener URL. The request payload represents the event triggered when the buyer applies a discount code to an order that does not require shipping. The merchant responds with the updated order details, reflecting the discount applied successfully. value: id: 5O190127TN364715T orders_shippingOptionsExternalCallback_discount_code_callback_remove_code: summary: Discount Code Callback Request - Removing a Discount Code description: >- The PayPal callback server sends a request with the discount code the buyer wants to remove, along with the buyer's address and purchase_units of the order, to the merchant listener URL. The request payload represents the event triggered when the buyer removes a discount code. The merchant responds with the updated order details, reflecting the discount removal. value: id: 5O190127TN364715T purchase_units: reference_id: d9f80740-38f0-11e8-b467-0ed5f89f718b amount: currency_code: USD value: '100.00' breakdown: item_total: currency_code: USD value: '90.00' tax_total: currency_code: USD value: '10.00' shipping: currency_code: USD value: '0.00' items: - name: T-Shirt description: Green XL sku: sku01 unit_amount: currency_code: USD value: '90.00' tax: currency_code: USD value: '10.00' quantity: '1' category: PHYSICAL_GOODS shipping: options: - id: FEDEX amount: currency_code: USD value: '0.00' type: SHIPPING label: Free Shipping selected: true orders_shippingOptionsExternalCallback_shipping_address_callback_address_alone: summary: >- Shipping Options Callback Request - Shipping Address Only Event description: >- The PayPal callback server sends request with a buyer's shipping address, and the purchase_units of the order, to the merchant listener URL. The request payload is an example of the event that will be sent as soon as the buyer is presented with the "PayPal Buyer Approval" page. The merchant responds with a the appropriate tax calculation for the shipping address, and a list of available shipping options. value: id: 8HFTASDATTV orders_shippingOptionsExternalCallback_shipping_address_callback_with_address_and_options: summary: >- Shipping Options Callback Request - Shipping Address and Shipping Options Event description: >- The PayPal callback server sends request with a buyer's shipping address, the shipping option the buyer selected, and the purchase_units of the order, to the merchant listener URL. The merchant responds with a the appropriate tax calculation and breakdown for the given address and shipping option combination. value: id: 8HFTASDATTV '400': description: >- The request is not well-formed, is syntactically incorrect, or violates the schema. content: application/json: schema: $ref: '#/components/schemas/order_update_callback_error_response' '401': $ref: '#/components/responses/401_error_response' '403': $ref: '#/components/responses/403_error_response' '422': description: >- The requested action could not be completed, was semantically incorrect, or failed business validation. content: application/json: schema: $ref: '#/components/schemas/order_update_callback_error_response' '500': $ref: '#/components/responses/500_error_response' default: $ref: '#/components/responses/default_response' security: - Oauth2: - https://uri.paypal.com/services/payments/payment components: parameters: authorization: name: Authorization in: header description: Holds authorization information for external API calls. required: false schema: $ref: '#/components/schemas/standard_header_schema' examples: bearer: summary: Bearer authorization. description: >- An authorization header with information for the Bearer authorization scheme. The authorization parameter value is randomized for this example. value: >- Bearer A21AAGHr9qtiRRXH4oYcQokQgV99rGqEIfgrr8xHCclP0OzmD9KVgg5ppIIg1jzJgQkV4wd02svIvBJyg6cLFJjFow_SjBhxQ schemas: order_update_callback_request: title: OrderUpdateCallbackRequest description: >- Shipping Options Callback request. This will be implemented by the merchants. type: object required: - purchase_units properties: id: description: The ID of the order. type: string minLength: 1 maxLength: 36 pattern: ^[A-Z0-9-]+$ readOnly: true shipping_address: allOf: - $ref: '#/components/schemas/address_portable' - description: >- Redacted shipping address to be used for shipping options and tax calculations. not: anyOf: - required: - address_line_1 - required: - address_line_2 - required: - address_line_3 - required: - admin_area_3 - required: - admin_area_4 - required: - address_details shipping_option: allOf: - $ref: '#/components/schemas/shipping_option' - description: Buyer selected shipping option. not: required: - selected purchase_units: description: >- An array of purchase units. At present only 1 purchase_unit is supported. Each purchase unit establishes a contract between a payer and the payee. Each purchase unit represents either a full or partial order that the payer intends to purchase from the payee. type: array minItems: 1 maxItems: 1 items: allOf: - $ref: '#/components/schemas/purchase_unit_request' - title: purchase_unit order_update_callback_response: title: OrderUpdateCallbackResponse description: Returns the updated shipping options for an order. type: object properties: id: description: The ID of the order. type: string minLength: 1 maxLength: 36 pattern: ^[A-Z0-9-]+$ readOnly: true order_update_callback_error_response: title: OrderUpdateCallbackErrorResponse description: The error details. type: object required: - name properties: name: description: The human-readable, unique name of the error. type: string minLength: 1 maxLength: 256 pattern: ^.*$ message: description: The message that describes the error. type: string minLength: 1 maxLength: 2048 pattern: ^.*$ details: description: An array of additional details about the error. type: array minItems: 1 maxItems: 100 items: $ref: '#/components/schemas/order_update_callback_error_response_details' standard_header_schema: title: Schema Object for standard headers description: >- Standard headers are generally less restrictive in structure due to historical precedent across browsers, etc. This is a common schema for use in defining most standard headers. type: string minLength: 1 maxLength: 16000 pattern: ^.*$ address_portable: title: Portable Postal Address (Medium-Grained) description: >- The portable international postal address. Maps to [AddressValidationMetadata](https://github.com/googlei18n/libaddressinput/wiki/AddressValidationMetadata) and HTML 5.1 [Autofilling form controls: the autocomplete attribute](https://www.w3.org/TR/html51/sec-forms.html#autofilling-form-controls-the-autocomplete-attribute). type: object required: - country_code properties: address_line_1: description: >- The first line of the address, such as number and street, for example, `173 Drury Lane`. Needed for data entry, and Compliance and Risk checks. This field needs to pass the full address. type: string minLength: 0 maxLength: 300 pattern: ^[\S\s]*$ address_line_2: description: >- The second line of the address, for example, a suite or apartment number. type: string minLength: 0 maxLength: 300 pattern: ^[\S\s]*$ address_line_3: description: >- The third line of the address, if needed. Examples include a street complement for Brazil, direction text, such as `next to Walmart`, or a landmark in an Indian address. type: string minLength: 0 maxLength: 100 pattern: ^[\S\s]*$ admin_area_4: description: >- The neighborhood, ward, or district. This is smaller than `admin_area_level_3` or `sub_locality`. Value is: type: string minLength: 0 maxLength: 100 pattern: ^[\S\s]*$ admin_area_3: description: >- The sub-locality, suburb, neighborhood, or district. This is smaller than `admin_area_level_2`. Value is: type: string minLength: 0 maxLength: 100 pattern: ^[\S\s]*$ admin_area_2: description: A city, town, or village. Smaller than `admin_area_level_1`. type: string minLength: 0 maxLength: 120 pattern: ^[\S\s]*$ admin_area_1: description: >- The highest-level sub-division in a country, which is usually a province, state, or ISO-3166-2 subdivision. This data is formatted for postal delivery, for example, `CA` and not `California`. Value, by country, is: type: string minLength: 0 maxLength: 300 pattern: ^[\S\s]*$ postal_code: description: >- The postal code, which is the ZIP code or equivalent. Typically required for countries with a postal code or an equivalent. See [postal code](https://en.wikipedia.org/wiki/Postal_code). type: string minLength: 0 maxLength: 60 pattern: ^[\S\s]*$ country_code: $ref: '#/components/schemas/country_code' address_details: title: Address Details description: >- The non-portable additional address details include fine-grain address information for Compliance, Risk, and other scenarios. This isn't portable with common third-party and open source applications. This can include data that is redundant with core fields. For example, `address_portable.address_line_1` is usually a combination of `address_details.street_number`, `street_name`, and `street_type`. type: object properties: street_number: description: The street number. type: string minLength: 0 maxLength: 100 pattern: ^[\S\s]*$ street_name: description: The street name. Just `Drury` in `Drury Lane`. type: string minLength: 0 maxLength: 100 pattern: ^[\S\s]*$ street_type: description: >- The street type. For example, avenue, boulevard, road, or expressway. type: string minLength: 0 maxLength: 100 pattern: ^[\S\s]*$ delivery_service: description: >- The delivery service. Post office box, bag number, or post office name. type: string minLength: 0 maxLength: 100 pattern: ^[\S\s]*$ building_name: description: >- A named locations that represents the premise. Usually a building name or number or collection of buildings with a common name or number. For example, Craven House. type: string minLength: 0 maxLength: 100 pattern: ^[\S\s]*$ sub_building: description: >- The first-order entity below a named building or location that represents the sub-premise. Usually a single building within a collection of buildings with a common name. Can be a flat, story, floor, room, or apartment. type: string minLength: 0 maxLength: 100 pattern: ^[\S\s]*$ shipping_option: title: shipping_option description: >- The options that the payee or merchant offers to the payer to ship or pick up their items. type: object required: - id - label - selected properties: id: description: A unique ID that identifies a payer-selected shipping option. type: string minLength: 0 maxLength: 127 pattern: ^[\S\s]*$ label: description: >- A description that the payer sees, which helps them choose an appropriate shipping option. For example, `Free Shipping`, `USPS Priority Shipping`, `Expédition prioritaire USPS`, or `USPS yōuxiān fā huò`. Localize this description to the payer's locale. type: string minLength: 0 maxLength: 127 pattern: ^[\S\s]*$ type: allOf: - $ref: '#/components/schemas/shipping_type' - description: A classification for the method of purchase fulfillment. amount: allOf: - $ref: '#/components/schemas/money' - description: The shipping cost for the selected option. selected: description: >- If the API request sets `selected = true`, it represents the shipping option that the payee or merchant expects to be pre-selected for the payer when they first view the `shipping.options` in the PayPal Checkout experience. As part of the response if a `shipping.option` contains `selected=true`, it represents the shipping option that the payer selected during the course of checkout with PayPal. Only one `shipping.option` can be set to `selected=true`. type: boolean purchase_unit_request: title: Purchase Unit Request description: >- The purchase unit request. Includes required information for the payment contract. type: object required: - amount properties: reference_id: description: >- The API caller-provided external ID for the purchase unit. Required for multiple purchase units when you must update the order through `PATCH`. If you omit this value and the order contains only one purchase unit, PayPal sets this value to `default`. type: string minLength: 1 maxLength: 256 pattern: ^[\S\s]*$ amount: allOf: - $ref: '#/components/schemas/amount_with_breakdown' - description: >- The total order amount with an optional breakdown that provides details, such as the total item amount, total tax amount, shipping, handling, insurance, and discounts, if any.
If you specify `amount.breakdown`, the amount equals `item_total` plus `tax_total` plus `shipping` plus `handling` plus `insurance` minus `shipping_discount` minus discount.
The amount must be a positive number. The `amount.value` field supports up to 15 digits preceding the decimal. For a list of supported currencies, decimal precision, and maximum charge amount, see the PayPal REST APIs Currency Codes. payee: allOf: - $ref: '#/components/schemas/payee' - description: The merchant who receives payment for this transaction. payment_instruction: $ref: '#/components/schemas/payment_instruction' description: description: >-
This field supports up to 3,000 characters, but any content beyond 127 characters (including spaces) will be truncated. The 127 character limit is reflected in the response representation of this field.
The purchase description. The maximum length of the character is dependent on the type of characters used. The character length is specified assuming a US ASCII character. Depending on type of character; (e.g. accented character, Japanese characters) the number of characters that that can be specified as input might not equal the permissible max length. type: string minLength: 1 maxLength: 3000 pattern: ^[\S\s]*$ custom_id: description: >- The API caller-provided external ID. Used to reconcile client transactions with PayPal transactions. Appears in transaction and settlement reports but is not visible to the payer. type: string minLength: 1 maxLength: 255 pattern: ^[\S\s]*$ invoice_id: description: >- The API caller-provided external invoice number for this order. Appears in both the payer's transaction history and the emails that the payer receives. invoice_id values are required to be unique within each merchant account by default. Although the uniqueness validation is configurable, disabling this behavior will remove the account's ability to use invoice_id in other APIs as an identifier. It is highly recommended to keep a unique invoice_id for each Order. type: string minLength: 1 maxLength: 127 pattern: ^[\S\s]*$ soft_descriptor: description: >-
This field supports up to 127 characters, but any content beyond 22 characters (including spaces) will be truncated. The 22 character limit is reflected in the response representation of this field.
The soft descriptor is the dynamic text used to construct the statement descriptor that appears on a payer's card statement.

If an Order is paid using the "PayPal Wallet", the statement descriptor will appear in following format on the payer's card statement: PAYPAL_prefix+(space)+merchant_descriptor+(space)+ soft_descriptor
Note: The merchant descriptor is the descriptor of the merchant’s payment receiving preferences which can be seen by logging into the merchant account https://www.sandbox.paypal.com/businessprofile/settings/info/edit
The PAYPAL prefix uses 8 characters. Only the first 22 characters will be displayed in the statement.
For example, if:Then, the statement descriptor on the card is PAYPAL * Janes Gift 80. type: string minLength: 1 maxLength: 1000 pattern: ^[\S\s]*$ items: description: An array of items that the customer purchases from the merchant. type: array minItems: 0 maxItems: 32767 items: allOf: - $ref: '#/components/schemas/item_request' - title: item description: The item. shipping: allOf: - $ref: '#/components/schemas/shipping_detail' - description: The name and address of the person to whom to ship the items. supplementary_data: allOf: - $ref: '#/components/schemas/supplementary_data' - description: Contains Supplementary Data. order_update_callback_error_response_details: title: OrderUpdateCallbackErrorResponseDetails description: The error details. Required for client-side `4XX` errors. type: object required: - issue properties: field: 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. type: string minLength: 0 maxLength: 256 pattern: ^.*$ value: description: The value of the field that caused the error. type: string minLength: 0 maxLength: 1024 pattern: ^.*$ issue: description: The unique, fine-grained application-level error code. type: string minLength: 0 maxLength: 256 pattern: ^.*$ error: title: Error description: The error details. type: object required: - debug_id - message - name properties: name: description: The human-readable, unique name of the error. type: string minLength: 0 maxLength: 2147483647 pattern: ^[\S\s]*$ message: description: The message that describes the error. type: string minLength: 0 maxLength: 2147483647 pattern: ^[\S\s]*$ debug_id: description: The PayPal internal ID. Used for correlation purposes. type: string minLength: 0 maxLength: 2147483647 pattern: ^[\S\s]*$ details: description: An array of additional details about the error. type: array minItems: 0 maxItems: 32767 items: allOf: - $ref: '#/components/schemas/error_details' - title: error_details links: description: >- An array of request-related [HATEOAS links](/api/rest/responses/#hateoas-links). type: array minItems: 0 maxItems: 32767 readOnly: true items: allOf: - $ref: '#/components/schemas/link_description' - title: link_description readOnly: true country_code: description: >- The [2-character ISO 3166-1 code](/api/rest/reference/country-codes/) that identifies the country or region.
Note: The country code for Great Britain is GB and not UK 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.
type: string minLength: 2 maxLength: 2 pattern: ^([A-Z]{2}|C2)$ shipping_type: title: shipping_type description: A classification for the method of purchase fulfillment. type: string enum: - SHIPPING - PICKUP - PICKUP_IN_STORE - PICKUP_FROM_PERSON default: SHIPPING money: title: Money description: >- The currency and amount for a financial transaction, such as a balance or payment due. type: object required: - currency_code - value properties: currency_code: $ref: '#/components/schemas/currency_code' value: description: >- The value, which might be:For the required number of decimal places for a currency code, see [Currency Codes](/api/rest/reference/currency-codes/). type: string minLength: 0 maxLength: 32 pattern: ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$ amount_with_breakdown: title: amount_with_breakdown description: >- The total order amount with an optional breakdown that provides details, such as the total item amount, total tax amount, shipping, handling, insurance, and discounts, if any.
If you specify `amount.breakdown`, the amount equals `item_total` plus `tax_total` plus `shipping` plus `handling` plus `insurance` minus `shipping_discount` minus discount.
The amount must be a positive number. For listed of supported currencies and decimal precision, see the PayPal REST APIs Currency Codes. type: object allOf: - $ref: '#/components/schemas/money' - type: object properties: breakdown: $ref: '#/components/schemas/amount_breakdown' payee: title: payee description: >- The merchant who receives the funds and fulfills the order. The merchant is also known as the payee. type: object allOf: - $ref: '#/components/schemas/payee_base' - type: object payment_instruction: title: payment_instruction description: >- Any additional payment instructions to be consider during payment processing. This processing instruction is applicable for Capturing an order or Authorizing an Order. type: object properties: platform_fees: description: >- An array of various fees, commissions, tips, or donations. This field is only applicable to merchants that been enabled for PayPal Complete Payments Platform for Marketplaces and Platforms capability. type: array minItems: 0 maxItems: 1 items: allOf: - $ref: '#/components/schemas/platform_fee' - title: platform_fee disbursement_mode: allOf: - $ref: '#/components/schemas/disbursement_mode' - description: >- The funds that are held payee by the marketplace/platform. This field is only applicable to merchants that been enabled for PayPal Complete Payments Platform for Marketplaces and Platforms capability. payee_pricing_tier_id: description: >- This field is only enabled for selected merchants/partners to use and provides the ability to trigger a specific pricing rate/plan for a payment transaction. The list of eligible 'payee_pricing_tier_id' would be provided to you by your Account Manager. Specifying values other than the one provided to you by your account manager would result in an error. type: string minLength: 1 maxLength: 20 pattern: ^.*$ payee_receivable_fx_rate_id: description: >- FX identifier generated returned by PayPal to be used for payment processing in order to honor FX rate (for eligible integrations) to be used when amount is settled/received into the payee account. type: string minLength: 1 maxLength: 4000 pattern: ^.*$ item_request: title: item_request description: The details for the items to be purchased. type: object required: - name - quantity - unit_amount properties: name: description: >- The item name or title.
This field supports up to 3000 characters, but any content beyond 127 characters (including spaces) will be truncated. The 127 character limit is reflected in the response representation of this field
. type: string minLength: 1 maxLength: 3000 pattern: ^[\S\s]*$ unit_amount: allOf: - $ref: '#/components/schemas/money' - description: >- The item price or rate per unit. If you specify unit_amount, purchase_units[].amount.breakdown.item_total is required. Must equal unit_amount * quantity for all items. unit_amount.value can not be a negative number. tax: allOf: - $ref: '#/components/schemas/money' - description: >- The item tax for each unit. If tax is specified, purchase_units[].amount.breakdown.tax_total is required. Must equal tax * quantity for all items. tax.value can not be a negative number. quantity: description: The item quantity. Must be a whole number. type: string minLength: 0 maxLength: 10 pattern: ^[1-9][0-9]{0,9}$ description: description: >-
This field supports up to 4000 characters, but any content beyond 2048 characters (including spaces) will be truncated. The 2048 character limit is reflected in the response representation of this field
. type: string minLength: 0 maxLength: 4000 pattern: ^[\S\s]*$ sku: description: The stock keeping unit (SKU) for the item. type: string minLength: 0 maxLength: 127 pattern: ^[\S\s]*$ url: description: >- The URL to the item being purchased. Visible to buyer and used in buyer experiences. type: string minLength: 1 maxLength: 2048 format: uri category: description: The item category type. type: string enum: - DIGITAL_GOODS - PHYSICAL_GOODS - DONATION image_url: description: >- The URL of the item's image. File type and size restrictions apply. An image that violates these restrictions will not be honored. type: string minLength: 1 maxLength: 2048 format: uri upc: allOf: - $ref: '#/components/schemas/universal_product_code' - description: The Universal Product Code of the item. billing_plan: $ref: '#/components/schemas/order_billing_plan' shipping_detail: title: shipping_detail description: The shipping details. type: object properties: name: allOf: - $ref: '#/components/schemas/name' - description: >- The name of the person to whom to ship the items. Supports only the `full_name` property. not: anyOf: - required: - prefix - required: - given_name - required: - surname - required: - middle_name - required: - suffix - required: - alternate_full_name email_address: allOf: - $ref: '#/components/schemas/email_address' - description: >- The email address of the recipient of the shipped items, which may belong to either the payer, or an alternate contact, for delivery. phone_number: allOf: - $ref: '#/components/schemas/phone' - description: >- The phone number of the recipient of the shipped items, which may belong to either the payer, or an alternate contact, for delivery. [Format - canonical international [E.164 numbering plan](https://www.itu.int/rec/T-REC-E.164/en)] not: required: - extension_number type: title: Fulfillment 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 enum: - SHIPPING - PICKUP_IN_PERSON - PICKUP_IN_STORE - PICKUP_FROM_PERSON default: SHIPPING options: description: >- An array of shipping options that the payee or merchant offers to the payer to ship or pick up their items. type: array minItems: 0 maxItems: 30 items: allOf: - $ref: '#/components/schemas/shipping_option' - title: shipping_option description: >- The option that the payee or merchant offers to the payer to ship or pick up their items. address: allOf: - $ref: '#/components/schemas/address_portable' - 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. `admin_area_1` is required for addresses located in Argentina, Brazil, China, Canada, India, Indonesia, Japan, Mexico, Thailand, and the United States. not: anyOf: - required: - address_line_3 - required: - admin_area_3 - required: - admin_area_4 - required: - address_details supplementary_data: title: supplementary_data 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. type: object properties: card: allOf: - $ref: '#/components/schemas/card_supplementary_data' - 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 checkout or multiparty checkout. risk: allOf: - $ref: '#/components/schemas/risk_supplementary_data' - description: >- Merchants and partners can add additional customer parameters that can help with better fraud protection and reduced risk for unbranded card payments. error_details: title: Error Details description: The error details. Required for client-side `4XX` errors. type: object required: - issue properties: field: 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. type: string minLength: 0 maxLength: 2147483647 pattern: ^[\S\s]*$ value: description: The value of the field that caused the error. type: string minLength: 0 maxLength: 2147483647 pattern: ^[\S\s]*$ location: description: >- The location of the field that caused the error. Value is `body`, `path`, or `query`. type: string minLength: 0 maxLength: 2147483647 pattern: ^[\S\s]*$ default: body issue: description: The unique, fine-grained application-level error code. type: string minLength: 0 maxLength: 2147483647 pattern: ^[\S\s]*$ links: description: >- An array of request-related [HATEOAS links](/api/rest/responses/#hateoas-links) that are either relevant to the issue by providing additional information or offering potential resolutions. type: array minItems: 1 maxItems: 4 readOnly: true items: allOf: - $ref: '#/components/schemas/link_description' - title: link_description readOnly: true description: 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. type: string minLength: 0 maxLength: 2147483647 pattern: ^[\S\s]*$ 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: 2147483647 pattern: ^[\S\s]*$ 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: 2147483647 pattern: ^[\S\s]*$ method: description: The HTTP method required to make the related call. type: string enum: - GET - POST - PUT - DELETE - HEAD - CONNECT - OPTIONS - PATCH title: description: The link title. type: string minLength: 0 maxLength: 2147483647 pattern: ^[\S\s]*$ mediaType: title: media_type description: >- The media type, as defined by [RFC 2046](https://www.ietf.org/rfc/rfc2046.txt). Describes the link target. type: string minLength: 0 maxLength: 2147483647 pattern: ^[\S\s]*$ encType: title: enc_type description: The media type in which to submit the request data. type: string minLength: 0 maxLength: 2147483647 pattern: ^[\S\s]*$ default: application/json schema: allOf: - $ref: '#/components/schemas/link_schema' - description: The schema that describes the request data. targetSchema: allOf: - $ref: '#/components/schemas/link_schema' - title: target_schema description: The schema that describes the link target. currency_code: description: >- The [three-character ISO-4217 currency code](/api/rest/reference/currency-codes/) that identifies the currency. type: string minLength: 3 maxLength: 3 pattern: ^[\S\s]*$ amount_breakdown: title: amount_breakdown description: >- The breakdown of the amount. Breakdown provides details such as total item amount, total tax amount, shipping, handling, insurance, and discounts, if any. type: object properties: item_total: allOf: - $ref: '#/components/schemas/money' - description: >- The subtotal for all items. Required if the request includes `purchase_units[].items[].unit_amount`. Must equal the sum of `(items[].unit_amount * items[].quantity)` for all items. item_total.value can not be a negative number. shipping: allOf: - $ref: '#/components/schemas/money' - description: >- The shipping fee for all items within a given `purchase_unit`. shipping.value can not be a negative number. handling: allOf: - $ref: '#/components/schemas/money' - description: >- The handling fee for all items within a given `purchase_unit`. handling.value can not be a negative number. tax_total: allOf: - $ref: '#/components/schemas/money' - description: >- The total tax for all items. Required if the request includes `purchase_units.items.tax`. Must equal the sum of `(items[].tax * items[].quantity)` for all items. tax_total.value can not be a negative number. insurance: allOf: - $ref: '#/components/schemas/money' - description: >- The insurance fee for all items within a given `purchase_unit`. insurance.value can not be a negative number. shipping_discount: allOf: - $ref: '#/components/schemas/money' - description: >- The shipping discount for all items within a given `purchase_unit`. shipping_discount.value can not be a negative number. discount: allOf: - $ref: '#/components/schemas/discount_with_breakdown' - description: >- The discount for all items within a given `purchase_unit`. discount.value can not be a negative number. payee_base: title: payee_base description: >- The details for the merchant who receives the funds and fulfills the order. The merchant is also known as the payee. type: object properties: email_address: allOf: - $ref: '#/components/schemas/email' - description: The email address of merchant. merchant_id: allOf: - $ref: '#/components/schemas/account_id' - description: The encrypted PayPal account ID of the merchant. platform_fee: title: platform_fee description: >- The platform or partner fee, commission, or brokerage fee that is associated with the transaction. Not a separate or isolated transaction leg from the external perspective. The platform fee is limited in scope and is always associated with the original payment for the purchase unit. type: object required: - amount properties: amount: allOf: - $ref: '#/components/schemas/money' - title: amount description: The fee for this transaction. payee: allOf: - $ref: '#/components/schemas/payee_base' - title: payee description: The recipient of the fee for this transaction. disbursement_mode: title: disbursement_mode description: The funds that are held on behalf of the merchant. type: string enum: - INSTANT - DELAYED default: INSTANT universal_product_code: title: universal_product_code description: The Universal Product Code of the item. type: object required: - code - type properties: type: title: Universal Product Code Type description: The Universal Product Code type. type: string enum: - UPC-A - UPC-B - UPC-C - UPC-D - UPC-E - UPC-2 - UPC-5 code: description: The UPC product code of the item. type: string minLength: 6 maxLength: 17 pattern: ^[0-9]{0,17}$ order_billing_plan: title: order_billing_plan description: >- Metadata for merchant-managed recurring billing plans. Valid only during the saved payment method token or billing agreement creation. type: object required: - billing_cycles properties: billing_cycles: description: >- An array of billing cycles for trial billing and regular billing. A plan can have at most two trial cycles and only one regular cycle. type: array minItems: 1 maxItems: 3 items: $ref: '#/components/schemas/billing_cycle' setup_fee: allOf: - $ref: '#/components/schemas/money' - description: >- The setup fee for the recurring plan. Ensure its part of the item amount. name: description: Name of the recurring plan. type: string minLength: 1 maxLength: 127 pattern: ^[A-Za-z0-9() +',.:-]+$ name: title: Name description: The name of the party. type: object properties: prefix: description: The prefix, or title, to the party's name. type: string minLength: 0 maxLength: 140 pattern: ^[\S\s]*$ given_name: description: When the party is a person, the party's given, or first, name. type: string minLength: 0 maxLength: 140 pattern: ^[\S\s]*$ surname: 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. type: string minLength: 0 maxLength: 140 pattern: ^[\S\s]*$ middle_name: 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. type: string minLength: 0 maxLength: 140 pattern: ^[\S\s]*$ suffix: description: The suffix for the party's name. type: string minLength: 0 maxLength: 140 pattern: ^[\S\s]*$ full_name: description: When the party is a person, the party's full name. type: string minLength: 0 maxLength: 300 pattern: ^[\S\s]*$ email_address: description: >- The internationalized email address.
Note: Up to 64 characters are allowed before and 255 characters are allowed after the @ sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted @ sign exists.
type: string minLength: 3 maxLength: 254 pattern: >- ^(?:[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+)*|"(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21\x23-\x5b\x5d-\x7f]|\\[\x01-\x09\x0b\x0c\x0e-\x7f])*")@(?:(?:[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?\.)+[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?|\[(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?|[A-Za-z0-9-]*[A-Za-z0-9]:(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21-\x5a\x53-\x7f]|\\[\x01-\x09\x0b\x0c\x0e-\x7f])+)\])$ phone: 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). type: object required: - country_code - national_number properties: country_code: title: country_calling_code 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). type: string minLength: 1 maxLength: 3 pattern: ^[0-9]{1,3}?$ national_number: 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). type: string minLength: 1 maxLength: 14 pattern: ^[0-9]{1,14}?$ extension_number: description: The extension number. type: string minLength: 1 maxLength: 15 pattern: ^[0-9]{1,15}?$ card_supplementary_data: title: card_supplementary_data 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 checkout or multiparty checkout. type: object properties: level_2: $ref: '#/components/schemas/level_2_card_processing_data' level_3: $ref: '#/components/schemas/level_3_card_processing_data' risk_supplementary_data: title: risk_supplementary_data description: >- Additional information necessary to evaluate the risk profile of a transaction. type: object properties: customer: $ref: '#/components/schemas/participant_metadata' link_schema: title: Link Schema description: The request data or link target. type: object properties: additionalItems: title: additional_items description: Any additional items. type: object dependencies: title: Dependencies description: The dependencies. type: object items: title: Items description: An item. type: object definitions: title: Definitions description: Definitions. type: object patternProperties: title: pattern_properties description: The pattern properties. type: object properties: title: Properties description: The properties. type: object allOf: title: all_of description: >- An array of sub-schemas. The data must validate against all sub-schemas. type: array minItems: 0 maxItems: 32767 items: title: all_of_item description: A sub-schema against which the data must validate. type: object anyOf: title: any_of description: >- An array of sub-schemas. The data must validate against one or more sub-schemas. type: array minItems: 0 maxItems: 32767 items: title: any_of_item description: A sub-schema against which the data must validate. type: object oneOf: title: one_of description: >- An array of sub-schemas. The data must validate against one sub-schema. type: array minItems: 0 maxItems: 32767 items: title: one_of_item description: A sub-schema against which the data must validate. type: object not: title: Not description: Not. type: object links: description: An array of links. type: array minItems: 0 maxItems: 32767 readOnly: true items: title: link description: A link. type: object readOnly: true fragmentResolution: title: fragment_resolution description: The fragment resolution. type: string minLength: 0 maxLength: 2147483647 pattern: ^[\S\s]*$ media: title: Media description: The media type and context-encoding scheme. type: object properties: type: description: >- The media type. See [Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types](https://tools.ietf.org/html/rfc2046). type: string minLength: 0 maxLength: 2147483647 pattern: ^[\S\s]*$ binaryEncoding: title: binary_encoding description: >- The content-encoding scheme. See [Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies](https://tools.ietf.org/html/rfc2045). type: string minLength: 0 maxLength: 2147483647 pattern: ^[\S\s]*$ pathStart: title: path_start description: >- To apply this schema to the instances' URIs, start the URIs with this value. type: string minLength: 0 maxLength: 2147483647 format: uri discount_with_breakdown: title: discount_with_breakdown description: >- The discount amount and currency code. For list of supported currencies and decimal precision, see the PayPal REST APIs Currency Codes. type: object allOf: - $ref: '#/components/schemas/money' - type: object email: title: email description: >- The internationalized email address.
Note: Up to 64 characters are allowed before and 255 characters are allowed after the @ sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted @ sign exists.
type: string minLength: 3 maxLength: 254 pattern: >- ^.*(?:[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+)*|(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21\x23-\x5b\x5d-\x7f]|\[\x01-\x09\x0b\x0c\x0e-\x7f])*")@(?:(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?\.)+[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?|\[(?:(?:(2(5[0-5]|[0-4][0-9])|1[0-9][0-9]|[1-9]?[0-9]))\.){3}(?:(2(5[0-5]|[0-4][0-9])|1[0-9][0-9]|[1-9]?[0-9])|[a-zA-Z0-9-]*[a-zA-Z0-9]:(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21-\x5a\x53-\x7f]|\[\x01-\x09\x0b\x0c\x0e-\x7f])+)\]).*$ account_id: title: PayPal Account Identifier description: The account identifier for a PayPal account. type: string minLength: 13 maxLength: 13 pattern: ^[2-9A-HJ-NP-Z]{13}$ billing_cycle: title: billing_cycle description: >- The billing cycle providing details of the billing frequency, amount, duration and if the billing cycle is a free, discounted or regular billing cycle. The sequence of the billing cycle will be in the following order - free trial billing cycle(s), discounted trial billing cycle(s), regular billing cycle(s). type: object required: - tenure_type properties: tenure_type: description: >- The tenure type of the billing cycle identifies if the billing cycle is a trial(free or discounted) or regular billing cycle. type: string enum: - REGULAR - TRIAL pricing_scheme: allOf: - $ref: '#/components/schemas/pricing_scheme' - description: >- The active pricing scheme for this billing cycle. A free trial billing cycle does not require a pricing scheme. total_cycles: description: >- The number of times this billing cycle gets executed. Trial billing cycles can only be executed a finite number of times (value between 1 and 999 for total_cycles). Regular billing cycles can be executed infinite times (value of 0 for total_cycles) or a finite number of times (value between 1 and 999 for total_cycles). type: integer minimum: 0 maximum: 999 default: 1 sequence: description: >- The order in which this cycle is to run among other billing cycles. For example, a trial billing cycle has a `sequence` of `1` while a regular billing cycle has a `sequence` of `2`, so that trial cycle runs before the regular cycle. type: integer minimum: 1 maximum: 3 default: 1 start_date: allOf: - $ref: '#/components/schemas/date_no_time' - description: >- The start date for the billing cycle, in YYYY-MM-DD. This field should be not be provided if the billing cycle starts at the time of checkout. When this field is not provided, the billing cycle amount will be included in any data validations confirming that the total provided by the merchant match the sum of individual items due at the time of checkout. Only one billing cycle (with sequence equal to 1) can have a no start date. level_2_card_processing_data: title: level_2 description: >- The level 2 card processing data collections. If your merchant account has been configured for Level 2 processing this field will be passed to the processor on your behalf. Please contact your PayPal Technical Account Manager to define level 2 data for your business. type: object properties: invoice_id: description: >- Use this field to pass a purchase identification value of up to 127 ASCII characters. The length of this field will be adjusted to meet network specifications (25chars for Visa and Mastercard, 17chars for Amex), and the original invoice ID will still be displayed in your existing reports. type: string minLength: 1 maxLength: 127 pattern: ^[\w‘\-.,":;\!?]*$ tax_total: allOf: - $ref: '#/components/schemas/money' - description: > Use this field to break down the amount of tax included in the total purchase amount. The value provided here will not add to the total purchase amount. The value can't be negative, and in most cases, it must be greater than zero in order to qualify for lower interchange rates. Value, by country, is: UK. A county. US. A state. Canada. A province. Japan. A prefecture. Switzerland. A kanton. level_3_card_processing_data: title: level_3 description: >- The level 3 card processing data collections, If your merchant account has been configured for Level 3 processing this field will be passed to the processor on your behalf. Please contact your PayPal Technical Account Manager to define level 3 data for your business. type: object properties: shipping_amount: allOf: - $ref: '#/components/schemas/money' - description: >- Use this field to break down the shipping cost included in the total purchase amount. The value provided here will not add to the total purchase amount. The value cannot be negative. duty_amount: allOf: - $ref: '#/components/schemas/money' - description: >- Use this field to break down the duty amount included in the total purchase amount. The value provided here will not add to the total purchase amount. The value cannot be negative. discount_amount: allOf: - $ref: '#/components/schemas/money' - description: >- Use this field to break down the discount amount included in the total purchase amount. The value provided here will not add to the total purchase amount. The value cannot be negative. shipping_address: allOf: - $ref: '#/components/schemas/address_portable' - 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. not: anyOf: - required: - address_line_3 - required: - admin_area_3 - required: - admin_area_4 - required: - address_details ships_from_postal_code: description: Use this field to specify the postal code of the shipping location. type: string minLength: 1 maxLength: 60 pattern: ^[a-zA-Z0-9_'.-]*$ line_items: description: >- A list of the items that were purchased with this payment. If your merchant account has been configured for Level 3 processing this field will be passed to the processor on your behalf. type: array minItems: 1 maxItems: 100 items: allOf: - $ref: '#/components/schemas/line_item' - title: line_item participant_metadata: title: participant_metadata description: Profile information of the sender or receiver. type: object properties: ip_address: allOf: - $ref: '#/components/schemas/ip_address' - description: >- The consumer's IP address, which can be represented in either IPv4 or IPv6 format. pricing_scheme: title: pricing_scheme description: The pricing scheme details. type: object required: - pricing_model properties: price: allOf: - $ref: '#/components/schemas/money' - description: >- The price the customer will be charged based on the pricing model pricing_model: description: The pricing model for the billing cycle. type: string enum: - FIXED - VARIABLE - AUTO_RELOAD reload_threshold_amount: allOf: - $ref: '#/components/schemas/money' - description: >- The threshold amount on which the reload charge would be triggered. This will be associated with the account-balance where if the account-balance goes below this amount then customer would incur reload charge. date_no_time: description: >- The stand-alone date, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). To represent special legal values, such as a date of birth, you should use dates with no associated time or time-zone data. Whenever possible, use the standard `date_time` type. This regular expression does not validate all dates. For example, February 31 is valid and nothing is known about leap years. type: string minLength: 10 maxLength: 10 pattern: ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])$ line_item: title: line_item description: >- The line items for this purchase. If your merchant account has been configured for Level 3 processing this field will be passed to the processor on your behalf. type: object allOf: - $ref: '#/components/schemas/item_without_category_tax_or_amount' - type: object properties: unit_amount: allOf: - $ref: '#/components/schemas/money' - description: >- The item price or rate per unit. Must equal unit_amount * quantity for all items. unit_amount.value can not be a negative number. tax: allOf: - $ref: '#/components/schemas/money' - description: >- The item tax for each unit. Must equal tax * quantity for all items. tax.value can not be a negative number. commodity_code: description: >- Code used to classify items purchased and track the total amount spent across various categories of products and services. Different corporate purchasing organizations may use different standards, but the United Nations Standard Products and Services Code (UNSPSC) is frequently used. type: string minLength: 1 maxLength: 12 pattern: ^[a-zA-Z0-9_'.-]*$ discount_amount: allOf: - $ref: '#/components/schemas/money' - description: >- Use this field to break down the discount amount included in the total purchase amount. The value provided here will not add to the total purchase amount. The value cannot be negative. total_amount: allOf: - $ref: '#/components/schemas/money' - description: >- The subtotal for all items. Must equal the sum of (items[].unit_amount * items[].quantity) for all items. item_total.value can not be a negative number. unit_of_measure: description: >- Unit of measure is a standard used to express the magnitude of a quantity in international trade. Most commonly used (but not limited to) examples are: Acre (ACR), Ampere (AMP), Centigram (CGM), Centimetre (CMT), Cubic inch (INQ), Cubic metre (MTQ), Fluid ounce (OZA), Foot (FOT), Hour (HUR), Item (ITM), Kilogram (KGM), Kilometre (KMT), Kilowatt (KWT), Liquid gallon (GLL), Liter (LTR), Pounds (LBS), Square foot (FTK). type: string minLength: 1 maxLength: 12 pattern: ^[a-zA-Z0-9_'.-]*$ ip_address: title: IP Address description: >- An Internet Protocol address (IP address). This address assigns a numerical label to each device that is connected to a computer network through the Internet Protocol. Supports IPv4 and IPv6 addresses. type: string minLength: 7 maxLength: 39 pattern: >- ^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$|^(([a-zA-Z]|[a-zA-Z][a-zA-Z0-9\-]*[a-zA-Z0-9])\.)*([A-Za-z]|[A-Za-z][A-Za-z0-9\-]*[A-Za-z0-9])$|^\s*((([0-9A-Fa-f]{1,4}:){7}([0-9A-Fa-f]{1,4}|:))|(([0-9A-Fa-f]{1,4}:){6}(:[0-9A-Fa-f]{1,4}|((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3})|:))|(([0-9A-Fa-f]{1,4}:){5}(((:[0-9A-Fa-f]{1,4}){1,2})|:((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3})|:))|(([0-9A-Fa-f]{1,4}:){4}(((:[0-9A-Fa-f]{1,4}){1,3})|((:[0-9A-Fa-f]{1,4})?:((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}))|:))|(([0-9A-Fa-f]{1,4}:){3}(((:[0-9A-Fa-f]{1,4}){1,4})|((:[0-9A-Fa-f]{1,4}){0,2}:((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}))|:))|(([0-9A-Fa-f]{1,4}:){2}(((:[0-9A-Fa-f]{1,4}){1,5})|((:[0-9A-Fa-f]{1,4}){0,3}:((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}))|:))|(([0-9A-Fa-f]{1,4}:){1}(((:[0-9A-Fa-f]{1,4}){1,6})|((:[0-9A-Fa-f]{1,4}){0,4}:((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}))|:))|(:(((:[0-9A-Fa-f]{1,4}){1,7})|((:[0-9A-Fa-f]{1,4}){0,5}:((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}))|:)))(%.+)?\s*$ item_without_category_tax_or_amount: title: item description: The details for the items to be purchased. type: object required: - name - quantity properties: name: description: The item name or title. type: string minLength: 1 maxLength: 127 pattern: ^[\S\s]*$ quantity: description: The item quantity. Must be a whole number. type: string minLength: 0 maxLength: 10 pattern: ^[1-9][0-9]{0,9}$ description: description: The detailed item description. type: string minLength: 0 maxLength: 2048 pattern: ^[\S\s]*$ sku: description: The stock keeping unit (SKU) for the item. type: string minLength: 0 maxLength: 127 pattern: ^[\S\s]*$ url: description: >- The URL to the item being purchased. Visible to buyer and used in buyer experiences. type: string minLength: 1 maxLength: 2048 format: uri image_url: description: >- The URL of the item's image. File type and size restrictions apply. An image that violates these restrictions will not be honored. type: string minLength: 1 maxLength: 2048 format: uri upc: allOf: - $ref: '#/components/schemas/universal_product_code' - description: The Universal Product Code of the item. billing_plan: $ref: '#/components/schemas/order_billing_plan' responses: 401_error_response: description: Unauthorized. content: application/json: schema: $ref: '#/components/schemas/error' examples: generic: summary: Generic 'Unauthorized' error. description: Example response for unauthorized request. value: name: AUTHENTICATION_FAILURE debug_id: b1d1f06c7246c message: >- Authentication failed due to missing Authorization header, or invalid authentication credentials. 403_error_response: description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/error' examples: generic: summary: Generic 'Forbidden' error. description: Example response for a forbidden request. value: name: NOT_AUTHORIZED debug_id: b1d1f06c7246c message: Authorization failed due to insufficient permissions. 500_error_response: description: Internal Server Error. content: application/json: schema: $ref: '#/components/schemas/error' examples: generic: summary: Generic internal server error. description: >- Example response for a request that fails for reasons internal to the server. value: name: INTERNAL_SERVER_ERROR debug_id: b1d1f06c7246c message: An internal server error has occurred. default_response: description: Default response. content: application/json: schema: $ref: '#/components/schemas/error' examples: generic: summary: Default response. description: >- Example catch all response, should not be encountered in practice. value: name: INTERNAL_SERVER_ERROR debug_id: b1d1f06c7246c message: An internal server error has occurred. securitySchemes: Oauth2: type: oauth2 description: Oauth 2.0 authentication flows: clientCredentials: tokenUrl: https://api-m.paypal.com/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/deprecating-jssdk-migration-for-limited-merchants: >- Allows client-side integration on Create, Get, Patch, Authorize & Capture Order endpoints. https://uri.paypal.com/services/payments/orders/client_sdk_orders_api: >- Enables secure client-side integration on confirm payment source endpoint https://uri.paypal.com/services/payments/orders/provision-card: Manage card provisioning merchants. ````