Update cart

Updates a cart by completely replacing its contents with the provided PayPalCart object. This is used when customers make changes like adding items, updating shipping address, applying coupons, or completing checkout fields. **⚠️ CRITICAL: Complete Replacement Operation** - PUT replaces the ENTIRE cart with the provided PayPalCart object - Any fields not included in the request will be removed/reset - Missing fields will be lost (e.g., omitting customer info will remove it)

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

Path Parameters

cartId*string

The cart identifier

Header Parameters

Authorization*string

PayPal-supplied JWT token for authentication

Content-Type*string

Request content type

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

`application/json`

curl -X PUT "https://your-domain.com/api/paypal/v1/merchant-cart/CART-123" \  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \  -H "Content-Type: application/json" \  -H "Content-Type: application/json" \  -d '{    "items": [      {        "variant_id": "SHIRT-BASIC-001",        "quantity": 3,        "name": "Basic T-Shirt",        "price": {          "currency_code": "USD",          "value": "19.99"        }      }    ],    "customer": {      "email_address": "[email protected]"    },    "payment_method": {      "type": "paypal"    }  }'

{
  "id": "CART-UPDATE-001",
  "status": "READY",
  "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": "[email protected]"
  },
  "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"
    }
  }
}

{
  "name": "INVALID_REQUEST",
  "message": "The request could not be processed",
  "debug_id": "ERROR-12345",
  "details": [
    {
      "field": "items",
      "issue": "MISSING_REQUIRED_FIELD",
      "description": "The items field is required and cannot be empty"
    }
  ]
}

{
  "name": "CART_NOT_FOUND",
  "message": "Cart with ID does not exist",
  "debug_id": "ERROR-404-67890"
}

{
  "name": "UNPROCESSABLE_ENTITY",
  "message": "Item out of stock",
  "details": [
    {
      "field": "items[0].quantity",
      "issue": "INSUFFICIENT_STOCK",
      "description": "Requested quantity exceeds available stock"
    }
  ]
}

{
  "name": "INTERNAL_SERVER_ERROR",
  "message": "A temporary system error occurred. Please try again later.",
  "debug_id": "ERROR-500-44556"
}

Header Parameters

Authorization*string

PayPal-supplied JWT token for authentication

Content-Type*string

Request content type

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

available_shipping_options?array<>

Available shipping methods with selection state

items?array<>

Products in the cart

Items1 <= items

customer?

Represents customer information for the shopping cart.

shipping_address?

International shipping address for cart delivery.

billing_address?

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?

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:

Cart creation generates a payment token (in payment_method.token)
Customer completes PayPal approval (Smart Wallet)
PayPal provides token and payer_id for checkout
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?array<>

Custom checkout fields (age verification, etc.)

coupons?array<>

Discount coupons to apply or remove from cart

geo_coordinates?

Optional precise location coordinates for enhanced delivery services

curl -X PUT "https://your-domain.com/api/paypal/v1/merchant-cart/CART-123" \ -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \ -H "Content-Type: application/json" \ -H "Content-Type: application/json" \ -d '{ "items": [ { "variant_id": "SHIRT-BASIC-001", "quantity": 3, "name": "Basic T-Shirt", "price": { "currency_code": "USD", "value": "19.99" } } ], "customer": { "email_address": "[email protected]" }, "payment_method": { "type": "paypal" } }'

{ "id": "CART-UPDATE-001", "status": "READY", "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": "[email protected]" }, "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" } } }

{ "name": "INVALID_REQUEST", "message": "The request could not be processed", "debug_id": "ERROR-12345", "details": [ { "field": "items", "issue": "MISSING_REQUIRED_FIELD", "description": "The items field is required and cannot be empty" } ] }

{ "name": "UNPROCESSABLE_ENTITY", "message": "Item out of stock", "details": [ { "field": "items[0].quantity", "issue": "INSUFFICIENT_STOCK", "description": "Requested quantity exceeds available stock" } ] }

Update cart

200application/json

400application/json

404application/json

422application/json

500application/json

Item quantity updated successfully

Shipping address added with enhanced options

On this page

If you accept cookies, we’ll use them to improve and customize your experience and enable our partners to show you personalized PayPal ads when you visit other sites. Manage cookies and learn more

Update cart

200application/json

400application/json

404application/json

422application/json

500application/json

Item quantity updated successfully

Shipping address added with enhanced options

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`