Purchase Unit

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "#/components/schemas/purchase_unit",
  "title": "Purchase Unit",
  "type": "object",
  "description": "The purchase unit details. Used to capture required information for the payment contract.",
  "properties": {
    "reference_id": {
      "type": "string",
      "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`. <blockquote><strong>Note:</strong> If there are multiple purchase units, <code>reference_id</code> is required for each purchase unit.</blockquote>",
      "minLength": 1,
      "maxLength": 256
    },
    "amount": {
      "$ref": "#/components/schemas/amount_with_breakdown"
    },
    "payee": {
      "description": "The merchant who receives payment for this transaction.",
      "$ref": "#/components/schemas/payee"
    },
    "payment_instruction": {
      "$ref": "#/components/schemas/payment_instruction"
    },
    "description": {
      "type": "string",
      "description": "The purchase description.",
      "minLength": 1,
      "maxLength": 127
    },
    "custom_id": {
      "type": "string",
      "description": "The API caller-provided external ID. Used to reconcile API caller-initiated transactions with PayPal transactions. Appears in transaction and settlement reports.",
      "minLength": 1,
      "maxLength": 127
    },
    "invoice_id": {
      "type": "string",
      "description": "The API caller-provided external invoice ID for this order.",
      "minLength": 1,
      "maxLength": 127
    },
    "id": {
      "type": "string",
      "description": "The PayPal-generated ID for the purchase unit. This ID appears in both the payer's transaction history and the emails that the payer receives. In addition, this ID is available in transaction and settlement reports that merchants and API callers can use to reconcile transactions. This ID is only available when an order is saved by calling <code>v2/checkout/orders/id/save</code>.",
      "minLength": 1,
      "maxLength": 19
    },
    "soft_descriptor": {
      "type": "string",
      "description": "The payment descriptor on account transactions on the customer's credit card statement, that PayPal sends to processors. The maximum length of the soft descriptor information that you can pass in the API field is 22 characters, in the following format:<code>22 - len(PAYPAL * (8)) - len(<var>Descriptor in Payment Receiving Preferences of Merchant account</var> + 1)</code>The PAYPAL prefix uses 8 characters.<br/><br/>The soft descriptor supports the following ASCII characters:<ul><li>Alphanumeric characters</li><li>Dashes</li><li>Asterisks</li><li>Periods (.)</li><li>Spaces</li></ul>For Wallet payments marketplace integrations:<ul><li>The merchant descriptor in the Payment Receiving Preferences must be the marketplace name.</li><li>You can't use the remaining space to show the customer service number.</li><li>The remaining spaces can be a combination of seller name and country.</li></ul><br/>For unbranded payments (Direct Card) marketplace integrations, use a combination of the seller name and phone number.",
      "minLength": 1,
      "maxLength": 22
    },
    "items": {
      "type": "array",
      "description": "An array of items that the customer purchases from the merchant.",
      "items": {
        "description": "An item.",
        "$ref": "#/components/schemas/item"
      }
    },
    "shipping": {
      "description": "The shipping address and method.",
      "$ref": "#/components/schemas/shipping_with_tracking_details"
    },
    "supplementary_data": {
      "description": "Supplementary data about this payment. Merchants and partners can add Level 2 and 3 data to payments to reduce risk and payment processing costs. For more information about processing payments, see <a href=\"https://developer.paypal.com/docs/checkout/advanced/processing/\">checkout</a> or <a href=\"https://developer.paypal.com/docs/multiparty/checkout/advanced/processing/\">multiparty checkout</a>.",
      "$ref": "#/components/schemas/supplementary_data"
    },
    "payments": {
      "description": "The comprehensive history of payments for the purchase unit.",
      "readOnly": true,
      "$ref": "#/components/schemas/payment_collection"
    }
  }
}