Getting Started

The Riverr API is a single GraphQL endpoint. Every query and mutation — shops, orders, products, shipments, blanks — is sent as an HTTP POST to the same URL. (Despite the project name, there are no per-resource REST paths to call; you send GraphQL documents to one endpoint.)

Endpoint

POST https://api.riverr.app/graphql

Legacy hostname

https://dev.riverr.app/graphql remains available for existing integrations. New integrations should use https://api.riverr.app/graphql.

Authenticate

Every request must include your API key in the x-uid header. Your API key is your Riverr User ID — see Authentication for where to find it.

You must also send Content-Type: application/json. JSON is required both by the GraphQL transport and by the endpoint's CSRF protection, so do not use text/plain or form encodings.

{
  "x-uid": "YOUR_API_KEY",
  "Content-Type": "application/json"
}

There is no separate "log in" step and no token exchange — the x-uid header is sent on every call.

Your first request

This curl call fetches the five most recent orders for one shop. The GraphQL document goes in the query field of the JSON body; variables go in variables.

curl https://api.riverr.app/graphql \
  -X POST \
  -H "Content-Type: application/json" \
  -H "x-uid: YOUR_API_KEY" \
  -d '{
    "query": "query GetOrders($shopId: ID, $limit: Int) { getOrders(shopId: $shopId, limit: $limit) { id orderNumber status shipped grandTotal shippingAddress { name city country } } }",
    "variables": { "shopId": "shop_123", "limit": 5 }
  }'

Successful response

GraphQL responses are always wrapped in a top-level data object, keyed by the operation name you requested:

{
  "data": {
    "getOrders": [
      {
        "id": "8Wq2bL5x9Kd0",
        "orderNumber": "ORD-2001",
        "status": "production",
        "shipped": false,
        "grandTotal": 59.98,
        "shippingAddress": { "name": "Jane Smith", "city": "Los Angeles", "country": "US" }
      }
    ]
  }
}

Error response

When something goes wrong the response contains an errors array (and data is usually null). The HTTP status is typically 200 even for failed operations — branch on errors[].extensions.code, not the status code:

{
  "errors": [
    {
      "message": "Failed to retrieve order",
      "path": ["getOrder"],
      "extensions": { "code": "INTERNAL_SERVER_ERROR" }
    }
  ],
  "data": null
}

See Errors, Rate Limits & Pagination for the full list of codes and what they mean.

Explore the schema interactively

The endpoint has introspection enabled and serves an embedded Apollo Sandbox. Open https://api.riverr.app/graphql in a browser to browse the live schema, autocomplete fields, and run queries (set the x-uid header in the Sandbox "Headers" panel).

Where to go next

Guide	What it covers
Authentication	Finding and sending your API key
Finding GTINs	Looking up blank-product GTINs to order
Orders	Creating and reading orders
Placements	Valid print-location IDs for artwork
Artwork & Print Files	Image format, DPI, and hosting requirements
Tracking & Fulfillment	Reading shipment tracking
Errors, Rate Limits & Pagination	Error codes and list behavior