Your first request

Before you start

You need:

• the shop’s address, for example https://shop.example.com (each shop has its own)
• an API key from the shop operator, see Authentication

Put the key in an environment variable so it does not end up in your shell history or scripts:

export OMNEYA_API_KEY="omn_test_AbCd1234_0123456789abcdefghijABCDEFGHIJ12"

Test the connection

GET /ping checks the key and tells you what it is allowed to do. It needs no scope and changes nothing.

curl -s https://shop.example.com/api/v1/ping \
  -H "Authorization: Bearer $OMNEYA_API_KEY" \
  -H "Accept: application/json"

The raw request:

GET /api/v1/ping HTTP/1.1
Host: shop.example.com
Authorization: Bearer omn_test_AbCd1234_0123456789abcdefghijABCDEFGHIJ12
Accept: application/json

Read the response

A valid key returns 200 OK:

{
  "client": {
    "name": "Example Store App",
    "environment": "test",
    "scopes": ["orders.write", "customers.read"]
  },
  "server_time": "2026-10-14T14:05:00+02:00"
}

client describes your access: the name the operator gave it, its environment (live or test, see Live and test environments) and its scopes (see the scope reference). server_time is the shop’s current time in ISO 8601 with offset. GET /ping is the only endpoint that answers without a data wrapper.

Check client.scopes against what your integration needs. To send orders, orders.write must be listed. If a scope is missing, ask the operator to add it.

Next requests

If your key has orders.write, fetch the IDs you need for orders:

curl -s https://shop.example.com/api/v1/payment-methods \
  -H "Authorization: Bearer $OMNEYA_API_KEY" \
  -H "Accept: application/json"

{
  "data": [
    {
      "id": 3,
      "name": "Invoice",
      "provider": "invoice",
      "customer_class_ids": [],
      "min_order_value": null,
      "max_order_value": null
    }
  ]
}

Then continue with Send an order.

Common problems

Response	Cause	What to do
401 unauthorized	Key missing, mistyped, renewed, paused, expired or revoked	Check the Authorization: Bearer header and the key, then ask the operator whether the access is active
403 insufficient_scope	Key is valid but lacks the scope	Ask the operator to add the scope listed in error.details.missing
404 not_found	Wrong path, or the API is not enabled for this shop	Check the base URL including /api/v1
405 method_not_allowed	Wrong HTTP method, for example POST /ping	Use the method shown in the reference
429 rate_limited	Too many requests or too many failed attempts	Wait for the seconds in Retry-After, see Rate limits
HTML instead of JSON	The address does not point to the shop’s API	Check the host name and that the path starts with /api/v1

All error codes are explained in Errors.