Quickstart guide

​

What You’ll Build

1. Receive cart requests from PayPal Commerce Platform to validate products, calculate taxes & shipping
2. Handle updates to the cart like shipping options and line items
3. Complete orders by processing PayPal payments and fulfilling shipments

​

30-Second Overview

Customer ↔ AI Agent ↔ PayPal Commerce Platform ↔ Your Merchant API

​

What this means for you as a merchant on PayPal’s Commerce Platform

1. Customers interact with AI agents in natural language
2. AI agents understand intent and search for products via PayPal’s Commerce Platform
3. PayPal Commerce Platform validates requests and routes to your merchant API
4. Your API validates products, calculates pricing, handles inventory and orders

​

Your merchant API endpoints:

• POST /merchant-cart - create a new cart
• PUT /merchant-cart/{id} - make updates to a cart (complete replacement)
• POST /merchant-cart/{id}/checkout - complete the cart and fulfill the order

​

System Flow Diagram

​

Quick Start Integration

​

Step 1: Handle Incoming Cart Creation from PayPal Commerce Platform

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

{
  "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": []
}

• id - Cart identifier for GET/PUT/PATCH/checkout operations
• ec_token - PayPal payment token (required for checkout completion)
• status - Cart state (CREATED/INCOMPLETE/READY/COMPLETED)
• validation_issues - Array of problems that need fixing (empty = good)

​

Step 2: PayPal Handles Payment with Customer

1. PayPal Commerce Platform presents the cart to customer for approval
2. Customer approves payment via PayPal’s Agentic Checkout APIs
3. PayPal returns payment approval details to complete the checkout
4. Your API receives the checkout completion request (Step 3)

​

Step 3: Handle Order Completion Request

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

• token - The ec_token returned during cart creation
• type - Currently “paypal” for PayPal payments

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

​

Developer Quick Reference

​

HTTP Status Patterns

​

Cart Status Values

• CREATED - Cart successfully created with ec_token, ready for immediate payment
• INCOMPLETE - Has validation issues that need fixing (check validation_issues)
• READY - Previously incomplete cart now resolved, ready for payment
• COMPLETED - Order finished, payment captured

​

Common Status Combinations

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

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

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

• 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

• MISSING_FIELD - Need more info (address, checkout fields)
• INVALID_DATA - Data validation failed
• BUSINESS_RULE - Business logic violation (out of stock, etc.)

​

Customer 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