Skip to main content
The unified Cart API abstracts platform-specific complexities, letting your agents to work seamlessly with supported platforms through a single integration point. This guide explains how to integrate PayPal’s Cart API v1 into your commerce platform using the unified PayPalCart schema.
Important: To access and use store sync, including cart orchestration, merchants must complete this form to contact the AI team at PayPal and request access.
This guide explains:
  • How PayPal’s Cart API fits into your checkout flow
  • When to use each API endpoint and why
  • How to handle complex scenarios, including variants, discounts, age verification, and gift cards
  • Common integration mistakes and how to avoid them
You’ll also get to explore complete HTTP examples and implementation patterns that you can adapt to your tech stack.

​
Modern commerce architecture

PayPal’s Cart API enables agentic commerce, where AI agents handle shopping on behalf of customers through a sophisticated integration chain. This architecture connects customers, AI agents, and merchant systems seamlessly, creating a new paradigm for online shopping. 
Customer ↔ AI Agent ↔ PayPal Commerce Platform ↔ PayPal ↔ Your Merchant API
What this means:
  • Customers interact naturally with AI agents using voice or chat.
  • AI agents assess intent and make shopping decisions for customers.
  • PayPal’s Commerce Platform orchestrates the entire payment and cart flow.
  • PayPal Catalog provides catalog ingestion, product discovery, and validation. It uses product selections to route orders to the correct merchant API.
  • The merchant’s API handles inventory, pricing, and order fulfillment.

​
1. Product discovery

The shopping journey begins when customers express their needs in natural language. The AI agent interprets this intent and searches PayPal’s ingested catalog to find matching products across multiple merchants. 
Customer: "I need a blue t-shirt"
    ↓
AI Agent → PayPal Catalog (ingested products)
    ↓
PayPal returns product data with merchant routing info
    ↓
AI Agent: "Found perfect shirts! Here are your options..."

​
2. Cart creation and management

After a customer selects products, the AI agent creates and manages the shopping cart through PayPal’s Commerce Platform. This process validates product availability, pricing, and shipping options in real-time with your merchant API. 
Customer: "I'll take the medium one"
    ↓
AI Agent → PayPal Commerce Platform
    ↓
Shopping Cart validates with Honey (product details, merchant routing)
    ↓
Shopping Cart → Your Merchant API: POST /merchant-cart
    ↓
Your API responds: Cart created with pricing, shipping options

​
3. Seamless checkout

The final step completes the purchase without requiring customers to leave the conversation. PayPal’s Smart Wallet handles payment authentication and processing while the AI agent confirms order details. 
Customer: "Checkout with PayPal"
    ↓
AI Agent → PayPal Smart Wallet (no redirect needed)
    ↓
PayPal → Shopping Cart → Your Merchant API: Complete checkout
    ↓
AI Agent: "Order confirmed! Arrives Tuesday."

​
Benefits

This integration delivers value across all stakeholders in the commerce ecosystem. Here’s how each party benefits from the agentic commerce approach. For customers:
  • Natural conversation - No complex navigation or forms
  • Intelligent assistance - AI understands preferences and context
  • Seamless payments - PayPal smart wallet integration
  • Proactive updates - AI handles tracking and delivery information
For merchants:
  • Automated orders - AI agents create perfect carts without human intervention
  • Reduced friction - Customers never leave the conversation
  • Higher conversion - AI optimizes for successful purchases
  • Future-ready - Built for the next generation of commerce
For developers:
  • Simple integration - Just implement the merchant API endpoints using unified PayPalCart schema
  • Honey handles discovery - Catalog ingestion and product routing intelligence
  • Real-time inventory - Your API provides live pricing and availability
  • Rich error handling - Clear validation and resolution options

​
Cart status fields

The PayPal Cart API uses three key status indicators that work together to communicate cart state and validation issues. Understanding these fields is crucial for proper error handling and cart lifecycle management. 
{
  "id": "CART-123",
  "status": "INCOMPLETE",
  "validation_status": "REQUIRES_ADDITIONAL_INFORMATION",
  "validation_issues": [
    {
      "code": "DATA_ERROR",
      "type": "MISSING_FIELD",
      "message": "Shipping address is required for delivery",
      "context": {
        "specific_issue": "MISSING_SHIPPING_ADDRESS"
      }
    }
  ]
}

