> For the complete documentation index, see [llms.txt](https://help.dollarlabs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.dollarlabs.io/dollarback-store-credit/earning-cashback-programs/set-up-birthday-rewards.md). # Set up birthday rewards {% embed url="" %} *This article's section starts at 1:08 in the video.* A birthday reward is a credit issued on the customer's birthday, or on the first day of their birthday month. You configure it once; DollarBack collects birthdays, schedules each customer's credit, and issues it automatically. ## Prerequisites * The floating widget active in your theme, since it contains the birthday form customers fill in ([Activate widgets in your theme](/dollarback-store-credit/getting-started/activate-widgets-in-your-theme.md)) ## Step 1: Create the program 1. Open **DollarBack admin → Home**, select the **Cashback** tab and click **Manage configurations**. Choose the **Birthday gift** type. 2. Set the credit amount (say $10) and optional start/end dates. 3. Choose the **Trigger**: * **Exact birthday date**: credit is issued on the customer's birthday. * **Birthday month**: credit is issued on the 1st of the customer's birthday month. 4. Set **Lifetime limit**: how many times each customer can receive the reward. It defaults to **1**, which makes it a one-time gift. For a reward every year, raise it (for example to 10). 5. Optionally set a **Cooldown** in days. If a customer submits their birthday fewer than this many days before it's due, the reward waits until the following year. This stops customers entering a date a few days away just to collect the credit. `0` means no restriction. 6. Optionally set an expiry in days. To keep a birthday-month reward inside the month, use **28 days**: it never runs into the next month, though in 30- and 31-day months it ends a few days early. 7. Save and enable the program.
Birthday gift editor with Lifetime limit 5, Trigger Exact birthday date, Cooldown 0 days, and a Reward section with Amount $10 and Credit expires 30 days.

The Birthday trigger section sets when the gift fires and how often. You set the expiry under Reward.

{% hint style="warning" %} The amount, expiry and lifetime limit are saved with each customer's birthday at the moment they submit it. Changing the program later applies to birthdays submitted afterwards, not to ones already scheduled. Settle these before you launch. {% endhint %} ## Step 2: Collect birthdays DollarBack needs to know each customer's birthday before it can schedule anything. There are two ways in: **The widget form (no work needed).** Once a birthday program is enabled, the floating widget's "ways to earn" area shows a birthday form to signed-in customers. When a customer submits their date, DollarBack stores it on their profile. **The Merchant API (for custom storefronts or your own forms).** Your server can submit a birthday with: ``` POST /api/v1/merchant/birthday ``` The request carries the customer ID, the birthday (day / month / year; the widget form asks for all three too), the birthday program's config ID, and the customer's currency, authenticated with your API key. Details and examples: [Merchant API: keys & endpoints](/dollarback-store-credit/developer-tools/merchant-api-keys-and-endpoints.md). Either way, the birthday is saved to the customer's profile (as a customer metafield), so it survives and doesn't need to be re-collected each year. ## Step 3: What happens on the day When a birthday is submitted, DollarBack computes the customer's **next eligible credit date** and queues a scheduled reward. On the date, the credit is issued automatically. The customer gets the birthday email (if enabled) and sees the balance in the widget and their account. Connected integrations receive a **Birthday Reward Credited** event ([Klaviyo integration](/dollarback-store-credit/integrations/klaviyo-integration.md)). If the lifetime limit allows another reward, the next one is scheduled for the same date a year later. You can watch the queue in **DollarBack admin → Analytics → Scheduled Rewards**: pending rewards show the customer and the date they'll fire; completed and failed entries stay visible for auditing. {% hint style="info" %} If the reward date has already passed this year when a customer submits their birthday, it is scheduled for **next** year; it isn't paid immediately or backdated. This includes submitting on the day itself, and, with the **Birthday month** trigger, submitting at any point during the birthday month (the reward date is the 1st). {% endhint %} ## Verify it works 1. Sign in to your storefront as a test customer and submit a birthday in the widget form. 2. In **Analytics → Scheduled Rewards**, confirm a pending entry exists for that customer with the expected date. 3. To see the payout end to end without waiting a year, submit a test birthday a day or two ahead and check the credit lands on the date. ## Common issues * No scheduled entry after submitting: the program may be disabled or outside its date window; check the program under **Home → Cashback** tab → **Manage configurations**. * The widget shows no birthday form: the program must be enabled and the customer signed in; see [A widget isn't showing on my store](/dollarback-store-credit/troubleshooting-and-faq/widget-isnt-showing.md). * The customer got the reward once and never again: the **Lifetime limit** is still at 1. Raising it only affects birthdays submitted afterwards. * Credit scheduled but never arrived: check the entry's status in **Scheduled Rewards**, then [A customer didn't receive cashback](/dollarback-store-credit/troubleshooting-and-faq/customer-didnt-receive-cashback.md). ## Related articles * [Cashback program types at a glance](/dollarback-store-credit/earning-cashback-programs/cashback-program-types-at-a-glance.md) * [Custom rewards via API](/dollarback-store-credit/earning-cashback-programs/custom-rewards-via-api.md) * [When credit is issued](/dollarback-store-credit/earning-cashback-programs/when-credit-is-issued.md) * [Credit logs & scheduled rewards](/dollarback-store-credit/analytics-data-and-account/credit-logs-and-scheduled-rewards.md)