8b:T534,# Vendure stock monitoring plugin This plugin helps you monitor the stock levels in two ways: 1. A dashboard widget that displays variants that have stock level's below their threshold 2. An event is emitted when a variant's stock level drops below a given threshold after each placed order. ## Getting started 1. Add the plugin to your `vendure-config.ts` to expose a `productVariantsWithLowStock` query in the admin API. ```ts import { StockMonitoringPlugin } from '@pinelab/vendure-plugin-stock-monitoring'; plugins: [ StockMonitoringPlugin.init({ globalThreshold: 10, uiTab: 'My Admin UI Tab', }), ]; ``` The "Low stock" widget is provided as a React Dashboard extension — no Admin UI compilation step is needed. When you start the server and login, you can find `Low stock` under the dashboard's `add widget` button. ### Caveats 1. This plugin doesn't use the `StockLocationStrategy` because of performance reasons. Instead, it fetches the stock level for each variant from the database and calculates its absolute stock based on the `stockOnHand` and `stockAllocated` fields. 2. Performance: Each allocation, sale or adjustment in `StockMovementEvent` will create a job that triggers a stock check: get saleable stock, compare with variant threshold, and emit event if variant dropped below threshold. 8c:Ta9f,# 3.1.2 (2026-08-21) - Fixed `getVariantsBelowThreshold` query failing on PostgreSQL (`column "FALSE" does not exist`): use a bound string parameter instead of the double-quoted `"FALSE"` (an identifier in Postgres), and reference the full expressions in `HAVING` instead of SELECT aliases (which Postgres does not allow in `HAVING`). The configured `globalThreshold` is now bound as a query parameter too. Works across PostgreSQL, MySQL and SQLite. # 3.1.1 (2026-08-04) - Include dashboard extensions in dist. # 3.1.0 (2026-07-21) - Migrated to React Dashboard # 3.0.0 (2026-07-15) - Listen to StockMovementEvent for ALLOCATION, SALE, and ADJUSTMENT movements to check if stock dropped below threshold - Removed OrderPlacedEvent-based stock monitoring in favor of StockMovementEvent-based monitoring - Renamed `StockDroppedBelowThresholdEvent` fields from `stockBeforeOrder`/`stockAfterOrder` to `stockBeforeAdjustment`/`stockAfterAdjustment` - Removed `order` field from `StockDroppedBelowThresholdEvent` # 2.2.1 (2026-05-29) - Fixed stock-monitoring widget to display items sorted from lowest to highest available stock - Widget now shows available stock (stockOnHand - stockAllocated) instead of only stockOnHand # 2.2.0 (2026-08-05) - Upgraded to Vendure 3.6.3 # 2.1.1 (2026-05-19) - Fixed `trackInventory` query filter to use correct boolean string value - Set stock monitoring query limit to 100 variants # 2.1.0 (2026-02-05) - Upgraded to Vendure 3.5.3 # 2.0.2 (2025-11-13) - Documentation update # 2.0.1 (2025-11-06) - Updated official documentation URL # 2.0.0 (2025-10-17) - Added support for per variant thresholds - Emitting event when a variant's stock level drops below a given threshold - Processing stock checking in worker instead of main process. - BREAKING: removed email handler functionality. You can implement your own email handler by listening to the event `StockLevelBelowThresholdEvent`. # 1.6.0 (2025-06-04) - Upgrade to Vendure to 3.3.2 # 1.5.1 (2025-03-27) - Prevent error `column "stockonhand" does not exist` on Postgres # 1.5.0 (2024-12-19) - Update Vendure to 3.1.1 # 1.4.1 (2024-08-04) - Update compatibility range (#480) # 1.4.0 (2024-06-21) - Updated Vendure to 2.2.6 # 1.3.2 (2024-02-27) - Show max 100 out of stock items instead of 50 # 1.3.1 (2023-11-21) - Fixed link to products from stock widget # 1.3.0 (2023-11-09) - Fixed `reduceSum` function call bug - Made `StockWidgetComponent` standalone and removed `StockWidgetSharedModule` and `StockWidgetModule` # 1.2.0 (2023-10-26) - Fix broken links as described [here](https://github.com/Pinelab-studio/pinelab-vendure-plugins/issues/277) # 1.1.0 (2023-10-24) - Updated vendure to 2.1.1 8d:T42f4,## 3.3.11-next.1 ### 🚀 Features - **product-import-export-plugin:** backport id export field + customExportColumns to 3.5 line (3.3.11-next.0) ([#22](https://github.com/WeAreHausTech/haus-tech-vendure-plugins-public/pull/22)) ## 3.3.11-next.0 ### 🚀 Features - **product-import-export-plugin:** add progress reporting to product export process ([ed6220e](https://github.com/WeAreHausTech/haus-tech-vendure-plugins-public/commit/ed6220e)) - **product-import-export-plugin:** optimize product export process and stock level retrieval ([d281929](https://github.com/WeAreHausTech/haus-tech-vendure-plugins-public/commit/d281929)) - **product-import-export-plugin:** enhance email notification and import/export functionality ([c133dc5](https://github.com/WeAreHausTech/haus-tech-vendure-plugins-public/commit/c133dc5)) - **product-import-export-plugin:** enforce import/export acceptance criteria and enhance documentation ([b1a93b6](https://github.com/WeAreHausTech/haus-tech-vendure-plugins-public/commit/b1a93b6)) - **product-import-export-plugin:** update pre-version command and clean up export artifacts ([1cde024](https://github.com/WeAreHausTech/haus-tech-vendure-plugins-public/commit/1cde024)) - **product-import-export-plugin:** optimize asset handling and caching in product importer ([9d2888e](https://github.com/WeAreHausTech/haus-tech-vendure-plugins-public/commit/9d2888e)) - **product-import-export-plugin:** enhance testing and export functionality ([1764eb2](https://github.com/WeAreHausTech/haus-tech-vendure-plugins-public/commit/1764eb2)) ### 🩹 Fixes - **product-import-export-plugin:** ensure tax category is always assigned to product variants ([276bed5](https://github.com/WeAreHausTech/haus-tech-vendure-plugins-public/commit/276bed5)) - **product-import-export-plugin:** poll exports list and restore featured asset on import ([2c61b48](https://github.com/WeAreHausTech/haus-tech-vendure-plugins-public/commit/2c61b48)) ## 3.3.10-next.6 ### 🩹 Fixes - **product-import-export-plugin:** ensure tax category is always assigned to product variants ([276bed5](https://github.com/WeAreHausTech/haus-tech-vendure-plugins-public/commit/276bed5)) ## 3.3.10-next.5 ### 🚀 Features - **product-import-export-plugin:** add progress reporting to product export process ([ed6220e](https://github.com/WeAreHausTech/haus-tech-vendure-plugins-public/commit/ed6220e)) ## 3.3.10-next.4 ### 🚀 Features - **product-import-export-plugin:** optimize product export process and stock level retrieval ([d281929](https://github.com/WeAreHausTech/haus-tech-vendure-plugins-public/commit/d281929)) ## 3.3.10-next.3 ### 🚀 Features - **product-import-export-plugin:** optimize product export process and stock level retrieval ([d281929](https://github.com/WeAreHausTech/haus-tech-vendure-plugins-public/commit/d281929)) ## 3.3.10-next.2 ### 🩹 Fixes - **product-import-export-plugin:** poll exports list and restore featured asset on import ([2c61b48](https://github.com/WeAreHausTech/haus-tech-vendure-plugins-public/commit/2c61b48)) ## 3.3.2-next.2 ### 🚀 Features - **product-import-export-plugin:** enhance email notification and import/export functionality ([c133dc5](https://github.com/WeAreHausTech/haus-tech-vendure-plugins-public/commit/c133dc5)) ## 3.3.2-next.1 ### 🚀 Features - **product-import-export-plugin:** enforce import/export acceptance criteria and enhance documentation ([b1a93b6](https://github.com/WeAreHausTech/haus-tech-vendure-plugins-public/commit/b1a93b6)) - **product-import-export-plugin:** update pre-version command and clean up export artifacts ([1cde024](https://github.com/WeAreHausTech/haus-tech-vendure-plugins-public/commit/1cde024)) ## 3.3.2-next.0 ### 🚀 Features - **product-import-export-plugin:** optimize asset handling and caching in product importer ([9d2888e](https://github.com/WeAreHausTech/haus-tech-vendure-plugins-public/commit/9d2888e)) - **product-import-export-plugin:** enhance testing and export functionality ([1764eb2](https://github.com/WeAreHausTech/haus-tech-vendure-plugins-public/commit/1764eb2)) - **product-import-export-plugin:** enforce import/export acceptance criteria (column-presence updates, multi-variant option requirements, no ProductID export option, clearer import CTA, and strict required relation custom-field validation) ## 3.3.1 This was a version bump only for product-import-export-plugin to align it with other projects, there were no code changes. ## 3.3.1-next.0 ### 🚀 Features - enhance file name validation for product export functionality ([f9d5a45](https://github.com/WeAreHausTech/haus-tech-vendure-plugins-public/commit/f9d5a45)) - enhance export storage strategy configuration ([d589906](https://github.com/WeAreHausTech/haus-tech-vendure-plugins-public/commit/d589906)) - abstract logic into separate strategies ([1c7d0c7](https://github.com/WeAreHausTech/haus-tech-vendure-plugins-public/commit/1c7d0c7)) - enhance product export functionality with file name sanitization and S3 region update ([06af120](https://github.com/WeAreHausTech/haus-tech-vendure-plugins-public/commit/06af120)) - add S3 storage support for product export functionality ([08c0901](https://github.com/WeAreHausTech/haus-tech-vendure-plugins-public/commit/08c0901)) ### 🩹 Fixes - correct file path handling and ensure consistent file name sanitization in product export ([03a5bb5](https://github.com/WeAreHausTech/haus-tech-vendure-plugins-public/commit/03a5bb5)) ## 3.2.1 This was a version bump only for product-import-export-plugin to align it with other projects, there were no code changes. ## 3.2.0 This was a version bump only for product-import-export-plugin to align it with other projects, there were no code changes. ## 3.1.10 This was a version bump only for product-import-export-plugin to align it with other projects, there were no code changes. ## 3.1.9 This was a version bump only for product-import-export-plugin to align it with other projects, there were no code changes. ## 3.1.8 This was a version bump only for product-import-export-plugin to align it with other projects, there were no code changes. ## 3.1.7 This was a version bump only for product-import-export-plugin to align it with other projects, there were no code changes. ## 3.1.6 This was a version bump only for product-import-export-plugin to align it with other projects, there were no code changes. ## 3.1.5 This was a version bump only for product-import-export-plugin to align it with other projects, there were no code changes. ## 3.1.4 This was a version bump only for product-import-export-plugin to align it with other projects, there were no code changes. ## 3.1.3 ### 🚀 Features - enhance product import logic to handle soft-deleted products ([c88a164](https://github.com/WeAreHausTech/haus-tech-vendure-plugins/commit/c88a164)) ## 3.1.2 ### 🩹 Fixes - correct languageCode reference in slug assignment logic ([6c4d56d](https://github.com/WeAreHausTech/haus-tech-vendure-plugins/commit/6c4d56d)) ## 3.1.1 ### 🩹 Fixes - update slug assignment logic in ProductImporter ([#74](https://github.com/WeAreHausTech/haus-tech-vendure-plugins/pull/74)) ## 3.1.0 This was a version bump only for product-import-export-plugin to align it with other projects, there were no code changes. ## 3.0.31-0 ### 🩹 Fixes - improve error handling and type safety in import/export plugin ([81ca5cf](https://github.com/WeAreHausTech/haus-tech-vendure-plugins/commit/81ca5cf)) ## 3.0.30 ### 🚀 Features - **product-import-export-plugin:** enhance product export functionality with temporary file handling ([aed754f](https://github.com/WeAreHausTech/haus-tech-vendure-plugins/commit/aed754f)) ## 3.0.29 ### 🚀 Features - **product-import-export-plugin:** add bulk export and exported files list components ([eb56ade](https://github.com/WeAreHausTech/haus-tech-vendure-plugins/commit/eb56ade)) ## 3.0.29-1 ### 🚀 Features - **product-import-export-plugin:** implement product export queue and enhance export functionality ([7e2d9f0](https://github.com/WeAreHausTech/haus-tech-vendure-plugins/commit/7e2d9f0)) ## 3.0.29-0 This was a version bump only for product-import-export-plugin to align it with other projects, there were no code changes. ## 3.0.28-0 ### 🚀 Features - **product-import-export-plugin:** replace request header logic with channel-specific headers ([dfc781c](https://github.com/WeAreHausTech/haus-tech-vendure-plugins/commit/dfc781c)) - **product-import-export-plugin:** enhance import/export functionality and dashboard integration ([825ee89](https://github.com/WeAreHausTech/haus-tech-vendure-plugins/commit/825ee89)) ## 3.0.27-4 This was a version bump only for product-import-export-plugin to align it with other projects, there were no code changes. ## 3.0.27-3 This was a version bump only for product-import-export-plugin to align it with other projects, there were no code changes. ## 3.0.27-2 This was a version bump only for product-import-export-plugin to align it with other projects, there were no code changes. ## 3.0.27-1 This was a version bump only for product-import-export-plugin to align it with other projects, there were no code changes. ## 3.0.27-0 ### 🚀 Features - **product-import-export-plugin:** add restoreSoftDeleted option for product import ([0458a2a](https://github.com/WeAreHausTech/haus-tech-vendure-plugins/commit/0458a2a)) - **product-importer:** enhance product variant handling ([4af2198](https://github.com/WeAreHausTech/haus-tech-vendure-plugins/commit/4af2198)) - **product-import-export-plugin:** enhance product import service with event bus integration and collection filtering ([#48](https://github.com/WeAreHausTech/haus-tech-vendure-plugins/pull/48)) - **product-import-export-plugin:** implement removal of option groups from product ([39f34ec](https://github.com/WeAreHausTech/haus-tech-vendure-plugins/commit/39f34ec)) - Enhance asset importer with URL and local file stream handling ([2b5ae3d](https://github.com/WeAreHausTech/haus-tech-vendure-plugins/commit/2b5ae3d)) ### 🩹 Fixes - **product-import-export-plugin:** improve import parser handling ([c952c7b](https://github.com/WeAreHausTech/haus-tech-vendure-plugins/commit/c952c7b)) - **product-import-export-plugin:** improve variant enabled handling ([a3a6af3](https://github.com/WeAreHausTech/haus-tech-vendure-plugins/commit/a3a6af3)) - **product-import-export-plugin:** improve option group handling and validate custom fields ([a95db85](https://github.com/WeAreHausTech/haus-tech-vendure-plugins/commit/a95db85)) - **product-import-export-plugin:** handle undefined prices in product variants ([#49](https://github.com/WeAreHausTech/haus-tech-vendure-plugins/pull/49)) - Refactor facetValues and options mapping for consistency in extended fast importer ([3514892](https://github.com/WeAreHausTech/haus-tech-vendure-plugins/commit/3514892)) - Improve asset and product importer logic for better channel handling and data consistency ([bc9416e](https://github.com/WeAreHausTech/haus-tech-vendure-plugins/commit/bc9416e)) - Assign assets to current channel on import ([#41](https://github.com/WeAreHausTech/haus-tech-vendure-plugins/pull/41)) ## 3.0.24-0 ### 🚀 Features - **product-import-export-plugin:** add restoreSoftDeleted option for product import ([0458a2a](https://github.com/WeAreHausTech/haus-tech-vendure-plugins/commit/0458a2a)) - **product-importer:** enhance product variant handling ([4af2198](https://github.com/WeAreHausTech/haus-tech-vendure-plugins/commit/4af2198)) - **product-import-export-plugin:** enhance product import service with event bus integration and collection filtering ([#48](https://github.com/WeAreHausTech/haus-tech-vendure-plugins/pull/48)) - **product-import-export-plugin:** implement removal of option groups from product ([39f34ec](https://github.com/WeAreHausTech/haus-tech-vendure-plugins/commit/39f34ec)) - Enhance asset importer with URL and local file stream handling ([2b5ae3d](https://github.com/WeAreHausTech/haus-tech-vendure-plugins/commit/2b5ae3d)) ### 🩹 Fixes - **product-import-export-plugin:** improve import parser handling ([c952c7b](https://github.com/WeAreHausTech/haus-tech-vendure-plugins/commit/c952c7b)) - **product-import-export-plugin:** improve variant enabled handling ([a3a6af3](https://github.com/WeAreHausTech/haus-tech-vendure-plugins/commit/a3a6af3)) - **product-import-export-plugin:** improve option group handling and validate custom fields ([a95db85](https://github.com/WeAreHausTech/haus-tech-vendure-plugins/commit/a95db85)) - **product-import-export-plugin:** handle undefined prices in product variants ([#49](https://github.com/WeAreHausTech/haus-tech-vendure-plugins/pull/49)) - Refactor facetValues and options mapping for consistency in extended fast importer ([3514892](https://github.com/WeAreHausTech/haus-tech-vendure-plugins/commit/3514892)) - Improve asset and product importer logic for better channel handling and data consistency ([bc9416e](https://github.com/WeAreHausTech/haus-tech-vendure-plugins/commit/bc9416e)) - Assign assets to current channel on import ([#41](https://github.com/WeAreHausTech/haus-tech-vendure-plugins/pull/41)) ## 3.0.23-0 ### 🚀 Features - **product-import-export-plugin:** add restoreSoftDeleted option for product import ([0458a2a](https://github.com/WeAreHausTech/haus-tech-vendure-plugins/commit/0458a2a)) - **product-importer:** enhance product variant handling ([4af2198](https://github.com/WeAreHausTech/haus-tech-vendure-plugins/commit/4af2198)) - **product-import-export-plugin:** enhance product import service with event bus integration and collection filtering ([#48](https://github.com/WeAreHausTech/haus-tech-vendure-plugins/pull/48)) - **product-import-export-plugin:** implement removal of option groups from product ([39f34ec](https://github.com/WeAreHausTech/haus-tech-vendure-plugins/commit/39f34ec)) - Enhance asset importer with URL and local file stream handling ([2b5ae3d](https://github.com/WeAreHausTech/haus-tech-vendure-plugins/commit/2b5ae3d)) ### 🩹 Fixes - **product-import-export-plugin:** improve import parser handling ([c952c7b](https://github.com/WeAreHausTech/haus-tech-vendure-plugins/commit/c952c7b)) - **product-import-export-plugin:** improve variant enabled handling ([a3a6af3](https://github.com/WeAreHausTech/haus-tech-vendure-plugins/commit/a3a6af3)) - **product-import-export-plugin:** improve option group handling and validate custom fields ([a95db85](https://github.com/WeAreHausTech/haus-tech-vendure-plugins/commit/a95db85)) - **product-import-export-plugin:** handle undefined prices in product variants ([#49](https://github.com/WeAreHausTech/haus-tech-vendure-plugins/pull/49)) - Refactor facetValues and options mapping for consistency in extended fast importer ([3514892](https://github.com/WeAreHausTech/haus-tech-vendure-plugins/commit/3514892)) - Improve asset and product importer logic for better channel handling and data consistency ([bc9416e](https://github.com/WeAreHausTech/haus-tech-vendure-plugins/commit/bc9416e)) - Assign assets to current channel on import ([#41](https://github.com/WeAreHausTech/haus-tech-vendure-plugins/pull/41)) ## 3.0.22 ### 🩹 Fixes - **product-import-export-plugin:** improve import parser handling ([c952c7b](https://github.com/WeAreHausTech/haus-vendure-plugins-public/commit/c952c7b)) ## 3.0.21 ### 🚀 Features - **product-importer:** enhance product variant handling ([4af2198](https://github.com/WeAreHausTech/haus-vendure-plugins-public/commit/4af2198)) - **product-import-export-plugin:** enhance product import service with event bus integration and collection filtering ([#48](https://github.com/WeAreHausTech/haus-vendure-plugins-public/pull/48)) - **product-import-export-plugin:** implement removal of option groups from product ([39f34ec](https://github.com/WeAreHausTech/haus-vendure-plugins-public/commit/39f34ec)) - Enhance asset importer with URL and local file stream handling ([2b5ae3d](https://github.com/WeAreHausTech/haus-vendure-plugins-public/commit/2b5ae3d)) ### 🩹 Fixes - **product-import-export-plugin:** improve variant enabled handling ([a3a6af3](https://github.com/WeAreHausTech/haus-vendure-plugins-public/commit/a3a6af3)) - **product-import-export-plugin:** improve option group handling and validate custom fields ([a95db85](https://github.com/WeAreHausTech/haus-vendure-plugins-public/commit/a95db85)) - **product-import-export-plugin:** handle undefined prices in product variants ([#49](https://github.com/WeAreHausTech/haus-vendure-plugins-public/pull/49)) - Refactor facetValues and options mapping for consistency in extended fast importer ([3514892](https://github.com/WeAreHausTech/haus-vendure-plugins-public/commit/3514892)) - Improve asset and product importer logic for better channel handling and data consistency ([bc9416e](https://github.com/WeAreHausTech/haus-vendure-plugins-public/commit/bc9416e)) - Assign assets to current channel on import ([#41](https://github.com/WeAreHausTech/haus-vendure-plugins-public/pull/41)) 8e:T576f,# @uplab/vendure-plugin-turbosms Send transactional SMS from Vendure through [TurboSMS](https://turbosms.ua/), the Ukrainian bulk-SMS provider. The plugin adds no GraphQL API extensions, no entities and no admin UI. It exports one injectable service, `TurboSmsService`, with `send()`, `sendBulk()` and `getBalance()`. It is deliberately message-agnostic: it sends the text you hand it. Composing that text — templates, translations, which language a given customer reads — stays in your application, which knows its own copy. What the plugin does own is everything specific to sending SMS through this provider: the wire format, phone number formatting, segment accounting, per-recipient outcomes, and the account balance. No runtime dependencies: the client is built on the global `fetch`. Compatible with **Vendure ^3.7.0**. ## Install ```bash npm install @uplab/vendure-plugin-turbosms # or pnpm add @uplab/vendure-plugin-turbosms ``` `@vendure/core` and `@nestjs/common` are peer dependencies — the plugin uses the copies already in your project. ## Usage ```ts import { VendureConfig } from '@vendure/core'; import { TurboSmsPlugin } from '@uplab/vendure-plugin-turbosms'; export const config: VendureConfig = { // ... plugins: [ TurboSmsPlugin.init({ apiKey: process.env.TURBOSMS_API_KEY!, sender: 'MyShop', dryRun: process.env.NODE_ENV !== 'production', }), ], }; ``` Then inject the service anywhere in your own plugin: ```ts import { Injectable } from '@nestjs/common'; import { Logger } from '@vendure/core'; import { TurboSmsError, TurboSmsService } from '@uplab/vendure-plugin-turbosms'; @Injectable() export class MyAuthService { constructor(private turboSms: TurboSmsService) {} async sendLoginCode(phone: string, code: string): Promise { const text = `Your MyShop login code – ${code}`; try { await this.turboSms.send(phone, text); return true; } catch (e) { if (e instanceof TurboSmsError) { // Log it and fall back to another channel rather than failing the request. Logger.error(e.message, 'MyAuthService'); return false; } throw e; } } } ``` Remember to add `TurboSmsPlugin` to your own plugin's `imports` if you inject its service, since Vendure plugins are Nest modules. ## Options `TurboSmsPlugin.init(options)`: | Option | Type | Default | Description | | ----------------- | ------------------------------------------------------------------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------- | | `apiKey` | `string` | _required_ | The TurboSMS API key (the bearer token from your TurboSMS account). | | `sender` | `string` | _required_ | The registered alphanumeric sender name ("alpha name"). Overridable per call. | | `dryRun` | `boolean` | `false` | When `true`, nothing is sent: the message is written to the Vendure log instead. | | `apiUrl` | `string` | `'https://api.turbosms.ua/'` | Base URL of the TurboSMS REST API. Point it at a mock server in tests. | | `timeout` | `number` | `10000` | How long a request may take before it is aborted, in milliseconds. | | `lowBalanceAlert` | `{ threshold?, schedule?, onLowBalance?, minIntervalBetweenAlerts?, onCheckFailed? }` | — | Low-balance alerting: a callback, a scheduled check, or both. See **Watching the balance**. | ## Sending ```ts // One recipient. const result = await turboSms.send('380501234567', 'Your code is 1234'); // The same text to many recipients, in a single request. await turboSms.sendBulk(['380501234567', '380671234567'], 'We are closed on Monday'); // A different registered alpha name for this message only. await turboSms.send('380501234567', 'Your code is 1234', { sender: 'MyOtherShop' }); ``` Both return a `TurboSmsSendResult`: ```ts { dryRun: boolean; // true when the message was only logged recipients: string[]; // after normalization text: string; sender: string; accepted: string[]; // numbers TurboSMS took for delivery refused: TurboSmsRefusedRecipient[]; // { phone, responseCode, responseStatus } response?: TurboSmsSendMessageResponse; // the raw API response; absent in dry-run mode } ``` **A request can be accepted as a whole while an individual number is refused**, which is easy to miss when reading only the top-level response code. That is why the result splits recipients up front: ```ts const { refused } = await turboSms.sendBulk(phones, text); if (refused.length) { Logger.warn(`Not delivered: ${refused.map((r) => `${r.phone} (${r.responseStatus})`).join(', ')}`); } ``` There is no message template or localization layer: the plugin sends the text you hand it. See **Localizing messages** for how to keep that copy in your application. ## Phone numbers TurboSMS wants digits only, no leading `+` — `380501234567`. Storefronts collect whatever the customer typed, so every recipient is stripped down before it is sent: 1. Everything that is not a digit is dropped, `+` and separators included. 2. A leading `00` — the international access code, the written form of `+` — is dropped. ```ts await turboSms.send('+38 (050) 123-45-67', text); // → 380501234567 await turboSms.send('00380501234567', text); // → 380501234567 ``` Both steps only remove notation. **The plugin never adds a country code**, because which country a national number like `0501234567` belongs to is not something it can know — that is a fact about your customers. Such a number goes out as stored and TurboSMS refuses it, which shows up in `refused` rather than being silently guessed at. The same stripping is exported as `normalizePhoneNumber`, so an application that needs to reason about a number before sending — picking a language from the country code, say — can apply it rather than re-deriving it: ```ts import { normalizePhoneNumber } from '@uplab/vendure-plugin-turbosms'; const digits = normalizePhoneNumber(phoneNumber); // '+38 (050) …' → '380501234567' const lang = digits.startsWith('380') ? 'uk' : sessionLanguage; ``` So store phone numbers in international form. If you have national ones, expand them where the country is known: ```ts const international = normalizePhoneNumber(phone).replace(/^0/, '380'); await turboSms.send(international, text); ``` The stripping does not validate: a string that is not a phone number goes out as whatever digits it contained, and TurboSMS refuses it per recipient. ## Message length and cost TurboSMS bills per segment, and a segment is much smaller in Cyrillic than the familiar 160 characters: **one** non-Latin character re-encodes the whole message to UCS-2, where a segment holds **70** characters instead of 160. A 75-character Ukrainian message therefore costs two segments, and a message that mixes in a single `і` costs the same as one written entirely in Ukrainian. Worth knowing when writing campaign copy, or when showing an author how much room is left. The plugin does not count segments for you — that is the GSM 03.38 standard rather than anything specific to TurboSMS, and it is a solved problem: use a dedicated package such as [`split-sms`](https://www.npmjs.com/package/split-sms) or [`sms-segments-calculator`](https://www.npmjs.com/package/sms-segments-calculator) if you need the exact count. ## Localizing messages The plugin ships no templates on purpose: a published package cannot know your copy, and Vendure's `I18nService` translates GraphQL error results for API responses, so it is not available on the background paths that send SMS. Keep the strings in your application: ```ts import { LanguageCode } from '@vendure/core'; const templates: Partial string }>> = { [LanguageCode.en]: { otpCode: (code) => `Your MyShop login code – ${code}` }, [LanguageCode.uk]: { otpCode: (code) => `Ваш код входу MyShop – ${code}` }, }; /** Falls back through the shop's default language to English. */ function template(languageCode: LanguageCode) { return templates[languageCode] ?? templates[defaultLanguageCode] ?? templates[LanguageCode.en]!; } const text = template(ctx.languageCode).otpCode(code); await turboSms.send(phone, text); ``` If the recipient's number is a better signal of what they read than the storefront locale, branch on it yourself — `recipient.startsWith('380') ? LanguageCode.uk : ctx.languageCode`. That is a decision about your customers, not about TurboSMS, so it stays on your side. ## Events The plugin publishes on Vendure's event bus, so metering and audit logging do not have to wrap every call site: | Event | When | | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `TurboSmsSentEvent` | A send request was accepted. Carries the full result, `dryRun` sends too. | | `TurboSmsFailedEvent` | A send request failed as a whole, published just before the error is thrown. | | `TurboSmsLowBalanceEvent` | The **scheduled** check found the balance below the threshold. Not published for a refused send, and gated by `minIntervalBetweenAlerts` like the callback. | ```ts eventBus.ofType(TurboSmsSentEvent).subscribe(({ result }) => { metrics.increment('sms.sent', result.accepted.length); metrics.increment('sms.refused', result.refused.length); }); ``` ## Watching the balance Running out of credit stops SMS silently from the application's point of view: the API simply starts refusing sends. There are two triggers, and both call the same `onLowBalance` callback, so you wire up notification once. | Trigger | When it fires | Needs | | ------------------- | --------------------------------------------------------- | ------------------------- | | **Refused send** | TurboSMS rejects a send for insufficient funds (code 103) | nothing | | **Scheduled check** | The polled balance is below `threshold` | `threshold` + a scheduler | The refused send is exact and immediate, costs no extra API call and works without a scheduler — but by then messages are already failing. The scheduled check is what warns you _before_ that happens. Configure both in production. A third thing can happen: the scheduled check fails and the balance is simply unknown. That is `onCheckFailed` — see **When the check itself fails**. ### The callback ```ts TurboSmsPlugin.init({ apiKey: process.env.TURBOSMS_API_KEY!, sender: 'MyShop', lowBalanceAlert: { onLowBalance: ({ message }) => notifySlack(message), }, }); ``` `message` is the same line the plugin logs, so the simple case needs no unpacking. Add a `threshold` to also poll the balance ahead of time: ```ts lowBalanceAlert: { threshold: 100, // UAH; checked daily at 09:00 onLowBalance: ({ message }) => notifySlack(message), }, ``` ### Reaching your own services The callback is handed Vendure's `Injector`, so it can use anything in the application without you building a plugin to hold a subscription: ```ts lowBalanceAlert: { threshold: 100, onLowBalance: async (context) => { const notifier = context.injector.get(MyNotifierService); switch (context.reason) { case 'scheduledCheck': // `balance` and `threshold` are numbers here. return notifier.warn(`TurboSMS balance is down to ${context.balance} UAH`); case 'sendRejected': // `error` carries the recipients and the response code. return notifier.page(`TurboSMS is out of credit: ${context.error.responseStatus}`); } }, }, ``` Rules worth knowing: - **Errors are caught and logged.** A failing callback never breaks a send or fails a scheduled run. - **It is awaited**, so keep it quick — a slow callback delays the send's rejection and counts against the scheduled task's timeout. That is `DefaultSchedulerPlugin`'s `defaultTimeout` (60 s unless you changed it), except when one request (`timeout`) plus 20 s of headroom would not fit in it — then the task sets that budget itself. Queue anything slow. That comparison needs a number. A `defaultTimeout` written as a duration string (`'30s'`) is only readable by the scheduler's own parser, so the task leaves it alone and logs a warning. Express it in milliseconds if you want the check made — especially if it is short, since the balance check would otherwise be cut off mid-request on every run. - **It can fire once per refused send**, so a burst of failures means a burst of calls. Debounce before paging anyone. - In a cluster the refused-send trigger fires on whichever instance sent the SMS, while the scheduled check runs once. - **Dry-run fires neither trigger** — nothing reaches the API and the scheduled task skips itself — so a local test of `onLowBalance` will look like nothing happened. ### How often it repeats While the balance stays low, every scheduled run alerts. That is the right default for a single alert channel that collapses duplicates, and the wrong one for a chat room. Set `minIntervalBetweenAlerts` to quieten it: ```ts lowBalanceAlert: { threshold: 100, schedule: '0 * * * *', // check hourly minIntervalBetweenAlerts: 24 * 60 * 60 * 1000, // but alert at most daily onLowBalance: ({ message }) => notifySlack(message), }, ``` **A recovery re-arms the alert immediately.** Topped up at noon and drained again by evening, and you are told — a plain "once per day" timer would swallow that, and only the check itself can tell the difference, because your callback never sees the healthy runs. **The interval starts once the alert has gone out.** A callback that throws is logged and retried on the next scheduled run, not silenced until the interval is up. State lives in Vendure's `CacheService`, so it is as durable as your cache strategy: Redis or DB survives restarts and is shared between instances, the default in-memory strategy is per process — it resets on restart, and in a cluster each instance keeps its own, so use a shared strategy there. Cache failures fail open — a duplicate alert beats a silently dropped one. Changing `threshold` re-arms too, since it is part of the key. `0` (or a negative value) means no interval, the same as leaving it out. The interval gates the scheduled check only, `TurboSmsLowBalanceEvent` included. A refused send always calls `onLowBalance`: its rate is bounded by your own send volume, and each one is a customer message that actually failed. ### When the check itself fails TurboSMS being unreachable is not a low balance — it means you no longer know what the balance is. The task rethrows, so the run is recorded as failed, but nothing is pushed anywhere unless you ask for it: ```ts lowBalanceAlert: { threshold: 100, onLowBalance: ({ message }) => notifySlack(message), onCheckFailed: ({ message }) => notifySlack(message), // "balance monitoring is blind" }, ``` `onCheckFailed` fires for a `TurboSmsError` — a refusal, or a transport failure, which includes a 2xx body with no balance in it. Anything else is a bug rather than an outage and is rethrown untouched. It shares `minIntervalBetweenAlerts` under its own key, and re-arms as soon as a check succeeds. Without it, a multi-day outage shows up only as failed runs in the scheduled-tasks screen — which is exactly where nobody is looking while SMS still appears to work. ### Choosing when to check `schedule` takes a cron expression or a `cron-time-generator` callback, and is only used when a `threshold` is set: ```ts lowBalanceAlert: { threshold: 100, schedule: '0 * * * *' }; // hourly lowBalanceAlert: { threshold: 100, schedule: '0 9,18 * * 1-5' }; // 09:00 and 18:00 on weekdays lowBalanceAlert: { threshold: 100, schedule: (cronTime) => cronTime.every(6).hours() }; ``` The scheduled check needs a scheduler plugin (such as Vendure's `DefaultSchedulerPlugin`) configured, since that is what runs scheduled tasks. ### Opting out Omit `lowBalanceAlert` and nothing happens: no task is registered, no callback runs, nothing extra is logged. There is deliberately no `enabled` flag — Vendure's own task config has none either, and one more boolean would just be a second way to express "leave it out". To pause only the scheduled check at runtime without redeploying, disable it like any other Vendure task — in the admin UI's scheduled-tasks screen, or on the Admin API: ```graphql mutation { updateScheduledTask(input: { id: "turbosms-low-balance", enabled: false }) { id enabled } } ``` That does not affect the refused-send trigger, which is not a scheduled task. ### The event-bus escape hatch If you already have event subscribers, the scheduled check also publishes `TurboSmsLowBalanceEvent`. A refused send publishes **no** low-balance event — there is no balance figure to report — but it does publish `TurboSmsFailedEvent`, so the same case is one predicate away: ```ts eventBus.ofType(TurboSmsFailedEvent).subscribe(({ error }) => { if (error instanceof TurboSmsRejectedError && error.responseCode === INSUFFICIENT_FUNDS_RESPONSE_CODE) { // Out of credit. } }); ``` `getBalance()` is there for a one-off check. It is a live call even in dry-run mode, where the configured API key is usually a placeholder — guard it with `isDryRun`. ## GraphQL surface None. The plugin contributes no schema extensions, resolvers, entities, permissions or custom fields — it is a service-only plugin. ## Error handling Everything the plugin throws extends `TurboSmsError`, so one `catch` covers falling back to another channel. Both kinds carry the `endpoint` that failed. | Error | When | Extra fields | | ------------------------ | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | | `TurboSmsRejectedError` | TurboSMS answered, and the answer was a refusal — unknown alpha name, empty balance, … | `responseCode`, `responseStatus`, `responseResult`, `recipientCodes`, `recipients`, `text` | | `TurboSmsTransportError` | The request never produced a usable answer: network failure, timeout, non-2xx, non-JSON body | `status` (when there was an HTTP response), `cause` | Response codes `0`, `1` and `800`–`803` are treated as accepted; everything else raises a `TurboSmsRejectedError`. Code `103` (`NOT_ENOUGH_MONEY`) means the account is out of credit. It is exported as `INSUFFICIENT_FUNDS_RESPONSE_CODE`, and it is what triggers `lowBalanceAlert.onLowBalance` with `reason: 'sendRejected'` — see **Watching the balance**. ### Per-recipient codes A refusal also carries a row per recipient. `recipientCodes` reads their codes in order, and is empty when the rejection was request-level rather than per-number. It is a getter over `responseResult`, so it is not in `JSON.stringify(error)` or `{ ...error }` — the rows are: ```ts import { RECIPIENT_COUNTRY_NOT_ALLOWED_CODE, RECIPIENT_INSUFFICIENT_FUNDS_CODE, TurboSmsRejectedError, } from '@uplab/vendure-plugin-turbosms'; catch (e) { if (e instanceof TurboSmsRejectedError) { const codes = e.recipientCodes; // Routine: SMS is not enabled for that country, fall back to another channel. if (codes.every((c) => c === RECIPIENT_COUNTRY_NOT_ALLOWED_CODE)) return callInstead(); // Never routine: the account is empty and no recipient will go through. if (codes.includes(RECIPIENT_INSUFFICIENT_FUNDS_CODE)) return alertOps(); } } ``` A `TurboSmsTransportError` means the outcome is **unknown** — the message may or may not have gone out, so an automatic retry can deliver it twice. The message body is never put into an error's `message`, so codes do not leak into logs through a stack trace. It is available on `TurboSmsRejectedError.text` if you need it. `text` is an own enumerable property, though, so **serializing the whole error puts the body back in** — `JSON.stringify(error)` in an alert or a log line will carry whatever the message said, one-time codes included. Pick the fields you want, or redact `text`. ## Dry-run mode With `dryRun: true`, nothing touches the network: the recipients and the message body are written to the Vendure log under the `TurboSmsPlugin` context, and the call resolves with `dryRun: true`. `TurboSmsService.isDryRun` exposes the flag, so monitoring code can skip balance checks when there is no real account behind the plugin. Because the body is logged verbatim, anything sensitive in it — a one-time code, an order total — ends up in your logs. Dry run is a development mode; do not enable it in production. ## Changelog See [CHANGELOG.md](./CHANGELOG.md). ## License MIT © Uplab 8f:Tf5d,# @uplab/vendure-plugin-turbosms ## 0.2.0 ### Minor Changes - [#16](https://github.com/Uplab/uplab-vendure-plugins/pull/16) [`136d49e`](https://github.com/Uplab/uplab-vendure-plugins/commit/136d49eb49dd48e7654eec1485634157ea2ece91) Thanks [@brmk](https://github.com/brmk)! - Export the protocol knowledge consumers were re-deriving, and make the scheduled balance check survive contact with a real ops channel. New exports: - `normalizePhoneNumber` — the same stripping the plugin applies to every recipient. An application that reasons about a number before sending (picking a language from the country code, say) no longer has to reimplement it. - `RECIPIENT_COUNTRY_NOT_ALLOWED_CODE` (406) and `RECIPIENT_INSUFFICIENT_FUNDS_CODE` (203) — the per-recipient codes a caller has to classify. Distinct from the request-level `INSUFFICIENT_FUNDS_RESPONSE_CODE` (103), which is a different row of the response. - `TurboSmsRejectedError.recipientCodes` — the codes in order, empty for a request-level rejection. New `lowBalanceAlert` options: - `minIntervalBetweenAlerts` — stay quiet after alerting, but re-arm as soon as the balance recovers, so a top-up followed by another drop is still reported. The interval only starts once the alert went out, so a callback that throws is retried next run. Backed by Vendure's `CacheService` and failing open. Omitted (or `0`), the behaviour is unchanged: an alert on every scheduled run while the balance is low. - `onCheckFailed` — called when a scheduled check cannot read the balance at all. The task still rethrows, so the failed run is recorded either way; the callback is what turns "we no longer know the balance" into something that reaches a person. The scheduled task also sets its own timeout when the configured request timeout plus 20 s of callback headroom would not fit in `DefaultSchedulerPlugin`'s `defaultTimeout`, so a slow API response is not reported as a task failure. When it fits, the scheduler's setting is left as it was — as it is for a `defaultTimeout` given as a duration string, which only the scheduler's own parser can read, with a warning so a short one is not left unnoticed. `TurboSmsService.getBalance()` now throws a `TurboSmsTransportError` for a 2xx body without a balance in it, instead of a bare `TypeError`, so the scheduled check reports it as an outage. ## 0.1.0 ### Minor Changes - [`dd0f7b1`](https://github.com/Uplab/uplab-vendure-plugins/commit/dd0f7b18e43644d8f36aaad92fc57b09bfe9a63e) Thanks [@brmk](https://github.com/brmk)! - Initial release: send transactional SMS through TurboSMS. - `TurboSmsPlugin.init({ apiKey, sender, dryRun?, apiUrl?, timeout?, lowBalanceAlert? })` - Exports `TurboSmsService` — `send()`, `sendBulk()` and `getBalance()`, plus an `isDryRun` flag - Recipients are stripped to the digits TurboSMS expects (separators, `+`, a leading `00`); no country code is ever added - Send results split recipients into `accepted` and `refused`, so a number refused inside an accepted request is not missed - `lowBalanceAlert` warns before the account runs dry: an `onLowBalance` callback fires the moment TurboSMS refuses a send for insufficient funds, and — when a `threshold` is set — from a scheduled balance check as well - Publishes `TurboSmsSentEvent` / `TurboSmsFailedEvent`, and `TurboSmsLowBalanceEvent` from the scheduled balance check - Exports `INSUFFICIENT_FUNDS_RESPONSE_CODE`, so a `TurboSmsFailedEvent` subscriber can recognise a refusal for insufficient funds without a magic number - Failures are `TurboSmsError`: `TurboSmsRejectedError` when TurboSMS refuses a request (carrying the per-recipient codes), `TurboSmsTransportError` when it fails or times out - `dryRun` mode logs the message instead of calling the API - No runtime dependencies — the client is built on the global `fetch` 90:T1bba,# Vendure Klaviyo Plugin An extensible plugin for sending placed orders to the Klaviyo marketing platform. ## Getting started The default setup will only send placed orders to Klaviyo 1. Log in to your Klaviyo account and get your API key 2. Add the following config to your `vendure-config.ts`: ```ts import { KlaviyoPlugin } from '@pinelab/vendure-plugin-klaviyo'; plugins: [ KlaviyoPlugin.init({ apiKey: 'some_private_api_key', }), ]; ``` All placed orders will now be synced. ## Custom event handlers If you want to send more events to Klaviyo, you can implement your own handlers. For example, syncing account verification events to Klaviyo, so that you can send out welcome e-mails: 1. Create a custom handler `klaviyo-account-verified-handler.ts` ```ts import { AccountVerifiedEvent } from '@vendure/core'; import { KlaviyoEventHandler, KlaviyoGenericEvent, } from '@pinelab/vendure-plugin-klaviyo'; /** * Event handler to send Vendure's AccountVerifiedEvent to Klaviyo */ export const accountVerifiedHandler: KlaviyoEventHandler = { vendureEvent: AccountVerifiedEvent, mapToKlaviyoEvent: async (event, injector) => { const { customer } = event; return { // Unique ID per event to make the event idempotent uniqueId: `account-verified-${customer.id}-${Date.now()}`, eventName: 'Account Verified', profile: { emailAddress: customer.emailAddress, externalId: customer.id.toString(), firstName: customer.firstName, lastName: customer.lastName, }, eventProperties: { myCustomProperty: 'my custom value', }, }; }, }; ``` 2. Register the handler in the plugin in your `vendure-config.ts` ```ts import { defaultOrderPlacedEventHandler, KlaviyoPlugin, } from '@pinelab/vendure-plugin-klaviyo'; import { accountVerifiedHandler } from './klaviyo-account-verified-handler.ts'; plugins: [ KlaviyoPlugin.init({ apiKey: 'some_private_api_key', eventHandlers: [defaultOrderPlacedEventHandler, accountVerifiedHandler], }), ]; ``` ## Custom data in Klaviyo's default Order Placed event If you'd like to send custom data in the Klaviyo native Order Placed event, you can also create a custom handler, but make sure to return a `KlaviyoOrderPlacedEvent` instead of a `KlaviyoGenericEvent`. The plugin will recognize your return type and handle it as an Order Placed event. Don't forget to exclude the default order placed handler if you do! ```ts KlaviyoPlugin.init({ apiKey: 'some_private_api_key', // No defaultOrderPlacedHandler here! eventHandlers: [customOrderPlacedHandler], }), ``` ## Abandoned cart emails This plugin includes a mutation `klaviyoCheckoutStarted`, which can be called from your storefront. When called, and an active order is present, it sends a custom event `Checkout Started` to Klaviyo, including basic order and profile data. This event can be used to set up abandoned cart email flows in Klaviyo. ## Refund and Cancellation Events This plugin includes a mutation `klaviyoRefundCreated`, which sends events to Klaviyo whenever a refund is created for an order. To enable the refund event, add the refund handler to the plugin config: ```ts import { KlaviyoPlugin, createRefundHandler, } from '@pinelab/vendure-plugin-klaviyo'; plugins: [ KlaviyoPlugin.init({ apiKey: 'some_private_api_key', eventHandlers: [ createRefundHandler({ getPaymentMethodName: (payment) => { // This sample gets the payment method (like 'iDeal') when a the settled payment was a Mollie payment return payment?.metadata.method; }, }), ], }), ]; ``` ## Newsletter signup The following mutation allows a customer to sign up to a Klaviyo Audience list via the API: ```graphql mutation { subscribeToKlaviyoList( emailAddress: "testing@pinelab.studio" listId: "WpeFJd" ) } ``` This mutation requires an active session, which means a customer should have interacted with the Vendure API already. This can be done for example by fetching an active order. This is to prevent unwanted bot sign ups. The customer will also receive a double opt-in email, asking them to confirm signing up for marketing emails. ## Product Feed You can use this plugin to get the JSON product feed for Klaviyo. This can be used to sync your products to Klaviyo. To enable it, you need to configure the feed settings of the plugin: ```ts import { KlaviyoPlugin } from '@pinelab/vendure-plugin-klaviyo'; plugins: [ KlaviyoPlugin.init({ apiKey: 'some_private_api_key', feed: { // The feed is secured by a password, to prevent abuse, but still able to use it via the shop API in your storefront build. password: 'some_password', enhanceProductFeedItemFn: (ctx, variant, feedItem) => { const asset = variant.product.featuredAsset ?? variant.featuredAsset; return { ...feedItem, image_link: `https://my-storefront.io/assets/${asset?.preview}`, link: `https://my-storefront.io/product/${variant.product.slug}`, // You can add any custom fields you want to the feed item, like so: myCustomField: variant.customFields.myCustomField, // or override any of the default fields, like so: name: variant.product.name + ' - Buy Now!', }; }, }, }), ]; ``` After that, you can call the feed via the shop API, which will return a JSON object. You could stringify that, and use it to save it to a static file. For example `klaviyo_feed.json`, and use the path to that file to have Klaviyo fetch your products. ```graphql query { klaviyoProductFeed(password: "some_password") } ``` Without the `feed.password` set, feed generation is disabled. ## Back In Stock notifications Allow customers to subscribe to back in stock notifications for a given product. Requires an active session, and requires the Klaviyo feed to be connected in your account. ```graphql mutation { subscribeToKlaviyoBackInStock( emailAddress: "testing@pinelab.studio" # This is the catalog item ID, which is the variant ID if you use the generated feed above. catalogItemId: "1" ) } ``` ## Failed to send event to Klaviyo If for some reason an event fails to be sent to Klaviyo, an `FailedToSendToKlaviyoEvent`event is emitted. You can listen to this event to monitor failed events and take action. Example: ```ts import { FailedToSendToKlaviyoEvent } from '@pinelab/vendure-plugin-klaviyo'; this.eventBus.ofType(FailedToSendToKlaviyoEvent).subscribe((event) => { console.log('Failed to send event to Klaviyo:', event.data.eventName); console.log('For profile:', event.data.profile.emailAddress); console.log('Because of reason:', (event.error as Error)?.message); // Maybe send some alerts to your monitoring system }); ``` 91:T869,# 1.13.0 (2026-08-05) - Upgraded to Vendure 3.6.3 # 1.12.0 (2026-02-05) - Upgraded to Vendure 3.5.3 # 1.11.0 (2026-01-27) - Set `customProperties.language` for Klaviyo profiles based on the request context language code from Vendure # 1.10.0 (2026-01-21) - Emitting `FailedToSendToKlaviyoEvent` event when a Klaviyo event fails to be sent # 1.9.3 (2025-11-13) - Documentation update # 1.9.2 (2025-11-06) - Updated official documentation URL # 1.9.1 (2025-06-27) - Don't throw error for products without a price when generating the product feed - Filter out disabled variants from the product feed # 1.9.0 (2025-06-27) - Added query for retrieving the Klaviyo JSON product feed. - Added mutation for subscribing to back in stock notifications for a given product. - Upgrade to Klaviyo Client from 10.1.0 to 18.0.0 # 1.8.0 (2025-06-04) - Upgrade to Vendure to 3.3.2 # 1.7.0 (2025-05-28) - Added `RefundEventHandler` to send events to Klaviyo when a refund is created. # 1.6.2 (2025-05-22) - Fetch order with relations instead of hydrating in CheckoutStartedEvent, to prevent order object modification # 1.6.1 (2025-02-19) - Fetch order with relations instead of hydrating, to prevent `Maximum call stack exceeded` (https://github.com/vendure-ecommerce/vendure/issues/3355) # 1.6.0 (2025-01-14) - Added mutation to sign up to Klaviyo Audience list # 1.5.0 (2024-12-19) - Update Vendure to 3.1.1 # 1.4.0 (2024-12-13) - Include `klaviyoCheckoutStarted` mutation to be able to use abandoned cart email flows # 1.3.1 (2024-12-13) - Don't log push jobs and log errors for channels without api keys # 1.3.0 (2024-12-12) - Allow setting an apiKey per channel # 1.2.1 (2024-12-04) - Add support for DiscountCode on Placed Order event # 1.2.0 (2024-08-14) - Allow setting multiple Klaviyo handlers for Vendure's OrderPlacedEvent - Allow order items to be excluded from 'Ordered Product' events # 1.1.1 (2024-08-04) - Update compatibility range (#480) # 1.1.0 (2024-06-21) - Updated Vendure to 2.2.6 # 1.0.1 (2024-06-19) - Added extra tests for 'Ordered Product' events # 1.0.0 (2024-06-18) - Initial setup of the plugin 92:T10a3,# Google Cloud Tasks Vendure plugin Plugin for using Vendure worker with Google Cloud Tasks. This plugin will show ending, successful and failed jobs in the admin UI under `sytem/jobs`, but not running jobs. Only jobs of the past 7 days are kept in the DB. ## Getting started ## Plugin setup 2. Remove `DefaultJobQueuePlugin` from your vendure-config. Add this plugin to your `vendure-config.ts`: ```ts import { CloudTasksPlugin } from '@pinelab/vendure-plugin-google-cloud-tasks'; plugins: [ CloudTasksPlugin.init({ // Must reachable by Google Cloud Task. Messages are pushed to this endpoint taskHandlerHost: 'https://your-public-host/', projectId: 'your-google-project-id', // Region where the taskqueue should be created location: 'europe-west1', // Used to prevent unauithorized requests to your public endpoint authSecret: 'some-secret-to-authenticate-incoming-messages', /** * Used to distinguish taskQueues within the same * Google Project (if you have OTAP environments in the same project for example) * This suffix will be appended to the queue name: "send-email-plugin-test" */ queueSuffix: 'plugin-test', // Default amount of retries when no job.retries is given defaultJobRetries: 15, // The amount of retries when a job fails to be pushed to the queue createTaskRetries: 3, // Default amount of days to keep jobs in the database. clearStaleJobsAfterDays: 7, }), ]; ``` 2. Run a database migration to add the `JobRecordBuffer` table. 3. Start the Vendure server, log in to the admin dashboard and trigger a reindex job via `Products > (cog icon) > reindex` to test the Cloud Tasks Plugin. This plugin installs the `SQLJobBufferStrategy` from Vendure's default JobQueue plugin, to buffer jobs in the database. This is because most projects that are using Google Cloud Tasks will also have multiple instances of the Vendure server. # Clear jobs You can call the endpoint `/cloud-tasks/clear-jobs/X` with the secret as Auth header to clear jobs older than X days. For example: ```shell curl -H "Authorization: Bearer some-secret-to-authenticate-cloud-tasks" "http://localhost:3050/cloud-tasks/clear-jobs/1" ``` Will clear all jobs older than 1 day. # FAQ ## DEADLINE_EXCEEDED errors when pushing tasks to queue When pushing multiple tasks concurrently to a queue in serverless environments, you might see `DEADLINE_EXCEEDED` errors. If that happens, you can instantiate the plugin with `fallback: true` to make the Google Cloud Tasks client fallback to HTTP instead of GRPC. For more details see https://github.com/googleapis/nodejs-tasks/issues/397#issuecomment-618580649 ```ts CloudTasksPlugin.init({ ... clientOptions: { fallback: true } }); ``` ## Request entity too large This means the Job data is larger than NestJS's configured request limit. You can set a large limit in your `vendure-config.ts`: ```ts import { VendureConfig } from '@vendure/core'; import { json } from 'body-parser'; export const config: VendureConfig = { // ... apiOptions: { middleware: [ { handler: json({ limit: '10mb' }), route: '*', beforeListen: true, }, ], }, }; ``` We don't include this in the plugin, because it affects the entire NestJS instance ## `ER_OUT_OF_SORTMEMORY: Out of sort memory, consider increasing server sort buffer size` on MySQL If you get this error, you should create an index on the `createdAt` column of the job table: ```sql CREATE INDEX idx_job_created_at ON job_record (createdAt); ``` The error is caused by the fact that the `job_record.data` column is a `json` column and can contain a lot of data. More information can be found here: https://stackoverflow.com/questions/29575835/error-1038-out-of-sort-memory-consider-increasing-sort-buffer-size 93:T8f4,# 2.2.0 (2026-08-05) - Upgraded to Vendure 3.6.3 # 2.1.0 (2026-02-05) - Upgraded to Vendure 3.5.3 # 2.0.3 (2025-11-13) - Documentation update # 2.0.2 (2025-11-06) - Updated official documentation URL # 2.0.1 (2025-08-14) - IMPORTANT: Better truncate of job.data, and retry saving without data if it fails. V2.0.0 crashes the Vendure server when job.data is too large. # 2.0.0 (2025-08-11) - BREAKING: Included `SQLJobBufferStrategy`, to buffer jobs in DB instead of in memory, to support multiple instances. A database migration is required. - Added documentation to fix `ER_OUT_OF_SORTMEMORY: Out of sort memory, consider increasing server sort buffer size` on MySQL - Constrain data size to 64kb to prevent `ER_DATA_TOO_LONG` errors on MySQL - Allow configuring deletion of jobs older than X days - Save original queue names in database. Only use suffix for creating queues in Google Cloud. This fixes admin UI job filtering # 1.9.1 (2025-06-24) - Add stack trace to error message when job fails # 1.9.0 (2025-06-04) - Upgrade to Vendure to 3.3.2 # 1.8.0 (2024-12-19) - Update Vendure to 3.1.1 # 1.7.1 (2024-08-04) - Update compatibility range (#480) # 1.7.0 (2024-09-06) - Updated `@google-cloud/tasks` to `"^5.4.0"` - Generates a unique task name; this reduces the latency during creation of the task # 1.6.0 (2024-06-21) - Updated Vendure to 2.2.6 # 1.5.0 (2024-01-30) - Don't store `job.data` when it's too big for MySQL text column - Remove jobs older than 30 days on application startup # 1.4.0 (2023-12-19) - Allow setting `fallback:true` to fallback to HTTP instead of gRPC to prevent DEADLINE_EXCEEDED errors. For more details see https://github.com/googleapis/nodejs-tasks/issues/397#issuecomment-618580649 - Allow setting of all Google Cloud Tasks Client options via `clientOptions: ...` - Removed `bodySizeLimit` option, because body-parser is loaded by NestJs since Vendure V2 # 1.3.0 (2023-11-21) - Only log error when job is not added to queue after configured retries - Apply exponential backoff when adding to queue doesn't work. # 1.2.0 (2023-10-24) - Updated vendure to 2.1.1 # 1.1.2 (2023-09-26) - Added `onJobFailure` option to inspect errors from failed jobs([#262](https://github.com/Pinelab-studio/pinelab-vendure-plugins/pull/262)) 94:T1080,# Vendure SendCloud plugin This plugin syncs orders to the SendCloud fulfillment platform. ## How it works 1. When an order is placed, it is automatically sent to SendCloud as a parcel (for label creation). 2. The order stays in `PaymentSettled` state in Vendure — **no fulfillment is created at this point**. 3. Once an order has been sent to SendCloud, SendCloud is responsible for tracking status. The Vendure order will simply be transitioned to `Delivered` by the included scheduled task. This is because orders are sometimes cancelled and duplicated in Sendcloud, resulting in misaligned stock. 4. A private note is added to the order after each sync attempt, indicating success or failure. ## Getting started 1. Add the plugin to your `vendure-config.ts`: ```ts plugins: [ SendcloudPlugin.init({}), ... ] ``` 2. Go to your SendCloud account and go to `Settings > Integrations` and create an integration. 3. Write down the `secret` and `publicKey` of the created integration. 4. Start Vendure and login as admin. 5. Make sure you have the permission `SetSendCloudConfig`. 6. Go to `Settings` > `Channels`, open the channel you want to configure and select the **SendCloud** tab. Fill in your SendCloud `Secret` and `Public key`. Configuration is stored per channel as Channel custom fields, so no Admin UI extension needs to be compiled. 7. Additionally, you can set a `Default phone number`, for when a customer hasn't filled out one. A phone number is required by Sendcloud in some cases. > SendCloud is considered enabled for a channel once both `Secret` and > `Public key` are set. ## Scheduled task: fulfill settled orders An optional scheduled task `fulfillSettledOrdersTask` is included to automatically transition settled orders to `Delivered`. It is **not auto-registered** — you need to add it to your `schedulerOptions.tasks` yourself. The task runs nightly (default 2:00 AM) and processes all `PaymentSettled` orders placed within the last N days (default 7) that use the SendCloud fulfillment handler. Each qualifying order is fulfilled and transitioned to `Delivered`. Do not manually change order statuses in Vendure if you use this scheduled task. The task will fulfill orders and transition to delivered every night. ```ts import { DefaultSchedulerPlugin } from '@vendure/core'; import { SendcloudPlugin, fulfillSettledOrdersTask, } from '@pinelab/vendure-plugin-sendcloud'; const config: VendureConfig = { plugins: [SendcloudPlugin.init({}), DefaultSchedulerPlugin.init()], schedulerOptions: { tasks: [ // Use defaults (every day at 2:00 AM, look back 7 days) fulfillSettledOrdersTask, // Or configure the task fulfillSettledOrdersTask.configure({ schedule: (cron) => cron.everyDayAt(3, 0), params: { settledSinceDays: 14 }, }), ], }, }; ``` ## Additional configuration You can choose to send additional info to SendCloud: `weight`, `hsCode`, `origin_country` and additional parcel items. Parcel items will show up as rows on your SendCloud packaging slips. ```ts import { SendcloudPlugin, getNrOfOrders, } from '@pinelab/vendure-plugin-sendcloud'; plugins: [ SendcloudPlugin.init({ /** * Implement the weightFn to determine the weight of a parcel item, * or set a default value */ weightFn: (line) => (line.productVariant.product?.customFields as any)?.weight || 5, /** * Implement the hsCodeFn to set the hsCode of a parcel item, * or set a default value */ hsCodeFn: (line) => (line.productVariant.product?.customFields as any)?.hsCode || 'test hs', /** * Implement the originCountryFn to set the origin_country of a parcel item, * or set a default value */ originCountryFn: (line) => 'NL', /** * Implement the additionalParcelItemsFn to add additional rows to the SendCloud order. * This example adds the nr of previous orders of the current customer to SendCloud */ additionalParcelItemsFn: async (ctx, injector, order) => { const additionalInputs = []; additionalInputs.push(await getNrOfOrders(ctx, injector, order)); return additionalInputs; }, }), ]; ``` 95:T6a6,# 2.2.0 (2026-07-21) - Moved configurations from DB into code # 2.1.1 (2026-06-10) - Made the number of job queue retries for syncing orders to SendCloud configurable via `maxRetries` plugin option (default: 10, previously hardcoded to 20). # 2.1.0 (2026-08-05) - Upgraded to Vendure 3.6.3 # 2.0.0 (2026-04-12) - **Breaking**: Removed all webhook handling. Sendcloud is responsible for fulfillment. - Added `fulfillSettledOrdersTask` scheduled task (opt-in) to fulfill settled orders to `Delivered` on a nightly basis. - Orders are no longer automatically fulfilled on placement. They stay in `PaymentSettled` until the scheduled task runs to prevent misaligned stock in Vendure. # 1.6.0 (2026-02-05) - Upgraded to Vendure 3.5.3 # 1.5.3 (2025-11-13) - Documentation update # 1.5.2 (2025-11-06) - Updated official documentation URL # 1.5.1 (2025-09-15) - Log existing fulfillments when items are already fulfilled # 1.5.0 (2025-06-04) - Upgrade to Vendure to 3.3.2 # 1.4.0 (2024-12-19) - Update Vendure to 3.1.1 # 1.3.1 (2024-08-04) - Update compatibility range (#480) # 1.3.0 (2024-06-21) - Updated Vendure to 2.2.6 # 1.2.4 (2024-06-13) - Using util.inspect again to log the incoming webhook body # 1.2.4 (2024-06-13) - Check if incoming request is a Buffer or already parsed by other middleware # 1.2.3 (2024-06-13) - Log request body, instead of util.inspect # 1.2.2 (2024-06-13) - Added better logging for failing incoming webhooks # 1.2.1 (2023-01-16) - Correctly transition order to Delivered after it has been Shipped # 1.2.0 (2023-11-16) - Fulfill on order placement, to prevent stock levels going out of sync # 1.1.0 (2023-10-24) - Updated vendure to 2.1.1 96:T602,# Vendure Facets Suggestion Plugin This plugin allows you to define facets that will show as suggestions on a product detail page. You can set facets to always show on every product detail, or dependant on other facet values. This feature is based on one of [Michael Bromley's (Co-founder of Vendure) tutorials](https://www.youtube.com/watch?v=nfIlBvbMcJ8). ![image](https://plugins.pinelab.studio/plugin-images/facet-suggestions_product-detail.png) ## Getting started 1. Add the plugin to your `vendure-config.ts`: ```ts ... plugins: [ FacetSuggestionsPlugin, ... ] ... ``` The suggested facets selector on the product detail page is provided via a React Dashboard extension — no Admin UI compilation step is needed. 2. Run a DB migration to add the new custom fields: https://docs.vendure.io/guides/developer-guide/migrations/#migration-workflow 3. Start the server and login to the admin UI and go to `facets` 4. On the facet detail page, check the box `Show on product detail page` 5. Update the facet 6. Go to a product detail page 7. You should now see a facet value selector for your facet right below the name/description block There are two ways to show facets on the product detail page: 1. `Show on product detail page` - Always show for every product 2. `Show if product has facets` - Only show if a product already has selected facets. For example, you can use this to create product types: "If product has `category:laptop`, it should also have a facet value from the `memory` facet" 97:T701,# Vendure Coinbase plugin Accept crypto payments via Coinbase Commerce in Vendure. ## Getting started Add the plugin to your `vendure-config.ts`: ```ts import { CoinbasePlugin } from "@pinelab/vendure-plugin-coinbase" plugins: [ CoinbasePlugin, ... ]; ``` ### 2. Set API key in Vendure 1. Start your server 2. Go to the Admin UI > Settings > Payment methods and add a payment method with handler `coinbase-payment-handler` 3. Set your Coinbase API key. You can find your API key at https://beta.commerce.coinbase.com/settings/security 4. Set your desired storefront redirectUrl, something like `https://storefront/order/`. Your customer will be redirected to this page + order code: `https://storefront/order/897HH7HG7` 5. Save the payment method ### 3. Set webhook in Coinbase 1. Go to https://beta.commerce.coinbase.com/settings/notifications 2. Add a new webhook with endpoint `https:///payments/coinbase` ### 4. Storefront usage You can now call the mutation `createCoinbasePaymentIntent` to get a redirectUrl to the Coinbase hosted checkout page. You can redirect your customer to this URL, so your customer can continue making a payment on the Coinbase platform. After payment the customer will be redirected to `https://storefront/order/897HH7HG7` ## Notes - Orders are NOT transitioned to `PaymentSettled` directly after Coinbase redirects the customer to the confirmation page, because crypto transactions can take some time to confirm. You should notify your customer with a message that the order will be handled when their transaction is confirmed. This can take a few minutes. - Refunds are not supported. If you want to refund a payment done via Coinbase you need to manually do so. This plugin will not do refunds via Coinbase. 98:T1d47,--- name: badge-plugin title: Badge Plugin description: Vendure plugin for managing and displaying product badges via the admin UI and shop API. version: 4.0.7 tags: - vendure - plugin - badge - product - label --- # Badge Plugin A Vendure plugin for creating image badges and showing them on products in your storefront. A badge is an image asset (e.g. "New", "Sale", "Best Seller") placed at a fixed position on a product image. Badges are attached to **collections**, and every product in a badged collection automatically inherits that collection's badge, so you label many products at once instead of one at a time. Badges are managed from the Admin UI and read from the Shop API, are **channel-aware** (each channel sees only its own badges), and expose a ready-to-use `badges` field on `Product`, `ProductVariant`, and `SearchResult`. ## Features - **Image badges** – Each badge is an uploaded asset rendered at a chosen position on the product - **Collection-based** – Assign a badge to a collection; all products in that collection (and its sub-collections) inherit it - **Configurable positions** – Restrict badges to a fixed set of positions (e.g. `top-left`, `top-right`); invalid positions are rejected - **Channel-aware** – Badges are scoped per channel; admins and storefronts only see badges for the active channel - **Admin UI** – Manage badges from a dedicated section in the Vendure Admin UI / Dashboard - **Shop API** – Read badges directly off `Product`, `ProductVariant`, and `SearchResult`, or query a collection's badge ## Compatibility Vendure **^3.6.0** ## Getting started ```bash npm install @haus-tech/badge-plugin ``` Or with Yarn: ```bash yarn add @haus-tech/badge-plugin ``` ## Configuration Add the plugin to your Vendure configuration in `vendure-config.ts`: ```typescript import { BadgePlugin } from '@haus-tech/badge-plugin' export const config = { plugins: [ BadgePlugin.init({ availablePositions: ['top-left', 'top-right', 'bottom-left', 'bottom-right'], }), ], } ``` The plugin adds a `badge` table (plus its channel join table) to the database, so generate and run a migration before starting the server: ```bash npx vendure migrate ``` (Or generate one with your project's existing migration workflow.) Then restart the server. Badges appear under their own section in the Admin UI. ## Configuration options | Option | Type | Default | Description | | -------------------- | ---------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | | `availablePositions` | `string[]` | `['top-left', 'top-right', 'bottom-left', 'bottom-right']` | Available positions selecteble in the ui | The configured positions are also exposed on the Admin API via the `getBadgePluginConfig` query, so the Admin UI can offer them as choices. ## How it works A **badge** holds an image asset, a position and a link to one collection. Products are never badged directly, they inherit badges from the collections they belong to: 1. **Create a badge** in the Admin UI: upload an image, pick a position, and assign it to a collection. 2. **Products inherit it** – every product in that collection, including products in its sub-collections, gets the badge automatically through the Shop API. 3. **The storefront reads it** – fetch the `badges` field on a product (or search result) and render each badge's image at its `position`. Because badges are channel-aware, a badge is only visible in the channel it was created in. ## Permissions Badge management is exposed on the Admin API and guarded by the standard Vendure catalog permissions: | Operation | Required permission | | ------------------------------------ | ------------------- | | Query badges / plugin config | `ReadCatalog` | | Create a badge | `CreateCatalog` | | Update a badge | `UpdateCatalog` | | Delete a badge | `DeleteCatalog` | The Shop API badge queries are public, matching the rest of the Vendure shop API. ## Usage ### Admin UI Once installed, manage badges from the dedicated **Badges** section in the Admin UI. From there you can: - Create a badge by uploading an image asset and choosing a position. - Assign the badge to a collection. - Update or delete existing badges. Deleting a badge also deletes its image asset. ### Shop API The plugin extends the Shop API with badge queries and adds a `badges` resolver field to `Product`, `ProductVariant`, and `SearchResult`. | Field / Query | Returns | Description | | ---------------------------------------- | --------------- | ------------------------------------------------------------------------ | | `Product.badges` | `[Badge!]!` | Badges inherited from all collections the product belongs to | | `ProductVariant.badges` | `[Badge!]!` | Badges from the variant's collections | | `SearchResult.badges` | `[Badge!]!` | Badges for a search result (resolved via its product's collections) | | `badges(options)` | `BadgeList!` | Paginated list of all badges in the active channel | | `getBadgeFromCollection(collectionId)` | `Badge` | The badge assigned to a single collection, if any | | `getBadgesFromCollections(collectionIds)`| `[Badge!]!` | Badges assigned to any of the given collections | The most common pattern is to read badges straight off a product: ```graphql query ProductBadges($slug: String!) { product(slug: $slug) { id name badges { id position text asset { preview } } } } ``` Or off search results, to render badges in a product listing: ```graphql query Search($input: SearchInput!) { search(input: $input) { items { productName badges { position asset { preview } } } } } ``` ### Example integration Fetch a product's badges from the Shop API and render each one at its `position`: ```ts const res = await fetch('/shop-api', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ query: ` query ($slug: String!) { product(slug: $slug) { badges { position text asset { preview } } } } `, variables: { slug: 'my-product' }, }), }) const { data } = await res.json() // data.product.badges -> [{ position: 'top-left', asset: { preview } }, ...] // Render each badge image absolutely positioned over the product image using `position`. ``` ## Resources - [Vendure Plugin Documentation](https://docs.vendure.io/guides/developer-guide/plugins/) - [Vendure Collections](https://docs.vendure.io/guides/core-concepts/collections/) - [GraphQL Code Generator](https://the-guild.dev/graphql/codegen) for generating TypeScript types for custom GraphQL types.99:Tdc1,# Vendure Selectable Gifts Plugin Vendure plugin to allow your loyal customers to select gifts when they placed more than X orders, or to select a gift when their order value is over $50. - Administrators can use a Promotion to select products that are applicable as gift. - Administrators can use Promotion Conditions to determine if gifts are eligible for an order - The storefront can fetch eligible gifts for an order,and add a gift to cart - The selected gift in cart will be free of charge - Includes the Promotion Condition `When customer placed more than {minimum} orders` ## Getting started Just add the plugin to the plugins in your `vendure-config.ts`: ```ts import { SelectableGiftsPlugin } from '@pinelab/vendure-plugin-selectable-gifts'; plugins: [SelectableGiftsPlugin], ``` ### Admin UI 1. Create a Promotion and select Condition `If customer placed more than { amount } orders`, and fill out the number you'd like, e.g. 'placed more than 5 orders'. 2. Attach the Action `Allow selected products as free gift` to the Promotion and select which variants should be selectable as gift. You can use different conditions for the free gifts, but the promotion **needs to have the selectable_gifts action**, in order for the `eligibleGifts` query to work. ### Storefront usage 1. On your storefront, call `eligibleGifts` to show a list of eligible gifts to your customer: ```graphql { eligibleGifts { id name sku priceWithTax } } ``` 2. Add the desired Gift to the order with the `addSelectedGiftToOrder` mutation: ```graphql mutation addSelectedGiftToOrder($productVariantId: ID!) { addSelectedGiftToOrder(productVariantId: $productVariantId) { ... on Order { id code totalWithTax lines { id quantity linePriceWithTax discountedUnitPriceWithTax discountedLinePriceWithTax productVariant { id name sku } customFields { isSelectedAsGift } } discounts { amount amountWithTax description } } ... on ErrorResult { errorCode message } } } ``` 3. The order should now include the Gift, with a `discountedLinePriceWithTax` of €0,- 4. You can display the selected gift to the customer by finding the order line that has `customField.isSelectedAsGift = true`. The quantity of that order line will always be 1. ```ts const orderLineWithGift = order.lines.find( (l) => l.customFields.isSelectedAsGift ); ``` ### Gift tiers You can create multiple promotions with different gifts to support different gift tiers. For example: - _Tier 1 promotion: Customers with over 2 placed orders can select gifts A, B and C_ - _Tier 2 promotion: Customers with over 5 placed orders can select gifts X, Y and Z_ When a customer has over 5 placed orders, the `eligibleGifts` query will return gifts A, B, C, X, Y and Z, because both promotion conditions are met. However, only 1 gift can be added to the order, even though the gifts come from 2 different promotions. ℹ️ Only 1 gift can be added to an order at any given time. Selecting a new gift will remove the other selected gift. If you don't want tier 2 to have tier 1 gifts, you can set a maximum in your promotion condition. It would then look like this: - _Promotion 1: Customers with 2 - 5 placed orders can select gifts A, B and C_ - _Promotion 2: Customers with 5 - 999 placed orders can select gifts X, Y and Z_ 9a:T1c80,# Vendure UTM Tracker Plugin This plugin aims to fix over attribution when you use multiple different marketing platforms, by connecting UTM parameters directly to orders. ![UTM Tracker Plugin](https://plugins.pinelab.studio/plugin-images/utm-tracker.jpeg) When using multiple marketing platforms, each platform has their own attribution model, and each doesn't know what the other already attributed. This can lead to over attribution, or double-attribution. This means your ROAS or ROI might look better than it actually is. This plugin connects UTM parameters directly to orders, so that attribution can never exceed the actual value of an order. This might lead to slight under-attribution, but never to over attribution. ## Getting started 1. Add the plugin to your `vendure-config.ts` ```ts import { UTMTrackerPlugin, FirstClickAttribution, LastClickAttribution, LinearAttribution, UShapedAttribution, NoopAttribution, } from '@pinelab/vendure-plugin-utm-tracker'; UTMTrackerPlugin.init({ // Replace with new NoopAttribution() to collect tracking data without attribution. attributionModel: new FirstClickAttribution(), maxParametersPerOrder: 5, // The maximum number of UTM parameters that can be added to an order. If a customer adds more than this number, the oldest UTM parameters will be removed. maxAttributionAgeInDays: 10, // The maximum age of a UTM parameter to be attributed. If a UTM parameter is older than this number of days, it will not be attributed. getCampaignDisplayName: (ctx, utmParameters) => { // Allows you to set a custom display name for a campaign, based on the ctx and utm params. // Useful for example with Google Ads, where the campaign is the campaign ID, not the campaign name. if (utmParameters.campaign === '1234567890') { return `Campaign 1`; } else if (utmParameters.campaign === '1234567891') { return `Campaign 2`; } else { return utmParameters.campaign; } } }), ``` Set `attributionModel: new NoopAttribution()` to retain tracking parameters without attributing order value. The attributed percentage and value remain null after order placement, and the **UTM attribution** table displays `-` for the attributed value. 2. Generate and run a database migration for the plugin entities. Upgrading from a version before 1.7.0 requires an additive nullable `clid` column on `utm_order_parameter`; existing rows remain valid with a null client ID. Review the generated migration before running it. The React order detail extension displays two tables. **UTM attribution** keeps the campaign display name and attributed value view. **UTM Parameters** shows the raw Connected, Source, Medium, Campaign, Term, Content, and Client ID values for every retained parameter set. Missing values display `-`. No Admin UI compilation step is needed, but this plugin doesn't include diagrams or charts. Use your own data visualization or BI tool for further analysis. ## Enable UTM parameters in your marketing tools Most platforms like Klaviyo or Google Ads allow you to automatically add UTM parameters to your campaigns. This is needed to extract the parameters on your storefront. ## Storefront usage To add parameters to an order, you can use the `addUTMParametersToOrder` mutation: ```graphql mutation addUTMParametersToOrder($inputs: [UTMParameterInput!]!) { addUTMParametersToOrder(inputs: $inputs) } ``` Example variables: ```json { "inputs": [ { "connectedAt": "2025-01-01T00:00:00.000Z", "source": "test-source1", "medium": "test-medium1", "campaign": "test-campaign1", "term": "test-term1", "content": "test-content1", "clid": "client-id-1" }, { "connectedAt": "2025-01-02T00:00:00.000Z", "clid": "client-id-only" } ] } ``` `clid` is optional and can be supplied with UTM values or by itself. `connectedAt` remains required for every parameter set. Keep in mind that UTM parameters can only be added to an active order! On most page visits, an active order is not present yet, so you should save the parameters in a cookie or local storage, along with the connectedAt date, and add them to the order when the order is created. You should not create a new order for each page visit, because this drastically increase the amount of orders in your database (Most visitors will never create an order, so this is a waste of resources). You should do something like this in your storefront: ```js import {storeUtmParameters, clearUtmParameters} from './utm-util.js'; // See script below async mounted() { // Or, `useEffect` in React const utmParameters = storeUtmParameters(window.location.search); // Store params in local storage on page load const activeOrder = await getActiveOrder(); // Or your equivalent of fetching the active order if (activeOrder && utmParameters) { await addUTMParametersToOrder(utmParameters); // The newly added mutation clearUtmParameters(); // Clear the parameters from local storage, so they are not added again later } }, ```