​
1. status - Business outcome (merchant controlled)

Indicates what happened to the cart
ValueDescription
CREATEDCart was successfully created and is ready for use
INCOMPLETECart has issues that need resolution
READYCart is validated and ready for checkout
COMPLETEDOrder is finalized and payment was captured

​
2. validation_status - Item and data validation

Indicates whether the cart contents and data are valid for checkout:
  • All items are available with current pricing.
  • Required information is complete (shipping address, customer data).
  • No business rule violations exist.
  • The validation_issues array is empty.
  • Transaction can proceed to checkout.
ValueDescription
VALIDReady for checkout
INVALIDHas problems that block checkout
Needs more data to proceed
If the value is REQUIRES_ADDITIONAL_INFORMATION, the validation_issues array indicates what information is needed, for example:
  • Required fields are missing (shipping address, checkout fields).
  • Items and pricing are valid but require additional customer input.

​
3. validation_issues - Specific problems with type classification

Detailed list of issues that need resolution with clear categorization
FieldDescription
MISSING_FIELDRequired information missing (shipping address, checkout fields, etc.)
INVALID_DATAProvided data is incorrect or invalid
BUSINESS_RULEBusiness logic violations (out of stock, minimum order, etc.)
The following example shows the structure. 
[
  {
    "code": "DATA_ERROR",
    "type": "MISSING_FIELD",
    "message": "Shipping address is required",
    "context": {
      "specific_issue": "MISSING_SHIPPING_ADDRESS"
    },
    "variant_id": "optional-if-item-specific"
  }
]

​
validation_status decision matrix

Available statuses can be one of the following options.
StatusDescription
VALIDEverything is in order for checkout
REQUIRES_ADDITIONAL_INFORMATIONValue is valid, but more data is needed to proceed
INVALIDIntervention is necessary before the transaction can continue
See the following table to understand when to use each status.
Situationvalidation_statusvalidation_issuesAction Required
All good, ready for checkoutVALID[] (empty)Proceed to checkout
Missing shipping addressREQUIRES_ADDITIONAL_INFORMATION[{code: "DATA_ERROR", type: "MISSING_FIELD", context: {specific_issue: "MISSING_SHIPPING_ADDRESS"}}]Collect shipping address
Age verification neededREQUIRES_ADDITIONAL_INFORMATION[{code: "DATA_ERROR", type: "MISSING_FIELD", context: {specific_issue: "MISSING_CHECKOUT_FIELDS"}}]Complete age verification
Item out of stockINVALID[{code: "INVENTORY_ISSUE", type: "BUSINESS_RULE"}]Remove item or suggest alternatives
Price changedINVALID[{code: "PRICING_ERROR", type: "BUSINESS_RULE"}]Customer must accept new price
Invalid postal codeINVALID[{code: "SHIPPING_ERROR", type: "INVALID_DATA"}]Correct address format
Payment declinedINVALID[{code: "PAYMENT_ERROR", type: "BUSINESS_RULE"}]Try different payment method

​
Common Status Combinations

ScenarioHTTP StatusCart statusvalidation_statusvalidation_issues
Cart Created Successfully201 CreatedCREATEDVALID[]
Item Out of Stock200 OKINCOMPLETEINVALID[{code: "INVENTORY_ISSUE", type: "BUSINESS_RULE", context: {specific_issue: "ITEM_OUT_OF_STOCK"}}]
Missing Shipping200 OKINCOMPLETEREQUIRES_ADDITIONAL_INFORMATION[{code: "DATA_ERROR", type: "MISSING_FIELD", context: {specific_issue: "MISSING_SHIPPING_ADDRESS"}}]
Ready for Checkout200 OKREADYVALID[]
Order Completed200 OKCOMPLETEDVALID[]

​
HTTP status code strategy

The PayPal Cart API uses a combination of HTTP status codes and cart status fields to communicate the outcome of requests.

​
Business logic issues → 200 OK + validation_issues

Use 200 OK for business scenarios that AI agents can understand and potentially resolve:
  • Cart validation issues (out of stock, price changes)
  • Missing required information (shipping address, checkout fields)
  • Payment processing issues (declined payments, business rules)

​
Technical issues → HTTP error codes

