Behio Storefront SDK
Customer

Newsletter

First-party newsletter subscribe and unsubscribe

Subscribe

First-party opt-in stored in Behio (the merchant owns the emails). No authentication needed:

const { data } = await client.newsletter.subscribe({
  email: '[email protected]',
  locale: 'cs',        // optional, preferred locale captured at signup
  source: 'footer',    // optional, where the opt-in came from ("footer", "checkout", ...)
});
// data: { success: true, alreadySubscribed: false, confirmationRequired?: true }

Subscribing is idempotent: one record per person and shop. The answer is the same for a new address, an existing subscriber and a rate limited request, so it never reveals who is on the list. alreadySubscribed stays in the response for older clients and is always false. Aliases count as one person: [email protected], [email protected] and [email protected] are the same buyer for subscriptions and rewards.

Pass consentText with the wording the visitor saw. Only its hash is stored, as proof of consent.

Honeypot

The input accepts an optional website field as a spam honeypot. Render it as a hidden input real users never fill; when a bot fills it, the API responds with success but stores nothing. Keep it empty (or omit it) in legitimate calls.

Unsubscribe

An address proves nothing, so unsubscribe(email) changes nothing yet: if the address is on the list, or belongs to a customer or an order of this shop, its owner receives an e-mail with a signed link. The answer is always the same, so it never reveals who is a customer:

await client.newsletter.unsubscribe('[email protected]');
// { success: true, confirmationRequired: true }

Every newsletter e-mail carries a signed one-click link and List-Unsubscribe headers, hosted by Behio, so you do not have to build anything. If you handle the token yourself:

await client.newsletter.unsubscribeWithToken(token);
// { success: true, confirmationRequired: false }

Checkout Opt-in

The checkout newsletter checkbox does not call subscribe directly. Pass the customer's choice as newsletterOptIn in checkout.createOrder, and render the checkbox default from ShopInfo.checkout.newsletterOptInDefault (CHECKED / UNCHECKED / HIDDEN).

React Hooks

import { useNewsletterSubscribe } from '@behio/storefront-sdk/react';

const subscribe = useNewsletterSubscribe();
subscribe.mutate({ email, source: 'footer' });

useNewsletterUnsubscribe() is the matching mutation: pass an address, or {token} for a signed link.

Confirmed subscription and first-order reward

Merchants can enable email confirmation in their checkout consent settings with newsletterDoubleOptIn. Set newsletterWelcomeDiscountPercent (0 disables the reward) and newsletterWelcomeValidDays (default 30). A reward requires email confirmation. Existing shops remain on their existing opt-in behavior until enabled.

When subscribe returns confirmationRequired: true, show a request to check email. The subscription is inactive until confirmation, and no reward is issued at signup. Do not claim the visitor is already subscribed or display a shared code.

The confirmation email links to a page hosted by Behio, so double opt-in works for every kind of site and needs no page of yours. The page loads no merchant or third party script and removes the token from the address bar. A custom flow can still confirm through the API, always after an explicit click, never on page load:

const {data, error} = await client.newsletter.confirm(token);
// data: {success: true, welcomeDiscountIssued: boolean}

The React hook is useNewsletterConfirm(). The code is delivered by email and never returned by subscribe or confirm. No customer account is required. Tokens expire in 24 hours, are single-use and scoped to the shop.

Rewards are personal, single-use percentage codes. Checkout requires the same buyer (aliases included) and no previous non-cancelled/non-refunded order, including guest orders and orders belonging to the signed-in customer. Eligibility is rechecked atomically at order creation, also for orders created in the admin. Changing email does not transfer the reward. Cancelling an order that was not shipped gives the same code back, once; it never issues a second reward.

Pending addresses are excluded from newsletter campaigns, but a pending request does not remove a customer from customer or segment campaigns. An active subscriber is never lowered by a new request; if it was never confirmed, it may still confirm and get the reward. At most 3 confirmation e-mails per address and shop in 24 hours, plus a cap per address across shops and per visitor and hour. Limits hold back the e-mail, never the record: the address appears in the admin and it says that no e-mail went out. Over the shop's hourly budget e-mails wait in the outbox and leave later, with a link valid for 24 hours from sending; a link that expired in the meantime is not sent at all, and the admin says that no e-mail went out. The merchant can send the confirmation again to an address with an unconfirmed request, at most 3 times and within 30 days of the request, under the same per-address limits; the new link replaces the old one. Not to a suppressed address, to somebody who is confirmed under another alias, or after an opt-out once the link is dead. The public answer does not change when a limit is reached. A person who unsubscribed, or was erased after unsubscribing, can come back only by confirming from their mailbox, in single opt-in too. Opening a used confirmation link again ends on the confirmed page while the subscription stands. Pass consentText with the wording shown: only its hash is stored, and without it the consent log records no wording. When a request comes from your own server rather than ours and carries x-behio-visitor-ip, that server's address is not the visitor's: neither is recorded, and instead of the per-visitor cap the server has its own cap of 120 per hour and shop. The per-address and shop limits still apply. A confirmation applies to the confirmed address: an old opt-out of an alias stays on that row, but no longer excludes the person, and one person gets one copy of a campaign. Delivery has a durable outbox with retries for at least 72 hours. The admin shows Pending, Confirmed, Unsubscribed, Link expired and Not subscribed (a customer who only asked for an opt-out link; such an address gave no consent and enters no audience), and whether the welcome was sent or failed. A provider accepting a message is not proof that the recipient's inbox received it.

Welcome automations

For an automatic welcome with no custom workflow, leave newsletterWelcomeAutomation off. A reward of 0 sends the standard welcome without a coupon.

For a custom workflow, enable email confirmation and newsletterWelcomeAutomation in checkout consent settings, then activate the Newsletter welcome recipe. The newsletter.subscribed event is queued durably only after explicit confirmation. The newsletter.welcome action accepts discountPercent (0 to 90), validDays (1 to 365), an alphanumeric prefix (up to 20 characters), and optional subject and plain-text message. Set the percentage to 0 for a welcome without a reward. The standard email appends coupon terms only when an eligible reward exists. An earlier purchaser receives the welcome without a first-order coupon.

Automation mode replaces the built-in welcome, and saving it requires an active automation with this action. If none is active at confirmation, or the action does not deliver within 15 minutes, the built-in welcome goes out instead, so nothing is lost. Both modes share the same lifetime reward and welcome-message deduplication. Retries, multiple matching rules and re-subscriptions cannot create a second welcome reward. An unsubscribed or unconfirmed recipient is rejected when the action runs, including delayed runs. Queue failure after confirmation is recovered from the newsletter outbox. discount.create in a newsletter event also uses the recipient-bound first-order reward, in single opt-in too; prefer newsletter.welcome for the complete durable email workflow. When no code is issued, or the code the person already has is inactive, expired or used up, the actions that follow are skipped and the run says why: an e-mail is never sent with an empty or dead code.

On this page