@chazify/smartcart-hydrogen

Smart Cart for Shopify Hydrogen - Upsells, Cross-sells, BOGO & Product Recommendations

Installation

NPM (Future)

npm install @chazify/smartcart-hydrogen

Setup

1. Get Your API Token

1. Login to your Chazify SmartCart admin at smartcart.chazify.com
2. Click on "Settings" in the bottom left corner of the dashboard
3. In the "API Security Token" section, click "Generate API Token" if you haven't already
4. Click "Show" to reveal the token, then click "Copy" to copy it to your clipboard

2. Configure Allowed Domains

⚠️ REQUIRED: You must whitelist the domains that can use your API token:

1. In the Settings page (bottom left corner), scroll to the "Allowed Domains" section
2. Add your storefront domain(s), for example:
   • mystore.myshopify.com (production)
   • staging.myshopify.com (staging)
3. Click "Add Domain" for each domain

Important Security Notes:

• Localhost is automatically allowed for local development (no need to add it)
• Production domains MUST be added or the API will reject requests with 403 Forbidden
• If no domains are configured, only localhost will work
• API requests from unauthorized domains are always blocked

3. Add Token to Environment Variables

In your Hydrogen storefront, add to .env:

CHAZIFY_SMARTCART_API_TOKEN=your_jwt_token_here

Security Note: The token is a JWT (JSON Web Token) that:

• Is safe to expose in browser requests (signed, not encrypted)
• Only works from domains in your whitelist
• Can be regenerated anytime in the admin dashboard

4. Pass Token to Provider

In your app/root.jsx:

import {SmartCartProvider, SmartCart} from '@chazify/smartcart-hydrogen';
import {useLoaderData} from 'react-router';
import '@chazify/smartcart-hydrogen/dist/index.css';

// In your loader
export async function loader({context}) {
  const {cart} = context;
  const apiToken = context.env.CHAZIFY_SMARTCART_API_TOKEN;
  
  return {cart, apiToken};
}

export default function App() {
  const {cart, apiToken} = useLoaderData();

  return (
    <SmartCartProvider 
      shop="your-store.myshopify.com" 
      cart={cart}
      apiToken={apiToken}
      countryCode="US"
    >
      <PageLayout>{children}</PageLayout>
      <SmartCart />
    </SmartCartProvider>
  );
}

Usage

Trigger cart drawer from anywhere

import { useSmartCart } from '@chazify/smartcart-hydrogen';

function ProductCard() {
 const {toggleDrawer} = useSmartCart();

  return <button onClick={toggleDrawer}>Add to Cart</button>;
}

Show product recommendations

import {ProductRecommendations} from '@chazify/smartcart-hydrogen';

export default function CartPage() {
  return (
    <div>
      <Cart />
      <ProductRecommendations />
    </div>
  );
}

Configuration

The Smart Cart automatically fetches configuration from your Chazify SmartCart API using the provided token. You can also provide initial config:

<SmartCartProvider
  shop="your-store.myshopify.com"
  cart={cart}
  apiToken={apiToken}
  countryCode="US"
  initialConfig={{
    cartTitle: 'Your Cart',
    recommendationMode: 'collections',
    collectionHandles: ['trending'],
  }}
>
  {children}
</SmartCartProvider>

API

SmartCartProvider Props

