Deliver world-class omnichannel customer experiences through our API-driven retail infrastructure and world's largest retail graph.

Today’s brands face enormous challenges to differentiate and meet the ever-changing behaviors of their customers. Customers are more empowered than ever before; they are social, connected, well-informed, and they expect experiences that are no less than stellar. XY Retail helps to integrate all digital and physical customer touchpoints onto a single and robust platform including online, mobile, point-of-sale, call center, and social media. It empowers brands to deliver exceptional, seamless omnichannel customer experiences.

The XY platform was created to address the challenge of what it means to be truly omnichannel. The platform exists to answer questions such as:

How does a brand move from being store centric to omnichannel centric?
How does a brand manage a complete asymmetric customer experience, where today's systems are inherently built for single store experiences?
How does a brand manage sales attribution when a customer orders from one store and performs a return an exchange at another?
How does a brand extend it's retail to support new marketplaces and business models like subscriptions and rentals with minimal effort?
How does a brand extend into other geographies and countries and support cross border shipments and returns with third party integrations?

A 360-degree view and analysis of the customer at every touchpoint is a bare minimum requirement to provide a relevant and personalized omnichannel experience.

But wait, there is more! For the platform to be truly omni we had to make the following key decisions and distinctions:

A sales order line is the only construct that can support and pass the true omni smell test -where a customer can buy 5 items at Store A, carry out 3 items, ship the other 2 to two separate addresses. Then at a later date, return an item at Store B, and exchange an item at Store C - all in one order.
An order or a sales order line cannot be restricted to a particular channel as a foundational capability.
Every location is a Point Of Sale, whether it is a store POS, ecommerce website, warehouse, showroom, dropship location..
It was imperative to make a distinction between a 'Point Of Sale' and a 'Channel', where sales attribution is tracked and accounted for, and return or exchange flows could be processed beyond just the sale.
Given that integrating disparate systems would not provide a real-time 360-degree customer view and get us to omnichannel nirvana, we had to put our heads down and build a first of it's kind, vertically integrated, cloud-native platform for omnichannel retail from the very ground-up
API Reference
XY’s cloud-native omnichannel platform is bringing a connections-first approach to applications and analytics across the enterprise.

The graph helps you build, query, and manage a retail data: a unified data layer that enables applications to interact with data from any combination of connected data stores and external APIs.

An XY query retrieves data from the cloud, similar to a GET request for a REST API. However, unlike REST, all XY queries are sent to a single endpoint and use the POST http method.

An XY data graph uses XY Query Language 'XYQL' to define and enforce the structure of this data flow.

XY Graph
XY Graph
XY Graph is the gateway to data and intelligence in the XY Omnichannel Platform. It provides a unified programmability model that you can use to access the tremendous amount of data from internal and external apps. It's an HTTP-based API that apps can use to programmatically query data. Use the wealth of data in XY Graph to build apps for organizations and consumers that interact with millions of users.
XY Query: A query language for XY API Graph
  • 1. /xy/query/{node uri of query}

    This endpoint supports a wide range of queries, such as aggregates and a few more enhancements such as joins and variables are coming soon.
  • 2. /xy/collection/{node uri of collection}

    This endpoint supports the base level and filtered collections.
  • 3. /xy/path/{expression}

    This will allow you to express any path in the graph and it will return results. Coming Soon
  • 4. /xy/search/(node uri of query)

    This endpoint for now is practically the same as 1, except with controls to define search behaviour through configuration.
  • 5. /xy/functions/{node uri of function}

    This endpoint allows developers to either use GET for read only functions or POST for write functions (mutations).
XY Content: A lightweight but flexible CMS
  • 1. /xy/query/{node uri of query}

    This endpoint supports all forms of content.

A new basic CMS but with the idea that developers should be able to use any framework of their choice. The focus of the CMS is to:

  • Dynamic Content

    Merge HTML Templates with XY Graph.
  • Cloud Hosting

    Provide a wide range of configurations and controls to optimize content hosting and distribution, which is available out of the box.

    Provide an out of the box digital space for brands. A default web root will be provided to all brands and they can customize it by paying a fee.
  •{private links}

    Bring an out of the box digital space for brands to interact with their customers.

XY Connect: An Integration Framework
  • 1. /xy/api/{node uri of api}

    The holy grail of endpoints. This endpoint allows developers to connect to any API. Coming Soon
XY Bot: An Automation Framework
  • 1. xy/bot/{node uri of bot}

    A new endpoint that will allow developers to invoke and create workflows developed within XY using functions and conditions. Coming Soon
What is XYQL?

XYQL is a native query language and a runtime system similar to GraphQL. Clients form requests by using the XY query language, and the XYQL executes the request and returns the data in a response. Unlike REST APIs, which exposes a different endpoint for each resource object, an XYQL API makes all data available at a single endpoint. A client specifies exactly the data that it wants, and the cloud responds with only that data. Data can be segmented using filters and access control can be done at a level as granular as an attribute level.

An XY query retrieves data from the cloud, similar to a GET request for a REST API. However, unlike REST, all XY queries are sent to a single endpoint and use the POST http method.

An XYQL API models data as nodes connected by edges. A node is an object that has a global ID, such as an Order object or Product object. You can fetch data about an individual node, or you can follow the edges to fetch data about a collection of related nodes. At each node, you specify the fields that you want to retrieve.

XYQL looks similar to JSON. The following example shows a simple XYQL query and the JSON response:

POST /admin/api/2021-01/xyql.json

