late-sdk 0.0.897 → 0.0.899

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f8958df8e529d3c1779b84996c2f7e9f7985383f539b208fb1f869d34e694cad
-  data.tar.gz: 2f7e91e736793f88f5e4c701ce037238c1cb4edd3144bded727e208d0d88dd50
+  metadata.gz: f1fe40764a586fc0337945b4adb251032343ea0ce91994b80288c687805230e5
+  data.tar.gz: ff9af29348094b89309c7ee7136ddc041ffae14eb880268f47ba6b3651c1eefd
 SHA512:
-  metadata.gz: 4e406e07e57829db26c0942af4dbda76c8b3f9c13828016ffd77acf85775bdd552574932080334446e2d4c880b022d4d3b47a2daf21ad809475d0c233a6d5c92
-  data.tar.gz: 16fa3ec320abc933c0ca307dab57bcda3cbb573ad115275f1e952f9e22edc4cf9ae275f7ad0b55cfce8d38a5d8ed64944fcdd26b2a418984fafcde85b4b279fc
+  metadata.gz: 61205f71c1173b26f4f3f7086a5ffd4ffaf39c5aaec6bc283e32aceb66282025a302e16903a01362a582c98229d190ecb94fff351181e042c46593034b73ecef
+  data.tar.gz: bb681fb5b0cd796f8da6f54a94e77ddcdec2d93b50d8bb6df3995e909766f60890cb8da9563d182f2c5c6a884a22aa21b6ac6e63e3d4c6aa2d78a0dd3967443f

data/README.md

@@ -1949,6 +1949,8 @@ Class | Method | HTTP request | Description
  - [Zernio::MetaAdsPlatformData](docs/MetaAdsPlatformData.md)
  - [Zernio::MetaLeadFormPlatformData](docs/MetaLeadFormPlatformData.md)
  - [Zernio::MetaLeadFormPlatformDataContextCard](docs/MetaLeadFormPlatformDataContextCard.md)
+ - [Zernio::MetaPromotion](docs/MetaPromotion.md)
+ - [Zernio::MetaPromotionStatus](docs/MetaPromotionStatus.md)
  - [Zernio::Money](docs/Money.md)
  - [Zernio::MoneyAmount](docs/MoneyAmount.md)
  - [Zernio::MoveAccountToProfile200Response](docs/MoveAccountToProfile200Response.md)

data/docs/AdCampaignsApi.md

@@ -548,7 +548,7 @@ end
 
 Create standalone ad
 
-Create a paid ad with custom creative across Meta, Google Ads, Pinterest, TikTok, X, LinkedIn, and OpenAI Ads (ChatGPT Ads).  Three mutually-exclusive request shapes are selected by the body:  - Legacy single-creative shape (all platforms, the default). - Meta-only multi-creative shape via the creatives array: one ad set with N ads sharing budget and targeting. - Attach shape via adSetId: adds one new ad to an existing ad set, inheriting its budget, targeting, and schedule (Meta, Google Ads, TikTok, and LinkedIn). On LinkedIn adSetId is the existing Campaign id, and the budget, schedule, targeting and bidding fields must be omitted.  Per-platform required fields, budget minimums, and video-ad rules are documented on each property below.  LinkedIn creates a Single Image or Single Video Ad backed by a Direct Sponsored Content \"dark post\" authored by a Company Page (see `organizationId`). Supported goals are engagement, traffic, awareness, and video_views (video ads use the `video` field; video_views requires a video), and traffic ads require `linkUrl`.  **Idempotency:** this endpoint is not idempotent at the platform level (a blind retry creates a second campaign/ad set/ad). Send an `Idempotency-Key` header to make retries safe: the first request with a given key creates the ad and we store the response; a retry with the same key replays that exact response (with `Idempotent-Replayed: true`) instead of creating duplicates. Reusing a key with a different body returns 422; a key whose first request is still in flight returns 409 (retry after a short backoff). Keys are scoped to your credential and expire after 24h. 
+Create a paid ad with custom creative across Meta, Google Ads, Pinterest, TikTok, X, LinkedIn, and OpenAI Ads (ChatGPT Ads).  Three mutually-exclusive request shapes are selected by the body:  - Legacy single-creative shape (all platforms, the default). - Meta-only multi-creative shape via the creatives array: one ad set with N ads sharing budget and targeting. - Attach shape via adSetId: adds one new ad to an existing ad set, inheriting its budget, targeting, and schedule (Meta, Google Ads, TikTok, and LinkedIn). On LinkedIn adSetId is the existing Campaign id, and the budget, schedule, targeting and bidding fields must be omitted.  Meta accepts `promotion` and `creativeFeatures` on the single and attach shapes and as defaults for `creatives[]`. An item replaces the whole feature map; its `promotion` replaces the default offer, and `promotion: null` disables that default for the item. Reusing `existingCreativeId` uses the existing creative settings instead of new settings. Requested settings are persisted for lists, exports, and default ad-detail reads. Only ads supplied a `promotion` receive live readback; multi-create batches those reads in groups of up to 50 IDs without per-ad fallback. Inspect `ad.creative.promotionStatus` (or `ads[].creative.promotionStatus`). `not_returned` means Meta omitted the metadata; successful creation does not by itself prove the offer was applied or will display.  Per-platform required fields, budget minimums, and video-ad rules are documented on each property below.  LinkedIn creates a Single Image or Single Video Ad backed by a Direct Sponsored Content \"dark post\" authored by a Company Page (see `organizationId`). Supported goals are engagement, traffic, awareness, and video_views (video ads use the `video` field; video_views requires a video), and traffic ads require `linkUrl`.  **Idempotency:** this endpoint is not idempotent at the platform level (a blind retry creates a second campaign/ad set/ad). Send an `Idempotency-Key` header to make retries safe: the first request with a given key creates the ad and we store the response; a retry with the same key replays that exact response (with `Idempotent-Replayed: true`) instead of creating duplicates. Reusing a key with a different body returns 422; a key whose first request is still in flight returns 409 (retry after a short backoff). Keys are scoped to your credential and expire after 24h. 
 
 ### Examples
 
@@ -830,7 +830,7 @@ end
 
 Duplicate an ad
 
-Duplicates a single ad via Meta's native `POST /{ad-id}/copies`. The copy is created paused. `adSetId` retargets the copy into another ad set; omitted = the source's own ad set. Accepts the Zernio ad id or the platform ad id. Sync discovery is triggered automatically (`syncAfter: false` to skip).
+Duplicates a single ad via Meta's native `POST /{ad-id}/copies`. The copy is created paused. `adSetId` retargets the copy into another ad set; omitted = the source's own ad set. Accepts the Zernio ad id or the platform ad id. Sync discovery is triggered automatically (`syncAfter: false` to skip). Creative settings returned by Meta, including explicit promotion metadata and creativeFeatures, are preserved when the native copy requires a creative rebuild. Metadata Meta does not return cannot be recovered.
 
 ### Examples
 
@@ -1051,11 +1051,11 @@ end
 
 ## get_ad
 