`utm-util.js` file

```js /** * Local storage key for storing UTM parameters. */ const key = 'vendure_utm_parameters'; /** * Parses the given path name, and saves the UTM parameters to the local storage. * Does nothing if the path name doesn't contain any UTM parameters. * * Do not pass full url, but use window.location.search instead. */ export function storeUtmParameters(queryParams) { const urlParams = new URLSearchParams(queryParams); const storedParameters = localStorage.getItem(key); const utmParameters = storedParameters ? JSON.parse(storedParameters) : []; const hasTrackingParameters = Array.from(urlParams.keys()).some((key) => key.startsWith('utm_')) || urlParams.has('clid'); if (!hasTrackingParameters) { // Return existing parameters if no new ones are found. Or undefined if no parameters are stored. return utmParameters.length > 0 ? utmParameters : undefined; } utmParameters.push({ connectedAt: new Date().toISOString(), source: urlParams.get('utm_source') || undefined, medium: urlParams.get('utm_medium') || undefined, campaign: urlParams.get('utm_campaign') || undefined, term: urlParams.get('utm_term') || undefined, content: urlParams.get('utm_content') || undefined, clid: urlParams.get('clid') || undefined, }); localStorage.setItem(key, JSON.stringify(utmParameters)); return utmParameters; } /** * Clears the UTM parameters from the local storage. */ export function clearUtmParameters() { localStorage.removeItem(key); } ```

