Your Shipments

Carrier: {pkg.carrier}

Method: {pkg.method}

Price: {formatCurrency(pkg.price, session.locale.currency)}

{pkg.estimatedDeliveryTime && (

Estimated delivery: {pkg.estimatedDeliveryTime.value} {pkg.estimatedDeliveryTime.unit}

)}

{/* Product Image */}

{item.image ? (

) : (

)}

{/* Product Details */}

{item.name}

{/* Price Display with Discount Logic */} {hasDiscount ? (

{item.originalPrice}

{item.price}

) : (

{item.price}

)}

{/* Quantity Controls - Will add functionality later */}

{item.quantity}

{/* Remove Button - Will add functionality later */}

{/* Total Price */} {item.price * item.quantity}

); } ``` Create a CSS module file named `cartItem.module.css` with the following styles: ```css cartItem.module.css expandable theme={"system"} .cartItem { display: grid; grid-template-columns: 100px 1fr auto auto; align-items: center; gap: 16px; padding: 16px; border-bottom: 1px solid #e0e0e0; } .imageContainer { width: 80px; height: 80px; } .itemImage { width: 100%; height: 100%; object-fit: cover; border-radius: 4px; } .placeholderImage { width: 100%; height: 100%; background-color: #f0f0f0; border-radius: 4px; } .itemDetails { display: flex; flex-direction: column; gap: 4px; } .itemName { margin: 0; font-size: 16px; font-weight: 500; } .priceContainer { display: flex; align-items: center; gap: 8px; } .originalPrice { text-decoration: line-through; color: #888; margin: 0; } .itemPrice { margin: 0; font-weight: 500; } .itemActions { display: flex; flex-direction: column; gap: 8px; align-items: center; } .quantityControl { display: flex; align-items: center; border: 1px solid #e0e0e0; border-radius: 4px; } .quantityButton { border: none; background-color: transparent; padding: 4px 8px; cursor: pointer; font-size: 16px; } .quantityButton:disabled { opacity: 0.5; cursor: not-allowed; } .quantity { padding: 0 8px; min-width: 24px; text-align: center; } .removeButton { background-color: transparent; border: none; color: #ff4d4f; cursor: pointer; padding: 4px; font-size: 14px; } .itemTotal { font-weight: 700; } ``` The first two steps were very simple. It's a simple react component, which you could have easily created yourself with any AI Coding Agent. The fun starts now. With the component in place we need to get this component to interact with your ecommerce provider. We've built an SDK with some React Hooks to make this super easy. Let's enhance our `CartItem` component to use the `useCheckoutSession` hook to access session data. This will allow us to use the session's currency and language settings. Take a look at our [SDK](/ollie-shop/api/index) docs for a refresher on the concepts Update the `'index.tsx'` file to import the `useCheckoutSession` hook from the SDK ```typescript index.tsx theme={"system"} import { useCheckoutSession, type CheckoutSession } from "@ollie-shop/sdk"; ``` Now we can **delete** the original `CartItemType` because the SDK already exports a type ```typescript index.tsx theme={"system"} // Delete this snippet from the original code type CartItemType = { id: string; name: string; quantity: number; price: number; originalPrice?: number; available: boolean; index: number; image?: string; url: string; }; ``` In the `CartItem` component we'll declare the item to be of type `CheckoutSession` ```typescript index.tsx theme={"system"} export default function CartItem({ item = { id: "1", name: "Product Name", quantity: 1, price: 10000, originalPrice: 12000, available: true, index: 0, image: "https://example.com/image.jpg", url: "/product-name/p", }, } : { item: CheckoutSession['cartItems'][number]; }) { const { session } = useCheckoutSession(); const { currency, language } = session.locale; ``` To make our component prettier let's include a function that formats the price according to the `currency` which is imported from the `CheckoutSession` ```typescript index.tsx theme={"system"} // Format price utility function const formatPrice = (price: number) => { return new Intl.NumberFormat(language, { style: "currency", currency: currency, }).format(price / 100); }; ... ``` ```html index.tsx expandable theme={"system"} ... //update the HTML to use formatPrice return (

{/* Product Image */}

{item.image ? (

) : (

)}

{/* Product Details */}

{item.name}

{/* Price Display with Discount Logic */} {hasDiscount ? (

{formatPrice(item.originalPrice)}

{formatPrice(item.price)}

) : (

{formatPrice(item.price)}

)}

{/* Quantity Controls - Will add functionality later */}

{item.quantity}

{/* Remove Button - Will add functionality later */}

{/* Total Price */} {formatPrice(item.price * item.quantity)}

); } ``` Now let's add functionality to **update quantities and remove items**. These actions already exist in the Ollie SDK In the `index.tsx` file, update the `import` to include the`useCheckoutAction` ```typescript index.tsx theme={"system"} import { useCheckoutAction, // Add this import useCheckoutSession, type CheckoutSession } from "@ollie-shop/sdk"; ``` Add the action hooks for removing items and updating quantities: ```typescript index.tsx theme={"system"} // Add actions for removing items const { execute: executeActionRemoveItems } = useCheckoutAction("REMOVE_ITEMS"); // Add actions for updating item quantity const { execute: executeActionUpdateItemsQuantity } = useCheckoutAction( "UPDATE_ITEMS_QUANTITY" ); ``` Create handler functions for quantity changes and item removal: ```typescript index.tsx theme={"system"} // Handler for quantity changes const handleQuantityChange = async (index: number, newQuantity: number) => { if (newQuantity <= 0) return; executeActionUpdateItemsQuantity([ { index, quantity: newQuantity }, ]); }; // Handler for removing an item const handleRemoveItem = async (index: number) => { executeActionRemoveItems([index]); }; ``` Update the button components to use these handlers: ```html index.tsx theme={"system"} {/* Quantity Controls - Now with functionality */}

{item.quantity}

{/* Remove Button - Now with functionality */} ``` Let's add feedback messages to inform users when actions succeed or fail. Here are the specific changes needed: First, update the imports to include `useMessages`: ```typescript index.tsx theme={"system"} import { useMessages, // Add this import useCheckoutAction, useCheckoutSession, type CheckoutSession } from "@ollie-shop/sdk"; ``` Add the message hook to access the `messages` system: ```typescript index.tsx theme={"system"} // Add message hook const { addMessage } = useMessages(); ``` Update the action hooks to include success and error handlers: ```typescript index.tsx theme={"system"} // Add actions with success and error messages const { execute: executeActionRemoveItems } = useCheckoutAction("REMOVE_ITEMS", { onSuccess() { addMessage({ type: "success", content: "Item removed successfully.", }); }, onError({ serverError }) { addMessage({ type: "error", content: serverError?.message ?? "Failed to remove item. Please try again later or contact support.", }); }, }); // Add actions for updating item quantity with messages const { execute: executeActionUpdateItemsQuantity } = useCheckoutAction( "UPDATE_ITEMS_QUANTITY", { onSuccess() { addMessage({ type: "success", content: "Quantity updated successfully.", }); }, onError({ serverError }) { addMessage({ type: "error", content: serverError?.message ?? "Failed to update quantity. Please try again later or contact support.", }); }, } ); ``` Here's the complete CartItem component with all features implemented: ```typescript index.tsx expandable theme={"system"} import React from "react"; import { useCheckoutAction, useCheckoutSession, useMessages, type CheckoutSession } from "@ollie-shop/sdk"; import styles from "./cartItem.module.css"; export default function CartItem({ item = { id: "1", name: "Product Name", quantity: 1, price: 10000, originalPrice: 12000, available: true, index: 0, image: "https://example.com/image.jpg", url: "/product-name/p", }, } : { item: CheckoutSession['cartItems'][number]; }) { const { session } = useCheckoutSession(); const { addMessage } = useMessages(); const { currency, language } = session.locale; const hasDiscount = item.originalPrice && item.price !== item.originalPrice; // Add actions with success and error messages const { execute: executeActionRemoveItems } = useCheckoutAction("REMOVE_ITEMS", { onSuccess() { addMessage({ type: "success", content: "Item removed successfully.", }); }, onError({ serverError }) { addMessage({ type: "error", content: serverError?.message ?? "Failed to remove item. Please try again later or contact support.", }); }, }); // Add actions for updating item quantity with messages const { execute: executeActionUpdateItemsQuantity } = useCheckoutAction( "UPDATE_ITEMS_QUANTITY", { onSuccess() { addMessage({ type: "success", content: "Quantity updated successfully.", }); }, onError({ serverError }) { addMessage({ type: "error", content: serverError?.message ?? "Failed to update quantity. Please try again later or contact support.", }); }, } ); // Handler for quantity changes const handleQuantityChange = async (index: number, newQuantity: number) => { if (newQuantity <= 0) return; executeActionUpdateItemsQuantity([ { index, quantity: newQuantity }, ]); }; // Handler for removing an item const handleRemoveItem = async (index: number) => { executeActionRemoveItems([index]); }; // Format price utility function const formatPrice = (price: number) => { return new Intl.NumberFormat(language, { style: "currency", currency: currency, }).format(price / 100); }; return (

{/* Product Image */}

{item.image ? (

) : (

)}

{/* Product Details */}

{item.name}

{/* Price Display with Discount Logic */} {hasDiscount ? (

{formatPrice(item.originalPrice)}

{formatPrice(item.price)}

) : (

{formatPrice(item.price)}

)}

{/* Quantity Controls */}

{item.quantity}

{/* Remove Button */}

{/* Total Price */} {formatPrice(item.price * item.quantity)}

); } ``` ```css cartItem.module.css expandable theme={"system"} .cartItem { display: grid; grid-template-columns: 100px 1fr auto auto; align-items: center; gap: 16px; padding: 16px; border-bottom: 1px solid #e0e0e0; } .imageContainer { width: 80px; height: 80px; } .itemImage { width: 100%; height: 100%; object-fit: cover; border-radius: 4px; } .placeholderImage { width: 100%; height: 100%; background-color: #f0f0f0; border-radius: 4px; } .itemDetails { display: flex; flex-direction: column; gap: 4px; } .itemName { margin: 0; font-size: 16px; font-weight: 500; } .priceContainer { display: flex; align-items: center; gap: 8px; } .originalPrice { text-decoration: line-through; color: #888; margin: 0; } .itemPrice { margin: 0; font-weight: 500; } .itemActions { display: flex; flex-direction: column; gap: 8px; align-items: center; } .quantityControl { display: flex; align-items: center; border: 1px solid #e0e0e0; border-radius: 4px; } .quantityButton { border: none; background-color: transparent; padding: 4px 8px; cursor: pointer; font-size: 16px; } .quantityButton:disabled { opacity: 0.5; cursor: not-allowed; } .quantity { padding: 0 8px; min-width: 24px; text-align: center; } .removeButton { background-color: transparent; border: none; color: #ff4d4f; cursor: pointer; padding: 4px; font-size: 14px; } .itemTotal { font-weight: 700; } ``` # Import Components Source: https://docs.ollie.shop/ollie-shop/customization/import-components Copy a component from another store you have access to, even one in a different organization, into your own store as an independent, re-syncable copy It's common to need the same component in more than one store. You build a payment notice or a shipping banner once, then a sister store (sometimes in another organization) needs the exact same thing, just with a few props changed. Rebuilding it by hand is wasted effort, and the two copies drift apart over time. Import components solves that. You pick a source store, choose the components you want, and Ollie copies each one into your store as an inactive copy that keeps a link back to its source, so you can pull updates later. You'll find it in the Admin dashboard at **store → Components → Import components**. You can only import from organizations and stores you're a **member of**. The picker is scoped by your access, so importing across organizations works only when your account belongs to more than one. You'll never see, or be able to copy, a component from a store you don't have access to. ## How it works ``` source store (any org you're a member of) │ copy props + slot, copy build artifact ▼ your store ──▶ new inactive component (own id, __importSource → source) │ Re-sync (later) ▼ re-copies the latest build from the source component ``` Each import creates a **brand-new component** under its own id in your target version. The name, slot, and props are copied over, the build artifact is copied to the new id, and the copy is created **inactive** so it never goes live before you've reviewed it. The copy also records its origin (`__importSource`), which is what powers **Re-sync** and keeps the same component from showing up again on a second import. ## Importing components Go to **store → Components** and click **Import components**. The picker loads the organizations and stores you can import from. Choose an **Organization**, then a **Store** within it. Only stores other than the one you're importing into are listed. Check the components you want, or use **Select all**. The list shows each component's **name** and **slot**, and only includes components that are worth importing (see below). Pick the **version** the copies should land in. It defaults to the version you're viewing, or your store's default version. Click **Import**. Each component is copied independently, so if some fail the rest still succeed and you're told how many of each. Imported copies arrive **inactive**, so activate one when you're ready for it to render. ## Reference The picker lists **active** components from the source store that have a built artifact. It hides anything that wouldn't be a useful import: * Components you've **already imported** from that source. * Components whose **build already exists** in your store (same underlying build), so you don't get duplicates. * Duplicate builds within the source itself (listed once). If there's nothing left after that, you'll see **"Nothing new to import from this store."** For each selected component, the import: * Creates a new component with its **own id** in the chosen target version. * Copies the **name**, **slot**, and **props** from the source. * Copies the **build artifact** to the new id, so the copy renders on its own and doesn't depend on the source store staying around. * Marks the copy **inactive** and records its origin in `__importSource`. Because an imported copy remembers where it came from, its detail page shows a **Synced copy** notice with a **Re-sync** button. * **Re-sync** re-copies the latest build from the original source component into your copy. Use it to pull updates after the source changes. * Avoid deploying a fresh build onto a synced copy unless you mean to replace it: a deploy here overwrites the synced build, and a later Re-sync would overwrite your changes in turn. ## Troubleshooting You're only a member of the store you're importing into (or of organizations with no other stores). Importing needs at least one **other** store you have access to. Every importable component from that store is already in your store, or none of its components have a built artifact yet. Build and deploy the component in the source store first, then try again. Imports arrive **inactive** on purpose. Open the component and activate it once you've confirmed its props and slot. Copies don't update automatically. Open your copy and click **Re-sync** to pull the latest build from its source. ## Related * [Components](../concepts/component.mdx) — how components work * [Custom Component](./custom-component.mdx) — building a component from scratch * [Studio](./studio-editor.mdx) — preview and deploy components from the Admin dashboard * [Versions](../concepts/version.mdx) — where imported copies land # Payment Slots Source: https://docs.ollie.shop/ollie-shop/customization/payment-slots Create custom payment-method components for the checkout A **payment slot** lets you render your own component inside a payment method in the checkout, for example to show a disclaimer, terms, or extra instructions when a shopper selects a specific method. Each payment method exposes one content slot, and the slot id is derived from the method itself. Build a component for that slot id, deploy it, and it renders whenever that method is selected. ## How a payment slot id is built A payment slot id is derived from the payment method's **name** and **id**: 1. Take the method `name`. 2. Remove accents and lowercase it. 3. Replace every run of non-alphanumeric characters with `_`. 4. Append the method `id`. The result is: ``` payment___content ``` **Example**: a method `{ id: "203", name: "Pay in Installments" }`: | Step | Value | | -------------- | ----------------------------------------- | | Method name | `Pay in Installments` | | Sanitized name | `pay_in_installments` | | Method id | `203` | | **Slot id** | `payment_pay_in_installments_203_content` | ## Finding the method name and id The `name` and `id` come straight from the checkout session, so you don't need to look them up in your payment provider's admin. Read `session.payment.availableMethods`. Each entry is a payment method with an `id` and a `name`: ```json theme={"system"} { "id": "16", "name": "Vale" } ``` Use those two values to build the slot id as shown above. ## Creating a custom payment component ### 1. Build the component The component receives `children` (the method's default content) and renders it, then adds your own content below. Keep the copy inline: ```tsx theme={"system"} // components/PaymentInstallmentNotice/index.tsx import type { ReactNode } from "react"; import styles from "./index.module.css"; export default function PaymentInstallmentNotice({ children, }: { children?: ReactNode; }) { return ( <> {children}

Pay in 3 interest-free installments with your card. You'll be redirected to complete the payment, so please don't close the page.{" "} Terms & conditions

); } ``` ### 2. Add meta.json Point the component at the slot id. `meta.json` only needs the slot plus the required identifiers: ```json theme={"system"} // components/PaymentInstallmentNotice/meta.json { "name": "payment-installment-notice", "version": "1.0.0", "slot": "payment_pay_in_installments_203_content", "id": "2893c0fc-1872-4a59-be2a-dba92d7a54f5" } ``` The `slot` must match the id you built from the method's name and id. ### 3. Deploy Deploy the component from **Studio**. Once the build succeeds, the component renders whenever that payment method is selected in the checkout. See [Studio](./studio-editor.mdx) for the deploy flow. ## Styling Style your component with a CSS module and the checkout's CSS variables so it follows the active theme: ```css theme={"system"} /* components/PaymentInstallmentNotice/index.module.css */ .notice { margin-top: 1rem; font-size: 0.875rem; color: var(--color-secondary, #666); } .notice a { color: var(--color-primary); text-decoration: underline; } ``` ## Troubleshooting The method is provided by your payment provider, not by the component. Confirm it's enabled for your store and that any eligibility rules (order value, categories, region) are met. The `slot` in `meta.json` must exactly match the generated id. Re-derive it from the method's `name` and `id` (`payment___content`) and confirm the method `id` is correct. Make sure your CSS module is imported in the component and deployed alongside it. Use the checkout CSS variables for colors so it follows the active theme. Run the dev server and open **Studio** to preview your component live in the checkout. Select the payment method to see your component render. See [Studio](./studio-editor.mdx). ## Related * [Studio](./studio-editor.mdx) — preview and deploy components * [Slots](../concepts/slots.mdx) — the slot system in general * [Components](../concepts/component.mdx) — how components work # Passing Props to Custom Components Source: https://docs.ollie.shop/ollie-shop/customization/props Useful for custom components that are reused in different stores/versions where each requires a different configuration Ollie Custom Components can receive properties configured directly in the Admin. Prop Configuration Pn

