o2sdev · marcinkrasowski · Feb 19, 2026 · Feb 9, 2026 · Feb 12, 2026 · Feb 12, 2026
diff --git a/.changeset/easy-sides-enjoy.md b/.changeset/easy-sides-enjoy.md
@@ -0,0 +1,5 @@
+---
+'@o2s/integrations.medusajs': minor
+---
+
+Medusa.js integration implementations for carts, checkout, customers, and payments.
diff --git a/.changeset/good-webs-wish.md b/.changeset/good-webs-wish.md
@@ -0,0 +1,5 @@
+---
+'@o2s/blocks.product-list': patch
+---
+
+removed permission check from `ProductList` block as it should be accessible also for unauthenticated users
diff --git a/.changeset/lucky-sides-battle.md b/.changeset/lucky-sides-battle.md
@@ -0,0 +1,9 @@
+---
+'@o2s/framework': minor
+---
+
+Added the normalized data model for a cart/checkout system with full CRUD operations for items and promotions:
+
+- Checkout flow supporting address, shipping, and payment setup
+- Customer address management for authenticated users
+- Payment provider integration and session handling
diff --git a/.changeset/red-peaches-strive.md b/.changeset/red-peaches-strive.md
@@ -0,0 +1,6 @@
+---
+'@o2s/blocks.product-details': patch
+'@o2s/blocks.product-list': patch
+---
+
+added missing auth token to products service calls
diff --git a/.changeset/silent-bees-play.md b/.changeset/silent-bees-play.md
@@ -0,0 +1,5 @@
+---
+'@o2s/integrations.mocked': minor
+---
+
+Mock integrations updated with carts/customers/payments/checkout mocks and enhanced product/order handling.
diff --git a/.gitignore b/.gitignore
@@ -53,3 +53,6 @@ dist
 AGENTS.md
 CLAUDE.md
 agent-os
+
+# Generated files
+O2S-API.postman_collection.json
diff --git a/apps/api-harmonization/.env.local b/apps/api-harmonization/.env.local
@@ -40,8 +40,6 @@ API_SURVEYJS_BASE_URL=https://api.surveyjs.io/public/v1
 MEDUSAJS_BASE_URL=
 MEDUSAJS_PUBLISHABLE_API_KEY=
 MEDUSAJS_ADMIN_API_KEY=
-MEDUSA_VARIANT_SPEC_FIELDS=
-PRODUCTS_BASE_PATH=
 
 SEARCH_ARTICLES_INDEX_NAME=mock
 

diff --git a/apps/api-harmonization/src/app.config.ts b/apps/api-harmonization/src/app.config.ts
@@ -4,10 +4,14 @@ import {
     BillingAccounts,
     CMS,
     Cache,
+    Carts,
+    Checkout,
+    Customers,
     Invoices,
     Notifications,
     Orders,
     Organizations,
+    Payments,
     Products,
     Resources,
     Search,
@@ -32,6 +36,10 @@ export const AppConfig: ApiConfig = {
         search: Search.SearchIntegrationConfig,
         products: Products.ProductsIntegrationConfig,
         orders: Orders.OrdersIntegrationConfig,
+        carts: Carts.CartsIntegrationConfig,
+        customers: Customers.CustomersIntegrationConfig,
+        payments: Payments.PaymentsIntegrationConfig,
+        checkout: Checkout.CheckoutIntegrationConfig,
         auth: Auth.AuthIntegrationConfig,
     },
 };
