/wix-app

Gift Cards Service Plugin Reference

Overview

The Gift Vouchers Provider SPI allows you to integrate external gift card or voucher systems with Wix eCommerce. This enables customers to redeem gift cards, check balances, and void transactions.

Handlers

Request and Response Schema

Before implementing, call ReadFullDocsMethodSchema on each docs URL to get the full request/response types.

Example: Gift Card Provider Implementation

This example shows a basic gift card provider with all three required handlers.

import { giftVouchersProvider } from '@wix/ecom/service-plugins';

giftVouchersProvider.provideHandlers({
  redeem: async (payload) => {
    const { request, metadata } = payload;
    // Use the `request` and `metadata` received from Wix and
    // apply custom logic.
    return {
      // Return your response exactly as documented to integrate with Wix.
      // Return value example:
      remainingBalance: 80.00,
      currencyCode: metadata.currency || "ILS",
      transactionId: "00000000-0000-0000-0000-000000000001",
    };
  },
  _void: async (payload) => {
    const { request, metadata } = payload;
    // Use the `request` and `metadata` received from Wix and
    // apply custom logic.
    return {
      // Return your response exactly as documented to integrate with Wix.
      // Return value example:
      remainingBalance: 100.00,
      currencyCode: metadata.currency || "ILS",
    };
  },
  getBalance: async (payload) => {
    const { request, metadata } = payload;
    // Use the `request` and `metadata` received from Wix and
    // apply custom logic.
    return {
      // Return your response exactly as documented to integrate with Wix.
      // Return value example:
      balance: 100.00,
      currencyCode: metadata.currency || "ILS",
    };
  },
});

Manual Setup Required

No dashboard configuration beyond installing the app. But there's nothing to redeem/getBalance against until a real gift card exists — a customer (or you, via the Wix Gift Cards app's own purchase/issuance flow) must actually buy or be issued a gift card first. You can't shortcut this by calling redeem with a made-up code; the code has to correspond to a gift card your provider recognizes as real. Test by issuing a real gift card through the site's own gift-card purchase flow, then redeeming it at checkout.

Singular Constraint

GIFT_CARDS_PROVIDER is singular — only one component of this type is allowed per app. Do not scaffold or include two Gift Cards service plugins in the same app.

Key Implementation Notes

1. All three handlers required - You must implement redeem, getBalance, and _void
2. Transaction tracking - The redeem handler must return a unique transactionId for tracking
3. Balance as number - Unlike other SPIs, balance values are numbers, not strings
4. Void restores balance - The _void handler should restore the redeemed amount back to the card
5. Currency handling - Use metadata.currency to get the site's currency setting