> ## Documentation Index > Fetch the complete documentation index at: https://paypal-sb-staging.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Quickstart guide export const ZoomableGraph = ({children}) => { const [zoomed, setZoomed] = useState(false); return <>
setZoomed(true)} className="cursor-zoom-in"> {children}
setZoomed(false)} className={`zoomed-graph cursor-zoom-out backdrop-blur-sm z-50 bg-neutral-50/90 dark:bg-neutral-950/90 transition fixed top-0 left-0 w-screen h-screen p-8 ${zoomed ? 'opacity-100' : 'opacity-0 pointer-events-none'}`}> {children}
; }; To let AI agents shop on behalf of customers, merchants can enable store sync, including cart orchestration. This revolutionary approach transforms how customers interact with online stores. Instead of browsing websites, customers can use their own words to tell an AI agent what they want. The AI agent can handle product discovery, cart management, and checkout completion through secure API calls to your merchant system by way of PayPal's Commerce Platform. With this integration, you can open your storefront to a new generation of AI-powered shopping assistants, commerce platforms, and automated purchasing systems. ``` Customer ↔ AI Agent ↔ PayPal Commerce Platform ↔ Your Merchant API ``` In this guide, you'll see how to build an API that integrates with PayPal Checkout for AI-powered commerce, including: * Receiving cart requests from PayPal Commerce Platform to validate products, calculate taxes, and handle shipping * Handling updates to a shopping cart, like shipping options and line items * Completing orders by processing PayPal payments and fulfilling shipments ## Benefits Merchants using PayPal's agentic commerce services can enable AI agents to shop on their behalf by integrating with shop sync, which includes cart orchestration and offers the following benefits: * Customers interact with AI agents in natural language. * AI agents understand intent and search for products via PayPal's Commerce Platform. * PayPal's Commerce Platform validates requests and routes to your merchant API. * Your API validates products, calculates pricing, handles inventory and orders. ## API endpoints | Endpoint | Description | | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `POST /merchant-cart` | Create a new cart. | | `PUT /merchant-cart/{id}` | Make updates to a cart. Note that this is a complete replacement of everything in the cart, not incremental or partial updates. For more information, see Cart orchestration. | | `POST /merchant-cart/{id}/checkout` | Complete the cart, and fulfill the order. | ## System flow ```mermaid theme={null} sequenceDiagram title Headless Checkout Orchestration autonumber participant USER as Buyer participant AGENT as Agent participant PLATFORM as PayPal Commerce Platform participant PARTNER as Merchant API USER->>+AGENT: "Search for product" AGENT->>+PLATFORM: GET /search?query=[search_query] PLATFORM->>-AGENT: search_results AGENT->>USER: Relevant Products USER->>AGENT: "Buy Now" AGENT->>+PLATFORM: POST /commerce/carts { product_id, access_token } PLATFORM->>+PARTNER: POST /merchant-cart { items, shippingAddress, paymentSource } PARTNER->>-PLATFORM: { cartId, items, shippingOptions, totals } PLATFORM->>-AGENT: Cart details, wallet_info AGENT->>-USER: "Total amount: $x, shipping to {y} using CC ending in {z} - complete?" USER->>+AGENT: "Yes, complete payment" AGENT->>+PLATFORM: POST /commerce/carts/{id}/complete_payment {access_token, payment_source: paypal} PLATFORM->>+PARTNER: POST /merchant-cart/{cartId}/checkout { paymentSource } PARTNER->>-PLATFORM: { status: 'completed', orderId, transactionId } PLATFORM->>-AGENT: { status: 'completed', transaction_details } AGENT->>-USER: "Payment Success, see details", {transaction_details} ``` ## Quickstart integration This section walks you through the essential steps to implement a working Cart API integration. You'll learn how to handle incoming cart requests, process payment completions, and manage the full transaction lifecycle. Follow these 3 core steps to get your merchant API up and running with the store sync feature from PayPal's agentic commerce services, from initial cart creation through successful order fulfillment. > **Important:** This quickstart guide provides a simplified overview. You must complete the product feed integration before you can set up cart orchestration. ### Step 1: Handle incoming cart creation from PayPal Commerce Platform When a customer interacts with an AI agent to buy something, Commerce Platform calls your API endpoint, as shown in the following example. > **Note:** This step shows one type of product feed integration. To determine which type of product feed integration is best for your environment, see the Product feed integration guide. ```json theme={null} POST /api/paypal/v1/merchant-cart Content-Type: application/json Authorization: Bearer { "items": [ { "variant_id": "SHIRT-001", "quantity": 1, "name": "Blue T-Shirt", "price": { "currency_code": "USD", "value": "25.00" } } ], "shipping_address": { "address_line_1": "1060 West Addison Street", "admin_area_2": "CHICAGO", "admin_area_1": "IL", "postal_code": "60613", "country_code": "US" } } ``` #### Success Response (201 created) ```json theme={null} { "id": "CART-123", "status": "CREATED", "payment_method": { "type": "PAYPAL", "token": "EC-7U8939823K567" }, "items": [ { "variant_id": "SHIRT-001", "quantity": 1, "name": "Blue T-Shirt", "unit_amount": { "currency_code": "USD", "value": "25.00" }, "item_total": { "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" }, "total": { "currency_code": "USD", "value": "33.69" } }, "validation_issues": [] } ``` #### Key response fields | Field | Description | | ------------------- | --------------------------------------------------------------------------------------------------- | | `id` | Cart identifier for GET/PUT/PATCH/checkout operations | | `ec_token` | PayPal payment token (required for checkout completion) that enables PayPal payment for a customer. | | `status` | Cart state:
`CREATED`
`INCOMPLETE`
`READY`
`COMPLETED` | | `validation_issues` | Array of problems that need fixing (empty = good) | ### Step 2: PayPal handles payment with customer After receiving a successful cart creation response: 1. PayPal Commerce Platform presents the cart to customer for approval. 2. Customer approves payment using PayPal's agentic checkout APIs. 3. PayPal returns payment approval details to complete the checkout. 4. Your API receives the checkout completion request, which is [Step 3: Handle order completion request](#step-3-handle-order-completion-request). ### Step 3: Handle order completion request After customer approves payment, PayPal Commerce Platform calls your API to complete the order. ```http theme={null} POST /api/paypal/v1/merchant-cart/CART-123/checkout Content-Type: application/json Authorization: Bearer { ...existing cart, "payment_method": { "type": "paypal", "token": "EC-7U8939823K567" } } ``` #### Key parameters | Parameter | Description | | --------- | -------------------------------------------- | | `token` | The `ec_token` returned during cart creation | | `type` | Currently "paypal" for PayPal payments | #### Success response (200 OK) ```json theme={null} { "id": "CART-123", "status": "COMPLETED", "payment_confirmation": { "merchant_order_number": "ORDER-789", "order_review_page": "https://yourstore.com/orders/789" }, "totals": { "total": { "currency_code": "USD", "value": "33.69" } } } ``` At this point, your API has successfully processed the AI-assisted purchase, the customer now owns a new t-shirt, and the AI agent can confirm the successful order. ## Developer quick reference This reference section provides essential lookup tables and patterns you'll need during implementation. Use these quick references to understand HTTP status codes, cart states, validation error structures, and common integration patterns. Keep this section handy while building and debugging your Cart API integration—it contains the most frequently needed information for handling responses, troubleshooting issues, and implementing proper error handling. For the complete protocol reference, see ### HTTP status patterns | Status | Meaning | Response Content | Action | | ---------------------------- | ------------------------- | --------------------- | ------------------------ | | `201 Created` | Cart created successfully | Full cart + ec\_token | Proceed to payment | | `200 OK` | Operation successful | Full cart object | Check status field | | `200 OK + validation_issues` | Business logic issues | Full cart + problems | Fix issues shown | | `400 Bad Request` | Invalid request | Error object | Fix request format | | `404 Not Found` | Cart doesn't exist | Error object | Use valid cart ID | | `500 Server Error` | System problem | Error object | Retry or contact support | ### Cart status values | Value | Description | | ------------ | --------------------------------------------------------------------- | | `CREATED` | Cart successfully created with ec\_token, ready for immediate payment | | `INCOMPLETE` | Cart has validation issues (check `validation_issues`) | | `READY` | Previously incomplete cart is now ready for payment | | `COMPLETED` | Order finished, payment captured | ### Common status combinations | HTTP Status | Cart status | `validation_issues` | Next step | | ------------- | ------------ | ------------------- | --------------------- | | `201 Created` | `CREATED` | `[]` | Proceed to payment | | `200 OK` | `INCOMPLETE` | `[{...}]` | Fix validation issues | | `200 OK` | `READY` | `[]` | Complete checkout | | `200 OK` | `COMPLETED` | `[]` | Order fulfilled | ### State transition example (`INCOMPLETE` → `READY`) ``` 1. Initial cart creation with out-of-stock item: POST /merchant-cart → status: "INCOMPLETE", validation_issues: ["INVENTORY_ISSUE"] 2. Cart updated with alternative item: PUT /merchant-cart/{id} → status: "READY", validation_issues: [] 3. Now ready for checkout: POST /merchant-cart/{id}/checkout → status: "COMPLETED" ``` ### Common `validation_issues` The `validation_issues` array communicates business logic problems that prevent cart completion but don't warrant HTTP error codes. These structured error objects help AI agents understand what went wrong and how to fix it, whether that's suggesting alternative products for out-of-stock items, requesting missing information, or explaining pricing changes. Use these patterns to provide clear, actionable feedback that enables automatic resolution or guides customers to make informed decisions. > **Note:** When validation\_issues exist, PayPal Commerce Platform will send a PUT request with the updated cart state. #### Simple validation error (minimal fields) ```json theme={null} { "code": "INVENTORY_ISSUE", "type": "BUSINESS_RULE", "message": "Product availability issue" } ``` #### Complete validation error (all fields) ```json theme={null} { "code": "INVENTORY_ISSUE", "type": "BUSINESS_RULE", "message": "Product availability issue", "user_message": "The Blue T-Shirt is currently 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"] }, "resolution_options": [ { "action": "SUGGEST_ALTERNATIVE", "label": "View similar colors", "metadata": { "priority": "high", "auto_applicable": true } } ] } ``` ### Error categories | Error type | Description | | --------------------- | ---------------------------------------------------------- | | `INVENTORY_ISSUE` | Stock, availability, back-orders, discontinued items | | `PRICING_ERROR` | Price changes, discounts, tax calculation, currency issues | | `SHIPPING_ERROR` | Address validation, delivery restrictions, shipping zones | | `PAYMENT_ERROR` | Payment limits, currency support, processor issues | | `DATA_ERROR` | Field validation, format issues, required fields | | `BUSINESS_RULE_ERROR` | Account restrictions, compliance, regional limits | ### Types | Type | Description | | --------------- | -------------------------------------------------- | | `MISSING_FIELD` | Need more info (address, checkout fields) | | `INVALID_DATA` | Data validation failed | | `BUSINESS_RULE` | Business logic violation, such as inventory issues | ### Customer information availability | Transaction stage | Information availability | | --------------------- | ------------------------------------------------------ | | Initial cart creation | Customer info may be absent (anonymous shopping) | | After PayPal approval | Customer info available in checkout completion request | | Returning customers | Customer info may be available from start |