diff --git a/apps/api-harmonization/src/app.module.ts b/apps/api-harmonization/src/app.module.ts
@@ -13,10 +13,14 @@ import {
     BillingAccounts,
     CMS,
     Cache,
+    Carts,
+    Checkout,
+    Customers,
     Invoices,
     Notifications,
     Orders,
     Organizations,
+    Payments,
     Products,
     Resources,
     Search,
@@ -79,6 +83,10 @@ export const ArticlesBaseModule = Articles.Module.register(AppConfig);
 export const SearchBaseModule = Search.Module.register(AppConfig);
 export const ProductsBaseModule = Products.Module.register(AppConfig);
 export const OrdersBaseModule = Orders.Module.register(AppConfig);
+export const CartsBaseModule = Carts.Module.register(AppConfig);
+export const CustomersBaseModule = Customers.Module.register(AppConfig);
+export const PaymentsBaseModule = Payments.Module.register(AppConfig);
+export const CheckoutBaseModule = Checkout.Module.register(AppConfig);
 export const AuthModuleBaseModule = AuthModule.Module.register(AppConfig);
 
 @Module({
@@ -106,6 +114,10 @@ export const AuthModuleBaseModule = AuthModule.Module.register(AppConfig);
         SearchBaseModule,
         ProductsBaseModule,
         OrdersBaseModule,
+        CartsBaseModule,
+        CustomersBaseModule,
+        PaymentsBaseModule,
+        CheckoutBaseModule,
         AuthModuleBaseModule,
 
         PageModule.register(AppConfig),

diff --git a/apps/docs/blog/releases/o2s/1.5.0.md b/apps/docs/blog/releases/o2s/1.5.0.md
@@ -61,8 +61,8 @@ The [Zendesk integration](../../../docs/integrations/tickets/zendesk/overview) n
 ![zendesk integration](../../../static/img/blog/o2s-zendesk-integration.png)
 
 - You can now create new tickets via the Tickets API. The Zendesk integration implements `createTicket` and forwards requests to the Zendesk API.
-  - Attachments are supported when creating tickets.
-  - Custom field mapping is handled by the `ZendeskFieldMapper`. Configure environment variables (e.g., `ZENDESK_DEVICE_NAME_FIELD_ID`) and add corresponding entries in your CMS mappers to display custom field labels in the UI.
+    - Attachments are supported when creating tickets.
+    - Custom field mapping is handled by the `ZendeskFieldMapper`. Configure environment variables (e.g., `ZENDESK_DEVICE_NAME_FIELD_ID`) and add corresponding entries in your CMS mappers to display custom field labels in the UI.
 - Using our [Survey.js form block](../../../docs/integrations/forms/surveyjs/overview), you can submit custom forms to Zendesk. This gives you full control over form layout (single- or multi-step, splitting fields into sections/columns, and more) independently of Zendesk configuration.
 
 ### Dev watch task improvement

diff --git a/apps/docs/docs/integrations/articles/zendesk/how-to-setup.md b/apps/docs/docs/integrations/articles/zendesk/how-to-setup.md
@@ -64,10 +64,10 @@ After configuring the integration, you need to set up environment variables that
 
 Configure the following environment variables in your API Harmonization server:
 
-| Name                | Type   | Description                                                              | Required | Default |
-| ------------------- | ------ | ------------------------------------------------------------------------ | -------- | ------- |
-| ZENDESK_API_URL     | string | Your Zendesk API URL (e.g., `https://your-subdomain.zendesk.com/api/v2`) | yes      | -       |
-| ZENDESK_API_TOKEN   | string | Base64-encoded authentication token                                      | yes      | -       |
+| Name              | Type   | Description                                                              | Required | Default |
+| ----------------- | ------ | ------------------------------------------------------------------------ | -------- | ------- |
+| ZENDESK_API_URL   | string | Your Zendesk API URL (e.g., `https://your-subdomain.zendesk.com/api/v2`) | yes      | -       |
+| ZENDESK_API_TOKEN | string | Base64-encoded authentication token                                      | yes      | -       |
 
 **Important notes:**
 

diff --git a/apps/docs/docs/integrations/articles/zendesk/overview.md b/apps/docs/docs/integrations/articles/zendesk/overview.md
@@ -4,7 +4,7 @@ sidebar_position: 100
 
 # Zendesk
 
-This integration provides the integration with [Zendesk Help Center API](https://developer.zendesk.com/api-reference/help_center/help-center-api/introduction/), allowing users to browse knowledge base articles, categories, and search for content within your application.
+this package provides the integration with [Zendesk Help Center API](https://developer.zendesk.com/api-reference/help_center/help-center-api/introduction/), allowing users to browse knowledge base articles, categories, and search for content within your application.
 
 ## In this section
 

diff --git a/apps/docs/docs/integrations/cache/redis/overview.md b/apps/docs/docs/integrations/cache/redis/overview.md
@@ -4,7 +4,7 @@ sidebar_position: 100
 
 # Redis Cache
 
-This integration provides caching capabilities using [Redis](https://redis.io/). It implements the framework's `Cache.Service` interface and is used by CMS integrations (Strapi, Contentful) to cache pages, components, and configuration.
+this package provides caching capabilities using [Redis](https://redis.io/). It implements the framework's `Cache.Service` interface and is used by CMS integrations (Strapi, Contentful) to cache pages, components, and configuration.
 
 ## In this section
 

diff --git a/apps/docs/docs/integrations/cms/contentful/overview.md b/apps/docs/docs/integrations/cms/contentful/overview.md
@@ -4,7 +4,7 @@ sidebar_position: 100
 
 # Contentful CMS
 
-This integration provides a full integration with [Contentful CMS](https://www.contentful.com/), enabling comprehensive content management capabilities for your application. The integration supports content management, page management, and content localization, allowing you to create and manage multilingual content with ease. Additionally, Contentful integration includes built-in support for Live Preview, enabling content editors to see their changes in real-time as they edit content in the Contentful web app.
+this package provides a full integration with [Contentful CMS](https://www.contentful.com/), enabling comprehensive content management capabilities for your application. The integration supports content management, page management, and content localization, allowing you to create and manage multilingual content with ease. Additionally, Contentful integration includes built-in support for Live Preview, enabling content editors to see their changes in real-time as they edit content in the Contentful web app.
 
 ## In this section
 

diff --git a/apps/docs/docs/integrations/cms/strapi/overview.md b/apps/docs/docs/integrations/cms/strapi/overview.md
@@ -4,7 +4,7 @@ sidebar_position: 100
 
 # Strapi CMS
 
-This integration provides a full integration with [Strapi CMS](https://strapi.io/), enabling comprehensive content management capabilities for your application. The integration supports content management, page management, and content localization, allowing you to create and manage multilingual content with ease.
+this package provides a full integration with [Strapi CMS](https://strapi.io/), enabling comprehensive content management capabilities for your application. The integration supports content management, page management, and content localization, allowing you to create and manage multilingual content with ease.
 
 ## In this section
 

diff --git a/apps/docs/docs/integrations/commerce/medusa-js/cart-checkout.md b/apps/docs/docs/integrations/commerce/medusa-js/cart-checkout.md
@@ -0,0 +1,97 @@
+---
+sidebar_position: 400
+---
+
+# Cart & Checkout
+
+This document describes the cart lifecycle and checkout process when using the Medusa.js integration. It is intended for developers familiar with O2S who need to understand how the Medusa.js flow maps to the O2S cart and checkout model.
+
+## Understanding MedusaJS Concepts
+
+If you are familiar with O2S but not Medusa, these concepts are essential:
+
+### Regions
+
+Medusa requires a **`region_id`** for every cart. Regions determine:
+
+- **Pricing** — Currency and tax rules
+- **Shipping** — Available shipping options
+- **Taxes** — Tax calculation for the region
+
+O2S maps `regionId` (in request bodies) to Medusa's `region_id`. You must create regions in Medusa Admin and pass a valid `regionId` when creating carts.
+
+### Variants vs Products
+
+Medusa uses **product variants** for cart line items, not products directly. Each variant has its own ID, SKU, price, and options (size, color, etc.).
+
+- **O2S** uses the `sku` field when adding items to cart.
+- **Medusa** expects `variant_id` — the integration maps O2S `sku` to Medusa `variant_id`.
+- You must use the **variant ID** from the product catalog (e.g., from `GET /products/:id` response), not the product ID.
+
+### Currency
+
+Medusa expects lowercase currency codes (e.g., `eur`), while O2S typically uses uppercase (e.g., `EUR`). The integration converts automatically. The `DEFAULT_CURRENCY` environment variable is used when currency is not provided.
+
+### Cart Ownership
+
+- **Customer carts** — When a cart is associated with a logged-in customer, the `customerId` is extracted from the SSO token. The integration verifies ownership on cart access; unauthorized access throws `UnauthorizedException`.
+- **Guest carts** — Carts created without authentication have no `customerId`. Anyone with the cart ID can access them.
+
+## O2S to MedusaJS Mapping
+
+### Cart Model
+
+The O2S `Cart` model maps to Medusa's `StoreCart`:
+
+| O2S Field        | Medusa Field      | Notes                                              |
+| ---------------- | ----------------- | -------------------------------------------------- |
+| `id`             | `id`              | Cart identifier                                    |
+| `customerId`     | `customer_id`     | Present when cart is linked to a customer          |
+| `regionId`       | `region_id`       | Required for Medusa                                |
+| `currency`       | `currency_code`   | Normalized to uppercase in O2S                     |
+| `items`          | `items`           | Line items with variant references                 |
+| `subtotal`, `total`, etc. | Calculated by Medusa | Mapped to O2S `Price` objects              |
+| `shippingAddress`| `shipping_address`| Set via checkout addresses                         |
+| `billingAddress`| `billing_address` | Set via checkout addresses                         |
+| `shippingMethod` | `shipping_methods[0]` | Single shipping method supported               |
+| `paymentMethod`  | `metadata.paymentMethod` | Stored in cart metadata after setPayment   |
+| `metadata`       | `metadata`        | Notes stored in `metadata.notes`; payment session ID in `metadata.paymentSessionId` |
+
+### Checkout Flow Mapping
+
+Each O2S checkout step maps to a Medusa operation:
+
+| O2S Step          | Medusa Operation                                      |
+| ----------------- | ----------------------------------------------------- |
+| `setAddresses`    | `sdk.store.cart.update()` with `shipping_address`, `billing_address` |
+| `setShippingMethod` | `sdk.store.cart.addShippingMethod()` with `option_id` |
+| `setPayment`      | `sdk.store.payment.initiatePaymentSession()` then store session ID and payment method in cart metadata |
+| `placeOrder`      | `sdk.store.cart.complete()` — single call creates the order; no separate order creation endpoint |
+
+### Payment Session Storage
+
+After `setPayment`, the integration stores:
+
+- **`cart.metadata.paymentSessionId`** — ID of the created payment session
+- **`cart.metadata.paymentMethod`** — Object with `{ id, name, type }` for display
+
+These are used by `getCheckoutSummary` and validated before `placeOrder`.
+
+### Address Handling
+
+- **Saved addresses** — When `shippingAddressId` or `billingAddressId` is provided (authenticated users), the integration fetches the address from the Customers service and maps it to Medusa format via `mapAddressToMedusa()`.
+- **Inline addresses** — When `shippingAddress` or `billingAddress` is provided (guests or one-off addresses), the integration maps directly to Medusa format.
+- **Single address** — If only one address is provided, it is used for both shipping and billing.
+
+## Important Caveats
+
+| Caveat | Details |
+| ------ | ------- |
+| **Region required** | `regionId` is required for cart creation. It affects pricing, shipping options, and tax calculation. |
+| **Variant ID required** | Use variant ID (from product catalog), not product ID. O2S `sku` expects the variant ID. |
+| **Payment session storage** | Payment session ID and payment method are stored in `cart.metadata`. Do not clear metadata when updating cart. |
+| **Guest checkout** | Email is required for guest order placement. Provide it in `setAddresses`, `placeOrder`, or `completeCheckout`. |
+| **Shipping price calculation** | Options with `price_type=calculated` require a separate API call to `sdk.store.fulfillment.calculate()`. Flat-price options are returned as-is. |
+| **Order creation** | Single operation (`cart.complete()`) — no separate order creation endpoint. The order is returned directly from the response. |
+| **Cart ownership** | Customer carts verify ownership via SSO token. Unauthorized access throws `UnauthorizedException`. |
+| **Unimplemented methods** | `getCartList`, `getCurrentCart`, `deleteCart` are not available due to Store API limitations. |