| Prop | Type | Required | Description | |------|------|----------|-------------| | shop | string | ✅ | Your Shopify store domain (e.g., your-store.myshopify.com) | | cart | object | ✅ | Hydrogen cart object from loader | | apiToken | string | ✅ | Your Chazify SmartCart API token | | countryCode | string | ❌ | ISO 3166-1 alpha-2 country code for multi-currency support (e.g., US, GB, CA). Defaults to US | | apiUrl | string | ❌ | API URL (default: https://smartcart.chazify.com) | | initialConfig | SmartCartConfig | ❌ | Pre-loaded configuration |fy.com) | | initialConfig|SmartCartConfig` | ❌ | Pre-loaded configuration |

useSmartCart Hook

const {
  config,          // Smart Cart configuration
  isLoading,       // Loading state
  isDrawerOpen,    // Drawer open state
  openDrawer,      // Open cart drawer
  closeDrawer,     // Close cart drawer
  toggleDrawer,    // Toggle cart drawer
  cart,            // Hydrogen cart object
  recommendations, // Product recommendations
} = useSmartCart();

Multi-Currency Support

The Smart Cart supports multi-currency pricing through Shopify Markets. Pass the customer's country code to get localized prices:

// Example: Get country from Hydrogen context
export async function loader({context}) {
  const {cart} = context;
  const {storefront, env} = context;

  const countryCode = storefront.i18n.country || 'US';

  const apiToken = context.env.PUBLIC_CHAZIFY_SMARTCART_API_KEY;

  return {
    cart: await cart.get(),
    apiToken,
    countryCode,
  };
}

export default function App() {
  const {cart, apiToken, countryCode} = useLoaderData();

  return (
    <SmartCartProvider 
      shop="your-store.myshopify.com" 
      cart={cart}
      apiToken={apiToken}
      countryCode={countryCode}
    >
      <PageLayout>{children}</PageLayout>
      <SmartCart />
    </SmartCartProvider>
  );
}

Supported Country Codes: Any ISO 3166-1 alpha-2 country code (e.g., US, GB, CA, AU, DE, FR, JP, etc.)

How It Works:

• Product recommendations automatically fetch prices in the specified currency
• Prices are converted using Shopify's Admin API contextualPricing
• Currency symbols and amounts are displayed correctly for each market
• Falls back to USD if no country code is provided

Requirements:

• Your Shopify store must have Shopify Markets configured
• Products must have prices set for the target markets

See CURRENCY_SUPPORT.md for detailed documentation.

Features

• ✅ Smart cart drawer with real-time updates
• ✅ Product recommendations (manual & collection-based)
• ✅ Multi-currency support via Shopify Markets
• ✅ BOGO promotions (Buy One Get One)
• ✅ Auto-add upsells with discounts
• ✅ Show recommendations popup/on-cart
• ✅ Secure API token authentication
• ✅ Customizable styling
• ✅ TypeScript support
• ✅ Works with Hydrogen's cart API
• ✅ Works with Hydrogen's cart API

Admin Configuration

Configure your cart settings at smartcart.chazify.com/cart:

• Cart UI: Customize colors, text, buttons
• Product Recommendations: Manual selection or collection-based
• Rules: Create BOGO, auto-add, and show recommendation rules
• Trigger Products: Set specific products that trigger upsells
• API Token: Generate and manage your secure API tokens

Security

Your API token uses a three-layer security model:

1. JWT Authentication: Token is cryptographically signed and can't be forged
2. Shop Validation: Token is tied to your specific store
3. Domain Whitelisting: Token only works from authorized domains

Best Practices

• ✅ Store token in environment variables (.env)
• ✅ Add all your domains to the whitelist in admin dashboard
• ✅ Use localhost for local development
• ✅ Never commit tokens to version control
• ✅ Pass via server-side loader when possible
• ✅ Regenerate token if compromised
• ❌ Don't use * (all domains) in production

Common Issues

403 Forbidden - "Domain not authorized"

• Add your domain to the "Allowed Domains" whitelist in SmartCart admin
• Make sure you added the full domain (e.g., mystore.myshopify.com)
• For local development, add localhost to the whitelist

401 Unauthorized - "Invalid token"

• Check that you copied the complete token from the dashboard
• If you regenerated the token, update it in your .env file
• Restart your development server after changing .env

See SECURITY.md for detailed security documentation.

Support

• Dashboard: smartcart.chazify.com
• Issues: GitHub Issues
• Email: [email protected]

License

MIT