---
title: OMS REST API
slug: oms/oms-rest-api
docTags: 
createdAt: 2026-08-11T17:27:38.941Z
---

## Authentication

The API provides three means of authentication:

1. An admin level API key
2. A storefront's authentication provider
3. An order's guest token

### API key

You can use your API key to access all resources in the API. The API key must be passed in the `Authorization` header in
the following form:

```javascript
Authorization: Bearer API_KEY
```

As an admin, you can find your API token in the admin section under Users > Your email > API Access (at `admin/users/<user_id>/edit`)

Example:

```javascript
curl --header "Authorization: Bearer 1a6a9936ad150a2ee345c65331da7a3ccc2de" https://plant-staging.assembly-api.com/api/stores
```

**This authentication method is extremely sensitive should never be used in public contexts.** Instances where it would be
appropriate to use this authentication method include:

- Segment functions
- Custom storefront functionality that requires admin level roles that is called server side
- Scripts that import or modify data

### Storefront Authentication

Your storefront can be configured to use a 3rd party authentication provider for your customers to login with.
Services that Chord currently supports includes:

- [Stytch](https://stytch.com/)
- [Magic](https://magic.link/)

You may use their opaque tokens like so:

```javascript
curl --header "Authorization: yQscCbXp5EdisdenCal1ovxutnuyhHAlw6ucLfbUWLGn" https://plant-staging.assembly-api.com/api/users/me
```

If the user has no roles (which would make them a customer), this token allows for a subset of operations upon records
owned by the user. If the email address matches that of an admin, this token can be used for admin level operations.

If you want to allow your users to perform operations against the API in the browser, this is an advisable method to do
so.

### Order token

For allowing guests to manage their cart and place their order, you can use the order's guest token. This token is
contained in the `token` property of the order, and it allows you to perform certain checkout-related operations on the
order such as managing line items, completing the checkout flow etc.

The order token must be passed in the `X-Spree-Order-Token` header in the following form:

```javascript
X-Spree-Order-Token: ORDER_TOKEN
```

If you are already providing an API key, you don't need to also provide the order token (although you may do so).

## Pagination

Most endpoints that return a collection are paginated. A paginated response contains metadata about the current page at the root level and the resources in the current page in a child key named after the resource (e.g. `orders`).

You can pass the `page` and `per_page` parameters to set the current page and the desired number of items per page. Note that the default and the maximum number of items per page is decided at the application level.

All pagination metadata is documented in the individual API endpoints, so take a look there if you're unsure what data you can expect.

## Searching with Ransack

OMS implements [Ransack](https://activerecord-hackery.github.io/ransack/) to allow searches on any GET index API endpoint without having to create additional endpoints specific for searching. Searches with Ransack are performed by including specific query parameters in the request. Multiple criteria can be passed as query parameters for more specific searches.

The full list of search matchers can be found on the [Ransack Search Matchers page](https://activerecord-hackery.github.io/ransack/getting-started/search-matches/).

Note that documentation for some endpoints includes Ransack details. However, Ransack is enabled for *many (but not all)* entities in ChordOMS, so these entities are searchable even if the documents for the corresponding endpoint do not specifically include Ransack details. If an entity is not searchable, please contact Chord to discuss enabling search.

### Example

To return all the products that have a variant SKU of **product-1-large-red** use the `q[sku_matches]=` parameter:

```javascript
/api/variants?q[sku_matches]=product-1-large-red
```

To return all orders completed between August 2 and 4, 2024:

```javascript
/api/orders?q[completed_at_gteq]=2024-08-02&q[completed_at_lteq]=2024-08-04
```

## Store Selection

Tenants in OMS are able to operate multiple 'stores'. A store represents a digital storefront with distinct configuration options, such as store variables, shipping methods, products, orders, etc... The most common use case is merchants that wish to operate different stores in different regions (e.g. one store for US customers and another for Canadian customers). Most tenants, however, operate a single store.

### Specifying the store

When interacting with the Chord OMS API, set the `ACS-Store` header to the code (slug) for the specified store. The code (slug) value is specified in the **Store** settings in Chord OMS administration page.

For example, to specify a request to the **Plant Canada** store which has the store code `plant_canada`, include the following header in the request(s):

```javascript
ACS-Store=plant_canada
```