--- title: "n8n | Crossmart Docs" description: "The Crossmart community nodes for n8n, to automate products, stock, listings and orders and start workflows from Crossmart webhooks on new orders, stock changes and failed listings." url: "https://docs.crossmart.io/integrations/n8n/" --- # n8n `n8n-nodes-crossmart` is the official [n8n](https://n8n.io/) community node package for Crossmart. It has three nodes: - **Crossmart:** products, stock, listings, orders and stores. It can also be a tool of n8n’s AI Agent. - **Crossmart Trigger:** starts a workflow the moment Crossmart sends an event (orders, stock, listings, products), through a [webhook](https://docs.crossmart.io/developers/webhooks/). - **Crossmart Polling Trigger:** the fallback when Crossmart can’t reach n8n. It checks the API on a schedule for new orders, stock changes and failed listings. The package is MIT-licensed. The package is not published to npm yet. Once it is, install it as below. ## Install In n8n, open **Settings → Community nodes → Install** and enter `n8n-nodes-crossmart`. ## Credentials Add a **Crossmart API** credential with a workspace API key (dashboard: **Settings → API keys**) and, if you self-host Crossmart, your API’s base URL. The default is `https://api.crossmart.io`; a trailing slash or `/api/v1` is fine. n8n tests the credential with `GET /api/v1/api-key`, and the nodes use the same call to find the key’s workspace, so there is no workspace field to fill. Use a key for n8n alone, with the smallest role that works (see [Roles and permissions](https://docs.crossmart.io/developers/permissions/)): | What the workflow does | Role | | - | - | | Reads products, stock, orders; runs the **Crossmart Polling Trigger** | `VIEWER` | | Creates and updates products, adjusts stock, publishes and retries listings | `EDITOR` | | Syncs stores | `ADMIN` | | Runs the **Crossmart Trigger** (creates and deletes its webhook endpoint) | `ADMIN`, or a custom role with `webhooks:manage` | ## Examples - **Restock from a purchase order:** a Google Sheets trigger → **Inventory → Get by SKU** → **Inventory → Adjust Stock** (mode _Add or Remove_, reason _Received_, note = the PO number). - **Alert on failed listings:** **Crossmart Trigger** (_Listing Failed_) → Slack, with `{{$json.data.listing.channel}}` and `{{$json.data.listing.lastError}}`; then fix the product and run **Listing → Retry** with `{{$json.data.listing.productId}}` and `{{$json.data.listing.connectionId}}`. - **Orders to a spreadsheet:** **Crossmart Trigger** (_Order Created_) → Google Sheets, one row per order from `{{$json.data.order.name}}`, `{{$json.data.order.total}}` and `{{$json.data.order.lines}}`. - **Low stock report:** Schedule → **Inventory → Get Many** (stock level _Low Stock_, Return All) → email. ## How the triggers work ### Crossmart Trigger The trigger receives Crossmart’s [webhooks](https://docs.crossmart.io/developers/webhooks/), where the events, their payloads and the signature are documented. 1. **When you activate the workflow**, the node adds a webhook endpoint in Crossmart that points at the workflow’s webhook URL, with the events you picked, and keeps its signing secret. If the endpoint it made before is gone, turned off or out of date, it replaces it. 2. **For each event**, the node checks the `Crossmart-Signature` header and refuses deliveries that don’t verify (`401`), so they never run the workflow. Events you didn’t pick are acknowledged and dropped; a test event always runs it. Delivery is at least once, so the node remembers the last 100 event ids and drops repeats. The workflow gets one item per event: the whole envelope, `{ id, type, createdAt, workspaceId, apiVersion, data }`. 3. **When you deactivate the workflow**, the node deletes its endpoint. Activating fails with a clear message when the key lacks `webhooks:manage` (403), the plan’s webhook endpoint limit is reached (402), or Crossmart refuses the URL (400: Crossmart Cloud only delivers to public `https` URLs). If n8n runs behind a proxy, set n8n’s `WEBHOOK_URL` to its public URL. Workflows saved with version 0.1 of the package used a polling Crossmart Trigger. They keep polling after an upgrade; new Crossmart Trigger nodes use webhooks. ### Crossmart Polling Trigger Use it when Crossmart can’t reach n8n, such as n8n on a laptop or on a private network. It polls the REST API on the interval set in n8n and remembers what it has seen: | Event | Emits | | - | - | | New Order | Each order it hasn’t seen, newest first | | Stock Changed | Each inventory item whose stock changed since the last check | | Listing Failed | Each listing that failed since the last check, with the store’s reason | The first check after activation records the starting point and emits nothing, so activating a workflow doesn’t replay history. A listing that recovers and fails again, or fails again with another error, is emitted again. One check reads at most 10 pages. ## Limits - **The Polling Trigger** delivers events on n8n’s polling interval, not instantly. Its **Stock Changed** emits an item’s current stock, not each movement (the webhook’s `inventory.stock_changed` carries `availableDelta` and `reason`), and its **New Order** can miss an order a store reports late, with an older order date than the last 1,000 orders. - **Update** replaces the whole product, so the node reads it first and sends it back whole. Two workflows updating the same product at once can overwrite each other. - **Get by SKU** searches and keeps exact matches.