PayPalCart

Unified cart object used for all operations (create, update, checkout, responses). This is the core schema that makes the API simple and consistent.

Request Usage: Include only writable fields (items, customer, shipping_address, billing_address, etc.) Response Usage: Includes all fields, with server-calculated fields marked as readOnly

validation_statusenumOptional

Cart data validation status indicating whether the cart can proceed to checkout. **VALID**: Cart data is complete and valid, ready for checkout - All items are available with current pricing - Required information is complete (shipping address, customer data) - No business rule violations - validation_issues array is empty - Can proceed directly to checkout **INVALID**: Cart has data issues that prevent checkout - Items out of stock, price changes, business rule violations - Invalid or incomplete data that needs correction - validation_issues array contains specific problems - Customer/AI agent must resolve issues before checkout **REQUIRES_ADDITIONAL_INFORMATION**: Cart needs more data but is otherwise valid - Missing optional but required fields (shipping address, checkout fields) - Age verification, custom fields, delivery preferences needed - Items and pricing are valid, just needs customer input - validation_issues array indicates what information is needed

Value in"VALID" | "INVALID" | "REQUIRES_ADDITIONAL_INFORMATION"

validation_issuesobject<ValidationIssue>[]Optional

List of issues preventing checkout (empty = ready)

ValidationIssue properties

8 properties

messagestringRequired

Technical message for developers and logging

user_messagestringOptional

Customer-friendly message for end users

contextobject<6 types>Optional

Category-specific context information

One of the following types

6 types

InventoryIssueContext

Context for inventory and stock-related issues

PricingErrorContext

Context for pricing and financial issues

ShippingErrorContext

Context for shipping and address issues

PaymentErrorContext

Context for payment processing issues

DataErrorContext

Context for data validation issues

BusinessRuleErrorContext

Context for business logic violations

resolution_optionsobject<ResolutionOption>[]Optional

Available actions to resolve this issue

totalsobject<CartTotals>Optional

Comprehensive cart pricing breakdown calculated by merchant and returned in all cart responses. All fields are merchant-owned and calculated based on business logic, inventory, shipping rules, and tax regulations. **Merchant Responsibility:** - Calculate all totals based on items, shipping address, and business rules - Ensure accuracy for tax compliance and customer transparency - Handle currency consistency across all money fields - Apply discounts, shipping rates, and custom charges appropriately **Field Calculation Guidelines:** - **subtotal**: Sum of all item prices × quantities (before discounts) - **discount**: Total amount saved from coupons, promotions, and discounts - **shipping**: Calculated shipping cost based on address and selected method - **tax**: Sales tax, VAT, or other applicable taxes based on billing/shipping jurisdiction - **handling**: Processing fees, packaging costs, or handling charges - **insurance**: Optional shipping insurance costs - **shipping_discount**: Discounts applied specifically to shipping costs - **custom_charges**: Additional fees like gift wrapping, expedited processing, etc. - **total**: Final amount customer pays (subtotal - discount + shipping + tax + handling + insurance - shipping_discount + custom_charges) **PayPal Orders API Integration:** When creating PayPal orders, custom_charges are typically rolled into the handling field or added as separate line items. The total amount must match the PayPal order total for successful payment capture. Fields map to PayPal Orders API breakdown structure where supported.

CartTotals properties

9 properties

subtotalobject<Money>Optional

Sum of all item prices multiplied by quantities before any discounts are applied. This represents the base cost of all products in the cart. **Calculation:** Σ(item.price.value × item.quantity) for all items

discountobject<Money>Optional

Total amount saved from all applied discounts, coupons, and promotions. This should be a positive value representing savings to the customer. **Includes:** Coupon discounts, promotional offers, loyalty program savings, bulk discounts

shippingobject<Money>Optional

Cost of shipping the order to the customer's shipping address. Based on selected shipping method, package weight/dimensions, and destination. **Calculation factors:** Shipping method, distance, package size, delivery speed

taxobject<Money>Optional

Sales tax, VAT, or other applicable taxes based on billing/shipping jurisdiction. Calculated according to local tax regulations and product tax categories. **Tax basis:** Usually applied to (subtotal - discount + shipping) depending on local laws

handlingobject<Money>Optional

