Skip to main content
Merchant notifications — new order, new subscription, renewal, cancellation, past due — are delivered to the recipients configured on the store. Each recipient has its own address and its own per-event subscription toggles, so two people on the same store can subscribe to different things. When a store has no recipients configured, notifications fall back to the store owner’s account email.

​
Event catalog

All nine toggles above are per recipient — including notifySubscriptionPlanChanged and notifyChargeback. Two people on the same store can subscribe to different events, and update-recipient accepts any of the nine.The delivery address follows the recipient list: merchant notifications go to the configured recipients, falling back to the store owner’s account email while the list is empty, rather than to supportEmail.

​
Limits

Each store may have at most 5 recipients. Exceeding the limit returns 400. There is no lower bound — but an empty list does not mean silence: it falls back to the store owner’s account email (see below). Consumer-facing transactional email (order receipts, subscription confirmations) is a separate pipeline and is unaffected.

​
The fallback recipient

While a store has no explicit recipients, the list contains exactly one synthesized entry with isPrimary: true: the address is the store owner’s account email, the toggles come from the store-level notify* settings, and createdAt is the store’s creation time. Its id is a stable sentinel of the form OWNER_<storeId>. It is not a stored row. remove-recipient on that id returns 404 — the account email is the fallback and cannot be deleted; add a real recipient to replace it. update-recipient on that id materializes it instead: the account email is written as a real recipient, your patch is applied on top, and the response carries a real UUID. Adding the first explicit recipient makes the fallback entry disappear. That is intentional and visible.

​
Environments

Recipients are not environment-scoped. Requests may carry X-Environment as usual, but it does not filter or shape recipient reads and writes — the same store returns the same list in test and in prod.

​
Listing recipients

There is no list-recipients endpoint — querying the recipient list goes through the top-level GraphQL query storeNotificationRecipients, which also returns the fallback entry when no explicit recipient is configured:

​
Endpoints

Add Recipient

Add an address that receives merchant notifications.

Update Recipient

Change which events a recipient subscribes to.

Remove Recipient

Remove a recipient from the list.