Developers

Store Data API

Read-only access to your store's orders, customers, products, and categories. Sync your data with spreadsheets, dashboards, ERPs, and automation tools through a stable, versioned REST API.

Create an API key OpenAPI 3.1 spec Markdown for AI assistants

Introduction

The Store Data API gives you programmatic, read-only access to your store's data: orders, customers, products, and categories. Use it to sync your store with spreadsheets, BI dashboards, ERPs, accounting tools, or automation platforms like Zapier and Make.

All endpoints are GET, return JSON, and live under a stable versioned prefix:

Building with an AI assistant? The whole reference is available as plain markdown at rovela.ai/developers.md and as an OpenAPI 3.1 spec at rovela.ai/api/v1/openapi.json. Paste either into your assistant and ask it to write your integration.

Quickstart

From zero to your first JSON response in about two minutes.

1. Create an API key

Open your dashboard, pick a store, and go to Settings → API → Create key. The full key (it starts with rvk_) is shown exactly once, so copy it somewhere safe. Each key belongs to one store.

2. Check the connection

3. Pull your orders

When meta.has_more is true, pass meta.next_cursor back to get the next page. See Pagination for the full walk.

Authentication

Every request needs your API key in the x-api-key header. Keys are scoped to exactly one store, which is why no store identifier appears in any URL.

A store can have up to 5 active keys, managed in Settings → API. Only a hash of each key is stored, so a lost key cannot be recovered, only replaced. Revoking a key takes effect on the very next request.

Keep keys on your server. The API deliberately sends no CORS headers, so browser calls fail by design. A key embedded in a website or mobile app would be readable by anyone, and it grants access to your customer data.

Response format

Every endpoint uses the same envelope. List endpoints return an array plus pagination metadata; detail endpoints return a single object; errors return a code and a human-readable message.

Convention	Detail
Field names	snake_case, matching the store database.
Money	Strings with 2 decimals, for example "49.90", never floats. The store currency is on /api/v1/store.
Timestamps	ISO 8601 in UTC, for example "2026-06-14T09:21:33.000Z".
Ids	UUIDs, unique within a store.
Guest checkout	orders.customer_id is null for guest orders; orders.email is always present.
Forward compatibility	New fields may appear at any time. Write clients that ignore fields they do not recognize.

Pagination

List endpoints are cursor-paginated, which stays correct even while orders are being written mid-export (offset pagination would skip or repeat rows). Rows come back oldest first by creation time. Cursors are opaque: pass them back exactly as received and never parse them.

Parameter	Description
limit	Page size, 1 to 250. Defaults to 50. Use 250 for bulk exports.
cursor	The meta.next_cursor value from the previous page.

Incremental sync

For a recurring sync (hourly, nightly) you do not need full exports. Orders and products support updated_since; customers support created_since (customer records carry no updated timestamp).

On the first run, record your own last_synced_at timestamp taken before the run starts, then walk every page.
On every following run, request only what changed and upsert by id.
On success, advance last_synced_at to the new run's start time.

Taking the timestamp before the run (not after) means an order updated while the run was in flight is picked up again next time. Duplicate upserts by id are harmless; missed rows are not.

Rate limits

Each key allows 120 requests per minute. Above that the API returns 429 RATE_LIMITED with a Retry-After header (seconds). Treat the limit as a target rather than a contract: it can be slightly more generous under horizontal scaling.

A full export of a large store fits comfortably inside the limit: 120 pages of 250 rows moves 30,000 rows per minute. If you hit 429s, request bigger pages instead of retrying faster.

Errors

Every error is JSON with a stable machine code and a human message. The codes below are the complete catalog, with what each one means and whether a retry can succeed.

Status	Code	When it happens	What to do	Retry?
401	INVALID_API_KEY	The x-api-key header is missing, malformed, or the key was revoked. Revocation takes effect on the very next request.	Check that the header name is exactly x-api-key and the value starts with rvk_. If the key was revoked, create a new one in your store dashboard under Settings then API.	No
403	STORE_NOT_SUPPORTED	The key belongs to an imported store. Imported stores run on their own infrastructure, so their data does not live on Rovela.	Query the store on its own hosting instead. The Store Data API only serves stores generated on Rovela.	No
409	STORE_NOT_READY	The store exists but its database has not been provisioned yet, which only happens while the initial generation is still running.	Wait for the store to finish generating, then retry.	Yes
400	INVALID_PARAM	A query parameter failed validation: a limit outside 1 to 250, an unknown status value, a malformed datetime, or a non-UUID resource id.	The error message names the offending parameter and the accepted values. Correct the request.	No
400	INVALID_CURSOR	The cursor value could not be decoded. Cursors are opaque and only valid when passed back exactly as received.	Pass meta.next_cursor back verbatim. Never parse, edit, or store cursors long term; restart the walk from the first page if one goes stale.	No
404	NOT_FOUND	The resource id is a valid UUID but no matching row exists in this store.	Confirm the id belongs to this store. Ids are never shared across stores.	No
429	RATE_LIMITED	The key exceeded 120 requests in the current minute.	Honor the Retry-After header (seconds) before retrying. For bulk exports, request limit=250 pages instead of many small pages.	With backoff
502	STORE_DB_ERROR	A transient failure while reading the store database.	Retry with exponential backoff. If it persists for more than a few minutes, contact support.	With backoff

