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": "jsmith@example.com",
  "sendReceipt": true,
  "cost": 500000.005,
  "couponCode": "<string>",
  "affiliateCode": "<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,
        "additionalFixedFeeAmount": 123,
        "volumeDiscountAmount": 123,
        "quantity": 123,
        "volumeDiscountValue": 123,
        "volumeDiscountTierQuantity": 123,
        "customIntervalDays": 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,
    "globalGatewayFeePercentage": 123,
    "globalGatewayFeeAmount": 123,
    "globalGatewayFixedFee": 123,
    "globalGatewayFixedFeeAmount": 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
    },
    "tax": {
      "taxAmount": 123,
      "taxRate": 123,
      "taxName": "<string>",
      "isReverseCharge": true,
      "preTaxAmount": 123,
      "taxBehavior": "<string>",
      "customerVatId": "<string>"
    },
    "customFieldAnswers": {},
    "returnUrl": "<string>",
    "metadata": {},
    "discordAccount": {
      "discordUserId": "<string>",
      "username": "<string>",
      "displayName": "<string>",
      "avatarUrl": "<string>"
    },
    "marketingOptIn": true
  }
}

​
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. Supply either Komerza.Common.Forms.Orders.CreateDashboardOrderForm.Cost for a product-less invoice, or Komerza.Common.Forms.Orders.LineItemsForm.Items for a standard product order.

​
items
object[]
required

Hides the base Komerza.Common.Forms.Orders.LineItemsForm.Items to remove the [Required] / [Length] constraints, since items are optional when Komerza.Common.Forms.Orders.CreateDashboardOrderForm.Cost is provided.

​
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.

​
cost
number<double> | null

An arbitrary total to charge the customer, without referencing any products. When set, Items is ignored and the order is created with no line items.

Required range: 0.01 <= x <= 1000000
​
couponCode
string | null

The coupon code that the customer is applying to the order

Maximum string length: 32
​
affiliateCode
string | null

The affiliate code (store affiliate link) to apply to this order.

Maximum string length: 256
​
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