ApexDocsOpen Apex
Merchants & developers

Price basis for value-bearing treatments

Choose and document the price source for treatments built against staging and production storefronts.

Apex can model staging and production storefronts as environments of one shop, or as two independent shops. A preview resolves domains for its shop and environment. It does not translate treatment values for whichever storefront happens to render them.

This distinction matters whenever a treatment displays a price, discount, shipping amount, threshold, or other value that can differ between storefronts.

Literal treatment values stay literal

Treatment artifacts store authored values. Mutation text and html fields and custom_js are delivered as saved; Apex does not recognize a price inside them or replace it with the current storefront's value.

For example, a treatment that contains 1,13 € will still display 1,13 € when previewed on a staging shop whose page currently shows 1,10 €. A successful staging preview proves that the saved treatment rendered. It does not prove that a hardcoded production price matches staging data, or that Apex selected a price for the previewed environment.

Before approving a value-bearing treatment, identify both:

  1. the shop and storefront domain used for QA; and
  2. the basis of every authored value (live page data, staging data, or production data).

Choose one pattern deliberately.

Read the live value from the page

Prefer a live-computed treatment when the value should follow the storefront being viewed. Read the authoritative value from the page DOM at apply time, derive the treatment copy or calculation from it, and re-evaluate after relevant SPA or product-variant updates.

This is usually the safest option for presentation-only treatments that must work unchanged across independently configured shops. Use stable selectors and fail closed: if the expected source value is absent or cannot be parsed, do not render a fabricated price.

Maintain one experiment per shop

When staging and production intentionally use different fixed values, create a separate experiment in each shop and author the values for that shop. QA and approve each experiment against its own storefront. Do not copy a production artifact to a staging shop and treat a visually successful render as price verification.

Record the basis when hardcoding

If a fixed production value is intentional, make the basis explicit in the QA evidence. Use a note such as:

text
Price basis: production. Hardcoded values were checked against <production URL or catalog evidence> on <date>. The staging storefront has independent prices and is used only to verify rendering.

List each fixed value when the treatment contains more than one. A screenshot without this note is ambiguous: it cannot tell a reviewer whether the displayed value came from the page, staging data, or production data.

Use environments within one shop

For a same-shop setup, attach the staging domain to a non-production environment. Install that environment's snippet tag on the staging storefront, and author the experiment in that environment with values checked against staging data. The tag delivers experiments assigned to its environment, and config delivery filters by environment_key.

When the experiment is ready, promote it to create a production draft. Promotion copies the treatment, including literal values. Re-check every storefront-dependent value against production data before you start the production experiment.

What environment_key does not do

Experiment.environment_key selects experiments for config delivery within one shop. It supports a same-shop staging workflow, but it never pairs two shops.

If a merchant's staging storefront is modeled as a separate shop, it remains fully independent. Each shop has its own shop_id, domains, experiments, variations, and configuration. An environment_key in one shop does not map that shop to another shop or translate treatment values between them.

First confirm whether the staging storefront is an environment of the production shop or a separate shop. Then use the matching value pattern above.

QA checklist

  • Confirm the active shop and preview domain.
  • Inventory every literal price, discount, threshold, and other storefront-dependent value in mutations and custom JavaScript.
  • For live-computed values, verify the source selector, parsing behavior, SPA/variant updates, and fail-closed state.
  • For per-shop experiments, verify that each shop's artifact contains its own values.
  • For same-shop environments, verify staging values before promotion and production values in the promoted draft.
  • For hardcoded production values, add an explicit Price basis: production note and cite the evidence used to validate them.
  • Treat the preview as rendering evidence, not as automatic price-source validation.