Versioning

The /api/v1 prefix is stable. Additive changes (new fields, endpoints, or filters) land in v1 without notice, which is why clients should ignore unknown fields. A breaking change would ship as /api/v2 with a migration window, never as an in-place change to v1.

Store

A snapshot of the store the key belongs to: identity, currency, configuration flags, and row counts per resource. Use it as a connection sanity check and to learn the currency your money fields are denominated in.

The store object11 fields

Field	Type	Description
id	uuid	The store id on Rovela.
name	string	The store name on the Rovela dashboard.
store_name	string or null	The customer-facing store name.
store_email	string or null	The store contact email.
store_currency	string or null	ISO 4217 currency code all money fields use, for example "USD".
store_timezone	string or null	IANA timezone, for example "America/New_York".
tax_included_in_prices	boolean or null	Whether displayed prices already include tax.
shipping_enabled	boolean or null	Whether the store ships physical goods.
guest_checkout	boolean or null	Whether customers can buy without an account.
customer_accounts	boolean or null	Whether customer accounts are enabled.
counts	object	Row counts: products, categories, customers, orders.

Retrieve the store

GET/api/v1/store

Returns the store snapshot for the key you authenticate with. If this call works, every other endpoint will too.

Endpoint errors: STORE_NOT_SUPPORTED · STORE_NOT_READY

Orders

Orders placed on the storefront, with their line items embedded. Money fields are strings in the store currency. Guest orders have a null customer_id but always carry the buyer's email.

The orders object24 fields

Field	Type	Description
id	uuid	Order id.
customer_id	uuid or null	The buyer's customer id, or null for guest checkout.
email	string	The buyer's email. Always present.
status	string	One of pending, paid, shipped, delivered, cancelled, refunded, return_requested.
subtotal	decimal string	Item total before tax, shipping, and discounts.
tax	decimal string	Tax charged.
shipping	decimal string	Shipping charged.
total	decimal string	Amount the customer paid.
refund_amount	decimal string or null	Total refunded so far.
return_reason	string or null	The customer's reason when a return was requested.
discount_code	string or null	The promotion code the customer redeemed, if any.
discount_amount	decimal string or null	Amount the discount removed.
shipping_address	object or null	firstName, lastName, line1, line2, city, state, postalCode, country, phone.
billing_address	object or null	Same shape as shipping_address.
stripe_payment_intent_id	string or null	Stripe PaymentIntent id, for reconciliation.
stripe_charge_id	string or null	Stripe Charge id.
receipt_url	string or null	Stripe-hosted receipt for the customer.
tracking_number	string or null	Shipment tracking number once fulfilled.
tracking_url	string or null	Carrier tracking link.
carrier	string or null	Carrier code, for example "ups".
shipping_method	string or null	The shipping option the customer chose.
created_at	timestamp	When the order was placed.
updated_at	timestamp	Last change to the order. Drives updated_since.
items	array	The order's line items, embedded. See Order item below.

Order item

One line of an order. Name and price are snapshots taken at purchase time, so they stay correct even after the product changes.

Field	Type	Description
id	uuid	Line item id.
order_id	uuid	The parent order.
product_id	uuid	The product purchased.
variant_id	uuid or null	The variant purchased, if the product has variants.
name	string	Product name at purchase time.
price	decimal string	Unit price at purchase time.
quantity	integer	Units purchased.
attributes	object or null	Variant attributes at purchase time, for example {"color": "Sand"}.
created_at	timestamp	When the line was written.

List orders

GET/api/v1/orders

Returns orders oldest first, line items embedded. Filter by status or by updated_since for incremental syncs.

Query parameters

Parameter	Type	Description
limit	integer	Page size, 1 to 250. Defaults to 50.
cursor	string	Opaque cursor from the previous page's meta.next_cursor.
updated_since	ISO 8601 datetime	Only orders updated at or after this instant.
status	string	One of pending, paid, shipped, delivered, cancelled, refunded, return_requested.

Endpoint errors: INVALID_PARAM · INVALID_CURSOR

Retrieve an order

GET/api/v1/orders/{id}

Returns a single order with its line items.

Path parameters

Parameter	Type	Description
id *	uuid	The order id.

Endpoint errors: INVALID_PARAM · NOT_FOUND

Customers

Customers who created an account or checked out on the storefront. Passwords are never exposed through the API, on any endpoint.

The customers object6 fields

