Skip to main content
By default a wholesale product is open: every buyer your Seller Account admits can discover and book it. Use eligibleAccountIds on save_wholesale_product to restrict one product to the buyer accounts you name. It suits inventory you donate to one nonprofit, a negotiated package for one agency client, a house-ad unit, or a product in early access. A restriction changes who sees a product. It never changes a price, and it never gives an account access to a source that account is not admitted to.

Restrict a product

Pass the product’s sourceId and id with eligibleAccountIds, a list of buyer accounts:
  • Name an account by its accountId. Read it from search({ "kind": "account_relationship" }). It is seller_account_v1_… for a buyer account on a complete account key, or the retained account id for an older relationship. An id that is not a buyer account on your Seller Account is refused, and the answer names it. The list holds 1 to 50 accounts with no repeats.
  • The list replaces the stored list. To add an account, send the whole new list. Leave eligibleAccountIds out of a call to keep the restriction as it is.
  • Match is exact. A restriction names a buyer account, not its operator, its brand or the brands above it. If a buyer’s account key changes, it is a different account and does not inherit the restriction. List the new one.
  • It applies to products you author on an ad-server source. A product from a third-party sales agent or a modular source is not written here, so it is never restricted by Apostra. A third-party agent restricts its own products.
You can send eligibleAccountIds when you create a product, or on its own to change a product that exists. A call that changes only the restriction makes no change at the ad server.

Confirm when you narrow a live product

Restricting a product that is open and live hides it from every other buyer at once. So when a product is open and its status is active (or the same call sets it active), the save is refused until you send confirmVisibilityImpact: true. Nothing is written without it. You do not need it for a new product, a draft, a product that is already restricted, or when you open a product.

Open a restricted product again

Send eligibleAccountIds: null. This is the only way to open a restricted product. An empty list [] is refused, so a mistaken empty list can never make a donated product public.

Check what you set

get and search for wholesale_product return eligibleAccountIds: the accountId of each account the product is restricted to, or null when it is open. A restricted product’s buyerVisibility is hidden with the reason restricted_to_accounts and a detail saying how many accounts may see it. That is the restriction working, not a problem to fix. Every change is recorded in your audit log with who made it.

What a buyer sees

  • An account on the list discovers and books the product as it does any other, at the price it normally gets.
  • Every other buyer, and a request that names no account, does not see the product in discovery. If it books the product by an id it learned elsewhere, it gets the same PRODUCT_NOT_FOUND answer it gets for a product that does not exist, with no hint that a restriction exists.
  • A media buy already running keeps running as booked. If you restrict a product that live buys use, or remove an account from the list, the committed state of each existing package is kept. It keeps delivering and reporting, and the account can pause, resume or cancel it. The account cannot commit more: a later end date, an earlier start date, a higher budget or a higher impressions goal is refused as PRODUCT_UNAVAILABLE, which tells the buyer to talk to you. A new package on the product is refused as PRODUCT_NOT_FOUND.

Limits

  • The tool needs a Seller Account, and the same seller roles as the rest of save_wholesale_product.
  • A product from a modular source or a third-party sales agent cannot carry a restriction.
  • A change from an automated brain, such as the Merchandising Agent, that includes eligibleAccountIds waits for an administrator’s approval, as any change other than a price within your band does.