Base URL
Authentication is determining whether a user is logged in or not, and subsequently figuring out which user someone is. Authorization is then deciding what the user has permission to do or see.

Access to XY Query is based on OAuth token that is issued by the owner of the data. User can assign permission for specific endpoint to each token.

Authenticated Request

Authorization: Bearer


A sample test API key is included in all the examples here, so you can test any example right away.

To test requests using your account, replace the sample API key with your actual API key or sign in.

Attribute Types

XY currently supports 16 attribute types.

The primitive types are the most basic data types available within the Java language. Similar to JAVA, these types serve as the building blocks of data manipulation in XY platform. Such types serve only one purpose — containing pure, simple values of a kind.

The nested type is a specialised version of the object datatype that allows arrays of objects to be indexed in a way that they can be queried independently of each other.

  • String

    Any text value.

  • Integer

    Any whole number from -2147483648 to 2147483647.

  • Long

    Any whole number from -9223372036854775808 to 9223372036854775807.

  • Double

    Number with decimal points.

  • Currency

    Number representing currency value. Currency is a long with no decimal. For example, 1050 = 10.50.

  • Date

    Date value. There are 3 parts to any date value ($year, $month, $day). $month value is in base 0.

  • Date/Time

    Long value representing date and time in UTC timezone.

  • Password

    One-way has value representing password value.

  • Boolean

    A binary variable, having two possible values called "true" and "false".

  • Location

    Geolocation value represented by $longitude and $longitude.

  • JSON

    Any JSON object

  • Node

    An object of any entity type. For example, charges object that is nested within a sales order object.

  • Any

    Any attribute can be of any values with exception of attribute of type Lookup and XY Query

Connect to data sources

Fetch data from multiple locations using the following three methods.

A data source is any database, service, or API that holds the data you use to populate your schema's fields. Your XYQL API can interact with any combination of data sources.

XY provides a DataSource class that we can extend to handle interaction logic for a particular type of data source. In this section, we'll extend DataSource to connect both a REST API and a SQL database to XY Cloud. Don't worry, you don't need to be familiar with either of these technologies to follow along with the examples.

  • Link

    Represent a connection to another addressable object in the system.

  • Lookup

    Data from another source based on specified join condition.

  • XY Query

    Customizable data source including aggregates.

    "string": "Lorem ipsum dolor sit amet, consectetur",
    "int": 20,
    "long": 12,
    "double": 1.30,
    "currency": 130000,
        "$year": 2021,
        "$day": 20,
        "$month": 1
    "datetime": 1614220379000,
    "password": "YX72s98sn=2nj",
    "boolean": true,
        "$latitude": 40.7468831,
        "$longitude": -73.9964039
        "a": "Sed ut perspiciatis unde omnis iste natus",
        "b": 777
        "$type": "node",
        "$nodeType": "commerce.charges",
        "currency": {
            "$type": "string",
            "$value": "USD"
        "$type": "link",
        "$value": "7leaf.7leaf/spaces/type/sample"
Node URI

Every object in XY is addressable with a node URI.

Node URI consists of 4 different parts:

  • Space - Indicate which space the data belongs to
  • App - Application domain such as commerce
  • Type - Object type
  • Id - Unique id

Example: spaces-identity.xyretail/commerce/salesorder/373938922

Entity Types
The most basic components of an XYQL schema are entity types, which just represent a kind of entity you can fetch from your service, and what fields it has. In the XYQL schema language, we might represent it like what you see on the right here.
{ "data": { "hero": { "name": "R2-D2", "appearsIn": [ "NEWHOPE", "EMPIRE", "JEDI" ] } } }

XY uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.). Codes in the 5xx range indicate an error with the XY Cloud (these are rare).

Some 4xx errors that could be handled programmatically (e.g., a card is declined) include an error code that briefly explains the error reported.

HTTP Status Code Summary
200 - OK Everything worked as expected.
400 - Bad Request The request was unacceptable, often due to missing a required parameter.
401 - Unauthorized No valid API key provided.
402 - Request Failed The parameters were valid but the request failed.
403 - Forbidden The API key doesn't have permissions to perform the request.
404 - Not Found The requested resource doesn't exist.
409 - Conflict The request conflicts with another request (perhaps due to using the same idempotent key).
429 - Too Many Requests Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500, 502, 503, 504 - Server Errors Something went wrong on XY's end. (These are rare.)

XY Query utilizes cursor-based pagination via the from and parameters. The parameters take an existing position value and return objects in order specified by the sorter.

  • from optional, default is 0

    A cursor for use in pagination.

  • size optional, default is 20

    The number of objects to be returned.

Response Format
  • hits array

    An array containing the actual response elements, paginated by any request parameters..

  • total int

    Total number of records matching specified query.

  • count int

    Number of records in the current results set.

  • size int

    Requested number of records per page.

  • from int

    Requested cursor position.

    "hits": [{...}],
    "total": 12,
    "size": 20,
    "count": 12,
    "from": 0

XY Query is filtered based on a pre-configured conditions by default. However, additional filters can be supplied using additional parameters.

String, Link
  • Equals (=)

    An equals filter can be used to filter down the results by specifying one or more matching values

  • start

    start is used to specified the start of the range. The range is inclusive and include results with matching values.

  • end

    end is used to specified the end of the range. The range is inclusive and include results with matching values.

Equals Filter
Range Filter

XY Query is sorted based on a pre-configured sorter by default. However, this can be overriden by supplying an additional parameter.

  • desc optional

    Sort direction with 2 possible values. true to sort descending and false to sort ascending.