# 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](api.md#customer-data-levels).

**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](webhooks.md#sms-send).

All keys: [biticaret.app.toml keys](../reference/app-toml.md). Scopes: [Scopes](../reference/scopes.md). Topics: [Webhook topics](../reference/webhook-topics.md).

## 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](../reference/extension-toml.md). Function types: [Checkout functions](../reference/checkout-functions.md). Targets: [UI extension targets](../reference/ui-extension-targets.md).

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`).
