Omneo SDK

The Omneo SDK (@omneo/omneo-sdk) is the typed JavaScript and TypeScript client for the Omneo API. Install it once and use it in Node or in the browser.

Installation

npm install @omneo/omneo-sdk

yarn add @omneo/omneo-sdk

The package requires Node >=20. It ships ESM and CJS builds with TypeScript types. For browser-only loading without a bundler, import the ESM build from unpkg:

<script type="module">
  import { Omneo, ID } from 'https://unpkg.com/@omneo/omneo-sdk/dist/index.js'
</script>

Two clients

The SDK exports two classes from a single package. Pick the one that matches your runtime and authentication context.

Client	Authentication	Runtime	Use it for
`Omneo`	Bearer API token	Server-side only	Backend integrations, batch jobs, admin tooling, server-rendered profile data
`ID`	Profile-scoped JWT (`IDToken`)	Server-side mint, then safe in the browser	Storefronts, profile portals, customer-facing UIs

The Omneo client carries the full admin API surface and a token with broad scopes. Never ship that token to a browser. The ID client is initialised once on a trusted server with an admin token to mint a short-lived, profile-scoped IDToken. You can then hand that token to the browser, where new ID({ tenant, IDToken }) is safe to use against the customer’s own profile only.

Picking a client

Building…	Use
A storefront, customer UI, or any browser-facing surface	`ID`
A backend service, batch import, or admin tool	`Omneo`

Migration from the legacy Shapes SDK

The previous script-tag library at cdn.getomneo.com/sdk/omneo.js, with OmneoSDK.init() (also referred to as ShapesSDK.init()), .hydrate(), .find(), .on(), and .off(), is deprecated. New integrations must use @omneo/omneo-sdk.

The legacy library was event-driven. The current SDK is promise-based with typed namespaces. Common patterns map as follows:

Legacy	Current
`ShapesSDK.init({ url, token })`	`new ID({ tenant, IDToken })`
`client.hydrate('profile')` + `client.on('profile.ready', fn)`	`await id.profile.get()`
`client.hydrate('transactions')` + `client.on('transactions.ready', fn)`	`await id.profile.transactions.list()`
`client.get('transactions?include=product')`	`await id.profile.transactions.list({ include: 'product' })` or `id.call({ method: 'GET', endpoint: '/profile/transactions', params: { include: 'product' } })`
`client.find('balances.combined_balance_dollars')`	`await id.profile.balances.list()`
`client.off(event, handler)`	Not required, calls are one-shot promises

Using the Omneo SDK (the Omneo admin client)
Using Omneo ID (the ID profile-scoped client)
Omneo SDK concept
API tokens

Omneo CLI Omneo MCP

⌘I

Core setup

Profiles and data

Commerce

Incentives

Reactions

Webhooks and events

Frontend & SDK

POS integration

Appointments

Lists

Groups

Feedback

Extensions

Installation

Two clients

Picking a client

Migration from the legacy Shapes SDK

​Installation

​Two clients

​Picking a client

​Migration from the legacy Shapes SDK

​Related

Installation

Two clients

Picking a client

Migration from the legacy Shapes SDK

Related