Gift Card system architecture

Our Gift Card system provides stores with the flexibility to plug in multiple gift card providers and offer these different options to their customers. This is possible thanks to a layer of interaction between gift card providers and the store, which we call Gift Card Hub, and the communication standards defined in our Gift Card Provider Protocol.


This article presents an overview of this architecture, so you understand its building blocks and how they interact with each other. We will also explain the purpose of the Gift Card API and the Gift Card Hub API and how they should be used.


Our native gift card provider is available to all stores

If you do not need to integrate an external solution, remember you can set up and manage gift cards natively in your admin panel or using our Gift Card API.

Gift Card Hub

This is the system that provides a layer of interaction between gift card providers and VTEX stores. It is used to manage multiple gift card providers connected to a store, both native and external, using a single interface - the Gift Card Hub API.

Gift Card Provider Protocol

This is the protocol defining the communication standards gift card providers must follow in their integration with Gift Card Hub. The Gift Card Provider Protocol section of our API Reference provides details on the eleven endpoints that should be exposed by the middleware connecting the external gift card provider to VTEX.

VTEX Gift Card Provider

Our native gift card provider is bundled into your VTEX store, and Gift Card API is the implementation of the Gift Card Provider Protocol for it. It can be used to manage VTEX gift cards directly - although Gift Card Hub API provides the same functionality in a more generic abstraction layer.


Our native gift card provider does not fully implement our protocol

The VtexGiftCard provider was built from a legacy system, created before our Gift Card system architecture evolved to the Gift Card Hub model. As such, it should not be considered a reference implementation of the Gift Card Provider Protocol.

Did this page help you?