> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apostra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Restrict a product to named buyer accounts

> Make a wholesale product visible and bookable only to the buyer accounts you name, with eligibleAccountIds on save_wholesale_product, and what a restricted product looks like to a buyer.

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:

```json theme={null}
{
  "sourceId": "gam-main",
  "id": "prod_donated_spot",
  "eligibleAccountIds": ["seller_account_v1_9f2c0e7d41ab4c56a1d3e8b5c7f60a12"],
  "confirmVisibilityImpact": true
}
```

* **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.

## Related

* [Create and manage seller products](https://docs.apostra.com/v3/seller-product-creation.md)
* [The Buyers Page and buyer accounts](https://docs.apostra.com/v3/seller-buyer-account-mapping-page.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.