## Insights and visualizations This plugin doesn't include any visualization by default, but you can easily write your own insights with SQL. For example, this query will give you the total attributed revenue per source: ```sql SELECT utm.utmSource, utm.utmMedium, utm.utmCampaign, utm.utmTerm, utm.utmContent, SUM(utm.attributedRevenue) AS totalAttributedRevenue FROM utm_order_parameter utm JOIN `order` o ON utm.orderId = o.id WHERE o.orderPlacedAt IS NOT NULL AND o.state != 'Cancelled' GROUP BY utm.utmSource; ``` You can use different GROUP BY clauses to get the total attributed revenue per medium, campaign, term, content, etc. 9b:T4d2,# 1.7.0 (2026-09-16) - Added optional client-ID (`clid`) tracking through the Shop and Admin APIs. - Added `NoopAttribution` for collecting tracking parameters without attributing order value. - Added a raw UTM Parameters table and titled the existing dashboard table UTM attribution. # 1.6.0 (2026-07-21) - Migrated to React Dashboard # 1.5.0 (2026-08-05) - Upgraded to Vendure 3.6.3 # 1.4.0 (2026-02-05) - Upgraded to Vendure 3.5.3 # 1.3.1 (2026-01-06) - Fix type error in `getCampaignDisplayName` - Fixed typo in UI # 1.3.0 (2026-01-06) - Allow setting a custom display name for a campaign. # 1.2.2 (2025-11-13) - Documentation update # 1.2.1 (2025-11-06) - Updated official documentation URL # 1.2.0 (2025-10-30) - Added UI to view UTM parameters on the order detail page. - Added U-Shaped Attribution model. - Reversed orders of UTM parameters in API: Most recent parameters are now first. # 1.1.1 (2025-10-27) - Add `utm-util.js` file to the README.md # 1.1.0 (2025-10-24) - Allow adding bulk UTM parameters to an order, and de-duplicate parameters on the backend. - Allow passing `connectedAt` date from client, because UTM parameters are saved on the client first # 1.0.0 (2025-10-23) - Initial release 9c:T7a7,# Vendure Social Authentication for Administrators Allow admins to login with social accounts like Google. > **Note:** This plugin (v2.0.0+) only works with the React Dashboard. For the Angular Admin UI, use [v1.4.0](https://www.npmjs.com/package/@pinelab/vendure-plugin-admin-social-auth/v/1.4.0). The plugin setup allows for easy extension of other auth providers. Contributions welcome: Contact us via Discord or Github and we'll help you get started on contributing. You will be able to login if an administrator with your email address already exists in Vendure. Roles and permissions are still handled in Vendure. This plugin disables the native authentication method, so you will only be able to login via Google. ![image](https://plugins.pinelab.studio/plugin-images/admin-google.png) ## Set up Google login First, you need to get your Google Client id using these steps: https://developers.google.com/identity/gsi/web/guides/get-google-api-clientid. This should give you a client id that looks something like `xxxxx.apps.googleusercontent.com` 1. Install `google-auth-library`: `npm install google-auth-library` 2. In your `vendure-config.ts`, add the plugin: ```ts import { AdminSocialAuthPlugin } from '@pinelab/vendure-plugin-admin-social-auth'; ... plugins: [ AdminSocialAuthPlugin.init({ google: { oAuthClientId: process.env.GOOGLE_OAUTH_CLIENT_ID!, }, }), ] ``` 3. Run `npx vite build` 4. Start the server and navigate to `localhost:3000/dashboard/` 5. Login with your Google account 6. If an administrator exists with the same email address, you will be redirected to your dashboard. ## Managing administrators Administrators are managed via the default Vendure Admin UI. Just create an administrator with the same email address as the social account. When an admin logs in with a social account for the first time, the social auth method will be added to the `user.authenticationMethods`. 89:{"data":{"items":[{"id":"1959f0be-897b-4208-b1e0-58f70e0f39bf","packageName":"@pinelab/vendure-plugin-stock-monitoring","slug":"stock-monitoring-plugin","name":"Stock Monitoring Plugin","description":null,"registry":"npm","repositoryUrl":"https://github.com/Pinelab-studio/pinelab-vendure-plugins","iconUrl":"https://minio.minio--wq6vpbzhh2fw.addon.code.run/api-public/plugin-icon/72aeb104-ef77-4af1-88c4-d425fcbb7355/original.png","downloadCount":545,"latestVersion":"3.1.2","lastPublish":"2026-08-25T11:57:09.200Z","compatibility":">=3.0.0","readme":"$8b","changelog":"$8c","docs":null,"metadataVersion":"3.1.2","partnerId":"a87615d5-735c-494b-b572-84feaab866d8","categories":["admin-extensions"],"createdAt":"2026-05-22T12:30:12.657Z"},{"id":"9dd5b53c-f66e-4707-9342-68b82320f32e","packageName":"@haus-tech/product-import-export-plugin","slug":"product-import-export","name":"Product Import & Export","description":null,"registry":"npm","repositoryUrl":"https://github.com/WeAreHausTech/haus-tech-vendure-plugins-public","iconUrl":"https://minio.minio--wq6vpbzhh2fw.addon.code.run/api-public/plugin-icon/79d5ea89-a7b5-4c4a-8687-4552033ef826/original.png","downloadCount":533,"latestVersion":"3.6.3","lastPublish":"2026-08-21T11:49:22.421Z","compatibility":"^2.0.0 || ^3.0.0","readme":null,"changelog":"$8d","docs":null,"metadataVersion":"3.6.3","partnerId":"b3f85c03-d34c-494e-af34-a2a9a55ca163","categories":["import-export"],"createdAt":"2026-06-22T10:10:52.017Z"},{"id":"c035399f-df6e-4b06-8260-d5f557374e66","packageName":"@uplab/vendure-plugin-turbosms","slug":"turbosms","name":"TurboSMS","description":null,"registry":"npm","repositoryUrl":"https://github.com/Uplab/uplab-vendure-plugins/tree/main/packages/vendure-plugin-turbosms#readme","iconUrl":"https://minio.minio--wq6vpbzhh2fw.addon.code.run/api-public/plugin-icon/19ed20ff-4e89-4c4f-bf3a-ed65c11c89c1/original.svg","downloadCount":445,"latestVersion":"0.2.0","lastPublish":"2026-08-26T07:20:16.998Z","compatibility":"^3.7.0","readme":"$8e","changelog":"$8f","docs":null,"metadataVersion":"0.2.0","partnerId":"94b2aa77-7aea-48db-8d1c-7be76fe68393","categories":["email-notifications"],"createdAt":"2026-08-31T09:04:55.250Z"},{"id":"ccb3cfb3-cb11-4deb-9908-83bfd0670fe5","packageName":"@pinelab/vendure-plugin-klaviyo","slug":"klaviyo","name":"Klaviyo","description":null,"registry":"npm","repositoryUrl":"https://github.com/Pinelab-studio/pinelab-vendure-plugins","iconUrl":"https://minio.minio--wq6vpbzhh2fw.addon.code.run/api-public/plugin-icon/28dc6533-278f-40b4-a649-cde5e23a8d59/original.png","downloadCount":430,"latestVersion":"1.13.0","lastPublish":"2026-07-22T08:22:01.490Z","compatibility":">=2.2.0","readme":"$90","changelog":"$91","docs":null,"metadataVersion":"1.13.0","partnerId":"a87615d5-735c-494b-b572-84feaab866d8","categories":["marketing-seo"],"createdAt":"2026-05-22T12:36:54.040Z"},{"id":"e0da3649-83d5-4961-9794-cc740e4efcb2","packageName":"@pinelab/vendure-plugin-google-cloud-tasks","slug":"google-cloud-tasks","name":"Google Cloud Tasks","description":null,"registry":"npm","repositoryUrl":"https://github.com/Pinelab-studio/pinelab-vendure-plugins","iconUrl":"https://minio.minio--wq6vpbzhh2fw.addon.code.run/api-public/plugin-icon/267fcac3-e672-4abd-ad76-9f21e717fbb4/original.png","downloadCount":413,"latestVersion":"2.2.0","lastPublish":"2026-07-22T08:21:30.515Z","compatibility":">=2.2.0","readme":"$92","changelog":"$93","docs":null,"metadataVersion":"2.2.0","partnerId":"a87615d5-735c-494b-b572-84feaab866d8","categories":["infrastructure"],"createdAt":"2026-05-22T12:36:46.279Z"},{"id":"6a05c3e4-ef2e-4530-bda6-df799830cb8c","packageName":"@pinelab/vendure-plugin-sendcloud","slug":"sendcloud","name":"SendCloud","description":null,"registry":"npm","repositoryUrl":"https://github.com/Pinelab-studio/pinelab-vendure-plugins","iconUrl":"https://minio.minio--wq6vpbzhh2fw.addon.code.run/api-public/plugin-icon/882c65c4-f855-4666-bc64-958b72acf76c/original.png","downloadCount":385,"latestVersion":"2.2.0","lastPublish":"2026-07-21T13:59:18.254Z","compatibility":">=3.1.0","readme":"$94","changelog":"$95","docs":null,"metadataVersion":"2.2.0","partnerId":"a87615d5-735c-494b-b572-84feaab866d8","categories":["shipping-fulfillment"],"createdAt":"2026-05-22T12:37:24.371Z"},{"id":"91e403c6-c426-4f2b-ac04-68b28ed04cd0","packageName":"@pinelab/vendure-plugin-facet-suggestions","slug":"facet-suggestions","name":"Facet Suggestions","description":null,"registry":"npm","repositoryUrl":"https://github.com/Pinelab-studio/pinelab-vendure-plugins","iconUrl":"https://minio.minio--wq6vpbzhh2fw.addon.code.run/api-public/plugin-icon/ab514d37-53ef-40ba-aca1-10012d1b7ad8/original.png","downloadCount":384,"latestVersion":"1.6.1","lastPublish":"2026-08-04T11:14:42.422Z","compatibility":">=2.2.0","readme":"$96","changelog":"# 1.6.1 (2026-08-04)\n\n- Include dashboard extensions in dist.\n\n# 1.6.0 (2026-07-21)\n\n- Migrated to React Dashboard\n\n# 1.5.0 (2026-08-05)\n\n- Upgraded to Vendure 3.6.3\n\n# 1.4.0 (2026-02-05)\n\n- Upgraded to Vendure 3.5.3\n\n# 1.3.2 (2025-11-13)\n\n- Documentation update\n\n# 1.3.1 (2025-11-06)\n\n- Updated official documentation URL\n\n# 1.3.0 (2025-06-04)\n\n- Upgrade to Vendure to 3.3.2\n\n# 1.2.0 (2024-12-20)\n\n- Update Vendure to 3.1.1\n\n# 1.1.2 (2024-12-20)\n\n- Fix to correctly save facets with Vendure V3.1\n\n# 1.1.1 (2024-08-04)\n\n- Update compatibility range (#480)\n\n# 1.1.0 (2024-06-21)\n\n- Updated Vendure to 2.2.6\n\n# 1.0.0 (2024-01-03)\n\n- Created the plugin\n","docs":null,"metadataVersion":"1.6.1","partnerId":"a87615d5-735c-494b-b572-84feaab866d8","categories":["storefront"],"createdAt":"2026-05-22T12:36:40.687Z"},{"id":"b7107fc1-6036-48f2-b4d3-e8bed77ca46c","packageName":"@pinelab/vendure-plugin-coinbase","slug":"coinbase","name":"Coinbase","description":null,"registry":"npm","repositoryUrl":"https://github.com/Pinelab-studio/pinelab-vendure-plugins","iconUrl":"https://minio.minio--wq6vpbzhh2fw.addon.code.run/api-public/plugin-icon/c0a771df-c0bb-4b66-99bf-d27e37b2d47f/original.png","downloadCount":366,"latestVersion":"1.6.0","lastPublish":"2026-06-30T09:22:14.132Z","compatibility":">=2.2.0","readme":"$97","changelog":"# 1.6.0 (2026-08-05)\n\n- Upgraded to Vendure 3.6.3\n\n# 1.5.0 (2026-02-05)\n\n- Upgraded to Vendure 3.5.3\n\n# 1.4.2 (2025-11-13)\n\n- Documentation update\n\n# 1.4.1 (2025-11-06)\n\n- Updated official documentation URL\n\n# 1.4.0 (2025-06-04)\n\n- Upgrade to Vendure to 3.3.2\n\n# 1.3.0 (2024-12-19)\n\n- Update Vendure to 3.1.1\n\n# 1.2.1 (2024-08-04)\n\n- Update compatibility range (#480)\n\n# 1.2.0 (2024-06-21)\n\n- Updated Vendure to 2.2.6\n\n# 1.1.0 (2023-10-24)\n\n- Updated vendure to 2.1.1\n","docs":null,"metadataVersion":"1.6.0","partnerId":"a87615d5-735c-494b-b572-84feaab866d8","categories":["other"],"createdAt":"2026-05-22T12:36:32.992Z"},{"id":"2cbe2996-350c-46d0-8af5-34119444d817","packageName":"@haus-tech/badge-plugin","slug":"product-badges","name":"Product Badges","description":null,"registry":"npm","repositoryUrl":"https://github.com/WeAreHausTech/haus-tech-vendure-plugins-public","iconUrl":"https://minio.minio--wq6vpbzhh2fw.addon.code.run/api-public/plugin-icon/612cba14-92e5-4c48-9c7a-5854a01ceab8/original.png","downloadCount":354,"latestVersion":"4.0.8","lastPublish":"2026-06-29T12:45:06.940Z","compatibility":"^3.6.0","readme":"$98","changelog":"## 4.0.7\n\n### 🩹 Fixes\n\n- handle update asset ([ad0fdbf](https://github.com/WeAreHausTech/haus-tech-vendure-plugins/commit/ad0fdbf))\n\n## 4.0.6\n\n### 🩹 Fixes\n\n- handle update asset ([33e1c58](https://github.com/WeAreHausTech/haus-tech-vendure-plugins/commit/33e1c58))\n\n## 4.0.6-0\n\n### 🚀 Features\n\n- **badge-plugin:** add dashboard integration and enhance badge management ([2603563](https://github.com/WeAreHausTech/haus-tech-vendure-plugins/commit/2603563))\n\n## 4.0.5\n\nThis was a version bump only for badge-plugin to align it with other projects, there were no code changes.\n\n## 4.0.4\n\nThis was a version bump only for badge-plugin to align it with other projects, there were no code changes.\n\n## 4.0.3\n\nThis was a version bump only for badge-plugin to align it with other projects, there were no code changes.\n\n## 4.0.1\n\n### 🚀 Features\n\n- Add badge plugin ([6e7934f](https://github.com/WeAreHausTech/haus-vendure-plugins-public/commit/6e7934fd45123ba7a0cf5c91c2ba22b649276750))\n","docs":null,"metadataVersion":"4.0.8","partnerId":"b3f85c03-d34c-494e-af34-a2a9a55ca163","categories":["storefront","marketing-seo"],"createdAt":"2026-06-29T13:10:46.998Z"},{"id":"d4091185-2377-49b5-b389-3b54ee289105","packageName":"@pinelab/vendure-plugin-selectable-gifts","slug":"selectable-gifts","name":"Selectable Gifts","description":null,"registry":"npm","repositoryUrl":"https://github.com/Pinelab-studio/pinelab-vendure-plugins","iconUrl":"https://minio.minio--wq6vpbzhh2fw.addon.code.run/api-public/plugin-icon/2ef08e66-8edb-4166-ad79-4e77e255caf4/original.png","downloadCount":323,"latestVersion":"1.6.0","lastPublish":"2026-05-26T08:52:12.262Z","compatibility":">=2.2.0","readme":"$99","changelog":"# 1.6.0 (2026-02-05)\n\n- Upgraded to Vendure 3.6.3\n\n# 1.5.1 (2026-05-19)\n\n- Exclude variants whose parent product is disabled from eligible gifts\n\n# 1.5.0 (2026-02-05)\n\n- Upgraded to Vendure 3.5.3\n\n# 1.4.2 (2025-11-13)\n\n- Documentation update\n\n# 1.4.1 (2025-11-06)\n\n- Updated official documentation URL\n\n# 1.4.0 (2025-06-04)\n\n- Upgrade to Vendure to 3.3.2\n\n# 1.3.0 (2024-12-19)\n\n- Update Vendure to 3.1.1\n\n# 1.2.1 (2024-08-04)\n\n- Update compatibility range (#480)\n\n# 1.2.0 (2024-06-21)\n\n- Updated Vendure to 2.2.6\n\n# 1.1.1 (2024-01-23)\n\n- MySQL bugfix and use stock level service for resolving stock\n\n# 1.1.0 (2023-11-22)\n\n- `eligibleGifts` bug fix as reported in #326\n\n# 1.0.0 (2023-11-22)\n\n- Initial release\n","docs":null,"metadataVersion":"1.6.0","partnerId":"a87615d5-735c-494b-b572-84feaab866d8","categories":["marketing-seo"],"createdAt":"2026-05-22T12:37:22.662Z"},{"id":"76b7ac24-c151-45ea-8c6b-f40cb2a29251","packageName":"@pinelab/vendure-plugin-utm-tracker","slug":"utm-tracker","name":"UTM Tracker","description":null,"registry":"npm","repositoryUrl":"https://github.com/Pinelab-studio/pinelab-vendure-plugins","iconUrl":"https://minio.minio--wq6vpbzhh2fw.addon.code.run/api-public/plugin-icon/56a6632c-3d32-4009-b4a2-f881cb39feb8/original.png","downloadCount":316,"latestVersion":"1.7.0","lastPublish":"2026-09-17T11:21:27.625Z","compatibility":"^3.0.0","readme":"$9a","changelog":"$9b","docs":null,"metadataVersion":"1.7.0","partnerId":"a87615d5-735c-494b-b572-84feaab866d8","categories":["marketing-seo"],"createdAt":"2026-05-22T12:37:35.634Z"},{"id":"0cfd742f-387e-4660-b9a4-804aab1e6807","packageName":"@pinelab/vendure-plugin-admin-social-auth","slug":"admin-social-auth","name":"Admin Social Auth","description":null,"registry":"npm","repositoryUrl":"https://github.com/Pinelab-studio/pinelab-vendure-plugins","iconUrl":"https://minio.minio--wq6vpbzhh2fw.addon.code.run/api-public/plugin-icon/a5346787-7951-4e13-b75a-a78bf6d9c20e/original.png","downloadCount":313,"latestVersion":"2.4.1","lastPublish":"2026-08-04T11:14:12.380Z","compatibility":">=3.2.0","readme":"$9c","changelog":null,"docs":null,"metadataVersion":"2.4.1","partnerId":"a87615d5-735c-494b-b572-84feaab866d8","categories":["admin-extensions"],"createdAt":"2026-05-22T12:36:25.995Z"}],"total":44,"page":2,"pageSize":12},"error":"$undefined"}

Plugin Directory

Plugin Directory