-> <GetAd200Response> get_ad(ad_id)
+> <GetAd200Response> get_ad(ad_id, opts)
 
 Get ad details
 
-Returns an ad with its creative, targeting, status, and performance metrics.  The `{adId}` path segment accepts any identifier dialect Zernio indexes for the ad: - the Zernio internal `_id` (24-char hex) - Meta's numeric `platformAdId` (the value shipped in `comment.received` webhooks as `comment.ad.id`) - the creative's `effective_object_story_id` (`{pageId}_{postId}` shape, Facebook side) - the creative's `effective_instagram_media_id` (Instagram side)  Any of the four resolve to the same ad. Caller doesn't need a translation step. 
+Returns an ad with its creative, targeting, status, and performance metrics.  The `{adId}` path segment accepts any identifier dialect Zernio indexes for the ad: - the Zernio internal `_id` (24-char hex) - Meta's numeric `platformAdId` (the value shipped in `comment.received` webhooks as `comment.ad.id`) - the creative's `effective_object_story_id` (`{pageId}_{postId}` shape, Facebook side) - the creative's `effective_instagram_media_id` (Instagram side)  Any of the four resolve to the same ad. Caller doesn't need a translation step. By default, creative.promotion and creative.creativeFeatures contain stored requested settings, which do not confirm platform application. With `refreshPromotion=true`, Meta promotion metadata is read live and exposed as `ad.creative.promotion` with `promotionStatus`. Only `applied` confirms an offer; `not_returned` means the creative read succeeded without promotion metadata, and `unavailable` means it failed. 
 
 ### Examples
 
@@ -1070,10 +1070,13 @@ end
 
 api_instance = Zernio::AdCampaignsApi.new
 ad_id = 'ad_id_example' # String | Zernio `_id` (hex), Meta `platformAdId` (numeric), or one of the creative's effective story/media IDs. See description for details. 
+opts = {
+  refresh_promotion: true # Boolean | Meta only. Read current promotion metadata from Meta and include promotionStatus. Omit for stored creative settings with no promotion-specific Graph call.
+}
 
 begin
   # Get ad details
-  result = api_instance.get_ad(ad_id)
+  result = api_instance.get_ad(ad_id, opts)
   p result
 rescue Zernio::ApiError => e
   puts "Error when calling AdCampaignsApi->get_ad: #{e}"
@@ -1084,12 +1087,12 @@ end
 
 This returns an Array which contains the response data, status code and headers.
 
-> <Array(<GetAd200Response>, Integer, Hash)> get_ad_with_http_info(ad_id)
+> <Array(<GetAd200Response>, Integer, Hash)> get_ad_with_http_info(ad_id, opts)
 
 ```ruby
 begin
   # Get ad details
-  data, status_code, headers = api_instance.get_ad_with_http_info(ad_id)
+  data, status_code, headers = api_instance.get_ad_with_http_info(ad_id, opts)
   p status_code # => 2xx
   p headers # => { ... }
   p data # => <GetAd200Response>
@@ -1103,6 +1106,7 @@ end
 | Name | Type | Description | Notes |
 | ---- | ---- | ----------- | ----- |
 | **ad_id** | **String** | Zernio &#x60;_id&#x60; (hex), Meta &#x60;platformAdId&#x60; (numeric), or one of the creative&#39;s effective story/media IDs. See description for details.  |  |
+| **refresh_promotion** | **Boolean** | Meta only. Read current promotion metadata from Meta and include promotionStatus. Omit for stored creative settings with no promotion-specific Graph call. | [optional][default to false] |
 
 ### Return type
 

data/docs/AdCreative.md

@@ -8,6 +8,8 @@
 | **image_url** | **String** | Alternative image URL | [optional] |
 | **video_id** | **String** | Meta video ID for VIDEO-type ads. Null for non-video ads. Callers that need an embeddable MP4 can call GET /{videoId}?fields=source with the page access token. | [optional] |
 | **video_url** | **String** | Public Facebook watch URL for VIDEO-type ads (https://www.facebook.com/watch/?v={videoId}). Null for non-video ads. | [optional] |
+| **promotion** | [**MetaPromotion**](MetaPromotion.md) | Meta offer read from the live creative on creation or GET /v1/ads/{adId}. Null when metadata is not returned or cannot be read. Requested values are never echoed as applied. | [optional] |
+| **promotion_status** | [**MetaPromotionStatus**](MetaPromotionStatus.md) |  | [optional] |
 | **creative_id** | **String** | Meta ad creative id backing this ad. Reusable via existingCreativeId on POST /v1/ads/create. | [optional] |
 | **object_type** | **String** | Meta creative object_type (e.g. SHARE, VIDEO, PRIVACY_CHECK_FAIL, POST_DELETED). Use this to render state-aware previews: when Meta moderation strips image/video fields, only thumbnailUrl at 64x64 is available. | [optional] |
 | **object_story_id** | **String** | Meta creative `object_story_id` (the SHARE reference). Frequently absent, because Meta omits it for SHARE creatives. Use effectiveObjectStoryId instead. | [optional] |
@@ -38,6 +40,8 @@ instance = Zernio::AdCreative.new(
   image_url: null,
   video_id: null,
   video_url: null,
+  promotion: null,
+  promotion_status: null,
   creative_id: null,
   object_type: null,
   object_story_id: null,

data/docs/AdCreativesApi.md

@@ -27,7 +27,7 @@ All URIs are relative to *https://zernio.com/api*
 
 Create a standalone creative
 
-Creates a creative in the library WITHOUT an ad, reusable on the create endpoints via `existingCreativeId`. Provide exactly one of `imageUrl` (uploaded server-side), `imageHash` (from POST /v1/ads/images or the library list), or `carouselCards` (2-10 hand-built cards). The Page (and linked Instagram account, when present) is resolved from `accountId` as the story actor.
+Creates a creative in the library WITHOUT an ad, reusable on the create endpoints via `existingCreativeId`. Provide exactly one of `imageUrl` (uploaded server-side), `imageHash` (from POST /v1/ads/images or the library list), or `carouselCards` (2-10 hand-built cards). The Page (and linked Instagram account, when present) is resolved from `accountId` as the story actor. `promotion` configures an explicit offer separately from Advantage+ `creativeFeatures`. Only when `promotion` is supplied does the response read the creative back from Meta; `promotionStatus: not_returned` means Meta accepted creation but omitted promotion metadata, so the requested offer is not confirmed as applied.
 
 ### Examples
 
@@ -526,7 +526,7 @@ end
 
 List a catalog's product sets
 
-Lists a Meta product catalog's product sets, the unit a catalog ad promotes. Pass the chosen set as `promotedObject.productSetId` on POST /v1/ads/create with `goal: catalog_sales`.
+Lists a Meta product catalog's product sets, the unit a catalog ad promotes. Pass the chosen set id, not the parent catalog id, as `promotedObject.productSetId` on POST /v1/ads/create with `goal: catalog_sales`. Creation verifies set visibility and returns 400 for a catalog id or an inaccessible set.
 
 ### Examples
 

data/docs/BoostPostRequest.md

@@ -4,6 +4,7 @@
 
 | Name | Type | Description | Notes |
 | ---- | ---- | ----------- | ----- |
+| **creative_features** | **Hash<String, String>** | Meta Advantage+ creative enhancements. Map snake_case feature names to OPT_IN or OPT_OUT; Meta validates supported keys and unspecified features default to OPT_OUT. auto_promotion_tag is an enhancement; use the separate promotion field for an explicit offer. The deprecated standard_enhancements bundle is rejected by Meta. | [optional] |
 | **post_id** | **String** | Zernio post ID (provide this or platformPostId) | [optional] |
 | **platform_post_id** | **String** | Platform post ID (alternative to postId) | [optional] |
 | **account_id** | **String** | Account ID |  |
@@ -43,6 +44,7 @@
 require 'zernio-sdk'
 
 instance = Zernio::BoostPostRequest.new(
+  creative_features: {auto_promotion_tag=OPT_IN},
   post_id: null,
   platform_post_id: null,
   account_id: null,

data/docs/CreateAdCreative201Response.md

@@ -6,6 +6,8 @@
 | ---- | ---- | ----------- | ----- |
 | **ad_account_id** | **String** |  | [optional] |
 | **creative_id** | **String** | Platform creative id, reusable via existingCreativeId. | [optional] |
+| **promotion** | [**MetaPromotion**](MetaPromotion.md) |  | [optional] |
+| **promotion_status** | [**MetaPromotionStatus**](MetaPromotionStatus.md) |  | [optional] |
 
 ## Example
 
@@ -14,7 +16,9 @@ require 'zernio-sdk'
 
 instance = Zernio::CreateAdCreative201Response.new(
   ad_account_id: null,
-  creative_id: null
+  creative_id: null,
+  promotion: null,
+  promotion_status: null
 )
 ```
 

