Manage product catalog 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.

To enable advertisers to use your data for targeting and measurement, you must grant them access to your product catalog, and then to the products within it. This guide focuses on the first step, which is managing access to your catalog. Here's what you need to know about granting advertisers access:

You must build your product catalog before granting access.
Only merchants with a valid merchant ID can perform these tasks.
All Commerce Solutions endpoints enforce a maximum of 1000 items per request. Payloads that exceed this limit are rejected. To stay within the limit, split large datasets into multiple requests.
Permissions are granted per advertiser. To enable access, call the POST/ecommerce/permission endpoint for each advertiser.

To build audiences or manage conversions with your product data, a brand or advertiser must have permission to access your catalog. These permissions allow advertisers to do the following:

Access your product catalog (required for using your data for targeting and measurement).
Access your aggregated sales data.
Use your data for targeting.
Use your data for measurement.

NOTE: By default, targeting and measurement use your default rates. If needed, you can assign custom rates instead.

Prerequisites

Before you grant access, you must have the following IDs:

Your merchant ID.
The IDs of the advertisers you want to grant access to.

Manage product catalog access tasks

The following table lists the tasks for managing product catalog access for advertisers.

Task	Operation
Grant and manage catalog permissions	`merchantPermittedAdvertiserGrant` mutation
Get catalog access permissions for an advertiser	`merchant` query

Grant and manage catalog permissions

To grant an advertiser access to your product catalog or feature, use the merchantPermittedAdvertiserGrant mutation and enable each feature that you want the advertiser to have access to. You can grant and revoke access all at once as needed using the same mutation.

IMPORTANT: If you want to grant an advertiser access to targeting and measurement, you must also grant access to the product catalog.

The following merchantPermittedAdvertiserGrant mutation example shows how to grant and revoke advertiser access to your features with custom CPM rates for targeting and measurement, using the sharedAs field to indicate that you're granting access as a data provider (THIRD_PARTY).

mutation {
  merchantPermittedAdvertiserGrant(
    input: {
      merchantId: "MERCHANT_ID_PLACEHOLDER"
      advertiserId: "ADVERTISER_ID_PLACEHOLDER"
      sharedAs: THIRD_PARTY
      features: {
        productCatalog: {
          enabled: true
        }
        targeting: {
          enabled: true
          cpmRate: 4
          percentOfMediaCostRate: 40
          thirdPartyDataBrandId: "3PD_BRAND_ID_PLACEHOLDER"
        }
        measurement: {
          enabled: true
          displayMeasurementCpmRate: 0.20
          videoMeasurementCpmRate: 0.20
        }
      }
    }
  ) {
    data {
      merchant {
        id
        name
      }
      advertiser {
        id
        name
      }
      features
      createdAt
      lastUpdatedAt
    }
    userErrors {
      field
      message
    }
  }
}

A successful response returns the list of features that the advertiser has access to.

Get catalog access permissions for advertisers

To check whether an advertiser has access to your catalog and related features, use the merchant query and specify your merchant ID and the IDs of the advertisers you want to check.

The following merchant query example shows how to retrieve permission details for two advertisers.

query GetMultipleAdvertiserPermissionsExample {
  merchant(id: "MERCHANT_ID_PLACEHOLDER") {
    id
    name
    permittedAdvertisers(
      where: {
        advertiser: {
          id: { in: ["ADVERTISER_ID_A_PLACEHOLDER", "ADVERTISER_ID_B_PLACEHOLDER"] }
        }
      }
      first: 50
    ) {
      totalCount
      edges {
        node {
          id
          name
        }
        sharedAs
        features
        createdAt
        lastUpdatedAt
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
}

Next steps

After setting up advertiser access to your catalog, grant the advertisers access to your products.

FAQs

The following are frequently asked questions about managing access to the product catalog.

IMPORTANT: All Commerce Solutions REST 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.

What features can I grant advertisers access to?

You can grant advertisers access to the following features:

Product catalog
Targeting
Measurement
Aggregate sales self-service

For details on how to grant an advertiser access to these features, see Grant and manage catalog permissions.

What happens if I grant access to targeting or measurement without granting catalog access?

The request returns an error. Targeting and measurement data relies on your product catalog for advertisers to use. To grant advertiser access to your targeting and measurement data, you must also grant them access to your product catalog.

Can I revoke access after granting it?

Yes. Use the same merchantPermittedAdvertiserGrant mutation and, for each feature you want to revoke, set the enabled field to false. You can grant and revoke multiple features for the same advertiser in a single request. For details, see Grant and manage catalog permissions.

What's the difference between using GraphQL and REST to manage catalog access?

With the REST API, you use separate endpoints to manage access. With the GraphQL API, you can grant and revoke access with just one merchantPermittedAdvertiserGrant mutation.

Can I use REST to grant an advertiser access to my catalog?

Yes. GraphQL is the recommended way to grant catalog access because it enables you to manage multiple advertisers and features in a single request. If you need to use REST instead, use the POST/ecommerce/permission endpoint. In the request, specify your merchant ID and the advertiser ID, and in the FeaturesToGrantAccessTo array, include the product catalog and other appropriate values.

{
   "MerchantId":"MERCHANT_ID_PLACEHOLDER",
   "AdvertiserId":"ADVERTISER_ID_PLACEHOLDER",
   "FeaturesToGrantAccessTo": [
     "ProductCatalog",
     "AggregateSales",
     "Targeting",
     "Measurement"
   ]
}

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

Can I use REST to check whether an advertiser has access to my catalog?

Yes. GraphQL is the recommended way to check catalog access permissions, but if you need to use REST instead, use the POST/ecommerce/permission/query endpoint and specify your merchant ID and the advertiser ID.

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

A successful response indicates whether the specified advertiser can build audiences using your data.

{
   "MerchantId":"MERCHANT_ID_PLACEHOLDER",
   "AdvertiserId":"ADVERTISER_ID_PLACEHOLDER",
   "FeaturesToGrantAccessTo": [
     "ProductCatalog",
     "AggregateSales",
     "Targeting",
     "Measurement"
   ]
}

Can I use REST to remove an advertiser's catalog access permission?

Yes. GraphQL is the recommended way to revoke catalog access, but if you need to use REST instead, use the POST/ecommerce/permission/delete endpoint. In the request, specify your merchant ID and the advertiser ID, and in the FeaturesToRemove array, include the appropriate values of the permissions you want to remove.

{
   "MerchantId":"MERCHANT_ID_PLACEHOLDER",
   "AdvertiserId":"ADVERTISER_ID_PLACEHOLDER",
   "FeaturesToRemove": [
     "ProductCatalog",
     "AggregateSales",
     "Targeting",
     "Measurement"
   ]
}

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