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:

PayPal Commerce Platform presents the cart to customer for approval.
Customer approves payment using PayPal’s agentic checkout APIs.
PayPal returns payment approval details to complete the checkout.
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

Grow your business

Send payouts

Analyze reports

Agentic commerce

Benefits

API endpoints

System flow

Quickstart integration

Step 1: Handle incoming cart creation from PayPal Commerce Platform

Success Response (201 created)

Key response fields

Step 2: PayPal handles payment with customer

Step 3: Handle order completion request

Key parameters

Success response (200 OK)

Developer quick reference

HTTP status patterns

Cart status values

Common status combinations

State transition example (`INCOMPLETE` → `READY`)

Common `validation_issues`

Simple validation error (minimal fields)

Complete validation error (all fields)

Error categories

Types

Customer information availability

Grow your business

Send payouts

Analyze reports

Agentic commerce

​Benefits

​API endpoints

​System flow

​Quickstart integration

​Step 1: Handle incoming cart creation from PayPal Commerce Platform

​Success Response (201 created)

​Key response fields

​Step 2: PayPal handles payment with customer

​Step 3: Handle order completion request

​Key parameters

​Success response (200 OK)

​Developer quick reference

​HTTP status patterns

​Cart status values

​Common status combinations

​State transition example (INCOMPLETE → READY)

​Common validation_issues

​Simple validation error (minimal fields)

​Complete validation error (all fields)

​Error categories

​Types

​Customer information availability

Benefits

API endpoints

System flow

Quickstart integration

Step 1: Handle incoming cart creation from PayPal Commerce Platform

Success Response (201 created)

Key response fields

Step 2: PayPal handles payment with customer

Step 3: Handle order completion request

Key parameters

Success response (200 OK)

Developer quick reference

HTTP status patterns

Cart status values

Common status combinations

State transition example (`INCOMPLETE` → `READY`)

Common `validation_issues`

Simple validation error (minimal fields)

Complete validation error (all fields)

Error categories

Types

Customer information availability