OMS REST API

authentication the api provides three means of authentication an admin level api key a storefront's authentication provider 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 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 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 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 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 /api/variants?q\[sku matches]=product 1 large red to return all orders completed between august 2 and 4, 2024 /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) acs store=plant canada