Use proper HTTP error codes for technical problems:
  • 400 Bad Request - Invalid request format, missing required parameters
  • 404 Not Found - Cart ID doesn’t exist
  • 500 Internal Server Error - System failures, service unavailable

​
Scenario

Imagine a simple customer interaction where an AI agent helps a customer find and purchase a blue t-shirt.
Customer: “I need a medium blue t-shirt” AI Agent: processes intent and searches inventory AI Agent: creates cart via PayPal Commerce Platform, orchestrating with the Merchant API 
POST /api/paypal/v1/merchant-cart
Content-Type: application/json
Authorization: Bearer <paypal-jwt-token>

{
  "items": [
    {
      "variant_id": "TSHIRT-BLUE-M",
      "quantity": 1,
      "name": "Blue Cotton T-Shirt (Medium)",
      "price": {
        "currency_code": "USD",
        "value": "25.00"
      }
    }
  ],
  "customer": {
    "email_address": "customer@example.com"
  },
  "shipping_address": {
    "address_line_1": "123 Main Street",
    "admin_area_2": "San Jose",
    "admin_area_1": "CA",
    "postal_code": "95131",
    "country_code": "US"
  },
  "payment_method": {
    "type": "paypal"
  }
}
AI agent: “Found perfect blue t-shirt in medium! $25 total. Ready to checkout?”

​
PayPal Cart API returns cart information

{
  "id": "CART-ABC123",
  "status": "CREATED",
  "items": [
    {
      "variant_id": "TSHIRT-BLUE-M",
      "quantity": 1,
      "name": "Blue Cotton T-Shirt (Medium)",
      "price": { "currency_code": "USD", "value": "25.00" }
    }
  ],
  "totals": {
    "subtotal": { "currency_code": "USD", "value": "25.00" },
    "shipping": { "currency_code": "USD", "value": "5.99" },
    "tax": { "currency_code": "USD", "value": "2.70" },
    "handling": { "currency_code": "USD", "value": "1.50" },
    "custom_charges": { "currency_code": "USD", "value": "2.00" },
    "total": { "currency_code": "USD", "value": "37.19" }
  }
}

​
AI completes checkout

AI Agent: “Ready to checkout with PayPal?” Customer: “Yes, proceed” AI Agent: seamlessly handles PayPal smart wallet approval (no redirect needed) 
POST /api/paypal/v1/merchant-cart/CART-ABC123/checkout
Content-Type: application/json
Authorization: Bearer <paypal-jwt-token>

{
  "payment_method": {
    "type": "paypal",
    "token": "EC-7U8939823K567",
    "payer_id": "PAYER123456789"
  },
  "accepted_policies": [
    "terms_of_service"
  ]
}
AI Agent: “Order confirmed! Your t-shirt will arrive Tuesday.”

​
Authentication - PayPal-supplied JWT tokens

  1. PayPal-issued - Tokens are generated and managed by PayPal, not merchants.
  2. Request authentication - Included in Authorization header for every API call.
  3. Merchant identification - Token contains merchant ID and permissions.
  4. Security verification - Verify token signature using PayPal’s public keys.

​
1. Receive token in authorization header

POST /api/paypal/v1/merchant-cart
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJtZXJjaGFudF9pZCI6Ik1FUkNIQU5ULTEyMyIsInNjb3BlIjpbImNhcnQiXSwiaWF0IjoxNzE5MjQwMDAwLCJleHAiOjE3MTkyNDM2MDB9.signature
Content-Type: application/json

{
  ...cart create request body
}

​
2. Verify token

  1. Parse Authorization header: “Bearer <token>”
  2. Verify token signature using PayPal public keys
  3. Validate token expiration
  4. Check required scopes (e.g., “cart”, “complete”)

​
API endpoints

The Cart API provides 3 core endpoints that handle the complete cart lifecycle. Each endpoint serves a specific purpose in the shopping flow.

​
Unified PayPalCart schema

{
  "items": [...],
  "customer": {...},
  "shipping_address": {...},
  "payment_method": {...},
  "checkout_fields": [...],
  "gift_options": {...}
}

​
POST /merchant-cart - Create cart

Creates a new shopping cart with specified items, customer info, shipping address, and payment method.

​
Basic creation

