Connect your system to CallYo

1What this is

CallYo holds a merchant’s cash-on-delivery orders and the phone calls their team makes about them. The API lets another program — not a person clicking around — do three things:

• Read orders and their status, so a warehouse knows what to pack.
• Create orders, so a shop or funnel CallYo is not connected to can still feed the call queue.
• Be told when something changes, instead of asking every few minutes.

An order you create does not stop with us. When a caller confirms it, CallYo creates the real order in the merchant’s Shopify store — stock, fulfilment, courier labels and Shopify’s own reports all work from that moment. You are told when it lands, and told if it does not.

Everything lives under https://callyo.ro/api/v1. Every response is JSON. Money is a string, never a number — more on that below, because it is the one thing that catches people out.

2Get a key

A key proves the request is yours. The merchant makes it once, in CallYo, under Settings → API & integrations → Create key, and pastes it into your system. It looks like this:

cyk_live_7Fq2XbW9_kR3nP...
└──┬───┘ └──┬───┘ └─┬──┘
   │        │       └─ the secret — shown once, never again
   │        └───────── the public handle, so keys can be told apart
   └────────────────── environment label

A key carries only the permissions it was given:

Ask for only what you need. A key with orders:read alone cannot change anything, which makes it a safe thing to hand a reporting tool.

3Your first request

Confirm the key works before writing anything else:

curl https://callyo.ro/api/v1/me \
  -H "Authorization: Bearer YOUR_KEY"

{
  "key": {
    "id": "0b6c1f0e-5a3d-4c58-9d5e-2f7a1b0c9e44",
    "prefix": "7Fq2XbW9",
    "name": "Warehouse sync",
    "scopes": ["orders:read", "stores:read"],
    "rate_limit_per_minute": 120,
    "created_at": "2026-09-23T08:00:00+00:00",
    "last_used_at": "2026-09-23T08:14:22+00:00",
    "expires_at": null
  },
  "firma": { "id": "3d1f6c0a-7b1e-4f0e-9c5a-8e2b4d6f1a90", "name": "Lumina Home" },
  "environment": "live"
}

A 401 means the key is wrong, revoked or expired. A 403 means the key is good but is missing a permission, and the message names which one.

Every refusal carries a request_id — quote it if you ask for help and it takes us straight to your exact request.

4Reading orders

curl "https://callyo.ro/api/v1/orders?limit=50" \
  -H "Authorization: Bearer YOUR_KEY"

One order, complete — every field we send, nothing trimmed (an order whose customer pays in the delivery country’s own money also carries customer_total and, per line, customer_unit_price; v1 grows only by adding fields, so ignore fields you do not know):

{
  "id": "6fbadfa8-cac2-4bd7-81f8-999b11d1337e",
  "store_id": "965069f5-1fd4-45d8-8081-acce19616532",
  "status": "confirmed",
  "type": "order",
  "customer": { "name": "Mihai Ionescu", "phone": "0745300112", "email": null },
  "shipping_address": {
    "name": "Mihai Ionescu",
    "line1": "Str. Exemplu 12",
    "line2": null,
    "city": "Cluj-Napoca",
    "region": "Cluj",
    "postcode": "400001",
    "country": "Romania",
    "country_code": "RO",
    "phone": "0745300112"
  },
  "lines": [
    {
      "title": "Set 3 prosoape",
      "quantity": 1,
      "unit_price": "129.00",
      "sku": "PRS-3",
      "external_variant_id": "44012345678",
      "variant_title": "Gri"
    }
  ],
  "total": { "amount": "129.00", "currency": "RON" },
  "origin": {
    "platform": "shopify",
    "external_id": "5501234567",
    "external_number": "2042"
  },
  "push": null,
  "notes": null,
  "phone_order": false,
  "no_answer_count": 1,
  "scheduled_at": null,
  "created_at": "2026-09-23T08:30:00+00:00",
  "received_at": "2026-09-23T08:31:12+00:00",
  "cancelled_at": null,
  "removed_at": null,
  "archived_at": null
}

push is null here because this order came from Shopify — there is nothing to send back. For an order you created it is the answer to “did it reach the shop yet?”, covered in the next section.

type is order or draft; the list holds both. created_at is when the order was placed where it began. received_at is when CallYo last heard about it from the shop, and it does not move when a caller acts — so it cannot tell you what changed.

Paging

A list never answers with a bare array. The orders are under data, and beside them is a next_cursor:

{
  "data": [ { … }, { … } ],
  "next_cursor": "eyJ0IjoiMjAyNi0wOS0yM1QwODozMDowMCswMDowMCIsImkiOiI2ZmJhZGZhOC0…"
}

Pass it back as ?cursor= to get the next page. A null cursor means you have everything. Page size is 1 to 100, and 50 by default. Stop when the cursor is null, not when a page looks short: with a status filter a page can come back short, or even empty, while more remain.

Narrowing the list

Add any of these to the query string. Combine as many as you like:

What the statuses mean

