Manage product access

IMPORTANT: You're on this page because you're considering granting advertisers access to your data. Before you begin, make sure you have uploaded your product catalog, along with your product and event data. This step is required only if you plan to monetize your data and enable advertisers to use it for targeting and measurement.

This guide explains how to grant advertisers access to your products in the catalog so they can use your data for targeting or measurement. You can assign access either dynamically (recommended) or by SKU.

Access can be granted per advertiser or per product, as shown in the following options.

NOTE: You can also use the platform UI to manage access.

Product access by advertiser: Using dynamic rules

You can grant advertisers product access with dynamic rules, which streamline managing access across your catalog. Here's what you need to know about dynamic rules:

• Dynamic rules enable you to grant product access without specifying individual SKU IDs.
• Product access is automatically updated as products are added, updated, or removed if they meet the rule criteria.
• The available dynamic rule types enable you to grant access to all products in the catalog, products of specific brands, or products within selected categories (including their subcategories).
• A single mutation, productPermissionDynamicRulesReplace, enables you to add, replace, and delete dynamic rules for the specified advertiser.
• Setting a dynamic rule overrides any previously set individual SKU permissions or rules.
• Deleting a dynamic rule removes the advertiser’s product access and automatically clears those products from their itemsets.

IMPORTANT: If you use the REST endpoints to manage product access with dynamic rules already applied, existing permissions from those rules are retained, but the rules are deleted and no longer automatically update access when products in the catalog change.

The following table lists the tasks for managing brand or advertiser access to products in your catalog using dynamic rules.

IMPORTANT: All Commerce Solutions endpoints enforce a maximum of 1000 items per request. Payloads that exceed this limit will be rejected. To stay within the limit, split large datasets into multiple requests.

Add or replace dynamic rules

To grant dynamic access to products in your catalog to a specific advertiser using dynamic rules, run the productPermissionDynamicRulesReplace GraphQL mutation. Here's what you need to know about adding dynamic rules:

• The supported rule types include the following:
  • ALL_PRODUCTS: Grants access to all products in the catalog.
  • BRAND: Grants access to products of specific brands.
  • CATEGORY: Grants access to products in specific categories and their subcategories.
• You can specify more than one rule type for your request. If multiple rules are defined, a product must match at least one specified rule value for each rule type.
• Rule values, such as brand names and category IDs, are not case-sensitive.
• It might take up to 15 minutes for any dynamic rule changes to take effect.

IMPORTANT: Setting a dynamic rule overrides any previously set individual SKU permissions or rules for the specified advertiser. If you want to retain any existing rules already set for the advertisers, include them in the mutation input. Otherwise, they will be removed.

The following example productPermissionDynamicRulesReplace mutation shows how to grant an advertiser access to all products in the catalog.

mutation {
  productPermissionDynamicRulesReplace(
    input: {
        advertiserId: "ADVERTISER_ID_PLACEHOLDER",
        merchantId: "MERCHANT_ID_PLACEHOLDER",
        rules: [
          {
            ruleType: ALL_PRODUCTS,
            ruleValues: null
          }
        ]
      }
  ) {
    data {
      advertiser { id }
      merchant { id }
      rules {
        ruleType
        ruleValues
      }
    }
    userErrors {
      field
      message
    }
  }
}

The following example productPermissionDynamicRulesReplace mutation shows how to grant an advertiser dynamic access to products from two brands within a specific category. Note that with two rules defined, a product must match at least one specified rule value for each rule type. For example, if the two brands are Zentra and Mavrix and the category is Shoes, then Zentra shoes are included, but Zentra jackets or Auralis shoes are not.

mutation {
  productPermissionDynamicRulesReplace(
    input: {
        advertiserId: "ADVERTISER_ID_PLACEHOLDER",
        merchantId: "MERCHANT_ID_PLACEHOLDER",
        rules: [
          {
            ruleType: BRAND,
            ruleValues: ["BRAND_NAME_1_PLACEHOLDER","BRAND_NAME_2_PLACEHOLDER"]
          },
          {
            ruleType: CATEGORY,
            ruleValues: ["CATEGORY_ID_PLACEHOLDER"]
          }
        ]
      }
  ) {
    data {
      advertiser { id }
      merchant { id }
      rules {
        ruleType
        ruleValues
      }
    }
    userErrors {
      field
      message
    }
  }
}

Retrieve dynamic rules

To retrieve all dynamic rules set for an advertiser, use the productPermissionDynamicRules GraphQL query.

query GetProductPermissionDynamicRulesExample {
  merchant(id: "MERCHANT_ID_PLACEHOLDER") {
    permittedAdvertiser(id: "ADVERTISER_ID_PLACEHOLDER") {
      productPermissionDynamicRules {
        ruleType
        ruleValues
      }
    }
  }
}

Delete dynamic rules

To delete all dynamic rules set for an advertiser, use the productPermissionDynamicRulesReplace GraphQL mutation to send an empty rules array. To delete a specific rule, include only the rule types you want to keep in your mutation request. For example, if both BRAND and CATEGORY rules are defined and you want to remove the CATEGORY rule, send the mutation with just the BRAND rule, and the CATEGORY rule will be deleted (replaced). For details, see Add or replace dynamic rules.

IMPORTANT: Deleting a dynamic rule removes the advertiser’s product access and automatically clears those products from their itemsets.

