Tokengating lets merchants offer eligible token holders exclusive access to products and discounts. For example, a merchant can give customers who hold their token a 25%-off discount. Customers can unlock the discount by connecting their wallet to prove that they own the token. Merchants can use tokengating to build loyalty and reward mechanisms for their communities and customers.
How tokengating worksAnchor link to section titled "How tokengating works"
A tokengate is a definition of token requirements that determines who can unlock it. Tokengates consist of a segment and a reaction.
- A segment defines which tokenholders can pass the tokengate by verifying their ownership against blockchain data.
- A reaction is the outcome of passing a gate, such as a discount for a specific product.
A tokengating app guides merchants through the gate configuration process, which includes defining the gate requirements and corresponding reactions. The app also evaluates the configured tokengates, and presents them to customers on the storefront alongside a wallet connection experience.
For example, a merchant might offer an exclusive discount to token holders of smart contract
GateConfiguration is the object that stores the merchant-defined requirements and reactions. The
GateSubject then binds that configuration to a
Product. The same
GateConfiguration can be used across multiple
The following diagram illustrates a high-level flow of a tokengating app that's configuring an exclusive product discount tokengate:
Tokengating app requirementsAnchor link to section titled "Tokengating app requirements"
Tokengating apps on Shopify enable merchants to gate access to products, promotions, and content based on the contents of a customer’s Web3 wallet. All gated variants and all gated line items within completed orders must have a programmatic representation of their gated status using metafields.
All tokengating apps must have a programmatic representation of their gated status using metafields with the following specifications:
Tokengating order metafieldsAnchor link to section titled "Tokengating order metafields"
Any orders that contain line items that are either added or discounted as a result of a buyer successfully passing a gate-check must be identified by adding the line item IDs to the
Order object through the use of the following specified metafields:
Tokengating product metafieldsAnchor link to section titled "Tokengating product metafields"
Any products that contain one or more gated variants must list the gated variant IDs within the
Product object using product metafields as follows:
Tokengate app responsibilitiesAnchor link to section titled "Tokengate app responsibilities"
A tokengating app has three main responsibilities.
|Responsibility||Description||What to use|
|Configuration||How the app is used to configure the merchant-defined gate and gate requirements. For example, one or more tokens from a specified NFT collection can be made a requirement for offering an exclusive discount for the subjects of the gate that's bound to a product. Your gate requirements can be for any chain or any level of granularity, such as specific traits or IDs. Your app is responsible for evaluating whether customers meet the requirements of any gate that it configures.||Gates API, Polaris, App Bridge|
||Gates API, Theme App Extension or custom storefront|
|Evaluation||How the app checks the customers's wallet contents against the
||Gates API, Theme App Extension or custom storefront, Ajax API, Shopify Functions|
ConfigurationAnchor link to section titled "Configuration"
A tokengating app is responsible for storing the merchant's gate configuration, including the requirements and reaction, in the
GateConfiguration model using the
gateConfigurationCreate mutation. The configuration is then bound to a product through the
GateSubject model using the
GateConfiguration can only be updated or deleted by the app that created it. This is done using the
gateConfigurationDelete mutations respectively.
GateSubject can only be updated by the app that created it using the
PresentationAnchor link to section titled "Presentation"
The presentation layer has 3 main responsibilities on the product details page:
- Display the gate requirements
- Display the gate status
- Connect and verify the wallet
A tokengating app is responsible for evaluating the wallet's contents against the
GateConfiguration. You can enforce the evaluation results through Shopify Functions, which enables developers to write code that's triggered in the merchant's checkout process.
Certain Function APIs enable the exclusive discounts reaction, such as the Product Discount API or the Cart and Checkout Validation API. These Functions are automatically called by Shopify when the customer reaches a certain point in their purchase journey, such as adding a product to cart or attempting to complete checkout.
Additional context can be written to cart attributes using the Ajax API to inform your Function on whether or not to apply the gate's reaction.
Custom storefrontsAnchor link to section titled "Custom storefronts"
A tokengated custom storefront has the following responsibilities:
|Responsibility||Description||What to use|
|Read gates on products||Read gates bound to products. The gates bound to the products should have been assigned using the app you created in the build a tokengating app tutorial series.||Gates API|
|Display gate reaction and requirements||Parse the
|Connect and verify customer's wallet||Use the
|Evaluate wallet contents against the
||Use the wallet data stored in the cookie and a third-party service such as Alchemy to validate the wallet's contents against the
||Gates API, third-party service blockchain querying service|
|Display the unlocking status||Use the evaluation result to display your customer's unlocking tokens in the
|Update cart attributes||When a gate is unlocked, update the cart attributes for the customer so the Shopify Function you created in the in the build a tokengating app tutorial series applies the automatic discount.||GraphQL Storefront API|
Get startedAnchor link to section titled "Get started"
Developer tools and resourcesAnchor link to section titled "Developer tools and resources"
Tokengating UX guidelines
Best practices for designing merchant and customer tokengating experiences.
Integrate Tokengate and Wallet Connect components into your app for seamless storefront tokengating.
Gates GraphQL Admin API
Check out the GraphQL Admin API reference to learn more about the Gate object.
LimitationsAnchor link to section titled "Limitations"
Productas the subject type.
- Online store cart attributes can be updated only with the Ajax Cart API.
gatesproperty on the Liquid
productobject is available to Partners by request for testing purposes. To get access, contact Partner Support with the development
.myshopify.comstore domain that you'd like to test with.