Getting started
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 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
biticaretCLI: see Install the CLI. - For a theme:
gitandzip. - 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
-
Start from the skeleton theme:
biticaret theme init my-themecd my-theme -
Edit the files. Theme structure explains how a theme is organised.
-
Check the theme. This runs the same checks applied during upload:
biticaret theme check --strict . -
Zip the theme folders:
zip -r ../my-theme.zip assets blocks config layout locales sections snippets templatesZip only the theme folders. The uploader rejects files outside them, such as
README.md,LICENSE,AGENTS.mdandCLAUDE.md. -
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).
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.
- 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.
- 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önlendirmefor referrals, orDiğerfor 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. - 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.
- 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
-
Start from the Go template:
biticaret app init my-appcd my-appThe template is a small Go server. It handles OAuth installation, renders an embedded admin page, and answers the mandatory privacy webhooks.
-
Check the configuration. This works offline:
biticaret app check -
Sign in and create the app in your organisation. config link writes the app's
client_idintobiticaret.app.toml:biticaret auth loginbiticaret app config link -
Point the app at your server. The template serves the admin page at /app, so set
application_urlinbiticaret.app.tomlto your server's public HTTPS origin followed by /app, such as https://my-app.example.com/app. Then start the server.CLIENT_IDandCLIENT_SECRETcome from your app's page in the partner portal;APP_URLis the server's origin without /app:CLIENT_ID=… CLIENT_SECRET=… APP_URL=https://my-app.example.com go run .The server listens on port 8080; set
PORTto change it.ADMIN_ORIGIN(default https://admin.biticaret.com.tr) andSTORE_DOMAIN(defaultmybiticaret.com.tr) control which platform it talks to. -
Upload a version and release it:
biticaret app deploy --submitapp 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. -
Install the app on your development store. Installation starts in the store's admin: the platform opens
application_urlwith 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.
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_urlinbiticaret.app.tomlto it (with the Go template, the tunnel's origin followed by /app). Relative paths in [auth] redirect_urls,[privacy]and webhookurifields (/oauth/callback, /webhooks) resolve against the origin ofapplication_url, so they don't need updating. If you wrote full URLs, update them as well. - Start the server with
APP_URLset 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, objects, tags, filters.
- Apps: App API, webhooks, Go SDK, app proxy and admin page, page states, configuration files, all API routes.
- Coding agents: connect the docs and checks to your agent with biticaret mcp (CLI).
- Extensions:
biticaret app generate extension --type <type> --name <name>scaffolds a theme block, checkout function, UI extension or web pixel.