The following example productPermissionDynamicRulesReplace mutation shows how to delete all rules defined for an advertiser.

mutation {
  productPermissionDynamicRulesReplace(
    input: {
        advertiserId: "ADVERTISER_ID_PLACEHOLDER",
        merchantId: "MERCHANT_ID_PLACEHOLDER",
        rules: []
      }
  ) {
    data {
      advertiser { id }
      merchant { id }
      rules {
        ruleType
        ruleValues
      }
    }
    userErrors {
      field
      message
    }
  }
}

Product access by advertiser: Using SKUs

The following table lists the tasks for managing brand or advertiser access to multiple products in your catalog using SKUs.

TIP: This method is best suited if you want to manually manage access to individual products. For more efficient and dynamic product access management, see Product access by advertiser: Using dynamic rules.

Add advertiser products

To allow a specific brand or advertiser access to one or more products in your product catalog, in a PUT/ecommerce/advertiser/products/add request, specify your merchant ID, the advertiser ID, and SKU IDs of the products that the advertiser can use.

{
   "MerchantId":"MERCHANT_ID_PLACEHOLDER",
   "AdvertiserId":"ADVERTISER_ID_PLACEHOLDER",
   "SkuIds":[
      {
         "SkuId":"#3234567894"
      },
      {
         "SkuId":"#2234567892"
      },
      {
         "SkuId":"#1234567890"
      }
   ]
}

A successful response returns an empty BatchResponses object with the ContainsError property set to false. Otherwise, the response includes a BatchResponses object with errors that occurred. For details on the batch response format, see Commerce Solutions API usage overview.

Get advertiser products

To retrieve a list of products in your product catalog associated with a specific brand or advertiser, in a POST/ecommerce/advertiser/products/query request, specify your merchant ID and the advertiser ID.

{
   "MerchantId":"MERCHANT_ID_PLACEHOLDER",
   "AdvertiserId":"ADVERTISER_ID_PLACEHOLDER"
}

A successful response returns an array of product SKU IDs associated with the specified advertiser.

{
   "SkuIds":[
      "#3234567894",
      "#2234567892",
      "#1234567890"
   ]
}

Remove advertiser products

To remove access to one or more products in your product catalog from a specific brand or advertiser, in a PUT/ecommerce/advertiser/products/remove request, specify your merchant ID, the advertiser ID, and SKU IDs of the products that the advertiser can no longer use.

{
   "MerchantId":"MERCHANT_ID_PLACEHOLDER",
   "AdvertiserId":"ADVERTISER_ID_PLACEHOLDER",
   "SkuIds":[
      {
         "SkuId":"#3234567894"
      },
      {
         "SkuId":"#2234567892"
      },
      {
         "SkuId":"#1234567890"
      }
   ]
}

A successful response returns an empty BatchResponses object with the ContainsError property set to false. Otherwise, the response includes a BatchResponses object with errors that occurred. For details on the batch response format, see Commerce Solutions API usage overview.

Advertiser access by product

The following table lists the tasks for managing access to a specific product in your catalog for multiple brands or advertisers.

Add product advertisers

To allow one or more brands or advertisers to access and use a specific product from your product catalog, in a PUT/ecommerce/product/advertisers/add request, specify your merchant ID, the product SKU ID, and advertiser IDs.

{
   "MerchantId":"MERCHANT_ID_PLACEHOLDER",
   "SkuId":"#1234567890",
   "AdvertiserIds":[
      {
         "AdvertiserId":" ADVERTISER_ID_PLACEHOLDER"
      },
      {
         "AdvertiserId":" abc123Adv"
      },
      {
         "AdvertiserId":"456AdvQWE"
      }
   ]
}

A successful response returns an empty BatchResponses object with the ContainsError property set to false. Otherwise, the response includes a BatchResponses object with errors that occurred. For details on the batch response format, see Commerce Solutions API usage overview.

Get product advertisers

To get a list of brands or advertisers associated with a specific product in your catalog, in a POST/ecommerce/product/advertisers/query request, specify your merchant ID and the product SKU ID.

{
   "MerchantId":"MERCHANT_ID_PLACEHOLDER",
   "SkuId":"#1234567890"
}

A successful response returns an array of advertiser IDs associated with the specified product SKU.

{
   "AdvertiserIds":[
      "ADVERTISER_ID_PLACEHOLDER",
      "abc123Adv"
   ]
}

Remove product advertisers

To remove access to a specific product in your product catalog from multiple advertisers or brands, in a PUT/ecommerce/product/advertisers/remove request, specify your merchant ID, the product SKU ID, and advertiser IDs.

{
   "MerchantId":"MERCHANT_ID_PLACEHOLDER",
   "SkuId":"#1234567890",
   "AdvertiserIds":[
      {
         "AdvertiserId":" ADVERTISER_ID_PLACEHOLDER"
      },
      {
         "AdvertiserId":" abc123Adv"
      },
      {
         "AdvertiserId":"456AdvQWE"
      }
   ]
}

A successful response returns a 204 code with an empty body.

Next steps

IMPORTANT: If advertisers plan to use the API to build their lists of products from your data for audience building or measurement, be sure to share your merchant ID with them.

You can now do the following:

• Build reports

• Track data usage and spend

• Create tracking tags

• If you haven't done so, create your own product lists