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": "order_12345",
  "friendlyName": "#1059",
  "customer": {
    "id": "customer_67890",
    "firstName": "John",
    "lastName": "Doe",
    "userIds": [
      {
        "type": "email",
        "id": "john.doe@example.com"
      }
    ]
  },
  "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
    }
  ],
  "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"
  }
}'
{
  "id": "be6ed223-19c3-47db-8635-794f856e1956",
  "contactId": "21f0cf2f-30cd-4e13-9cde-7a3e4e77deff",
  "externalName": "1001",
  "externalId": "5210634092624",
  "firstName": "Jeff",
  "lastName": "Bezos",
  "email": "jeff@amazon.com",
  "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
​
id
string
required

Unique order identifier

Example:

"order_12345"

​
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

​
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

Order created successfully

​
id
string
Example:

"be6ed223-19c3-47db-8635-794f856e1956"

​
contactId
string
Example:

"21f0cf2f-30cd-4e13-9cde-7a3e4e77deff"

​
externalName
string
Example:

"1001"

​
externalId
string
Example:

"5210634092624"

​
firstName
string
Example:

"Jeff"

​
lastName
string
Example:

"Bezos"

​
email
string
Example:

"jeff@amazon.com"

​
phoneNumber
string
Example:

"+15551234"

​
orderTotal
number
Example:

69995

​
currency
string
Example:

"eur"

​
channel
string
Example:

"SHOPIFY"

​
status
string
Example:

"PAID"

​
trackingUrl
string
Example:

"https://{{YOUR_SHOPIFY_URL}}.myshopify.com/{{EXTERNAL_ID}}"

​
createdAt
string
Example:

"2024-11-07T11:57:25.000Z"

​
updatedAt
string
Example:

"2024-11-07T11:57:25.000Z"

​
shopId
string
Example:

"{{YOUR_SHOPIFY_URL}}.myshopify.com"