POST /api/paypal/v1/merchant-cart
Content-Type: application/json
Authorization: Bearer <paypal-jwt-token>

{
  "items": [
    {
      "variant_id": "PRODUCT-001",
      "quantity": 1,
      "name": "Basic T-Shirt",
      "price": {"currency_code": "USD", "value": "25.00"}
    }
  ],
  "payment_method": {
    "type": "paypal"
  }
}

​
Advanced creation (everything at once)

POST /api/paypal/v1/merchant-cart
Content-Type: application/json
Authorization: Bearer <paypal-jwt-token>

{
  "items": [...],
  "shipping_address": {...},
  "customer": {"email_address": "customer@example.com"},
  "payment_method": {"type": "paypal"},
  "checkout_fields": [...]
}

​
PUT /merchant-cart/{id} - Update cart

Updates an existing cart by replacing its contents with the provided data. Use this endpoint to add or remove items, change quantities, update shipping address, apply discounts, and so on.
Note: PUT replaces the ENTIRE cart. Any fields that you do not include in your request will be removed or reset. This is a complete replacement operation, not a merge.
Include ALL current cart data when making changes, as shown in the following example. 
{
  "items": [
    {"variant_id": "EXISTING-ITEM", "quantity": 1},
    {"variant_id": "NEW-ITEM", "quantity": 1}
  ],
  "customer": {
    "email_address": "customer@example.com"
  },
  "shipping_address": {
    "address_line_1": "123 Current Street",
    "admin_area_2": "Current City",
    "admin_area_1": "CA",
    "postal_code": "95131",
    "country_code": "US"
  },
  "checkout_fields": [...],
  "payment_method": {...}
}

​
POST /merchant-cart/{id}/checkout - Complete checkout

POST /api/paypal/v1/merchant-cart/CART-123/checkout
Content-Type: application/json
Authorization: Bearer <paypal-jwt-token>

{
  "payment_method": {
    "type": "paypal",
    "token": "EC-7U8939823K567",
    "payer_id": "PAYER123456789"
  },
  "checkout_fields": [
    {
      "type": "AGE_VERIFICATION_21_PLUS",
      "status": "COMPLETED",
      "value": {
        "confirmed": true,
        "verification_method": "self_declaration",
        "verification_date": "2024-06-24T14:30:00Z"
      }
    }
  ],
  "accepted_policies": [
    "terms_of_service",
    "privacy_policy"
  ]
}

​
PayPal Orders API Integration Pattern

Behind the scenes, the PayPal Cart API integrates with PayPal’s Orders API v2 to manage payment tokens and process transactions. Understanding this relationship helps you implement proper payment handling. When implementing the Cart API, merchants must integrate with PayPal Orders API v2 to handle payment tokens and order updates. This section clarifies when to CREATE vs PATCH orders based on cart lifecycle.

​
1. Initial cart creation → CREATE order

​
2. Cart updates → PATCH order

​
When to CREATE or PATCH

ScenarioPayPal Orders ActionReason
Initial cart creationPOST /v2/ordersCreate new payment context
Add/remove itemsPATCH /v2/orders/{id}Update totals
Apply/remove couponsPATCH /v2/orders/{id}Update totals
Update shipping addressPATCH /v2/orders/{id}Update shipping + tax
Change quantitiesPATCH /v2/orders/{id}Update totals
Payment token expiredPOST /v2/ordersCreate fresh payment context
New cart after checkoutPOST /v2/ordersNew transaction

​
Examples

The following code snippets illustrate how to implement cart creation and updates.

​
Cart creation with order

// Merchant API implementation
async function createCart(cartData) {
  const cart = await validateAndCalculateCart(cartData);

  const paypalOrder = await paypalClient.orders.create({
    intent: "CAPTURE",
    purchase_units: [
      {
        amount: {
          currency_code: cart.totals.total.currency_code,
          value: cart.totals.total.value,
          breakdown: {
            item_total: {
              currency_code: "USD",
              value: cart.totals.subtotal.value,
            },
            shipping: {
              currency_code: "USD",
              value: cart.totals.shipping.value,
            },
            tax_total: { currency_code: "USD", value: cart.totals.tax.value },
          },
        },
      },
    ],
  });

  cart.payment_method = {
    type: "PAYPAL",
    token: paypalOrder.id, // PayPal uses order_id as token
  };

  return cart;
}

