Skip to main content
To enable AI agents to create and manage shopping carts through your store, integrate with PayPal’s Cart API. This guide shows you how to implement the 3 core endpoints that handle cart creation, updates, and checkout completion, including PayPal Orders API v2 integration for payment processing.
Note: You can view the complete protocol reference for the Cart API and the Complete Checkout API.

​
API endpoints

The Cart API provides 3 core endpoints that handle the complete cart lifecycle. Each endpoint serves a specific purpose in the agentic shopping flow. To view the PayPal Cart schema, visit the API specification page.
  • POST /merchant-cart creates a new cart.
  • PUT /merchant-cart/{id} updates an existing cart.
  • POST /merchant-cart/{id}/checkout completes the checkout process.

​
Authentication with PayPal-supplied JWTs

  • Request authentication: Every API call includes the token in the authorization header.
  • Merchant identification: Tokens contain your PayPal merchant ID and permissions.
  • Security verification: Verify the token signature using PayPal’s public keys. For more information, see Verify token.

​
Receive token in the authorization header

Every API request must include the PayPal-supplied JWT in the authorization header. 
POST /api/paypal/v1/merchant-cart
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJtZXJjaGFudF9pZCI6Ik1FUkNIQU5ULTEyMyIsInNjb3BlIjpbImNhcnQiXSwiaWF0IjoxNzE5MjQwMDAwLCJleHAiOjE3MTkyNDM2MDB9.signature
Content-Type: application/json

{
  ...cart create request body
}

​
Verify token

  1. Parse the authorization header: "Bearer \<token\>".
  2. Verify token signature using the PayPal public key.
  3. Validate the token expiration.

​
Create a cart

To create a new shopping cart with specified items, use POST /merchant-cart. The cart also can include customer information, such as a shipping address and payment method to use.

​
Cart creation

This example of a request payload shows how to structure a cart creation request with items and customer information. 
POST /api/paypal/v1/merchant-cart
Content-Type: application/json
Authorization: Bearer <paypal-jwt-token>

{
  "items": [...],
  "shipping_address": {...},
  "billing_address": {...},
  "customer": {"email_address": "customer@example.com"},
  "payment_method": {"type": "paypal"},
}
Important: Within this endpoint, a merchant is expected to implement Orders API v2 integration. For more information about this, see Cart creation with an order

​
Update a cart

To update an existing cart by replacing its contents with the provided data, use PUT /merchant-cart/{id}. With this endpoint, you can add or remove items, change quantities, update the shipping address, apply discounts, and so on.
Important: PUT replaces the entire cart. It removes or resets any fields that you do not include in your request. This is a complete replacement operation, not a merge.
Include all current cart data when you make changes, as shown in the following example. 
{
  "items": [
    {"variant_id": "EXISTING-ITEM-VARIANT", "quantity": 5}
  ],
  "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"
  },
  "payment_method": {...}
}
Important: Within this endpoint, a merchant is expected to implement Orders API v2 integration. For more information about this, see Cart update with an order update.

​
Complete checkout

To complete the checkout process for a cart, use POST /merchant-cart/{id}/checkout. This endpoint finalizes the purchase by processing the payment using the specified payment method. 
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", //PayPal Orders V2 ID
    "payer_id": "PAYER123456789" //PayPal User Identifier
  }
}
Important: Within this endpoint, a merchant is expected to implement Orders API v2 integration. For more information about this, see Cart completed with an order captured.

​
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. The following table explains when to create (POST) or update (PATCH) a cart.
ScenarioPayPal Orders ActionReason
Initial cart creation.POST /v2/ordersCreate a new payment context.
Add or remove items.PATCH /v2/orders/{id}Update totals.
Apply or remove coupons.PATCH /v2/orders/{id}Update totals.
Update shipping address.PATCH /v2/orders/{id}Update shipping and tax.
Change quantities.PATCH /v2/orders/{id}Update totals.
Create a fresh payment context when a payment token expires.POST /v2/ordersCreate a fresh payment context.
Create a new cart after checkout.POST /v2/ordersPrepare for a new transaction.
Capture an order.POST /v2/checkout/orders/{id}/captureCapture the payment for an order.

​
Examples

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

​
Cart creation with an order

Implement cart creation by creating a PayPal order and linking it to your cart. 
// 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 an order update

When updating a cart, patch the corresponding PayPal order with new totals. 
async function updateCart(cartData) {
  const cart = await validateAndUpdateCart(cartData);
  const paypal_order_id = cart.payment_method.token;

  await paypalClient.orders.patch(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;
}

​
Cart completed with an order captured

Finalize the purchase by capturing the PayPal order. 
async function completeCart(cartData) {
  const paypal_order_id = cartData.payment_method.token;
  await paypalClient.orders.capture(paypal_order_id);

  return cartData;
}

​
Merchant cart response

These examples show some successful responses that your API can return.

​
Create and update cart response

Return comprehensive cart details, including status, items, totals, and payment information. 
{
  "id": "CART-123",
  "status": "CREATED",
  "validation_status": "VALID",
  "validation_issues": [],
  "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" }
    }
  ],
  "shipping_address": {...},
  "billing_address": {...},
  "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" }
  },
  "payment_method": {
    "type": "PAYPAL",
    "token": "EC-7U8939823K567" //PayPal Order ID
  },
}

​
Complete checkout response

After successful checkout, return the completed cart status with payment confirmation. 
{
  "id": "CART-123",
  "status": "COMPLETED",
  "validation_status": "VALID",
  "validation_issues": [],
  "payment_confirmation": {
    "merchant_order_number": "ORDER-789",
    "order_review_page": "https://yourstore.com/orders/789"
  },
  "totals": {
    "total": {
      "currency_code": "USD",
      "value": "37.19"
    }
  }
}

​
Next steps

Continue by learning more about response handling.