> For the complete documentation index, see [llms.txt](https://docs.violet.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.violet.io/api-reference/relay/relay.md).

# Overview

Relay reads data from a merchant's ecom platform at the moment you ask for it. Nothing comes from Violet's catalog or order tables, so every response is the platform's current state, and it takes as long as the platform's own API does.

New to Relay? Start with [What is Relay?](https://docs.violet.io/relay/relay) in the guides.

## Endpoints

| Group                                                              | What it reads                                               |
| ------------------------------------------------------------------ | ----------------------------------------------------------- |
| [Offers](https://docs.violet.io/api-reference/relay/offers.md)     | Products as Violet offers: list, get by platform ID, search |
| [Orders](https://docs.violet.io/api-reference/relay/orders.md)     | One order in Violet's order model, by platform ID           |
| [Store](https://docs.violet.io/api-reference/relay/store.md)       | The merchant's store profile                                |
| [Shipping](https://docs.violet.io/api-reference/relay/shipping.md) | Shipping zones and their methods                            |

## Before you call

Send `X-Violet-Token`, `X-Violet-App-Secret` and `X-Violet-App-Id` on every request. The token must belong to the developer that owns the app, and the app must be connected to the merchant. Every endpoint except Get Shipping Zones also needs the app on the Relay plan. To get an app Relay-enabled, contact <support@violet.io>.

## Platform support

Each endpoint page lists the platforms it supports. What happens on any other platform depends on the endpoint, and the page says which.

## Pagination

List endpoints paginate by cursor or by page number, depending on the platform.

* **Cursor platforms** (Shopify, for example) return `next_page_cursor`. Send it back as the `next_page_cursor` query parameter to get the next page, and stop when `last` is `true`. The cursor carries the filters of your first request, so filters sent along with it are ignored.
* **Page-number platforms** (WooCommerce and BigCommerce, for example) use `page` and `size`, and you send the filters again on every request. Keep requesting pages until one comes back empty. Don't rely on `last` or the totals here. `last` is not set reliably, and some platforms report totals for the current page only.

## Filters

A filter applies only on the platforms named in its description. Other platforms ignore it without returning an error, so results can come back unfiltered.

## Errors

Errors use Violet's standard body with `error`, `code` and `message`. When a merchant's platform rejects the connection Violet has stored, some platforms and endpoints answer 400 `invalid_merchant_credentials`, and the rest return a 500. Handle both.

## Guides

* [What is Relay?](https://docs.violet.io/relay/relay)
* [Relay Offers](https://docs.violet.io/relay/get-offers)
* [Relay Orders](https://docs.violet.io/relay/get-orders)
* [Relay Collections](https://docs.violet.io/relay/get-collections)
* [Relay Shipping Zones](https://docs.violet.io/relay/get-shipping-zones)
* [Webhooks](https://docs.violet.io/relay/webhooks)
* [Current Platforms](https://docs.violet.io/relay/current-platforms)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.violet.io/api-reference/relay/relay.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
