Quick Start

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

Open Account Settings → API Keys in the dashboard
Click Create New API Key and give it a name you’ll recognise later
Select the scopes it needs - user.view and stores.view are enough for this guide
Copy the key

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.

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:

curl "https://api.komerza.com/user" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "User-Agent: MyApp/1.0"

{
  "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.

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

3. Call an endpoint

Fetch the store you just found:

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

{
  "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:

{
  "success": false,
  "message": "Access denied."
}

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

When it doesn’t work

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.

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. Scopes are fixed when the key is created, so create a new key with the ones you need.

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.

429 - Too many requests

You’re sending requests faster than allowed. Back off and retry with increasing delays rather than immediately.

Next steps

Filtering & Sorting

Narrow, order and page through list endpoints.

Scopes

Every permission a key can carry.

Products

Read and manage your catalogue.

Orders

Query orders, deliver and refund them.

Store Webhooks

Get order events pushed to your server instead of polling.

SDKs

Official libraries for .NET, JavaScript, Python, Go and PHP.

Last modified on August 2, 2026

API Documentation

Reference

OAuth2

User

Stores

Products

Categories

Variants

Coupons

Tickets

Customers

Orders

Reviews

Affiliates

Webhooks

1. Create an API key

2. Find your store ID

3. Call an endpoint

The response envelope

When it doesn’t work

Next steps

Filtering & Sorting

Scopes

Products

Orders

Store Webhooks

SDKs

​1. Create an API key

​2. Find your store ID

​3. Call an endpoint

​The response envelope

​When it doesn’t work

​Next steps

Filtering & Sorting

Scopes

Products

Orders

Store Webhooks

SDKs

1. Create an API key

2. Find your store ID

3. Call an endpoint

The response envelope

When it doesn’t work

Next steps