Skip to main content
PUT
/
merchant-cart
/
{cartId}
curl --request PUT \
  --url https://your-domain.com/api/paypal/v1/merchant-cart/{cartId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "items": [
    {
      "variant_id": "SHIRT-BASIC-001",
      "quantity": 3,
      "name": "Basic T-Shirt",
      "price": {
        "currency_code": "USD",
        "value": "19.99"
      }
    }
  ],
  "customer": {
    "email_address": "customer@example.com"
  },
  "payment_method": {
    "type": "paypal"
  }
}
'
{
  "id": "CART-UPDATE-001",
  "status": "CREATED",
  "validation_status": "VALID",
  "validation_issues": [],
  "items": [
    {
      "variant_id": "SHIRT-BASIC-001",
      "quantity": 3,
      "name": "Basic T-Shirt",
      "price": {
        "currency_code": "USD",
        "value": "19.99"
      }
    }
  ],
  "customer": {
    "email_address": "customer@example.com"
  },
  "totals": {
    "subtotal": {
      "currency_code": "USD",
      "value": "59.97"
    },
    "shipping": {
      "currency_code": "USD",
      "value": "6.99"
    },
    "tax": {
      "currency_code": "USD",
      "value": "6.12"
    },
    "total": {
      "currency_code": "USD",
      "value": "73.08"
    }
  }
}

Authorizations

​
Authorization
string
header
required

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

Headers

​
Authorization
string
required

PayPal-supplied JWT token for authentication

Example:

"Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

​
Content-Type
string
required

Request content type

Example:

"application/json"

Path Parameters

​
cartId
string
required

The cart identifier

Example:

"CART-123"

Body

application/json

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

​
discounts
object

Discount codes and applied discounts

​
available_shipping_options
object[]

Available shipping methods with selection state

​
items
object[]

Products in the cart

Minimum array length: 1
​
customer
object

Represents customer information for the shopping cart.

​
shipping_address
Shipping Address · object

International shipping address for cart delivery.

​
billing_address
Billing Address · object

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_method
object

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_fields
object[]

Custom checkout fields (age verification, etc.)

​
marketing_consent_options
object[]

Marketing consent options the merchant offers. When present, the agent SHOULD display these to the buyer. An empty array is equivalent to absent — no consent UI should be shown.

​
marketing_consents
object[]

Buyer's marketing consent decisions. Agents SHOULD include an entry for each consent option surfaced to the buyer. Omission preserves existing subscription state.

​
geo_coordinates
object

Optional precise location coordinates for enhanced delivery services

Response

Cart updated successfully

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

​
id
string
read-only

Unique cart identifier (server-generated)

Example:

"CART-123"

​
status
enum<string>
read-only

Current cart business status (server-calculated)

Note: READY is deprecated. Use CREATED instead.

Available options:
CREATED,
INCOMPLETE,
COMPLETED,
READY
Example:

"CREATED"

​
validation_status
enum<string>
read-only

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
Available options:
VALID,
INVALID,
REQUIRES_ADDITIONAL_INFORMATION
Example:

"VALID"

​
validation_issues
object[]
read-only

List of issues preventing checkout (empty = ready)

​
totals
object
read-only

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 discounts and promotions
  • 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.

​
discounts
object

Discount codes and applied discounts

​
available_shipping_options
object[]

Available shipping methods with selection state

​
items
object[]

Products in the cart

Minimum array length: 1
​
customer
object

Represents customer information for the shopping cart.

​
shipping_address
Shipping Address · object

International shipping address for cart delivery.

​
billing_address
Billing Address · object

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_method
object

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_fields
object[]

Custom checkout fields (age verification, etc.)

​
marketing_consent_options
object[]

Marketing consent options the merchant offers. When present, the agent SHOULD display these to the buyer. An empty array is equivalent to absent — no consent UI should be shown.

​
marketing_consents
object[]

Buyer's marketing consent decisions. Agents SHOULD include an entry for each consent option surfaced to the buyer. Omission preserves existing subscription state.

​
geo_coordinates
object

Optional precise location coordinates for enhanced delivery services