Stape Store templates

Stape Store is a built-in NoSQL database designed specifically for server-side Google Tag Manager (sGTM) containers hosted on Stape. To interact with it directly, Stape provides a set of custom GTM templates:

• Stape Store Writer tag – lets you easily write or update data in Stape Store.
• Stape Store Lookup variable – allows you to retrieve stored data and put it into your sGTM variables for use across your tags, such as for authentication keys, transaction details, or user attributes.
• Stape Store reStore variable – a versatile template that simultaneously reads and writes data, making it ideal for stitching user profiles across multiple events. It fetches existing records using identifiers from incoming events, merges them with new data, and automatically creates new documents if no match is found, ensuring your session and customer information stays current and up-to-date.

Stape Store Writer tag

This is the primary template used to save data to the Stape Store. It allows you to save incoming event parameters, custom fields, or timestamps into specific database collections. This makes it an ideal solution for building a centralized repository of user interactions, managing API access tokens, or logging tracking data for future use. 

Here's how it works:

1. You specify a document key to update or overwrite an existing document.
2. You either manually define custom key-value pairs to store only specific, clean data, or you select to capture the entire tracking data sent by the client. This includes standard parameters (whatever is set to receive by your trigger that fires the tag) alongside client-specific metadata (such as GA4's x-ga- parameters).
3. When the tag fires, it automatically creates a new document with all information in a specified collection.

How to configure

1. Go to the Google Tag Manager and open your server container.

2. Open the Templates menu.

3. Click Search Gallery in the Tag Templates section.

4. Find the Stape Store Writer tag and click on the template.

5. Click Add to workspace.

6. Open the Tags menu and click New.

7. Click Tag Configuration and select the Stape Store Writer tag.

8. Open Stape Store Settings and enter the following:

• Stape Store Collection Name – this is the path of your collection where the documents will be stored. If this collection doesn't exist in the dashboard yet, the tag will create the collection automatically. If you won't set it, the default collection will be used. 
• Use the Stape Store database of a different container – if you manage multiple sGTM containers but need to maintain a single, centralized database for shared authentication keys, user IDs, configuration state, etc., you can set this to true. In this case you'll be asked to enter Stape Store Container API Key. For the instructions on how to find the key, read How to find Stape container API key?

9. Enter a Document ID – this is the document's name (document key) in the Stape Store dashboard. A common choice is Stape's User ID power-up header {{X-Stape-User-Id}}, or any other unique identifier.

10. Tick the applicable checkboxes:

• Add Event Data – controls whether the tag automatically includes all properties from the incoming sGTM event when saving data to your Stape Store database:
  • When enabled – the tag automatically retrieves the entire current event data and saves all of its keys and values to the database. This is a convenient way to capture everything from the event (e.g., page_location, client_id, user_data, and any custom incoming parameters) without having to map them manually. 
  • When disabled – the tag writes only the specific fields you manually define under the Custom Data section.

If Add Event Data is enabled, and you also map specific fields in the Custom Data table, any custom keys you define will overwrite the automatically captured event data.

• Merge document keys – controls how data is written when a document with the same key already exists in your Stape Store collection:
  • When enabled – the tag performs a partial update, meaning it only adds or updates the specific fields you're sending in the current event. Existing fields in the document that aren't part of this event remain unchanged. This is ideal for progressively building user profiles or session data. For example, adding an email address to a document that already contains a visitor ID without losing existing data.
  • When disabled – the tag performs a full overwrite. It replaces the entire document with the new data, meaning any pre-existing fields that aren't included in the current write will be deleted.
• Add Timestamp – this option will add the millisecond timestamp to the document.
• Skip null or undefined values – determines how fields containing empty, missing, or explicitly null/undefined data are handled when writing to your Stape Store database:
  • When enabled – any property or key in your data that has a value of null or undefined is completely excluded from the data sent to the database. This is the recommended behavior, as it keeps your database clean and avoids saving empty keys.
  • When disabled – these fields are written to the database document with explicit null values.

11. If you don't want to enable Add Event Data, then you need to add custom fields in the Custom Data section. You can manually enter a database Field name (will appear as field key in the dashboard) and associate it with a GTM variable in the Field value (will appear as field value in the dashboard).

12. Click Triggering and choose a trigger that fits your use case. For example, the tag will fire when a site visitor purchases something.

13. Click Save.

14. Go to the container's preview mode and perform actions (like making a purchase) on your website that will fire the tag.

15. Go to your Stape Store dashboard to see your new data.

Stape Store Lookup variable

This is the primary template used to retrieve and read data from the Stape Store without modifying any existing documents. It's ideal when you need to fetch previously saved user properties, configuration details, or attribution data to map directly into your tracking tags.

The variable allows you to target your Stape Store collection and look up data in one of two ways:

• You can target a specific document directly by entering its unique document key. This way you request to retrieve that exact document.
• You can filter your collection using query criteria. You can specify conditions (e.g., matching a user's email or phone number), and the variable returns the first matching document.

By default, the variable returns the entire retrieved document object. If you only need a specific property (e.g., a specific custom field like user_data.email), you can specify a key path in the variable's settings to extract and return only that field.

You'll get the returned value as a variable, which you can then pass to a tag. For example, if a user makes an action on your site that triggers an event (like a webhook) where their email or phone number is missing, you can look up their details using their client_id or session_id. You can then pass this retrieved user data to your Meta Conversions API to maximize match quality.

How to configure

1. Go to Google Tag Manager and open your server container.

2. Open the Templates menu.

3. Click Search Gallery in the Variable Templates section.

4. Find the Stape Store Lookup variable and click on the template.

5. Click Add to workspace.

6. Open the Variables menu and click New.

7. Click Variable Configuration and select Stape Store Lookup.

8. Open Stape Store Settings and enter the following:

• Stape Store Collection Name – this is the path of your collection where the documents will be searched. 
• Use the Stape Store database of a different container – if you want to look for data in another container, you can set this to true. In this case you'll be asked to enter Stape Store Container API Key. For the instructions on how to find the key, read How to find Stape container API key?

9. Select a Lookup Type:

• Document ID – this type is used to look up a single, specific document directly by specifying its unique document key (e.g., using a request header variable from the Stape User ID power-up {{X-Stape-User-Id}}).
• Query – this type is used to search the Stape Store collection for a document that meets custom query conditions. You need to define criteria by mapping document fields to values using a comparison operator. For example, email == {{Event Data - email}} If multiple documents match your query criteria, only the first matching document is returned and used by the variable.

10. Under More settings you can find Key Path. Regardless of the lookup type, you can use this field to retrieve a specific nested property within the document (e.g., event_location.country) instead of returning the entire document object.

11. For the best performance you can tick Store the result in cache. This prevents redundant network requests; if multiple tags (such as Google Analytics 4 or Facebook Conversions API) execute the same Stape Store lookup variable within a single event, the system makes only one network call. All subsequent tags will instantly retrieve the result from the cache, which minimizes server CPU usage and ensures fast container execution.

12. Under the Format Value section you can normalize values that are sent to your tags and reports. For more information read the Google documentation.

13. Click Save.

14. Open the Tags menu and select the tag you'd like to add your variable to.

15. Configure the event to match the type of data you're looking for with the variable you've created.

16. Click Save.

17. Go to the container's preview mode and perform actions (like making a purchase) on your website that will fire the tag. You should see your value in the Variables tab.

Stape Store reStore variable

The reStore variable is the most versatile template: it can write and retrieve data at the same time. It automatically fetches existing data that matches the user's identifiers while simultaneously saving any new information from the event. This makes it ideal for stitching together a user's profile across multiple events.

The variable collects user identifiers from the incoming event (such as email, phone, client ID, or first-party cookies) and checks the Stape Store for a matching document that already has one of the identifiers. It then processes the data as follows:

1. Merges incoming data with stored data. If a field (e.g., phone) is missing from the incoming request but exists in the Stape Store, the stored value is used. If the incoming request has a field the Stape Store lacks (or has a different value) the request's value is written to the Stape Store.
2. If no match is found for the user, it automatically creates a new document in the Stape Store, laying the foundation for future events.
3. The variable returns the resulting “restored” data and it can be easily mapped into your tags.

Here's a quick real world example:

1. A user signs up for a newsletter or logs in. Your sGTM container receives their email (e.g., user@example.com) along with a first-party cookie (_ga). By configuring the reStore variable to run on this event, you can define the _ga cookie as the user identifier and map the email address as data. When the event triggers, reStore automatically saves this association in the Stape Store.
2. Two days later, the same user returns through an ad and browses product pages (view_item events). Although they remain anonymous and don't submit forms or log in, their browser still passes the first-party tracking cookie.
3. When the view_item event triggers, the reStore variable executes. It uses the active user's tracking cookie to query the Stape Store and instantly locates the document created during their initial login. The variable automatically retrieves the stored email address and makes it available as a variable within your sGTM container.
4. You can map this reStore variable directly to your Meta Conversions API tag's User Data fields. This ensures Meta receives the user's email alongside the view_item event, even during anonymous sessions. This significantly boosts your Event Match Quality (EMQ) score and enhances ad performance.

How to configure

1. Go to Google Tag Manager and open your server container.

2. Open the Templates menu.

3. Click Search Gallery in the Variable Templates section.

4. Find the Stape Store reStore variable and click on the template.

5. Click Add to workspace.

6. Open the Variables menu and click New.

7. Click Variable Configuration and select Stape Store reStore.

8. Open Stape Store Settings and enter the following:

• Stape Store Collection Name – this is the path of your collection where the documents will be stored or read. If this collection doesn't exist in the dashboard yet, the variable will create the collection automatically. If you won't set it, the default collection will be used. 
• Use the Stape Store database of a different container – if you need to read or write to another container, you can set this to true. In this case you'll be asked to enter Stape Store Container API Key. For the instructions on how to find the key, read How to find Stape container API Key?

9. You can disable writing entirely so the variable only retrieves data by identifiers. To do so tick the Only restore data checkbox. This is useful when you simply want to recover session or customer data without modifying the Stape Store.

10 The List of identifiers section is used to search for and match user data in your Stape Store database. To maximize matching rates, you can add multiple identifiers in case some identifiers fail to fetch. Enter the following:

• Name – the unique field key name in the Stape Store document to search for (e.g., user_id, client_id, email, phone_number).
• Value – value of the field key (e.g. {{X-Stape-User-Id}} if you have enabled the User ID power-up). 

11. In the List of data that needs to be restored section specify the parameters you want to retrieve from the matched document, for example, city. If you want to override the existing document field value, enter a GTM variable referencing the incoming value, e.g., {{ed - city}}. For example, you want to save and retrieve a user's city, but override it if they fill out a form with a new location. If you've ticked Only restore data, then the value will be ignored and not written in Stape Store.

12. Under the Format Value section you can normalize values that are sent to your tags and reports. For more information read the Google documentation.

13. Click Save.

14. Open the Tags menu and select the tag you'd like to add your variable to.

15. Configure the event to match the type of data you're looking for with the variable you've created.

16. Click Save.

17. Go to the container's preview mode and perform actions (like making a purchase) on your website that will fire the tag. You should see your value in the Variables tab.

18. If you left the Only restore data checkbox unchecked, the same value should appear in a Stape Store document with a name that starts as restor_. For example, this particular user ID didn't exist in the collection, so you got a new document with the city.

When you filled in the purchase form with a new city, the same document got updated with this city: