DocsDocsReference

Create order

Creates a new order with order lines, addresses, and payment information. Validates that all products and variants exist. Publishes an order created event.

POST/api/v1/{team_slug}/{app_slug}/orders
API
Management
Updated
Apr 26, 2026

management-api:POST:/api/v1/{team_slug}/{app_slug}/orders

Creates a new order with order lines, addresses, and payment information. Validates that all products and variants exist. Publishes an order created event.

API ownership

  • API family: Management API
  • Best for: Trusted back-office workflows that create, update, organize, or delete merchant-owned data.
  • Do not use from: Browser-only storefront code or public clients.
  • Guide route: /apis/management/latest

The OpenAPI contract defines the method, path, parameters, request body, and responses for this operation.

Operation

  • Method: POST
  • Path: /api/v1/\{team_slug\}/\{app_slug\}/orders
  • Summary: Create order
  • Description: Creates a new order with order lines, addresses, and payment information. Validates that all products and variants exist. Publishes an order created event.
  • OpenAPI contract: management-api
  • Operation ID: Not documented in the OpenAPI contract.

Operation key uses API family, method, and path because this OpenAPI contract does not publish an operation ID.

Parameters2 parameters
NameInRequiredTypeDescription
app_slugpathYesstringApp slug
team_slugpathYesstringTeam slug
Request bodyDocumented body
  • Required: Yes
  • Description: Order data
  • Content: application/json (object)

Input Create Order

PropertyTypeRequiredDetails
billing_addressobjectNo-
bonus_totalnumberNomin: 0
country_codestringYes-
currency_codestringYes-
discount_totalnumberNomin: 0
gift_card_totalnumberNomin: 0
grand_totalnumberYesmin: 0
language_codestringYes-
linesobject[]YesminItems: 1
merchant_user_idstringNo-
payment_methodstringNo-
payment_method_idstringNo-
payment_method_namestringNo-
referencestringYes-
session_idstringNo-
shipping_addressobjectNo-
shipping_methodsstring[]No-
shipping_totalnumberNomin: 0
sourcestringYes-
statusenum("placed", "refunded", "compensated", "released", "delivered", "cancelled")Yes-
sub_totalnumberNomin: 0
tax_totalnumberNomin: 0

Input Order Address

PropertyTypeRequiredDetails
citystringNo-
country_codestringNo-
emailstringNo-
family_namestringNo-
given_namestringNo-
postal_codestringNo-
state_or_provincestringNo-
street_addressstringNo-
street_address_2stringNo-
telephone_numberstringNo-

Input Order Line

PropertyTypeRequiredDetails
base_price_amountnumberYesmin: 0
currency_codestringYes-
product_idstringYes-
quantityintegerYesmin: 1
tax_group_idstringNo-
total_discount_amountnumberNomin: 0
total_price_amountnumberYesmin: 0
total_tax_amountnumberNomin: 0
variant_idstringYes-
{
  "billing_address": {
    "city": "string",
    "country_code": "string",
    "email": "string",
    "family_name": "string",
    "given_name": "string",
    "postal_code": "string",
    "state_or_province": "string",
    "street_address": "string",
    "street_address_2": "string",
    "telephone_number": "string"
  },
  "bonus_total": 0,
  "country_code": "string",
  "currency_code": "string",
  "discount_total": 0,
  "gift_card_total": 0,
  "grand_total": 0,
  "language_code": "string",
  "lines": [
    {
      "base_price_amount": 0,
      "currency_code": "string",
      "product_id": "string",
      "quantity": 1,
      "tax_group_id": "string",
      "total_discount_amount": 0,
      "total_price_amount": 0,
      "total_tax_amount": 0,
      "variant_id": "string"
    }
  ],
  "merchant_user_id": "string",
  "payment_method": "string",
  "payment_method_id": "string",
  "payment_method_name": "string",
  "reference": "string",
  "session_id": "string",
  "shipping_address": {
    "city": "string",
    "country_code": "string",
    "email": "string",
    "family_name": "string",
    "given_name": "string",
    "postal_code": "string",
    "state_or_province": "string",
    "street_address": "string",
    "street_address_2": "string",
    "telephone_number": "string"
  },
  "shipping_methods": [
    "string"
  ],
  "shipping_total": 0,
  "source": "string",
  "status": "placed",
  "sub_total": 0,
  "tax_total": 0
}
Responses4 statuses
StatusDescriptionContent
201Order created successfullyapplication/json (object)
400Invalid request (validation error, product/variant not found)application/json (object)
401Unauthorized accessapplication/json (object)
500Internal server errorapplication/json (object)

