Checkout

Overview

The Checkout API handles the final steps of the purchase process including payment collection, payment processing, and order completion. Base Path: /store/carts Source: packages/medusa/src/api/store/carts/[id]/complete/route.ts

Checkout Flow

The typical checkout flow consists of:

Create or retrieve a cart
Add shipping and billing addresses
Select shipping method
Apply promotion codes (optional)
Initialize payment collection
Process payment
Complete the cart to create an order

Complete Cart

Complete the checkout process and create an order from the cart.

POST /store/carts/{id}/complete

Path Parameters

string

required

The cart’s ID.

Request

curl -X POST http://localhost:9000/store/carts/cart_123/complete

Success Response

When the order is successfully created:

{
  "type": "order",
  "order": {
    "id": "order_456",
    "status": "pending",
    "payment_status": "captured",
    "fulfillment_status": "not_fulfilled",
    "display_id": 1001,
    "email": "customer@example.com",
    "currency_code": "usd",
    "items": [
      {
        "id": "item_123",
        "title": "Premium T-Shirt",
        "quantity": 2,
        "unit_price": 2999,
        "total": 5998
      }
    ],
    "shipping_address": {
      "first_name": "John",
      "last_name": "Doe",
      "address_1": "123 Main St",
      "city": "New York",
      "postal_code": "10001",
      "country_code": "us"
    },
    "billing_address": {...},
    "shipping_methods": [
      {
        "name": "Standard Shipping",
        "amount": 500
      }
    ],
    "subtotal": 5998,
    "discount_total": 0,
    "shipping_total": 500,
    "tax_total": 480,
    "total": 6978,
    "created_at": "2024-03-03T12:00:00.000Z"
  }
}

string

Response type: "order" on success or "cart" if action required.

object

The created order object.

Error Response

When additional action is required (e.g., payment authorization failed):

{
  "type": "cart",
  "cart": {
    "id": "cart_123",
    "items": [...],
    "total": 6978
  },
  "error": {
    "message": "Payment authorization failed",
    "name": "MedusaError",
    "type": "payment_authorization_error"
  }
}

string

Returns "cart" when the cart cannot be completed.

object

The cart object with current state.

object

Error details explaining why completion failed.

Source: packages/medusa/src/api/store/carts/[id]/complete/route.ts:13

The complete endpoint uses the workflow engine and may return the cart with errors if the workflow cannot finish (see line 25-30). Common errors include payment failures and inventory issues.

Payment Collection

Initialize Payment Collection

Create a payment collection for the cart.

POST /store/payment-collections

Request Body

string

required

The cart ID to create payment collection for.

Request

curl -X POST http://localhost:9000/store/payment-collections \
  -H "Content-Type: application/json" \
  -d '{
    "cart_id": "cart_123"
  }'

Response

{
  "payment_collection": {
    "id": "paycol_789",
    "cart_id": "cart_123",
    "amount": 6978,
    "currency_code": "usd",
    "status": "not_paid",
    "payment_providers": [
      {
        "id": "pp_stripe",
        "is_enabled": true
      }
    ],
    "created_at": "2024-03-03T11:30:00.000Z"
  }
}

Source: packages/medusa/src/api/store/payment-collections/route.ts

Payment Processing

Create Payment Session

Initialize a payment session with a payment provider.

POST /store/payment-collections/{id}/payment-sessions

Path Parameters

string

required

The payment collection ID.

Request Body

string

required

Payment provider ID (e.g., “pp_stripe”, “pp_paypal”).

object

Provider-specific data required to initialize payment.

object

Additional context for the payment session.

Request

curl -X POST http://localhost:9000/store/payment-collections/paycol_789/payment-sessions \
  -H "Content-Type: application/json" \
  -d '{
    "provider_id": "pp_stripe",
    "data": {
      "payment_method_types": ["card"]
    }
  }'

Response

{
  "payment_collection": {
    "id": "paycol_789",
    "payment_sessions": [
      {
        "id": "ps_stripe_123",
        "provider_id": "pp_stripe",
        "amount": 6978,
        "currency_code": "usd",
        "status": "pending",
        "data": {
          "client_secret": "pi_xxx_secret_yyy"
        }
      }
    ]
  }
}

object

Provider-specific data needed by the client (e.g., Stripe client secret for card processing).

Authorize Payment Session

Authorize a payment session after customer completes payment on the client.

POST /store/payment-collections/{id}/payment-sessions/{session_id}/authorize

Path Parameters

string

required

The payment collection ID.

string

required

The payment session ID.

Request Body

object

Additional authorization context required by the payment provider.

Request

curl -X POST http://localhost:9000/store/payment-collections/paycol_789/payment-sessions/ps_stripe_123/authorize \
  -H "Content-Type: application/json" \
  -d '{}'

Response

{
  "payment_collection": {
    "id": "paycol_789",
    "status": "authorized",
    "authorized_amount": 6978,
    "payment_sessions": [
      {
        "id": "ps_stripe_123",
        "status": "authorized"
      }
    ]
  }
}

Payment Providers

List Payment Providers

Retrieve available payment providers for a region.

GET /store/payment-providers

Query Parameters

