How to Integrate Square with Your Headless CMS

What is Square?

Square is Block's commerce platform for taking payments, running point-of-sale systems, selling online, sending invoices, and tracking inventory. Restaurants, retailers, service businesses, and event sellers use Square to connect in-person sales with online ordering, customer records, and catalog data. Its APIs cover payments, catalog items, orders, inventory, customers, locations, and webhooks.

Why integrate Square with a headless CMS?

Square is often where the transaction happens, but it’s rarely where your full product story lives. A coffee shop may need Square for POS and online ordering, while the website needs tasting notes, farmer profiles, brewing instructions, SEO fields, and localized descriptions. If those details sit in a headless CMS while prices and SKUs sit in Square, teams end up copying product names, menu descriptions, and availability by hand.

Connecting Square to a headless CMS fixes that split. You can model the product content once, publish it, and send the exact fields Square needs to the Catalog API. With Sanity’s structured content in the Content Lake, that can mean a GROQ query that selects title, SKU, price, category, modifier copy, and Square location IDs. Webhooks or Functions can run the sync when a product is published, updated, or archived, instead of waiting for a nightly job.

The trade-off is that you need to decide ownership clearly. Square should usually remain the source for payments, orders, taxes, and inventory adjustments. Your AI Content Operating System should own editorial fields, product descriptions, merchandising content, and channel-specific copy. If you blur that line, you’ll create conflicts that are hard to debug, especially when POS staff update an item during store hours.

Architecture overview

A typical Square integration starts with structured product content in Sanity’s Content Lake. In Sanity Studio, editors publish a product document with fields such as title, description, SKU, price in cents, category reference, availability, image, and Square location mapping. A Sanity webhook fires on product publish, update, or delete. The webhook can call a Sanity Function or your own API route. That server-side handler receives the mutation payload, uses @sanity/client to fetch the full product with GROQ, and projects only the fields Square needs. For example, it can join the category reference, normalize Portable Text into plain text, and read a stored squareCatalogId if the item already exists. The handler then calls Square’s Catalog API, usually upsertCatalogObject, to create or update a CatalogItem and its CatalogItemVariation. For stock changes, it can call Square’s Inventory API, but many teams keep inventory updates flowing from Square back into their storefront instead. From there, the end user sees consistent product data wherever they shop. The website can read rich content directly from Sanity, while checkout and POS use Square’s catalog, payment, and order systems. If you also listen to Square webhooks, such as inventory.count.updated or order.created, you can update availability badges, hide sold-out items, or trigger follow-up content workflows without polling either system.

Common use cases

Step-by-step integration

1. 1

   Create and configure your Square app

   In the Square Developer Dashboard, create an application, choose Sandbox for testing, and copy the Sandbox access token. Note your Square location ID, then confirm your app has catalog permissions such as ITEMS_READ and ITEMS_WRITE. Move to Production only after you’ve tested catalog writes, price formatting, and item IDs.

2. 2

   Install the Square and Sanity clients

   In your integration project or Sanity Function, install the SDKs with npm i square @sanity/client. Add SQUARE_ACCESS_TOKEN, SQUARE_ENVIRONMENT, SANITY_PROJECT_ID, SANITY_DATASET, and SANITY_API_TOKEN to your environment variables. Use a Sanity token with read access, and write access only if you plan to save Square IDs back to product documents.

3. 3

   Model commerce content in Sanity Studio

   Create a product schema with fields like title, slug, description, sku, priceCents, category reference, squareCatalogId, squareLocationIds, availableForPickup, and publishToSquare. Keep price in cents as an integer so it maps cleanly to Square Money.amount. If Square owns price in your business, store squareCatalogId only, and read price from Square on the frontend.

4. 4

   Create the sync trigger

   Set up a Sanity webhook that fires when product documents are published, updated, or deleted. Use a GROQ filter such as _type == 'product' && publishToSquare == true. Point the webhook at a Sanity Function or API route that can fetch the full product and call Square from the server.

5. 5

   Call Square’s Catalog API

   In the handler, fetch the product from Sanity with GROQ, then call Square’s Catalog API to create or update a CatalogItem and CatalogItemVariation. Use idempotency keys for safe retries. Store the returned Square catalog object ID in Sanity if you want future publishes to update the same item instead of creating a new one.

6. 6

   Test the storefront and POS flow

   Publish one test product, verify it appears in Square Sandbox, and confirm the price, SKU, category, and variation names are correct. Then build the frontend so rich product pages read from Sanity, while checkout uses Square. Test failure cases too, including missing SKU, invalid price, archived item, and Square rate limits.

How Sanity + Square works

CMS approaches to Square

Keep building

Explore related integrations to complete your content stack.