Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.scalev.com/llms.txt

Use this file to discover all available pages before exploring further.

Scalev HTML Mode pages can use window.Scalev from browser JavaScript. The runtime gives your page access to safe page context, selected store context, checkout helpers, analytics forwarding, form prefill helpers, and diagnostics without exposing private API tokens. This page is written for both developers and AI agents that generate HTML Mode files. If you are generating an HTML file for Scalev, use this reference instead of calling private Scalev URLs directly.

​
Availability

The runtime is available on rendered HTML Mode pages. In local editor previews, some methods can return stubbed preview data. Always guard runtime usage: 
const scalev = window.Scalev;

if (!scalev) {
  // Render fallback content or keep the page usable without runtime data.
}
Most methods are asynchronous and return a Promise. Scalev.data.get() and Scalev.diagnostics.get() are synchronous.

​
Store context

An HTML Mode page may or may not have Store Context selected in the Scalev editor. When Store Context is selected, Scalev.data.get().store includes only the selected store summary, selected products, and selected bundle price options. It does not include the full store catalog. When Store Context is not selected, store is not available. Do not build checkout, payment, shipping, discount, product catalog, cart, or order creation flows. Use the page as a regular landing page and rely only on page-safe methods such as Scalev.data.get(), Scalev.analytics.track(), and Scalev.prefill.get().

​
Security rules

  • Do not request or store API keys, business-user JWTs, storefront API keys, customer tokens, cookies, or credentials.
  • Do not call private Scalev URLs or private APIs directly from page JavaScript.
  • Use only documented window.Scalev methods.
  • Create orders only after a visitor intentionally submits a form.
  • Call Scalev.checkout.validateOrder() before Scalev.checkout.createOrder().
  • Do not assume unselected products, bundles, prices, inventory, payment methods, shipping options, or customer identity.

​
Scalev.data.get()

Returns public page data injected into the rendered page. 
const data = Scalev.data.get();
Return shape: 
{
  "page": {
    "id": 1,
    "uniqueId": "page_uid",
    "username": "brand"
  },
  "store": null
}
With Store Context selected, store contains selected context only: 
{
  "page": {
    "id": 1,
    "uniqueId": "page_uid",
    "username": "brand"
  },
  "store": {
    "id": 1,
    "unique_id": "store_uid",
    "name": "Main Store",
    "payment_methods": ["bank_transfer", "cod"],
    "sub_payment_methods": [],
    "products": [
      {
        "id": 1,
        "name": "Product",
        "variants": [
          {
            "id": 10,
            "unique_id": "variant_uid",
            "name": "Default",
            "price": 99000,
            "available_qty": 12
          }
        ]
      }
    ],
    "bundle_price_options": [
      {
        "id": 20,
        "unique_id": "bundle_option_uid",
        "name": "Bundle",
        "price": 179000
      }
    ]
  }
}
Use it to render selected products, bundle options, enabled payment methods, and store-aware forms. Do not assume products, bundles, or payment methods that are not present in this payload. store.payment_methods contains the enabled payment methods after Scalev filters the store settings by the business payment capabilities. Use store.sub_payment_methods for enabled VA or bank submethods when present.

​
Location methods

Use these methods for address and shipping forms. 
const provinces = await Scalev.location.provinces();
const cities = await Scalev.location.cities(provinceId);
const subdistricts = await Scalev.location.subdistricts(cityId);
const postalCodes = await Scalev.location.postalCodes(subdistrictId);
provinces, cities, and subdistricts accept optional query objects: 
const provinces = await Scalev.location.provinces({ q: "Jawa" });
const cities = await Scalev.location.cities(provinceId, { q: "Bandung" });
const subdistricts = await Scalev.location.subdistricts(cityId, {
  q: "Coblong",
});
Use IDs returned by each previous step. Do not hardcode location IDs unless the user explicitly provided them.

​
Scalev.checkout.validateDiscount(payload)

Validates a discount code for a checkout payload. 
const store = Scalev.data.get().store;

const result = await Scalev.checkout.validateDiscount({
  code: "PROMO10",
  grossRevenue: 179000,
  netProductPrice: 179000,
  shippingCost: 0,
  paymentMethod: store.sub_payment_methods?.[0] || "bank_transfer",
});
Accepted field names can be camelCase or snake_case:
  • code
  • grossRevenue or gross_revenue
  • netProductPrice or net_product_price
  • shippingCost or shipping_cost
  • pageUniqueId or page_unique_id
  • paymentMethod or payment_method
  • domain
pageUniqueId defaults to the current page, and domain defaults to the current hostname. Payment values are normalized before the request: BT_* values become bank_transfer, and values listed in store.sub_payment_methods become va. Use this only for store-connected checkout flows.

​
Scalev.checkout.searchWarehouses(payload)

