### Complete HTML Page Setup
Source: https://docs.komerza.com/guides/embed-sdk
This example demonstrates a full HTML page structure including the necessary Komerza Embed SDK script tag and a placeholder for your integration code. Ensure the CSP header is configured correctly for security.
```html
My Store
Amazing Product
Price: $29.99
```
--------------------------------
### Preview .NET SDK Interface
Source: https://docs.komerza.com/api-reference/sdks
Demonstrates how to interact with the Komerza API using the upcoming .NET SDK. Includes examples for getting store information, listing products with pagination, and creating a new product.
```csharp
using Komerza.Api;
var client = new KomerzaClient("your-api-key");
// Get store information
var store = await client.Stores.GetAsync(storeId);
// List products with pagination
var products = await client.Products.ListAsync(storeId, new ProductListOptions
{
Page = 1,
PageSize = 20
});
// Create a new product
var newProduct = await client.Products.CreateAsync(storeId, new CreateProductRequest
{
Name = "New Product",
Price = 29.99m,
Currency = "USD"
});
```
--------------------------------
### Cloudflare Nameservers Example
Source: https://docs.komerza.com/guides/custom-domain
Example of Cloudflare nameservers provided during domain setup. Your assigned nameservers will differ.
```text
aaron.ns.cloudflare.com
bella.ns.cloudflare.com
```
--------------------------------
### Full Storefront Example with Initialization
Source: https://docs.komerza.com/storefront/installation
A complete HTML example demonstrating how to include the Komerza library, initialize it with a store ID, and then use other Komerza functions.
```html
My Store
```
--------------------------------
### Install Komerza CLI
Source: https://docs.komerza.com/guides/cli
Install the Komerza CLI globally using npm.
```bash
npm install -g @komerza/cli
```
--------------------------------
### Product with Stock Calculation Mode Example
Source: https://docs.komerza.com/api-reference/enums
Example JSON object for a product, demonstrating the use of stockCalculationMode and a list of items.
```json
{
"name": "Software License",
"stockCalculationMode": 0,
"items": ["KEY-1234-ABCD", "KEY-5678-EFGH", "KEY-9012-IJKL"]
}
```
--------------------------------
### Product License Example
Source: https://docs.komerza.com/api-reference/enums
Example JSON object for a product license, including its name, privacy setting, and price.
```json
{
"name": "Premium License",
"privacy": 0,
"price": 29.99
}
```
--------------------------------
### Pagination Examples
Source: https://docs.komerza.com/api-reference/filtering
Examples showing how to control the number of results and the specific page to retrieve using `page` and `pageSize` parameters.
```APIDOC
## Pagination Examples
Control the number of results and which page to retrieve.
### Parameters
Page number (1-indexed)
Number of items per page (max varies by endpoint)
### Example
```bash
# Get second page with 50 items per page
GET /api/products?page=2&pageSize=50
```
```
--------------------------------
### Start Local Server and Expose with ngrok
Source: https://docs.komerza.com/guides/dynamic-delivery
Expose your local development server to the internet using ngrok to test webhook integrations. Ensure your local server is running before starting ngrok.
```bash
# Start your local server
npm start # or your framework's dev command
# In another terminal, start ngrok
ngrok http 3000
# Use the ngrok URL (e.g., https://abc123.ngrok.io/webhook) in your Komerza product configuration
```
--------------------------------
### Product Privacy and Stock Example
Source: https://docs.komerza.com/api-reference/enums
Example of a product object, demonstrating the use of privacy settings and stock calculation mode.
```json
{
"name": "Software License",
"privacy": 0,
"stockCalculationMode": 0
}
```
--------------------------------
### Delivery Item Type Example
Source: https://docs.komerza.com/api-reference/enums
Example of how to specify the delivery type for a product. Use 'license_key' for products delivered via license keys.
```json
{
"deliveryType": "license_key",
"deliveryContent": "ABCD-EFGH-IJKL-MNOP"
}
```
--------------------------------
### Authentication Example
Source: https://docs.komerza.com/api-reference/introduction
Example of how to authenticate API requests using a Bearer token and include the required User-Agent header.
```APIDOC
## Authentication
All API endpoints require authentication using Bearer tokens. Include your API key in the Authorization header:
```bash theme={null}
curl -H "Authorization: Bearer YOUR_API_KEY" \
-H "User-Agent: MyApp/1.0" \
https://api.komerza.com/stores/{storeId}
```
**Required**: All API requests must include a `User-Agent` header or they will be blocked. Make sure to identify your application with a descriptive User-Agent string.
```
--------------------------------
### Sorting Examples
Source: https://docs.komerza.com/api-reference/filtering
Examples demonstrating how to sort API results using the `sorts` query parameter for ascending and descending order.
```APIDOC
## Sorting Examples
Use the `sorts` parameter to order results by one or more fields.
### Basic Syntax
```bash
# Sort ascending
?sorts=fieldName
# Sort descending (add minus sign)
?sorts=-fieldName
```
### Examples
```bash
# Sort products by price (lowest first)
GET /api/products?sorts=price
# Sort products by price (highest first)
GET /api/products?sorts=-price
# Sort by newest first
GET /api/orders?sorts=-createdAt
```
### Multiple Sort Fields
Separate multiple sort fields with commas:
```bash
# Sort by status, then by date (newest first)
GET /api/orders?sorts=status,-createdAt
# Sort by price ascending, then name ascending
GET /api/products?sorts=price,name
```
```
--------------------------------
### Delivery Item Source Example
Source: https://docs.komerza.com/api-reference/enums
Example demonstrating how to specify the source of the delivery content. 'generated' indicates the content is system-generated, like a license key.
```json
{
"deliveryType": "license_key",
"deliverySource": "generated",
"deliveryContent": "XXXX-YYYY-ZZZZ-WWWW"
}
```
--------------------------------
### Complete OAuth2 Flow Example
Source: https://docs.komerza.com/api-reference/oauth2/exchange
This example demonstrates the complete OAuth2 flow, from initiating the authorization request to exchanging the code for an API key and using it for API calls. It highlights the client-side redirection and the server-side exchange process.
```javascript
// 1. User clicks "Connect with Komerza" in your app
const authUrl = `https://dashboard.komerza.com/auth/authorize?client_id=${CLIENT_ID}&redirect_uri=${REDIRECT_URI}&state=${randomState}`;
window.location.href = authUrl;
// 2. User authorizes on Komerza, redirected back to your app
// URL: https://myapp.com/callback?code=ENCRYPTED_CODE&state=randomState
// 3. Your backend exchanges the code for an API key
const response = await fetch(
`https://api.komerza.com/oauth2/${CLIENT_ID}/exchange/${code}`,
{
headers: {
"x-client-secret": process.env.CLIENT_SECRET,
"User-Agent": "MyApp/1.0",
},
}
);
const { data: apiKey } = await response.json();
// 4. Store the API key securely and use it for API calls
const stores = await fetch("https://api.komerza.com/stores", {
headers: {
Authorization: `Bearer ${apiKey}`,
"User-Agent": "MyApp/1.0",
},
});
```
--------------------------------
### Start HTTP Server for Webhook Listener
Source: https://docs.komerza.com/guides/dynamic-delivery
Starts an HTTP server on port 3000 to listen for incoming webhook requests, routing them to the `webhookHandler` function. Ensure `webhookHandler` is defined.
```go
func main() {
http.HandleFunc("/webhook", webhookHandler)
http.ListenAndServe(":3000", nil)
}
```
--------------------------------
### Get All Products
Source: https://docs.komerza.com/api-reference/endpoint/products/get-all
Fetches all products for a given store.
```APIDOC
## GET /stores/{storeId}/products/all
### Description
Retrieves a list of all products within a specific store.
### Method
GET
### Endpoint
/stores/{storeId}/products/all
### Parameters
#### Path Parameters
- **storeId** (string) - Required - The unique identifier for the store.
### Response
#### Success Response (200)
- **products** (array) - A list of product objects.
- **id** (string) - The unique identifier for the product.
- **name** (string) - The name of the product.
- **description** (string) - The description of the product.
- **price** (number) - The price of the product.
- **currency** (string) - The currency of the product price.
- **imageUrl** (string) - The URL of the product image.
- **createdAt** (string) - The timestamp when the product was created.
- **updatedAt** (string) - The timestamp when the product was last updated.
```
--------------------------------
### Get Product List
Source: https://docs.komerza.com/api-reference/endpoint/products/get-list
Fetches a list of all products available in a store.
```APIDOC
## GET /stores/{storeId}/products
### Description
Retrieves a list of products for a specific store.
### Method
GET
### Endpoint
/stores/{storeId}/products
### Parameters
#### Path Parameters
- **storeId** (string) - Required - The unique identifier for the store.
#### Query Parameters
None specified in the source.
#### Request Body
None specified in the source.
### Request Example
None specified in the source.
### Response
#### Success Response (200)
- **products** (array) - A list of product objects.
#### Response Example
None specified in the source.
```
--------------------------------
### Start Local Development Server
Source: https://docs.komerza.com/guides/cli
Initiate the local development server and enable real-time file syncing with the Komerza Builder. Requires a 'dev' script in package.json.
```bash
komerza dev
```
--------------------------------
### Get Payouts for an Affiliate
Source: https://docs.komerza.com/api-reference/endpoint/affiliates/get-payouts
This example demonstrates how to retrieve a paginated list of payouts for a given affiliate customer ID within a specific store.
```APIDOC
## GET /stores/{storeId}/affiliates/{customerId}/payouts/{page}
### Description
Retrieves a paginated list of payouts for a specific affiliate.
### Method
GET
### Endpoint
/stores/{storeId}/affiliates/{customerId}/payouts/{page}
### Parameters
#### Path Parameters
- **storeId** (string) - Required - The unique identifier for the store.
- **customerId** (string) - Required - The unique identifier for the affiliate customer.
- **page** (integer) - Required - The page number of payouts to retrieve.
### Response
#### Success Response (200)
- **data** (array) - An array of payout objects.
- **id** (string) - The unique identifier for the payout.
- **amount** (number) - The amount of the payout.
- **currency** (string) - The currency of the payout.
- **status** (string) - The status of the payout (e.g., 'pending', 'completed', 'failed').
- **createdAt** (string) - The date and time the payout was created.
- **updatedAt** (string) - The date and time the payout was last updated.
#### Response Example
```json
{
"data": [
{
"id": "payout_123",
"amount": 100.50,
"currency": "USD",
"status": "completed",
"createdAt": "2023-10-27T10:00:00Z",
"updatedAt": "2023-10-27T10:05:00Z"
}
]
}
```
```
--------------------------------
### Basic Komerza Storefront HTML with Client Library
Source: https://docs.komerza.com/storefront/introduction
This example demonstrates a basic HTML structure for a storefront using the Komerza client library. It includes initializing the library, fetching store information, and displaying products with an 'Add to Cart' button. Ensure you replace 'your-store-id' with your actual store ID.
```html
My Store
```
--------------------------------
### Product Gallery Example
Source: https://docs.komerza.com/storefront/images
Demonstrates how to build a product gallery in HTML and JavaScript. It loads a product, sets the main image, and creates thumbnail images that can be clicked to change the main image.
```html
```
--------------------------------
### Handle Missing Images with Fallback URL
Source: https://docs.komerza.com/storefront/images
Provides a function to get an image URL, returning a fallback URL if the filename is missing. Includes an example of using the `onerror` attribute in an `img` tag for client-side error handling.
```javascript
function getImageUrl(filename, fallback = "/placeholder.png") {
if (!filename) return fallback;
return `https://user-generated-content.komerza.com/${filename}`;
}
// With error handling in HTML
;
```
--------------------------------
### Fetch Product by ID and Slug Examples
Source: https://docs.komerza.com/storefront/products
Demonstrates fetching a product by its ID and by its slug. Includes logging the product's name, description, and variants if the fetch is successful.
```javascript
// By ID
const byId = await komerza.getProduct("550e8400-e29b-41d4-a716-446655440000");
// By slug
const bySlug = await komerza.getProduct("premium-license");
if (bySlug.success) {
const product = bySlug.data;
console.log(product.name);
console.log(product.description);
console.log(product.variants);
}
```
--------------------------------
### Get Tickets
Source: https://docs.komerza.com/llms.txt
Gets the tickets in the store. Requires the `stores.tickets.view` permission.
```APIDOC
## GET /tickets/get-list
### Description
Gets the tickets in the store.
### Method
GET
### Endpoint
/tickets/get-list
### Permissions
Requires the `stores.tickets.view` permission.
```
--------------------------------
### Open Project in Browser
Source: https://docs.komerza.com/guides/cli
Open the live store or the Builder editor in your web browser.
```bash
komerza open
```
```bash
komerza open --builder
```
--------------------------------
### Get Coupon
Source: https://docs.komerza.com/llms.txt
Gets a coupon by ID. Requires the `stores.coupons.view` permission.
```APIDOC
## Get Coupon
### Description
Gets a coupon by ID.
### Permissions
Requires the `stores.coupons.view` permission.
```
--------------------------------
### Get Reviews
Source: https://docs.komerza.com/llms.txt
Gets the current and previous reviews for a store. Requires the `stores.view` permission.
```APIDOC
## GET /reviews/get-list
### Description
Gets the current and previous reviews for a store.
### Method
GET
### Endpoint
/reviews/get-list
### Permissions
Requires the `stores.view` permission.
```
--------------------------------
### Get Store Banner URL
Source: https://docs.komerza.com/storefront/store
Get the URL to your store's banner image.
```APIDOC
## Get Store Banner
### Description
Get the URL to your store's banner image.
### Method
`getStoreBannerUrl()`
### Returns
Returns a string containing the full URL to the banner image.
### Example
```javascript
// Display store banner
async function displayBanner() {
const bannerUrl = await komerza.getStoreBannerUrl();
document.getElementById(
"hero-banner"
).style.backgroundImage = `url('${bannerUrl}')`;
}
```
```
--------------------------------
### Complete Storefront Header Example
Source: https://docs.komerza.com/storefront/store
This HTML and JavaScript code demonstrates a full storefront header, including dynamic loading of store name, description, logo, banner, and product listings with formatted prices. It initializes Komerza, fetches store data in parallel, and renders the UI.
```html
Store
```
--------------------------------
### Get Store Logo URL
Source: https://docs.komerza.com/storefront/store
Get the URL to your store's logo image.
```APIDOC
## Get Store Logo
### Description
Get the URL to your store's logo image.
### Method
`getStoreLogoUrl()`
### Returns
Returns a string containing the full URL to the logo image.
### Example
```javascript
// Display store logo
async function displayLogo() {
const logoUrl = await komerza.getStoreLogoUrl();
const img = document.createElement("img");
img.src = logoUrl;
img.alt = "Store Logo";
document.getElementById("logo-container").appendChild(img);
}
```
```
--------------------------------
### Good Practice: Initialize on Page Load
Source: https://docs.komerza.com/storefront/installation
This example shows the correct way to initialize the Komerza library as soon as the page loads, before calling other functions.
```javascript
```
--------------------------------
### Get Ticket
Source: https://docs.komerza.com/llms.txt
Gets a ticket by the ID in the given store and returns it. Requires the `stores.tickets.view` permission.
```APIDOC
## GET /tickets/get
### Description
Gets a ticket by the ID in the given store and returns it.
### Method
GET
### Endpoint
/tickets/get
### Permissions
Requires the `stores.tickets.view` permission.
```
--------------------------------
### Webhook Response Example
Source: https://docs.komerza.com/guides/dynamic-delivery
An example of the plain text response expected from the dynamic delivery webhook.
```APIDOC
## Webhook Response Example
### Description
This is an example of the plain text response that your endpoint must return to fulfill a dynamic delivery.
### Response Format
```http
HTTP/1.1 200 OK
Content-Type: text/plain
LICENSE-KEY-ABC123-XYZ789-PREMIUM
Download: https://example.com/download/abc123
Valid until: 2026-11-27
```
### Response Requirements
Your endpoint must respond with `text/plain` containing the delivery content. This will be displayed to the customer exactly as returned.
- **Content-Type**: Must be `text/plain`.
- **Status Code**: Must be `200` for successful delivery. Any other status code will be treated as a failure and trigger retry logic.
- **Body**: The actual delivery content to show the customer. Can be multi-line. Maximum recommended length is 8,192 characters.
```
--------------------------------
### Display Products with Formatted Prices
Source: https://docs.komerza.com/storefront/formatting
Use `komerza.init` to initialize the SDK and `komerza.createFormatter` to get a formatter instance. Fetch store data with `komerza.getStore` and then map over products to display their names and formatted prices. Ensure `your-store-id` is replaced with your actual store ID.
```html
Products
```
--------------------------------
### Full Options Example (Data Attributes)
Source: https://docs.komerza.com/guides/embed-sdk
Demonstrates using various data attributes to configure the checkout, including return URL, email, coupon code, and metadata.
```APIDOC
## Full Options Example (Data Attributes)
### Description
This example illustrates how to utilize a comprehensive set of data attributes to customize the checkout experience, including setting a custom return URL, prefilling an email, applying a coupon code, and attaching metadata.
```
--------------------------------
### Refund Reason Example
Source: https://docs.komerza.com/api-reference/enums
Example of how to structure a refund request payload, including the refund reason code.
```json
{
"reason": 1,
"amount": 29.99,
"note": "Customer requested refund"
}
```
--------------------------------
### Full Options Example (JavaScript API)
Source: https://docs.komerza.com/guides/embed-sdk
Shows how to open the checkout modal programmatically with all available options set via JavaScript.
```APIDOC
## Full Options Example (JavaScript API)
### Description
This example demonstrates how to invoke the `Komerza.open()` method with a full set of options, including items, theme, affiliate code, return URL, email, coupon code, and metadata, all configured through JavaScript.
```
--------------------------------
### BadToken Error Example
Source: https://docs.komerza.com/api-reference/error-codes
This example shows an invalid or expired API key, requiring a new token generation.
```json
{
"success": false,
"message": "The provided API key is invalid or has expired",
"code": "BadToken",
"data": null
}
```
--------------------------------
### Preview Go SDK Interface
Source: https://docs.komerza.com/api-reference/sdks
Shows how to integrate with the Komerza API using the planned Go SDK. Includes examples for fetching store details, listing products with pagination, and creating new products.
```go
package main
import (
"context"
"github.com/komerza/go-sdk"
)
func main() {
client := komerza.NewClient("your-api-key")
ctx := context.Background()
// Get store information
store, err := client.Stores.Get(ctx, storeID)
if err != nil {
// Handle error
}
// List products with pagination
products, err := client.Products.List(ctx, storeID, &komerza.ProductListOptions{
Page: 1,
PageSize: 20,
})
// Create a new product
newProduct, err := client.Products.Create(ctx, storeID, &komerza.CreateProductRequest{
Name: "New Product",
Price: 29.99,
Currency: "USD",
})
}
```
--------------------------------
### AccessDenied Error Example
Source: https://docs.komerza.com/api-reference/error-codes
Use this example when an API key lacks the required scope or permissions to access a resource.
```json
{
"success": false,
"message": "Your API key does not have permission to update products",
"code": "AccessDenied",
"data": null
}
```
--------------------------------
### Filtering Examples
Source: https://docs.komerza.com/api-reference/filtering
Examples demonstrating how to filter API results using the `filters` query parameter with various operators.
```APIDOC
## Filtering Examples
Use the `filters` parameter to filter results by field values.
### Basic Syntax
```
?filters=fieldName==value
```
### Examples
```bash
# Products with price exactly $29.99
GET /api/products?filters=price==29.99
# Products created after a specific date
GET /api/products?filters=createdAt>2025-01-01
# Orders with "pending" status
GET /api/orders?filters=status==pending
```
### Operators
| Operator | Description | Example |
| -------- | ------------------------------ | ------------------- |
| `==` | Equals | `status==pending` |
| `!=` | Not equals | `status!=cancelled` |
| `>` | Greater than | `price>10` |
| `<` | Less than | `price<100` |
| `>=` | Greater than or equal | `stock>=5` |
| `<=` | Less than or equal | `stock<=50` |
| `@=` | Contains (case-sensitive) | `name@=premium` |
| `_=` | Starts with | `name_=Pro` |
| `@=*` | Contains (case-insensitive) | `name@=*PREMIUM` |
| `_=*` | Starts with (case-insensitive) | `name_=*pro` |
### Multiple Filters
Combine multiple filters with commas (all conditions must match):
```bash
# Products priced between $10 and $50 with stock available
GET /api/products?filters=price>10,price<50,stock>0
# Orders that are pending and created in 2025
GET /api/orders?filters=status==pending,createdAt>=2025-01-01
```
### OR Conditions
Use `|` for OR conditions within a single field:
```bash
# Products that are either "public" or "unlisted"
GET /api/products?filters=privacy==0|1
# Orders with status "pending" or "verifying"
GET /api/orders?filters=status==pending|verifying
```
```
--------------------------------
### Deploy Project to Production
Source: https://docs.komerza.com/guides/cli
Build and deploy your Komerza project to production. This command runs the 'build' script, uploads the output, and makes the store live.
```bash
komerza deploy
```
--------------------------------
### Product Privacy Settings Example - Private
Source: https://docs.komerza.com/api-reference/enums
Example for 'Private' product privacy (2). Products are only visible to administrators and not purchasable.
```json
{
"privacy": 2
}
```
--------------------------------
### Komerza.init(options?)
Source: https://docs.komerza.com/guides/embed-sdk
Initializes the embed SDK. This is automatically called when using Komerza.open(), but should be called explicitly if using data attributes.
```APIDOC
## Komerza.init(options?)
### Description
Initializes the embed and automatically binds all elements with `data-kmrza-*` attributes.
### Parameters
#### Options
* `nonce` (optional): CSP nonce for injected styles and scripts
```
--------------------------------
### Create Product
Source: https://docs.komerza.com/api-reference/endpoint/products/create
Creates a new product in the store. Requires the `stores.products.create` permission.
```APIDOC
## Create Product
### Description
Creates a new product in the store.
### Permissions
Requires the `stores.products.create` permission.
### Method
POST
### Endpoint
`/v1/products`
### Request Body
- **name** (string) - Required - The name of the product.
- **description** (string) - Optional - A detailed description of the product.
- **price** (number) - Required - The price of the product.
- **currency** (string) - Required - The currency of the price (e.g., "USD").
### Request Example
```json
{
"name": "Example Product",
"description": "This is a sample product.",
"price": 19.99,
"currency": "USD"
}
```
### Response
#### Success Response (201 Created)
- **id** (string) - The unique identifier of the created product.
- **name** (string) - The name of the product.
- **description** (string) - The description of the product.
- **price** (number) - The price of the product.
- **currency** (string) - The currency of the price.
- **created_at** (string) - The timestamp when the product was created.
#### Response Example
```json
{
"id": "prod_12345abcde",
"name": "Example Product",
"description": "This is a sample product.",
"price": 19.99,
"currency": "USD",
"created_at": "2023-10-27T10:00:00Z"
}
```
```