A call nobody answered is not a status. The order stays pending_call and no_answer_count goes up by one.

5Pushing an order in — and on to Shopify

For a shop or funnel CallYo is not connected to. The order lands in the call queue exactly like any other, counts toward the merchant’s plan, and shows in their revenue.

curl -X POST https://callyo.ro/api/v1/orders \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-7781" \
  -d '{
      "store_id": "965069f5-1fd4-45d8-8081-acce19616532",
      "origin": { "external_id": "7781", "external_number": "#7781" },
      "customer": { "name": "Elena Radu", "phone": "0733221100" },
      "shipping_address": {
        "name": "Elena Radu",
        "line1": "Bd. Eroilor 4, ap. 2",
        "city": "Brașov",
        "region": "Brașov",
        "postcode": "500036"
      },
      "lines": [
        { "title": "Lampă de birou LED", "quantity": 2, "unit_price": "89.50" }
      ],
      "total": "179.00"
    }'

It answers 201 with the order, in the same shape as above — keep its id. The store_id you send comes from GET /stores.

Send total when it includes something the lines do not — a delivery fee, a cash-on-delivery surcharge. That is the figure the caller reads to the customer, and the difference becomes a delivery line on the Shopify order.

The Idempotency-Key header is required, and it protects you

Networks time out. When yours does you do not know whether we got the order, and retrying blindly is how a customer receives two parcels. So every create carries a key you invent, and we remember what we answered:

Use your own order number — order-7781. Reuse it for every retry of that order and never for anything else. We remember for 24 hours; after that the external_id rule still stops a duplicate.

And on to Shopify

When the caller confirms, CallYo creates the real order in the merchant’s Shopify store: the same basket at the same prices, plus whatever your total carried beyond the lines, tagged API so it is recognisable in the Shopify admin.

The push object on every order you created says what happened. These are the parts that move:

{
  "status": "confirmed",
  "origin": {
    "platform": "shopify",
    "external_id": "7781",
    "external_number": "7781"
  },
  "push": {
    "platform": "shopify",
    "state": "pushed",
    "external_id": "5501234931",
    "at": "2026-09-23T08:14:22+00:00"
  }
}

origin.external_id is still your id, exactly as you sent it. push.external_id is Shopify’s own order id.

A retry is never a second order. Every push is signed with the CallYo order id on the Shopify side, and we ask Shopify whether that signature already exists before creating anything — so a lost answer, a timeout or a crash halfway through cannot leave the customer with two parcels.

6Being told when something happens

Register a URL and we POST to it when something changes. It has to be https and reachable from the public internet. The merchant can register it in Settings → API & integrations, or you can do it yourself with a key that has webhooks:manage:

curl -X POST https://callyo.ro/api/v1/webhooks \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "url": "https://your-server.example/callyo/webhook",
      "events": [
        "order.created",
        "order.status_changed",
        "order.pushed",
        "order.push_failed",
        "order.updated"
      ]
    }'

Read the reply carefully — the endpoint is nested, and the secret is not:

{
  "endpoint": {
    "id": "45711d04-2ed9-4abb-b64d-55a3e5382884",
    "url": "https://your-server.example/callyo/webhook",
    "events": [
      "order.created",
      "order.status_changed",
      "order.pushed",
      "order.push_failed",
      "order.updated"
    ],
    "secret_prefix": "juNCYZwr",
    "description": null,
    "active": true,
    "consecutive_failures": 0,
    "disabled_at": null,
    "disabled_reason": null,
    "created_at": "2026-09-23T08:00:00+00:00",
    "last_delivery_at": null,
    "last_success_at": null
  },
  "secret": "cyw_juNCYZwr_udeLS0seLBMsAMQAkbnoknf3cbntlUym"
}

The five things we will tell you

What a delivery looks like

POST https://your-server.example/callyo/webhook
Content-Type: application/json; charset=utf-8
User-Agent: CallYo-Webhooks/1
X-CallYo-Event: order.status_changed
X-CallYo-Event-Id: 7da50f76-d4e7-4e6f-902d-b0e1940cbd29
X-CallYo-Delivery-Id: 1f0c8e21-5d0a-4c3e-9a57-0d7e6b2f4c18
X-CallYo-Signature: t=1790182637,v1=82ca2a3322dff7d7b6f38a70d5c0a4f1…

{
  "id": "1f0c8e21-5d0a-4c3e-9a57-0d7e6b2f4c18",
  "event": "order.status_changed",
  "event_id": "7da50f76-d4e7-4e6f-902d-b0e1940cbd29",
  "occurred_at": "2026-09-23T21:06:01.644380+00:00",
  "data": {
    "order": { … the whole order, exactly as under “Reading orders” … },
    "previous_status": "pending_call"
  }
}

The order inside is the order as it is when we send it, not as it was when the event happened — the same thing GET /orders/{id} would answer at that moment. previous_status is the one thing kept from before.

A test delivery is not an order event

Send test sends a ping. It proves your URL is reachable, your TLS is valid and your signature check works — but it describes no order, so it carries no event id at all. The X-CallYo-Event-Id header is left out, not sent empty:

