Using the Omneo SDK

Reach for the Omneo client when you are writing trusted server code: backend integrations, batch jobs, admin tooling, or server-rendered views that need the full admin API surface. For customer-facing storefronts, use the ID client instead. Make sure you have installed the package and have a token. See SDK installation and API tokens.

Initialisation

import { Omneo } from '@omneo/omneo-sdk'

const omneo = new Omneo({
  tenant: '[tenant]',
  token: process.env.OMNEO_TOKEN
})

Option	Required	Description
`tenant`	Yes	The Omneo tenant handle, used to derive the base URL `https://api.[tenant].getomneo.com/api/v3`.
`token`	Yes	A bearer API token created in CX Manager.
`baseURL`	No	Override the default base URL, for example to point at a sandbox proxy.

The token carries broad admin scopes. Keep it on a server. Do not expose it to a browser.

Resource namespaces

The Omneo client exposes around 59 resource namespaces, one per top-level Omneo concept. A representative subset:

Namespace	Wraps
`omneo.profiles`	Profile records and profile-scoped sub-resources
`omneo.transactions`	Completed transactions
`omneo.orders`	Pre-purchase orders
`omneo.rewards`, `omneo.rewardDefinitions`	Reward instances and definitions
`omneo.benefits`, `omneo.benefitDefinitions`	Benefit instances and definitions
`omneo.tiers`, `omneo.tierDefinitions`, `omneo.tierPoints`	Tier status and tier point ledgers
`omneo.points`, `omneo.pointDefinitions`	Point ledgers and definitions
`omneo.lists`, `omneo.listDefinitions`	Lists and list configuration
`omneo.targets`, `omneo.webhooks`	Webhook targets and webhook events
`omneo.batches`, `omneo.imports`	Batch operations and imports

For the canonical list of namespaces and methods, see the SDK source.

Global and profile-scoped calls

The SDK mirrors the global vs profile-scoped route pattern. Top-level namespaces hit global endpoints. Profile sub-resources hang off omneo.profiles and require a profile ID.

Route	SDK call	HTTP path
Global	`omneo.transactions.list()`	`GET /v3/transactions`
Profile-scoped	`omneo.profiles.transactions.list(profileId)`	`GET /v3/profiles/{id}/transactions`
Global	`omneo.rewards.list()`	`GET /v3/rewards`
Profile-scoped	`omneo.profiles.rewards.list(profileId)`	`GET /v3/profiles/{id}/rewards`

Profile sub-namespaces include addresses, aggregations, attributes, balances, benefits, connections, credits, identities, interactions, ledgers, lists, orders, points, redemptions, regions, rewards, tiers, transactionClaims, and transactions.

Common patterns

List profiles with pagination:

const profiles = await omneo.profiles.list({ page: 1, per_page: 50 })

Fetch a single transaction by ID:

const transaction = await omneo.transactions.get(transactionId)

Find a profile by an external identity (for example, a Shopify customer ID):

const profile = await omneo.profiles.findByIdentity('1004993MH', 'shopify_id')

Subscribe a profile to email comms:

await omneo.profiles.attributes.comms.subscribe(profileId, { channel: 'email' })

Escape hatch: `call()`

Use omneo.call() for endpoints the SDK does not yet wrap, or for one-off requests with custom headers. The method handles authentication and base URL for you.

await omneo.call({
  method: 'POST',
  endpoint: '/profiles',
  body: { first_name: 'Test', last_name: 'Profile', email: 'test@example.com' }
})

Field	Description
`method`	HTTP method (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`).
`endpoint`	Path appended to the base URL. Leading slash optional.
`params`	Object serialised to the query string.
`body`	Object serialised as JSON.
`headers`	Extra headers merged onto the default `Authorization` and `Content-Type`.

Errors and responses

Successful calls resolve with the parsed JSON body. Non-2xx responses reject with the parsed error body, so handle them with standard promise control flow:

try {
  const profile = await omneo.profiles.get(profileId)
} catch (error) {
  // error contains the parsed Omneo error payload
}

Responses that are not JSON fall back to a raw response object, useful for binary or text endpoints called via call().

Core setup

Profiles and data

Commerce

Incentives

Reactions

Webhooks and events

Frontend & SDK

POS integration

Appointments

Lists

Groups

Feedback

Extensions

Using the Omneo SDK

Initialisation

Resource namespaces

Global and profile-scoped calls

Common patterns

Escape hatch: `call()`

Errors and responses

​Initialisation

​Resource namespaces

​Global and profile-scoped calls

​Common patterns

​Escape hatch: call()

​Errors and responses

​Related

Initialisation

Resource namespaces

Global and profile-scoped calls

Common patterns

Escape hatch: `call()`

Errors and responses

Related