string

Filter by region to get region-specific providers.

boolean

Filter by enabled status.

Request

curl -X GET http://localhost:9000/store/payment-providers \
  -G \
  --data-urlencode "region_id=reg_us"

Response

{
  "payment_providers": [
    {
      "id": "pp_stripe",
      "is_enabled": true
    },
    {
      "id": "pp_paypal",
      "is_enabled": true
    }
  ]
}

Source: packages/medusa/src/api/store/payment-providers/route.ts

Checkout Validation

Before completing checkout, ensure:

Cart has items

GET /store/carts/{id}
# Verify cart.items.length > 0

Shipping address is set

POST /store/carts/{id}/shipping-address

Billing address is set
POST /store/carts/{id}/billing-address

Shipping method is selected

POST /store/carts/{id}/shipping-methods

Payment is authorized

POST /store/payment-collections/{id}/payment-sessions/{session_id}/authorize

Email is provided

POST /store/carts/{id}
# Include email in request body

Error Handling

Common Checkout Errors

Payment Authorization Error

{
  "type": "payment_authorization_error",
  "message": "Payment could not be authorized"
}

Resolution: Customer needs to retry payment with valid payment method.

Payment Requires More

{
  "type": "payment_requires_more_error",
  "message": "Additional authentication required"
}

Resolution: Customer needs to complete 3D Secure or similar authentication.

Inventory Error

{
  "type": "invalid_data",
  "message": "Insufficient inventory for item"
}

Resolution: Remove or reduce quantity of out-of-stock items.

Missing Required Information

{
  "type": "invalid_data",
  "message": "Shipping address is required"
}

Resolution: Provide missing cart information before completing.

Source: Error handling logic at packages/medusa/src/api/store/carts/[id]/complete/route.ts:39-73

Complete Checkout Example

Here’s a complete checkout flow:

# 1. Create cart
curl -X POST http://localhost:9000/store/carts \
  -H "Content-Type: application/json" \
  -d '{"region_id": "reg_us"}'

# 2. Add items
curl -X POST http://localhost:9000/store/carts/cart_123/line-items \
  -H "Content-Type: application/json" \
  -d '{"variant_id": "variant_456", "quantity": 2}'

# 3. Set email and shipping address
curl -X POST http://localhost:9000/store/carts/cart_123 \
  -H "Content-Type: application/json" \
  -d '{
    "email": "customer@example.com",
    "shipping_address": {
      "first_name": "John",
      "last_name": "Doe",
      "address_1": "123 Main St",
      "city": "New York",
      "postal_code": "10001",
      "country_code": "us"
    }
  }'

# 4. Add shipping method
curl -X POST http://localhost:9000/store/carts/cart_123/shipping-methods \
  -H "Content-Type: application/json" \
  -d '{"option_id": "so_standard"}'

# 5. Create payment collection
curl -X POST http://localhost:9000/store/payment-collections \
  -H "Content-Type: application/json" \
  -d '{"cart_id": "cart_123"}'

# 6. Initialize payment session
curl -X POST http://localhost:9000/store/payment-collections/paycol_789/payment-sessions \
  -H "Content-Type: application/json" \
  -d '{"provider_id": "pp_stripe"}'

# 7. (Client-side: Complete payment with provider)

# 8. Authorize payment
curl -X POST http://localhost:9000/store/payment-collections/paycol_789/payment-sessions/ps_123/authorize

# 9. Complete cart
curl -X POST http://localhost:9000/store/carts/cart_123/complete

Getting Started

Admin API

Store API

JavaScript SDK

Overview

Checkout Flow

Complete Cart

Path Parameters

Request

Success Response

Error Response

Payment Collection

Initialize Payment Collection

Request Body

Request

Response

Payment Processing

Create Payment Session

Path Parameters

Request Body

Request

Response

Authorize Payment Session

Path Parameters

Request Body

Request

Response

Payment Providers

List Payment Providers

Query Parameters

Request

Response

Checkout Validation

Error Handling

Common Checkout Errors

Complete Checkout Example

Next Steps

Order Module

Customers

​Overview

​Checkout Flow

​Complete Cart

​Path Parameters

​Request

​Success Response

​Error Response

​Payment Collection

​Initialize Payment Collection

​Request Body

​Request

​Response

​Payment Processing

​Create Payment Session

​Path Parameters

​Request Body

​Request

​Response

​Authorize Payment Session

​Path Parameters

​Request Body

​Request

​Response

​Payment Providers

​List Payment Providers

​Query Parameters

​Request

​Response

​Checkout Validation

​Error Handling

​Common Checkout Errors

​Complete Checkout Example

​Next Steps

Order Module

Customers

Overview

Checkout Flow

Complete Cart

Path Parameters

Request

Success Response

Error Response

Payment Collection

Initialize Payment Collection

Request Body

Request

Response

Payment Processing

Create Payment Session

Path Parameters

Request Body

Request

Response

Authorize Payment Session

Path Parameters

Request Body

Request

Response

Payment Providers

List Payment Providers

Query Parameters

Request

Response

Checkout Validation

Error Handling

Common Checkout Errors

Complete Checkout Example

Next Steps