Ad events

Retail events

Models

Collect API

Connector Schema Management

Connector Management​

Connect API

Organisation

User

Permissions

Roles

Invitations

Media API

Catalogs

Products

Place

Override

Search API

For Zitcha to create Facebook Ads on behalf of your business, your assets (Business Page, Ad Account, Instagram & Catalogs) must be shared with the Zitcha Facebook Business Manager and granted ‘Full Control’. *Please only share your main Business Page (usually at a national level).

To do this please follow the below steps:

Select 'Give a partner access to your assets.'

On this screen, you can share multiple assets.
a. Choose the asset you wish to share in the first column 
(Page, Ad Account, Instagram & Catalogs.)
b. Assign the Admin role/Full control for your partner in the third column. 
c. Repeat these steps until you've chosen roles for all of the assets you want to assign.

Steps to provide Zitcha with Google & YouTube Access

In order for Zitcha to create Google and YouTube ads on behalf of your business, you must first share access to your Google Ad Account and staging environment where applicable.

To do this please provide your Google Ad Account ID to the Zitcha team, the Zitcha team will then send a request from the Zitcha Manager Account 805-599-5631 to your Google Ad Account.

Once the request has been sent by Zitcha all admins on your Google Ad Account will receive an email with a link to approve the request.

You can also approve the request via the below process.

Sign in to your Google Ads manager account.

Click the Tools and settings icon, then under 'Setup', click Access and security.

Select the Managers tab. Under 'Link request', you’ll find a list of manager accounts that have requested to link to your account.

In order for Zitcha to create Google shopping ads the below users will need to be added to your Google Merchant Center with standard access (as a minimum). A Content API Key will also need to be generated so your products can pull through from Google Merchant Center to the Zitcha Platform.

please contact your solutions lead for these email addresses.

To grant access to the users, follow these steps:

Click the tools icon, then select Account access under the “Settings” menu.

Enter the email address of the person you want to invite.

On the next page, select standard as the access level, and email preferences for that user.

Click on “+” to create the API key, this will automatically download the credentials as a .js

Select “Add user” for the newly created Service User.

Update the Service User access to “Standard” and “Report manager” user access

Share the .json file with the Zitcha team

In order for Zitcha to run YouTube Bumper and Short Form Video Ads, please grant the Zitcha email (please contact your solutions lead for the relevant email address) 'Editor' access to to your YouTube Channel to connect the Zitcha Access Token.

To add the above user follow these steps:

Click Invite and enter the email address of the person you’d like to invite.

Credit Lines: Single line of credit in the Facebook account is required.

Facebook Feeds are required for product related campaigns used in Meta.

Facebook Products that aren't split by brand may delay onboarding

Facebook & Google Audiences which are not setup may delay onboarding

Keep this guide at hand for a smooth integration. We're here to help every step of the way!

This offsite guide ensures a smooth integration with all offsite assets, covering all essential steps from account setup to understanding integration challenges for a successful partnership.

Offsite Integration Guide

Channels and Features of ALL Potential Integration Methods


Steps to Lowest Technical Lift Integration Method

Grant Zitcha access to Meta Product Catalogs

Grant Zitcha access to Google Tag Manager

Steps to provide Zitcha with META Catalogs Access

For Zitcha to create Facebook and Sponsored Product Ads on behalf of your business, your assets (Business Page, Ad Account, Instagram & Catalogs) must be shared with the Zitcha Facebook Business Manager and granted ‘Full Control’. *Please only share your main Business Page (usually at a national level).

Select Give a partner access to your assets.

On this screen, you can add partners to multiple assets.a. Choose a type of asset in the first column (Page, Ad Account, Instagram & Catalogs.)b. Select the assets you want to add your partner to in the second column.c. Assign the Admin role/Full control for your partner in the third column. Repeat these steps until you've chosen roles for all of the assets you want to assign.

Steps to provide Zitcha with Google Tag Manager Access

In order for Zitcha to generate and run ads on your website the below users will require standard access to your Google Tag Manager on your production site. Additionally, please grant the same Zitcha users ‘admin’ access to the GTM account linked to your staging environment:

In the Account column, select User Management.

Click Invite. Each invited user will receive an invitation to use the container.

This Onsite guide ensures a smooth integration with all offsite assets, covering all essential steps from account setup to understanding integration challenges for a successful partnership.

Onsite Integration Guide

The Zitcha Search API is designed to enhance product search capabilities, offering a comprehensive way to search, filter, and sort through products based on various attributes. Below is a detailed overview of the product fields, the type of data stored in each, and how these fields interact with the search endpoint and query method.

The product data schema is designed to be flexible and versatile, allowing for a wide range of product types and attributes. The schema is based on Meta’s Data Catalog and includes the following fields:

: An int32 integer. This field can be used to rank products in search results by default, which is useful for prioritising products based on metrics like popularity or relevance.

: An int32 integer. This identifies the specific store or location associated with the product, allowing for filtering and sorting by store.

: A string. Acts as a unique identifier for each product, critical for search operations and unique product retrieval.

: A string. The name or title of the product, is searchable and can be used to display in search results.

: A string. Offers a detailed description of the product, useful for full-text search to match on product features or specifications.

: A string. Indicates the product's price, including currency symbols or additional text, making it versatile for various formats but may require parsing for numerical comparison.

: A string. URL pointing to the product's image, useful for visual representation in search results.

: A string. A direct URL to the product's page on the website, enabling direct access to the product's detailed page.

: A string. Shows whether the product is in stock, out of stock, or available for pre-order, essential for filtering based on availability.

: A string. Describes categories or types the product belongs to, allowing for categorization in search.

: A string with faceting enabled. Specifies the product's condition (new, used, refurbished, etc.), useful for filtering search results based on condition.

: A string with faceting enabled. The brand or manufacturer of the product, important for brand-specific searches.

: A string with faceting enabled. Describes the product's color(s), offering a way to filter search results by color.

: A string. The size of the product, which could vary in meaning (e.g., clothing size, bottle size), important for searches requiring size specificity.

: A float. Represents a bidding amount for sponsored products or ads, influencing their position in search results based on the bid amount.

The Zitcha Search API provides a specific endpoint for a retail domain for querying these product fields, allowing for a flexible and powerful search experience. The endpoint supports complex queries against one or more text fields (e.g., title, description) and allows filtering against numerical or facet fields (e.g., store_id, brand, condition). The results can be sorted and faceted to provide a highly customised search experience.

To search for products, the API could be queried with parameters like q for the search query, query_by to specify which fields to search against, filter_by to apply filters such as availability or store_id, and sort_by to define the order of the results, using _text_match

,bidto prioritise by text match quality and bid amount for sponsored products.

The search query method involves sending these parameters to the Zitcha Search API's search endpoint will look like this:

GET /api/products/search/?q=panadol&query_by=brand:_text_match

,bid&query_by=title,description,bid&page=1

The exact syntax for the query would depend on the implementation details of the Zitcha Search API and the programming language or framework being used to make the request.

This approach ensures that users can find products that closely match their search terms while also allowing brands to promote certain products through bidding.

Search Request Modification: Modify the search request logic to include calls to both the existing search API and the Zitcha Search API. This dual request approach ensures that both regular and sponsored products are retrieved during a search query.

 Implement logic to merge the results from the existing search API and the Zitcha Search API. Since the Zitcha Search API can return either just the promoted product IDs or the entire product details, ensure this logic can handle both response types seamlessly.

 Apply a sorting mechanism that incorporates the bid value for sponsored products. Use the sort_by parameter with the value "_text_match

,bid" to prioritize sponsored products in the search results based on their bid amounts.

Ensure the front-end logic can differentiate between regular and sponsored products, perhaps by highlighting sponsored products or marking them with a "Sponsored" label to maintain user transparency.

Pagination and Filters: Adjust the pagination and filter logic to accommodate the inclusion of sponsored products in the search results. This may involve recalculating the number of pages or adjusting filters to include or exclude sponsored products as needed.

Testing and Optimization: Conduct thorough testing to ensure that sponsored products are correctly integrated and displayed as expected. This includes testing for various search queries, filter combinations, and pagination scenarios. Optimisation may be required to ensure the performance of the search feature remains high.

When a search query is initiated, make simultaneous requests to the existing search API and the Zitcha Search API.

For the Zitcha Search API, construct the search request similar to the existing search but include the sort_by parameter with "_text_match

Parse the response from the Zitcha Search API to extract either the product IDs or the full product details of sponsored products.

If only product IDs are returned, retrieve the full product details from the existing product database or API as needed.

Merge the results from the existing search API and the Zitcha Search API. Ensure sponsored products are correctly interleaved within the search results based on the sort_by logic.

Sponsored products with higher bids should appear higher in the search results, followed by regular products sorted by relevance to the search query.

Update the UI to distinguish sponsored products from regular products. This could involve adding a special badge, changing the background color, or using any other visual indicator.

Ensure that the UI updates dynamically to reflect the correct mixture of sponsored and regular products based on the search query and filters applied.

Test the integrated search feature extensively to ensure that sponsored products are displayed correctly and do not disrupt the user experience.

Monitor the performance impact of adding sponsored products to the search results and optimize as necessary.

