> For the complete documentation index, see [llms.txt](https://docs.amply.tools/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.amply.tools/recipes/seasonal-campaigns.md).

# Seasonal campaigns

Ship a time-bound campaign — Black Friday, World Cup, app anniversary — by activating and cancelling a dashboard campaign on a planned calendar.

**Use this when** the promotion has a clear start and end date and you want to avoid shipping two app releases around it. **Don't use this when** the offer is permanent; evergreen offers belong in the default paywall, not a campaign.

## Goal

Seasonal promos historically mean a rushed release the week before, a second release to take the banner down, and a third if the end date slips. This recipe replaces the release cycle with a single dashboard campaign that an operator activates on the start date and cancels on the end date — no code ships between the two dates.

## Setup

### In the dashboard

* Create a campaign `bf-2026-annual-50off` and keep it in `Draft` state while you prepare it.
* Trigger: session start, plus a second campaign triggered on `CheckoutOpened` so the user sees the banner both passively and at intent.
* Audience: free users in markets where the offer is valid (`country` in `["US", "CA", "GB", "DE"]`).
* Action: fire `yourapp://paywall/black-friday` pointing to a holiday-themed paywall with the 50%-off annual SKU.
* Frequency: once per session, capped at four sessions total.
* On the planned start date, move the campaign to `Active`. On the end date, move it to `Cancel`. The default paywall campaign stays running throughout and reclaims every session once the seasonal campaign is cancelled.

### In the app (engineering hand-off)

* Ship the seasonal paywall screen in a release before the start date. Remote scheduling cannot introduce new screens.
* Ensure the correct SKU is approved in App Store Connect and Google Play well before the start date.
* Register the `yourapp://paywall/black-friday` deeplink.
* Set region on the user so targeting works:

  ```typescript
  await Amply.setCustomProperty('country', deviceCountry);
  ```

## How it runs

1. Before November 24, the campaign sits in `Draft`. The default paywall runs normally.
2. On the morning of November 24, the operator moves the campaign to `Active`. Users in the target markets who open the app from then on see the seasonal paywall.
3. During the window, users can hit the paywall up to four times across sessions. After that, the frequency cap silences it and the default paywall returns for that user.
4. A user outside the target countries never matches. They continue to see the default paywall throughout.
5. On December 2, the operator moves the campaign to `Cancel`. The default paywall immediately reclaims every session.
6. The team reviews the campaign report in the dashboard and decides whether to re-run the same campaign with tweaks for Cyber Monday next year.

## Metrics to watch

* View-to-purchase rate during the window versus the default paywall in the same window a year prior.
* Share of revenue from the seasonal SKU — cannibalization matters. If monthly revenue drops as annual-50off rises, check whether you pulled forward demand.
* Post-window cancel rate at day 30 and day 60. Discount-led cohorts often churn earlier.
* Regional split. If one country converts dramatically worse, the creative or the localization is off.

## Related

* [Paywall versioning](/recipes/paywall-versioning.md) — the underlying variant pattern this recipe relies on
* [Testing and rollout](/user-guide/testing-and-rollout.md) — previewing the campaign before it goes live
* [Creating a campaign](/user-guide/creating-a-campaign.md) — moving a campaign through Draft → Active → Cancel
* [Targeting an audience](/user-guide/targeting-an-audience.md) — country and segment filters
* [Campaign delivery](/concepts/campaign-delivery.md) — how overlapping campaigns are evaluated
* [AI-assisted integration](/getting-started/ai-assisted-integration.md) — describe this campaign in plain language and have your AI assistant build it


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.amply.tools/recipes/seasonal-campaigns.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.