Skip to main content
POST
/
orders
cURL
curl --request POST \
  --url https://api.konvoai.com/orders \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
[
  {
    "id": "08c0e60e-26bd-4e41-bb05-97bfbe1ba7cd",
    "friendlyName": "#1059",
    "customer": {
      "id": "customer_67890",
      "firstName": "John",
      "lastName": "Doe",
      "userIds": [
        {
          "type": "email",
          "id": "[email protected]"
        }
      ]
    },
    "orderTotal": 3995,
    "currency": "USD",
    "items": [
      {
        "id": "variant_123",
        "sku": "SHIRT-BLU-M",
        "name": "Blue T-Shirt - Medium",
        "description": "Comfortable cotton t-shirt in blue",
        "price": 2999,
        "msrp": 3999,
        "imageUrl": "https://example.com/images/blue-tshirt.jpg",
        "currency": "USD",
        "available": true,
        "inventoryQuantity": 150,
        "quantity": 2
      }
    ],
    "externalId": "order_12345",
    "metadata": {
      "preorder": true,
      "gift_message": "Happy Birthday!"
    },
    "status": "paid",
    "shipmentStatus": "in_transit",
    "source": "online",
    "trackingUrl": "https://tracking.example.com/12345",
    "address": {
      "firstName": "John",
      "lastName": "Doe",
      "addressLineOne": "123 Main St",
      "addressLineTwo": "Apt 4B",
      "zipCode": "10001",
      "city": "New York",
      "countryCode": "US",
      "state": "NY",
      "latitude": "40.7128",
      "longitude": "-74.0060",
      "company": "Acme Corp",
      "phone": "+15551234567"
    }
  }
]
'
{
  "count": 2,
  "result": [
    {
      "id": "be6ed223-19c3-47db-8635-794f856e1956",
      "contactId": "21f0cf2f-30cd-4e13-9cde-7a3e4e77deff",
      "externalName": "1001",
      "externalId": "5210634092624",
      "firstName": "Jeff",
      "lastName": "Bezos",
      "email": "[email protected]",
      "phoneNumber": "+15551234",
      "orderTotal": 69995,
      "currency": "eur",
      "channel": "SHOPIFY",
      "status": "PAID",
      "trackingUrl": "https://{{YOUR_SHOPIFY_URL}}.myshopify.com/{{EXTERNAL_ID}}",
      "createdAt": "2024-11-07T11:57:25.000Z",
      "updatedAt": "2024-11-07T11:57:25.000Z",
      "shopId": "{{YOUR_SHOPIFY_URL}}.myshopify.com"
    }
  ]
}

Authorizations

​
x-api-key
string
header
required

Body

application/json
Minimum array length: 1
​
id
string
required

Unique order identifier

Example:

"08c0e60e-26bd-4e41-bb05-97bfbe1ba7cd"

​
friendlyName
string
required

Human-readable order name (e.g., #1059)

Example:

"#1059"

​
customer
object
required
​
orderTotal
number
required

Total order amount in Stripe format (e.g., 3995 = $39.95)

Example:

3995

​
currency
string
required

Currency code following ISO 4217 standard

Example:

"USD"

​
items
object[]
required

Array of ordered items

​
externalId
string

Order ID in the external system (your internal ID)

Example:

"order_12345"

​
metadata
object

Additional information in JSON format for AI prompting

Example:
{
  "preorder": true,
  "gift_message": "Happy Birthday!"
}
​
status
enum<string>

Current order status

Available options:
open,
paid,
refunded,
partially_refunded,
cancelled,
disputed,
completed,
shipped,
fulfilled
Example:

"paid"

​
shipmentStatus
enum<string>

Shipping status

Available options:
none,
confirmed,
in_transit,
out_for_delivery,
attempted_delivery,
ready_for_pickup,
delivered,
failure
Example:

"in_transit"

​
source
enum<string>

Order source

Available options:
online,
in_store
Example:

"online"

​
trackingUrl
string

Shipping tracking URL

Example:

"https://tracking.example.com/12345"

​
address
object

Response

Orders created successfully

​
count
integer

Number of orders created

Example:

2

​
result
object[]

Array of created orders