Purchase Unit Request

November 13, 2025 · View on GitHub

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

Structure

PurchaseUnitRequest

Fields

NameTypeTagsDescriptionGetterSetter
ReferenceIdStringOptionalThe 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.

Constraints: Minimum Length: 1, Maximum Length: 256		String getReferenceId()setReferenceId(String referenceId)
AmountAmountWithBreakdownRequiredThe 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.AmountWithBreakdown getAmount()setAmount(AmountWithBreakdown amount)
PayeePayeeBaseOptionalThe merchant who receives the funds and fulfills the order. The merchant is also known as the payee.PayeeBase getPayee()setPayee(PayeeBase payee)
PaymentInstructionPaymentInstructionOptionalAny additional payment instructions to be consider during payment processing. This processing instruction is applicable for Capturing an order or Authorizing an Order.PaymentInstruction getPaymentInstruction()setPaymentInstruction(PaymentInstruction paymentInstruction)
DescriptionStringOptionalThis 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.

Constraints: Minimum Length: 1, Maximum Length: 3000		String getDescription()setDescription(String description)
CustomIdStringOptionalThe 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.

Constraints: Minimum Length: 1, Maximum Length: 255		String getCustomId()setCustomId(String customId)
InvoiceIdStringOptionalThe 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.

Constraints: Minimum Length: 1, Maximum Length: 127		String getInvoiceId()setInvoiceId(String invoiceId)
SoftDescriptorStringOptionalThis 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.

Constraints: Minimum Length: 1, Maximum Length: 1000		String getSoftDescriptor()setSoftDescriptor(String softDescriptor)
ItemsList<ItemRequest>OptionalAn array of items that the customer purchases from the merchant.List getItems()setItems(List items)
ShippingShippingDetailsOptionalThe shipping details.ShippingDetails getShipping()setShipping(ShippingDetails shipping)
SupplementaryDataSupplementaryDataOptionalSupplementary 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.SupplementaryData getSupplementaryData()setSupplementaryData(SupplementaryData supplementaryData)

Example (as JSON)

{
  "reference_id": "reference_id6",
  "amount": {
    "currency_code": "currency_code6",
    "value": "value0",
    "breakdown": {
      "item_total": {
        "currency_code": "currency_code0",
        "value": "value6"
      },
      "shipping": {
        "currency_code": "currency_code0",
        "value": "value6"
      },
      "handling": {
        "currency_code": "currency_code2",
        "value": "value8"
      },
      "tax_total": {
        "currency_code": "currency_code4",
        "value": "value0"
      },
      "insurance": {
        "currency_code": "currency_code2",
        "value": "value8"
      }
    }
  },
  "payee": {
    "email_address": "email_address4",
    "merchant_id": "merchant_id6"
  },
  "payment_instruction": {
    "platform_fees": [
      {
        "amount": {
          "currency_code": "currency_code6",
          "value": "value0"
        },
        "payee": {
          "email_address": "email_address4",
          "merchant_id": "merchant_id6"
        }
      },
      {
        "amount": {
          "currency_code": "currency_code6",
          "value": "value0"
        },
        "payee": {
          "email_address": "email_address4",
          "merchant_id": "merchant_id6"
        }
      },
      {
        "amount": {
          "currency_code": "currency_code6",
          "value": "value0"
        },
        "payee": {
          "email_address": "email_address4",
          "merchant_id": "merchant_id6"
        }
      }
    ],
    "disbursement_mode": "INSTANT",
    "payee_pricing_tier_id": "payee_pricing_tier_id2",
    "payee_receivable_fx_rate_id": "payee_receivable_fx_rate_id0"
  },
  "description": "description6",
  "custom_id": "custom_id4"
}