201 - object

Order Response

PropertyTypeRequiredDetails
dataobjectNo-
detailsstring[]NoAdditional contextual information about the response. Used to provide supplementary details beyond the main data payload, such as validation warnings or processing notes
successbooleanNo-
Order
PropertyTypeRequiredDetails
billing_addressobjectNo-
bonus_totalnumberNo-
country_codestringNo-
created_atstringNo-
currency_codestringNo-
discount_totalnumberNo-
discountsobject[]No-
gift_card_totalnumberNo-
grand_totalnumberNo-
idstringNo-
language_codestringNo-
merchant_userobjectNo-
order_linesobject[]No-
payment_methodstringNo-
payment_method_idstringNo-
payment_method_namestringNo-
referencestringNo-
session_idstringNo-
shipping_addressobjectNo-
shipping_methodsstring[]No-
shipping_totalnumberNo-
sourcestringNo-
sub_totalnumberNo-
tax_totalnumberNo-
updated_atstringNo-
user_contentobject[]No-
Order Address
PropertyTypeRequiredDetails
address_typestringNo-
citystringNo-
country_codestringNo-
created_atstringNo-
emailstringNo-
family_namestringNo-
given_namestringNo-
idstringNo-
postal_codestringNo-
state_or_provincestringNo-
street_addressstringNo-
street_address_2stringNo-
telephone_numberstringNo-
updated_atstringNo-
Order Discount
PropertyTypeRequiredDetails
created_atstringNo-
discount_idstringNo-
idstringNo-
namestringNo-
order_idstringNo-
updated_atstringNo-
Merchant User Summary
PropertyTypeRequiredDetails
emailstringNo-
idstringNo-
namestringNo-
surnamestringNo-
Order Line
PropertyTypeRequiredDetails
base_price_amountnumberNo-
created_atstringNo-
currency_codestringNo-
first_image_pathstringNo-
idstringNo-
order_idstringNo-
product_idstringNo-
product_namestringNo-
product_numberstringNo-
quantityintegerNo-
short_descriptionstringNo-
tax_group_idstringNo-
total_discount_amountnumberNo-
total_price_amountnumberNo-
total_sale_pricenumberNo-
total_tax_amountnumberNo-
updated_atstringNo-
variant_idstringNo-
variant_namestringNo-
variant_numberstringNo-
Order User Content
PropertyTypeRequiredDetails
content_typestringNo-
filenamestringNo-
idstringNo-
urlstringNo-
{
  "data": {
    "billing_address": {
      "address_type": "string",
      "city": "string",
      "country_code": "string",
      "created_at": "string",
      "email": "string",
      "family_name": "string",
      "given_name": "string",
      "id": "string",
      "postal_code": "string",
      "state_or_province": "string",
      "street_address": "string",
      "street_address_2": "string",
      "telephone_number": "string",
      "updated_at": "string"
    },
    "bonus_total": 0,
    "country_code": "string",
    "created_at": "string",
    "currency_code": "string",
    "discount_total": 0,
    "discounts": [
      {
        "created_at": "string",
        "discount_id": "string",
        "id": "string",
        "name": "string",
        "order_id": "string",
        "updated_at": "string"
      }
    ],
    "gift_card_total": 0,
    "grand_total": 0,
    "id": "string",
    "language_code": "string",
    "merchant_user": {
      "email": "string",
      "id": "string",
      "name": "string",
      "surname": "string"
    },
    "order_lines": [
      {
        "base_price_amount": 0,
        "created_at": "string",
        "currency_code": "string",
        "first_image_path": "string",
        "id": "string",
        "order_id": "string",
        "product_id": "string",
        "product_name": "string",
        "product_number": "string",
        "quantity": 0,
        "short_description": "string",
        "tax_group_id": "string",
        "total_discount_amount": 0,
        "total_price_amount": 0,
        "total_sale_price": 0,
        "total_tax_amount": 0,
        "updated_at": "string",
        "variant_id": "string",
        "variant_name": "string",
        "variant_number": "string"
      }
    ],
    "payment_method": "string",
    "payment_method_id": "string",
    "payment_method_name": "string",
    "reference": "string",
    "session_id": "string",
    "shipping_address": {
      "address_type": "string",
      "city": "string",
      "country_code": "string",
      "created_at": "string",
      "email": "string",
      "family_name": "string",
      "given_name": "string",
      "id": "string",
      "postal_code": "string",
      "state_or_province": "string",
      "street_address": "string",
      "street_address_2": "string",
      "telephone_number": "string",
      "updated_at": "string"
    },
    "shipping_methods": [
      "string"
    ],
    "shipping_total": 0,
    "source": "string",
    "sub_total": 0,
    "tax_total": 0,
    "updated_at": "string",
    "user_content": [
      {
        "content_type": "string",
        "filename": "string",
        "id": "string",
        "url": "string"
      }
    ]
  },
  "details": [
    "string"
  ],
  "success": false
}

