Skip to main content
POST
/
merchant-cart
/
{cartId}
/
checkout
curl --request POST \
  --url https://your-domain.com/api/paypal/v1/merchant-cart/{cartId}/checkout \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: <content-type>' \
  --data '{
  "payment_method": {
    "type": "paypal",
    "token": "EC-7U8939823K567",
    "payer_id": "PAYER123456789"
  }
}'
{
  "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"
    }
  }
}

Authorizations

​
Authorization
string
header
required

PayPal-supplied JWT token for authenticating merchant API requests.

Important: These JWT tokens are issued and managed by PayPal, not generated by merchants. PayPal provides these tokens to authenticate calls to your merchant API endpoints.

Usage:

  • Include in Authorization header as "Bearer <paypal-jwt-token>"
  • Token is supplied by PayPal Shopping Cart service
  • Verify token signature using PayPal's public keys
  • Extract merchant identification from token claims

Example:

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Headers

​
Authorization
string
required

PayPal-supplied JWT token for authentication

Example:

"Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

​
Content-Type
string
required

Request content type

Example:

"application/json"

Path Parameters

​
cartId
string
required

The cart identifier

Example:

"CART-123"

Body

application/json
​
payment_method
object
required

Payment method information for PayPal Cart API. This API is specifically designed for PayPal's shopping cart service, so only PayPal payment methods are supported.

Payment Flow:

  1. Cart creation generates a payment token (in payment_method.token)
  2. Customer completes PayPal approval (Smart Wallet)
  3. PayPal provides token and payer_id for checkout
  4. Merchant receives PayPal payment confirmation

Billing Address Behavior:

  • PayPal handles all billing address collection internally for payment processing
  • Merchants can optionally collect billing addresses for tax calculation and business purposes
  • Billing address in cart is for merchant use cases, not payment requirements
  • Billing addresses are typically available from customer profile data

Note: Other payment methods (credit cards, Apple Pay, etc.) would be handled by separate merchant payment systems outside of this PayPal Cart API.

​
checkout_fields
object[]

Final checkout field values

​
accepted_policies
enum<string>[]

Policies accepted by customer

Response

Checkout completed successfully

Unified cart object used for all operations (create, update, checkout, responses). This is the core schema that makes the API simple and consistent.

Request Usage: Include only writable fields (items, customer, shipping_address, billing_address, etc.) Response Usage: Includes all fields, with server-calculated fields marked as readOnly

​
id
string

Unique cart identifier (server-generated)

Example:

"CART-123"

​
status
enum<string>

Current cart business status (server-calculated)

Available options:
CREATED,
INCOMPLETE,
READY,
COMPLETED
Example:

"CREATED"

​
validation_status
enum<string>

Cart data validation status indicating whether the cart can proceed to checkout.

VALID: Cart data is complete and valid, ready for checkout

  • All items are available with current pricing
  • Required information is complete (shipping address, customer data)
  • No business rule violations
  • validation_issues array is empty
  • Can proceed directly to checkout

INVALID: Cart has data issues that prevent checkout

  • Items out of stock, price changes, business rule violations
  • Invalid or incomplete data that needs correction
  • validation_issues array contains specific problems
  • Customer/AI agent must resolve issues before checkout

REQUIRES_ADDITIONAL_INFORMATION: Cart needs more data but is otherwise valid

  • Missing optional but required fields (shipping address, checkout fields)
  • Age verification, custom fields, delivery preferences needed
  • Items and pricing are valid, just needs customer input
  • validation_issues array indicates what information is needed
Available options:
VALID,
INVALID,
REQUIRES_ADDITIONAL_INFORMATION
Example:

"VALID"

​
validation_issues
object[]

List of issues preventing checkout (empty = ready)

​
totals
object

Comprehensive cart pricing breakdown calculated by merchant and returned in all cart responses. All fields are merchant-owned and calculated based on business logic, inventory, shipping rules, and tax regulations.

Merchant Responsibility:

  • Calculate all totals based on items, shipping address, and business rules
  • Ensure accuracy for tax compliance and customer transparency
  • Handle currency consistency across all money fields
  • Apply discounts, shipping rates, and custom charges appropriately

Field Calculation Guidelines:

  • subtotal: Sum of all item prices × quantities (before discounts)
  • discount: Total amount saved from coupons, promotions, and discounts
  • shipping: Calculated shipping cost based on address and selected method
  • tax: Sales tax, VAT, or other applicable taxes based on billing/shipping jurisdiction
  • handling: Processing fees, packaging costs, or handling charges
  • insurance: Optional shipping insurance costs
  • shipping_discount: Discounts applied specifically to shipping costs
  • custom_charges: Additional fees like gift wrapping, expedited processing, etc.
  • total: Final amount customer pays (subtotal - discount + shipping + tax + handling + insurance - shipping_discount + custom_charges)

PayPal Orders API Integration: When creating PayPal orders, custom_charges are typically rolled into the handling field or added as separate line items. The total amount must match the PayPal order total for successful payment capture. Fields map to PayPal Orders API breakdown structure where supported.

​
applied_coupons
object[]

Successfully applied coupons (server-calculated)

​
available_shipping_options
object[]

Available shipping methods with selection state

​
links
object[]

HATEOAS navigation links for cart operations

​
items
object[]

Products in the cart

Minimum length: 1
​
customer
object

Represents customer information for the shopping cart.

​
shipping_address
object

Base address schema used for both shipping and billing addresses. Maps to AddressValidationMetadata and HTML 5.1 Autofilling form controls the autocomplete attribute.

​
billing_address
object

Base address schema used for both shipping and billing addresses. Maps to AddressValidationMetadata and HTML 5.1 Autofilling form controls the autocomplete attribute.

​
payment_method
object

Payment method information for PayPal Cart API. This API is specifically designed for PayPal's shopping cart service, so only PayPal payment methods are supported.

Payment Flow:

  1. Cart creation generates a payment token (in payment_method.token)
  2. Customer completes PayPal approval (Smart Wallet)
  3. PayPal provides token and payer_id for checkout
  4. Merchant receives PayPal payment confirmation

Billing Address Behavior:

  • PayPal handles all billing address collection internally for payment processing
  • Merchants can optionally collect billing addresses for tax calculation and business purposes
  • Billing address in cart is for merchant use cases, not payment requirements
  • Billing addresses are typically available from customer profile data

Note: Other payment methods (credit cards, Apple Pay, etc.) would be handled by separate merchant payment systems outside of this PayPal Cart API.

​
checkout_fields
object[]

Custom checkout fields (age verification, etc.)

​
coupons
object[]

Discount coupons to apply or remove from cart

​
geo_coordinates
object

Optional precise location coordinates for enhanced delivery services

​
payment_confirmation
object
⌘I