​
Cart update with order PATCH

async function updateCart(cartData) {
  const cart = await applyUpdatesAndRecalculate(cartData);

  await paypalClient.orders.patch(cart.paypal_order_id, [
    {
      op: "replace",
      path: "/purchase_units/@reference_id=='default'/amount",
      value: {
        currency_code: cart.totals.total.currency_code,
        value: cart.totals.total.value,
        breakdown: {
          item_total: {
            currency_code: "USD",
            value: cart.totals.subtotal.value,
          },
          shipping: { currency_code: "USD", value: cart.totals.shipping.value },
          tax_total: { currency_code: "USD", value: cart.totals.tax.value },
        },
      },
    },
  ]);

  return cart;
}

​
Error handling guide

Effective error handling is critical for maintaining a smooth shopping experience. The API provides rich error context that enables AI agents to resolve issues automatically or guide customers to resolution. Instead of handling dozens of specific error cases, focus on these essential patterns:
  1. Can you fix this automatically? → Fix it
  2. Can the customer fix this? → Show them how

​
Common error pattern

{
  "code": "INVENTORY_ISSUE",
  "user_message": "Blue T-Shirt is out of stock. Try a different color?",
  "resolution_options": [
    {
      "action": "SUGGEST_ALTERNATIVE",
      "label": "View other colors"
    },
    {
      "action": "REMOVE_ITEM",
      "label": "Remove from cart"
    }
  ]
}

​
Inventory and stock management errors

Inventory issues are among the most common errors in e-commerce. These examples show how to handle out-of-stock scenarios, back-orders, and discontinued products gracefully.

​
Out of stock with alternatives

{
  "code": "INVENTORY_ISSUE",
  "type": "BUSINESS_RULE",
  "message": "Product is no longer available",
  "user_message": "The Blue T-Shirt is temporarily out of stock. Would you like to try a different color?",
  "variant_id": "SHIRT-BLUE-M",
  "context": {
    "specific_issue": "ITEM_OUT_OF_STOCK",
    "available_quantity": 0,
    "requested_quantity": 1,
    "suggested_alternatives": ["SHIRT-RED-M", "SHIRT-GREEN-M"],
    "restock_date": "2024-07-20T00:00:00Z"
  },
  "resolution_options": [
    {
      "action": "SUGGEST_ALTERNATIVE",
      "label": "View similar colors",
      "metadata": {
        "priority": "high",
        "auto_applicable": true
      }
    },
    {
      "action": "WAIT_FOR_RESTOCK",
      "label": "Notify when back in stock",
      "metadata": {
        "estimated_time": "5-7 days",
        "priority": "medium"
      }
    },
    {
      "action": "REMOVE_ITEM",
      "label": "Remove from cart",
      "metadata": {
        "priority": "low"
      }
    }
  ]
}

​
Back-order scenario

{
  "code": "INVENTORY_ISSUE",
  "type": "BUSINESS_RULE",
  "message": "Item is currently back-ordered",
  "user_message": "This item will ship in 2-3 weeks. Would you like to proceed with your order?",
  "variant_id": "LAPTOP-PRO-15",
  "context": {
    "available_quantity": 0,
    "back_order_limit": 50,
    "estimated_ship_date": "2024-08-15T00:00:00Z",
    "current_back_orders": 23
  },
  "resolution_options": [
    {
      "action": "ACCEPT_BACK_ORDER",
      "label": "Order anyway (ships August 15th)",
      "metadata": {
        "estimated_time": "2-3 weeks",
        "priority": "high",
        "cost_impact": "$0.00"
      }
    },
    {
      "action": "SUGGEST_ALTERNATIVE",
      "label": "View similar laptops in stock",
      "metadata": {
        "priority": "medium",
        "auto_applicable": true
      }
    }
  ]
}

​
Discontinued product

