How to Integrate Retool with Square (Inventory & Catalog)

Before configuring Retool, you need a Square access token. Navigate to developer.squareup.com and sign in with your Square account. Click 'Applications' in the left sidebar and select an existing application or click 'Create Your First Application' to make a new one. Give it a name like 'Retool Inventory Manager'. Once the application is created, click into it and navigate to the 'Credentials' tab. You will see two sets of credentials: Sandbox (for testing) and Production (for live data). For initial setup, copy the Sandbox access token — it starts with 'EAAAl' and is safe for development. When you are ready to connect to real inventory data, switch to the Production access token. Keep in mind that Square access tokens are scoped to specific applications and automatically include permissions based on your app's approved scopes. For inventory management, your app needs INVENTORY_READ, INVENTORY_WRITE, ITEMS_READ, and ITEMS_WRITE permissions — these are available by default for new Square Developer applications. Store this token securely; you will paste it into Retool in the next step. Do not commit it to any code repository or share it in plain text.

In Retool, navigate to the Resources tab from the left sidebar of your organization homepage, or access it directly at your Retool instance URL followed by /resources. Click '+ Create new' and scroll through the connector list to select 'REST API'. On the resource configuration screen, fill in the Name field with something descriptive like 'Square API' so it is recognizable in the query editor across multiple apps. Set the Base URL to https://connect.squareup.com for production, or https://connect.squareupsandbox.com for Sandbox testing. Under Headers, click 'Add header' and add two headers: first, Content-Type with value application/json (required for all Square API requests that send a body), and second, Square-Version with value 2024-01-18 (or the latest API version from Square's changelog — pinning a version prevents breaking changes from affecting your integration). For authentication, select 'Bearer token' from the Authentication dropdown and paste your Square access token in the token field. Click 'Test connection' to verify — Retool will make a lightweight request to confirm the base URL and token are valid. If the test passes, click 'Save resource'. The resource is now available to all apps in your Retool organization. All requests through this resource are proxied server-side, so your Square token is never exposed in browser network traffic.

Open a new or existing Retool app and navigate to the Code panel at the bottom of the screen. Click '+ New query', select your Square API resource, and give the query a clear name like getCatalogItems. Set the Method to POST — Square's catalog search endpoint uses POST even for read operations, which is a common source of confusion. Set the URL path to /v2/catalog/search. In the Body section, select JSON and enter the search parameters. The request body controls which object types to return and supports cursor-based pagination. Square uses 'cursor' for pagination — the first response omits it when there are no more pages, and includes it when more results exist. Set the body to specify ITEM as the object type and enable include_related_objects to also get CatalogItemVariation records (which hold per-variant pricing and SKU data) in the same response. Set limit to 100 (the maximum per page). Click 'Run query' to test. Square returns a catalog_objects array where each object has type ITEM, a data field with item metadata, and a related_objects array containing the associated variants. Name your query getCatalogItems and note the structure of the response — you will flatten it in the next step using a JavaScript transformer.

1{
2  "object_types": ["ITEM"],
3  "include_related_objects": true,
4  "limit": 100,
5  "cursor": "{{ getCatalogItems.data.cursor || '' }}"
6}

Create a second query to fetch real-time inventory counts. In the Code panel, click '+ New query', select your Square API resource, and name this query getInventoryCounts. Set the Method to POST and the URL path to /v2/inventory/counts/batch-retrieve. This endpoint accepts a list of catalog object IDs (the variant IDs from your catalog query) and location IDs, and returns current inventory counts for each combination. In the Body, provide location_ids as an array — you can hardcode your location IDs during development or reference a Select component if you want users to filter by location dynamically. Set the catalog_object_ids array to reference the variant IDs from your getCatalogItems query using Retool's double-brace syntax to extract them from the previous query's response. Set cursor to handle pagination using the same pattern as the catalog query. Run the query to verify it returns inventory count objects — each count has a catalog_object_id (the variant ID), location_id, quantity (as a string), and calculated_at timestamp. Note that Square returns quantity as a string, not a number, so your transformer will need to convert it with parseFloat(). This is a known Square API quirk that trips up many integrations.

1{
2  "location_ids": ["YOUR_LOCATION_ID"],
3  "catalog_object_ids": {{ getCatalogItems.data.related_objects?.filter(o => o.type === 'ITEM_VARIATION').map(v => v.id) || [] }},
4  "cursor": "{{ getInventoryCounts.data.cursor || '' }}"
5}

