> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/medusajs/medusa/llms.txt
> Use this file to discover all available pages before exploring further.

# Checkout

> Store API endpoints for completing the checkout process and creating orders.

## 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:

1. Create or retrieve a cart
2. Add shipping and billing addresses
3. Select shipping method
4. Apply promotion codes (optional)
5. Initialize payment collection
6. Process payment
7. Complete the cart to create an order

## Complete Cart

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

```bash theme={null}
POST /store/carts/{id}/complete
```

### Path Parameters

<ParamField path="id" type="string" required>
  The cart's ID.
</ParamField>

### Request

```bash theme={null}
curl -X POST http://localhost:9000/store/carts/cart_123/complete
```

### Success Response

When the order is successfully created:

```json theme={null}
{
  "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"
  }
}
```

<ResponseField name="type" type="string">
  Response type: `"order"` on success or `"cart"` if action required.
</ResponseField>

<ResponseField name="order" type="object">
  The created order object.
</ResponseField>

### Error Response

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

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

<ResponseField name="type" type="string">
  Returns `"cart"` when the cart cannot be completed.
</ResponseField>

<ResponseField name="cart" type="object">
  The cart object with current state.
</ResponseField>

<ResponseField name="error" type="object">
  Error details explaining why completion failed.
</ResponseField>

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

<Note>
  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.
</Note>

## Payment Collection

### Initialize Payment Collection

Create a payment collection for the cart.

```bash theme={null}
POST /store/payment-collections
```

### Request Body

<ParamField body="cart_id" type="string" required>
  The cart ID to create payment collection for.
</ParamField>

### Request

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

### Response

```json theme={null}
{
  "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.

```bash theme={null}
POST /store/payment-collections/{id}/payment-sessions
```

### Path Parameters

<ParamField path="id" type="string" required>
  The payment collection ID.
</ParamField>

### Request Body

<ParamField body="provider_id" type="string" required>
  Payment provider ID (e.g., "pp\_stripe", "pp\_paypal").
</ParamField>

<ParamField body="data" type="object">
  Provider-specific data required to initialize payment.
</ParamField>

<ParamField body="context" type="object">
  Additional context for the payment session.
</ParamField>

### Request

```bash theme={null}
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

```json theme={null}
{
  "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"
        }
      }
    ]
  }
}
```

<ResponseField name="data" type="object">
  Provider-specific data needed by the client (e.g., Stripe client secret for card processing).
</ResponseField>

### Authorize Payment Session

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

```bash theme={null}
POST /store/payment-collections/{id}/payment-sessions/{session_id}/authorize
```

### Path Parameters

<ParamField path="id" type="string" required>
  The payment collection ID.
</ParamField>

<ParamField path="session_id" type="string" required>
  The payment session ID.
</ParamField>

### Request Body

<ParamField body="context" type="object">
  Additional authorization context required by the payment provider.
</ParamField>

### Request

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

### Response

```json theme={null}
{
  "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.

```bash theme={null}
GET /store/payment-providers
```

### Query Parameters

<ParamField query="region_id" type="string">
  Filter by region to get region-specific providers.
</ParamField>

<ParamField query="is_enabled" type="boolean">
  Filter by enabled status.
</ParamField>

### Request

```bash theme={null}
curl -X GET http://localhost:9000/store/payment-providers \
  -G \
  --data-urlencode "region_id=reg_us"
```

### Response

```json theme={null}
{
  "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:

1. **Cart has items**
   ```bash theme={null}
   GET /store/carts/{id}
   # Verify cart.items.length > 0
   ```

2. **Shipping address is set**
   ```bash theme={null}
   POST /store/carts/{id}/shipping-address
   ```

3. **Billing address is set**
   ```bash theme={null}
   POST /store/carts/{id}/billing-address
   ```

4. **Shipping method is selected**
   ```bash theme={null}
   POST /store/carts/{id}/shipping-methods
   ```

5. **Payment is authorized**
   ```bash theme={null}
   POST /store/payment-collections/{id}/payment-sessions/{session_id}/authorize
   ```

6. **Email is provided**
   ```bash theme={null}
   POST /store/carts/{id}
   # Include email in request body
   ```

## Error Handling

### Common Checkout Errors

<AccordionGroup>
  <Accordion title="Payment Authorization Error">
    ```json theme={null}
    {
      "type": "payment_authorization_error",
      "message": "Payment could not be authorized"
    }
    ```

    **Resolution:** Customer needs to retry payment with valid payment method.
  </Accordion>

  <Accordion title="Payment Requires More">
    ```json theme={null}
    {
      "type": "payment_requires_more_error",
      "message": "Additional authentication required"
    }
    ```

    **Resolution:** Customer needs to complete 3D Secure or similar authentication.
  </Accordion>

  <Accordion title="Inventory Error">
    ```json theme={null}
    {
      "type": "invalid_data",
      "message": "Insufficient inventory for item"
    }
    ```

    **Resolution:** Remove or reduce quantity of out-of-stock items.
  </Accordion>

  <Accordion title="Missing Required Information">
    ```json theme={null}
    {
      "type": "invalid_data",
      "message": "Shipping address is required"
    }
    ```

    **Resolution:** Provide missing cart information before completing.
  </Accordion>
</AccordionGroup>

**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:

```bash theme={null}
# 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
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Order Module" icon="receipt" href="/modules/order">
    Learn about order management
  </Card>

  <Card title="Customers" icon="user" href="/api/store/customers">
    Manage customer account
  </Card>
</CardGroup>