skills/wix-app/references/service-plugin/GIFT-CARDS.md

# 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

| Handler | Description |
| --- | --- |
| `redeem` | Process a gift card redemption during checkout |
| `getBalance` | Check the current balance of a gift card |
| `_void` | Cancel/void a previous redemption |

## Request and Response Schema

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

| Handler | Docs URL |
| --- | --- |
| `redeem` | https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/payments/gift-cards/gift-cards-service-plugin/redeem?apiView=SDK |
| `getBalance` | https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/payments/gift-cards/gift-cards-service-plugin/get-balance?apiView=SDK |
| `_void` | https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/payments/gift-cards/gift-cards-service-plugin/void?apiView=SDK |

## Example: Gift Card Provider Implementation

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

```typescript
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