Processing fees, packaging costs, or handling charges for order fulfillment. **PayPal Orders API:** Maps directly to the handling field in PayPal's order breakdown. **Common uses:** Processing fees, packaging materials, order handling costs

insuranceobject<Money>Optional

Optional shipping insurance costs to protect against loss or damage during transit. **PayPal Orders API:** Maps directly to the insurance field in PayPal's order breakdown. **Typical usage:** High-value orders, fragile items, international shipping

shipping_discountobject<Money>Optional

Discounts applied specifically to shipping costs (free shipping promotions, etc.). This should be a positive value representing shipping savings to the customer. **PayPal Orders API:** Maps directly to the shipping_discount field in PayPal's order breakdown. **Examples:** Free shipping promotions, reduced shipping rates, shipping coupons

custom_chargesobject<Money>Optional

Sum of all custom charges (gift wrap, processing fees, expedited handling, etc.). **PayPal Orders API Note:** This field doesn't map directly to PayPal Orders API breakdown. When creating PayPal orders, these charges are typically: - Rolled into the handling field, or - Added as separate line items in the order Merchants should ensure the total amount includes custom_charges for payment accuracy.

totalobject<Money>Required

Final amount the customer will pay. This is the sum of all charges minus all discounts. **Formula:** subtotal - discount + shipping + tax + handling + insurance - shipping_discount + custom_charges **PayPal Orders API:** Must match the total amount in the PayPal order for successful payment capture. **Critical:** This is the amount that will be charged to the customer's payment method.

applied_couponsobject<AppliedCoupon>[]Optional

Successfully applied coupons (server-calculated)

available_shipping_optionsobject<ShippingOption>[]Optional

Available shipping methods with selection state

itemsobject<CartItem>[]Optional

Products in the cart

Items1 <= length <= ∞

CartItem properties

11 properties

descriptionstringOptional

Product description

priceobject<Money>Optional

Monetary amount with currency

gift_optionsobject<GiftOptions>Optional

Gift-specific options

customerobject<Customer>Optional

Represents customer information for the shopping cart.

Customer properties

3 properties

nameobject<object>Optional

The name of the payer. Supports only the given_name and surname properties.

phoneobject<Phone>Optional

The phone number in its canonical international E.164 numbering plan format.

email_addressstringOptional

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.

Match^(?:[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])+)\])$Length3 <= length <= 254

shipping_addressobject<ShippingAddress>Optional

International shipping address for cart delivery.

billing_addressobject<BillingAddress>Optional

Billing address for merchant business purposes, obtained from customer's PayPal profile. Similar to shipping addresses, billing addresses can be retrieved from customer's default address information stored in their PayPal account. **When Billing Address is Available:** - Customer has a default billing address in their PayPal profile - PayPal Credit and Buy Now Pay Later transactions - Guest checkout with credit/debit cards - User explicitly consents to address sharing - Required for tax compliance and regulatory reporting **Primary Use Cases:** - **Tax calculation**: Sales tax/VAT rates determined by billing jurisdiction - **Export compliance**: Product restrictions based on customer's billing country - **Financial reporting**: Accounting systems requiring customer billing location - **Address verification**: Comparing billing vs shipping addresses for fraud prevention **Secondary Use Cases:** - **Business intelligence**: Customer demographics and market analysis - **B2B invoicing**: Legal invoices requiring customer billing details - **Compliance reporting**: Regulatory requirements based on customer location **Note**: Payment verification (AVS) and chargeback protection are handled by PayPal internally. **Implementation Notes:** - Billing address is typically available from customer profile data - Can be populated during cart creation if customer provides it - Falls back to shipping address when billing address is not specified - Merchants should handle graceful fallback scenarios

payment_methodobject<PaymentMethod>Optional

Payment method information for PayPal Cart API. This API is specifically designed for PayPal's shopping cart service, so only PayPal payment methods are supported. **Payment Flow:** 1. Cart creation generates a payment token (in payment_method.token) 2. Customer completes PayPal approval (Smart Wallet) 3. PayPal provides token and payer_id for checkout 4. Merchant receives PayPal payment confirmation **Billing Address Behavior:** - PayPal handles all billing address collection internally for payment processing - Merchants can optionally collect billing addresses for tax calculation and business purposes - Billing address in cart is for merchant use cases, not payment requirements - Billing addresses are typically available from customer profile data **Note:** Other payment methods (credit cards, Apple Pay, etc.) would be handled by separate merchant payment systems outside of this PayPal Cart API.