Field	Type	Description
id	uuid	Customer id.
email	string	The customer's email. Unique within the store.
name	string or null	The customer's name, when provided.
stripe_customer_id	string or null	Stripe Customer id, for reconciliation.
email_verified	timestamp or null	When the email was verified, or null if it never was.
created_at	timestamp	When the customer record was created. Drives created_since.

List customers

GET/api/v1/customers

Returns customers oldest first. Customer records are effectively append-only, so created_since gives you a clean incremental sync.

Query parameters

Parameter	Type	Description
limit	integer	Page size, 1 to 250. Defaults to 50.
cursor	string	Opaque cursor from the previous page's meta.next_cursor.
created_since	ISO 8601 datetime	Only customers created at or after this instant.

Endpoint errors: INVALID_PARAM · INVALID_CURSOR

Retrieve a customer

GET/api/v1/customers/{id}

Returns a single customer.

Path parameters

Parameter	Type	Description
id *	uuid	The customer id.

Endpoint errors: INVALID_PARAM · NOT_FOUND

Products

The store catalog, with variants embedded on every product. Products without variants return an empty variants array; their price and inventory live on the product itself.

The products object25 fields

Field	Type	Description
id	uuid	Product id.
name	string	Product name.
slug	string	URL slug, unique within the store.
description	string	Product description.
price	decimal string	Base price. Variants can override it.
compare_price	decimal string or null	The crossed-out "was" price, when on sale.
images	string[]	Image URLs, in display order.
videos	string[]	Video URLs.
status	string	One of draft, active, archived.
category_id	uuid or null	The category the product belongs to.
has_variants	boolean	Whether the product sells in variants.
sku	string or null	Stock keeping unit, when set.
inventory	integer or null	Units in stock (for products without variants).
track_inventory	boolean or null	Whether stock is tracked.
continue_selling_when_out_of_stock	boolean or null	Whether checkout stays open at zero stock.
product_type	string or null	Free-form type label.
vendor	string or null	Brand or supplier name.
tags	string[] or null	Free-form tags.
meta_title	string or null	SEO title override.
meta_description	string or null	SEO description override.
meta_keywords	string[] or null	SEO keywords.
metafields	array	Custom fields as {key, label, value} objects.
created_at	timestamp	When the product was created.
updated_at	timestamp	Last change. Drives updated_since.
variants	array	The product's variants, embedded. See Variant below.

Variant

One sellable variation of a product, for example a size and color combination. A null price means the variant sells at the product's base price.

Field	Type	Description
id	uuid	Variant id.
product_id	uuid	The parent product.
sku	string	Stock keeping unit, unique within the store.
name	string	Variant display name, for example "Sand / Large".
price	decimal string or null	Price override, or null to use the product price.
inventory	integer	Units in stock for this variant.
image	string or null	Variant-specific image URL.
video	string or null	Variant-specific video URL.
attributes	object	The option values, for example {"color": "Sand", "size": "Large"}.
created_at	timestamp	When the variant was created.

List products

GET/api/v1/products

Returns products oldest first, variants embedded. Filter by status to export only the live catalog, or by updated_since for incremental syncs.

Query parameters

Parameter	Type	Description
limit	integer	Page size, 1 to 250. Defaults to 50.
cursor	string	Opaque cursor from the previous page's meta.next_cursor.
updated_since	ISO 8601 datetime	Only products updated at or after this instant.
status	string	One of draft, active, archived.

Endpoint errors: INVALID_PARAM · INVALID_CURSOR

Retrieve a product

GET/api/v1/products/{id}

Returns a single product with its variants.

Path parameters

Parameter	Type	Description
id *	uuid	The product id.

Endpoint errors: INVALID_PARAM · NOT_FOUND

Field	Type	Description
id	uuid	Category id.
name	string	Category name.
slug	string	URL slug, unique within the store.
description	string or null	Category description.
image	string or null	Cover image URL.
parent_id	uuid or null	The parent category, or null for top level.
order	integer	Display position among siblings.
created_at	timestamp	When the category was created.

Changelog

2026-07-08
Store Data API v1 launch
First public release: read-only access to the store snapshot, orders (with line items), customers, products (with variants), and categories. Cursor pagination, incremental sync filters, per-store API keys with instant revocation, and a 120 requests per minute rate limit.

Introduction

Quickstart

1. Create an API key

2. Check the connection

3. Pull your orders

Authentication

Response format

Pagination

Incremental sync

Rate limits

Errors

Versioning

Store

Retrieve the store

Orders

List orders

Retrieve an order

Customers

List customers

Retrieve a customer

Products

List products

Retrieve a product

Categories

List categories

Changelog

Store Data API

Your dream store is one sentence away.

Introduction

Quickstart

1. Create an API key

2. Check the connection

3. Pull your orders

Authentication

Response format

Pagination

Incremental sync

Rate limits

Errors

Versioning

Store

Retrieve the store

Orders

List orders

Retrieve an order

Customers

List customers

Retrieve a customer

Products

List products

Retrieve a product

Categories

List categories

Changelog