# Your first theme and app

> Start from an empty folder and end with a theme and an app running on a development store.

This guide takes you from an empty folder to a theme and an app running on a development store. It walks through the steps in order; see the [CLI](cli.md) page for full command details.

The admin and the partner portal are in Turkish. This guide names their buttons and menus by their Turkish labels, with English glosses.

## What you need

- The `biticaret` CLI: see [Install the CLI](cli.md#install-the-cli).
- For a theme: `git` and `zip`.
- For an app: Go, and membership in a partner organisation with permission to work on apps.
- A development store. Your partner organisation creates them. They are free, their password protection cannot be turned off, and their checkout runs in test mode only, so they never process real sales.

## Build a theme

1. Start from the skeleton theme:

   ```bash
   biticaret theme init my-theme
   cd my-theme
   ```

2. Edit the files. [Theme structure](themes/structure.md) explains how a theme is organised.

3. Check the theme. This runs the same checks applied during upload:

   ```bash
   biticaret theme check --strict .
   ```

4. Zip the theme folders:

   ```bash
   zip -r ../my-theme.zip assets blocks config layout locales sections snippets templates
   ```

   Zip only the theme folders. The uploader rejects files outside them, such as `README.md`, `LICENSE`, `AGENTS.md` and `CLAUDE.md`.

5. In your development store's admin, upload the ZIP under **Online Mağaza > Temalar** (Online store > Themes). An uploaded theme arrives unpublished: preview it, and publish it when it's ready.

That's the loop: edit, run `theme check`, zip, upload and preview. Every upload creates a new unpublished theme, and a store can hold up to 20 themes. To get a theme's preview link from the terminal, run `biticaret theme list --store <handle>` ([CLI](cli.md#list-store-themes)).

## Get a partner account and a development store

You need a partner organisation to build apps. Themes don't require one: you can upload a theme to any store you manage in the admin.

1. Open the admin (the platform address used by `auth login`, `https://admin.biticaret.com.tr` by default). Create an account with **Hesap oluşturun** (Create an account) and verify your email address. An unverified account cannot apply.
2. Open the partner portal (`/partners`)—or follow **Partner olun** (Become a partner)—and fill out the **biticaret partneri olun** application form: your organisation's details, one or more purposes (`Uygulama geliştirme` for app development, `Müşteri mağazaları` for client stores, `Yönlendirme` for referrals, or `Diğer` for other), what you plan to build, and links to previous work if you have any, then click **Başvuruyu gönder** (Submit application). The biticaret team reviews each application manually. If a purpose is declined, you can reapply for it after 30 days. The review criteria and timelines will be published with the partner programme. While your application is pending, the portal shows only its status.
3. Once `Uygulama geliştirme` is approved, open the portal's **Mağazalar** (Stores) page and create a `Geliştirme mağazası` (Development store) with **Mağaza oluştur** (Create store). Give it a name and an address. Your organisation has a store quota; the page shows how many you have used and how many remain. A development store is never billed, cannot disable its storefront password, accepts test payments only, and cannot be transferred to a client.
4. Create your app in the same portal (with a name, a handle, and its distribution: public, or private for a single client store), or let `biticaret app config link` create it from the CLI.

## Build an app

1. Start from the Go template:

   ```bash
   biticaret app init my-app
   cd my-app
   ```

   The template is a small Go server. It handles OAuth installation, renders an embedded admin page, and answers the mandatory privacy webhooks.

2. Check the configuration. This works offline:

   ```bash
   biticaret app check
   ```

3. Sign in and create the app in your organisation. `config link` writes the app's `client_id` into `biticaret.app.toml`:

   ```bash
   biticaret auth login
   biticaret app config link
   ```

4. Point the app at your server. The template serves the admin page at `/app`, so set `application_url` in `biticaret.app.toml` to your server's public HTTPS origin followed by `/app`, such as `https://my-app.example.com/app`. Then start the server. `CLIENT_ID` and `CLIENT_SECRET` come from your app's page in the partner portal; `APP_URL` is the server's origin without `/app`:

   ```bash
   CLIENT_ID=… CLIENT_SECRET=… APP_URL=https://my-app.example.com go run .
   ```

   The server listens on port 8080; set `PORT` to change it. `ADMIN_ORIGIN` (default `https://admin.biticaret.com.tr`) and `STORE_DOMAIN` (default `mybiticaret.com.tr`) control which platform it talks to.

5. Upload a version and release it:

   ```bash
   biticaret app deploy --submit
   ```

   `app deploy` on its own uploads a draft. Drafts are never installed on any store: installations always use the app's released version. For a private app, `--submit` (or clicking **İncelemeye gönder**, Submit for review, on the portal's **Sürümler** (Versions) tab) releases the version immediately; before approval it runs only on your own organisation's stores. Payment apps, and versions that request additional scopes or a higher customer data level than already approved, go through review first.

6. Install the app on your development store. Installation starts in the store's admin: the platform opens `application_url` with a signed query, the app redirects the store owner to the consent screen, and after approval the app receives an access token. See the full flow in [App API](apps/api.md#install-an-app).

### Get an HTTPS address for local development

The platform calls `application_url`, your redirect URLs and your webhook URLs from its own servers, so your app needs a publicly reachable HTTPS address. While developing locally, any tunnel tool that exposes a local port over public HTTPS will work. Once you have a tunnel URL:

- Set `application_url` in `biticaret.app.toml` to it (with the Go template, the tunnel's origin followed by `/app`). Relative paths in `[auth] redirect_urls`, `[privacy]` and webhook `uri` fields (`/oauth/callback`, `/webhooks`) resolve against the origin of `application_url`, so they don't need updating. If you wrote full URLs, update them as well.
- Start the server with `APP_URL` set to the tunnel's origin.
- Re-upload the configuration with `biticaret app check` and `biticaret app deploy --submit`. The URLs are bundled with each version and there is no separate command to push configuration: whenever the tunnel URL changes, upload and release a new version. A tunnel with a fixed domain saves you this step.

The loop: update your code and restart the server. Whenever the configuration changes (scopes, webhooks, URLs or extensions), run `app check` and `app deploy --submit` again.

The Go template stores access tokens in memory and loses them when restarted. A production app should store them encrypted in its own database.

## Review and release

`biticaret app deploy` uploads a draft version, and `--submit` submits it for review in the same command (or you can submit it from the partner portal's **Sürümler** tab). A version's review status is `draft`, `submitted` (in review), `approved` or `rejected`; `biticaret app versions list` shows these statuses. You can submit a version only once the app's listing (its page in the app store) is complete; otherwise the version remains a draft and the command exits with code `1` and `listing_incomplete`. Only an approved version is released.

- **Public app:** each version goes through biticaret's review. Once approved, the app appears under **Uygulamalar > Uygulama mağazası** (Apps > App store) in store admins—or, if you choose not to list it, can be installed only through its install link. The review criteria and timelines will be published with the partner programme.
- **Private app:** not listed in the app store. It installs without prior approval on your organisation's development and client stores using the install link on the app's portal page. Running on a live store requires biticaret's approval for that store.

## Next steps

- Themes: [Theme structure](themes/structure.md), [objects](themes/objects.md), [tags](themes/tags.md), [filters](themes/filters.md).
- Apps: [App API](apps/api.md), [webhooks](apps/webhooks.md), [Go SDK](apps/go-sdk.md), [app proxy and admin page](apps/storefront-and-admin.md), [page states](apps/page-states.md), [configuration files](apps/configuration.md), [all API routes](reference/api-routes.md).
- Coding agents: connect the docs and checks to your agent with `biticaret mcp` ([CLI](cli.md#work-with-an-ai-coding-agent)).
- Extensions: `biticaret app generate extension --type <type> --name <name>` scaffolds a theme block, checkout function, UI extension or web pixel.
