Pos Integration

POS Integration

Overview

Point-of-sale integration connects your physical retail operations with your online store, enabling unified inventory visibility, centralized order management, and consistent customer profiles across channels. When a customer buys in-store, the online store must reflect the updated inventory immediately; when they return an online order in-store, the refund must flow back to the payment gateway. This skill covers connecting Square and Shopify POS to your commerce platform, synchronizing inventory in real time, and handling cross-channel returns.

When to Use This Skill

• When opening a physical retail location alongside an existing online store
• When inventory discrepancies between in-store and online are causing oversells
• When customers expect to return online purchases in-store (omnichannel returns)
• When franchised or multi-location retail needs unified inventory and reporting
• When building a custom kiosk or tablet-based POS application

Core Instructions

Step 1: Determine your platform and POS integration path

Step 2: Platform-specific POS setup

---

Shopify + Shopify POS

Shopify POS is the most seamless option for Shopify stores since inventory is managed in a single system:

1. Subscribe to Shopify POS Pro ($89/month or included in Shopify Plus):

• Go to Point of Sale → Devices in your Shopify admin
• Install the Shopify POS app on your iPad or iPhone
• Connect a card reader (Shopify provides its own Tap & Chip reader)

2. Set up locations for each store:

• Go to Settings → Locations and click Add location for each physical store
• Assign inventory quantities per location — Shopify tracks stock at each location separately

3. Inventory automatically stays in sync:

• A sale in the POS app immediately decrements inventory for that location
• The online store can be configured to sell from multiple locations (go to Settings → Shipping and delivery → Local pickup to configure)

4. Configure click-and-collect (Buy Online, Pick Up In Store):

• Go to Settings → Shipping and delivery → Local pickup and enable it for each location
• Customers select their pickup location at checkout; the order appears in that store's POS app under Pickups

---

WooCommerce + Square

Connect Square to WooCommerce:

1. Install the WooCommerce Square plugin (free, developed by Square) from wordpress.org 2. Go to WooCommerce → Settings → Integrations → Square and click Connect with Square 3. Log in to your Square account and select your Square business location 4. In the Square plugin settings, enable Sync inventory (bidirectional) 5. Run the initial sync: go to WooCommerce → System Status → Tools → Sync Products with Square

How inventory sync works:

• When you sell a product in your Square POS, WooCommerce stock decrements automatically (within minutes via webhook)
• When WooCommerce receives an online order, Square stock decrements
• Go to WooCommerce → Square → Sync Log to see sync history and troubleshoot discrepancies

Handle in-store returns of online orders:

• Returns initiated in WooCommerce admin automatically sync to Square if the original payment used Square
• For Stripe-paid online orders returned in-store: process the refund in Square and reconcile in WooCommerce manually, or build a custom refund endpoint (see Custom section below)

---

BigCommerce + Square

1. Go to Channel Manager in your BigCommerce admin and click + Create New Channel 2. Select Square from the channel list 3. Authorize BigCommerce to connect to your Square account 4. Configure inventory sync settings — BigCommerce and Square will sync stock levels bidirectionally 5. Square POS orders can be imported into BigCommerce for unified reporting

---

Custom / Headless + Square API

Initialize the Square client:

// lib/pos/square-client.ts
import { Client, Environment } from 'square';

export const squareClient = new Client({
  accessToken: process.env.SQUARE_ACCESS_TOKEN!,
  environment: process.env.NODE_ENV === 'production' ? Environment.Production : Environment.Sandbox,
});

export const { catalogApi, inventoryApi, ordersApi, paymentsApi, locationsApi } = squareClient;

Handle Square inventory webhooks (in-store sale → update online store):

// POST /api/webhooks/square
import { createHmac } from 'node:crypto';

export async function POST(req: NextRequest) {
  const rawBody = Buffer.from(await req.arrayBuffer());
  const signature = req.headers.get('x-square-hmacsha256-signature') ?? '';

  // Square HMAC includes the full notification URL in the signature
  const notificationUrl = `${process.env.APP_URL}/api/webhooks/square`;
  const expected = createHmac('sha256', process.env.SQUARE_WEBHOOK_SECRET!)
    .update(notificationUrl + rawBody.toString('utf8'))
    .digest('base64');

  if (signature !== expected) {
    return NextResponse.json({ error: 'Invalid signature' }, { status: 401 });
  }

  const event = JSON.parse(rawBody.toString('utf8'));

  if (event.type === 'inventory.count.updated') {
    const counts = event.data.object.inventory_counts ?? [];
    for (const count of counts) {
      const variant = await db.variants.findBySquareCatalogId(count.catalog_object_id);
      if (!variant) continue;

      await db.inventory.updateLocationQuantity(variant.sku, count.location_id, parseInt(count.quantity));
      const total = await db.inventory.getTotalAvailable(variant.sku);
      await redis.setex(`inventory:${variant.productId}`, 3600, String(total));
    }
  }

  return NextResponse.json({ accepted: true });
}

