Skip to content
biticaretdevelopers

Apps

App configuration files

How biticaret.app.toml and biticaret.extension.toml work, environments, and what the checks look at.

An app keeps its configuration in TOML files inside its project folder. The CLI builds manifest.json and the upload bundle from these files, and the platform runs the same checks on upload. This page explains how each file works; the generated reference pages list every key.

my-app/
  biticaret.app.toml
  biticaret.app.staging.toml        # optional: environment-specific override
  extensions/
    tier-discount/
      biticaret.extension.toml
      ...

biticaret.app.toml

This file defines the app itself: its identity, URLs, requested scopes and customer data level, webhook subscriptions, privacy endpoints, app proxy, embedded admin page, payment endpoints (for payment apps), and SMS provider flags. Any URL in this file can be written as a relative path resolved against the origin of application_url.

toml
client_id = "..."
handle = "my-app"
name = "My app"
application_url = "https://app.example.com"

[access_scopes]
scopes = ["read_products", "read_customers"]

[customer_data]
level = 1
reason = "To add loyalty points to the customer's account."

[auth]
redirect_urls = ["/auth/callback"]

[privacy]
customers_data_request_url = "/webhooks/customers/data_request"
customers_redact_url = "/webhooks/customers/redact"
store_redact_url = "/webhooks/store/redact"

[[webhooks.subscriptions]]
topics = ["products/update"]
uri = "/webhooks"

Relative paths resolve against the origin of application_url: with application_url = "https://app.example.com/app", the path /auth/callback resolves to https://app.example.com/auth/callback.

application_url and redirect_urls may not have a query (anything from ?) or a # fragment: the platform adds its own signed query to them, and the signature covers the whole query. The configuration check refuses such a URL.

Customer data level. An app whose scopes or features access customer data must include a [customer_data] block. level is 0 (no customer data), 1 (customer data without names or contact details) or 2 (including names and contact details). For level 1 or 2, reason (up to 1,000 characters) explains why the app needs that access. The requested level is approved during version review and determines which fields the API and webhooks return: see App API.

Large responses through the app proxy. An app that serves large files through its proxy can request extended limits by setting app_proxy.large_responses = true and large_responses_reason. Once approved by the platform, GET and HEAD limits increase to 120 seconds and 256 MiB. Requesting large responses never causes a version to be rejected; if not approved, the version simply runs with standard limits.

SMS provider. Setting sms_provider = true registers the app as an SMS provider that stores can select (requires write_sms). The app receives transactional notification messages via the sms/send webhook. Setting sms_commercial = true additionally allows sending campaign SMS messages through the IYS filter and syncing store consents to IYS via iys/consent: see Webhooks.

All keys: biticaret.app.toml keys. Scopes: Scopes. Topics: Webhook topics.

Use environments

biticaret.app.<env>.toml holds environment-specific configuration with that environment's own client_id. For example, biticaret.app.staging.toml can point to a separate staging app with its own application_url.

  • biticaret app config use <env> sets that environment as the default; biticaret app config use default reverts to biticaret.app.toml.
  • --config <env> selects an environment for a single command.
  • app config link --config <env> writes the file from the platform's copy of the app. If the file already exists without a client_id line, the CLI preserves your file and adds only client_id—making it easy to copy biticaret.app.toml, adjust application_url, and link it to a staging app.

Because environment files reference specific app instances, you can keep them out of git.

biticaret.extension.toml

Each folder under extensions/ defines one extension with its own biticaret.extension.toml. The type key determines the extension kind: theme (theme app blocks), function (a checkout function), ui_extension (a UI extension) or web_pixel. Remaining keys depend on type.

toml
type = "function"
handle = "tier-discount"
function_type = "discount"
title = "Tier discount"

[build]
command = "tinygo build -o tier-discount.wasm -target wasi ."
path = "tier-discount.wasm"

When a UI extension setting's default is "https://APPBASE", the CLI substitutes the scheme and host of application_url at build time (https://app.example.com), so each environment's extension calls that environment's backend.

biticaret app generate extension --type <type> --name <name> scaffolds an extension from its type template. Keys per type: biticaret.extension.toml keys. Function types: Checkout functions. Targets: UI extension targets.

Each app is limited to at most 30 theme app blocks, 25 checkout functions, 25 UI extensions, 10 web pixels and 50 webhook subscriptions. Across blocks/, snippets/ and assets/, a theme extension can contain at most 200 files, with each Liquid file at most 100 KB and total assets at most 10 MB.

What the checks look at

biticaret app check validates all configuration files locally and reports each issue with its file, line and key. On upload, the platform runs two additional checks that depend on platform state: ensuring no other app already claims the same app_proxy subpath, and ensuring only first-party apps request restricted first-party scopes (such as write_emails).