Create a promo

A promo defines the timing and tiers used by countdowns and promo-aware checkout. Start with a short test campaign so you can check its expiry before using it with customers.

Before you start

Use the intended Plandalf organization and its public SDK host. The promo and SDK must belong to the same organization. Open Settings → Organization and confirm the Subdomain field. New organizations receive one during creation. A working admin session alone does not establish that the SDK host matches the selected organization.

For checkout price changes, prepare the checkout and its prices first. A standalone countdown can be checked without taking a payment.

Create the campaign

1. Open Promos → Create Promo.
2. Enter a name, such as HTML timer test. Plandalf generates the campaign slug.
3. Under Connect your marketing stack, choose your page platform. For a plain HTML test, select Custom HTML. Select Plandalf for checkout when you intend to connect a Plandalf offer; leave email as None for a timer-only check.
4. Choose Evergreen and set a short duration, such as 3 minutes. Leave Starts blank for this replay.
5. Click Create promo. The editor opens on Tiers with a Standard tier and the duration you entered.

The current creation screen enables Evergreen and Tripwire. Options marked SOON, including fixed-date and quantity campaign presets, cannot be selected. This guide follows the Evergreen path.

Configure the tiers

• Review the Label and This tier has a time limit fields. The example starts with 3 Minutes from enrollment.
• Set Destination URL if visitors should navigate to a page while that tier is active. Leave redirects disabled in your first SDK check.
• For price changes, choose the intended Checkout, then enable Change the cart price when this tier is active and select the corresponding price. Verify the charged amount separately.
• Use Add tier for another phase. For a permanent fallback, turn off This tier has a time limit on the final tier.
• Click Save promo after editing.

Connect two checkout prices

This example uses one checkout item with two one-time USD prices: Early bird USD 25 and Standard USD 50.

1. On Tiers, select your checkout in the Checkout field.
2. Name the first tier Early bird. Enable Change the cart price when this tier is active.
3. Select the Checkout item, then the 25.00 USD price. Keep its 3 Minutes from enrollment time limit.
4. Click Add tier, name it Standard, and turn off This tier has a time limit.
5. Enable the second tier’s cart-price change. Select the same checkout item and its 50.00 USD price.
6. Leave both destination URLs blank for this price-only check. Click Save promo, wait for saving to finish, then reload and confirm the mapping.

Mounting a countdown and applying a promo to checkout are separate steps. Pass the same campaign identifier to the checkout’s promo option, as shown below. Verify the actual checkout amount before the deadline and again after closing and reopening it once the final tier is active.

Enroll a test visitor

Use this path when the countdown should begin before an identified visitor opens your page.

1. Open the campaign’s Promo tab and click Enroll above the participant table.
2. Enter a synthetic, non-sensitive Ref, such as demo-visitor-001. Leave the optional email blank for this test.
3. Click Enroll and confirm the participant appears with the expected tier and deadline.
4. Open your test page with ?pf_ref=demo-visitor-001. If its URL already has query parameters, append &pf_ref=demo-visitor-001 instead.
5. Use the same reference throughout the countdown and checkout replay. Compare the countdown with the participant’s deadline, then reload to confirm it has not restarted.

Enrollment starts the timer immediately. Allow enough time to open checkout before the deadline. A pf_ref value identifies this promo visitor; affiliate partner tracking uses its own parameter, usually via.

Check the public countdown

New campaigns in the current editor are labelled Live after creation. There is no separate publish step in this flow. That label does not prove that the public countdown configuration is available.

Copy the campaign identifier from its Promo tracking link and use the same organization’s SDK host. Follow Embedded promos or the Custom HTML countdown example to mount it on a test page.

Verify all of the following:

1. The actual widget resolves the intended promo and starts counting down.
2. Reloading in the same browser preserves the visitor’s original deadline.
3. The timed tier expires and the next tier or final expiry state appears.
4. Any configured redirect reaches the intended destination.
5. If you enabled tier pricing, checkout shows the expected amount before and after the deadline.

If the promo cannot be resolved, check the organization host and campaign identifier first. An organization without a public subdomain cannot publish its countdown configuration. Resolve that setup issue before treating Live or the editor preview as a successful integration.

Apply to checkout

await plandalf.present("summit-ticket", {
  promo: "early-bird",
  mode: "test"
});

In the local replay, the actual checkout displayed Early bird USD 25 before the deadline. After the real tier-change event, closing and reopening it displayed Standard USD 50. Both opens requested test mode. The organization had no payment provider, so no purchase was attempted.

Keep checkout open across expiry

Repeat the check with a newly enrolled test reference. Open checkout while the early tier is active and leave it open until that participant’s deadline. Confirm the item and total change to the fallback price without closing the checkout.

In the local enrolled-visitor replay, the open checkout changed from USD 25 to USD 50 at the saved deadline. The server session total also changed to USD 50. The session’s stored tier label remained Early bird, so tier reporting and payment-time enforcement still need verification.

Before using this with buyers, complete sandbox purchases on both sides of the deadline and reconcile the charged amount with the invoice. Include a purchase from a checkout kept open across expiry. Verify the released application and SDK together; a local price-display check does not establish payment-time enforcement.

Read promo state

Use the ready callback’s sdk.promo(slug, options) to read the current promo state from your storefront code.

The returned handle keeps monitoring after its first result resolves. For a one-time read, disable redirects and close it as below. Otherwise the default monitor can navigate to the active tier’s configured URL. Handle a null result when the promo cannot be resolved.

plandalf('ready', async sdk => {
  const handle = sdk.promo("early-bird", { redirect: false });
  try {
    const promo = await handle;
    console.log(promo?.activeTier?.label, promo?.remaining);
  } finally {
    handle.close();
  }
});

Related docs

• Pricing models
• Countdown timers
• Embedded promos