> ## Documentation Index
> Fetch the complete documentation index at: https://docs.komerza.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Start

> Make your first Komerza API call

Three steps: create a key, call `/user` to find your store, then call something with that store ID. You need a Komerza account and dashboard access.

## 1. Create an API key

1. Open **[Account Settings → API Keys](https://dashboard.komerza.com/account?api)** in the dashboard
2. Click **Create New API Key** and give it a name you'll recognise later
3. Select the scopes it needs - `user.view` and `stores.view` are enough for this guide
4. Copy the key

<Warning>
  The key is shown once. Store it in an environment variable or a secrets
  manager, never in source control, and give each integration its own key so you
  can revoke one without breaking the rest.
</Warning>

Every request needs two headers:

| Header          | Value                                                |
| --------------- | ---------------------------------------------------- |
| `Authorization` | `Bearer YOUR_API_KEY`                                |
| `User-Agent`    | Something that identifies your app, e.g. `MyApp/1.0` |

## 2. Find your store ID

Almost every endpoint is scoped to a store. `GET /user` returns your account, with the stores on it:

```bash theme={null}
curl "https://api.komerza.com/user" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "User-Agent: MyApp/1.0"
```

```json theme={null}
{
  "success": true,
  "message": null,
  "code": null,
  "data": {
    "id": "…",
    "email": "you@example.com",
    "plan": 1,
    "stores": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "My Store",
        "url": "mystore",
        "currencyCode": "USD"
      }
    ]
  }
}
```

The `id` of the store you want is what every `{storeId}` in these docs refers to.

<Tip>
  You can also copy it from the dashboard: **Online Store → Settings →
  General**, where the **Store ID** field has a copy button next to it.
</Tip>

## 3. Call an endpoint

Fetch the store you just found:

```bash theme={null}
curl "https://api.komerza.com/stores/{storeId}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "User-Agent: MyApp/1.0"
```

```json theme={null}
{
  "success": true,
  "message": null,
  "code": null,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "dateCreated": "2026-01-15T10:30:00Z",
    "name": "My Store",
    "description": "Digital goods, delivered instantly",
    "url": "mystore",
    "customDomain": "shop.example.com",
    "currencyCode": "USD",
    "rating": 4.8,
    "isTicketingEnabled": true,
    "isCustomerBalanceEnabled": false
  }
}
```

That's it - you're authenticated and reading real data.

## The response envelope

Every response has the same four fields:

| Field     | What it is                                             |
| --------- | ------------------------------------------------------ |
| `success` | Whether the request worked                             |
| `message` | Human-readable detail, often `null` on success         |
| `code`    | Error code when something went wrong, otherwise `null` |
| `data`    | The payload - an object, an array, or `null`           |

Errors keep the same shape:

```json theme={null}
{
  "success": false,
  "message": "Access denied."
}
```

Check `success` rather than assuming a `200` means you got what you asked for.

## When it doesn't work

<AccordionGroup>
  <Accordion title="401 - Access denied">
    The key is missing, malformed or revoked. Check you sent `Authorization:
            Bearer YOUR_KEY` including the `Bearer ` prefix, and that the key still
    exists in the dashboard.
  </Accordion>

  <Accordion title="403 - Forbidden">
    The key is valid but lacks the scope for that endpoint. Scopes follow the
    resource: reading orders needs `stores.orders.view`, refunding them needs
    `stores.orders.refund`. The full list is in [Scopes](/api-reference/scopes).
    Scopes are fixed when the key is created, so create a new key with the ones
    you need.
  </Accordion>

  <Accordion title="404 - Not found">
    Usually a store ID that doesn't exist, belongs to another account, or picked
    up a stray character. Confirm it against `GET /user`. Check the path too:
    the base URL is `https://api.komerza.com` with **no** `/api` prefix.
  </Accordion>

  <Accordion title="429 - Too many requests">
    You're sending requests faster than allowed. Back off and retry with
    increasing delays rather than immediately.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Filtering & Sorting" icon={<span className="kicon kicon-check-list" />} href="/api-reference/filtering">
    Narrow, order and page through list endpoints.
  </Card>

  <Card title="Scopes" icon={<span className="kicon kicon-key" />} href="/api-reference/scopes">
    Every permission a key can carry.
  </Card>

  <Card title="Products" icon={<span className="kicon kicon-box" />} href="/api-reference/endpoint/products/get-list">
    Read and manage your catalogue.
  </Card>

  <Card title="Orders" icon={<span className="kicon kicon-receipt" />} href="/api-reference/endpoint/orders/get-list">
    Query orders, deliver and refund them.
  </Card>

  <Card title="Store Webhooks" icon={<span className="kicon kicon-webhook" />} href="/guides/webhooks">
    Get order events pushed to your server instead of polling.
  </Card>

  <Card title="SDKs" icon={<span className="kicon kicon-code" />} href="/api-reference/sdks">
    Official libraries for .NET, JavaScript, Python, Go and PHP.
  </Card>
</CardGroup>