400 - object

Error Message

PropertyTypeRequiredDetails
detailsstring[]No-
messagestringNo-
successbooleanNo-

Generated example (synthetic):

{
  "details": [
    "string"
  ],
  "message": "string",
  "success": false
}

401 - object

Error Message

PropertyTypeRequiredDetails
detailsstring[]No-
messagestringNo-
successbooleanNo-

Generated example (synthetic):

{
  "details": [
    "string"
  ],
  "message": "string",
  "success": false
}

500 - object

Error Message

PropertyTypeRequiredDetails
detailsstring[]No-
messagestringNo-
successbooleanNo-

Generated example (synthetic):

{
  "details": [
    "string"
  ],
  "message": "string",
  "success": false
}

Contract identity

Use these fields to confirm you are implementing the intended endpoint contract.

  • API family: Management API
  • Method: POST
  • Path: /api/v1/\{team_slug\}/\{app_slug\}/orders
  • Operation ID: Not documented in the OpenAPI contract.
  • OpenAPI tag: Orders
  • OpenAPI summary: Create order

Create order

# Create order Creates a new order with order lines, addresses, and payment information. Validates that all products and variants exist. Publishes an order created event.
POST /api/v1/{team_slug}/{app_slug}/orders
Purpose

Creates a new order with order lines, addresses, and payment information.

Required inputs

app_slug path team_slug path

Primary response

201 ยท Order created successfully

Operation key

management-api:POST:/api/v1/{team_slug}/{app_slug}/orders

