create_microsoft_promotion_extension

Add a time-bound promotional offer (sale, discount, promo code) that shows under a Microsoft Ads (Bing) ad — flag a holiday occasion, pick the discount style (% off or $ off), optionally attach a promo code or "on orders over $X" qualifier, and set the start/end window. Standard for Black Friday, Cyber Monday, seasonal sales, flash discounts, holiday campaigns.

                ALSO KNOWN AS: promotion, promo, discount, sale, offer, coupon, promo code, voucher, deal, holiday sale, seasonal offer

                KEYWORDS: promotion, promo, promo code, coupon, sale, discount, offer, deal, black friday, cyber monday, holiday, christmas, summer sale, percent off, dollar off, $ off, voucher, microsoft ads, bing, extension

                WHEN TO USE:
                - "Set up a Black Friday 20% off Microsoft Ads promotion for our Pro plan"
                - "Add a Bing holiday promo extension with code SUMMER2026"
                - "Register a Microsoft Ads sale: $50 off orders over $200"

                WHEN NOT TO USE:
                - Permanent pricing tiers (not a limited-time discount) → use create_microsoft_price_extension
                - Plain "Free Shipping" badge → use create_microsoft_callout_extension
                - Same promotion for Google Ads → use create_google_promotion_extension

                INPUTS (required):
                - occasion: holiday/event tag (NONE if no specific occasion). Available: NONE, BACK_TO_SCHOOL, BLACK_FRIDAY, BOXING_DAY, CARNIVAL, CHINESE_NEW_YEAR, CHRISTMAS, CYBER_MONDAY, DIWALI, EASTER, EID_AL_ADHA, EID_AL_FITR, END_OF_SEASON, EPIPHANY, FALL_SALE, FATHERS_DAY, HALLOWEEN, HANUKKAH, HOLI, INDEPENDENCE_DAY, LABOR_DAY, MOTHERS_DAY, NATIONAL_DAY, NAVRATRI, NEW_YEARS, PARENTS_DAY, PASSOVER, RAMADAN, ROSH_HASHANAH, SINGLES_DAY, SONGKRAN, SPRING_SALE, ST_NICHOLAS_DAY, SUMMER_SALE, VALENTINES_DAY, WINTER_SALE, WOMENS_DAY, YEAR_END_GIFT.
                - url: landing page for the promotion.
                - item: what's on sale (1-20 chars). E.g. "Pro subscription".
                - category_type: discount style.
                    * MONETARY        → "$X off". Provide category_amount.
                    * UP_TO_MONETARY  → "Up to $X off". Provide category_amount.
                    * PERCENT         → "X% off". Provide category_percent (≤100).
                    * UP_TO_PERCENT   → "Up to X% off". Provide category_percent (≤100).
                - details_type: optional qualifier.
                    * NONE            → no qualifier.
                    * ON_ORDERS_OVER  → "on orders over $X". Provide details_amount.
                    * PROMO_CODE      → "with code XXXX". Provide details_promo_code (≤15 chars).
                - start_date / end_date: ISO-8601 in pattern "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'" (e.g. 2026-11-25T00:00:00.000Z). Both must be today or in the future.

                INPUTS (optional, see category_type / details_type above):
                - category_amount, category_percent, details_promo_code, details_amount.

                EXAMPLE — Black Friday 20% off Pro with promo code:
                create_microsoft_promotion_extension(
                    occasion="BLACK_FRIDAY",
                    url="https://example.com/sale",
                    item="Pro subscription",
                    category_type="PERCENT",   category_percent=20,
                    details_type="PROMO_CODE", details_promo_code="BF2026",
                    start_date="2026-11-25T00:00:00.000Z",
                    end_date="2026-11-30T23:59:59.000Z",
                )