Returns warehouse options for selected variants and destination. 
const data = Scalev.data.get();
const firstVariant = data.store.products[0].variants[0];

const warehouses = await Scalev.checkout.searchWarehouses({
  destinationSubdistrictId: selectedSubdistrictId,
  ordervariants: [{ variant_unique_id: firstVariant.unique_id, quantity: 1 }],
});
Accepted field names:
  • storeId, store_id, or store; if omitted, the runtime uses the selected Store Context.
  • destinationSubdistrictId, destination_subdistrict_id, subdistrictId, subdistrict_id, destinationId, destination_id, destination, locationId, location_id, or location
  • variants, orderVariants, or ordervariants: array of { variantId | variant_id | id | variant_unique_id | variantUniqueId | unique_id | uniqueId, qty | quantity }
  • orderId, order_id, or order when validating against an existing order flow
Use selected variants from Scalev.data.get().store.products. You may pass public variant_unique_id values; the runtime resolves them to the numeric variant_id expected by the old landing-page warehouse endpoint.

​
Scalev.checkout.searchCouriers(payload)

Returns courier service options for a store, destination, warehouse, and payment method. 
const firstWarehouse = warehouses.data?.[0] || warehouses[0];

const couriers = await Scalev.checkout.searchCouriers({
  paymentMethod: "cod",
  destinationSubdistrictId: selectedSubdistrictId,
  warehouse: firstWarehouse,
  weight: 1200,
});
Accepted field names:
  • storeId, store_id, or store; if omitted, the runtime uses the selected Store Context.
  • paymentMethod or payment_method
  • destinationSubdistrictId, destination_subdistrict_id, subdistrictId, subdistrict_id, locationId, location_id, destinationId, destination_id, destination, or location
  • warehouseId, warehouse_id, or warehouse. You can pass the warehouse object returned by searchWarehouses.
  • weight
Use this after the visitor has chosen products and a shipping destination. Scalev expects a numeric warehouse_id; the runtime extracts it from the warehouse object when possible.

​
Scalev.checkout.validateOrder(payload)

Validates order payload shape without creating an order. 
const data = Scalev.data.get();
const store = data.store;
const firstVariant = store.products[0].variants[0];

const validation = await Scalev.checkout.validateOrder({
  page: data.page.uniqueId,
  store: store.unique_id,
  customerName: "Customer Name",
  customerPhone: "08123456789",
  customerEmail: "customer@example.com",
  address: "Customer address",
  location: 12345,
  ordervariants: [{ variant_unique_id: firstVariant.unique_id, quantity: 1 }],
  paymentMethod: store.payment_methods[0] || "bank_transfer",
});
Response shape: 
{
  "valid": true,
  "normalized_payload": {
    "page_unique_id": "page_uid",
    "store_unique_id": "store_uid",
    "customer_name": "Customer Name",
    "customer_phone": "08123456789"
  },
  "warnings": []
}
If valid is false, inspect warnings and fix the form payload before creating an order. Common warnings include missing page id, store id, customer name, customer phone, or order items.

​
Scalev.checkout.createOrder(payload)

Creates a real public order. Call this only after a visitor intentionally submits the form and validateOrder has passed. 
async function submitOrder() {
  const data = Scalev.data.get();
  const store = data.store;
  const firstVariant = store.products[0].variants[0];

  const payload = {
    page: data.page.uniqueId,
    store: store.unique_id,
    customerName: "Customer Name",
    customerPhone: "08123456789",
    customerEmail: "customer@example.com",
    address: "Customer address",
    location: 12345,
    ordervariants: [{ variant_unique_id: firstVariant.unique_id, quantity: 1 }],
    paymentMethod: store.payment_methods[0] || "bank_transfer",
  };

  const validation = await Scalev.checkout.validateOrder(payload);
  if (!validation.valid) {
    return showValidationWarnings(validation.warnings);
  }

  const order = await Scalev.checkout.createOrder(payload);
  return order;
}
createOrder accepts the same public payload keys used by Scalev’s regular editor checkout flow. The runtime normalizes them before sending the order request:
  • Customer fields: customerName, customerPhone, customerEmail, name, phone, address
  • Store and page fields: store, page, plus aliases such as storeUniqueId, store_unique_id, pageUniqueId, and page_unique_id
  • Location and shipping fields: location, destinationSubdistrictId, subdistrictId, postalCode, shippingOrigin, courierService, shippingCost, and courierAggregator
  • Payment fields: paymentMethod, financialEntityId, paymentAccount, paymentAccountHolder, paymentAccountNumber, and subPaymentMethod
  • Item fields: ordervariants with { variant_unique_id, quantity }, orderbundles with { bundle_price_option_unique_id, quantity }, or legacy orderlines
  • Discount and pricing fields: discountCodeCode, productDiscount, shippingCost, shippingDiscount
