Overview The Checkout API handles the final steps of the purchase process including payment collection, payment processing, and order completion.
Base Path: /store/cartsSource: packages/medusa/src/api/store/carts/[id]/complete/route.tsCheckout 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 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" : "[email protected] " , "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" } }
Response type: "order" on success or "cart" if action required.
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" } }
Returns "cart" when the cart cannot be completed.
The cart object with current state.
Error details explaining why completion failed.
Source: packages/medusa/src/api/store/carts/[id]/complete/route.ts:13The 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 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.tsPayment Processing Create Payment Session Initialize a payment session with a payment provider.
POST /store/payment-collections/{id}/payment-sessions
Path Parameters The payment collection ID.
Request Body Payment provider ID (e.g., “pp_stripe”, “pp_paypal”).
Provider-specific data required to initialize payment.
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" } } ] } }
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 The payment collection ID.
Request Body 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 Filter by region to get region-specific providers.
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.tsCheckout 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.
{ "type" : "payment_requires_more_error" , "message" : "Additional authentication required" }
Resolution: Customer needs to complete 3D Secure or similar authentication.
{ "type" : "invalid_data" , "message" : "Insufficient inventory for item" }
Resolution: Remove or reduce quantity of out-of-stock items.
Missing Required Information
Source: Error handling logic at packages/medusa/src/api/store/carts/[id]/complete/route.ts:39-73Complete 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": "[email protected] ", "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
Order Module Learn about order management
Customers Manage customer account