data/docs/CreateAdCreativeRequest.md

@@ -15,7 +15,8 @@
 | **image_hash** | **String** | Existing library image hash (POST /v1/ads/images or GET /v1/ads/images). | [optional] |
 | **carousel_cards** | [**Array<CreateAdCreativeRequestCarouselCardsInner>**](CreateAdCreativeRequestCarouselCardsInner.md) |  | [optional] |
 | **url_tags** | **String** | Appended to every outbound URL (e.g. utm_source=fb). | [optional] |
-| **creative_features** | **Hash<String, String>** | Advantage+ creative enhancements: partial map of Meta creative feature keys (snake_case) to enroll status, forwarded as degrees_of_freedom_spec.creative_features_spec. Unspecified features default to OPT_OUT. | [optional] |
+| **promotion** | [**MetaPromotion**](MetaPromotion.md) |  | [optional] |
+| **creative_features** | **Hash<String, String>** | Meta only. Applied to each new creative, including standalone and attach shapes. With creatives[], these are defaults; an item replaces the whole feature map, including an empty map. auto_promotion_tag is an enhancement; an explicit offer uses promotion. | [optional] |
 | **multi_advertiser** | **String** | Meta only. Multi-advertiser ads: whether Meta may show this ad alongside other advertisers' in one unit. Meta auto-enrols since Aug 2024, so send OPT_OUT to leave. It is a top-level creative field, NOT a `creativeFeatures` key, and Meta rejects it there. | [optional] |
 
 ## Example
