Get to know our frameworks

Select an app template built on your preferred framework.

Build apps on our native app editor. Use drag and drop elements, Velo code and Wix APIs to develop custom features.

Streamline your app development process with the Wix CLI. Get a familiar developer experience with minimal setup and configuration.

Take full control over your app's tech stack, deployment, and hosting.

App templates

Wix Blocks templates

Wix CLI templates

Self-hosted templates

Kickstart your app development with templates built on your preferred Wix developer tool. Browse templates for practical foundation and get to know the Wix ecosystem.

Wix App Templates for Developers

This example apps can be used as a starting point for building your own app, for concrete examples of how to use Wix framework, or for inspiration.

Choose a template.<0 />Build an app.

Browse by:

How to build it step by step:

This template is built with:

Read how this template was built, step by step.

How we built this template

Deployment instructions:

Choose a package manager and run the command in your terminal.

Copy command

Before you get started, make sure you have the following:

Prerequisite steps

Get started with Wix CLI

Begin by setting up your Next.js project with your preferred hosting platform.

Select your hosting service

Start the deployment flow and set up your template repo on Netlify. After you finish set up, come back here and add your Netlify custom domain.

Copy the code from our Git repo to deploy your app on any platform that supports Next.js.

Start the deployment flow and set up your template repo on Vercel. After you finish set up, come back here and add your Vercel generated URL.

Add the base URL and give your app a name.

App details

Go to the app dashboard and test your app to ensure a smooth integration within the Wix ecosystem. <0>Learn more about app checks and testing</0>

Define your environment

Terminal

Related templates

Note

Warning

Your app name will be used as the namespace suffix.

Name your app to generate a namespace. This lets you refer to your app in code later on.

Go Headless

Build Apps

Client

API Preview

Ricos

Develop Websites

REST

Velo

GraphQL (Alpha)

payload

_voidEnvelope

This method requests that a gift card transaction be voided by your app.
Wix calls this method when a purchase fails after gift card redemption.

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

giftVouchersProvider.provideHandlers({

  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: "USD"
      }
    }
});


Example of an `giftVouchersProvider` return value @description:

_void

VoidResponse

GiftCardDisabledWixError

GiftCardExpiredWixError

GiftCardNotFoundWixError

GetBalanceEnvelope

This method retrieves gift card data from your app.
Wix calls this method when a customer applies a gift card as a payment method at checkout.

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

giftVouchersProvider.provideHandlers({

  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: "USD"
      }
    }
});


getBalance

GetBalanceResponse

Gift card already redeemed for the given order

AlreadyRedeemedWixError

CurrencyNotSupportedWixError

InsufficientFundsWixError

RedeemEnvelope

This method requests that a transaction be created by your app.
Wix calls this method when a customer completes a purchase that includes a gift card as a payment method at checkout.

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: "USD",
        transactionId: "00000000-0000-0000-0000-000000000001"
      }
    }
});


redeem

RedeemResponse

# About the Wix eCommerce Gift Vouchers Service Plugin

The Wix eCommerce Gift Vouchers Provider Service Plugin allows you to integrate with Wix as a gift card service provider, 
enabling Wix merchants to utilize your gift card functionalities directly on their sites, providing a seamless experience for their customers.

<blockquote class="important">
  <strong>Important:</strong>
  
The Wix eCommerce Gift Cards service plugin is exposed here as the Wix eCommerce Gift Vouchers service plugin due to npm package limitations. Individual methods will refer to gift cards rather than gift vouchers.
</blockquote>

By integrating your service with Wix, you can facilitate key gift card operations such as balance retrieval, redemption, and voiding transactions. 
These operations are seamlessly integrated into the site's checkout page, enhancing the overall customer experience.