Use unique_id values from Scalev.data.get().store; do not submit numeric product, variant, or bundle ids as order item identifiers. As with discount and shipping helpers, payment values are normalized before the request. BT_* values are sent as bank_transfer; enabled VA or bank submethods in store.sub_payment_methods are sent as payment_method: "va" with the selected submethod. Do not create orders automatically on page load. After createOrder succeeds, choose the post-order redirect yourself. The runtime creates the order only; it does not apply the Builder After Submit Event setting for you. See HTML Mode checkout success paths.

​
Scalev.analytics.track(providerOrPayload, payload?)

Forwards configured analytics events through Scalev. 
await Scalev.analytics.track("facebook", {
  firstName: "Customer",
  phone: "08123456789",
  variants: [{ unique_id: "variant_uid", quantity: 1, price: 179000 }],
  events: [
    {
      event_name: "Lead",
      parameters: { value: 179000, currency: "IDR" },
    },
  ],
});
You can also pass one object: 
await Scalev.analytics.track({
  provider: "tiktok",
  payload: {
    events: [
      {
        event: "CompletePayment",
        parameters: { value: 179000, currency: "IDR" },
      },
    ],
  },
});
Supported provider names:
  • fb
  • facebook
  • tiktok
  • kwai
The runtime forwards the legacy Scalev analytics payload shapes for each provider. It adds the current page id, event source URL, referrer, and safe attribution values from browser cookies or URL parameters when available. For Facebook and TikTok events, event_id is generated automatically when omitted. For product attribution, pass variants, orderVariants, or ordervariants with variant_unique_id / unique_id, and bundlePriceOptions, bundle_price_options, or orderbundles with bundle_price_option_unique_id / unique_id. Only track events that match the page interaction. Do not send credentials or private customer tokens in analytics payloads.

​
Scalev.prefill.get()

Reads safe browser-scoped form prefill data. 
const prefill = await Scalev.prefill.get();
const formData = prefill.data || {};
Return shape: 
{
  "data": {
    "customerName": "Customer Name",
    "customerPhone": "08123456789"
  }
}
Use this to repopulate form fields. Treat all values as optional.

​
Scalev.prefill.save(form, metadata?)

Saves safe form prefill data for later visits. 
await Scalev.prefill.save(
  {
    customerName: "Customer Name",
    customerPhone: "08123456789",
  },
  {
    source: "html_mode",
  },
);
Only save ordinary form values that are safe to remember. Do not save passwords, tokens, payment secrets, or private credentials.

​
Scalev.customer.prefill()

Returns a mediated customer profile when the visitor has an active storefront customer session. If no customer session is available, or if the customer lookup fails, it returns null. 
const customer = await Scalev.customer.prefill();

if (customer) {
  // Use mediated customer data.
}
The runtime calls a local Scalev endpoint so customer tokens stay server-side. Always handle null.

​
Scalev.diagnostics.get()

Returns recent runtime diagnostics for debugging. 
const diagnostics = Scalev.diagnostics.get();
Diagnostics can include failed runtime requests and, when ?agent_debug=1 is present, visual warnings such as horizontal overflow or unlabeled visible form controls. Do not build customer-facing logic from diagnostics; use it for debugging and QA only.

​
Minimal non-store example

Use this pattern when Store Context is not selected: 
<script>
  async function init() {
    const scalev = window.Scalev;
    const data = scalev?.data?.get
      ? scalev.data.get()
      : { page: {}, store: null };
    const prefill = scalev?.prefill?.get
      ? await scalev.prefill.get()
      : { data: {} };

    document.querySelector("[name='name']").value =
      prefill.data?.customerName || "";

    document.querySelector("form").addEventListener("submit", async (event) => {
      event.preventDefault();
      const form = Object.fromEntries(new FormData(event.currentTarget));
      await scalev?.prefill?.save?.(form, { source: "lead_form" });
    });
  }

  init();
</script>

​
Minimal store checkout example

Use this pattern only when Store Context is selected: 
<script>
  async function submitOrder(event) {
    event.preventDefault();

    const scalev = window.Scalev;
    const data = scalev.data.get();
    const store = data.store;
    const firstProduct = store.products[0];
    const firstVariant = firstProduct.variants[0];

    const payload = {
      page: data.page.uniqueId,
      store: store.unique_id,
      customerName: event.currentTarget.elements.customerName.value,
      customerPhone: event.currentTarget.elements.customerPhone.value,
      ordervariants: [
        { variant_unique_id: firstVariant.unique_id, quantity: 1 },
      ],
      paymentMethod: store.payment_methods[0] || "bank_transfer",
    };

    const validation = await scalev.checkout.validateOrder(payload);
    if (!validation.valid) {
      console.warn(validation.warnings);
      return;
    }

    const order = await scalev.checkout.createOrder(payload);
    console.log(order);
  }
</script>