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. Library file upload is the exception: see Library uploads. Everything else is a GraphQL document sent 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. Find it in Settings → Developer → API credentials — see Authentication. New keys are a dedicated rv_live_… value. Existing integrations that still send your Riverr User ID continue to work.

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
Webhooks	Receiving signed events at your URL
Finding GTINs	Looking up blank-product GTINs to order
Orders	Creating orders, quoting print prices, and prepaid labels
Quote requests	Submit a quote from your own website so you can price ink and send it back
Placements	Valid print-location IDs for artwork
Library uploads	Push a PNG or DST into a seller's library
Artwork & Print Files	Image format, DPI, and hosting requirements
Tracking & Fulfillment	Reading shipment tracking
Errors, Rate Limits & Pagination	Error codes and list behavior