The integration process involves creating an app in the Wix App Market via the [Wix Dev Center](https://dev.wix.com/), 
and configuring the Gift Vouchers Provider service plugin [extension](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/about-extensions).

## Terminology
- **Redeem**: Applying a gift card balance to a purchase, including subtracting the applied value from the gift card balance.
- **Void**: Reversing a redeem action and returning the applied value to the gift card balance.


## Get started

Follow these steps to begin implementing your service plugin:

### Step 1| Choose a framework

You can implement this service plugin with the following [frameworks](https://dev.wix.com/docs/build-apps/get-started/overview/wix-s-development-frameworks):

+ **Wix CLI:** Learn how to [implement a service plugin with the CLI and the SDK](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/wix-cli/supported-extensions/backend-extensions/service-plugins/add-service-plugin-extensions-with-the-cli).
+ **Self-hosted:** Learn how to [implement a self-hosted service plugin with the SDK and the Wix Dev Center](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions-with-the-sdk).

### Step 2| Configure your service plugin

To configure and customize your plugin, you need to provide important information in the service plugin configuration file. You can [configure your plugin in the Wix Dev Center](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions-with-the-sdk#step-1--add-a-service-plugin-extension-to-your-app). For details, see [Gift Vouchers Provider Extension Configuration](https://dev.wix.com/docs/sdk/backend-modules/ecom/service-plugins/gift-vouchers-provider/extension-config).

### Step 3| Define handler functions

Use [`giftVouchersProvider.provideHandlers()`](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions-with-the-sdk#step-4--define-handler-functions) to define the following handler functions that implement your custom business logic. Make sure you define all required functions.

| Function                    | Required       |
|-----------------------------|----------------|
| [`getbalance()`](https://dev.wix.com/docs/sdk/backend-modules/ecom/service-plugins/gift-vouchers-provider/get-balance)    | Yes            |
| [`redeem()`](https://dev.wix.com/docs/sdk/backend-modules/ecom/service-plugins/gift-vouchers-provider/redeem)    | Yes            |
| [`_void()`](https://dev.wix.com/docs/sdk/backend-modules/ecom/service-plugins/gift-vouchers-provider/void)    | Yes            |

## Code examples

Below is an example for implementing the Gift Vouchers Provider service plugin in your code.

### CLI: Basic code structure

This is the basic code structure for implementing the Gift Vouchers Provider service plugin with the Wix CLI:

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

giftVouchersProvider.provideHandlers({
  getBalance: async (payload) => {

    const {request, metadata} = payload;

    // Add your logic here

  },
  redeem: async (payload) => {

    const {request, metadata} = payload;

    // Add your logic here

  },
   void: async (payload) => {

    const {request, metadata} = payload;

    // Add your logic here

  }    
});
  
```

### Self-hosted: Basic code structure

This is the basic code structure for implementing a self-hosted Gift Vouchers Provider service plugin:

```js
import { createClient } from '@wix/sdk';
import { giftVouchersProvider } from '@wix/ecom/service-plugins'

const wixClient = createClient({
  auth: {
    appId: <YOUR_APP_ID>,
    publicKey: <YOUR_APP_PUBLIC_KEY>
  },
  modules: { giftVouchersProvider }
});

wixClient.giftVouchersProvider.provideHandlers({
  getBalance: async (payload) => {

    const { request, metadata } = payload;

    // Add your logic here

  },
  redeem: async (payload) => {

    const { request, metadata } = payload;

    // Add your logic here

  },
  void: async (payload) => {

    const { request, metadata } = payload;

    // Add your logic here

  }    
});

// Implement a router to process all requests
express.post('/plugins-and-webhooks/*', (req, res) => {
  wixClient.process(req);
});
  
```

## See also

+ [About Service Plugin Extensions](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/service-plugins/about-service-plugin-extensions)
+ [Add a Service Plugin Extension With the CLI](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/wix-cli/supported-extensions/backend-extensions/service-plugins/add-service-plugin-extensions-with-the-cli)
+ [Add a Self-hosted Service Plugin With the SDK](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions-with-the-sdk)


ecom_gift-vouchers-provider

To configure and customize your service plugin, you need to provide important details in the `plugin.json` configuration file.

{ "deploymentUri": "https://my-gift-cards.com/" }


Gift Vouchers Provider Extension Config

Extension Config

GiftCardProviderConfig

Context

[ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) 3-letter currency code.

currency

string

An object that describes the identity that triggered this request.

identity

IdentificationData

instanceId

A string representing a language and region in the format of `"xx-XX"`. First 2 letters represent the language code according to ISO 639-1. This is followed by a dash "-", and then a by 2 capital letters representing the region according to ISO 3166-2. For example, `"en-US"`.

languages

A unique identifier of the request. You may print this ID to your logs to help with future debugging and easier correlation with Wix's logs.

requestId

metadata

request

GetBalanceRequest

App ID of the Gift Card provider. Deprecated.

appInstanceId

code

The physical location ID. Can be based on the Locations API or an external provider.

locationId

balance

number

currencyCode

External ID in the gift card provider's system.
Used for integration and tracking across different platforms.

externalId

Base URI where the endpoints are called. Wix eCommerce appends the endpoint path to the base URI. For example, to call the Get Balance endpoint at https://my-gift-cards.com/v1/balance, the base URI you provide here is https://my-gift-cards.com/.

deploymentUri

ID of a site visitor that has not logged in to the site.

anonymousVisitorId

appId

ID of a site visitor that has logged in to the site.

memberId

ID of a Wix user (site owner, contributor, etc.).

wixUserId

identityType

IdentityType

RedeemRequest

amount

Physical location ID. Can be based on the Locations API or an external provider.

Order ID the gift card transaction is applied to. Order details can be collected from eCommerce Search Orders.

Extension Config

redeem( )