Trustpilot, a SpindleCommerce plugin

Asks each customer to review your store on Trustpilot once their order ships, with an email invitation from Trustpilot.

What it does

• One invitation per order. When an order's first shipment is recorded, the plugin asks Trustpilot to invite the customer to write a service review: a review of your store, not of a product. Later shipments of the same order add nothing.
• A few days later. Trustpilot sends the invitation email some days after the shipment (5 by default), so the parcel has arrived by the time the customer is asked.
• From the order. The invitation goes to the order's email address, with the customer's name from the shipping address. It carries the order number as Trustpilot's reference number, and the order's language.
• Your template and sender, when set: the invitation template, the sender's name and address, the reply-to address, tags, and where customers go once they have reviewed.

The plugin uses Trustpilot's Invitations API with your API application's key and secret, on behalf of one of your Trustpilot Business users. When Trustpilot is unreachable or answers with an error, the platform retries the delivery.

Setup

1. Add the plugin to your SpindleCommerce installation and deploy:

   pnpm add @spindlecommerce/plugin-trustpilot

   // ecom.config.ts
   import { trustpilot } from "@spindlecommerce/plugin-trustpilot";
   
   export default defineConfig({ plugins: [email(), stripe(), trustpilot()] });

   It works with plugin SDK 1.0 and every later 1.x release.

2. Create an API application in Trustpilot Business, under Integrations › Developers › APIs, and note its API key and secret. Your Trustpilot plan needs API access.

3. Choose the user invitations are made for. Trustpilot's Invitations API makes them on behalf of a Trustpilot Business user with the Admin or Manager role. Open that user's profile page in Trustpilot Business and copy their User ID.

4. Find your business unit ID from your domain. It is the id in the answer:

   curl -H "apikey: <API key>" "https://api.trustpilot.com/v1/business-units/find?name=example.com"

5. Settings › Plugins › Trustpilot. Enter the API key and secret, the business unit ID and the business user ID.

   • On a server, environment variables can supply all of them but the business unit ID: TRUSTPILOT_API_KEY, TRUSTPILOT_API_SECRET and TRUSTPILOT_BUSINESS_USER_ID.
   • Test connection gets an access token and names the business unit.
   • The plugin is active once every required setting has a value. Orders that ship from then on are invited.

Settings

• API key (TRUSTPILOT_API_KEY) and API secret (secret, TRUSTPILOT_API_SECRET): the API application's.
• Business unit ID: your Trustpilot profile's.
• Business user ID (TRUSTPILOT_BUSINESS_USER_ID): the User ID of an Admin or Manager user, from that user's profile page in Trustpilot Business. Invitations are made on their behalf.
• Sender name, Sender email and Reply-to address: the invitation email's. Empty uses Trustpilot's defaults.
• Template ID: one of the business unit's invitation templates. Empty uses Trustpilot's default template. Trustpilot's API lists them: GET https://invitations-api.trustpilot.com/v1/private/business-units/<business unit ID>/templates.
• Delay (days): whole days after the shipment to send the invitation, 5 by default. 0 sends it at once.
• Redirect URL: where customers go once they have written their review, such as your store.
• Tags: comma-separated tags for the invitations, such as webshop.

When invitations are sent

• On the first shipment. The platform emits order.fulfilled once per shipment. The first the plugin receives creates the order's invitation, once per order (ctx.once("invite:<order ID>")). Later shipments, and deliveries the platform runs again, send nothing.

• At the preferred send time. That is when the plugin receives the event, plus the delay, in UTC. Trustpilot holds the invitation until then.

  • The platform delivers the event seconds after the shipment is recorded, on Vercel too.
  • A delivery that fails is retried later, and the send time moves with it.

• Skipped for orders without an email address.

• What the invitation holds:

  • consumerEmail: the order's email address.
  • consumerName: the name on the shipping address, else on the billing address.
  • referenceNumber: the order number, such as UK-000042.
  • locale: the order's locale as Trustpilot writes it, a language and a country (en-GB). A locale without a country gets the usual one for its language: en becomes en-US, de becomes de-DE.
  • senderName, senderEmail and replyTo, when set.
  • serviceReviewInvitation: the template, the preferred send time, the redirect URL and the tags.
  • The business user it is made on behalf of, in the x-business-user-id header.

• Errors. When Trustpilot answers with an error, the delivery fails with Trustpilot's message, and the platform retries it with backoff. Staff see failed deliveries under the plugin in the admin, and can retry them. An invitation counts as made only once Trustpilot has accepted it.

• The access token. The plugin gets one with the client credentials grant, from the API key and secret alone. Trustpilot answers 429 to token requests made too often, so the plugin caches the token in its storage until a minute before it expires; Trustpilot's tokens last 100 hours. It requests a new one:

  • when the token expires, since these tokens can't be refreshed;
  • when Trustpilot refuses it (a 401), and then retries the call once;
  • when the API key or secret changes.

  Test connection always requests a new one.

Limitations

• Service reviews only. Product review invitations, for the products in the order, are later work.
• Test connection doesn't check the business user. A wrong user ID, or a user without the Admin or Manager role, shows only when an invitation fails.
• No withdrawal. An order refunded or returned before the send time is still invited.
• No backfill. Orders shipped before the plugin was set up aren't invited.
• The access token is kept in the plugin's key-value storage in the database until it expires. Unlike secret settings, it is not encrypted there.
• One user. Every invitation is made on behalf of the user in the settings. If that user loses the Admin or Manager role, invitations fail until the settings name another.

Develop

pnpm install
pnpm test
pnpm build

The tests run the plugin against a fake Trustpilot API. The plugin API it builds on is @spindlecommerce/plugin-sdk.

Release

Each version is staged on npm and goes live when a maintainer approves it.

1. Raise version in package.json and in src/index.ts. A test checks they match.
2. Commit, then tag and push: for example git tag v1.0.1 && git push origin main v1.0.1.
3. The Release workflow tests, builds and stages the version, and creates the GitHub release.
4. Approve it on npmjs.com, under Staged Packages, with 2FA.

The workflow publishes with npm's trusted publishing, so it needs no token. Before its first release, a maintainer links the package to the workflow:

npm trust github @spindlecommerce/plugin-trustpilot --repo spindlecommerce/plugin-trustpilot --file release.yml --allow-stage-publish

Run it just before tagging: npm drops a link that isn't used within 48 hours.

License

MIT