{
  "code": "INVENTORY_ISSUE",
  "type": "BUSINESS_RULE",
  "message": "Product has been discontinued",
  "user_message": "This product is no longer available. Here are some similar alternatives.",
  "variant_id": "PRODUCT-OLD-MODEL",
  "context": {
    "discontinuation_date": "2024-02-01T00:00:00Z",
    "suggested_alternatives": ["PRODUCT-NEW-MODEL", "PRODUCT-SIMILAR"],
    "upgrade_available": true
  },
  "resolution_options": [
    {
      "action": "SUGGEST_ALTERNATIVE",
      "label": "View newer model (+$50)",
      "metadata": {
        "cost_impact": "+$50.00",
        "priority": "high"
      }
    },
    {
      "action": "REMOVE_ITEM",
      "label": "Remove from cart",
      "metadata": {
        "priority": "low"
      }
    }
  ]
}

​
Pricing and financial Errors

Price changes can occur between cart creation and checkout. These error patterns help you handle pricing discrepancies transparently while maintaining customer trust.

​
Price change during checkout

{
  "code": "PRICING_ERROR",
  "type": "BUSINESS_RULE",
  "message": "Product price has changed since cart creation",
  "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": {
    "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
      }
    },
    {
      "action": "REMOVE_ITEM",
      "label": "Remove from cart",
      "metadata": {
        "cost_impact": "-$29.99",
        "priority": "medium"
      }
    }
  ]
}

​
Shipping and address errors

Address validation ensures successful delivery while preventing fraud. These examples demonstrate handling invalid addresses, PO Box restrictions, and shipping limitations.

​
Invalid shipping address

{
  "code": "SHIPPING_ERROR",
  "type": "INVALID_DATA",
  "message": "Shipping address validation failed",
  "user_message": "The shipping address appears to be incomplete or invalid. Please check and correct.",
  "field": "shipping_address",
  "context": {
    "validation_failures": ["invalid_postal_code", "missing_street_number"],
    "suggested_corrections": {
      "postal_code": "90210",
      "address_line_1": "123 Main Street"
    },
    "address_quality_score": 0.3
  },
  "resolution_options": [
    {
      "action": "UPDATE_ADDRESS",
      "label": "Use suggested corrections",
      "metadata": {
        "priority": "high",
        "auto_applicable": true
      }
    },
    {
      "action": "PROVIDE_MISSING_FIELD",
      "label": "Add street number",
      "metadata": {
        "priority": "medium"
      }
    }
  ]
}

​
PO box destrictions

{
  "code": "SHIPPING_ERROR",
  "type": "BUSINESS_RULE",
  "message": "PO Box delivery not available for this order",
  "user_message": "This order contains items requiring signature confirmation and cannot be delivered to a PO Box.",
  "field": "shipping_address",
  "context": {
    "restricted_items": ["ELECTRONICS-LAPTOP-001"],
    "restriction_reason": "signature_required",
    "po_box_detected": true
  },
  "resolution_options": [
    {
      "action": "UPDATE_ADDRESS",
      "label": "Use street address instead",
      "metadata": {
        "priority": "high"
      }
    },
    {
      "action": "REMOVE_ITEM",
      "label": "Remove items requiring signature",
      "metadata": {
        "cost_impact": "-$899.00",
        "priority": "low"
      }
    }
  ]
}
Some products or merchants have regional restrictions due to regulations or business policies. These errors help communicate limitations clearly to customers.

​
Regional sales restrictions

{
  "code": "BUSINESS_RULE_ERROR",
  "type": "BUSINESS_RULE",
  "message": "Store does not sell to this region",
  "user_message": "Unfortunately, we don't ship to your location due to regulatory restrictions. Please check our shipping policy.",
  "context": {
    "restricted_region": "EU",
    "customer_country": "DE",
    "restriction_reason": "regulatory_compliance",
    "supported_countries": ["US", "CA", "GB"],
    "policy_url": "https://merchant.com/shipping-policy"
  },
  "resolution_options": [
    {
      "action": "CONTACT_SUPPORT",
      "label": "Contact support for alternatives",
      "url": "https://merchant.com/support",
      "metadata": {
        "priority": "medium"
      }
    }
  ]
}

​
System and store errors

Temporary system issues require special handling to maintain customer relationships. These patterns show how to communicate maintenance windows and system unavailability.

​
Store maintenance mode

