If you accept cookies, we’ll use them to improve and customize your experience and enable our partners to show you personalized PayPal ads when you visit other sites. Manage cookies and learn more
After you set up your product catalog and catalog ingestion, the next step is to integrate with the PayPal endpoints that create and manage shopping carts. By the end of this guide, you will have implemented the 3 core cart endpoints and chosen a payment integration pattern — either PayPal Orders API v2 or Braintree — to support AI-driven checkout through your store.
Before you set up your API, it helps to understand the different roles and steps in the agentic shopping flow. This flow involves 3 main parties: the customer, the AI agent, and your (merchant) API. The AI agent acts as an intermediary that understands the customer's intent and interacts with PayPal's Cart API on your behalf.
To integrate Store Sync with your API, you must meet the following requirements:
Be an existing PayPal merchant. If you are not yet a PayPal merchant, complete onboarding first. For help with onboarding, contact your PayPal account manager or customer support.
Use PayPal Orders API v2 or support an Orders v2 integration if you want to use PayPal's Orders API v2 for payment processing or Braintree if you plan to use Braintree for payment processing. For details about both integration patterns, see Choose an integration pattern.
Create your product catalog and set up catalog ingestion. For information about creating your product catalog, see Create a product catalog.
The following PayPal Cart API endpoints are used in this integration. PayPal calls these endpoints on your merchant API — you implement them, and PayPal invokes them during the agentic shopping flow.
Method, Endpoint, Description
Method
Endpoint
Description
POST
/merchant-cart
Creates a new shopping cart with items, customer, and payment information.
PUT
/merchant-cart/{id}
Replaces an existing cart's contents. This is a full replacement, not a partial update.
POST
/merchant-cart/{id}/checkout
Finalizes the purchase and processes payment using the specified payment method.
Now that you understand the agentic shopping flow, choose one of the following payment integration patterns to implement your API. Both patterns enable you to support AI-driven shopping experiences, but they differ in how you handle payment processing. Choose the pattern that best fits your existing payment setup and technical preferences.
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 using Orders API v2 for payment processing.
This section includes the PayPal Orders API v2 integration pattern. If you use
Braintree for payment processing, see the Braintree integration section.
Use POST /merchant-cart to create a new shopping cart with specified items. The cart can also include customer information such as a shipping address and payment method.
Results: PayPal receives the cart and returns cart details including a status of CREATED, a validation_status, and a payment_method.token containing the PayPal order ID. See Cart response for create and update endpoints.
Use PUT /merchant-cart/{id} to update an existing cart by replacing its contents with the provided data. You can add or remove items, change quantities, update the shipping address, apply discounts, and more.
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 to a cart.
Results: PayPal receives the updated cart and returns the full cart object with recalculated totals and an updated validation_status. See Cart response for create and update endpoints.
Results: PayPal captures the payment and returns a completed cart response with status of COMPLETED and a payment_confirmation object containing your order number and a review URL. See Complete checkout response.
The PayPal Cart API integrates with Orders API v2 to manage payment tokens and process transactions. When implementing the Cart API, you must integrate with Orders API v2 to handle payment tokens and order updates.
The following table explains when to create (POST) or update (PATCH) a PayPal order.
Scenario, Orders API action, Reason
Scenario
Orders API action
Reason
Create a cart.
POST /v2/orders
Create 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 the shipping address.
PATCH /v2/orders/{id}
Update shipping and tax.
Change quantities.
PATCH /v2/orders/{id}
Update totals.
Payment token expires.
POST /v2/orders
Create a fresh payment context.
Create a new cart after checkout.
POST /v2/orders
Prepare for a new transaction.
Capture an order.
POST /v2/checkout/orders/{id}/capture
Capture the payment.
For information about error handling and other response handling, see the
response handling documentation for this guide.
Download the Postman collection for example requests covering all Cart API endpoints. Use it as a reference when building and testing your API.
To enable AI agents to create and manage shopping carts through your store, you integrate your API with PayPal's Cart API. This guide shows you how to implement the 3 core endpoints that handle cart creation, updates, and checkout completion using Braintree for payment processing.
Use POST /merchant-cart to create a new shopping cart with specified items. The cart can also include customer information such as a shipping address and payment method.
Results: PayPal uses your Braintree credentials to create a token and returns cart details including a status of CREATED and a validation_status. You do not need to return a token in this response. See Create and update cart response.
Use PUT /merchant-cart/{id} to update an existing cart by replacing its contents with the provided data. You can add or remove items, change quantities, update the shipping address, apply discounts, and more.
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 to a cart.
Results: PayPal receives the updated cart and returns the full cart object with recalculated totals and an updated validation_status. See Create and update cart response.
Use POST /merchant-cart/{id}/checkout to finalize the purchase by processing the payment. PayPal passes a Braintree nonce in the request, which you can then use to create a transaction.
Results: PayPal passes the Braintree nonce to your API. Use the nonce to create a transaction with Braintree, then return a completed cart response with status of COMPLETED and a payment_confirmation object. See Complete checkout response.
To handle Cart API responses effectively and provide AI agents with the context they need for intelligent decision-making, understand the status fields and error patterns throughout the shopping cart lifecycle. This guide explains how to interpret cart status indicators, handle validation issues, and implement proper error responses that enable automatic problem resolution.
The validation_issues array communicates business logic problems that prevent cart completion but don't require 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.
The following table summarizes the key fields and values in a validation issue object.
The following example shows the minimum structure for a validation issue with required fields only. This format provides basic information about the problem but lacks rich context that you can use to resolve the issue.
For rich context that supports AI agents, include detailed information and resolution options. Each code can map to a series of specific_issue values. For details, see the protocol reference.
{ "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 } } ]}
For business scenarios that AI agents can understand and potentially resolve, return 200 OK and communicate the issue through validation_issues, for example:
Cart validation issues (out of stock, price changes)
Missing required information (shipping address, checkout fields)
Payment processing issues (declined payments, business rules)
The following sections describe the standard HTTP error codes for technical problems. For additional guidance about which codes to use, see Error handling implementation strategy.
Effective error handling is critical for maintaining a smooth shopping experience. The Cart API provides rich error context that enables AI agents to resolve issues automatically or guide customers to resolution.
Instead of handling dozens of specific error cases, focus on these essential patterns:
Can you fix this automatically? If so, fix it for the customer.
The Cart API organizes validation issues into logical categories that help AI agents understand the nature of problems and apply appropriate resolution strategies.
Most validation errors follow this structure, with clear user messaging and actionable options.
{ "code": "INVENTORY_ISSUE", "user_message": "Blue T-Shirt is out of stock. Try a different color?", "resolution_options": [ { "action": "SUGGEST_ALTERNATIVE", "label": "View other colors" }, { "action": "REMOVE_ITEM", "label": "Remove from cart" } ]}
Use the following guidelines to determine the appropriate HTTP status code for each error scenario.
200 OK and validation_issues
Use 200 OK for business logic issues that can be communicated through the validation_issues array. This allows AI agents to understand the problem and apply intelligent resolutions without needing to handle HTTP errors. Examples include:
Inventory changes (out of stock, back-ordered)
Price changes during checkout
Payment processing issues that can be resolved
Geographic restrictions
Discount validation failures
Customer account issues
Address validation problems
422 Unprocessable Entity
Use 422 only when the request is semantically valid but you must reject it entirely and cannot create a cart. If the cart can still be created and the problem can be surfaced for agent resolution, return 200 OK with validation_issues instead, including for inventory-related issues such as an item being out of stock.
400 Bad request
Use 400 for malformed requests where client-side issues prevent processing. Examples include:
Invalid JSON format
Missing required fields (for example, the items array)
Invalid field types or formats
Malformed request structure
Invalid cart ID format (for example, an ID that doesn't match an expected pattern such as CART-[A-Z0-9]+)
404 Not found
Use 404 when a well-formed request references a resource that doesn't exist. Examples include:
A cart ID that doesn't exist in the merchant's system (well-formed ID, but not found)
The following examples use PUT /merchant-cart/{cartId}.
Example: Invalid cart ID format (400 response)
When the cart ID doesn't match your expected format, return detailed validation information.
{ "name": "INVALID_CART_ID", "message": "Cart ID format is invalid. Expected format: CART-[A-Z0-9]+", "debug_id": "ERROR-400-CART-FORMAT", "details": [ { "field": "cartId", "issue": "INVALID_FORMAT", "description": "Cart ID format is invalid. Expected format: CART-[A-Z0-9]+. Provided: invalid-cart-id-123" } ]}
Example: Cart not found (404 response)
When a well-formed cart ID doesn't exist in your system, provide clear guidance.
{ "name": "CART_NOT_FOUND", "message": "Cart with ID 'CART-MISSING-123' does not exist", "debug_id": "ERROR-404-12345", "details": [ { "field": "cartId", "issue": "NOT_FOUND", "description": "Cart with ID 'CART-MISSING-123' does not exist for merchant 'MERCHANT_789'. Verify the cart ID or create a new cart." } ]}
The Cart API supports various resolution actions that AI agents can use to automatically resolve validation issues. The auto_applicable field indicates whether the action can be applied without customer intervention.
Continue by reviewing some Store Sync integration use cases to see how these API responses and error handling patterns come together in real-world scenarios. These examples will help you understand how to implement your API to support intelligent, agentic shopping experiences.