Create cart

Creates a new cart with the provided PayPalCart object. This is called by PayPal Shopping Cart when an AI agent or customer initiates a checkout process. **Returns:** - `201 Created`: Cart created successfully with payment token in payment_method - `200 OK` + `validation_issues`: Business logic issues that need resolution - `400 Bad Request`: Invalid request format - `422 Unprocessable Entity`: Validation errors in cart data - `500 Internal Server Error`: System errors

Authorization

PayPalJWT

AuthorizationBearer <token>

PayPal-supplied JWT token for authenticating merchant API requests.

Important: These JWT tokens are issued and managed by PayPal, not generated by merchants. PayPal provides these tokens to authenticate calls to your merchant API endpoints.

Usage:

Include in Authorization header as "Bearer "
Token is supplied by PayPal Shopping Cart service
Verify token signature using PayPal's public keys
Extract merchant identification from token claims

Example:

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

In: header

Header Parameters

Content-TypestringRequired

Request content type

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

available_shipping_optionsobject<ShippingOption>[]Optional

Available shipping methods with selection state

itemsobject<CartItem>[]Optional

Products in the cart

Items1 <= length <= ∞

CartItem properties

11 properties

item_idstringOptional

Unique product identifier (DEPRECATED - optional in v1 for backwards compatibility)

variant_idstringOptional

Product variant identifier (color, size, etc.) - unique id of the product

parent_idstringOptional

Item grouping identifier - passed when item is part of a group in product catalog

quantityintegerRequired

Number of items

Range1 <= value <= ∞

namestringOptional

Product display name

descriptionstringOptional

Product description

item_urlstringOptional

URL for product details page

Formaturi

priceobject<Money>Optional

Monetary amount with currency

selected_attributesobject<object>[]Optional

Selected product attributes

gift_optionsobject<GiftOptions>Optional

Gift-specific options

custom_optionsobject<object>[]Optional

Custom product 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

typeenumRequired

PayPal-approved checkout field type

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

AgeVerificationValue

Age verification confirmation value

GiftRecipientEmailValue

Gift recipient email information

GiftRecipientNameValue

Gift recipient name information

GiftMessageValue

Gift message content

DeliveryInstructionsValue

Special delivery instructions

DeliveryDatePreferenceValue

Preferred delivery date and time

AllergyInformationValue

Allergy and medical restriction information

CustomEngravingTextValue

Custom engraving text specification

CustomSizingInfoValue

Custom sizing measurements

TermsAcceptanceValue

Terms and conditions acceptance

PrivacyConsentValue

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

codeenumRequired

Consolidated error category

typeenumRequired

Type classification for error handling

Value in"MISSING_FIELD" | "INVALID_DATA" | "BUSINESS_RULE"

messagestringRequired

Technical message for developers and logging

user_messagestringOptional

Customer-friendly message for end users

variant_idstringOptional

Specific item ID if the issue is item-specific

fieldstringOptional

Specific field name if the issue is field-specific

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

couponsobject<Coupon>[]Optional

Discount coupons to apply or remove from cart

geo_coordinatesobject<GeoCoordinates>Optional

Optional precise location coordinates for enhanced delivery services

Response Body

`application/json`

curl -X POST "https://example.com/merchant-cart" \  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \  -H "Content-Type: application/json" \  -H "Content-Type: application/json" \  -d '{    "items": [      {        "variant_id": "SHIRT-BASIC-001",        "quantity": 1      }    ],    "payment_method": {      "type": "paypal"    }  }'

{  "id": "CART-MIN-001",  "status": "CREATED",  "validation_status": "VALID",  "validation_issues": [],  "items": [    {      "variant_id": "SHIRT-BASIC-001",      "quantity": 1    }  ],  "payment_method": {    "type": "paypal",    "token": "EC-1A23456789B012345"  },  "totals": {    "subtotal": {      "currency_code": "USD",      "value": "19.99"    },    "shipping": {      "currency_code": "USD",      "value": "4.99"    },    "tax": {      "currency_code": "USD",      "value": "1.82"    },    "total": {      "currency_code": "USD",      "value": "30.30"    }  }}

On this page

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

Authorization

Header Parameters

Request Body

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

Response Body

201application/json

400application/json

422application/json

500application/json

Minimal cart created successfully (201)

Full cart with quantity (201)

Simple validation error - minimal required fields only

Shipping address and restriction validation errors

Business rules and compliance validation errors

Item out of stock with alternatives

On this page

On this page

`application/json`

`application/json`

`application/json`

`application/json`