---
title: "Create order"
method: POST
path: "/stores/{storeId}/orders"
tags: ["Order"]
---

# Create order

`POST /stores/{storeId}/orders`

Creates a new order for a customer in the admin dashboard.
Requires the `stores.orders.create` permission.

## Path parameters

- `storeId` string, uuid, required

## Request body

- CreateDashboardOrderForm — 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.
  - `cost` number, double, nullable — 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.
  - `items` FormLineItem[], 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.
    - `productId` string, uuid, required — The ID of the product
    - `variantId` string, uuid, required — The ID of the variant, this must match an ID in the product
    - `quantity` integer, required — The amount of the product requested
  - `gateway` string, required — The specific payment method ID to use for this order
  - `couponCode` string, nullable — The coupon code that the customer is applying to the order
  - `affiliateCode` string, nullable — The affiliate code (store affiliate link) to apply to this order.
  - `emailAddress` string, email, required — The email address of the customer placing the order
  - `returnUrl` string, uri, nullable — The URL to redirect the customer to after payment completion. If not provided, the store's default return URL will be used.
  - `sendReceipt` boolean, required — Whether to send a receipt email to the customer after the order is completed. Defaults to true.
  - `metadata` object, nullable — 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, nullable — The IP address of the customer placing the order
  - `userAgent` string, nullable — The browser user agent of the customer placing the order, you can get this from the request headers or using JavaScript
  - `countryCode` string, nullable — The 2-digit country code (ISO 3166-1 alpha-2) of the customer placing the order

## Response `200`

The object was successfully created.