X-CallYo-Event: ping
X-CallYo-Delivery-Id: 303ae418-10fe-496b-8ee5-bd353765634c
X-CallYo-Signature: t=1790182637,v1=82ca2a3322dff7d7b6f38a70d5c0a4f1…

{
  "id": "303ae418-10fe-496b-8ee5-bd353765634c",
  "event": "ping",
  "event_id": null,
  "occurred_at": "2026-09-23T21:06:01.644Z",
  "data": {
    "message": "This is a test delivery from CallYo. If your signature check passed, you are ready to receive order events."
  }
}

Test deliveries are limited to 10 a minute, and they never count toward the twenty failures that switch an endpoint off.

7Checking a delivery came from us

Your webhook URL is public, so anyone could POST to it. The signature is how you tell our delivery from someone else’s. Do this before you trust the contents.

X-CallYo-Signature is t=<unix>,v1=<hex> where the hex is hmac_sha256(secret, "<t>.<raw body>"). The secret is the whole string you were given, cyw_ included. Use the raw body, before parsing — re-serialising JSON changes bytes and therefore the signature.

import { createHmac, timingSafeEqual } from 'crypto'

function verify(rawBody, header, secret, toleranceSec = 300) {
  const parts = Object.fromEntries(header.split(',').map(p => p.split('=')))
  const expected = createHmac('sha256', secret)
    .update(`${parts.t}.${rawBody}`, 'utf8').digest('hex')

  const a = Buffer.from(expected, 'hex')
  const b = Buffer.from(parts.v1, 'hex')
  if (a.length !== b.length || !timingSafeEqual(a, b)) return false

  // Reject a stale timestamp, or a captured delivery can be replayed at you forever.
  return Math.abs(Date.now() / 1000 - Number(parts.t)) < toleranceSec
}

8If you cannot receive webhooks

Plenty of systems cannot accept an incoming request — an ERP behind a corporate firewall, a back office on someone’s laptop. Poll instead. The same events, in a slightly flatter shape.

curl "https://callyo.ro/api/v1/events?limit=100" \
  -H "Authorization: Bearer YOUR_KEY"

{
  "data": [
    {
      "id": "7da50f76-d4e7-4e6f-902d-b0e1940cbd29",
      "event": "order.status_changed",
      "occurred_at": "2026-09-23T21:06:01.644380+00:00",
      "order": { … the whole order, exactly as under “Reading orders” … },
      "previous_status": "pending_call"
    }
  ],
  "next_cursor": null
}

Two differences from a webhook body, and both are easy to trip on. The fields sit at the top level rather than under data. And id here is the event’s id — the value a webhook calls event_id and sends as X-CallYo-Event-Id. Deduplicate on it and the two channels agree.

The feed is newest first, and next_cursor walks backwards in time. To catch up, start from the top and follow the cursor until you reach an id you have already handled, then work through what you collected, oldest first. Add ?event= to read one kind only. As with a webhook, each item carries the order as it is now.

9When something goes wrong

Every refusal is the same shape — the standard one, RFC 9457 — so you can handle them all in one place.

{
  "type": "https://callyo.ro/api/v1/errors#unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "That API key is not valid for this request.",
  "instance": "/api/v1/me",
  "code": "unauthorized",
  "request_id": "fra1::sj77q-1788989400308-0289c305543f"
}

Switch on code, never on the prose in detail — the wording may improve, the code will not. The complete list is at https://callyo.ro/api/v1/errors, and every type is a link you can open. A 422 for a body we could not accept also carries an errors list naming each field and what is wrong with it.

An x-retryable header says whether sending the same request again could succeed. A 429 says yes, after a wait: you are over the rate limit, and its retry-after header is the number of seconds after which the limit is certain to have cleared. Quote the request_id when you ask for support.

10Reference

Everything you can call

Numbers to design around

What this cannot do

Worth reading before you design around it — finding a missing verb halfway through a build costs far more than finding it here.

• Create or connect shops. A merchant does that in CallYo with Shopify’s own login. The API only reads them.
• Edit an order. There is no PATCH. Callers edit orders; you send them.
• Delete an order. A merchant should not be able to erase a confirmed sale.
• List what changed since a date. created_since is about when an order was placed. Changes are what webhooks and the event feed are for.
• Tell you about CallYo’s own bookkeeping. Notes, assignment and sync stamps never produce an event — they mean nothing outside CallYo. A caller changing the order does: subscribe to order.updated.
• Choose where a confirmed order goes. The merchant sets that per shop in CallYo: Shopify by default, their warehouse, or nowhere. The API cannot change it and does not report it.
• Follow an order into a warehouse. The warehouse’s reference, the tracking number and the delivery status are not in the API yet.

Generate a client instead of writing one

https://callyo.ro/api/v1/openapi.json is the full machine-readable contract, including the webhook delivery shape. Most languages have a generator that turns it into a typed client — less work and fewer mistakes than writing requests by hand.