Upsert Order - Developer docs

curl --request PATCH \ --url https://api.konvoai.com/orders/{ID} \ --header 'Content-Type: application/json' \ --header 'x-api-key: <api-key>' \ --data ' { "friendlyName": "#1059", "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" } '

{ "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

Path Parameters

string

required

ID of the order to update

Body

application/json

Schema for updating an order. All fields are optional except the ID in the path.

friendlyName

string

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

Example:

"#1059"

customer

object

Show child attributes

orderTotal

number

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

Example:

3995

currency

string

Currency code following ISO 4217 standard

Example:

"USD"

items

object[]

Array of ordered items

Show child attributes

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

Show child attributes

Response

Order updated successfully

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"

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"