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 Studio workspace, and configuring the Gift Cards Provider service plugin extension.

Use cases

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 app dashboard:

    NameTypeDescription
    deploymentUristringRequired. 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/.
    componentNamestringUnique name for this component, that appears only in the app dashboard.
  • 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:

    Copy
    $ 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:

    Copy
    { "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.
Did this help?

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 request to your app with the code, app_instance_id, and optionally location_id.

    Example request:

    Copy
    { "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:

    Copy
    { "balance": 50.0, "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 request to your app with the code, amount, order_id, currency_code, and optionally location_id.

    Example request:

    Copy
    { "code": "GIFT-CARD-CODE-123", "app_instance_id": "044667f4-c13f-46c2-8506-de9e42293896", "amount": 50.0, "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:

    Copy
    { "remaining_balance": 0.0, "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 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:

    Copy
    { "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:

    Copy
    { "remaining_balance": 50.0, "currency_code": "USD" }
Did this help?

POST

Get Balance


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

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.

Endpoint
POST
{DEPLOYMENT-URI}/v1/balance
Body Params
codestringminLength 8maxLength 20

Gift card code.


appInstanceIdstringdeprecatedformat GUID

App ID of the Gift Card provider. Deprecated.


locationIdstringmaxLength 50

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

Response Object
balancenumberminimum 0maximum 999999999.99

Current balance.


currencyCodestringformat CURRENCY

Currency code.


externalIdstringminLength 1maxLength 50

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

Get Balance

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.

Request
cURL
curl -X POST \ 'http://provider.example.com/v1/balance' \ -H 'user-agent: Wix' \ -H 'accept-encoding: gzip, deflate' \ -H 'content-type: text/plain; charset=utf-8' \ -d '{ "code": "GIFT-CARD-CODE-123", "appInstanceId": "044667f4-c13f-46c2-8506-de9e42293896", }'
Response
JSON
{ "balance": 100.0, "currencyCode": "USD" }
Errors
GiftCardNotFoundobjectstatus code: 404
GiftCardDisabledobjectstatus code: 428
GiftCardExpiredobjectstatus code: 428
Did this help?

POST

Redeem


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

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.

Endpoint
POST
{DEPLOYMENT-URI}/v1/redeem
Body Params
codestringminLength 8maxLength 20

Gift card code.


appInstanceIdstringdeprecatedformat GUID

App ID of the Gift Card provider. Deprecated.


amountnumberminimum 0maximum 999999999.99

Amount to redeem from the gift card.


orderIdstringformat GUID

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


currencyCodestringformat CURRENCY

Currency code.


locationIdstringmaxLength 50

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

Response Object
remainingBalancenumberminimum 0maximum 999999999.99

Remaining balance on the Gift Card after the redemption.


currencyCodestringformat CURRENCY

Currency code.


transactionIdstringminLength 1maxLength 100

Transaction ID.

Redeem Gift Card

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.

Request
cURL
curl -X POST \ 'http://provider.example.com/v1/redeem' \ -H 'user-agent: Wix' \ -H 'accept-encoding: gzip, deflate' \ -H 'content-type: text/plain; charset=utf-8' \ -d '{ "code": "GIFT-CARD-CODE-123", "appInstanceId":"044667f4-c13f-46c2-8506-de9e42293896", "amount": 20.00, "currencyCode": "USD", "orderId": "00000000-0000-0000-0000-000000000001" }'
Response
JSON
{ "remainingBalance": 80.00, "currencyCode": "USD", "transactionId: "00000000-0000-0000-0000-000000000001" }
Errors
GiftCardNotFoundobjectstatus code: 404
GiftCardDisabledobjectstatus code: 428
GiftCardExpiredobjectstatus code: 428
InsufficientFundsobjectstatus code: 428
AlreadyRedeemedobjectstatus code: 409
CurrencyNotSupportedobjectstatus code: 400
Did this help?

POST

Void


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

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.

Endpoint
POST
{DEPLOYMENT-URI}/v1/void
Body Params
appInstanceIdstringdeprecatedformat GUID

App ID of the Gift Card provider. Deprecated.


transactionIdstringminLength 1maxLength 100

Transaction ID to void.


locationIdstringmaxLength 50

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

Response Object
remainingBalancenumberminimum 0maximum 999999999.99

Remaining balance on the Gift Card after voiding the transaction.


currencyCodestringformat CURRENCY

Currency code.

Void Transaction

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.

Request
cURL
curl -X POST \ 'http://provider.example.com/v1/void' \ -H 'user-agent: Wix' \ -H 'accept-encoding: gzip, deflate' \ -H 'content-type: text/plain; charset=utf-8' \ -d '{ "transactionId": "00000000-0000-0000-0000-000000000001" }'
Response
JSON
{ "remainingBalance": 100.0, "currencyCode": "USD" }
Errors
TransactionNotFoundobjectstatus code: 404
AlreadyVoidedobjectstatus code: 409
GiftCardDisabledobjectstatus code: 428
GiftCardExpiredobjectstatus code: 428
Did this help?