{
  "code": "BUSINESS_RULE_ERROR",
  "type": "BUSINESS_RULE",
  "message": "Store is currently in maintenance mode",
  "user_message": "The store is temporarily closed for maintenance. Please try again later.",
  "context": {
    "maintenance_end_time": "2024-06-25T09:00:00Z",
    "service_status": "maintenance",
    "reason": "system_upgrade",
    "retry_after": 7200
  },
  "resolution_options": [
    {
      "action": "RETRY_LATER",
      "label": "Try again at 9:00 AM",
      "metadata": {
        "estimated_time": "2 hours",
        "priority": "high"
      }
    }
  ]
}

​
Error handling implementation strategy

When implementing error handling for the PayPal Cart API, use the following guidelines to determine appropriate HTTP status codes and error responses.

​
200 OK + validation_issues

  • Inventory changes (out of stock, back-ordered)
  • Price changes during checkout
  • Payment processing issues that can be resolved
  • Geographic restrictions
  • Discount validation failures
  • Customer account issues
  • Address validation problems

​
422 Unprocessable entity

This should be used when encountering any validation_issue that would prevent you from creating a cart. For instance, if you do not create a cart for an OUT_OF_STOCK issue, you would send back a 422 Unprocessable Entity error with details about the error in the body. Refer to the API Spec for how Errors should be formatted

​
400 Bad request

  • Invalid JSON format
  • Missing required fields (items array)
  • Invalid field types or formats
  • Malformed request structure
  • Invalid cart ID format (e.g., doesn’t match expected pattern like “CART-[A-Z0-9]+“)

​
404 not found

  • Cart ID doesn’t exist in merchant’s system (well-formed ID but not found)
  • Invalid endpoint paths

​
Cart retrieval error handling (GET /merchant-cart/{cartId})

Example 1: Invalid cart ID format (400 response) 
{
  "name": "INVALID_CART_ID",
  "message": "Cart ID format is invalid. Expected format: CART-[A-Z0-9]+",
  "debug_id": "ERROR-400-CART-FORMAT",
  "details": [
    {
      "field": "cartId",
      "issue": "INVALID_FORMAT",
      "description": "Cart ID format is invalid. Expected format: CART-[A-Z0-9]+. Provided: invalid-cart-id-123"
    }
  ]
}
Example 2: Cart not found (404 response) 
{
  "name": "CART_NOT_FOUND",
  "message": "Cart with ID 'CART-MISSING-123' does not exist",
  "debug_id": "ERROR-404-12345",
  "details": [
    {
      "field": "cartId",
      "issue": "NOT_FOUND",
      "description": "Cart with ID 'CART-MISSING-123' does not exist for merchant 'MERCHANT_789'. Verify cart ID or create a new cart."
    }
  ]
}

​
500 internal server error

  • System failures
  • Database connectivity issues
  • Payment processor unavailable
  • Unexpected server errors

​
Error context best practices

  1. Provide Rich Context: Include all relevant information for smart resolution.
  2. Customer-Friendly Messages: Write user_message for end customers.
  3. Technical Details: Include technical message for developers.
  4. Resolution Guidance: Always provide actionable next steps.
  5. Cost Impact: Show financial implications of resolution options.
  6. Time Estimates: Provide realistic timeframes for resolutions.

​
AI agent considerations

Errors are designed for AI agents to handle autonomously:
  • Auto-applicable actions: AI can resolve without human intervention.
  • Priority guidance: Immediate action is required.
  • Context-rich: The system has enough information for intelligent decision making.
  • Resolution metadata: The system helps AI choose best resolution.

​
Resolution action types

ActionUse CaseAuto-applicable
ACCEPT_NEW_PRICEPrice increasesNo
ACCEPT_BACK_ORDERInventory delaysDepends on customer preference
SUGGEST_ALTERNATIVEOut of stock itemsYes
UPDATE_ADDRESSAddress validationYes (if correction available)
REMOVE_ITEMRestriction violationsDepends on item importance
SPLIT_ORDERPayment limitsYes
CONTACT_SUPPORTComplex issuesNo
RETRY_LATERTemporary failuresYes

​
Advanced use cases

Beyond basic cart operations, the API supports sophisticated scenarios like gift cards and location-based services. These examples demonstrate advanced integration capabilities.

​
Gift cards

POST /api/paypal/v1/merchant-cart
Content-Type: application/json
Authorization: Bearer <paypal-jwt-token>

