Quickstart guide

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

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.

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

{
  "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)

{
  "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

After customer approves payment, PayPal Commerce Platform calls your API to complete the order.

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

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

{
  "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)

{
  "code": "INVENTORY_ISSUE",
  "type": "BUSINESS_RULE",
  "message": "Product availability issue"
}

Complete validation error (all fields)

{
  "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