Square's catalog and inventory data come from separate API endpoints and need to be joined on the variant ID to produce a unified view. Create a JavaScript transformer to merge these datasets. In the Code panel, click '+ New query', but this time select 'JavaScript' as the query type instead of a resource. Name it inventoryDashboardData. In the transformer, you will access the previous two queries' results directly using their names. First, extract the variant objects from the catalog response — they are in the related_objects array filtered to type ITEM_VARIATION. Build a lookup map from catalog item ID to item name by iterating over the catalog_objects array (type ITEM). Then, iterate over the inventory counts from getInventoryCounts and join each count to its variant data and parent item name using the ID maps. Convert quantity from string to number using parseFloat(). Add a derived field for stock status: 'Critical' when quantity is below 5, 'Low' when below your reorder threshold (reference a NumberInput component for a configurable threshold), and 'OK' otherwise. Return the merged array. Bind the output of this transformer to a Table component by dragging a Table onto the canvas and setting its Data source to {{ inventoryDashboardData.data }}. Add columns for item name, SKU, location, quantity, and stock status. Apply conditional row coloring by setting the Table's row color property to reference the stock_status field: red for Critical, yellow for Low, and no color for OK. For complex multi-location inventory operations with automated reorder workflows, RapidDev's team can help architect your full Retool solution.

1// Join catalog items with inventory counts
2const catalogItems = getCatalogItems.data.catalog_objects || [];
3const relatedObjects = getCatalogItems.data.related_objects || [];
4const inventoryCounts = getInventoryCounts.data.counts || [];
5const reorderThreshold = numberInput1.value || 10;
6
7// Build item name lookup: item_id -> item_name
8const itemNameMap = {};
9catalogItems.forEach(item => {
10  if (item.type === 'ITEM') {
11    itemNameMap[item.id] = item.item_data?.name || 'Unknown Item';
12  }
13});
14
15// Build variant lookup: variant_id -> { sku, item_id }
16const variantMap = {};
17relatedObjects.forEach(obj => {
18  if (obj.type === 'ITEM_VARIATION') {
19    variantMap[obj.id] = {
20      sku: obj.item_variation_data?.sku || 'N/A',
21      item_id: obj.item_variation_data?.item_id,
22      name: obj.item_variation_data?.name || 'Default'
23    };
24  }
25});
26
27// Merge inventory counts with catalog data
28return inventoryCounts.map(count => {
29  const variant = variantMap[count.catalog_object_id] || {};
30  const qty = parseFloat(count.quantity) || 0;
31  const status = qty < 5 ? 'Critical' : qty < reorderThreshold ? 'Low' : 'OK';
32  return {
33    item_name: itemNameMap[variant.item_id] || 'Unknown',
34    variant: variant.name,
35    sku: variant.sku,
36    location_id: count.location_id,
37    quantity: qty,
38    stock_status: status,
39    last_updated: new Date(count.calculated_at).toLocaleString()
40  };
41});

With the dashboard built, create a Retool Workflow to send automated low-stock alerts on a schedule so ops managers are notified before stock runs out, not after. Navigate to the Workflows section in Retool (left sidebar → Workflows) and click '+ New Workflow'. Name it 'Square Low Stock Alert'. On the Workflow canvas, you will see a default Start block. Add a Schedule trigger by clicking the trigger icon and selecting 'Schedule' — configure it to run daily at 8:00 AM in your timezone using the cron expression. Add a Resource Query block by dragging it onto the canvas. Select your Square API resource, set it to POST /v2/inventory/counts/batch-retrieve with your location IDs, and name this block fetchInventory. Connect the Schedule trigger to this block. Add a Code block (JavaScript) connected after fetchInventory — this block filters the inventory counts to find items below threshold. Set your threshold directly in the code block using a constant (e.g., const REORDER_THRESHOLD = 10). The code should parse quantities, filter low-stock items, and format a summary message. Connect a final Resource Query block to send the alert — if you have Slack connected as a Resource in Retool, use a Slack resource query to post a message; alternatively use an HTTP POST to a Slack incoming webhook URL. Click 'Publish release' to activate the scheduled workflow. You can test it immediately using the 'Run now' button before the first scheduled execution. Every run is logged in the Workflow history with per-block status for easy debugging.

1// Code block: filter low-stock items and format alert message
2const counts = fetchInventory.data.counts || [];
3const REORDER_THRESHOLD = 10;
4
5const lowStockItems = counts
6  .filter(c => parseFloat(c.quantity) < REORDER_THRESHOLD)
7  .map(c => ({
8    variant_id: c.catalog_object_id,
9    location: c.location_id,
10    quantity: parseFloat(c.quantity),
11    alert: parseFloat(c.quantity) < 5 ? '🔴 CRITICAL' : '🟡 LOW'
12  }));
13
14if (lowStockItems.length === 0) {
15  return { message: 'All inventory levels are healthy.', count: 0 };
16}
17
18const lines = lowStockItems.map(i =>
19  `${i.alert} Variant ${i.variant_id} at location ${i.location}: ${i.quantity} units`
20).join('\n');
21
22return {
23  message: `Square Inventory Alert — ${lowStockItems.length} items need restocking:\n${lines}`,
24  count: lowStockItems.length
25};