Overview

What the API does

The Omneya REST API lets your app work directly with an Omneya shop. With version 1 you can:

• send orders, which the shop creates as regular orders
• check an order without creating anything
• read any order of your shop by its order number, including status, addresses and tracking numbers
• look up the payment methods, referrers and order statuses your order needs
• read customers that your app created or that were matched to your app
• maintain those customers: addresses, notes, labels and customer class

Every endpoint is listed in the API reference. The full specification is available as an OpenAPI file: openapi-v1.yaml. You can import it into Postman or a code generator.

Base URL

Each shop has its own address. The examples in this documentation use a placeholder:

https://shop.example.com/api/v1

Replace shop.example.com with the address the shop operator gives you. All paths in this documentation are relative to this base URL, for example GET /ping means GET https://shop.example.com/api/v1/ping. Use HTTPS for every request.

Access

The shop operator creates an API key for your app in the shop’s admin area and decides what the key may do. You send the key with every request as a bearer token. See Authentication.

If the API is not enabled for a shop, every path under /api/v1 answers 404.

Request and response format

Protocol	HTTPS
Data format	JSON, UTF-8
Authentication	API key as bearer token
Request headers	Authorization, Content-Type: application/json, Accept: application/json

Successful responses with content wrap their payload in data:

{
  "data": { "id": 17, "name": "Example Store App" }
}

There are three exceptions:

• GET /ping answers without the data wrapper.
• Creating an order also returns a top-level warnings list next to data.
• Delete requests answer 204 No Content without a body.

Errors always use the same envelope with a stable error.code. See Errors.

Endpoints at a glance

Area	Endpoints
Connection	Test the connection
Orders	Create an order, Validate an order, Get an order
Lookups	List payment methods, List referrers, List order statuses
Customers	Get a customer
Customer addresses	List, create, update, delete
Customer notes	Create a note
Customer labels	List labels, set labels, remove a label
Customer classes	List classes, set the class

Which key may call which endpoint is defined by scopes. See the scope reference.

Where to start

1. Authentication: get a key and send it.
2. Your first request: test the connection.
3. Send an order: the main use case, end to end.
4. Go-live checklist: what to check before real orders arrive.

While you build, an AI assistant can read this documentation, look up IDs and check your requests with you. See Integrate with an AI assistant.