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 Braintree 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.
  • POST /merchant-cart creates a new cart.
  • PUT /merchant-cart/{id} updates an existing cart.
  • POST /merchant-cart/{id}/checkout completes the checkout process.
Tip: You can view the PayPal Cart schema here.

​
Authentication with PayPal-supplied JWTs

  • Request authentication: Every API call includes the token in the authorization header.
  • Merchant identification: Tokens contain your merchant ID and permissions.
  • Security verification: Verify token signature using PayPal’s public keys. See Verify the 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 the token

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

​
Braintree credentials

To enable agentic checkout, we will need your Braintree credentials: merchant_id and tokenization_key. For more information, see Important gateway credentials.

​
Create a cart

To create a new shopping cart with specified items, use POST /merchant-cart. The cart can also 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>

{
  "items": [...],
  "shipping_address": {...},
  "billing_address": {...},
  "customer": {"email_address": "customer@example.com"},
  "payment_method": {"type": "paypal"},
}
Important: PayPal uses your Braintree credentials to create a token. You do not need to return a token here.

​
Update a cart

To update an existing cart by replacing its contents with the provided data, use PUT /merchant-cart/{id}. Use this endpoint to 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 making 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": {...}
}

​
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": "15a93f45-fda1-12ee-7e10-1e0a3bdf2503", //BT nonce
  }
}
Important: Within this endpoint, PayPal passes a Braintree nonce, which you can then use to create a transaction.

​
Merchant cart response

The following 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",
  },
}

​
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.