E-Commerce Store

1. Feature Overview

The Hyphen Ecommerce Store lets your publication sell physical products — books, print magazines, and literary merchandise — directly through the Reader Portal storefront. The store is powered by Shopify behind the scenes.

Here is how it works at a high level:

• Products are managed in Shopify. You create and manage your products (titles, descriptions, images, prices, variants, inventory) in your Shopify store.
• Products sync to Hyphen. Products are pulled from Shopify into the Hyphen Admin Console either manually (using the "Sync from Shopify" button) or automatically (through Shopify webhooks whenever a product is created, updated, or deleted).
• Your team controls editorial settings. In the Admin Console, you can mark products as "Featured" and set a display priority to control how products appear in the storefront.
• Readers browse and shop in the Reader Portal. The Reader Portal has a full storefront with product browsing, search, filtering, product detail pages, a shopping cart, and collections.
• Checkout happens on Shopify. When a reader clicks "Proceed to Checkout," they are redirected to your Shopify checkout page where they complete payment and shipping.
• Order history is available to logged-in readers. Readers can view their past orders, order details, shipping status, and tracking information in the Reader Portal.

What is fully working today:

---

2. Who Should Use This Guide

---

3. Before You Begin

3.1 Prerequisites

Before the Ecommerce Store can work, the following must be in place:

1. A Shopify store with products. You need an active Shopify store with at least one published product. This is where all product data originates.

2. Shopify API credentials. You need the following from your Shopify store:

   • Shop Domain — Your Shopify store URL (e.g., your-shop.myshopify.com)
   • Storefront Access Token — Used to fetch products and manage carts (public-facing)
   • Admin API Access Token — Used for product sync, order retrieval, and webhook verification
   • API Version — The Shopify API version to use

3. Shopify integration configured in Hyphen. An Admin must enter the Shopify credentials in the Admin Console (see Section 5.1).

4. Shopify webhooks registered. For automatic product and order sync, Shopify must be configured to send webhooks to your Hyphen instance. The webhook topics needed are:

   • products/update
   • products/delete
   • orders/create
   • orders/updated

5. Webhook secret configured. The SHOPIFY_WEBHOOK_SECRET must be set for Hyphen to verify incoming webhook requests from Shopify.

6. Admin permissions. The user performing setup must have the Admin role, which has full access to all product and settings permissions.

3.2 Required Permissions

Note: Editors can view products but cannot sync products, edit featured settings, or configure the Shopify integration. If an Editor needs these capabilities, an Admin must update their role or grant additional permissions.

---

4. Key Terms

---

5. Step-by-Step Setup Guide

5.1 Configure Shopify Integration

This step connects your Hyphen platform to your Shopify store. An Admin must do this before any products can be synced.

1. Log in to the Admin Console with an Admin account.

2. In the left sidebar, click Settings.

3. Click Integrations.

4. Scroll down to the E-Commerce section.

5. Find the Shopify integration card and click Configure.

6. A configuration modal will open with these fields:

   Field	What to Enter
   Shop Domain	Your Shopify store URL (e.g., your-shop.myshopify.com)
   Storefront Access Token	The token from your Shopify Storefront API credentials
   Admin API Access Token	The token from your Shopify Admin API credentials
   API Version	The Shopify API version (e.g., 2024-01)

7. Click Save to store the configuration.

8. The Shopify integration card should now show as Connected.

Where to find these credentials in Shopify:

• Log in to your Shopify Admin → Settings → Apps and sales channels → Develop apps → Select or create an app → API credentials tab.
• The Storefront Access Token is under the "Storefront API" section.
• The Admin API Access Token is under the "Admin API" section.

5.2 Register Shopify Webhooks

For automatic sync when products change in Shopify, you need to register webhooks in your Shopify store pointing to your Hyphen instance.

1. In your Shopify Admin, go to Settings → Notifications → Webhooks (or configure via the Shopify API).

2. Create the following webhooks:

   Event	Webhook URL
   Product update	https://your-hyphen-domain.com/api/webhooks/shopify
   Product deletion	https://your-hyphen-domain.com/api/webhooks/shopify
   Order creation	https://your-hyphen-domain.com/api/webhooks/shopify
   Order updated	https://your-hyphen-domain.com/api/webhooks/shopify

3. Set the format to JSON.

4. Copy the Webhook signing secret from Shopify — this must be configured as the SHOPIFY_WEBHOOK_SECRET environment variable in your Hyphen deployment.