- PublicOrderResponse — Represents a default generic response for API endpoints.
  - `success` boolean, required — Indicates whether the operation or response was successful.
  - `message` string, nullable — A descriptive message providing additional context or information about the response.
  - `code` string, nullable — The error code (if there was an error) to use when referencing the error
  - `data` PublicOrder — An order made by a customer to a merchant for a product they are selling
    - `id` string, uuid, required — The unique identifier of the entity
    - `dateCreated` string, date-time, required — The date the entity was created
    - `items` PublicLineItem[], required — The product that was purchased
      - `id` string, uuid, required — The unique identifier of the entity
      - `dateCreated` string, date-time, required — The date the entity was created
      - `productName` string, required — The name of the product
      - `productId` string, uuid, required — The ID of the product
      - `variantId` string, uuid, required — The ID of the variant they purchased
      - `variantName` string, required — The name of the variant they purchased
      - `amount` number, double, required — The unit cost, how much one unit of the product costs
      - `lineTotal` number, double, required — The total cost for the line item (Amount * Quantity)
      - `additionalFeePercentage` number, double, required — An additional fee percentage applied to the line item, if any.
      - `additionalFeeAmount` number, double, required — The total amount of any additional percentage fees applied to the line item.
      - `additionalFixedFeeAmount` number, double, required — The total amount of any additional fixed fees applied to the line item.
      - `volumeDiscountAmount` number, double, required — The volume discount amount applied to this line item.
      - `volumeDiscountType` 0 | 1 | 2 — Specifies the type of discount to apply for volume pricing tiers.
      - `volumeDiscountValue` number, double, nullable — The discount value from the applied tier (e.g., 10 for 10% or $10).
      - `volumeDiscountTierQuantity` integer, nullable — The quantity threshold of the tier that was applied (e.g., 10 for "Buy 10+").
      - `quantity` integer, required — The amount of product that was purchased
      - `billingInterval` 0 | 1 | 2 | 3 | 4 — The billing interval for a subscription product
      - `customIntervalDays` integer, nullable — Custom interval in days when Komerza.Common.Models.Orders.PublicLineItem.BillingInterval is Komerza.Common.Models.Products.BillingInterval.Custom.
    - `currencyCode` string, required — The fiat currency code used for the order, defaults to USD
    - `gateway` string, required — The gateway used to facilitate the purchase
    - `customer` PublicCustomerDetails, required — The customer details on the order
      - `id` string, uuid, required — The unique identifier of the entity
      - `dateCreated` string, date-time, required — The date the entity was created
      - `countryCode` string, required — The country code of the customer
      - `emailAddress` string, required — The email address of the customer
      - `customerId` string, uuid, required — The ID of the customer profile in the database
    - `chargeback` PublicChargeback — Represents a cardholder chargeback/dispute on an order
      - `id` string, uuid, required — The unique identifier of the entity
      - `dateCreated` string, date-time, required — The date the entity was created
      - `status` string, required — Represents the current state of the dispute.
      - `reason` string, required — Represents the reason associated with a dispute.
    - `gatewayMetadata` PublicGatewayMetadata, required — The gateway-specific metadata for the order
      - `id` string, uuid, required — The unique identifier of the entity
      - `dateCreated` string, date-time, required — The date the entity was created
      - `transactionId` string, nullable — The transaction ID associated with the gateway
      - `clientSecret` string, nullable — The client secret used by card gateways to facilitate payments down to the browser
      - `note` string, nullable — The note for PayPal Friends and Family or Cash App payments
      - `cryptocurrencyAddress` string, nullable — The address for a cryptocurrency payment
      - `cryptocurrencyAmount` number, double, nullable — The amount of cryptocurrency converted at the time for a cryptocurrency payment
      - `cryptocurrencyExpiration` string, date-time, nullable — The date the cryptocurrency payment expires
    - `status` string, required — The current payment status
    - `amountPaid` number, double, required — The amount that the customer has paid for the invoice
    - `amount` number, double, required — The cost of the order
    - `coupon` PublicOrderCoupon — Represents the usage data of a coupon within an order
      - `id` string, uuid, required — The unique identifier of the entity
      - `dateCreated` string, date-time, required — The date the entity was created
      - `percentageDecrease` number, double, nullable — The percentage the coupon cut off the order, this is null if the coupon was a fixed amount instead which the net decrease is below
      - `netDecrease` number, double, required — The net amount the coupon decreased the order by
      - `code` string, required — The code of the coupon
      - `couponId` string, uuid, required — The ID of the coupon
    - `affiliateDiscount` PublicOrderDiscount — Represents the usage data of a coupon within an order
      - `id` string, uuid, required — The unique identifier of the entity
      - `dateCreated` string, date-time, required — The date the entity was created
      - `percentageDecrease` number, double, nullable — The percentage the coupon cut off the order, this is null if the coupon was a fixed amount instead which the net decrease is below
      - `netDecrease` number, double, required — The net amount the coupon decreased the order by
    - `tax` PublicOrderTax — Represents the tax applied to an order.
      - `taxAmount` number, double, required — The tax amount charged.
      - `taxRate` number, double, required — The tax rate applied as a percentage.
      - `taxName` string, required — The display name of the tax (e.g. "VAT", "Sales Tax").
      - `isReverseCharge` boolean, required — Whether reverse charge was applied.
      - `customerVatId` string, nullable — The customer's VAT ID if provided.
      - `preTaxAmount` number, double, required — The order subtotal before tax.
      - `taxBehavior` string, required — Tax behavior: "exclusive" or "inclusive".
    - `globalGatewayFeePercentage` number, double, required — The global gateway fee percentage that was configured (e.g., 2.5 for 2.5%).
    - `globalGatewayFeeAmount` number, double, required — The calculated amount from the global gateway fee percentage.
    - `globalGatewayFixedFee` number, double, required — The global gateway fixed fee that was configured.
    - `globalGatewayFixedFeeAmount` number, double, required — The global gateway fixed fee amount actually applied (0 if product-level overrides exist).
    - `deliveredItems` PublicDeliveredItem[], required — The list of delivered items
      - `id` string, uuid, required — The unique identifier of the entity
      - `dateCreated` string, date-time, required — The date the entity was created
      - `orderId` string, uuid, required — The unique identifier for the order associated with the delivered item.
      - `storeId` string, uuid, required — The unique identifier for the store associated with the delivered item.
      - `productId` string, uuid, nullable — The identifier of the related product, if applicable.
      - `variantId` string, uuid, nullable — The optional identifier for the variant of the delivered item, if applicable.
      - `type` string, required — The type that categorizes the delivered item.
      - `source` string, required — The source of the delivered item, indicates its origin or context.
      - `textContent` string, nullable — The text content associated with the delivered item. Used for LicenseKey, Plaintext, or Dynamic types.
      - `file` PublicStoredFile — Represents a publicly accessible file with additional metadata.
        - `id` string, uuid, required — The unique identifier of the entity
        - `dateCreated` string, date-time, required — The date the entity was created
        - `friendlyName` string, required — The friendly name representing the stored file.
    - `customFieldAnswers` object, nullable — The answers to the custom fields for the order
    - `returnUrl` string, nullable — The URL to redirect the customer to after payment completion.
    - `metadata` object, nullable — Custom key-value metadata attached to the order for merchant tracking purposes.
    - `source` string, required — The source of the order: "store" (marketplace), "embed" (embeds), "api" (dashboard/API).
    - `discordAccount` PublicOrderDiscordAccount — Public representation of the Discord account details associated with an order.
      - `discordUserId` string, required — The Discord user ID (snowflake) of the customer.
      - `username` string, required — The Discord username at the time of the order.
      - `displayName` string, nullable — The Discord display name at the time of the order, if set.
      - `avatarUrl` string, nullable — The Discord avatar URL at the time of the order, if available.
    - `marketingOptIn` boolean, nullable — Whether the customer has opted in to receive marketing emails from this store. Null means no explicit choice has been recorded (pre-existing customer, treated as opted-in).

## Other responses

- `401` — You are not authorized, check your API key and try again.
- `403` — You are not authorized to access this endpoint, you may be missing an API key scope or be requesting a privileged endpoint.
- `404` — One of the objects referenced by the ID given in the URL or form was not found, check the ID and try again.

---

[API](https://skmtc.net/komerza/apis/komerza-api.md) · [All operations](https://skmtc.net/komerza/apis/komerza-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/komerza/komerza-api/versions/060e78bc7f80/schema)