checkout_fieldsobject<CheckoutField>[]Optional

Custom checkout fields (age verification, etc.)

CheckoutField properties

5 properties

statusenumRequired

Field completion and validation status: **PENDING**: Field needs customer input - Initial state when field is required - AI agent should collect this information - value field is null or empty **COMPLETED**: Valid value provided and accepted - Customer provided acceptable input - Value passes all validation rules - Cart can proceed with this field resolved **REJECTED**: Invalid or unacceptable value provided - Customer provided input that doesn't meet requirements - validation_issue explains the specific problem - AI agent should request corrected input **ERROR**: System error during processing - Technical failure in field processing - Should retry or escalate to support - Not caused by customer input

Value in"PENDING" | "COMPLETED" | "REJECTED" | "ERROR"

valueobject<11 types>Optional

Structured value based on field type. Each checkout field type has a specific value schema. Use oneOf to validate against the appropriate structure for the field type.

One of the following types

11 types

GiftMessageValue

Gift message content

CustomEngravingTextValue

Custom engraving text specification

CustomSizingInfoValue

Custom sizing measurements

contextobjectOptional

Additional context and metadata for the checkout field. This is a flexible object that can contain any field-specific information needed for validation, display, or processing. The structure varies based on the field type.

validation_issueobject<ValidationIssue>Optional

Associated validation issue when status is REJECTED or ERROR. Provides detailed information about why the field value was not accepted. **When present:** - status is REJECTED: Customer input didn't meet requirements - status is ERROR: System error processing the field **When null:** - status is PENDING: No validation attempted yet - status is COMPLETED: Validation passed successfully

ValidationIssue properties

8 properties

messagestringRequired

Technical message for developers and logging

user_messagestringOptional

Customer-friendly message for end users

contextobject<6 types>Optional

Category-specific context information

One of the following types

6 types

InventoryIssueContext

Context for inventory and stock-related issues

PricingErrorContext

Context for pricing and financial issues

ShippingErrorContext

Context for shipping and address issues

PaymentErrorContext

Context for payment processing issues

DataErrorContext

Context for data validation issues

BusinessRuleErrorContext

Context for business logic violations

resolution_optionsobject<ResolutionOption>[]Optional

Available actions to resolve this issue

geo_coordinatesobject<GeoCoordinates>Optional

Optional precise location coordinates for enhanced delivery services

On this page

We currently use cookies to improve and customize your experience on our site. If you accept, we’ll also use marketing cookies to show you personalized ads. Manage your cookies and learn more.

ValidationIssue properties

One of the following types

InventoryIssueContext properties

PricingErrorContext properties

object properties

ShippingErrorContext properties

object properties

PaymentErrorContext properties

DataErrorContext properties

BusinessRuleErrorContext properties

object properties

ResolutionOption properties

object properties

CartTotals properties

Money properties

Money properties

Money properties

Money properties

Money properties

Money properties

Money properties

Money properties

Money properties

AppliedCoupon properties

Money properties

ShippingOption properties

Money properties

CartItem properties

Money properties

object properties

GiftOptions properties

object properties

object properties

Customer properties

object properties

Phone properties

ShippingAddress properties

BillingAddress properties

PaymentMethod properties

CheckoutField properties

One of the following types

AgeVerificationValue properties

GiftRecipientEmailValue properties

GiftRecipientNameValue properties

GiftMessageValue properties

DeliveryInstructionsValue properties

DeliveryDatePreferenceValue properties

AllergyInformationValue properties

CustomEngravingTextValue properties

CustomSizingInfoValue properties

object properties

TermsAcceptanceValue properties

PrivacyConsentValue properties

ValidationIssue properties

One of the following types

InventoryIssueContext properties

PricingErrorContext properties

object properties

ShippingErrorContext properties

object properties

PaymentErrorContext properties

DataErrorContext properties

BusinessRuleErrorContext properties

object properties

ResolutionOption properties

object properties

Coupon properties

GeoCoordinates properties

Back to top

On this page