Skip to content

Commit 0dcd579

Browse files
prateek-ctprateek-ct
authored
Merge pull request #3 from commercetools/ct-checkout-example
adding commercetools Checkout example
2 parents d7f4c4c + cadb9c2 commit 0dcd579

22 files changed

+21487
-0
lines changed

‎README.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,13 @@ AI-native integrations for modern LLM applications
2626
- **Features**: MCP server offering 60+ commerce based tools
2727
- **Full guide**: [commerce-mcp/essentials-mcp/README.md](commerce-mcp/essentials-mcp/README.md)
2828

29+
### 📦 **Checkout**
30+
commercetools Checkout integration using Browser SDK
31+
- **Location**: `checkout/`
32+
- **Best for**: Prebuilt checkout component including payment integrations
33+
- **Features**: Full SDK access, type safety, complete control over API calls
34+
- **Full guide**: [checkout/README.md](checkout/README.md)
35+
2936
## 🚀 Quick Start
3037

3138
### For AI/LLM Applications
@@ -42,6 +49,16 @@ cd composable-commerce
4249
npm install
4350
```
4451

52+
### For precomposed Checkout
53+
```bash
54+
git clone https://github.com/commercetools/hackathon-starter-kit.git
55+
cd checkout
56+
npm run setup
57+
# Configure .env with your credentials and Checkout Application ID
58+
npm run build-client && npm run start-client
59+
npm run start-server
60+
```
61+
4562
## 💡 Sample Implementations & Use Cases
4663

4764
### 🎯 **AI-Powered Commerce Assistant** (Essentials + Developer MCP)
@@ -65,6 +82,18 @@ Traditional service layer applications with:
6582

6683
**Examples**: `composable-commerce/src/examples/`
6784

85+
### 💳 **Checkout Integration Example** (commercetools Checkout)
86+
Complete React e-commerce application with embedded checkout:
87+
- **Full Shopping Experience**: Product catalog, cart management, and checkout
88+
- **Embedded Payments**: Secure payment processing with commercetools Checkout
89+
- **Multiple Payment Methods**: Credit cards, PayPal, and more
90+
- **Order Completion**: Success pages and order confirmation
91+
- **Responsive Design**: Works on desktop and mobile
92+
- **Real-time Updates**: Cart and checkout state management
93+
94+
**Framework**: `checkout/`
95+
**Full guide**: [checkout/README.md](checkout-example/README.md)
96+
6897
## 🔑 Project Setup
6998

7099
### 1. Create or use a commercetools account

‎checkout/.env.example‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# commercetools Platform Configuration
2+
CTP_PROJECT_KEY=your-project-key
3+
CTP_CLIENT_ID=your-client-id
4+
CTP_CLIENT_SECRET=your-client-secret
5+
CTP_AUTH_URL=https://auth.europe-west1.gcp.commercetools.com
6+
CTP_API_URL=https://api.europe-west1.gcp.commercetools.com
7+
CTP_SCOPES=manage_project:your-project-key manage_payments:your-project-key manage_sessions:your-project-key
8+
9+
# commercetools Checkout Configuration
10+
# Get the Application Key from Merchant Center > Settings > Checkout
11+
CHECKOUT_APPLICATION_ID=your-checkout-application-key
12+
# Session API URL (adjust region as needed)
13+
SESSION_API_URL=https://session.europe-west1.gcp.commercetools.com
14+
15+
# Server Configuration
16+
PORT=3001
17+
CLIENT_PORT=3000

‎checkout/README.md‎

Lines changed: 192 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,192 @@
1+
# commercetools Checkout Example
2+
3+
A complete React-based e-commerce application demonstrating commercetools Checkout integration with embedded payment processing, cart management, and order completion.
4+
5+
## 🚀 Features
6+
7+
- **Product Catalog**: Browse products from your commercetools project
8+
- **Shopping Cart**: Add, update, and remove items
9+
- **Embedded Checkout**: Secure payment processing with commercetools Checkout
10+
- **Order Completion**: Success page with order confirmation
11+
- **Responsive Design**: Works on desktop and mobile devices
12+
- **Real-time Updates**: Cart and checkout state management
13+
14+
## 📋 Prerequisites
15+
16+
Before running this example, you need:
17+
18+
### 1. commercetools Project Setup
19+
- commercetools account and project
20+
- API client credentials with required scopes
21+
- Sample products in your project (or import using the import example)
22+
- Shipping methods configured with rates
23+
- Configure taxes with rates for address being used for testing
24+
25+
### 2. commercetools Checkout Application Setup
26+
This is the **critical step** - you must set up a Checkout application in Merchant Center:
27+
28+
#### Step-by-Step Checkout Setup:
29+
30+
1. **Login to Merchant Center**
31+
```
32+
https://mc.europe-west1.gcp.commercetools.com
33+
```
34+
35+
2. **Navigate to Settings > Checkout**
36+
- In the left sidebar: Settings → Checkout
37+
- If you don't see "Checkout", ensure your project has Checkout enabled
38+
39+
3. **Configure Checkout Application**
40+
- Use sample Checkout application
41+
- Change Origin URLs to "Allow all URLs to communicate to the checkout application" for testing purposes
42+
43+
4. **Configure Payment Methods**
44+
- In the Checkout application settings
45+
- Configure Payment Integrations , install Sample payment connector
46+
- Add payment methods (card etc.) and enable them
47+
48+
5. **Copy Application ID**
49+
- After configuration, copy the **Application Key**
50+
- You'll need this for your `.env` file
51+
52+
## 🛠 Installation & Setup
53+
54+
### 1. Clone and Install
55+
56+
```bash
57+
# From the hackathon-starter-kit root
58+
cd checkout
59+
60+
# Install server & client dependencies
61+
npm run setup
62+
63+
64+
### 2. Environment Configuration
65+
66+
```bash
67+
# Copy environment template
68+
cp .env.example .env
69+
cp /client/.env.example /client/.env
70+
```
71+
72+
Edit `.env` with your credentials:
73+
74+
```env
75+
# commercetools Platform Configuration
76+
CTP_PROJECT_KEY=your-project-key
77+
CTP_CLIENT_ID=your-client-id
78+
CTP_CLIENT_SECRET=your-client-secret
79+
CTP_AUTH_URL=https://auth.europe-west1.gcp.commercetools.com
80+
CTP_API_URL=https://api.europe-west1.gcp.commercetools.com
81+
CTP_SCOPES=manage_orders:your-project-key manage_customers:your-project-key view_shipping_methods:your-project-key view_cart_discounts:your-project-key view_discount_codes:your-project-key view_tax_categories:your-project-key view_sessions:your-project-key view_categories:your-project-key view_products:your-project-key view_published_products:your-project-key view_project_settings:your-project-key create_anonymous_token:your-project-key view_standalone_prices:your-project-key manage_shopping_lists:your-project-key manage_order_edits:your-project-key view_product_selections:your-project-key view_types:your-project-key manage_sessions:your-project-key
82+
83+
# commercetools Checkout Configuration
84+
CHECKOUT_APPLICATION_ID=your-checkout-application-id-from-step-5-above
85+
CHECKOUT_APPLICATION_URL=https://checkout.europe-west1.gcp.commercetools.com
86+
87+
# Server Configuration
88+
PORT=3001
89+
CLIENT_PORT=3000
90+
```
91+
92+
Edit client `.env` with your project:
93+
94+
```env
95+
REACT_APP_CTP_PROJECT_KEY=your-project-key
96+
```
97+
98+
99+
## 🎯 Running the Application
100+
101+
### Development Mode
102+
103+
```bash
104+
# Start server
105+
npm run start-server
106+
```
107+
108+
```bash
109+
# Start client
110+
npm run build-client
111+
npm run start-client
112+
```
113+
114+
This starts:
115+
- **Backend server**: http://localhost:3001
116+
- **React client**: http://localhost:3000
117+
118+
119+
## 🧪 Testing the Checkout Flow
120+
121+
### 1. Browse Products
122+
- Navigate to http://localhost:3000
123+
- Products should load from your commercetools project
124+
- Add items to cart
125+
126+
### 2. View Cart
127+
- Click the cart icon (should show item count)
128+
- Verify items, quantities, and pricing
129+
- Proceed to checkout
130+
131+
### 3. Complete Checkout
132+
- Fill in shipping/billing information
133+
- Use test card numbers for testing:
134+
- **Visa**: 4111111111111111
135+
- **Expiry**: Any future date
136+
- **CVV**: Any 3-digit number
137+
138+
### 4. Order Completion
139+
- Should redirect to success page
140+
- Order ID should be displayed
141+
- Cart should be cleared
142+
143+
## 🚨 Troubleshooting
144+
145+
### Common Issues
146+
147+
#### 1. "CHECKOUT_APPLICATION_ID not set"
148+
**Cause**: Missing or incorrect checkout application ID
149+
**Solution**:
150+
- Verify the Application ID in Merchant Center → Settings → Checkout
151+
- Ensure `.env` file has correct `CHECKOUT_APPLICATION_ID`
152+
153+
#### 2. "Failed to create checkout session"
154+
**Causes**:
155+
- Incorrect API credentials
156+
- Missing cart or invalid cart ID
157+
- Checkout application not properly configured
158+
159+
**Solutions**:
160+
- Check API client scopes include `manage_payments`
161+
- Verify cart exists and has items
162+
- Confirm checkout application is active in Merchant Center
163+
164+
#### 3. "No products found"
165+
**Cause**: Empty commercetools project
166+
**Solution**: Import sample products using the import example
167+
168+
#### 4. Checkout SDK fails to load
169+
**Causes**:
170+
- CORS issues
171+
- Invalid session URL
172+
- Network connectivity
173+
174+
**Solutions**:
175+
- Check browser console for CORS errors
176+
- Verify allowed origins in checkout application settings
177+
- Use fallback checkout URL provided in the UI
178+
179+
#### 5. Payments fail in test mode
180+
**Cause**: Test payment processor not configured
181+
**Solution**:
182+
- Enable test mode in checkout application
183+
- Use valid test card numbers
184+
- Check payment processor logs in Merchant Center
185+
186+
187+
## 📖 Additional Resources
188+
189+
### commercetools Documentation
190+
- [Checkout Documentation](https://docs.commercetools.com/checkout)
191+
- [Checkout Browser SDK](https://docs.commercetools.com/checkout/browser-sdk)
192+
- [Payment Connectors](https://docs.commercetools.com/checkout/connectors-and-applications)

‎checkout/client/.env.example‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# React environment variables (must start with REACT_APP_)
2+
REACT_APP_CTP_PROJECT_KEY=consulting
3+
REACT_APP_CHECKOUT_APPLICATION_ID=demo-commercetools-checkout-taxes

0 commit comments

Comments
 (0)