> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omneo.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Using the Omneo SDK

> Server-side patterns for the Omneo admin client from @omneo/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](/dev-guides/frontend/omneo-id) instead.

Make sure you have installed the package and have a token. See [SDK installation](/dev-guides/core-setup/sdk) and [API tokens](/dev-guides/core-setup/api-tokens).

## Initialisation

```typescript theme={null}
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](/dev-guides/core-setup/api-tokens).                   |
| `baseURL` | No       | Override the default base URL, for example to point at a sandbox proxy.                          |

<Warning>
  The `token` carries broad admin scopes. Keep it on a server. Do not expose it to a browser.
</Warning>

## 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](https://github.com/omneo/omneo-sdk/tree/develop/src/omneo/resources).

## Global and profile-scoped calls

The SDK mirrors the [global vs profile-scoped route pattern](/dev-guides/core-setup/global-vs-profile-routes). 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:

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

Fetch a single transaction by ID:

```typescript theme={null}
const transaction = await omneo.transactions.get(transactionId)
```

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

```typescript theme={null}
const profile = await omneo.profiles.findByIdentity('1004993MH', 'shopify_id')
```

Subscribe a profile to email comms:

```typescript theme={null}
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.

```typescript theme={null}
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:

```typescript theme={null}
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()`.

## Related

* [SDK installation](/dev-guides/core-setup/sdk)
* [Using Omneo ID](/dev-guides/frontend/omneo-id)
* [Omneo SDK concept](/concepts/platform-surfaces/omneo-sdk)
* [API tokens](/dev-guides/core-setup/api-tokens)
* [Global vs profile-scoped routes](/dev-guides/core-setup/global-vs-profile-routes)