You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: .agents/plugins/commercetools/skills/commercetools-checkout/SKILL.md
+7-7Lines changed: 7 additions & 7 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,8 +1,8 @@
1
1
---
2
2
name: commercetools-checkout
3
-
description: The commercetools Checkout product — payment-only mode (integrating commercetools Checkout for payments while owning the rest of the flow), full hosted checkout (checkoutFlow), widget integration via @commercetools/checkout-browser-sdk, configuration, PSP connector setup (Stripe, Adyen, Mollie), and webhook handling. Use when integrating commercetools Checkout (the product) into a storefront or headless app — not for generic cart-to-order patterns (see commercetools-storefront).
3
+
description: The Checkout — payment-only mode (integrating Checkout for payments while owning the rest of the flow), full hosted checkout (checkoutFlow), widget integration via @commercetools/checkout-browser-sdk, configuration, PSP connector setup (Stripe, Adyen, Mollie), and webhook handling. Use when integrating Checkout (the product) into a storefront or headless app — not for generic cart-to-order patterns (see commercetools-storefront).
4
4
when_to_use:
5
-
- "Integrating the commercetools Checkout product into a storefront or headless app"
5
+
- "Integrating the Checkout into a storefront or headless app"
6
6
- "Setting up payment-only mode while keeping existing address and shipping flows"
7
7
- "Configuring PSP connectors such as Stripe, Adyen, or Mollie"
8
8
- "Handling payment webhooks and order confirmation"
@@ -14,15 +14,15 @@ metadata:
14
14
- psp
15
15
---
16
16
17
-
# commercetools Checkout
17
+
# Checkout
18
18
19
-
The commercetools Checkout product provides hosted payment and checkout experiences via the Browser SDK.
19
+
The Checkout provides hosted payment and checkout experiences via the Browser SDK.
20
20
21
21
## Integration Modes
22
22
23
-
Three modes — choose based on how much of the checkout flow commercetools Checkout should own:
23
+
Three modes — choose based on how much of the checkout flow Checkout should own:
24
24
25
-
-**`paymentFlow`** (payment-only) — keep existing address/shipping UI, replace only the payment step with the commercetools Checkout widget. Least invasive.
25
+
-**`paymentFlow`** (payment-only) — keep existing address/shipping UI, replace only the payment step with the Checkout widget. Least invasive.
26
26
-**`checkoutFlow`** (full hosted) — replace the entire multi-step checkout with a single commercetools-hosted page covering address, shipping, and payment.
27
27
-**`expressPayment`** — add Apple Pay / Google Pay express buttons to cart or PDP. Can coexist with either mode above.
28
28
@@ -48,7 +48,7 @@ When this skill is invoked, always follow these steps:
48
48
## References
49
49
50
50
See [payment-only-mode.md](./references/payment-only-mode.md) for:
51
-
- Full architecture diagram (Browser SDK → commercetools Checkout service → PSP)
51
+
- Full architecture diagram (Browser SDK → Checkout service → PSP)
Copy file name to clipboardExpand all lines: .agents/plugins/commercetools/skills/commercetools-checkout/references/payment-only-mode.md
+15-15Lines changed: 15 additions & 15 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,10 +1,10 @@
1
1
---
2
2
name: payment-only-mode
3
-
description: Implementation guide for integrating the commercetools Checkout Browser SDK with payment-only mode (paymentFlow), full hosted checkout (checkoutFlow), and express payment buttons.
3
+
description: Implementation guide for integrating the Checkout Browser SDK with payment-only mode (paymentFlow), full hosted checkout (checkoutFlow), and express payment buttons.
4
4
when_to_use:
5
-
- "Integrating the commercetools Checkout product into a headless or hosted storefront"
5
+
- "Integrating the Checkout into a headless or hosted storefront"
6
6
- "Replacing only the payment step while keeping existing address and shipping flows"
7
-
- "Setting up Stripe, Adyen, Mollie, or other PSP connectors via commercetools Checkout Applications"
7
+
- "Setting up Stripe, Adyen, Mollie, or other PSP connectors via Checkout Applications"
8
8
- "Implementing order creation via commercetools Sessions API and handling post-payment confirmation"
9
9
metadata:
10
10
contentType: REFERENCE
@@ -15,9 +15,9 @@ metadata:
15
15
- sdk
16
16
---
17
17
18
-
# commercetools Checkout Integration
18
+
# Checkout Integration
19
19
20
-
Adds payment processing via the [commercetools Checkout Browser SDK](https://docs.commercetools.com/checkout/browser-sdk).
20
+
Adds payment processing via the [Checkout Browser SDK](https://docs.commercetools.com/checkout/browser-sdk).
21
21
22
22
---
23
23
@@ -27,7 +27,7 @@ Adds payment processing via the [commercetools Checkout Browser SDK](https://doc
27
27
28
28
1.**Which checkout mode?**
29
29
-`paymentFlow` — payment-only: keep existing address/shipping steps, replace only `StepPayment.tsx` with the commercetools widget. Least invasive.
30
-
-`checkoutFlow` — full page: replace the entire multi-step checkout with a single commercetools-hosted checkout page (addresses, shipping, and payment all handled by commercetools Checkout).
30
+
-`checkoutFlow` — full page: replace the entire multi-step checkout with a single commercetools-hosted checkout page (addresses, shipping, and payment all handled by Checkout).
31
31
-`expressPayment` — express buttons: add Apple Pay / Google Pay buttons to the cart or PDP. Can coexist with either of the above.
32
32
33
33
2.**Which PSP (Payment Service Provider)?**
@@ -38,9 +38,9 @@ Adds payment processing via the [commercetools Checkout Browser SDK](https://doc
38
38
## Architecture Overview
39
39
40
40
```
41
-
Browser (SDK) → commercetools Checkout service → PSP
41
+
Browser (SDK) → Checkout service → PSP
42
42
↑
43
-
/api/checkout/session (creates commercetools Checkout Session from cart)
43
+
/api/checkout/session (creates Checkout Session from cart)
44
44
↑
45
45
commercetools Sessions API (POST https://session.{region}.commercetools.com/{projectKey}/sessions)
46
46
```
@@ -54,7 +54,7 @@ The storefront creates a **Checkout Session** (server-side, via a new API route)
54
54
### 0a. Add environment variables to `site/.env`
55
55
56
56
```bash
57
-
# The key of your commercetools Checkout Application
57
+
# The key of your Checkout Application
58
58
CTP_CHECKOUT_APP_KEY=storefront-checkout
59
59
```
60
60
@@ -182,19 +182,19 @@ export default function StepPayment() {
182
182
183
183
In Checkout page, the payment step should render the PaymentStep.tsx
184
184
185
-
> **Note**: With `paymentFlow`, commercetools Checkout handles the payment AND the **order is created by commercetools** automatically when payment succeeds (via the `paymentReturnUrl` configured in the Application).
185
+
> **Note**: With `paymentFlow`, Checkout handles the payment AND the **order is created by commercetools** automatically when payment succeeds (via the `paymentReturnUrl` configured in the Application).
186
186
187
187
---
188
188
189
-
## Step 3 — Order confirmation after commercetools Checkout
189
+
## Step 3 — Order confirmation after Checkout
190
190
191
-
commercetools Checkout navigates the browser to `paymentReturnUrl` after a successful payment, appending `?orderId=<id>` (or `?orderNumber=<n>`). Update the confirmation page to read these params:
191
+
Checkout navigates the browser to `paymentReturnUrl` after a successful payment, appending `?orderId=<id>` (or `?orderNumber=<n>`). Update the confirmation page to read these params:
192
192
193
193
---
194
194
195
195
## Step 5 — Styling
196
196
197
-
Optional: Override commercetools Checkout widget styles via the `styles` option (CSS custom properties):
197
+
Optional: Override Checkout widget styles via the `styles` option (CSS custom properties):
198
198
199
199
```typescript
200
200
checkoutFlow({
@@ -208,15 +208,15 @@ checkoutFlow({
208
208
});
209
209
```
210
210
211
-
Available CSS variables are listed in the commercetools Checkout theming docs.
211
+
Available CSS variables are listed in the Checkout theming docs.
212
212
213
213
---
214
214
215
215
## Environment Variable Summary
216
216
217
217
| Variable | Secret? | Purpose |
218
218
|---|---|---|
219
-
|`CTP_CHECKOUT_APP_KEY`| No |**New** — key of the commercetools Checkout Application |
219
+
|`CTP_CHECKOUT_APP_KEY`| No |**New** — key of the Checkout Application |
220
220
221
221
222
222
No `CT_REGION`, `NEXT_PUBLIC_CT_PROJECT_KEY`, or `NEXT_PUBLIC_CT_REGION` variables are needed. The session API derives the region from `CTP_API_URL` and returns `{ sessionId, projectKey, region }` to the browser.
1.**Addresses step** — shipping and billing addresses persisted to cart when moving to the next step. All cart writes use the as-associate chain — see the [reference](./cart.md).
44
44
2.**Shipping step** — user selects a method with `shippingMethodId`
45
-
3.**Payment step** — commercetools checkout frontend SDK mounts and handles payment capture and order placement. If a PO Number payment method is configured in the commercetools checkout frontend SDK, it will appear automatically — no custom PO Number field is needed in the checkout form.
45
+
3.**Payment step** — Checkout frontend SDK mounts and handles payment capture and order placement. If a PO Number payment method is configured in the Checkout frontend SDK, it will appear automatically — no custom PO Number field is needed in the checkout form.
46
46
4.**Confirmation** — SDK signals completion → clear `cartId` from session → redirect to `/checkout/confirmation?orderId=<id>`
47
47
48
-
Order placement is handled entirely by the commercetools checkout frontend SDK. Do not implement a separate `POST /api/checkout` route for order creation.
48
+
Order placement is handled entirely by the Checkout frontend SDK. Do not implement a separate `POST /api/checkout` route for order creation.
49
49
50
-
> **Reference:** See the [commercetools checkout frontend SDK](../../../commercetools-checkout/references/payment-only-mode.md) implementation skill for SDK setup and the order-completion event handler.
50
+
> **Reference:** See the [Checkout frontend SDK](../../../commercetools-checkout/references/payment-only-mode.md) implementation skill for SDK setup and the order-completion event handler.
51
51
52
52
### BU + Store Validation
53
53
@@ -102,8 +102,8 @@ After submission, the quote progresses through seller review and negotiation. Se
1.**Addresses step** — shipping and billing addresses persisted to cart in real time
37
37
2.**Shipping step** — user selects a method
38
-
3.**Payment step** — commercetools checkout frontend SDK mounts, handles payment capture and order placement
38
+
3.**Payment step** — Checkout frontend SDK mounts, handles payment capture and order placement
39
39
4.**Confirmation** — SDK signals completion → clear `cartId` from session → redirect to `/checkout/confirmation?orderId=<id>`
40
40
41
-
Order placement is handled entirely by the commercetools checkout frontend SDK on the payment step. Do not implement a separate `POST /api/checkout` route for order creation.
41
+
Order placement is handled entirely by the Checkout frontend SDK on the payment step. Do not implement a separate `POST /api/checkout` route for order creation.
42
42
43
-
> **Reference:** See the [commercetools checkout frontend SDK](../../../commercetools-checkout/references/payment-only-mode.md) implementation skill for SDK setup and the order-completion event handler.
43
+
> **Reference:** See the [Checkout frontend SDK](../../../commercetools-checkout/references/payment-only-mode.md) implementation skill for SDK setup and the order-completion event handler.
44
44
45
45
---
46
46
@@ -51,5 +51,5 @@ Order placement is handled entirely by the commercetools checkout frontend SDK o
51
51
-[ ] Saved address list shown as selectable options; manual entry also allowed
52
52
-[ ] Address changes debounced to `PATCH /api/cart` (inherited from shared)
53
53
-[ ] Shipping method filtered by session currency (inherited from shared)
54
-
-[ ] Order placement driven by commercetools checkout frontend SDK — no custom order route
54
+
-[ ] Order placement driven by Checkout frontend SDK — no custom order route
55
55
-[ ]`cartId` cleared from session after SDK order completion event
Copy file name to clipboardExpand all lines: .agents/plugins/commercetools/skills/commercetools-storefront/references/b2c/overview.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -15,7 +15,7 @@ metadata:
15
15
16
16
# Next.js + commercetools B2C Storefront
17
17
18
-
Production-tested patterns for building a B2C storefront on commercetools with Next.js 16, TypeScript, Tailwind v4, and JWT sessions. Derived from the b2c-starter-kit — a working production storefront.
18
+
Production-tested patterns for building a B2C storefront on commercetools with Next.js 16, TypeScript, Tailwind v4, and JWT sessions.
19
19
20
20
> **Shared foundation:** BFF architecture, JWT session setup, commercetools SDK singleton, project scaffold, `COUNTRY_CONFIG`, performance patterns, image config, Vercel deployment, and the shared auth base are in the `commercetools-storefront` skill. Load that skill alongside this one when starting a new project.
- "Integrating the payment step with commercetools checkout SDK"
7
+
- "Integrating the payment step with Checkout SDK"
8
8
- "Handling order confirmation pages"
9
9
metadata:
10
10
contentType: REFERENCE
@@ -17,13 +17,13 @@ metadata:
17
17
18
18
**Impact: HIGH — The checkout route is the revenue path. A failed order placement or stale cart version drops the conversion entirely.**
19
19
20
-
This reference covers the shared checkout structure used by both B2C and B2B storefronts: the multi-step page shell, shipping method selection, payment via the commercetools checkout frontend SDK, and the confirmation page. Address step details and order placement are storefront-specific — see the relevant extension file.
20
+
This reference covers the shared checkout structure used by both B2C and B2B storefronts: the multi-step page shell, shipping method selection, payment via the Checkout frontend SDK, and the confirmation page. Address step details and order placement are storefront-specific — see the relevant extension file.
The payment step is handled entirely by the commercetools checkout frontend SDK, which renders the full payment UI and drives order placement.
126
+
The payment step is handled entirely by the Checkout frontend SDK, which renders the full payment UI and drives order placement.
127
127
128
-
> **Reference:** See the [commercetools checkout frontend SDK](../../../commercetools-checkout/references/payment-only-mode.md) implementation skill for full setup, component mounting, and event handling.
128
+
> **Reference:** See the [Checkout frontend SDK](../../../commercetools-checkout/references/payment-only-mode.md) implementation skill for full setup, component mounting, and event handling.
129
129
130
130
Key rules:
131
131
- Do not implement a custom payment form — mount the SDK component and let it manage the flow.
@@ -169,6 +169,6 @@ Both flows (cart checkout and quote checkout) redirect to `/checkout/confirmatio
169
169
-[ ] Step skip guards redirect back if prerequisites are not met
170
170
-[ ]`GET /api/shipping-methods` filters by session currency
171
171
-[ ] Address changes debounced to update cart address method
172
-
-[ ] Payment step mounts the commercetools checkout frontend SDK — no custom payment form
172
+
-[ ] Payment step mounts the Checkout frontend SDK — no custom payment form
173
173
-[ ]`cartId` cleared from session after the SDK signals order completion
174
174
-[ ] Confirmation page is a Server Component that fetches order by ID from commercetools
0 commit comments