{
  "items": [
    {
      "variant_id": "GIFTCARD-100",
      "quantity": 1,
      "gift_options": {
        "is_gift": true,
        "recipient": {
          "name": "Mary Johnson",
          "email": "mary@example.com"
        },
        "delivery_date": "2024-12-25T09:00:00Z",
        "sender_name": "John Smith",
        "gift_message": "Merry Christmas! Enjoy your shopping."
      }
    }
  ],
  "payment_method": {
    "type": "paypal"
  }
}

​
Geographic coordinates

Some merchants offer location-based services that require precise geographic positioning beyond standard postal addresses. The Cart API supports optional latitude/longitude coordinates to enable features like local inventory checking, distance-based pricing, delivery radius validation, and enhanced shipping calculations. This geographic data operates independently from shipping addresses, allowing you to provide location-aware commerce experiences while maintaining clean separation between postal and coordinate data.

​
Latitute and longitude support strategy

Geographic coordinates are optional. It is designed for merchants who can provide enhanced location services. Geographic coordinates are provided in a separate geo_coordinates field, distinct from the shipping_address object. This clean separation allows:
  • Postal addresses to remain focused on standard shipping data
  • Geographic coordinates to provide precise location enhancement
  • Independent handling of address vs. coordinate data
  • Graceful degradation when coordinates aren’t supported
{
  "shipping_address": {
    "address_line_1": "123 Main Street",
    "admin_area_2": "San Jose",
    "admin_area_1": "CA",
    "postal_code": "95131",
    "country_code": "US"
  },
  "geo_coordinates": {
    "latitude": "37.3349",
    "longitude": "-122.0090",
    "subdivision": "CA",
    "country_code": "US"
  }
}

​
Geographic fields

  • latitude & longitude: Precise WGS84 coordinates in decimal degrees
  • subdivision: Administrative division (state, province, region) using ISO 3166-2 format
  • country_code: ISO 3166-1 alpha-2 country code for the coordinate location
Examples:
  • US: subdivision: "CA" (California), country_code: "US"
  • Canada: subdivision: "ON" (Ontario), country_code: "CA"
  • UK: subdivision: "ENG" (England), country_code: "GB"

​
Testing your integration

Comprehensive testing ensures your integration handles all scenarios correctly. Use this checklist and test scenarios to validate your implementation before going live.

​
Integration checklist

Before you launch your integration, verify that your implementation handles all critical scenarios correctly. This checklist covers the essential functionality, error states, and edge cases that ensure a robust commerce experience. Work through each item systematically to confirm your integration can handle real-world usage patterns and recover gracefully from common issues.

​
Basic Functionality

  • Can create cart with simple items
  • Can handle PayPal payment (smart wallet)
  • Can handle successful payment return
  • Can complete checkout and get order confirmation
  • Can handle payment cancellation

​
Cart Updates

  • Can update shipping address via PUT
  • Can add/remove items via PUT
  • Can apply and remove coupon codes
  • Can handle cart validation errors
  • Can update checkout field values

​
Error Handling

  • Out of stock items are handled gracefully
  • Invalid addresses are caught and corrected
  • Network errors don’t break the flow
  • Payment failures are handled properly

​
Test scenario: Happy path

# 1. Create cart
POST /api/paypal/v1/merchant-cart
{
  "items": [
    {
      "variant_id": "TEST-PRODUCT-001",
      "quantity": 1,
      "price": {"currency_code": "USD", "value": "29.99"}
    }
  ],
  "payment_method": {
    "type": "paypal"
  }
}

# 2. Update with shipping
PUT /api/paypal/v1/merchant-cart/CART-TEST-123
{
  "items": [
    {
      "variant_id": "TEST-PRODUCT-001",
      "quantity": 1,
      "price": {"currency_code": "USD", "value": "29.99"}
    }
  ],
  "shipping_address": {
    "address_line_1": "123 Test Street",
    "admin_area_2": "Test City",
    "admin_area_1": "CA",
    "postal_code": "95131",
    "country_code": "US"
  },
  "payment_method": {
    "type": "paypal"
  }
}

# 3. Simulate PayPal return
POST /api/paypal/v1/merchant-cart/CART-TEST-123/checkout
{
  "payment_method": {
    "type": "paypal",
    "token": "EC-TEST123",
    "payer_id": "TEST_PAYER"
  }
}