Purchase Unit Request

The purchase unit request. Includes required information for the payment contract.

amountobject<amount_with_breakdown>Required

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.

amount_with_breakdown properties

3 properties

payeeobject<payee>Optional

The merchant who receives the funds and fulfills the order. The merchant is also known as the payee.

payment_instructionobject<payment_instruction>Optional

Any additional payment instructions to be consider during payment processing. This processing instruction is applicable for Capturing an order or Authorizing an Order.

payment_instruction properties

4 properties

platform_feesobject<platform_fee>[]Optional

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.

Items0 <= length <= 1

descriptionstringOptional

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.

Match^[\S\s]*$Length1 <= length <= 3000

invoice_idstringOptional

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.

Match^[\S\s]*$Length1 <= length <= 127

soft_descriptorstringOptional

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:

The PayPal prefix toggle is PAYPAL *.
The merchant descriptor in the profile is Janes Gift.
The soft descriptor is 800-123-1234.

Then, the statement descriptor on the card is PAYPAL * Janes Gift 80.

Match^[\S\s]*$Length1 <= length <= 1000

On this page

If you accept cookies, we’ll use them to improve and customize your experience and enable our partners to show you personalized PayPal ads when you visit other sites. Manage cookies and learn more

Purchase Unit Request

amount_with_breakdown properties

amount_breakdown properties

money properties

money properties

money properties

money properties

money properties

money properties

discount_with_breakdown properties

payee properties

payment_instruction properties

platform_fee properties

money properties

payee_base properties

item_request properties

money properties

money properties

universal_product_code properties

order_billing_plan properties

billing_cycle properties

pricing_scheme properties

money properties

money properties

money properties

shipping_detail properties

name properties

phone properties

shipping_option properties

money properties

address_portable properties

Address Details properties

supplementary_data properties

card_supplementary_data properties

level_2_card_processing_data properties

money properties

level_3_card_processing_data properties

money properties

money properties

money properties

address_portable properties

Address Details properties

line_item properties

universal_product_code properties

order_billing_plan properties

billing_cycle properties

pricing_scheme properties

money properties

money properties

money properties

money properties

money properties

money properties

money properties

risk_supplementary_data properties

participant_metadata properties

Back to top

On this page