Handle cross-channel returns (online order returned in-store):

// lib/pos/returns.ts
export async function processInStoreReturn(params: {
  orderId: string;
  lineItems: Array<{ lineItemId: string; quantity: number }>;
  locationId: string;
}) {
  const { orderId, lineItems, locationId } = params;
  const order = await db.orders.findById(orderId);
  if (!order) throw new Error(`Order ${orderId} not found`);

  // Calculate refund amount
  const refundAmount = lineItems.reduce((sum, item) => {
    const line = order.lineItems.find(l => l.id === item.lineItemId)!;
    return sum + (line.unitPriceCents * item.quantity);
  }, 0);

  // Issue refund via original payment gateway
  if (order.paymentGateway === 'stripe') {
    await stripe.refunds.create({
      payment_intent: order.stripePaymentIntentId,
      amount: refundAmount,
      metadata: { orderId, locationId, channel: 'in_store_return' },
    });
  } else if (order.paymentGateway === 'square') {
    await paymentsApi.createPaymentRefund({
      idempotencyKey: `return_${orderId}_${Date.now()}`,
      paymentId: order.squarePaymentId!,
      amountMoney: { amount: BigInt(refundAmount), currency: 'USD' },
    });
  }

  // Restock returned items at the return location
  for (const item of lineItems) {
    const line = order.lineItems.find(l => l.id === item.lineItemId)!;
    await db.inventory.incrementLocationQuantity(line.sku, locationId, item.quantity);
  }

  await db.orders.addReturn({ orderId, lineItems, processedAtLocation: locationId, processedAt: new Date() });
}

Sync your product catalog to Square (required before Square can track inventory):

export async function syncProductToSquare(product: Product) {
  const { result } = await catalogApi.batchUpsertCatalogObjects({
    idempotencyKey: `sync_${product.sku}_${Date.now()}`,
    batches: [{
      objects: [{
        type: 'ITEM',
        id: `#item_${product.sku}`,
        itemData: {
          name: product.name,
          variations: product.variants.map(variant => ({
            type: 'ITEM_VARIATION' as const,
            id: `#var_${variant.sku}`,
            itemVariationData: {
              itemId: `#item_${product.sku}`,
              name: variant.name,
              sku: variant.sku,
              pricingType: 'FIXED_PRICING',
              priceMoney: { amount: BigInt(Math.round(variant.price * 100)), currency: 'USD' },
              trackInventory: true,
            },
          })),
        },
      }],
    }],
  });

  // Store Square-assigned IDs for future inventory updates
  for (const mapping of result.idMappings ?? []) {
    if (mapping.clientObjectId?.startsWith('#var_')) {
      const sku = mapping.clientObjectId.replace('#var_', '');
      await db.variants.update(sku, { squareCatalogVariationId: mapping.objectId });
    }
  }
}

Best Practices

• For Shopify merchants, use Shopify POS — it shares a single inventory system with your online store; no sync lag, no duplicate records, and unified reporting out of the box
• Reserve a safety stock buffer for the online store — never expose 100% of physical inventory online; reserve 10–20% as a buffer for in-store sales that happen faster than inventory sync can propagate
• Implement location-aware inventory — track stock per physical location (store), not just as a global total; this enables accurate click-and-collect availability
• Monitor sync lag — measure the time between a POS sale and the inventory update appearing online; alert when lag exceeds 5 minutes
• Build a manual reconciliation tool — inventory discrepancies happen; store managers need a UI to compare POS inventory counts with your system and trigger a manual sync

Common Pitfalls

Related Skills

• @marketplace-connectors
• @webhook-architecture
• @flash-sale-scaling
• @monitoring-alerting-commerce

Omnichannel Returns: Buy Online, Return In Any Store

Problem/Feature Description

Redwood Home Goods runs 12 physical stores and a flagship online shop. Their current returns policy only allows online purchases to be returned by mail — but competitor analysis shows that 60% of customers prefer to return items in-person. The operations team has decided to roll out a "return anywhere" policy: any online order can be returned at any physical store location, with a refund issued immediately back to the customer's original payment method.

The technical challenge is that online orders were paid through either Stripe or Square depending on which payment gateway was active when the order was placed. When a store associate processes a return, the system needs to find the original order, validate what can still be returned, process the refund through the correct channel, and update inventory counts at the specific store where the goods were physically handed back. The operations team is also mindful of the impact incorrect inventory counts have on the online availability displayed to shoppers — the timing of when inventory changes are reflected online matters.