@@ -35,7 +36,8 @@ instance = Zernio::CreateAdCreativeRequest.new(
   image_hash: null,
   carousel_cards: null,
   url_tags: null,
-  creative_features: null,
+  promotion: null,
+  creative_features: {auto_promotion_tag=OPT_IN},
   multi_advertiser: null
 )
 ```

data/docs/CreateCallAdRequest.md

@@ -4,6 +4,7 @@
 
 | Name | Type | Description | Notes |
 | ---- | ---- | ----------- | ----- |
+| **creative_features** | **Hash<String, String>** | Meta enhancement settings for single or attached ads, and defaults for creatives[]. An item replaces the entire map, including with an empty object. | [optional] |
 | **account_id** | **String** | Facebook or Instagram SocialAccount ID. |  |
 | **ad_account_id** | **String** | Meta ad account ID, e.g. `act_123456789`. |  |
 | **name** | **String** | Ad display name. Used to derive campaign / ad set names. On the multi-creative shape, each ad's Meta name gets a \" #N\" suffix (1-indexed) so Ads Manager shows them as a numbered batch.  |  |
@@ -52,6 +53,7 @@
 require 'zernio-sdk'
 
 instance = Zernio::CreateCallAdRequest.new(
+  creative_features: {auto_promotion_tag=OPT_IN},
   account_id: null,
   ad_account_id: null,
   name: null,

data/docs/CreateMessagingAdRequest.md

@@ -4,6 +4,7 @@
 
 | Name | Type | Description | Notes |
 | ---- | ---- | ----------- | ----- |
+| **creative_features** | **Hash<String, String>** | Meta enhancement settings for single or attached ads, and defaults for creatives[]. An item replaces the entire map, including with an empty object. | [optional] |
 | **account_id** | **String** | Facebook or Instagram SocialAccount ID. |  |
 | **ad_account_id** | **String** | Meta ad account ID, e.g. `act_123456789`. |  |
 | **name** | **String** | Ad display name. Used to derive campaign / ad set names. On the multi-creative shape, each ad's Meta name gets a \" #N\" suffix (1-indexed) so Ads Manager shows them as a numbered batch.  |  |
@@ -51,6 +52,7 @@
 require 'zernio-sdk'
 
 instance = Zernio::CreateMessagingAdRequest.new(
+  creative_features: {auto_promotion_tag=OPT_IN},
   account_id: null,
   ad_account_id: null,
   name: null,

data/docs/CreateStandaloneAdRequest.md

@@ -16,7 +16,8 @@
 | **billing_event** | **String** | Meta only. Explicit ad-set `billing_event`. Defaults to `IMPRESSIONS`. Forwarded verbatim to Meta, which validates compatibility with the optimization goal. | [optional] |
 | **buying_type** | **String** | Meta only. RESERVED = Reach & Frequency: requires `rfPredictionId` (a RESERVED prediction from /v1/ads/rf-predictions + /reserve). Budget, schedule and pricing come from the reservation, so budgetAmount/budgetType are not required and bid fields are ignored. Only the plain single-ad shape (no creatives[], adSetId, existingCampaignId or dynamicCreative). | [optional] |
 | **rf_prediction_id** | **String** | Meta only. The RESERVED prediction id the R&F ad set runs on (reserving mints a new id, so pass that one). Requires buyingType RESERVED. | [optional] |
-| **creative_features** | **Hash<String, String>** | Meta only. Advantage+ creative enhancements: a partial map of Meta creative feature keys (snake_case, e.g. enhance_cta, image_brightness_and_contrast, text_optimizations) to enroll status, forwarded as degrees_of_freedom_spec.creative_features_spec. Meta validates the keys; unspecified features default to OPT_OUT. The legacy standard_enhancements bundle is deprecated by Meta and rejected. | [optional] |
+| **promotion** | [**MetaPromotion**](MetaPromotion.md) |  | [optional] |
+| **creative_features** | **Hash<String, String>** | Meta only. Applied to each new creative, including standalone and attach shapes. With creatives[], these are defaults; an item replaces the whole feature map, including an empty map. auto_promotion_tag is an enhancement; an explicit offer uses promotion. | [optional] |
 | **multi_advertiser** | **String** | Meta only. Multi-advertiser ads: whether Meta may show this ad alongside other advertisers' in one unit. Meta auto-enrols since Aug 2024, so send OPT_OUT to leave. It is a top-level creative field, NOT a `creativeFeatures` key, and Meta rejects it there. | [optional] |
 | **validate_only** | **Boolean** | Meta only, single standalone shape only (no creatives[], adSetId, or RESERVED). Dry-run: each node runs Meta's execution_options validate_only and NOTHING is created or persisted. Children need real parents, so a fresh tree validates the campaign + creative (the ad set needs its campaign to exist, so pass existingCampaignId to validate it too; the ad itself is never validatable pre-create). A Meta validation failure returns the 400 verbatim; success returns 200 with per-node results instead of an ad. | [optional] |
 | **budget_amount** | **Float** | Budget in WHOLE currency units (USD: 50 = $50.00), NOT cents. Meta's own Marketing API takes this same number in minor units, so it is an easy and expensive mix-up. Required on legacy + multi-creative shapes. Inherited on attach. OpenAI Ads requires a $1 minimum (its budget is lifetime-only, see budgetType). | [optional] |
@@ -39,7 +40,7 @@
 | **images** | [**CreateStandaloneAdRequestImages**](CreateStandaloneAdRequestImages.md) |  | [optional] |
 | **video** | [**CreateStandaloneAdRequestVideo**](CreateStandaloneAdRequestVideo.md) |  | [optional] |
 | **creatives** | [**Array<CreateStandaloneAdRequestCreativesInner>**](CreateStandaloneAdRequestCreativesInner.md) | Meta-only. When present, switches to the multi-creative shape: creates 1 campaign + 1 ad set + N ads (one per entry here). Top-level `headline` / `body` / `imageUrl` / `linkUrl` / `callToAction` are ignored in this mode. Mutually exclusive with `adSetId`.  | [optional] |
-| **ad_set_id** | **String** | When present, switches to the attach shape: adds one new ad to this existing ad set without creating a new campaign. Budget, targeting, goal, schedule, AND bid strategy are inherited from the ad set on Meta, and passing `bidStrategy` in attach mode returns 400. To change an existing ad set's bid, use `PUT /v1/ads/ad-sets/{adSetId}`. Mutually exclusive with `creatives[]`.  The attached ad takes the full single-creative surface: `headline`/`body`/`description`/`callToAction` plus either `imageUrl`/`video` OR `placementAssets` (its own per-placement Feed/Story assets) OR `translations`/`defaultLocale` (its own per-locale asset feed, Meta only), and `leadGenFormId` when the target is a lead ad set (the parent must be ON_AD, true for ad sets created via goal `lead_generation`; Meta rejects a formless ad there, so pass the form on EVERY attached ad). This is the way to build N full ads sharing one ad set: create the first ad via the normal shape, then attach the rest one call each.  Supported on Meta (facebook, instagram), Google Ads, TikTok, and LinkedIn. On TikTok the `adSetId` is the ad group ID; the new ad inherits the ad group's bid + budget + targeting. On LinkedIn the `adSetId` is the LinkedIn Campaign ID (numeric); we attach a new Creative to that Campaign, so the Campaign's `platformSpecificData` bidding, targeting, budget and schedule are inherited (passing those fields returns 400).  On Google Ads the `adSetId` is the AD GROUP id. `goal` is still REQUIRED even though budget and targeting are inherited from the ad group. Send `campaignType: \"search\"` to attach into a Search ad group, including one created by `POST /v1/ads/ad-sets` (always SEARCH_STANDARD): without it the request is treated as Display and requires `images.landscape` + `images.square` + `businessName`, and the resulting display creative does not match a Search ad group. `budgetAmount`/`budgetType` and bidding fields (`bidStrategy`, `bidAmount`, `portfolioBidStrategyId`) return 400 on this shape; the ad group already owns them.  | [optional] |
+| **ad_set_id** | **String** | When present, switches to the attach shape: adds one new ad to this existing ad set without creating a new campaign. Budget, targeting, goal, schedule, AND bid strategy are inherited from the ad set on Meta, and passing `bidStrategy` in attach mode returns 400. To change an existing ad set's bid, use `PUT /v1/ads/ad-sets/{adSetId}`. Mutually exclusive with `creatives[]`. `dynamicCreative` returns 400 in attach mode: create a new dynamic ad set by omitting `adSetId` instead.  The attached ad takes the full single-creative surface: `headline`/`body`/`description`/`callToAction` plus either `imageUrl`/`video` OR `placementAssets` (its own per-placement Feed/Story assets) OR `translations`/`defaultLocale` (its own per-locale asset feed, Meta only), and `leadGenFormId` when the target is a lead ad set (the parent must be ON_AD, true for ad sets created via goal `lead_generation`; Meta rejects a formless ad there, so pass the form on EVERY attached ad). This is the way to build N full ads sharing one ad set: create the first ad via the normal shape, then attach the rest one call each.  Supported on Meta (facebook, instagram), Google Ads, TikTok, and LinkedIn. On TikTok the `adSetId` is the ad group ID; the new ad inherits the ad group's bid + budget + targeting. On LinkedIn the `adSetId` is the LinkedIn Campaign ID (numeric); we attach a new Creative to that Campaign, so the Campaign's `platformSpecificData` bidding, targeting, budget and schedule are inherited (passing those fields returns 400).  On Google Ads the `adSetId` is the AD GROUP id. `goal` is still REQUIRED even though budget and targeting are inherited from the ad group. Send `campaignType: \"search\"` to attach into a Search ad group, including one created by `POST /v1/ads/ad-sets` (always SEARCH_STANDARD): without it the request is treated as Display and requires `images.landscape` + `images.square` + `businessName`, and the resulting display creative does not match a Search ad group. `budgetAmount`/`budgetType` and bidding fields (`bidStrategy`, `bidAmount`, `portfolioBidStrategyId`) return 400 on this shape; the ad group already owns them.  | [optional] |
 | **existing_campaign_id** | **String** | Meta, Google Ads, and LinkedIn. On Meta: add the new ad set under this EXISTING campaign instead of creating a new one (multi-ad-set audience testing). The new ad set's budget is matched to the campaign's mode automatically: for a CBO campaign (campaign-level budget) omit `budgetAmount`/`budgetType`, since the campaign owns the budget; for an ABO campaign pass them (they go on the new ad set). On LinkedIn: create a new Campaign (and its Creative) under this EXISTING CampaignGroup. On Google Ads: create a new ad group under this EXISTING campaign; the new ad group inherits the campaign's budget, so omit `budgetAmount`/`budgetType` (and any bidding field), or the request returns 400. On failure only the entities we authored are cleaned up; the pre-existing parent is left untouched and is never (re)activated. Mutually exclusive with `adSetId` and `creatives[]`.  | [optional] |
 | **existing_creative_id** | **String** | Meta only. Reuse an EXISTING ad creative by id instead of building a new one from the copy/media fields (which are then ignored). Combine with `existingCampaignId` to build a multi-ad-set campaign that shares one creative. Mutually exclusive with `creatives[]`, `dynamicCreative`, and `placementAssets`. The creative id used is returned as `creativeId` on the create response.  | [optional] |
 | **business_name** | **String** | Google Display only | [optional] |
