> ## 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. # Property-list briefs for sellers > What a buyer property list means when it reaches a storefront, and how a seller's agent resolves it ## Overview A buyer property list is a buyer-owned include or exclude set of domains, apps, or CTV identifiers. An include list asks the seller to run only on those properties; an exclude list asks the seller never to run on them. The property list reaches the seller as an ADCP `PropertyListReference`, and only when the seller declares in its AdCP capabilities that it applies that kind of list (see [Which sellers receive a reference](#which-sellers-receive-a-reference)). Where the reference appears depends on the request: | Request stage | Where the reference appears | Sent when the seller declares | | - | - | - | | Product discovery (`get_products`) | `filters.property_list` (include) | `media_buy.features.property_list_filtering` or `media_buy.execution.targeting.property_list` | | Media-buy package execution and list changes | `targeting_overlay.property_list` (include) | `media_buy.execution.targeting.property_list` | | Media-buy package execution and list changes | `targeting_overlay.property_list_exclude` (exclude) | `media_buy.execution.targeting.property_list_exclude`, or the product declares `overlay_support.property_list_exclude` | Exclude lists are never sent at discovery; Apostra applies them on its own side when it selects products. For discovery, the include reference travels in the `get_products` filters: ```json theme={null} { "filters": { "property_list": { "agent_url": "https://api.apostra.com", "list_id": "42", "auth_token": "..." } } } ``` For campaign or media-buy execution, the references appear in each package's targeting overlay: ```json theme={null} { "targeting_overlay": { "property_list": { "agent_url": "https://api.apostra.com", "list_id": "include:41,42", "auth_token": "..." }, "property_list_exclude": { "agent_url": "https://api.apostra.com", "list_id": "exclude:43,44", "auth_token": "..." } } } ``` ### Which sellers receive a reference Apostra sends a package reference only to a seller that declares, in its AdCP `get_adcp_capabilities` response, that it applies that kind of list: | Reference | Sent when the seller declares | | - | - | | `targeting_overlay.property_list` | `media_buy.execution.targeting.property_list` | | `targeting_overlay.property_list_exclude` | `media_buy.execution.targeting.property_list_exclude`, or the product declares `overlay_support.property_list_exclude` | The two declarations are independent: declaring `property_list` does not opt a seller into exclude lists. For a product sold through an Apostra storefront, the seller that applies the list is the sales agent behind the storefront, so Apostra reads that agent's declaration, not the storefront's own. Apostra uses the AdCP capabilities it last refreshed for that agent, and the storefront passes both references to the agent unchanged. To receive references, declare `property_list` or `property_list_exclude` in your own sales agent's capabilities. Managed sales agents and platform adapters publish no such declaration, so they receive no references. If Apostra cannot read the declaration, it sends no reference. The same rule applies when a list changes: a seller that does not declare a reference's dimension receives the update without that reference. Whatever the seller declares, Apostra also checks the buyer's exclude lists against each product's disclosed properties before it sends a buy. ### One reference per field A buyer can set lists on an advertiser and on an individual campaign. The seller does not receive each list separately. Apostra sends one reference per field that combines every list in effect for the package: | Field | Combines | A property is on the served list when… | | - | - | - | | `property_list` | The advertiser's include list and the campaign's own include list | It is on **every** include list (intersection) | | `property_list_exclude` | Every advertiser exclude list and the campaign's own exclude list | It is on **any** exclude list (union) | When only one list is in effect, `list_id` is that list's numeric id, such as `"42"`. When several lists are combined, `list_id` names them all, such as `"include:41,42"` or `"exclude:43,44"`, and the resolved list is named "Combined inclusion lists" or "Combined exclusion lists". Treat `list_id` as an opaque string: resolve it exactly as received, percent-encoding it in the URL path. Each `auth_token` is signed for its own `list_id` and opens no other list. ## What the seller's agent does When your sales agent receives a property-list reference, it resolves the list from the buyer's agent URL: ```http theme={null} GET {agent_url}/lists/{list_id} Authorization: Bearer {auth_token} ``` For Apostra buyer lists, that path is mounted at the app root: ```http theme={null} GET https://api.apostra.com/lists/42 Authorization: Bearer {auth_token} ``` The response uses the ADCP property-list shape: ```json theme={null} { "list": { "list_id": "42", "name": "Q1 premium food sites" }, "identifiers": [ { "type": "domain", "value": "wholesomeyum.com" }, { "type": "domain", "value": "tastesbetterfromscratch.com" } ], "resolved_at": "2026-04-25T10:30:00.000Z", "cache_valid_until": "2026-04-26T10:30:00.000Z", "pagination": { "has_more": false, "total_count": 2 } } ``` Agents should cache the resolved list until `cache_valid_until` (24 hours after `resolved_at`), then re-fetch if the buy or update still needs it. The endpoint always serves the list's current content, so a re-fetch picks up any change the buyer made. When the buyer changes a list, Apostra also sends `update_media_buy` to every active media buy that uses it, carrying the reference in effect on each package. The `list_id` stays the same when only the list's content changed, so treat that update as a signal to re-fetch the list rather than relying on the cached copy. Large lists can be paginated. Pass `max_results` and follow `pagination.cursor` while `pagination.has_more` is `true`. Cache each resolved page until `cache_valid_until`. `pagination.total_count` is reported on the first page of a single list only; a combined list omits it. ## What it means operationally Today, Apostra forwards the property-list references and provides the resolution endpoint. The seller decides how to honor them. Common seller-side outcomes: | If the seller can... | Then the seller can... | | - | - | | Map the identifiers to an existing product | Offer or execute that product. | | Map the identifiers to ad-server controls | Apply the seller's own GAM key-values, ad units, or placement logic. | | Honor only part of the list | Explain the supported subset or offer the closest available package. | | Not honor the list | Say the current products do not support that subset. | Do not treat a buyer property list as automatic ad-server enforcement. If the seller has not configured a way to execute that subset, the honest answer is that the storefront can see the buyer's requested properties but must decide seller-side whether it can run against them. ## How this relates to coverage Coverage and buyer property lists answer different questions. | Question | Answered by | | - | - | | "What publisher domains does this product cover?" | The product's `publisher_properties` in `get_products`. | | "Which properties is the buyer asking this request to include?" | `filters.property_list` or `targeting_overlay.property_list`, resolved through `GET {agent_url}/lists/{list_id}`. | | "Which properties must this request never run on?" | `targeting_overlay.property_list_exclude`, resolved the same way. | | "Can this seller execute the requested subset?" | The seller's products, ad-server setup, and agent behavior. | For network sellers, `publisher_properties` usually comes from `adagents.json` authorized coverage. A buyer property list is the buyer's requested subset inside or across seller coverage. ## Related Buyer-side list creation, validation, and resolution. How buyers see the publisher domains a product covers. How seller-managed GAM key-values relate to site lists. Browse GAM targeting and create signals. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.