Output Specification

Produce the following files:

• lib/pos/returns.ts — the main return processing module exporting a processInStoreReturn function
• returns.test.ts — unit tests (or a test script) covering at least: the already-refunded guard, the returnable quantity check, the gateway routing decision, and the inventory update behavior

The processInStoreReturn function should accept:

{
  orderId: string;
  lineItems: Array<{lineItemId: string; quantity: number; reason: string; status: string}>;
  locationId: string;
}

Assume the following are already implemented and can be imported/referenced:

• db.orders.findById(orderId) — returns an order with .status, .paymentGateway, .stripePaymentIntentId, .squarePaymentId, and .lineItems (each with .id, .sku, .unitPriceCents, .returnableQuantity)
• db.orders.addReturn({orderId, lineItems, gatewayRefundId, processedAt, processedAtLocation})
• db.inventory.incrementLocationQuantity(sku, locationId, qty)
• db.inventory.getTotalAvailable(sku)
• syncInventoryAcrossChannels({sku, quantity, source})
• stripe — Stripe SDK client instance
• paymentsApi — Square payments API client

Brick-and-Mortar Expansion: Square POS Catalog Setup

Problem/Feature Description

A fashion retailer called Varda Apparel has been running a successful online store for three years. They are now opening two physical boutique locations and have chosen Square as their point-of-sale system. Their existing product database contains hundreds of SKUs with names, descriptions, variants (size/color combinations), and prices. Before they can start selling in-store, every product needs to be available in Square so that cashiers can ring up sales, and so that in-store inventory movements are trackable per location.

The engineering team needs a TypeScript module that reads from the Varda product database and pushes the catalog into Square. The integration must be production-safe: it should work against Square's sandbox during development and switch to the live environment automatically when deployed. Catalog syncs will be triggered both on product updates and on a nightly batch job, so the implementation must be safe to run repeatedly without creating duplicate catalog entries or payments.

Output Specification

Produce a TypeScript file named catalog-sync.ts that exports:

• A syncProductToSquare(product: Product) function that syncs a single product and its variants to Square
• A Square client setup (may be in a separate square-client.ts file if you prefer)

Also produce a brief DESIGN.md file (max 300 words) explaining: 1. How new vs. existing catalog objects are identified 2. How Square-assigned IDs are stored back into the product database after the first sync

The following type definitions are provided as the starting data model. Extract them before beginning.

=============== FILE: inputs/types.ts =============== export interface Product { sku: string; name: string; description?: string; variants: Variant[]; }

export interface Variant { sku: string; name: string; price: number; // in dollars, e.g. 29.99 squareCatalogVariationId?: string; // populated after first sync }

Real-Time Inventory Sync: Square POS Webhook Handler

Problem/Feature Description

Pinnacle Sports is a multi-location sporting goods retailer with an online store built on Next.js and several physical locations running Square POS terminals. When a staff member rings up a sale at any store, the online store needs to reflect the updated stock immediately — customers have been completing purchases online for items that were already sold in-store, leading to oversells and angry order cancellations.

The team wants to build a webhook endpoint that Square will call whenever inventory changes, payments complete, or catalog updates occur. Security is critical: Square signs every webhook delivery, and the handler must reject any unsigned or tampered requests. The online store should never expose the full physical stock count directly — the visible quantity should account for the fact that in-store sales can happen faster than the sync propagates.

The endpoint will be deployed as a Next.js App Router API route at /api/webhooks/square.

Output Specification

Produce the following files:

• app/api/webhooks/square/route.ts — the Next.js App Router POST handler
• lib/pos/inventory-handler.ts — the inventory update logic called from the webhook (may be inlined into route.ts if you prefer)

Also produce a NOTES.md file (max 200 words) that explains: 1. How the signature verification works and why it is constructed the way it is 2. How online-visible inventory is calculated from the raw location counts

Assume the following are already implemented (do not redefine them, just import/reference them):

• db.variants.findBySquareCatalogId(variationId) — returns a variant object with .sku
• db.inventory.updateLocationQuantity(sku, locationId, qty) — sets qty for one location
• db.inventory.getTotalAvailable(sku) — returns total available (you must implement the safety stock logic here or in the webhook handler)
• syncInventoryAcrossChannels({sku, quantity, source}) — pushes the quantity to the online store
• syncCatalogFromSquare() — re-fetches catalog from Square
• handleSquarePayment(obj) and handleSquareRefund(obj) — stubs you may reference