@@ -121,7 +122,8 @@ instance = Zernio::CreateStandaloneAdRequest.new(
   billing_event: null,
   buying_type: null,
   rf_prediction_id: null,
-  creative_features: null,
+  promotion: null,
+  creative_features: {auto_promotion_tag=OPT_IN},
   multi_advertiser: null,
   validate_only: null,
   budget_amount: null,

data/docs/CreateStandaloneAdRequestCreativesInner.md

@@ -4,6 +4,8 @@
 
 | Name | Type | Description | Notes |
 | ---- | ---- | ----------- | ----- |
+| **promotion** | [**MetaPromotion**](MetaPromotion.md) | Overrides the top-level offer for this item. Omit to inherit; null disables the inherited offer. | [optional] |
+| **creative_features** | **Hash<String, String>** | Replaces the entire top-level creativeFeatures map for this item. Omit to inherit; an empty map clears these defaults. | [optional] |
 | **name** | **String** | Exact name for this ad. Falls back to `<name> #N` (N = 1-based position). | [optional] |
 | **headline** | **String** |  |  |
 | **body** | **String** |  |  |
@@ -19,6 +21,8 @@
 require 'zernio-sdk'
 
 instance = Zernio::CreateStandaloneAdRequestCreativesInner.new(
+  promotion: null,
+  creative_features: {auto_promotion_tag=OPT_IN},
   name: null,
   headline: null,
   body: null,

data/docs/CreateStandaloneAdRequestPromotedObject.md

@@ -11,8 +11,8 @@
 | **application_id** | **String** | App ID. Required for `goal: app_promotion`. | [optional] |
 | **object_store_url** | **String** | App Store / Play Store listing URL. Required for `goal: app_promotion`. | [optional] |
 | **custom_conversion_id** | **String** | Custom Conversion ID, when optimising against one instead of a standard event. Accepted alone by this API, without `pixelId` or `customEventType`. If `pixelId` is also sent, `customEventType` is still required on the promoted_object (Meta rejects `pixel_id` without `custom_event_type`, error_subcode 1885014).  | [optional] |
-| **product_catalog_id** | **String** | Catalog ID for catalog/Advantage+ Shopping campaigns. | [optional] |
-| **product_set_id** | **String** | Product Set ID inside the catalog. | [optional] |
+| **product_catalog_id** | **String** | Optional catalog ID. If supplied with productSetId, the set must belong to this catalog. A catalog ID cannot replace productSetId. | [optional] |
+| **product_set_id** | **String** | Meta product SET ID from GET /v1/ads/catalogs/{catalogId}/product-sets. Zernio checks that the token can read the set and its product_catalog before creation. A catalog ID or inaccessible set returns a precise 400 naming promotedObject.productSetId. A mismatch with productCatalogId names promotedObject.productCatalogId. | [optional] |
 | **offline_conversion_data_set_id** | **String** | Meta only. Offline event set (dataset) to optimise toward. Post-merger these are datasets: the id is the dataset id (for pixel-backed datasets, the pixel id). | [optional] |
 | **whatsapp_phone_number** | **String** | Meta only. WhatsApp number on messaging-destination ad sets. | [optional] |
 

data/docs/CtwaAdRequestBody.md

@@ -4,6 +4,7 @@
 
 | Name | Type | Description | Notes |
 | ---- | ---- | ----------- | ----- |
+| **creative_features** | **Hash<String, String>** | Meta enhancement settings for single or attached ads, and defaults for creatives[]. An item replaces the entire map, including with an empty object. | [optional] |
 | **account_id** | **String** | Facebook or Instagram SocialAccount ID. |  |
 | **ad_account_id** | **String** | Meta ad account ID, e.g. `act_123456789`. |  |
 | **name** | **String** | Ad display name. Used to derive campaign / ad set names. On the multi-creative shape, each ad's Meta name gets a \" #N\" suffix (1-indexed) so Ads Manager shows them as a numbered batch.  |  |
@@ -50,6 +51,7 @@
 require 'zernio-sdk'
 
 instance = Zernio::CtwaAdRequestBody.new(
+  creative_features: {auto_promotion_tag=OPT_IN},
   account_id: null,
   ad_account_id: null,
   name: null,

data/docs/CtwaAdRequestBodyCreativesInner.md

@@ -6,6 +6,7 @@
 | ---- | ---- | ----------- | ----- |
 | **existing_post_id** | **String** | Messaging and CTWA only. Platform post or reel ID, resolved like boost platformPostId. Facebook IDs become object_story_id; Instagram IDs become source_instagram_media_id using the connected Instagram identity. Mutually exclusive with objectStoryId and fresh creative fields. | [optional] |
 | **object_story_id** | **String** | Messaging and CTWA only. Raw Facebook pageId_postId reference, used as object_story_id even with an Instagram account. Mutually exclusive with existingPostId and fresh creative fields. | [optional] |
+| **creative_features** | **Hash<String, String>** | Replaces the top-level creativeFeatures map for this item. Omit to inherit; an empty object clears inherited enrollment choices. | [optional] |
 | **headline** | **String** |  | [optional] |
 | **body** | **String** | Primary text shown above the image / video. | [optional] |
 | **image_url** | **String** | Image asset. Mutually exclusive with this entry's `video`. Required if neither `video` nor an existing post reference is supplied.  | [optional] |
@@ -20,6 +21,7 @@ require 'zernio-sdk'
 instance = Zernio::CtwaAdRequestBodyCreativesInner.new(
   existing_post_id: null,
   object_story_id: null,
+  creative_features: {auto_promotion_tag=OPT_IN},
   headline: null,
   body: null,
   image_url: null,

data/docs/MetaPromotion.md

@@ -0,0 +1,26 @@
+# Zernio::MetaPromotion
+
+## Properties
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **type** | **String** | Promotion type accepted by Meta. PERCENTAGE_OFF values cannot exceed 100. |  |
+| **value** | **Float** | Nonnegative promotion value passed to Meta unchanged. AMOUNT_OFF units are not confirmed, including major versus minor currency units. For PERCENTAGE_OFF this is the percentage discount, at most 100. |  |
+| **code** | **String** | Optional promotion code. | [optional] |
+| **start_date** | **Time** | Optional ISO 8601 start timestamp with a timezone offset or Z. | [optional] |
+| **end_date** | **Time** | Optional ISO 8601 end timestamp with a timezone offset or Z. Must be after startDate when both are set. | [optional] |
+
+## Example
+
+```ruby
+require 'zernio-sdk'
+
+instance = Zernio::MetaPromotion.new(
+  type: null,
+  value: null,
+  code: null,
+  start_date: null,
+  end_date: null
+)
+```
+

data/docs/MetaPromotionStatus.md

@@ -0,0 +1,15 @@
+# Zernio::MetaPromotionStatus
+
+## Properties
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+
+## Example
+
+```ruby
+require 'zernio-sdk'
+
+instance = Zernio::MetaPromotionStatus.new()
+```
+

data/docs/UpdateAdRequestCreative.md

@@ -4,6 +4,8 @@
 
 | Name | Type | Description | Notes |
 | ---- | ---- | ----------- | ----- |
+| **promotion** | [**MetaPromotion**](MetaPromotion.md) |  | [optional] |
+| **creative_features** | **Hash<String, String>** | Meta Advantage+ creative enhancements. Map snake_case feature names to OPT_IN or OPT_OUT; Meta validates supported keys and unspecified features default to OPT_OUT. auto_promotion_tag is an enhancement; use the separate promotion field for an explicit offer. The deprecated standard_enhancements bundle is rejected by Meta. | [optional] |
 | **headline** | **String** | Meta and LinkedIn (TikTok has no headline slot) | [optional] |
 | **body** | **String** |  | [optional] |
 | **description** | **String** | Link description slot (Meta `link_data.description` / `video_data.link_description`, LinkedIn creative description). | [optional] |
@@ -20,6 +22,8 @@
 require 'zernio-sdk'
 
 instance = Zernio::UpdateAdRequestCreative.new(
+  promotion: null,
+  creative_features: {auto_promotion_tag=OPT_IN},
   headline: null,
   body: null,
   description: null,

data/lib/zernio-sdk/api/ad_campaigns_api.rb

@@ -523,7 +523,7 @@ module Zernio
     end
 
     # Create standalone ad
-    # Create a paid ad with custom creative across Meta, Google Ads, Pinterest, TikTok, X, LinkedIn, and OpenAI Ads (ChatGPT Ads).  Three mutually-exclusive request shapes are selected by the body:  - Legacy single-creative shape (all platforms, the default). - Meta-only multi-creative shape via the creatives array: one ad set with N ads sharing budget and targeting. - Attach shape via adSetId: adds one new ad to an existing ad set, inheriting its budget, targeting, and schedule (Meta, Google Ads, TikTok, and LinkedIn). On LinkedIn adSetId is the existing Campaign id, and the budget, schedule, targeting and bidding fields must be omitted.  Per-platform required fields, budget minimums, and video-ad rules are documented on each property below.  LinkedIn creates a Single Image or Single Video Ad backed by a Direct Sponsored Content \"dark post\" authored by a Company Page (see `organizationId`). Supported goals are engagement, traffic, awareness, and video_views (video ads use the `video` field; video_views requires a video), and traffic ads require `linkUrl`.  **Idempotency:** this endpoint is not idempotent at the platform level (a blind retry creates a second campaign/ad set/ad). Send an `Idempotency-Key` header to make retries safe: the first request with a given key creates the ad and we store the response; a retry with the same key replays that exact response (with `Idempotent-Replayed: true`) instead of creating duplicates. Reusing a key with a different body returns 422; a key whose first request is still in flight returns 409 (retry after a short backoff). Keys are scoped to your credential and expire after 24h. 
+    # Create a paid ad with custom creative across Meta, Google Ads, Pinterest, TikTok, X, LinkedIn, and OpenAI Ads (ChatGPT Ads).  Three mutually-exclusive request shapes are selected by the body:  - Legacy single-creative shape (all platforms, the default). - Meta-only multi-creative shape via the creatives array: one ad set with N ads sharing budget and targeting. - Attach shape via adSetId: adds one new ad to an existing ad set, inheriting its budget, targeting, and schedule (Meta, Google Ads, TikTok, and LinkedIn). On LinkedIn adSetId is the existing Campaign id, and the budget, schedule, targeting and bidding fields must be omitted.  Meta accepts `promotion` and `creativeFeatures` on the single and attach shapes and as defaults for `creatives[]`. An item replaces the whole feature map; its `promotion` replaces the default offer, and `promotion: null` disables that default for the item. Reusing `existingCreativeId` uses the existing creative settings instead of new settings. Requested settings are persisted for lists, exports, and default ad-detail reads. Only ads supplied a `promotion` receive live readback; multi-create batches those reads in groups of up to 50 IDs without per-ad fallback. Inspect `ad.creative.promotionStatus` (or `ads[].creative.promotionStatus`). `not_returned` means Meta omitted the metadata; successful creation does not by itself prove the offer was applied or will display.  Per-platform required fields, budget minimums, and video-ad rules are documented on each property below.  LinkedIn creates a Single Image or Single Video Ad backed by a Direct Sponsored Content \"dark post\" authored by a Company Page (see `organizationId`). Supported goals are engagement, traffic, awareness, and video_views (video ads use the `video` field; video_views requires a video), and traffic ads require `linkUrl`.  **Idempotency:** this endpoint is not idempotent at the platform level (a blind retry creates a second campaign/ad set/ad). Send an `Idempotency-Key` header to make retries safe: the first request with a given key creates the ad and we store the response; a retry with the same key replays that exact response (with `Idempotent-Replayed: true`) instead of creating duplicates. Reusing a key with a different body returns 422; a key whose first request is still in flight returns 409 (retry after a short backoff). Keys are scoped to your credential and expire after 24h. 
     # @param create_standalone_ad_request [CreateStandaloneAdRequest] 
     # @param [Hash] opts the optional parameters
     # @option opts [String] :idempotency_key Optional client-generated unique key (e.g. a UUID) that makes retries safe. Same key + same body replays the original response; same key + different body → 422; key still processing → 409.
@@ -534,7 +534,7 @@ module Zernio
     end
 
     # Create standalone ad
-    # Create a paid ad with custom creative across Meta, Google Ads, Pinterest, TikTok, X, LinkedIn, and OpenAI Ads (ChatGPT Ads).  Three mutually-exclusive request shapes are selected by the body:  - Legacy single-creative shape (all platforms, the default). - Meta-only multi-creative shape via the creatives array: one ad set with N ads sharing budget and targeting. - Attach shape via adSetId: adds one new ad to an existing ad set, inheriting its budget, targeting, and schedule (Meta, Google Ads, TikTok, and LinkedIn). On LinkedIn adSetId is the existing Campaign id, and the budget, schedule, targeting and bidding fields must be omitted.  Per-platform required fields, budget minimums, and video-ad rules are documented on each property below.  LinkedIn creates a Single Image or Single Video Ad backed by a Direct Sponsored Content \"dark post\" authored by a Company Page (see `organizationId`). Supported goals are engagement, traffic, awareness, and video_views (video ads use the `video` field; video_views requires a video), and traffic ads require `linkUrl`.  **Idempotency:** this endpoint is not idempotent at the platform level (a blind retry creates a second campaign/ad set/ad). Send an `Idempotency-Key` header to make retries safe: the first request with a given key creates the ad and we store the response; a retry with the same key replays that exact response (with `Idempotent-Replayed: true`) instead of creating duplicates. Reusing a key with a different body returns 422; a key whose first request is still in flight returns 409 (retry after a short backoff). Keys are scoped to your credential and expire after 24h. 
+    # Create a paid ad with custom creative across Meta, Google Ads, Pinterest, TikTok, X, LinkedIn, and OpenAI Ads (ChatGPT Ads).  Three mutually-exclusive request shapes are selected by the body:  - Legacy single-creative shape (all platforms, the default). - Meta-only multi-creative shape via the creatives array: one ad set with N ads sharing budget and targeting. - Attach shape via adSetId: adds one new ad to an existing ad set, inheriting its budget, targeting, and schedule (Meta, Google Ads, TikTok, and LinkedIn). On LinkedIn adSetId is the existing Campaign id, and the budget, schedule, targeting and bidding fields must be omitted.  Meta accepts `promotion` and `creativeFeatures` on the single and attach shapes and as defaults for `creatives[]`. An item replaces the whole feature map; its `promotion` replaces the default offer, and `promotion: null` disables that default for the item. Reusing `existingCreativeId` uses the existing creative settings instead of new settings. Requested settings are persisted for lists, exports, and default ad-detail reads. Only ads supplied a `promotion` receive live readback; multi-create batches those reads in groups of up to 50 IDs without per-ad fallback. Inspect `ad.creative.promotionStatus` (or `ads[].creative.promotionStatus`). `not_returned` means Meta omitted the metadata; successful creation does not by itself prove the offer was applied or will display.  Per-platform required fields, budget minimums, and video-ad rules are documented on each property below.  LinkedIn creates a Single Image or Single Video Ad backed by a Direct Sponsored Content \"dark post\" authored by a Company Page (see `organizationId`). Supported goals are engagement, traffic, awareness, and video_views (video ads use the `video` field; video_views requires a video), and traffic ads require `linkUrl`.  **Idempotency:** this endpoint is not idempotent at the platform level (a blind retry creates a second campaign/ad set/ad). Send an `Idempotency-Key` header to make retries safe: the first request with a given key creates the ad and we store the response; a retry with the same key replays that exact response (with `Idempotent-Replayed: true`) instead of creating duplicates. Reusing a key with a different body returns 422; a key whose first request is still in flight returns 409 (retry after a short backoff). Keys are scoped to your credential and expire after 24h. 
     # @param create_standalone_ad_request [CreateStandaloneAdRequest] 
     # @param [Hash] opts the optional parameters
     # @option opts [String] :idempotency_key Optional client-generated unique key (e.g. a UUID) that makes retries safe. Same key + same body replays the original response; same key + different body → 422; key still processing → 409.
@@ -798,7 +798,7 @@ module Zernio
     end
 
     # Duplicate an ad
-    # Duplicates a single ad via Meta's native `POST /{ad-id}/copies`. The copy is created paused. `adSetId` retargets the copy into another ad set; omitted = the source's own ad set. Accepts the Zernio ad id or the platform ad id. Sync discovery is triggered automatically (`syncAfter: false` to skip).
+    # Duplicates a single ad via Meta's native `POST /{ad-id}/copies`. The copy is created paused. `adSetId` retargets the copy into another ad set; omitted = the source's own ad set. Accepts the Zernio ad id or the platform ad id. Sync discovery is triggered automatically (`syncAfter: false` to skip). Creative settings returned by Meta, including explicit promotion metadata and creativeFeatures, are preserved when the native copy requires a creative rebuild. Metadata Meta does not return cannot be recovered.
     # @param ad_id [String] Zernio ad ID or platform ad ID
     # @param [Hash] opts the optional parameters
     # @option opts [String] :idempotency_key Optional client-generated unique key (e.g. a UUID) that makes retries safe. Same key + same body replays the original response; same key + different body → 422; key still processing → 409. Only 2xx responses are stored, so a request that failed with a 4xx can be retried with a corrected body under the SAME key.
@@ -810,7 +810,7 @@ module Zernio
     end
 
     # Duplicate an ad
-    # Duplicates a single ad via Meta's native `POST /{ad-id}/copies`. The copy is created paused. `adSetId` retargets the copy into another ad set; omitted = the source's own ad set. Accepts the Zernio ad id or the platform ad id. Sync discovery is triggered automatically (`syncAfter: false` to skip).
+    # Duplicates a single ad via Meta's native `POST /{ad-id}/copies`. The copy is created paused. `adSetId` retargets the copy into another ad set; omitted = the source's own ad set. Accepts the Zernio ad id or the platform ad id. Sync discovery is triggered automatically (`syncAfter: false` to skip). Creative settings returned by Meta, including explicit promotion metadata and creativeFeatures, are preserved when the native copy requires a creative rebuild. Metadata Meta does not return cannot be recovered.
     # @param ad_id [String] Zernio ad ID or platform ad ID
     # @param [Hash] opts the optional parameters
     # @option opts [String] :idempotency_key Optional client-generated unique key (e.g. a UUID) that makes retries safe. Same key + same body replays the original response; same key + different body → 422; key still processing → 409. Only 2xx responses are stored, so a request that failed with a 4xx can be retried with a corrected body under the SAME key.
@@ -1037,9 +1037,10 @@ module Zernio
     end
 
     # Get ad details
-    # Returns an ad with its creative, targeting, status, and performance metrics.  The `{adId}` path segment accepts any identifier dialect Zernio indexes for the ad: - the Zernio internal `_id` (24-char hex) - Meta's numeric `platformAdId` (the value shipped in `comment.received` webhooks as `comment.ad.id`) - the creative's `effective_object_story_id` (`{pageId}_{postId}` shape, Facebook side) - the creative's `effective_instagram_media_id` (Instagram side)  Any of the four resolve to the same ad. Caller doesn't need a translation step. 
+    # Returns an ad with its creative, targeting, status, and performance metrics.  The `{adId}` path segment accepts any identifier dialect Zernio indexes for the ad: - the Zernio internal `_id` (24-char hex) - Meta's numeric `platformAdId` (the value shipped in `comment.received` webhooks as `comment.ad.id`) - the creative's `effective_object_story_id` (`{pageId}_{postId}` shape, Facebook side) - the creative's `effective_instagram_media_id` (Instagram side)  Any of the four resolve to the same ad. Caller doesn't need a translation step. By default, creative.promotion and creative.creativeFeatures contain stored requested settings, which do not confirm platform application. With `refreshPromotion=true`, Meta promotion metadata is read live and exposed as `ad.creative.promotion` with `promotionStatus`. Only `applied` confirms an offer; `not_returned` means the creative read succeeded without promotion metadata, and `unavailable` means it failed. 
     # @param ad_id [String] Zernio `_id` (hex), Meta `platformAdId` (numeric), or one of the creative's effective story/media IDs. See description for details. 
     # @param [Hash] opts the optional parameters
+    # @option opts [Boolean] :refresh_promotion Meta only. Read current promotion metadata from Meta and include promotionStatus. Omit for stored creative settings with no promotion-specific Graph call. (default to false)
     # @return [GetAd200Response]
     def get_ad(ad_id, opts = {})
       data, _status_code, _headers = get_ad_with_http_info(ad_id, opts)
@@ -1047,9 +1048,10 @@ module Zernio
     end
 
     # Get ad details
-    # Returns an ad with its creative, targeting, status, and performance metrics.  The `{adId}` path segment accepts any identifier dialect Zernio indexes for the ad: - the Zernio internal `_id` (24-char hex) - Meta's numeric `platformAdId` (the value shipped in `comment.received` webhooks as `comment.ad.id`) - the creative's `effective_object_story_id` (`{pageId}_{postId}` shape, Facebook side) - the creative's `effective_instagram_media_id` (Instagram side)  Any of the four resolve to the same ad. Caller doesn't need a translation step. 
+    # Returns an ad with its creative, targeting, status, and performance metrics.  The `{adId}` path segment accepts any identifier dialect Zernio indexes for the ad: - the Zernio internal `_id` (24-char hex) - Meta's numeric `platformAdId` (the value shipped in `comment.received` webhooks as `comment.ad.id`) - the creative's `effective_object_story_id` (`{pageId}_{postId}` shape, Facebook side) - the creative's `effective_instagram_media_id` (Instagram side)  Any of the four resolve to the same ad. Caller doesn't need a translation step. By default, creative.promotion and creative.creativeFeatures contain stored requested settings, which do not confirm platform application. With `refreshPromotion=true`, Meta promotion metadata is read live and exposed as `ad.creative.promotion` with `promotionStatus`. Only `applied` confirms an offer; `not_returned` means the creative read succeeded without promotion metadata, and `unavailable` means it failed. 
     # @param ad_id [String] Zernio `_id` (hex), Meta `platformAdId` (numeric), or one of the creative's effective story/media IDs. See description for details. 
     # @param [Hash] opts the optional parameters
+    # @option opts [Boolean] :refresh_promotion Meta only. Read current promotion metadata from Meta and include promotionStatus. Omit for stored creative settings with no promotion-specific Graph call. (default to false)
     # @return [Array<(GetAd200Response, Integer, Hash)>] GetAd200Response data, response status code and response headers
     def get_ad_with_http_info(ad_id, opts = {})
       if @api_client.config.debugging
@@ -1064,6 +1066,7 @@ module Zernio
 
       # query parameters
       query_params = opts[:query_params] || {}
+      query_params[:'refreshPromotion'] = opts[:'refresh_promotion'] if !opts[:'refresh_promotion'].nil?
 
       # header parameters
       header_params = opts[:header_params] || {}

data/lib/zernio-sdk/api/ad_creatives_api.rb

@@ -20,7 +20,7 @@ module Zernio
       @api_client = api_client
     end
     # Create a standalone creative
-    # Creates a creative in the library WITHOUT an ad, reusable on the create endpoints via `existingCreativeId`. Provide exactly one of `imageUrl` (uploaded server-side), `imageHash` (from POST /v1/ads/images or the library list), or `carouselCards` (2-10 hand-built cards). The Page (and linked Instagram account, when present) is resolved from `accountId` as the story actor.
+    # Creates a creative in the library WITHOUT an ad, reusable on the create endpoints via `existingCreativeId`. Provide exactly one of `imageUrl` (uploaded server-side), `imageHash` (from POST /v1/ads/images or the library list), or `carouselCards` (2-10 hand-built cards). The Page (and linked Instagram account, when present) is resolved from `accountId` as the story actor. `promotion` configures an explicit offer separately from Advantage+ `creativeFeatures`. Only when `promotion` is supplied does the response read the creative back from Meta; `promotionStatus: not_returned` means Meta accepted creation but omitted promotion metadata, so the requested offer is not confirmed as applied.
     # @param create_ad_creative_request [CreateAdCreativeRequest] 
     # @param [Hash] opts the optional parameters
     # @return [CreateAdCreative201Response]
@@ -30,7 +30,7 @@ module Zernio
     end
 
     # Create a standalone creative
-    # Creates a creative in the library WITHOUT an ad, reusable on the create endpoints via `existingCreativeId`. Provide exactly one of `imageUrl` (uploaded server-side), `imageHash` (from POST /v1/ads/images or the library list), or `carouselCards` (2-10 hand-built cards). The Page (and linked Instagram account, when present) is resolved from `accountId` as the story actor.
+    # Creates a creative in the library WITHOUT an ad, reusable on the create endpoints via `existingCreativeId`. Provide exactly one of `imageUrl` (uploaded server-side), `imageHash` (from POST /v1/ads/images or the library list), or `carouselCards` (2-10 hand-built cards). The Page (and linked Instagram account, when present) is resolved from `accountId` as the story actor. `promotion` configures an explicit offer separately from Advantage+ `creativeFeatures`. Only when `promotion` is supplied does the response read the creative back from Meta; `promotionStatus: not_returned` means Meta accepted creation but omitted promotion metadata, so the requested offer is not confirmed as applied.
     # @param create_ad_creative_request [CreateAdCreativeRequest] 
     # @param [Hash] opts the optional parameters
     # @return [Array<(CreateAdCreative201Response, Integer, Hash)>] CreateAdCreative201Response data, response status code and response headers
@@ -505,7 +505,7 @@ module Zernio
     end
 
     # List a catalog's product sets
-    # Lists a Meta product catalog's product sets, the unit a catalog ad promotes. Pass the chosen set as `promotedObject.productSetId` on POST /v1/ads/create with `goal: catalog_sales`.
+    # Lists a Meta product catalog's product sets, the unit a catalog ad promotes. Pass the chosen set id, not the parent catalog id, as `promotedObject.productSetId` on POST /v1/ads/create with `goal: catalog_sales`. Creation verifies set visibility and returns 400 for a catalog id or an inaccessible set.
     # @param catalog_id [String] Meta product catalog ID (from GET /v1/ads/catalogs)
     # @param account_id [String] A facebook, instagram, or metaads account ID
     # @param [Hash] opts the optional parameters
@@ -516,7 +516,7 @@ module Zernio
     end
 
     # List a catalog&#39;s product sets
-    # Lists a Meta product catalog&#39;s product sets, the unit a catalog ad promotes. Pass the chosen set as &#x60;promotedObject.productSetId&#x60; on POST /v1/ads/create with &#x60;goal: catalog_sales&#x60;.
+    # Lists a Meta product catalog&#39;s product sets, the unit a catalog ad promotes. Pass the chosen set id, not the parent catalog id, as &#x60;promotedObject.productSetId&#x60; on POST /v1/ads/create with &#x60;goal: catalog_sales&#x60;. Creation verifies set visibility and returns 400 for a catalog id or an inaccessible set.
     # @param catalog_id [String] Meta product catalog ID (from GET /v1/ads/catalogs)
     # @param account_id [String] A facebook, instagram, or metaads account ID
     # @param [Hash] opts the optional parameters