Vendure Store Credit Plugin

A plugin for channel-aware store credit wallets with ledger tracking. Customers can use wallet balance as a payment method at checkout.

Installation

npm i @pinelab/vendure-plugin-store-credit

// vendure-config.ts
import { StoreCreditPlugin } from '@pinelab/vendure-plugin-store-credit';

plugins: [StoreCreditPlugin],

Run a migration to add the Wallet entities to the database, then create a Payment Method in the admin using the store-credit handler.

You also need to rebuild the admin dashboard to see the new Store Credit Wallets on the customer detail page.

Admin API

These functions are available in the admin API.

Create wallet

Each customer can have multiple wallets. This mutation creates a new wallet for the customer. Starting balance is always 0.

mutation CreateWallet($input: CreateWalletInput!) {
  createWallet(input: $input) {
    id
    name
    balance
    currencyCode
    adjustments {
      id
      amount
    }
  }
}
# Variables: { "input": { "customerId": "1", "name": "Gift card" } }

Set balance (add or subtract)

mutation AdjustBalance($input: AdjustBalanceForWalletInput!) {
  adjustBalanceForWallet(input: $input) {
    id
    balance
  }
}
# Variables: { "input": { "walletId": "1", "amount": 1500 } }
# Amount in minor units (1500 = €15.00). Use negative for deductions.

Refund payment to store credit

An admin can choose to refund any payment to store credit wiht the custom refundPaymentToStoreCredit mutation:

mutation RefundToStoreCredit($paymentId: ID!, $walletId: ID!) {
  refundPaymentToStoreCredit(paymentId: $paymentId, walletId: $walletId) {
    id
    balance
  }
}

To refund a payment that was made with store credit, you can use the built-in refundOrder mutation supplied by Vendure. In this case it will refund the store credit to the same wallet that was used to make the payment.

Storefront usage

Customers can pay for orders using their store credit balance.

mutation {
  addPaymentToOrder(
    input: { method: "store-credit", metadata: { walletId: "1" } }
  ) {
    ... on Order {
      id
      code
    }
  }
}

Optionally, a customer can choose to partially pay for an order by specifying the amount to pay with store credit.

mutation {
  addPaymentToOrder(
    input: {
      method: "store-credit"
      metadata: { walletId: "1", amount: 100000 }
    }
  ) {
    ... on Order {
      id
      code
    }
  }
}

Logged-in customers can fetch their wallets via activeCustomer:

query MyWallets {
  activeCustomer {
    id
    wallets {
      items {
        id
        name
        balance
        currencyCode
        adjustments {
          amount
        }
      }
      totalItems
    }
  }
}

Or query a single wallet by ID:

query Wallet($id: ID!) {
  wallet(id: $id) {
    id
    name
    balance
    currencyCode
    adjustments {
      id
      amount
      createdAt
    }
  }
}

Gift card code security

Gift card wallets are identified by their code. Treat this code like cash: anyone who knows the code can spend the wallet. It is the responsibility of the consuming project (via the createGiftCardWallet strategy) to make sure the returned cardCode is sufficiently unguessable — use a cryptographically secure random generator (e.g. crypto.randomUUID() or generatePublicId() from @vendure/core) and never derive the code from predictable data like order id or sequence numbers.

The walletByCode query has a few safeguards to reduce enumeration risk:

• on the admin API it requires the UpdateOrder permission;
• on the shop API it requires the caller to have an active order on the session;
• it returns null for unknown codes (instead of throwing) so the API does not leak whether a given code exists;
• lookups are channel-scoped.

Helper scripts

You can create wallets with a specified balance for all (or given) customers with the following script that is included:

import { bootstrap } from '@vendure/core';
import { createWalletsForCustomers } from '@pinelab/vendure-plugin-store-credit';
import dotenv from 'dotenv';
dotenv.config({ path: process.env.ENV_FILE });

// Import vendure config after dotenv.config() so env variables are available in config
import('./vendure-config')
  .then(async ({ config }) => {
    const app = await bootstrap(config);
    const wallets = await createWalletsForCustomers(
      app,
      // Details for all wallets
      {
        name: 'Special promotion wallet',
        balance: 123456,
        balanceDescription: 'Special promotion credits',
      },
      // Administrator email address to use for record-keeping
      '[email protected]',
      // A list of customer email addresses to create wallets for. If omitted, all customers get a wallet.
      undefined
    );
    console.log(`Created ${wallets.length} wallets`);
    await app.close();
  })
  .catch((err) => {
    console.error(err);
  });

FAQ

Can I create a wallet with an initial starting balance?

To create a wallet with an initial starting balance, you can create a wallet for a customer on the customer detail page in the admin dashboard. Wallets always start with a balance of 0, but you can adjust the balance to anything you want after creation. Wallets always start with 0, so that you can recalculate the current balance by 'rerunning' all the adjustments.

Can I delete a customer's wallet?

Currently you can not delete a wallet, because of accountability: you need to be able to see the history of adjustments on the wallet. Future version will allow you to archive a wallet.