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": "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
}
],
"externalId": "order_12345",
"metadata": {
"preorder": true,
"gift_message": "Happy Birthday!"
},
"status": "paid",
"shipmentStatus": "in_transit",
"source": "online",
"trackingUrl": "https://tracking.example.com/12345"
}
]
'import requests
url = "https://api.konvoai.com/orders"
payload = [
{
"id": "08c0e60e-26bd-4e41-bb05-97bfbe1ba7cd",
"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
}
],
"externalId": "order_12345",
"metadata": {
"preorder": True,
"gift_message": "Happy Birthday!"
},
"status": "paid",
"shipmentStatus": "in_transit",
"source": "online",
"trackingUrl": "https://tracking.example.com/12345"
}
]
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify([
{
id: '08c0e60e-26bd-4e41-bb05-97bfbe1ba7cd',
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
}
],
externalId: 'order_12345',
metadata: {preorder: true, gift_message: 'Happy Birthday!'},
status: 'paid',
shipmentStatus: 'in_transit',
source: 'online',
trackingUrl: 'https://tracking.example.com/12345'
}
])
};
fetch('https://api.konvoai.com/orders', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.konvoai.com/orders",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
[
'id' => '08c0e60e-26bd-4e41-bb05-97bfbe1ba7cd',
'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
]
],
'externalId' => 'order_12345',
'metadata' => [
'preorder' => true,
'gift_message' => 'Happy Birthday!'
],
'status' => 'paid',
'shipmentStatus' => 'in_transit',
'source' => 'online',
'trackingUrl' => 'https://tracking.example.com/12345'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.konvoai.com/orders"
payload := strings.NewReader("[\n {\n \"id\": \"08c0e60e-26bd-4e41-bb05-97bfbe1ba7cd\",\n \"friendlyName\": \"#1059\",\n \"customer\": {\n \"id\": \"customer_67890\",\n \"firstName\": \"John\",\n \"lastName\": \"Doe\",\n \"userIds\": [\n {\n \"type\": \"email\",\n \"id\": \"john.doe@example.com\"\n }\n ]\n },\n \"orderTotal\": 3995,\n \"currency\": \"USD\",\n \"items\": [\n {\n \"id\": \"variant_123\",\n \"sku\": \"SHIRT-BLU-M\",\n \"name\": \"Blue T-Shirt - Medium\",\n \"description\": \"Comfortable cotton t-shirt in blue\",\n \"price\": 2999,\n \"msrp\": 3999,\n \"imageUrl\": \"https://example.com/images/blue-tshirt.jpg\",\n \"currency\": \"USD\",\n \"available\": true,\n \"inventoryQuantity\": 150,\n \"quantity\": 2\n }\n ],\n \"externalId\": \"order_12345\",\n \"metadata\": {\n \"preorder\": true,\n \"gift_message\": \"Happy Birthday!\"\n },\n \"status\": \"paid\",\n \"shipmentStatus\": \"in_transit\",\n \"source\": \"online\",\n \"trackingUrl\": \"https://tracking.example.com/12345\"\n }\n]")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.konvoai.com/orders")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("[\n {\n \"id\": \"08c0e60e-26bd-4e41-bb05-97bfbe1ba7cd\",\n \"friendlyName\": \"#1059\",\n \"customer\": {\n \"id\": \"customer_67890\",\n \"firstName\": \"John\",\n \"lastName\": \"Doe\",\n \"userIds\": [\n {\n \"type\": \"email\",\n \"id\": \"john.doe@example.com\"\n }\n ]\n },\n \"orderTotal\": 3995,\n \"currency\": \"USD\",\n \"items\": [\n {\n \"id\": \"variant_123\",\n \"sku\": \"SHIRT-BLU-M\",\n \"name\": \"Blue T-Shirt - Medium\",\n \"description\": \"Comfortable cotton t-shirt in blue\",\n \"price\": 2999,\n \"msrp\": 3999,\n \"imageUrl\": \"https://example.com/images/blue-tshirt.jpg\",\n \"currency\": \"USD\",\n \"available\": true,\n \"inventoryQuantity\": 150,\n \"quantity\": 2\n }\n ],\n \"externalId\": \"order_12345\",\n \"metadata\": {\n \"preorder\": true,\n \"gift_message\": \"Happy Birthday!\"\n },\n \"status\": \"paid\",\n \"shipmentStatus\": \"in_transit\",\n \"source\": \"online\",\n \"trackingUrl\": \"https://tracking.example.com/12345\"\n }\n]")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.konvoai.com/orders")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "[\n {\n \"id\": \"08c0e60e-26bd-4e41-bb05-97bfbe1ba7cd\",\n \"friendlyName\": \"#1059\",\n \"customer\": {\n \"id\": \"customer_67890\",\n \"firstName\": \"John\",\n \"lastName\": \"Doe\",\n \"userIds\": [\n {\n \"type\": \"email\",\n \"id\": \"john.doe@example.com\"\n }\n ]\n },\n \"orderTotal\": 3995,\n \"currency\": \"USD\",\n \"items\": [\n {\n \"id\": \"variant_123\",\n \"sku\": \"SHIRT-BLU-M\",\n \"name\": \"Blue T-Shirt - Medium\",\n \"description\": \"Comfortable cotton t-shirt in blue\",\n \"price\": 2999,\n \"msrp\": 3999,\n \"imageUrl\": \"https://example.com/images/blue-tshirt.jpg\",\n \"currency\": \"USD\",\n \"available\": true,\n \"inventoryQuantity\": 150,\n \"quantity\": 2\n }\n ],\n \"externalId\": \"order_12345\",\n \"metadata\": {\n \"preorder\": true,\n \"gift_message\": \"Happy Birthday!\"\n },\n \"status\": \"paid\",\n \"shipmentStatus\": \"in_transit\",\n \"source\": \"online\",\n \"trackingUrl\": \"https://tracking.example.com/12345\"\n }\n]"
response = http.request(request)
puts response.read_body{
"count": 2,
"result": [
{
"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"
}
]
}{
"error": 123,
"message": "<string>"
}Orders
Create Orders
Create one or more orders
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": "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
}
],
"externalId": "order_12345",
"metadata": {
"preorder": true,
"gift_message": "Happy Birthday!"
},
"status": "paid",
"shipmentStatus": "in_transit",
"source": "online",
"trackingUrl": "https://tracking.example.com/12345"
}
]
'import requests
url = "https://api.konvoai.com/orders"
payload = [
{
"id": "08c0e60e-26bd-4e41-bb05-97bfbe1ba7cd",
"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
}
],
"externalId": "order_12345",
"metadata": {
"preorder": True,
"gift_message": "Happy Birthday!"
},
"status": "paid",
"shipmentStatus": "in_transit",
"source": "online",
"trackingUrl": "https://tracking.example.com/12345"
}
]
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify([
{
id: '08c0e60e-26bd-4e41-bb05-97bfbe1ba7cd',
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
}
],
externalId: 'order_12345',
metadata: {preorder: true, gift_message: 'Happy Birthday!'},
status: 'paid',
shipmentStatus: 'in_transit',
source: 'online',
trackingUrl: 'https://tracking.example.com/12345'
}
])
};
fetch('https://api.konvoai.com/orders', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.konvoai.com/orders",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
[
'id' => '08c0e60e-26bd-4e41-bb05-97bfbe1ba7cd',
'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
]
],
'externalId' => 'order_12345',
'metadata' => [
'preorder' => true,
'gift_message' => 'Happy Birthday!'
],
'status' => 'paid',
'shipmentStatus' => 'in_transit',
'source' => 'online',
'trackingUrl' => 'https://tracking.example.com/12345'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.konvoai.com/orders"
payload := strings.NewReader("[\n {\n \"id\": \"08c0e60e-26bd-4e41-bb05-97bfbe1ba7cd\",\n \"friendlyName\": \"#1059\",\n \"customer\": {\n \"id\": \"customer_67890\",\n \"firstName\": \"John\",\n \"lastName\": \"Doe\",\n \"userIds\": [\n {\n \"type\": \"email\",\n \"id\": \"john.doe@example.com\"\n }\n ]\n },\n \"orderTotal\": 3995,\n \"currency\": \"USD\",\n \"items\": [\n {\n \"id\": \"variant_123\",\n \"sku\": \"SHIRT-BLU-M\",\n \"name\": \"Blue T-Shirt - Medium\",\n \"description\": \"Comfortable cotton t-shirt in blue\",\n \"price\": 2999,\n \"msrp\": 3999,\n \"imageUrl\": \"https://example.com/images/blue-tshirt.jpg\",\n \"currency\": \"USD\",\n \"available\": true,\n \"inventoryQuantity\": 150,\n \"quantity\": 2\n }\n ],\n \"externalId\": \"order_12345\",\n \"metadata\": {\n \"preorder\": true,\n \"gift_message\": \"Happy Birthday!\"\n },\n \"status\": \"paid\",\n \"shipmentStatus\": \"in_transit\",\n \"source\": \"online\",\n \"trackingUrl\": \"https://tracking.example.com/12345\"\n }\n]")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.konvoai.com/orders")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("[\n {\n \"id\": \"08c0e60e-26bd-4e41-bb05-97bfbe1ba7cd\",\n \"friendlyName\": \"#1059\",\n \"customer\": {\n \"id\": \"customer_67890\",\n \"firstName\": \"John\",\n \"lastName\": \"Doe\",\n \"userIds\": [\n {\n \"type\": \"email\",\n \"id\": \"john.doe@example.com\"\n }\n ]\n },\n \"orderTotal\": 3995,\n \"currency\": \"USD\",\n \"items\": [\n {\n \"id\": \"variant_123\",\n \"sku\": \"SHIRT-BLU-M\",\n \"name\": \"Blue T-Shirt - Medium\",\n \"description\": \"Comfortable cotton t-shirt in blue\",\n \"price\": 2999,\n \"msrp\": 3999,\n \"imageUrl\": \"https://example.com/images/blue-tshirt.jpg\",\n \"currency\": \"USD\",\n \"available\": true,\n \"inventoryQuantity\": 150,\n \"quantity\": 2\n }\n ],\n \"externalId\": \"order_12345\",\n \"metadata\": {\n \"preorder\": true,\n \"gift_message\": \"Happy Birthday!\"\n },\n \"status\": \"paid\",\n \"shipmentStatus\": \"in_transit\",\n \"source\": \"online\",\n \"trackingUrl\": \"https://tracking.example.com/12345\"\n }\n]")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.konvoai.com/orders")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "[\n {\n \"id\": \"08c0e60e-26bd-4e41-bb05-97bfbe1ba7cd\",\n \"friendlyName\": \"#1059\",\n \"customer\": {\n \"id\": \"customer_67890\",\n \"firstName\": \"John\",\n \"lastName\": \"Doe\",\n \"userIds\": [\n {\n \"type\": \"email\",\n \"id\": \"john.doe@example.com\"\n }\n ]\n },\n \"orderTotal\": 3995,\n \"currency\": \"USD\",\n \"items\": [\n {\n \"id\": \"variant_123\",\n \"sku\": \"SHIRT-BLU-M\",\n \"name\": \"Blue T-Shirt - Medium\",\n \"description\": \"Comfortable cotton t-shirt in blue\",\n \"price\": 2999,\n \"msrp\": 3999,\n \"imageUrl\": \"https://example.com/images/blue-tshirt.jpg\",\n \"currency\": \"USD\",\n \"available\": true,\n \"inventoryQuantity\": 150,\n \"quantity\": 2\n }\n ],\n \"externalId\": \"order_12345\",\n \"metadata\": {\n \"preorder\": true,\n \"gift_message\": \"Happy Birthday!\"\n },\n \"status\": \"paid\",\n \"shipmentStatus\": \"in_transit\",\n \"source\": \"online\",\n \"trackingUrl\": \"https://tracking.example.com/12345\"\n }\n]"
response = http.request(request)
puts response.read_body{
"count": 2,
"result": [
{
"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"
}
]
}{
"error": 123,
"message": "<string>"
}Authorizations
Body
application/json
Minimum array length:
1Unique order identifier
Example:
"08c0e60e-26bd-4e41-bb05-97bfbe1ba7cd"
Human-readable order name (e.g., #1059)
Example:
"#1059"
Show child attributes
Show child attributes
Total order amount in Stripe format (e.g., 3995 = $39.95)
Example:
3995
Currency code following ISO 4217 standard
Example:
"USD"
Array of ordered items
Show child attributes
Show child attributes
Order ID in the external system (your internal ID)
Example:
"order_12345"
Additional information in JSON format for AI prompting
Example:
{
"preorder": true,
"gift_message": "Happy Birthday!"
}
Current order status
Available options:
open, paid, refunded, partially_refunded, cancelled, disputed, completed, shipped, fulfilled Example:
"paid"
Shipping status
Available options:
none, confirmed, in_transit, out_for_delivery, attempted_delivery, ready_for_pickup, delivered, failure Example:
"in_transit"
Order source
Available options:
online, in_store Example:
"online"
Shipping tracking URL
Example:
"https://tracking.example.com/12345"
Show child attributes
Show child attributes
