Vektra Connect API

Last updated: 19 September 2026

How it works Push orders Order fields Lookup on your server Privacy rules Limits

Vektra answers from your website. Your orders are not on your website, so questions like “where is my order?” used to end with a handover. Connect fixes that: give Vektra a way to see an order, and the assistant answers with the status, the tracking number and the expected delivery, in the visitor’s language, with the same rule as everything else — it never invents a detail it was not given.

How it works

There are two ways to connect. Pick one; you can use both.

Way	You do	Good for
Push	Send each order to Vektra when it is created or its status changes. One HTTP call.	Shops with a webhook, a plugin, Zapier or Make. No endpoint to host.
Lookup	Host one small endpoint. Vektra calls it when a visitor asks, signed, and reads the answer.	Shops that want their database to stay the only copy.

In both cases the visitor must give the assistant the order number and the email address used at checkoutbefore it says anything about an order. If either is missing, it asks for it. If they do not match, it says it could not find the order and offers a colleague.

Your API key and the lookup settings are in the console under Integrations. Connect is part of the Business plan.

Push orders

POST https://www.askvektra.com/api/connect/orders with Authorization: Bearer vk_…. Send one order, or up to 500 in { "orders": [ … ] }. The same order number sent again replaces the stored one, so a status change is just another POST.

curl -X POST https://www.askvektra.com/api/connect/orders \
  -H "Authorization: Bearer vk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "10482",
    "email": "anna@example.at",
    "status": "shipped",
    "placedAt": "2026-09-14T10:22:00Z",
    "total": "1299.00",
    "currency": "EUR",
    "items": [{ "name": "Tourer 28 Deep Blue, size 56", "qty": 1, "sku": "T28-DB-56" }],
    "tracking": { "carrier": "DHL", "number": "00340434161234567890", "url": "https://www.dhl.de/de/privatkunden/pakete-empfangen/verfolgen.html?piececode=00340434161234567890" },
    "eta": "Thursday, 18 September"
  }'

Several at once:

{ "orders": [ { "number": "10482", "email": "anna@example.at", "status": "shipped" },
             { "number": "10483", "email": "ben@example.de",  "status": "paid" } ] }

Response: { "ok": true, "stored": 1, "rejected": [], "total": 412 }. Orders without a valid number or email are listed in rejected and skipped.

To check what is stored: GET /api/connect/orders?number=10482&email=anna@example.at. To remove one: DELETE /api/connect/orders?number=10482.

Order fields

Field	Type	Notes
`number`	string	Required. The number the customer sees. `id` or `order` also accepted.
`email`	string	Required. The checkout email. Compared case-insensitively.
`status`	string	Free text, up to 40 characters: `paid`, `packed`, `shipped`, `delivered`, `cancelled`… The assistant repeats it as you wrote it.
`placedAt`	string	ISO date. `createdAt` also accepted.
`eta`	string	Expected delivery, in words or as a date. `estimatedDelivery` also accepted.
`tracking`	object	`{ carrier, number, url }`. The url must start with http(s).
`items`	array	Up to 50 of `{ name, qty, sku }`.
`total`, `currency`	string	Shown as given, e.g. `"1299.00"` and `"EUR"`.
`note`	string	Up to 300 characters the assistant may repeat to the customer. Do not put internal notes here.
`updatedAt`	string	ISO date. Defaults to now.

Anything else in the payload is ignored. The assistant can only repeat what is in these fields.

Lookup on your server

Set a lookup address and a secret in the console. When a visitor asks about an order and Vektra has nothing stored for that number, it calls:

GET https://shop.example/vektra/order?order=10482&email=anna%40example.at
X-Vektra-Timestamp: 1758200000000
X-Vektra-Signature: 9f2c…   (HMAC-SHA256 of "10482\nanna@example.at\n1758200000000" with your secret)

Answer with 200 and an order in the same shape as above (wrapped in order or not), or 404 if there is no such order for that email. Vektra waits at most 6 seconds.

{
  "order": {
    "number": "10482",
    "email": "anna@example.at",
    "status": "shipped",
    "eta": "Thursday, 18 September",
    "tracking": { "carrier": "DHL", "number": "00340434161234567890" },
    "items": [{ "name": "Tourer 28 Deep Blue, size 56", "qty": 1 }]
  }
}

Verify the signature so nobody else can query your endpoint:

// Node.js — verify the signature on your side
import { createHmac, timingSafeEqual } from 'node:crypto'

export function verify(req, secret) {
  const ts = req.headers['x-vektra-timestamp']
  const sig = req.headers['x-vektra-signature']
  if (Math.abs(Date.now() - Number(ts)) > 5 * 60 * 1000) return false   // older than 5 minutes
  const expected = createHmac('sha256', secret)
    .update(`${req.query.order}\n${req.query.email}\n${ts}`)
    .digest('hex')
  return sig.length === expected.length && timingSafeEqual(Buffer.from(sig), Buffer.from(expected))
}

The console has a Test lookup button: enter an order number and email, and see exactly what Vektra received.

Privacy rules

An order is only ever shown to someone who gives both the order number and the checkout email. A number alone is not enough.
The assistant repeats only the fields above. It does not see and cannot repeat addresses, payment details or internal notes, because you never send them.
Pushed orders are stored in the EU with the rest of your site data. Lookup answers are not stored; they are used for that one reply.
Your API key is a secret. Use it from your server, never from a browser. Rotate it in the console at any time; the old key stops working immediately.

Limits

120 requests a minute per API key, 500 orders per request.
Up to 5,000 stored orders per site; the oldest are dropped first. Use lookup if you have more.
Order answers are not cached: every question about an order reads the current status.

Questions: hello@nexuscode.hu. We answer within a business day.