Skip to main content

​
Overview

This guide will walk you through making your first API call to the Komerza platform. In just a few minutes, you’ll be able to authenticate and retrieve your store information.
Before starting, make sure you have a Komerza account and access to your dashboard.

​
Step 1: Generate Your API Key

First, you’ll need to create an API key with the appropriate scopes:
  1. Log in to your Komerza Dashboard
  2. Navigate to Account Settings → API Keys
  3. Click “Create New API Key”
  4. Select scopes - For this guide, select stores.view
  5. Copy your API key securely
Store your API key securely and never share it publicly. It provides access to your store data.
Important: All API requests must include a User-Agent header or they will be blocked. Make sure to identify your application in the User-Agent string.

​
Step 2: Get Your Store ID

You’ll need your store ID for most API calls. You can find this in your dashboard or by calling the stores endpoint.
Your store ID can be found on your store’s settings page:
  1. Navigate to your store in the dashboard
  2. Go to the Settings page
  3. Copy the store ID displayed next to the store name text box

​
Step 3: Make Your First API Call

Let’s retrieve your store information using the API: 
curl -X GET \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyApp/1.0" \
  https://api.komerza.com/stores/{your-store-id}

​
Step 4: Understanding the Response

If successful, you’ll receive a response like this: 
{
  "success": true,
  "message": "Store retrieved successfully",
  "code": null,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "My Store",
    "description": "My awesome e-commerce store",
    "currency": "USD",
    "domain": "mystore.com",
    "isActive": true,
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-08-29T14:22:00Z"
  }
}
  • success: Indicates the request was successful - message: Human-readable description of the operation - code: Error code (null for successful requests) - data: The actual store object with all its properties

​
Common Issues & Solutions

Problem: Your API key is invalid or missing.Solution:
  • Verify your API key is correct
  • Ensure you’re including the Bearer prefix
  • Check that your API key hasn’t expired
Problem: Your API key doesn’t have the required scopes. Solution: - Add the stores.view scope to your API key - Regenerate your API key with correct permissions
Problem: The store ID doesn’t exist or you don’t have access.Solution:
  • Verify the store ID is correct
  • Ensure you have access to this store
  • Check if the store is active
Problem: You’ve exceeded the rate limit.Solution:
  • Wait for your tokens to replenish (2 seconds for authenticated users)
  • Implement exponential backoff in your application
  • Consider caching responses to reduce API calls

​
Next Steps

Now that you’ve made your first successful API call, here are some suggested next steps:

Explore Products

Retrieve your product catalog

Manage Orders

Access your order data

Customer Data

Work with customer information

API Scopes

Learn about all available permissions

​
Example: Listing Products

Once you’re comfortable with the basics, try retrieving your product list: 
curl -X GET \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyApp/1.0" \
  "https://api.komerza.com/stores/{your-store-id}/products?Page=1&PageSize=10"
Remember to add the stores.products.view scope to your API key for product-related endpoints.

​
Best Practices

As you build your integration, keep these best practices in mind:

​
Security

  • Store API keys securely (environment variables, not in code)
  • Use the minimum required scopes for your use case
  • Rotate API keys regularly

​
Performance

  • Implement proper error handling and retry logic
  • Cache responses when appropriate
  • Use pagination for large datasets
  • Respect rate limits

​
Development

  • Test with a development store first
  • Use descriptive API key names for different integrations
  • Monitor your API usage through the dashboard

​
Getting Help

If you run into issues:

Help Center

Search our knowledge base

Developer Community

Connect with other developers

Support Team

Contact our support team

System Status

Check API availability
Congratulations! You’ve successfully made your first Komerza API call. You’re now ready to build powerful integrations with our e-commerce platform.