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)

# About the Wix eCommerce Gift Cards Service Plugin

The Wix eCommerce Gift Cards 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.

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](fallback::https://dev.wix.com/), and configuring the Gift Cards Provider service plugin [extension](fallback::https://dev.wix.com/docs/build-apps/develop-your-app/extensions/about-extensions).

## Use cases
- [Provide gift card data in response to a Get Balance request](fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/service-plugins/gift-cards-service-plugin/sample-flows#retrieve-a-gift-card)
- [Redeem a gift card in response to a Redeem request](fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/service-plugins/gift-cards-service-plugin/sample-flows#redeem-a-gift-card)
- [Void a transaction in response to a Void request](fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/service-plugins/gift-cards-service-plugin/sample-flows#void-a-transaction)

## Before you begin

- It's important to ensure that your implementation of the gift cards provider service plugin endpoints adheres to the provided specifications.
- Implementation of this Service Plugin is dependent on configuration of the eCommerce Gift Cards Provider extension in the [Dev Center](fallback::https://dev.wix.com/dc3/my-apps/):

   | Name             | Type   | Description                                                                                                          |
   | ---------------- | ------ | -------------------------------------------------------------------------------------------------------------------- |
   | `deploymentUri`  | string | Required. Base URI where the endpoints are called. Wix eCommerce appends the endpoint path to the base URI. For example, to call the Balance Retrieval endpoint at `https://my-gift-cards.com/v1/getBalance`, the base URI you provide here is `https://my-gift-cards.com/`. |
   | `componentName`  | string | Unique name for this component, that appears only in the Dev Center. |
- Configuration setup: When a site owner installs and authorizes your app to provide gift card operations, Wix will send a JSON Web Token (JWT) with an instance ID to your deployment URI + endpoint path. The app should collect the JWT, decode it, and store the resulting instance ID.  
   For example, the token in this request:

   ```curl
   $ curl -X POST https://ext-server.com/wix-spi/account-ids
   -H 'Content-Type: plain/text'
   -d 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpbnN0YW5jZUlkIjoiMDQ0NjY3ZjQtYzEzZi00NmMyLTg1MDYtZGU5ZTQyMjkzODk2In0.fxedHrnHUFi6V-   S5OH8gL-pY4STxFWZHjj-xo9QUwQY'
   ```

   Decodes into:
   ```json
   { "instanceId": "044667f4-c13f-46c2-8506-de9e42293896" }
   ```

## 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.


# Sample Flow

This article shares some typical use cases you can support, as well as an example flow that supports each use case. You're certainly not limited to these use cases, but they can be a helpful jumping off point as you plan your implementation.


## Retrieve a Gift Card Balance

When a customer begins the checkout flow on a Wix site for a purchase of $100 USD, and they have a gift card balance of $50 USD:
1. A customer chooses to use their gift card to pay for their $100 purchase, enters the gift card code in the designated slot, and clicks **Apply**.
2. The Wix site sends a [Get Balance](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::77439d6f-6696-4b55-bc50-8df0aca133dbslug::get-balance*fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/gift-cards/gift-cards-service-plugin/get-balance) request to your app with the `code`, **`app_instance_id`**, and optionally `location_id`.

   Example request:
   ```json
   {
      "code": "GIFT-CARD-CODE-123",
      "app_instance_id": "044667f4-c13f-46c2-8506-de9e42293896",
      "location_id": "store-location-001"
   }
   ```

3. Your app processes the request and returns the current balance and currency of the customer's gift card.

   Example response:
   ```json
   {
      "balance": 50.00,
      "currency_code": "USD"
   }
   ```
    
4. The Wix site displays the balance to the customer as part of the price summary at Checkout, as though the gift card is used for the purchase.


## Redeem a Gift Card
Continuing the example from above, the customer continues with the checkout flow:
1. The customer decides to use their gift card balance toward their purchase, enters credit card details to cover the remaining $50, and clicks **Place Order**.
2. The Wix site sends a [Redeem Gift Card](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::77439d6f-6696-4b55-bc50-8df0aca133dbslug::redeem*fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/gift-cards/gift-cards-service-plugin/redeem) request to your app with the `code`, `amount`, `order_id`, `currency_code`, and optionally `location_id`.

   Example request:
   ```json
   {
      "code": "GIFT-CARD-CODE-123",
      "app_instance_id": "044667f4-c13f-46c2-8506-de9e42293896",
      "amount": 50.00,
      "order_id": "00000000-0000-0000-0000-000000000001",
      "currency_code": "USD",
      "location_id": "store-location-001"
   }
   ```

3. Your app processes the request and returns the remaining balance, currency, and transaction ID of the redeem operation.

   Example response:
   ```json
   {
      "remaining_balance": 0.00,
      "currency_code": "USD",
      "transaction_id": "00000000-0000-0000-0000-000000000001"
   }
   ```

4. The customer's payment is processed, and they receive a confirmation showing that $50 has been deducted from his gift card, leaving a balance of $0.

## Void a Transaction
Continuing the example from above, the customer chooses to complete the checkout flow:
1. After the gift card was redeemed, the customer's credit card payment is processed, and **fails**.
2. The Wix site sends a [Void](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::77439d6f-6696-4b55-bc50-8df0aca133dbslug::void*fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/gift-cards/gift-cards-service-plugin/void) request to your app with the `transaction_id`, and optionally `location_id`, in order to restore the redeemed amount to the gift card balance.

   Example request:
   ```json
   {
      "transaction_id": "00000000-0000-0000-0000-000000000001",
      "app_instance_id": "044667f4-c13f-46c2-8506-de9e42293896",
      "location_id": "store-location-001"
   }
   ```

3. Your app processes the request and returns the remaining balance and currency of the gift card after the void operation.

   Example response:
   ```json
   {
     "remaining_balance": 50.00,
     "currency_code": "USD"
   }
   ```


value

StringValue

this message is not directly used by any service,
it exists to describe the expected parameters that SHOULD be provided to invoked Velo methods as part of open-platform.
e.g. SPIs, event-handlers, etc..
NOTE: this context object MUST be provided as the last argument in each Velo method signature.

Example:
```typescript
export function wixStores_onOrderCanceled({ event, metadata }: OrderCanceledEvent) {
...
}
```

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

currency

An object that describes the identity that triggered this request.

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

Context

identityType

IdentificationData

IdentityType

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

App instance ID of the Gift Card provider.

appInstanceId

code

locationId

GetBalanceRequest

balance

currencyCode

GetBalanceResponse

deploymentUri

GiftCardProviderConfig

GiftCardProviderEntity

amount

Order ID the gift card transaction is applied to.

orderId

RedeemRequest

Remaining balance on the Gift Card after the redemption.

remainingBalance

transactionId

RedeemResponse

VoidRequest

Remaining balance on the Gift Card after voiding the transaction.

VoidResponse

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.

GiftCardNotFound

GiftCardDisabled

GiftCardExpired

The data payload will include the following object as an encoded JWT. For the purposes of this example, we show the request and response objects decoded.

Get Balance

GetBalance

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.

InsufficientFunds

AlreadyRedeemed

CurrencyNotSupported

Redeem Gift Card

Redeem

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.