Skip to main content
POST
/
stores
/
{storeId}
/
orders
Create order
curl --request POST \
  --url https://api.komerza.com/stores/{storeId}/orders \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "items": [
    {
      "productId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "variantId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "quantity": 50000
    }
  ],
  "gateway": "<string>",
  "emailAddress": "[email protected]",
  "sendReceipt": true,
  "couponCode": "<string>",
  "returnUrl": "<string>",
  "metadata": {},
  "ipAddress": "<string>",
  "userAgent": "<string>",
  "countryCode": "<string>"
}
'
{
  "success": true,
  "message": "<string>",
  "code": "<string>",
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "dateCreated": "2023-11-07T05:31:56Z",
    "items": [
      {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "dateCreated": "2023-11-07T05:31:56Z",
        "productName": "<string>",
        "productId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "variantId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "variantName": "<string>",
        "amount": 123,
        "lineTotal": 123,
        "additionalFeePercentage": 123,
        "additionalFeeAmount": 123,
        "quantity": 123
      }
    ],
    "currencyCode": "<string>",
    "gateway": "<string>",
    "customer": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "dateCreated": "2023-11-07T05:31:56Z",
      "countryCode": "<string>",
      "emailAddress": "<string>",
      "customerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    },
    "gatewayMetadata": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "dateCreated": "2023-11-07T05:31:56Z",
      "transactionId": "<string>",
      "clientSecret": "<string>",
      "note": "<string>",
      "cryptocurrencyAddress": "<string>",
      "cryptocurrencyAmount": 123,
      "cryptocurrencyExpiration": "2023-11-07T05:31:56Z"
    },
    "status": "<string>",
    "amountPaid": 123,
    "amount": 123,
    "deliveredItems": [
      {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "dateCreated": "2023-11-07T05:31:56Z",
        "orderId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "storeId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "type": "<string>",
        "source": "<string>",
        "productId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "variantId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "textContent": "<string>",
        "file": {
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "dateCreated": "2023-11-07T05:31:56Z",
          "friendlyName": "<string>"
        }
      }
    ],
    "source": "<string>",
    "chargeback": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "dateCreated": "2023-11-07T05:31:56Z",
      "status": "<string>",
      "reason": "<string>"
    },
    "coupon": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "dateCreated": "2023-11-07T05:31:56Z",
      "netDecrease": 123,
      "code": "<string>",
      "couponId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "percentageDecrease": 123
    },
    "affiliateDiscount": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "dateCreated": "2023-11-07T05:31:56Z",
      "netDecrease": 123,
      "percentageDecrease": 123
    },
    "customFieldAnswers": {},
    "returnUrl": "<string>",
    "metadata": {}
  }
}

​
Payment Methods

When creating an order, specify the paymentMethod field using one of the supported payment method codes. See the Payment Methods reference for the complete list of available options.

​
Redirecting to Checkout

After successfully creating an order, redirect the customer to the hosted checkout page to complete payment: 
https://checkout.komerza.com/checkout/{orderId}

​
Example

const response = await fetch(`/stores/${storeId}/orders`, {
  method: "POST",
  headers: { Authorization: `Bearer ${apiKey}` },
  body: JSON.stringify(orderData),
});

const result = await response.json();

if (result.success) {
  const orderId = result.data.id;
  window.location.href = `https://checkout.komerza.com/checkout/${orderId}`;
}
The checkout page handles payment processing, order confirmation, and receipt generation automatically.

Authorizations

​
Authorization
string
header
required

Your API key goes here

Path Parameters

​
storeId
string<uuid>
required

The ID of the store the order will be created in.

Body

application/json

The form containing the order details.

Form to create an order on the dashboard

​
items
object[]
required

The list of products that the user wishes to purchase, including only the ID and quantity. The actual product details will be resolved later.

Required array length: 1 - 10 elements
​
gateway
string
required

The specific payment method ID to use for this order

Required string length: 1 - 256
​
emailAddress
string<email>
required

The email address of the customer placing the order

Maximum string length: 256
​
sendReceipt
boolean
required

Whether to send a receipt email to the customer after the order is completed. Defaults to true.

​
couponCode
string | null

The coupon code that the customer is applying to the order

Maximum string length: 32
​
returnUrl
string<uri> | null

The URL to redirect the customer to after payment completion. If not provided, the store's default return URL will be used.

Maximum string length: 2048
​
metadata
object

Custom key-value metadata to attach to the order for your own tracking purposes. Maximum of 20 keys, each key max 40 characters, each value max 500 characters.

​
ipAddress
string | null

The IP address of the customer placing the order

Maximum string length: 45
​
userAgent
string | null

The browser user agent of the customer placing the order, you can get this from the request headers or using JavaScript

Maximum string length: 512
​
countryCode
string | null

The 2-digit country code (ISO 3166-1 alpha-2) of the customer placing the order

Maximum string length: 2

Response

The object was successfully created.

Represents a default generic response for API endpoints.

​
success
boolean
required

Indicates whether the operation or response was successful.

​
message
string | null

A descriptive message providing additional context or information about the response.

​
code
string | null

The error code (if there was an error) to use when referencing the error

​
data
object

An order made by a customer to a merchant for a product they are selling