## API ownership - API family: Management API - Best for: Trusted back-office workflows that create, update, organize, or delete merchant-owned data. - Do not use from: Browser-only storefront code or public clients. - Guide route: [/apis/management/latest](/apis/management/latest) The OpenAPI contract defines the method, path, parameters, request body, and responses for this operation. ## Operation - Method: `POST` - Path: `/api/v1/{team_slug}/{app_slug}/orders` - Summary: Create order - Description: Creates a new order with order lines, addresses, and payment information. Validates that all products and variants exist. Publishes an order created event. - OpenAPI contract: management-api - Operation ID: Not documented in the OpenAPI contract. - Stable operation key: `management-api:POST:/api/v1/{team_slug}/{app_slug}/orders` Operation key uses API family, method, and path because this OpenAPI contract does not publish an operation ID. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | app_slug | path | Yes | string | App slug | | team_slug | path | Yes | string | Team slug | ## Request body - Required: Yes - Description: Order data - Content: application/json (object) ### Input Create Order | Property | Type | Required | Details | | --- | --- | --- | --- | | `billing_address` | object | No | - | | `bonus_total` | number | No | min: 0 | | `country_code` | string | Yes | - | | `currency_code` | string | Yes | - | | `discount_total` | number | No | min: 0 | | `gift_card_total` | number | No | min: 0 | | `grand_total` | number | Yes | min: 0 | | `language_code` | string | Yes | - | | `lines` | object[] | Yes | minItems: 1 | | `merchant_user_id` | string | No | - | | `payment_method` | string | No | - | | `payment_method_id` | string | No | - | | `payment_method_name` | string | No | - | | `reference` | string | Yes | - | | `session_id` | string | No | - | | `shipping_address` | object | No | - | | `shipping_methods` | string[] | No | - | | `shipping_total` | number | No | min: 0 | | `source` | string | Yes | - | | `status` | enum("placed", "refunded", "compensated", "released", "delivered", "cancelled") | Yes | - | | `sub_total` | number | No | min: 0 | | `tax_total` | number | No | min: 0 | #### Input Order Address | Property | Type | Required | Details | | --- | --- | --- | --- | | `city` | string | No | - | | `country_code` | string | No | - | | `email` | string | No | - | | `family_name` | string | No | - | | `given_name` | string | No | - | | `postal_code` | string | No | - | | `state_or_province` | string | No | - | | `street_address` | string | No | - | | `street_address_2` | string | No | - | | `telephone_number` | string | No | - | #### Input Order Line | Property | Type | Required | Details | | --- | --- | --- | --- | | `base_price_amount` | number | Yes | min: 0 | | `currency_code` | string | Yes | - | | `product_id` | string | Yes | - | | `quantity` | integer | Yes | min: 1 | | `tax_group_id` | string | No | - | | `total_discount_amount` | number | No | min: 0 | | `total_price_amount` | number | Yes | min: 0 | | `total_tax_amount` | number | No | min: 0 | | `variant_id` | string | Yes | - |
Generated example (synthetic) ```json { "billing_address": { "city": "string", "country_code": "string", "email": "string", "family_name": "string", "given_name": "string", "postal_code": "string", "state_or_province": "string", "street_address": "string", "street_address_2": "string", "telephone_number": "string" }, "bonus_total": 0, "country_code": "string", "currency_code": "string", "discount_total": 0, "gift_card_total": 0, "grand_total": 0, "language_code": "string", "lines": [ { "base_price_amount": 0, "currency_code": "string", "product_id": "string", "quantity": 1, "tax_group_id": "string", "total_discount_amount": 0, "total_price_amount": 0, "total_tax_amount": 0, "variant_id": "string" } ], "merchant_user_id": "string", "payment_method": "string", "payment_method_id": "string", "payment_method_name": "string", "reference": "string", "session_id": "string", "shipping_address": { "city": "string", "country_code": "string", "email": "string", "family_name": "string", "given_name": "string", "postal_code": "string", "state_or_province": "string", "street_address": "string", "street_address_2": "string", "telephone_number": "string" }, "shipping_methods": [ "string" ], "shipping_total": 0, "source": "string", "status": "placed", "sub_total": 0, "tax_total": 0 } ```
## Responses | Status | Description | Content | | --- | --- | --- | | 201 | Order created successfully | application/json (object) | | 400 | Invalid request (validation error, product/variant not found) | application/json (object) | | 401 | Unauthorized access | application/json (object) | | 500 | Internal server error | application/json (object) | ### 201 - object #### Order Response | Property | Type | Required | Details | | --- | --- | --- | --- | | `data` | object | No | - | | `details` | string[] | No | Additional contextual information about the response. Used to provide supplementary details beyond the main data payload, such as validation warnings or processing notes | | `success` | boolean | No | - | ##### Order | Property | Type | Required | Details | | --- | --- | --- | --- | | `billing_address` | object | No | - | | `bonus_total` | number | No | - | | `country_code` | string | No | - | | `created_at` | string | No | - | | `currency_code` | string | No | - | | `discount_total` | number | No | - | | `discounts` | object[] | No | - | | `gift_card_total` | number | No | - | | `grand_total` | number | No | - | | `id` | string | No | - | | `language_code` | string | No | - | | `merchant_user` | object | No | - | | `order_lines` | object[] | No | - | | `payment_method` | string | No | - | | `payment_method_id` | string | No | - | | `payment_method_name` | string | No | - | | `reference` | string | No | - | | `session_id` | string | No | - | | `shipping_address` | object | No | - | | `shipping_methods` | string[] | No | - | | `shipping_total` | number | No | - | | `source` | string | No | - | | `sub_total` | number | No | - | | `tax_total` | number | No | - | | `updated_at` | string | No | - | | `user_content` | object[] | No | - | ##### Order Address | Property | Type | Required | Details | | --- | --- | --- | --- | | `address_type` | string | No | - | | `city` | string | No | - | | `country_code` | string | No | - | | `created_at` | string | No | - | | `email` | string | No | - | | `family_name` | string | No | - | | `given_name` | string | No | - | | `id` | string | No | - | | `postal_code` | string | No | - | | `state_or_province` | string | No | - | | `street_address` | string | No | - | | `street_address_2` | string | No | - | | `telephone_number` | string | No | - | | `updated_at` | string | No | - | ##### Order Discount | Property | Type | Required | Details | | --- | --- | --- | --- | | `created_at` | string | No | - | | `discount_id` | string | No | - | | `id` | string | No | - | | `name` | string | No | - | | `order_id` | string | No | - | | `updated_at` | string | No | - | ##### Merchant User Summary | Property | Type | Required | Details | | --- | --- | --- | --- | | `email` | string | No | - | | `id` | string | No | - | | `name` | string | No | - | | `surname` | string | No | - | ##### Order Line | Property | Type | Required | Details | | --- | --- | --- | --- | | `base_price_amount` | number | No | - | | `created_at` | string | No | - | | `currency_code` | string | No | - | | `first_image_path` | string | No | - | | `id` | string | No | - | | `order_id` | string | No | - | | `product_id` | string | No | - | | `product_name` | string | No | - | | `product_number` | string | No | - | | `quantity` | integer | No | - | | `short_description` | string | No | - | | `tax_group_id` | string | No | - | | `total_discount_amount` | number | No | - | | `total_price_amount` | number | No | - | | `total_sale_price` | number | No | - | | `total_tax_amount` | number | No | - | | `updated_at` | string | No | - | | `variant_id` | string | No | - | | `variant_name` | string | No | - | | `variant_number` | string | No | - | ##### Order User Content | Property | Type | Required | Details | | --- | --- | --- | --- | | `content_type` | string | No | - | | `filename` | string | No | - | | `id` | string | No | - | | `url` | string | No | - |
Generated example (synthetic) ```json { "data": { "billing_address": { "address_type": "string", "city": "string", "country_code": "string", "created_at": "string", "email": "string", "family_name": "string", "given_name": "string", "id": "string", "postal_code": "string", "state_or_province": "string", "street_address": "string", "street_address_2": "string", "telephone_number": "string", "updated_at": "string" }, "bonus_total": 0, "country_code": "string", "created_at": "string", "currency_code": "string", "discount_total": 0, "discounts": [ { "created_at": "string", "discount_id": "string", "id": "string", "name": "string", "order_id": "string", "updated_at": "string" } ], "gift_card_total": 0, "grand_total": 0, "id": "string", "language_code": "string", "merchant_user": { "email": "string", "id": "string", "name": "string", "surname": "string" }, "order_lines": [ { "base_price_amount": 0, "created_at": "string", "currency_code": "string", "first_image_path": "string", "id": "string", "order_id": "string", "product_id": "string", "product_name": "string", "product_number": "string", "quantity": 0, "short_description": "string", "tax_group_id": "string", "total_discount_amount": 0, "total_price_amount": 0, "total_sale_price": 0, "total_tax_amount": 0, "updated_at": "string", "variant_id": "string", "variant_name": "string", "variant_number": "string" } ], "payment_method": "string", "payment_method_id": "string", "payment_method_name": "string", "reference": "string", "session_id": "string", "shipping_address": { "address_type": "string", "city": "string", "country_code": "string", "created_at": "string", "email": "string", "family_name": "string", "given_name": "string", "id": "string", "postal_code": "string", "state_or_province": "string", "street_address": "string", "street_address_2": "string", "telephone_number": "string", "updated_at": "string" }, "shipping_methods": [ "string" ], "shipping_total": 0, "source": "string", "sub_total": 0, "tax_total": 0, "updated_at": "string", "user_content": [ { "content_type": "string", "filename": "string", "id": "string", "url": "string" } ] }, "details": [ "string" ], "success": false } ```
### 400 - object #### Error Message | Property | Type | Required | Details | | --- | --- | --- | --- | | `details` | string[] | No | - | | `message` | string | No | - | | `success` | boolean | No | - | **Generated example (synthetic):** ```json { "details": [ "string" ], "message": "string", "success": false } ``` ### 401 - object #### Error Message | Property | Type | Required | Details | | --- | --- | --- | --- | | `details` | string[] | No | - | | `message` | string | No | - | | `success` | boolean | No | - | **Generated example (synthetic):** ```json { "details": [ "string" ], "message": "string", "success": false } ``` ### 500 - object #### Error Message | Property | Type | Required | Details | | --- | --- | --- | --- | | `details` | string[] | No | - | | `message` | string | No | - | | `success` | boolean | No | - | **Generated example (synthetic):** ```json { "details": [ "string" ], "message": "string", "success": false } ``` ## Contract identity Use these fields to confirm you are implementing the intended endpoint contract. - API family: Management API - Method: `POST` - Path: `/api/v1/{team_slug}/{app_slug}/orders` - Operation ID: Not documented in the OpenAPI contract. - Stable operation key: `management-api:POST:/api/v1/{team_slug}/{app_slug}/orders` - OpenAPI tag: Orders - OpenAPI summary: Create order