Monitoring and Analytics: Implement tracking for interactions with sponsored products to gauge their performance and adjust bidding strategies accordingly. The recommended approach on client-side is to implement Zitcha's Collect API to track user interactions with sponsored products.

Feedback Loop: Establish a feedback mechanism to refine the display and ranking of sponsored products based on user engagement and conversion rates.

By following these implementation notes, the engineering team can effectively integrate sponsored products into the pharmacy's website search feature, enhancing the visibility of sponsored products and the overall search experience for users.

Leveraging the Zitcha Search API for Onsite Retail Media Experiences.

Building Templated Audiences

To archive an order in Zitcha, follow these steps:

 button from the Menu Bar to navigate to the Orders page.

Open the specific order you want to archive.

On the upper-right-hand side of the Order page, click the drop-down button and select 

A confirmation alert will appear. Click the 

To view or restore archived orders, go to the Orders page and click the 

Following these steps will allow you to effectively manage and organize your orders in Zitcha.

Archive orders in Zitcha by selecting the Archive option from the drop-down menu and manage archived orders via the Archived Orders button.

How can I archive an Order?

To share a Custom Audience with your partnering Suppliers on Zitcha, follow these steps:

Log in to your Zitcha account and click on the 

 tab, click the Supplier you'd like to share a Custom Audience with. This will pull up the settings for that Supplier.

Select the Platform you’d like to share the audience from. Then select the audiences you’d like to share.

The selected Custom Audiences will now be available for your partnering Supplier.

Easily share Custom Audiences with your suppliers on Zitcha by selecting the audience in Supplier Settings and saving the changes.

Sharing Custom Audiences with a Supplier

Follow the steps below to share Facebook Custom Audiences with Zitcha:

From the drop-down on the top-right-hand side, select the Ad Account that’s housing the audience you’d like to share.

Select or enter the ID of the ad account that's linked to your Zitcha account.

 to acknowledge the responsibilities stated in the Custom Audiences Terms.

If you'd like to confirm everything has been linked correctly, please speak to our team.

Easily share Facebook Custom Audiences with Zitcha by logging into Facebook Business Manager, selecting your audience, and following the sharing steps provided.

How do I share Facebook Custom Audiences with Zitcha?

Zitcha provides a Product Update Endpoint that allows retailers to push their product catalog information to Zitcha's product feed. This guide will walk you through the steps to use the endpoint to update and add products to the Zitcha product feed.

Before you start using the Product Update Endpoint, ensure you have the following:

An API key or authentication credentials to access the Zitcha API.

The necessary libraries or tools to make HTTP requests to the API (e.g., Python with the 

You'll find implementation examples in Bash, Python, Go, Node.js, Ruby, CSharp, PHP, Java and PowerShell at our Product Update API documentation. The examples use dummy data to demonstrate how to structure the request. You can use the examples as a reference to build your own request.

To update or add a product to the Zitcha product feed, you need to send a POST request to the Product Update Endpoint with the relevant product information.

 variable with the actual information of the product you want to update or add. Let's break down the payload fields:

: The name of the event and corresponding schema, which should be set to "product_update".

: The version of the event and corresponding schema, which should be set to "1-0-0".

: A list containing a dictionary representing the product identifier, including its type, value, and system (e.g., product ID, SKU, etc.).

: An optional field representing the parent product's identifier, useful for linking variants to their parent product.

: A list of image URLs associated with the product.

: A list of dictionaries, each representing an attribute of the product, including its name, type, and value.

: A list of lists, where each inner list represents the category path of the product.

Upon making a product update request, you will receive a response from the Zitcha API. The response will indicate whether the product update was successful or if there were any errors. It's essential to handle the response appropriately and handle any potential errors or retries if needed.

The response will likely contain an HTTP status code, such as 200 for a successful request, 400 for a bad request, or 500 for server errors. Additionally, the response may include a JSON payload with more detailed information about the request's outcome.

By following this guide, you should now understand how to use the Zitcha Product Update Endpoint to push your product catalog information to the Zitcha product feed. If you encounter any issues, refer to the API documentation or reach out to Zitcha's support for further assistance.

Integration

Articles

Offsite Integration Guide

Onsite Integration Guide

Sponsored Product Integration Guide

Configuration Instructions for In-store Screens Deployment

Building Templated Audiences

How can I archive an Order?

Sharing Custom Audiences with a Supplier

How do I share Facebook Custom Audiences with Zitcha?

Native Product Feed

integration-topic - Articles Page

Integration

Articles

Offsite Integration Guide

Onsite Integration Guide

Sponsored Product Integration Guide

Configuration Instructions for In-store Screens Deployment

Building Templated Audiences

How can I archive an Order?

Sharing Custom Audiences with a Supplier

How do I share Facebook Custom Audiences with Zitcha?

Native Product Feed