Note: Without webhooks, products will only update when you manually click "Sync from Shopify" in the Admin Console. With webhooks, updates happen automatically within seconds of a change in Shopify.

5.3 Sync Products for the First Time

Once Shopify is connected, sync your products into Hyphen:

1. In the Admin Console, go to the left sidebar and click Content Entities → Products.
2. You will see the Products page. If this is your first time, the page will be empty.
3. Click the Sync from Shopify button (top-right area of the page).
4. Wait for the sync to complete. A notification will confirm how many products were synced.
5. The product grid will now show your Shopify products with their images, titles, prices, and availability status.

What gets synced: Product title, description, images, price, compare-at price, product type, vendor, tags, variants (with individual pricing and availability), handle, and inventory count.

What does NOT get synced: Shopify checkout settings, shipping rules, tax settings, or payment methods. Those remain in Shopify.

5.4 Set Featured Products and Display Priority

After syncing, you can control which products are highlighted in the storefront:

1. On the Products page, click on a product to open its detail page.
2. On the right side, you will see the Editorial Settings section.
3. Toggle Featured to "on" to mark the product as featured.
4. Enter a Priority number. Higher numbers appear first when readers sort by "Featured."
5. Click Save to apply changes.

Example: You want "Spring Poetry Collection" to appear at the top of the storefront when readers sort by Featured. Set it as Featured with Priority = 10. Set other featured products to Priority 5 or lower.

5.5 Monitor Inventory

To check stock levels across all products:

1. In the Admin Console, go to Content Entities → Inventory (in the left sidebar under Products).
2. The Inventory page shows:
   • Summary cards at the top: total In Stock, Out of Stock, and Pre-Order product counts.
   • Low Stock / Out of Stock alerts — products that need attention.
   • Inventory table — all products with their type, price, variant count, status, and last sync time.

Note: Inventory data comes from Shopify. To update inventory, make changes in Shopify and either wait for the webhook to sync or manually trigger a sync.

---

6. How to Verify It Worked

After completing setup, verify the end-to-end flow:

6.1 Verify Products Appear in Admin Console

1. Go to Content Entities → Products in the Admin Console.
2. Confirm your products appear with correct images, titles, and prices.
3. Use the availability tabs (All, In Stock, Out of Stock, Pre-Order) to filter.
4. Use the Search bar to find specific products by name.
5. Click into a product and verify:
   • Images display correctly (gallery with thumbnails)
   • Price and compare-at price are correct
   • Variants are listed with their individual prices and availability
   • Product type, vendor, and tags are accurate
   • Shopify Product ID is shown in the Shopify Info section
   • "Last Synced" timestamp is recent

6.2 Verify Products Appear in Reader Portal Storefront

1. Open the Reader Portal in a browser.
2. Navigate to the Shop page.
3. Confirm products appear in the product grid with:
   • Product image
   • Product type label (e.g., "Book," "Magazine," "Merchandise")
   • Title
   • Vendor name (if applicable)
   • Price (with compare-at price shown as strikethrough if on sale)
   • Availability badges ("Sold Out" for out-of-stock, "Pre-order" for pre-order items, "Sale" for discounted items)
4. Test the search bar — type part of a product name and confirm results appear.
5. Test the type filters — click "Book," "Magazine," "Merchandise," or "Print" to filter.
6. Test the sort options — try "Newest," "Price: Low to High," "A-Z," and "Featured."
7. Test pagination — if you have more than 12 products, click "Next" and "Previous."

6.3 Verify Product Detail Pages

1. From the Shop page, click on any product.
2. The product detail page should show:
   • Breadcrumb navigation at the top (Shop > Product Type > Product Name)
   • Image gallery with clickable thumbnails and next/previous arrows
   • Product title, vendor/author name, and price
   • Sale badge and strikethrough compare-at price (if applicable)
   • Variant selector (if the product has multiple options like size or format)
   • "Add to Cart" button (or "Sold Out" if unavailable, or "Pre-order Now" for pre-order items)
   • Product description (full text)
   • Tags displayed below the description

6.4 Verify Cart Behavior

1. On a product detail page, click Add to Cart.
2. The button should briefly show "Added to Cart!" as confirmation.
3. The cart icon in the header should update to show the item count (e.g., "1").
4. Click the cart icon to open the Cart Drawer (slides in from the right).
5. In the Cart Drawer, verify:
   • Product image, title, and price appear correctly
   • Quantity can be adjusted with + and − buttons
   • Items can be removed
   • Subtotal updates when quantity changes
   • Checkout button is present
6. Alternatively, navigate to /shop/cart to see the full Cart Page with:
   • All cart items listed
   • Quantity controls
   • Line totals for each item
   • Order Summary sidebar showing subtotal
   • "Shipping and taxes calculated at checkout" notice
   • "Proceed to Checkout" button

6.5 Verify Checkout

1. From the Cart Page or Cart Drawer, click Proceed to Checkout (or Checkout).
2. You should be redirected to your Shopify checkout page.
3. The Shopify checkout should show the same items that were in your cart.
4. Complete a test purchase (use Shopify's test mode if available).

6.6 Verify Order History (Logged-In Reader)

1. Log in to the Reader Portal as a reader who has placed an order.
2. Navigate to Shop → Orders (or /shop/orders).
3. The Order History page should show:
   • Order number (e.g., "#1001")
   • Order date
   • Total price
   • Financial status badge (Paid, Pending, Refunded, etc.)
   • Fulfillment status badge (Fulfilled, Partial, Unfulfilled)
   • Item count
4. Click on an order to view the Order Detail page:
   • Line items with images, titles, quantities, and prices
   • Order totals: Subtotal, Shipping, Tax, Total
   • Shipping address (if available)
   • Tracking information with tracking number and link (if fulfilled)

6.7 Verify Collections

1. Navigate to Shop → Collections (or /shop/collections) in the Reader Portal.
2. Confirm collection cards appear with image, title, description, and product count.
3. Click a collection to see its products filtered in the shop view.

---

7. Worked Examples

Example 1: Syncing a New Product from Shopify and Verifying It in the Storefront

Scenario: Your team has added a new book, "Monsoon Verses," to the Shopify store and you need to verify it appears in the Reader Portal.

Steps:

1. In Shopify: Go to your Shopify Admin → Products → confirm "Monsoon Verses" is created with:

   • Title: "Monsoon Verses"
   • Description: Poetry collection about the monsoon season
   • Product type: "Book"
   • Price: ₹499
   • Compare-at price: ₹699 (optional, if on sale)
   • At least one image uploaded
   • Status: Active
   • Inventory: In stock

2. In Admin Console: Go to Content Entities → Products.

3. If webhooks are set up: The product should already appear in the list (webhooks auto-sync within seconds). Look for "Monsoon Verses" in the product grid.

4. If webhooks are NOT set up: Click Sync from Shopify and wait for the sync to complete. A success message will confirm the sync results.

5. Verify in Admin Console: Click on "Monsoon Verses" to open the product detail page. Confirm:

   • Title: "Monsoon Verses"
   • Price: ₹499 (displayed as ₹4.99 × 100 = 499 cents internally, but shown as ₹499)
   • Product type: Book
   • Images display correctly
   • Availability: In Stock

6. Mark as Featured (optional): In the Editorial Settings panel on the right, toggle Featured on and set Priority to 8. Click Save.

7. Verify in Reader Portal: Open the Reader Portal → Shop page.

   • Search for "Monsoon" — the product should appear.
   • Filter by "Book" — the product should appear.
   • Sort by "Featured" — if you set it as Featured, it should appear near the top.
   • Click on the product to verify the detail page shows correct images, price (₹499 with ₹699 strikethrough if compare-at price was set), and description.
   • The "Sale" badge should appear since the compare-at price is higher than the selling price.

---

Example 2: Checking Product Details, Price, and Availability in the Storefront

Scenario: A customer contacts support saying a product shows "Sold Out" but you believe it should be in stock.

Steps:

1. In Admin Console: Go to Content Entities → Products.
2. Search for the product name.
3. Click the product to view its detail page.
4. Check the Availability field — it will show "In Stock," "Out of Stock," or "Pre-order."
5. Check the Total Inventory count (if available from Shopify).
6. Check the Variants section — each variant shows its individual availability status. A product may show as "Sold Out" if all its variants are unavailable, even if some were recently restocked.
7. Check the Last Synced timestamp. If it is old (e.g., hours ago), the stock may have been updated in Shopify but not yet synced.

To fix:

8. In Shopify: Go to the product and confirm the inventory is updated and the product status is "Active."
9. In Admin Console: Click Sync from Shopify to pull the latest data.
10. After the sync completes, refresh the product detail page and confirm the availability has updated.
11. In Reader Portal: Refresh the Shop page and confirm the product no longer shows "Sold Out."

---

Example 3: Adding a Product to Cart and Completing Checkout

Scenario: You want to test the full purchase flow from browsing to checkout.

Steps:

1. Open the Reader Portal and navigate to the Shop page.
2. Browse the products or search for a specific item (e.g., "Literary Tote Bag").
3. Click on the product to open the Product Detail page.
4. If the product has variants (e.g., Color: Black, Navy), select your preferred option from the variant selector.
5. Click Add to Cart. The button will briefly show "Added to Cart!" and the cart icon in the header will update to show "1."
6. Click the Cart Icon in the header to open the Cart Drawer.
7. Verify the item appears with the correct title, variant, price, and quantity.
8. Click Checkout in the Cart Drawer.
   • Alternatively, click View Cart to go to the full Cart Page, then click Proceed to Checkout.
9. You will be redirected to the Shopify Checkout page.
10. On the Shopify Checkout page:
    • Enter shipping address
    • Select shipping method
    • Enter payment details
    • Click Pay now (or complete with test payment if using Shopify's test mode)
11. After successful payment, Shopify displays an order confirmation.

To verify the order:

12. Go back to the Reader Portal → Shop → Orders.
13. Your new order should appear in the list with status "Paid" and "Unfulfilled" (until the seller ships it).

---

Example 4: Verifying Order History for a Logged-In Reader

Scenario: A reader contacts support saying they cannot see their order history. You need to verify it works correctly.

Steps:

1. Confirm the reader is logged in. Order history requires authentication. If the reader is not logged in, they will be redirected to the sign-in page when they try to access Orders.

2. In the Reader Portal: Log in as the reader (or use a test account that has placed orders).

3. Navigate to Shop → Orders (accessible from the shop navigation or directly at /shop/orders).

4. The Orders page should display:

   • All orders associated with the reader's email address
   • Each order shows: order number, date, total price, financial status, fulfillment status, and item count

5. If no orders appear:

   • Confirm the reader's email address in the Reader Portal matches the email used for the Shopify checkout.
   • Orders are fetched from Shopify by email address — the emails must match exactly.

6. Click on an order to view the Order Detail page. Verify:

   • Line items list with correct products, quantities, and prices
   • Order totals (Subtotal, Shipping, Tax, Total)
   • Shipping address (if provided)
   • Fulfillment and tracking information (if the order has been shipped)

7. If tracking information is available, click the tracking link to verify it opens the carrier's tracking page.

---

Example 5: Troubleshooting a Product Update Not Reflected in the Platform

Scenario: You updated a product's price in Shopify 30 minutes ago, but the Reader Portal still shows the old price.

Steps:

1. Check the Admin Console first.

   • Go to Content Entities → Products.
   • Find the product and click to open its detail page.
   • Check the Last Synced timestamp.
   • If the "Last Synced" time is before your Shopify update, the change has not synced yet.

2. Check if webhooks are working:

   • If webhooks are configured, product updates should appear within seconds.
   • If the "Last Synced" time is old, the webhook may not have fired or may have failed.
   • Check your server logs for webhook errors (ask your technical team for this).

3. Manually sync:

   • On the Products page, click Sync from Shopify.
   • Wait for the sync to complete.
   • Refresh the product detail page.
   • Confirm the price has updated to the new value.

4. Verify in Reader Portal:

   • Open the Reader Portal → Shop page.
   • Find the product and confirm the new price appears on the product card.
   • Click into the product detail page and confirm the price is updated there too.

5. If the price still does not update after manual sync:

   • Confirm the product is "Active" in Shopify (draft or archived products may not sync).
   • Confirm the price change was saved in Shopify (check Shopify Admin → Products → the product).
   • Check that the Shopify API credentials in Settings → Integrations are still valid and connected.

---

Example 6: Setting Up a Seasonal Sale and Verifying Storefront Display

Scenario: Your marketing team wants to run a summer sale. You need to update prices in Shopify, feature the sale products, and verify the storefront reflects the sale.

Steps:

1. In Shopify: For each sale product:

   • Set the Compare-at price to the original price (e.g., ₹999).
   • Set the Price to the sale price (e.g., ₹599).
   • Save each product.

2. In Admin Console:

   • If webhooks are active, wait a few seconds for the sync.
   • If not, go to Content Entities → Products and click Sync from Shopify.

3. Feature the sale products:

   • Click on each sale product.
   • In the Editorial Settings panel, toggle Featured to on.
   • Set Priority to a high number (e.g., 10) so these appear first.
   • Click Save for each product.

4. Verify in Reader Portal:

   • Open the Shop page.
   • Sort by Featured — sale products should appear at the top.
   • Each sale product should show:
     • The sale price (e.g., ₹599)
     • The original price with a strikethrough (e.g., ₹999)
     • A "Sale" badge on the product card
   • Click into a sale product to verify the detail page shows the discount correctly.

---

Example 7: Reviewing Returns and Refunds

Scenario: A customer has requested a refund through Shopify and you want to verify it is reflected in the platform.

Steps:

1. In Shopify: Process the refund through Shopify Admin → Orders → select the order → Refund.

2. In Admin Console:

   • The returns/refunds data is accessible through the admin API.
   • Returns can be filtered by status: Open, Closed, or All.

3. Verify the order status update:

   • In the Reader Portal, the reader can go to Shop → Orders and view the order.
   • The Financial Status badge should update to "Refunded" (shown in gray).
   • The order detail page will still show the original line items and totals for reference.

4. If the status does not update:

   • Remember that order data is fetched directly from Shopify in real-time — there is no sync delay for orders.
   • If the status still shows "Paid," the refund may not have been fully processed in Shopify yet. Check Shopify Admin for the refund status.

---

8. Common Mistakes and How to Fix Them

8.1 "No products appear in the Admin Console"

Possible causes:

• Shopify integration is not configured. Go to Settings → Integrations and verify Shopify is connected.
• Products have never been synced. Click Sync from Shopify on the Products page.
• Shopify API credentials are incorrect or expired. Re-enter them in the Shopify integration configuration.

Fix: Configure the integration (Section 5.1), then click Sync from Shopify (Section 5.3).

---

8.2 "Products appear in Admin Console but not in the Reader Portal"

Possible causes:

• Products are marked as "Out of Stock" — the public storefront hides out-of-stock products by default.
• The Reader Portal Shopify environment variables are not configured correctly.

Fix:

• Check product availability in the Admin Console. If out of stock, update inventory in Shopify and re-sync.
• Ask your technical team to verify the Reader Portal environment variables: NEXT_PUBLIC_SHOPIFY_DOMAIN, NEXT_PUBLIC_SHOPIFY_STOREFRONT_TOKEN, and NEXT_PUBLIC_ADMIN_API_URL.

---

8.3 "Product prices look wrong (showing very small or very large numbers)"

Possible cause: Prices are stored in the smallest currency unit (e.g., paise for INR, cents for USD). A product priced at ₹499 is stored as 49900 internally.

Fix: This is normal internal behavior. If the display is wrong, it means the price conversion is not working correctly. Report it to the technical team. In the storefront, prices should display correctly with the currency symbol (e.g., ₹499.00).

---

8.4 "Clicking 'Add to Cart' does nothing"

Possible causes:

• The product or selected variant is sold out.
• The Shopify Storefront API token is invalid or misconfigured.
• Browser localStorage is full or blocked.

Fix:

• Check if the button shows "Sold Out" — if so, the product is unavailable.
• Try clearing your browser cache and cookies, then refresh the page.
• If the issue persists, ask the technical team to verify the Storefront API token.

---

8.5 "Checkout redirects to a broken page or error"

Possible causes:

• The Shopify Storefront API is not generating a valid checkout URL.
• The Shopify store is in maintenance mode or paused.
• Cart has expired (Shopify carts expire after 30 days of inactivity).

Fix:

• Try adding items to a fresh cart and checking out again.
• Verify the Shopify store is active and accepting orders.
• Check the Shopify integration credentials in Settings → Integrations.

---

8.6 "Order history shows no orders even though the reader has purchased items"

Possible cause: The email address the reader uses to log in to the Reader Portal does not match the email used during Shopify checkout. Orders are looked up by email address.

Fix: Confirm that the reader used the same email for both their Reader Portal account and the Shopify checkout. If different emails were used, the orders will not appear.

---

8.7 "Sync from Shopify button is not visible"

Possible cause: Your account does not have the products:sync permission. Only Admin users have this permission by default.

Fix: Ask an Admin to either perform the sync or grant you the necessary permission.

---

8.8 "Product images are not displaying"

Possible causes:

• The product has no images uploaded in Shopify.
• Images were removed from Shopify after the last sync.

Fix: Upload or restore images in Shopify, then trigger a sync.

---