On this page
No Headings
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
objectidstringUnique cart identifier (server-generated)
statusstring"CREATED", "INCOMPLETE", "READY", "COMPLETED"Current cart business status (server-calculated)
validation_statusstring"VALID", "INVALID", "REQUIRES_ADDITIONAL_INFORMATION"Cart data validation status indicating whether the cart can proceed to checkout.
VALID: Cart data is complete and valid, ready for checkout
INVALID: Cart has data issues that prevent checkout
REQUIRES_ADDITIONAL_INFORMATION: Cart needs more data but is otherwise valid
validation_issuesarrayList of issues preventing checkout (empty = ready)
itemsobjectBusiness logic issues that allow cart creation but require buyer action to complete payment.
Use Validation Issues when:
Consolidated validation issue system with 6 main error categories and specific context schemas. This approach simplifies error handling while maintaining rich context and resolution options.
Error Categories:
Example - PO Box Shipping Restriction:
{
"code": "SHIPPING_ERROR",
"type": "INVALID_DATA",
"message": "Shipping address validation failed",
"user_message": "We can't ship to PO Box addresses. Please use a street address.",
"field": "shipping_address",
"context": {
"specific_issue": "SHIPPING_TO_PO_BOX_NOT_ALLOWED",
"po_box_detected": true,
"restricted_items": ["LARGE-FURNITURE-001"],
"restriction_reason": "oversized_item"
},
"resolution_options": [
{
"action": "UPDATE_ADDRESS",
"label": "Use street address instead of PO Box",
"metadata": {
"priority": "high",
"auto_applicable": false
}
}
]
}
Example - Price Change:
{
"code": "PRICING_ERROR",
"type": "BUSINESS_RULE",
"message": "Product pricing issue",
"user_message": "The price for Ocean Blue T-Shirt has increased from $29.99 to $34.99. Continue with new price?",
"variant_id": "SHIRT-OCEAN-BLUE",
"context": {
"specific_issue": "PRICE_MISMATCH",
"variant_id": "SHIRT-OCEAN-BLUE",
"original_price": "29.99",
"current_price": "34.99",
"currency_code": "USD",
"price_change_reason": "promotional_ended",
"price_increase": "5.00"
},
"resolution_options": [
{
"action": "ACCEPT_NEW_PRICE",
"label": "Continue with $34.99",
"metadata": {
"cost_impact": "+$5.00",
"priority": "HIGH",
"auto_applicable": false
}
}
]
}
Example - Address Validation:
{
"code": "SHIPPING_ERROR",
"type": "INVALID_DATA",
"message": "Shipping address validation failed",
"user_message": "The shipping address appears to be incomplete. Please check and correct.",
"field": "shipping_address.postal_code",
"context": {
"specific_issue": "SHIPPING_ADDRESS_INVALID",
"validation_failures": ["invalid_postal_code"],
"suggested_corrections": {
"postal_code": "90210"
},
"address_quality_score": 0.3
},
"resolution_options": [
{
"action": "UPDATE_ADDRESS",
"label": "Use suggested corrections",
"metadata": {
"priority": "HIGH",
"auto_applicable": true
}
}
]
}
Example - Billing Address for Tax Calculation:
{
"code": "DATA_ERROR",
"type": "MISSING_FIELD",
"message": "Billing address needed for tax calculation",
"user_message": "We need your billing address to calculate the correct sales tax for your order.",
"field": "billing_address",
"context": {
"specific_issue": "BILLING_ADDRESS_FOR_TAX",
"tax_jurisdiction_required": true,
"current_tax_rate": "unknown",
"supported_tax_regions": ["US", "CA", "EU"]
},
"resolution_options": [
{
"action": "PROVIDE_MISSING_FIELD",
"label": "Add billing address",
"metadata": {
"priority": "MEDIUM",
"auto_applicable": false
}
},
{
"action": "USE_SHIPPING_AS_BILLING",
"label": "Same as shipping address",
"metadata": {
"priority": "HIGH",
"auto_applicable": true
}
}
]
}
coderequiredstring"INVENTORY_ISSUE", "PRICING_ERROR", "SHIPPING_ERROR", "PAYMENT_ERROR", "DATA_ERROR", "BUSINESS_RULE_ERROR"Consolidated error category
typerequiredstring"MISSING_FIELD", "INVALID_DATA", "BUSINESS_RULE"Type classification for error handling
messagerequiredstringTechnical message for developers and logging
user_messagestringCustomer-friendly message for end users
variant_idstringSpecific item ID if the issue is item-specific
fieldstringSpecific field name if the issue is field-specific
contextCategory-specific context information
anyOf[0]objectContext for inventory and stock-related issues
specific_issuestring"ITEM_OUT_OF_STOCK", "INSUFFICIENT_INVENTORY", "BACK_ORDERED", "PRE_ORDER_ONLY", "ITEM_DISCONTINUED", "LOW_STOCK_WARNING", "INVENTORY_RESERVED", "SEASONAL_UNAVAILABLE", "VARIANT_NOT_AVAILABLE", "CUSTOM_OPTION_UNAVAILABLE"Specific inventory issue type
item_idstringProduct item identifier
variant_idstringProduct variant identifier if applicable
available_quantityintegerCurrently available quantity
requested_quantityintegerRequested quantity
reserved_quantityintegerQuantity reserved for other transactions
restock_datestringdate-timeExpected restock date
estimated_ship_datestringdate-timeEstimated shipping date for back-orders
back_order_limitintegerMaximum allowed back-order quantity
current_back_ordersintegerCurrent number of back-orders
discontinuation_datestringdate-timeDate product was discontinued
suggested_alternativesarrayAlternative product IDs
itemsstringupgrade_availablebooleanWhether newer version is available
seasonal_start_datestringdate-timeWhen seasonal product becomes available
last_soldstringdate-timeWhen item was last sold
anyOf[1]objectContext for pricing and financial issues
specific_issuestring"PRICE_MISMATCH", "DISCOUNT_EXPIRED", "DISCOUNT_USAGE_LIMIT_EXCEEDED", "DISCOUNT_CUSTOMER_INELIGIBLE", "DISCOUNT_MINIMUM_NOT_MET", "TAX_CALCULATION_FAILED", "CURRENCY_NOT_SUPPORTED", "CURRENCY_MISMATCH", "PROMOTIONAL_CONFLICT"Specific pricing issue type
variant_idstringItem with pricing issue
original_pricestringOriginal price value
current_pricestringCurrent price value
currency_codestringCurrency code
price_change_reasonstring"promotional_ended", "promotional_started", "market_adjustment", "cost_increase", "seasonal_pricing", "component_cost_increase", "terms_updated"Reason for price change
price_increasestringAmount of price increase
price_decreasestringAmount of price decrease
coupon_codestringCoupon code with issues
usage_limitintegerCoupon usage limit
current_usageintegerCurrent coupon usage count
expiration_datestringdate-timeDiscount expiration date
minimum_order_amountstringMinimum order for discount
supported_currenciesarrayList of supported currencies
itemsstringfound_currenciesarrayMultiple currencies found in cart
itemsstringtax_service_errorstringTax calculation service error
current_datestringdate-timeCurrent system date for comparisons
discount_amountstringDiscount amount that was applied
required_currency_consistencybooleanWhether all items must use same currency
mixed_itemsarrayItems with different currencies
itemsobjectvariant_idstringcurrencystringanyOf[2]objectContext for shipping and address issues
specific_issuestring"MISSING_SHIPPING_ADDRESS", "SHIPPING_ADDRESS_INVALID", "SHIPPING_TO_PO_BOX_NOT_ALLOWED", "NO_SHIPPING_OPTIONS", "INTERNATIONAL_SHIPPING_RESTRICTED", "REGION_RESTRICTED", "OVERSIZED_ITEM_SHIPPING", "HAZARDOUS_MATERIAL_SHIPPING", "SHIPPING_ZONE_NOT_COVERED", "MISSING_COORDINATES_FOR_ENHANCED_DELIVERY"Specific shipping issue type
validation_failuresarraySpecific address validation failures
itemsstringsuggested_correctionsobjectSuggested address corrections
postal_codestringaddress_line_1stringadmin_area_2stringaddress_quality_scorenumberAddress validation quality score
restricted_itemsarrayItems with shipping restrictions
itemsstringrestriction_reasonstring"signature_required", "age_verification_required", "export_controlled", "hazardous_material", "oversized_item", "po_box_restriction"Reason for shipping restriction
po_box_detectedbooleanWhether PO Box was detected
destination_countrystringDestination country code
restricted_regionstringRestricted region identifier
supported_countriesarrayList of supported countries
itemsstringprovided_addressstringAddress string that failed validation
anyOf[3]objectContext for payment processing issues
specific_issuestring"PAYMENT_AMOUNT_TOO_LARGE", "PAYMENT_AMOUNT_TOO_SMALL", "PAYMENT_METHOD_NOT_ACCEPTED", "CURRENCY_CONVERSION_FAILED", "PAYMENT_PROCESSOR_UNAVAILABLE", "MERCHANT_ACCOUNT_ISSUE", "PAYMENT_DECLINED", "PAYMENT_INSUFFICIENT_FUNDS", "PAYMENT_EXPIRED", "PAYMENT_FRAUD_DETECTED"Specific payment issue type
order_totalstringTotal order amount
payment_limitstringMaximum payment limit
minimum_amountstringMinimum payment amount
excess_amountstringAmount exceeding limit
payment_methodstringPayment method being used
currency_codestringTransaction currency
from_currencystringSource currency for conversion
to_currencystringTarget currency for conversion
conversion_servicestringCurrency conversion service status
supported_payment_methodsarrayList of supported payment methods
itemsstringprocessor_error_codestringPayment processor specific error code
decline_reasonstringReason for payment decline
payment_tokenstringPayment token that was declined
anyOf[4]objectContext for data validation issues
specific_issuestring"MISSING_CHECKOUT_FIELDS", "MISSING_PAYMENT_METHOD", "MISSING_POLICY_ACCEPTANCE", "REQUIRED_FIELD_MISSING", "INVALID_EMAIL_FORMAT", "INVALID_PHONE_FORMAT", "FIELD_VALUE_TOO_LONG", "FIELD_VALUE_TOO_SHORT", "INVALID_DATE_FORMAT", "FUTURE_DATE_NOT_ALLOWED", "INVALID_CUSTOMER_DATA", "ITEM_NOT_FOUND", "INVALID_ITEM_DATA", "ITEM_ATTRIBUTE_MISMATCH"Specific data validation issue type
field_namestringName of the field with validation error
provided_valuestringValue that failed validation
expected_formatstringExpected format description
max_lengthintegerMaximum allowed length
min_lengthintegerMinimum required length
current_lengthintegerCurrent value length
regex_patternstringRequired regex pattern
suggested_valuestringSuggested corrected value
allowed_valuesarrayList of allowed values for enum fields
itemsstringrequired_fieldsarrayList of required field names
itemsstringfield_descriptionsobjectDescriptions for required fields
anyOf[5]objectContext for business logic violations
specific_issuestring"MINIMUM_ORDER_NOT_MET", "MINIMUM_QUANTITY_NOT_MET", "MAXIMUM_QUANTITY_EXCEEDED", "CART_LIMIT_EXCEEDED", "CUSTOMER_ACCOUNT_SUSPENDED", "PURCHASE_LIMIT_EXCEEDED", "BULK_ORDER_APPROVAL_REQUIRED", "STORE_TEMPORARILY_CLOSED", "AGE_RESTRICTED_PRODUCT", "LOYALTY_PROGRAM_VALIDATION_FAILED", "BUSINESS_HOURS_RESTRICTION", "PRODUCT_ARCHIVED"Specific business rule issue type
current_amountstringCurrent order amount
required_amountstringRequired minimum amount
maximum_amountstringMaximum allowed amount
remaining_amountstringAmount needed to meet minimum
account_statusstringCustomer account status
suspension_reasonstringReason for account suspension
suspension_datestringdate-timeDate of account suspension
monthly_limitstringMonthly purchase limit
current_month_totalstringCurrent month purchase total
reset_datestringdate-timeWhen limits reset
total_quantityintegerTotal quantity in bulk order
approval_thresholdintegerQuantity requiring approval
maintenance_end_timestringdate-timeWhen maintenance ends
service_statusstringCurrent service status
retry_afterintegerSeconds before retry recommended
contact_infostringSupport contact information
restricted_itemsarrayItems with restrictions
itemsstringage_requirementintegerRequired minimum age
business_hoursobjectStore business hours
open_timestringclose_timestringtimezonestringshortage_amountstringAmount needed to meet minimum requirements
exceeds_bystringAmount by which limit is exceeded
resolution_optionsarrayAvailable actions to resolve this issue
itemsobjectAvailable action to resolve a validation issue
actionrequiredstring"REDIRECT_TO_MERCHANT", "MODIFY_CART", "ACCEPT_NEW_PRICE", "ACCEPT_BACK_ORDER", "SUGGEST_ALTERNATIVE", "REMOVE_ITEM", "UPDATE_ADDRESS", "PROVIDE_MISSING_FIELD", "USE_DIFFERENT_PAYMENT", "SPLIT_ORDER", "CONTACT_SUPPORT", "RETRY_LATER", "REQUEST_APPROVAL", "WAIT_FOR_RESTOCK", "USE_DIFFERENT_CURRENCY", "ACCEPT_PRE_ORDER", "UPDATE_SHIPPING_METHOD", "ACCEPT_TERMS", "VERIFY_ACCOUNT", "APPLY_DIFFERENT_COUPON", "REMOVE_COUPON", "CHOOSE_DIFFERENT_VARIANT"Machine-readable action identifier
labelrequiredstringHuman-readable action label
urlstringuriURL to redirect to for resolution
metadataobjectAdditional action metadata
cost_impactstringFinancial impact of this action
prioritystring"HIGH", "MEDIUM", "LOW"Priority level for this resolution
auto_applicablebooleanWhether this action can be applied automatically
estimated_timestringEstimated time for resolution
redirect_requiredbooleanWhether this action requires user redirect
totalsobjectComprehensive 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:
Field Calculation Guidelines:
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.
subtotalobjectSum 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
currency_coderequiredstring^[\S\s]*$The 3-character ISO-4217 currency code that identifies the currency.
valuerequiredstring^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$The value, which might be: An integer for currencies like JPY that are not typically fractional. A decimal fraction for currencies like TND that are subdivided into thousandths. For the required number of decimal places for a currency code, see Currency Codes.
discountobjectTotal 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
currency_coderequiredstring^[\S\s]*$The 3-character ISO-4217 currency code that identifies the currency.
valuerequiredstring^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$The value, which might be: An integer for currencies like JPY that are not typically fractional. A decimal fraction for currencies like TND that are subdivided into thousandths. For the required number of decimal places for a currency code, see Currency Codes.
shippingobjectCost 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
currency_coderequiredstring^[\S\s]*$The 3-character ISO-4217 currency code that identifies the currency.
valuerequiredstring^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$The value, which might be: An integer for currencies like JPY that are not typically fractional. A decimal fraction for currencies like TND that are subdivided into thousandths. For the required number of decimal places for a currency code, see Currency Codes.
taxobjectSales 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
currency_coderequiredstring^[\S\s]*$The 3-character ISO-4217 currency code that identifies the currency.
valuerequiredstring^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$The value, which might be: An integer for currencies like JPY that are not typically fractional. A decimal fraction for currencies like TND that are subdivided into thousandths. For the required number of decimal places for a currency code, see Currency Codes.
handlingobjectProcessing 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
currency_coderequiredstring^[\S\s]*$The 3-character ISO-4217 currency code that identifies the currency.
valuerequiredstring^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$The value, which might be: An integer for currencies like JPY that are not typically fractional. A decimal fraction for currencies like TND that are subdivided into thousandths. For the required number of decimal places for a currency code, see Currency Codes.
insuranceobjectOptional 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
currency_coderequiredstring^[\S\s]*$The 3-character ISO-4217 currency code that identifies the currency.
valuerequiredstring^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$The value, which might be: An integer for currencies like JPY that are not typically fractional. A decimal fraction for currencies like TND that are subdivided into thousandths. For the required number of decimal places for a currency code, see Currency Codes.
shipping_discountobjectDiscounts 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
currency_coderequiredstring^[\S\s]*$The 3-character ISO-4217 currency code that identifies the currency.
valuerequiredstring^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$The value, which might be: An integer for currencies like JPY that are not typically fractional. A decimal fraction for currencies like TND that are subdivided into thousandths. For the required number of decimal places for a currency code, see Currency Codes.
custom_chargesobjectSum 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:
Merchants should ensure the total amount includes custom_charges for payment accuracy.
currency_coderequiredstring^[\S\s]*$The 3-character ISO-4217 currency code that identifies the currency.
valuerequiredstring^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$The value, which might be: An integer for currencies like JPY that are not typically fractional. A decimal fraction for currencies like TND that are subdivided into thousandths. For the required number of decimal places for a currency code, see Currency Codes.
totalrequiredobjectFinal 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.
currency_coderequiredstring^[\S\s]*$The 3-character ISO-4217 currency code that identifies the currency.
valuerequiredstring^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$The value, which might be: An integer for currencies like JPY that are not typically fractional. A decimal fraction for currencies like TND that are subdivided into thousandths. For the required number of decimal places for a currency code, see Currency Codes.
applied_couponsarraySuccessfully applied coupons (server-calculated)
itemsobjectSuccessfully applied coupon
codestringdescriptionstringdiscount_amountobjectMonetary amount with currency
currency_coderequiredstring^[\S\s]*$The 3-character ISO-4217 currency code that identifies the currency.
valuerequiredstring^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$The value, which might be: An integer for currencies like JPY that are not typically fractional. A decimal fraction for currencies like TND that are subdivided into thousandths. For the required number of decimal places for a currency code, see Currency Codes.
available_shipping_optionsarrayAvailable shipping methods with selection state
itemsobjectAvailable shipping method with selection state
idrequiredstringUnique shipping option identifier
namerequiredstringDisplay name
descriptionstringDetailed description
pricerequiredobjectMonetary amount with currency
currency_coderequiredstring^[\S\s]*$The 3-character ISO-4217 currency code that identifies the currency.
valuerequiredstring^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$The value, which might be: An integer for currencies like JPY that are not typically fractional. A decimal fraction for currencies like TND that are subdivided into thousandths. For the required number of decimal places for a currency code, see Currency Codes.
is_selectedrequiredbooleanWhether this shipping option is currently selected
estimated_deliverystringdate^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])$Estimated delivery date in YYYY-MM-DD format
itemsarrayProducts in the cart
itemsobjectProduct item for cart creation/updates
item_idstringUnique product identifier (DEPRECATED - optional in v1 for backwards compatibility)
variant_idstringProduct variant identifier (color, size, etc.) - unique id of the product
parent_idstringItem grouping identifier - passed when item is part of a group in product catalog
quantityrequiredintegerNumber of items
namestringProduct display name
descriptionstringProduct description
item_urlstringuriURL for product details page
priceobjectMonetary amount with currency
currency_coderequiredstring^[\S\s]*$The 3-character ISO-4217 currency code that identifies the currency.
valuerequiredstring^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$The value, which might be: An integer for currencies like JPY that are not typically fractional. A decimal fraction for currencies like TND that are subdivided into thousandths. For the required number of decimal places for a currency code, see Currency Codes.
selected_attributesarraySelected product attributes
itemsobjectnamestringvaluestringgift_optionsobjectGift-specific options
is_giftbooleanWhether this is a gift
recipientobjectGift recipient information
namestringemailstringemailphonestringdelivery_datestringdate-time^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])[T,t]([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)([.][0-9]+)?([Zz]|[+-][0-9]{2}:[0-9]{2})$Scheduled delivery date in RFC3339 format. Seconds are required while fractional seconds are optional.
sender_namestringName of gift sender
gift_messagestringPersonal message (max 500 characters)
gift_wrapbooleanWhether to include gift wrapping
custom_optionsarrayCustom product options
itemsobjectnamestringvaluestringprice_modifierstringAdditional cost for this option
customerobjectRepresents customer information for the shopping cart.
nameobjectThe name of the payer. Supports only the given_name and surname properties.
given_namestring^.*$When the party is a person, the party's given, or first, name.
surnamestring^.*$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.
phoneobjectThe phone number in its canonical international E.164 numbering plan format.
country_coderequiredstring^[0-9]{1,3}?$The country calling code (CC), in its canonical international E.164 numbering plan format. 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).
national_numberrequiredstring^[0-9]{1,14}?$The national number, in its canonical international E.164 numbering plan format. 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).
extension_numberstring^[0-9]{1,15}?$The extension number.
email_addressstring^(?:[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])+)\])$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.
shipping_addressobjectInternational shipping address for cart delivery.
address_line_1string^.*$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.
address_line_2string^.*$The second line of the address, for example, a suite or apartment number.
admin_area_2string^.*$A city, town, or village. Smaller than admin_area_level_1.
admin_area_1string^.*$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 UK. A county. US. A state. Canada. A province. Japan. A prefecture. Switzerland. A kanton.
postal_codestring^.*$The postal code, which is the ZIP code or equivalent. Typically required for countries with a postal code or an equivalent. See postal code.
country_coderequiredstring^[A-Z]{2}$The 2-character ISO 3166-1 alpha-2 country code
billing_addressobjectBilling 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:
Primary Use Cases:
Secondary Use Cases:
Note: Payment verification (AVS) and chargeback protection are handled by PayPal internally.
Implementation Notes:
address_line_1string^.*$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.
address_line_2string^.*$The second line of the address, for example, a suite or apartment number.
admin_area_2string^.*$A city, town, or village. Smaller than admin_area_level_1.
admin_area_1string^.*$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 UK. A county. US. A state. Canada. A province. Japan. A prefecture. Switzerland. A kanton.
postal_codestring^.*$The postal code, which is the ZIP code or equivalent. Typically required for countries with a postal code or an equivalent. See postal code.
country_coderequiredstring^[A-Z]{2}$The 2-character ISO 3166-1 alpha-2 country code
payment_methodobjectPayment 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:
Billing Address Behavior:
Note: Other payment methods (credit cards, Apple Pay, etc.) would be handled by separate merchant payment systems outside of this PayPal Cart API.
typerequiredstring"paypal"Payment method type - only PayPal is supported by this API
tokenstringPayPal payment token from cart creation or customer approval
payer_idstringPayPal payer identifier provided after customer approval
approval_urlstringuriURL used to inform merchant that the PayPal buyer approved the order
checkout_fieldsarrayCustom checkout fields (age verification, etc.)
itemsobjectPayPal-controlled checkout field for buyer data collection with structured values and validation.
Field Lifecycle:
Structured Values: Each field type has a specific value schema based on its requirements. Age verification uses boolean confirmation, text fields use strings, etc.
typerequiredstring"AGE_VERIFICATION_18_PLUS", "AGE_VERIFICATION_21_PLUS", "GIFT_RECIPIENT_EMAIL", "GIFT_RECIPIENT_NAME", "GIFT_MESSAGE", "DELIVERY_INSTRUCTIONS", "DELIVERY_DATE_PREFERENCE", "ALLERGY_INFORMATION", "CUSTOM_ENGRAVING_TEXT", "CUSTOM_SIZING_INFO", "TERMS_ACCEPTANCE", "PRIVACY_CONSENT"PayPal-approved checkout field type
statusrequiredstring"PENDING", "COMPLETED", "REJECTED", "ERROR"Field completion and validation status:
PENDING: Field needs customer input
COMPLETED: Valid value provided and accepted
REJECTED: Invalid or unacceptable value provided
ERROR: System error during processing
valueStructured 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.
oneOf[0]objectAge verification confirmation value
typerequiredstring"AGE_VERIFICATION_18_PLUS", "AGE_VERIFICATION_21_PLUS"This should match the CheckField type.
confirmedrequiredbooleanWhether age verification was confirmed
verification_methodstring"self_declaration", "id_verification", "third_party"Method used for age verification
verification_datestringdate-timeWhen verification was completed
oneOf[1]objectGift recipient email information
typerequiredstring"GIFT_RECIPIENT_EMAIL"This should match the CheckField type.
emailrequiredstringemailRecipient's email address
verifiedbooleanWhether email was verified
oneOf[2]objectGift recipient name information
typerequiredstring"GIFT_RECIPIENT_NAME"This should match the CheckField type.
namerequiredstringRecipient's full name
first_namestringRecipient's first name
last_namestringRecipient's last name
oneOf[3]objectGift message content
typerequiredstring"GIFT_MESSAGE"This should match the CheckField type.
messagerequiredstringPersonal message for the recipient
sender_namestringName of the person sending the gift
oneOf[4]objectSpecial delivery instructions
typerequiredstring"DELIVERY_INSTRUCTIONS"This should match the CheckField type.
instructionsrequiredstringSpecial delivery instructions
access_codestringBuilding or gate access code
contact_phonestringContact phone for delivery
oneOf[5]objectPreferred delivery date and time
typerequiredstring"DELIVERY_DATE_PREFERENCE"This should match the CheckField type.
preferred_datestringdatePreferred delivery date
time_windowstring"morning", "afternoon", "evening", "anytime"Preferred time window
specific_timestring^([0-1]?[0-9]|2[0-3]):[0-5][0-9]$Specific preferred time (HH:MM format)
oneOf[6]objectAllergy and medical restriction information
typerequiredstring"ALLERGY_INFORMATION"This should match the CheckField type.
allergiesarrayList of known allergies
itemsstringseveritystring"mild", "moderate", "severe", "life_threatening"Allergy severity level
medicationsarrayMedications to avoid
itemsstringemergency_contactstringEmergency contact information
oneOf[7]objectCustom engraving text specification
typerequiredstring"CUSTOM_ENGRAVING_TEXT"This should match the CheckField type.
textrequiredstringText to be engraved
fontstring"arial", "times", "script", "block"Preferred font style
sizestring"small", "medium", "large"Text size preference
positionstring"front", "back", "side", "bottom"Engraving position
oneOf[8]objectCustom sizing measurements
typerequiredstring"CUSTOM_SIZING_INFO"This should match the CheckField type.
measurementsobjectBody measurements
cheststringChest measurement
waiststringWaist measurement
heightstringHeight measurement
weightstringWeight
size_preferencestring"tight", "regular", "loose"Fit preference
special_requirementsstringSpecial sizing requirements
oneOf[9]objectTerms and conditions acceptance
typerequiredstring"TERMS_ACCEPTANCE"This should match the CheckField type.
acceptedrequiredbooleanWhether terms were accepted
terms_versionrequiredstringVersion of terms accepted
acceptance_datestringdate-timeWhen terms were accepted
ip_addressstringIP address of acceptance
oneOf[10]objectPrivacy policy consent
typerequiredstring"PRIVACY_CONSENT"This should match the CheckField type.
consentedrequiredbooleanWhether privacy policy was consented to
consent_typesarrayTypes of consent given
itemsstring"data_processing", "marketing", "third_party_sharing", "analytics"policy_versionstringPrivacy policy version
consent_datestringdate-timeWhen consent was given
contextobjectAdditional 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_issueobjectAssociated validation issue when status is REJECTED or ERROR. Provides detailed information about why the field value was not accepted.
When present:
When null:
coderequiredstring"INVENTORY_ISSUE", "PRICING_ERROR", "SHIPPING_ERROR", "PAYMENT_ERROR", "DATA_ERROR", "BUSINESS_RULE_ERROR"Consolidated error category
typerequiredstring"MISSING_FIELD", "INVALID_DATA", "BUSINESS_RULE"Type classification for error handling
messagerequiredstringTechnical message for developers and logging
user_messagestringCustomer-friendly message for end users
variant_idstringSpecific item ID if the issue is item-specific
fieldstringSpecific field name if the issue is field-specific
contextCategory-specific context information
anyOf[0]objectContext for inventory and stock-related issues
specific_issuestring"ITEM_OUT_OF_STOCK", "INSUFFICIENT_INVENTORY", "BACK_ORDERED", "PRE_ORDER_ONLY", "ITEM_DISCONTINUED", "LOW_STOCK_WARNING", "INVENTORY_RESERVED", "SEASONAL_UNAVAILABLE", "VARIANT_NOT_AVAILABLE", "CUSTOM_OPTION_UNAVAILABLE"Specific inventory issue type
item_idstringProduct item identifier
variant_idstringProduct variant identifier if applicable
available_quantityintegerCurrently available quantity
requested_quantityintegerRequested quantity
reserved_quantityintegerQuantity reserved for other transactions
restock_datestringdate-timeExpected restock date
estimated_ship_datestringdate-timeEstimated shipping date for back-orders
back_order_limitintegerMaximum allowed back-order quantity
current_back_ordersintegerCurrent number of back-orders
discontinuation_datestringdate-timeDate product was discontinued
suggested_alternativesarrayAlternative product IDs
itemsstringupgrade_availablebooleanWhether newer version is available
seasonal_start_datestringdate-timeWhen seasonal product becomes available
last_soldstringdate-timeWhen item was last sold
anyOf[1]objectContext for pricing and financial issues
specific_issuestring"PRICE_MISMATCH", "DISCOUNT_EXPIRED", "DISCOUNT_USAGE_LIMIT_EXCEEDED", "DISCOUNT_CUSTOMER_INELIGIBLE", "DISCOUNT_MINIMUM_NOT_MET", "TAX_CALCULATION_FAILED", "CURRENCY_NOT_SUPPORTED", "CURRENCY_MISMATCH", "PROMOTIONAL_CONFLICT"Specific pricing issue type
variant_idstringItem with pricing issue
original_pricestringOriginal price value
current_pricestringCurrent price value
currency_codestringCurrency code
price_change_reasonstring"promotional_ended", "promotional_started", "market_adjustment", "cost_increase", "seasonal_pricing", "component_cost_increase", "terms_updated"Reason for price change
price_increasestringAmount of price increase
price_decreasestringAmount of price decrease
coupon_codestringCoupon code with issues
usage_limitintegerCoupon usage limit
current_usageintegerCurrent coupon usage count
expiration_datestringdate-timeDiscount expiration date
minimum_order_amountstringMinimum order for discount
supported_currenciesarrayList of supported currencies
itemsstringfound_currenciesarrayMultiple currencies found in cart
itemsstringtax_service_errorstringTax calculation service error
current_datestringdate-timeCurrent system date for comparisons
discount_amountstringDiscount amount that was applied
required_currency_consistencybooleanWhether all items must use same currency
mixed_itemsarrayItems with different currencies
itemsobjectvariant_idstringcurrencystringanyOf[2]objectContext for shipping and address issues
specific_issuestring"MISSING_SHIPPING_ADDRESS", "SHIPPING_ADDRESS_INVALID", "SHIPPING_TO_PO_BOX_NOT_ALLOWED", "NO_SHIPPING_OPTIONS", "INTERNATIONAL_SHIPPING_RESTRICTED", "REGION_RESTRICTED", "OVERSIZED_ITEM_SHIPPING", "HAZARDOUS_MATERIAL_SHIPPING", "SHIPPING_ZONE_NOT_COVERED", "MISSING_COORDINATES_FOR_ENHANCED_DELIVERY"Specific shipping issue type
validation_failuresarraySpecific address validation failures
itemsstringsuggested_correctionsobjectSuggested address corrections
postal_codestringaddress_line_1stringadmin_area_2stringaddress_quality_scorenumberAddress validation quality score
restricted_itemsarrayItems with shipping restrictions
itemsstringrestriction_reasonstring"signature_required", "age_verification_required", "export_controlled", "hazardous_material", "oversized_item", "po_box_restriction"Reason for shipping restriction
po_box_detectedbooleanWhether PO Box was detected
destination_countrystringDestination country code
restricted_regionstringRestricted region identifier
supported_countriesarrayList of supported countries
itemsstringprovided_addressstringAddress string that failed validation
anyOf[3]objectContext for payment processing issues
specific_issuestring"PAYMENT_AMOUNT_TOO_LARGE", "PAYMENT_AMOUNT_TOO_SMALL", "PAYMENT_METHOD_NOT_ACCEPTED", "CURRENCY_CONVERSION_FAILED", "PAYMENT_PROCESSOR_UNAVAILABLE", "MERCHANT_ACCOUNT_ISSUE", "PAYMENT_DECLINED", "PAYMENT_INSUFFICIENT_FUNDS", "PAYMENT_EXPIRED", "PAYMENT_FRAUD_DETECTED"Specific payment issue type
order_totalstringTotal order amount
payment_limitstringMaximum payment limit
minimum_amountstringMinimum payment amount
excess_amountstringAmount exceeding limit
payment_methodstringPayment method being used
currency_codestringTransaction currency
from_currencystringSource currency for conversion
to_currencystringTarget currency for conversion
conversion_servicestringCurrency conversion service status
supported_payment_methodsarrayList of supported payment methods
itemsstringprocessor_error_codestringPayment processor specific error code
decline_reasonstringReason for payment decline
payment_tokenstringPayment token that was declined
anyOf[4]objectContext for data validation issues
specific_issuestring"MISSING_CHECKOUT_FIELDS", "MISSING_PAYMENT_METHOD", "MISSING_POLICY_ACCEPTANCE", "REQUIRED_FIELD_MISSING", "INVALID_EMAIL_FORMAT", "INVALID_PHONE_FORMAT", "FIELD_VALUE_TOO_LONG", "FIELD_VALUE_TOO_SHORT", "INVALID_DATE_FORMAT", "FUTURE_DATE_NOT_ALLOWED", "INVALID_CUSTOMER_DATA", "ITEM_NOT_FOUND", "INVALID_ITEM_DATA", "ITEM_ATTRIBUTE_MISMATCH"Specific data validation issue type
field_namestringName of the field with validation error
provided_valuestringValue that failed validation
expected_formatstringExpected format description
max_lengthintegerMaximum allowed length
min_lengthintegerMinimum required length
current_lengthintegerCurrent value length
regex_patternstringRequired regex pattern
suggested_valuestringSuggested corrected value
allowed_valuesarrayList of allowed values for enum fields
itemsstringrequired_fieldsarrayList of required field names
itemsstringfield_descriptionsobjectDescriptions for required fields
anyOf[5]objectContext for business logic violations
specific_issuestring"MINIMUM_ORDER_NOT_MET", "MINIMUM_QUANTITY_NOT_MET", "MAXIMUM_QUANTITY_EXCEEDED", "CART_LIMIT_EXCEEDED", "CUSTOMER_ACCOUNT_SUSPENDED", "PURCHASE_LIMIT_EXCEEDED", "BULK_ORDER_APPROVAL_REQUIRED", "STORE_TEMPORARILY_CLOSED", "AGE_RESTRICTED_PRODUCT", "LOYALTY_PROGRAM_VALIDATION_FAILED", "BUSINESS_HOURS_RESTRICTION", "PRODUCT_ARCHIVED"Specific business rule issue type
current_amountstringCurrent order amount
required_amountstringRequired minimum amount
maximum_amountstringMaximum allowed amount
remaining_amountstringAmount needed to meet minimum
account_statusstringCustomer account status
suspension_reasonstringReason for account suspension
suspension_datestringdate-timeDate of account suspension
monthly_limitstringMonthly purchase limit
current_month_totalstringCurrent month purchase total
reset_datestringdate-timeWhen limits reset
total_quantityintegerTotal quantity in bulk order
approval_thresholdintegerQuantity requiring approval
maintenance_end_timestringdate-timeWhen maintenance ends
service_statusstringCurrent service status
retry_afterintegerSeconds before retry recommended
contact_infostringSupport contact information
restricted_itemsarrayItems with restrictions
itemsstringage_requirementintegerRequired minimum age
business_hoursobjectStore business hours
open_timestringclose_timestringtimezonestringshortage_amountstringAmount needed to meet minimum requirements
exceeds_bystringAmount by which limit is exceeded
resolution_optionsarrayAvailable actions to resolve this issue
itemsobjectAvailable action to resolve a validation issue
actionrequiredstring"REDIRECT_TO_MERCHANT", "MODIFY_CART", "ACCEPT_NEW_PRICE", "ACCEPT_BACK_ORDER", "SUGGEST_ALTERNATIVE", "REMOVE_ITEM", "UPDATE_ADDRESS", "PROVIDE_MISSING_FIELD", "USE_DIFFERENT_PAYMENT", "SPLIT_ORDER", "CONTACT_SUPPORT", "RETRY_LATER", "REQUEST_APPROVAL", "WAIT_FOR_RESTOCK", "USE_DIFFERENT_CURRENCY", "ACCEPT_PRE_ORDER", "UPDATE_SHIPPING_METHOD", "ACCEPT_TERMS", "VERIFY_ACCOUNT", "APPLY_DIFFERENT_COUPON", "REMOVE_COUPON", "CHOOSE_DIFFERENT_VARIANT"Machine-readable action identifier
labelrequiredstringHuman-readable action label
urlstringuriURL to redirect to for resolution
metadataobjectAdditional action metadata
cost_impactstringFinancial impact of this action
prioritystring"HIGH", "MEDIUM", "LOW"Priority level for this resolution
auto_applicablebooleanWhether this action can be applied automatically
estimated_timestringEstimated time for resolution
redirect_requiredbooleanWhether this action requires user redirect
couponsarrayDiscount coupons to apply or remove from cart
itemsobjectDiscount coupon for cart operations. Multiple coupons can be applied simultaneously, with merchant business rules determining stacking behavior, priorities, and conflicts.
Common Scenarios:
Business Rules: Merchants define stacking rules, maximum discounts, exclusions, and priority orders. Invalid combinations return validation issues with suggested resolutions.
coderequiredstringCoupon code identifier
actionrequiredstring"APPLY", "REMOVE"Action to perform on this specific coupon
geo_coordinatesobjectOptional precise location coordinates for enhanced delivery services
latitudestring^-?([1-8]?[0-9](\.\d+)?|90(\.0+)?)$Latitude coordinate in decimal degrees (-90 to 90). WGS84 datum.
longitudestring^-?((1[0-7]|[1-9])?[0-9](\.\d+)?|180(\.0+)?)$Longitude coordinate in decimal degrees (-180 to 180). WGS84 datum.
subdivisionstring^[A-Z0-9-]+$Administrative subdivision code (state, province, region). ISO 3166-2 format without country prefix (e.g., 'CA' for California, 'ON' for Ontario).
country_codestring^[A-Z]{2}$ISO 3166-1 alpha-2 country code for the coordinate location.