Karla API (1.0.0)

To get started with the Karla API, you'll need to:

1. Register an organization and shop - Sign up for a Karla account, create or join an organization and set up your first shop. Remember your shop slug, it will be required in all API URIs.
2. Obtain API credentials - Generate an API key in the Settings section.
3. Set up authentication - Use HTTP Basic Auth with your API credentials.
4. Make your first request - Test the connection with a simple API call.
5. Explore the endpoints - Use this documentation to understand available operations.

Here's a simple example to verify your API access:

curl https://api.gokarla.io/v1/shops/your-shop-slug \
  -u your-username:your-private-api-key

All API requests should be made to:

https://api.gokarla.io/v1/

• Content-Type: application/json
• Accept: application/json
• Encoding: UTF-8

All responses are returned in JSON format. Successful responses will have HTTP status codes in the 2xx range.

{
  "data": "...",
  "metadata": "..."
}

The Karla API uses HTTP Basic Authentication to secure endpoints. Your username is the one you assigned to the API key (if not given, it defaults to the shop slug), and your password is the generated API key.

HTTP Basic Authentication requires you to send credentials in the Authorization header with each request:

Authorization: Basic <base64-encoded-credentials>

1. Combine your credentials: Join your username and API key with a colon

   username:api-key
   

2. Base64 encode: Convert the combined string to Base64

   // JavaScript example
   const credentials = btoa("your-username:your-api-key");
   const authHeader = `Basic ${credentials}`;
   

   # Python example
   import base64
   credentials = base64.b64encode(b'your-username:your-api-key').decode('utf-8')
   auth_header = f'Basic {credentials}'
   

3. Include in requests: Add the header to your API calls

   // JavaScript/Fetch example
   fetch("https://api.gokarla.io/v1/shops/your-shop-slug", {
     headers: {
       Authorization: `Basic ${credentials}`,
       "Content-Type": "application/json",
     },
   });
   

   # Python/Requests example
   import requests
   response = requests.get(
     'https://api.gokarla.io/v1/shops/your-shop-slug',
     auth=('your-username', 'your-api-key')
   )
   

With cURL, you can use the -u flag which automatically handles the Base64 encoding:

curl https://api.gokarla.io/v1/shops/your-shop-slug \
  -u your-username:your-api-key

API keys can have different permission levels that control access to resources:

1. Log in to your Karla Dashboard
2. Navigate to Settings → API Keys
3. Select the appropriate permission level for your use case
4. Click Create API Key
5. Copy and securely store your credentials:
   • Username: Your merchant identifier
   • API Key: Your secret key (shown only once!)

Authentication errors return specific error codes:

1. Store credentials securely

   • Use environment variables or secure key management systems
   • Never hardcode credentials in your source code
   • Never expose credentials in client-side applications

2. Implement proper error handling

   • Handle authentication failures gracefully
   • Don't expose credential details in error messages
   • Implement retry logic with exponential backoff

3. Maintain credential hygiene

   • Use HTTPS for all API requests (HTTP redirects automatically)
   • Rotate API keys regularly
   • Revoke unused or compromised keys immediately
   • Use the minimum required permission level

The Karla API uses conventional HTTP response codes to indicate the success or failure of an API request. In general:

• Codes in the 2xx range indicate success
• Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, an order doesn't exist, etc.)
• Codes in the 5xx range indicate an error with Karla's servers

All error responses follow a consistent structure:

{
  "key": "shop_not_found",
  "message": "Unable to find shop",
  "type": "invalid_request_error",
  "errors": []
}

The API returns specific error keys that help identify the exact issue:

Client Errors (4xx)

Server Errors (5xx)

When a request fails validation, the API returns a 422 status code with additional details in the errors array:

{
  "key": "invalid_payload",
  "message": "Validation error",
  "type": "invalid_request_error",
  "errors": [
    {
      "loc": ["body", "email"],
      "msg": "field required",
      "type": "missing"
    }
  ]
}

Each validation error includes:

• loc: The location of the error (e.g., ["body", "email"] for a missing email field in the request body)
• msg: A human-readable error message
• type: The type of validation error (e.g., missing, value_error, type_error)

The API supports multiple languages and delivers localized content based on the Accept-Language header provided in HTTP requests. This ensures that responses are tailored to the individual language preferences of each user.

Single Language

Accept-Language: es

With Locale

Accept-Language: en-GB

Multiple Languages with Preferences

Accept-Language: fr-CA, fr;q=0.8, en;q=0.5

The Karla API uses page-based pagination for endpoints that return collections of resources. This provides a simple and intuitive way to navigate through large datasets.

Paginated endpoints accept the following query parameters:

curl https://api.gokarla.io/v1/shops/your-shop/orders?page=2&per_page=50 \
  -u your-username:your-private-api-key

Paginated responses return an array of items:

[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "order_number": "ORD-2024-001",
    "created_at": "2024-01-15T10:30:00Z"
  },
  {
    "id": "123e4567-e89b-12d3-a456-426614174001",
    "order_number": "ORD-2024-002",
    "created_at": "2024-01-15T11:00:00Z"
  }
]

1. Choose appropriate page sizes - Larger pages reduce requests but increase response time
2. Handle empty results - The last page may contain fewer items than per_page
3. Respect rate limits - Pagination doesn't exempt you from rate limiting
4. Cache when possible - Results from earlier pages are unlikely to change frequently

When backwards-incompatible changes are made to the API, we release a new, dated version. GoKarla uses a date-based versioning scheme to ensure a predictable and stable API experience for developers.

API versions are named for the date of their release. For example, the API version 2024-01-05 was released on Fri, 5 Jan 2024.

You can configure your API version with the Karla-Version header. As a precaution, use API versioning to test a new API version before committing to an upgrade.

curl https://api.gokarla.io/v1/shops/your-shop/campaigns \
  -u your-username:your-private-api-key \
  -H "Karla-Version: 2024-01-05"

Requests without the Karla-Version header, or with an invalid version, will default to use the latest stable version. This ensures backward compatibility while allowing developers to opt into specific versions when needed.

For significant architectural changes, the base URL path will be updated:

• Current: /v1/
• Future: /v2/

Major version changes are rare and will be communicated well in advance with comprehensive migration guides and at least 1 year of deprecation notice.