This is useful when you have a custom component but would like to abe able to change some of it's behaviour without needing to make code changes. ## Example - Free Shipping Progress Bar Instead of hard-coding the Free Shipping Tier directly in the code, use props to define the component behavior. In this example the Free Shipping custom component has a default value of \$99.00 and let's assume that we need to change the Free Tier to \$350.00.

In the custom component code you can define a variable and via the admin you can assign a value that will override the hard-coded value in your code. The snippet below is part of a Free Shipping Progress Bar (custom) component. The developer declared a variable named `target` and assgined a value of `99`, however it also declared that this component can receive props. ```typescript index.tsx theme={"system"} // piece of component with the target prop const FreeShippingProgress: React.FC = ({ target = 99, ...props }) => { ``` When you configure props in the admin, you can name them and if there is a matching variable then the configured value will override the hard-coded one. Free Shipping Tier 350 Pn

The result is the component will now use the configured prop `target=350` instead of the original (default) value of 99. Free Shipping Tier 350 Front Pn

# Extra Checkout Steps Source: https://docs.ollie.shop/ollie-shop/customization/steps Include extra steps (or exclude existing ones) to your checkout journey Some stores prefer a single-page checkout, others a multi-step. The reality is that there is no one-size fits all. You should use what is best for your store. With Ollie Shop you can configure your store to fit your needs. For example if you want to upsell your customer with a Warranty, instead of polluting the Cart page with more information you can create a dedicated step for the user to make the decision.

Your Shipments

Hello {session.customer?.firstName}!

{platformStoreId}

Thank you, {customer.firstName}!

Order Summary

Cart Summary

Welcome {session.customer?.firstName}!

{item.name}

{item.name}

{item.name}

Hello, {name}!