OMS REST API

The API provides three means of authentication:

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:

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:

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:

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

You may use their opaque tokens like so:

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.

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:

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

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.

OMS implements 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.

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.

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

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

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.

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):