Rose API Reference
Read a Consignor Connect store’s items, sales, consignors / vendors and payouts as JSON — for the store’s website, reporting, spreadsheets or its own apps. Every key belongs to one store and is read-only: the API never changes store data.
Quickstart
- The store turns on Rose Enterprise and makes a key in Rose:
Administration › Settings › ROSE API › CREATE API KEY. The key (rose_…) is shown once. - Keep it on your server, e.g. in an environment variable
ROSE_API_KEY. Never in a web page, mobile app or public repository. - Make your first call:
curl -H "Authorization: Bearer $ROSE_API_KEY" https://app.shr-consignorconnect.com/rose/api/v1/store
Base URL: https://app.shr-consignorconnect.com/rose/api/v1
Authentication
Send the key in the Authorization header of every request, as a bearer token:
Authorization: Bearer rose_XXXXXXXXXXXX_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
- A key reads one store only — the store is decided by the key, there is no store parameter.
- Keys made without contact details never return consignors’ e-mail, phone or address.
- A revoked key, or a store whose Rose Enterprise ended, gets
401/403at once. - HTTPS only.
Pagination
List endpoints return a page:
{ "data": [ … ], "limit": 100, "offset": 0, "next_offset": 100 }
Ask for the next page with offset=next_offset until next_offset is null. limit is 1–500 (default 100); offset at most 200,000 — narrow the dates or filters for more. Lists are ordered (SKU, date sold, account number, payout date), so pages are stable while data isn’t changing.
let offset = 0, all = [];
while (offset !== null) {
const r = await fetch(`https://app.shr-consignorconnect.com/rose/api/v1/items?limit=500&offset=${offset}`, { headers: { Authorization: `Bearer ${key}` } });
const page = await r.json();
all.push(...page.data);
offset = page.next_offset;
}Errors
Errors use HTTP status codes and a JSON body:
{ "error": { "code": "bad_dates", "message": "from and to are required, as yyyy-MM-dd" } }
| Status | code | Meaning |
|---|---|---|
| 400 | bad_dates bad_limit bad_offset | A parameter is missing or out of range |
| 401 | unauthorized | No key, a wrong key, or a revoked key |
| 403 | no_enterprise store_closed | The store doesn’t have Rose Enterprise, or its account isn’t open |
| 404 | not_found | No such item or account |
| 429 | rate_limited | Too many requests — wait and retry |
| 500 | server_error | Try again; if it keeps happening, contact support |
Rate limits
120 requests per minute per key. Over that you get 429 until the next minute. Use limit=500 to fetch in fewer calls, and cache what you don’t need fresh to the second. Every request has a 20-second limit on the server.
Data notes
- Dates are
yyyy-MM-ddstrings, in the store’s time zone (/store). Date ranges include bothfromandto, at most 366 days per request. - Money is a number in the store’s currency, rounded to cents.
- Accounts are consignor or vendor account numbers (strings). The store’s house account has
store_account: true. - Sales are item lines: returns are negative quantities / amounts. Fees, charges, credits and payouts are not sales.
- Freshness: data is read live from the store. Square sales appear once Rose has posted them.
- New fields may be added to responses at any time — ignore fields you don’t know. Fields are never removed or renamed within v1.
Endpoints
/storeStoreGet the store
The store the key belongs to: name, currency, time zone and its locations. Location codes are the location filter of the other endpoints.
Parameters
No parameters.
Response fields (data)
| Field | Type | Description |
|---|---|---|
store | string | The store's account name in Consignor Connect. |
name | string | The store's full name. |
preview | boolean | true while the store is trying the new Rose (a copy of its data). |
currency_symbol | string | |
timezone | string | |
locations | array of Location |
curl -H "Authorization: Bearer $ROSE_API_KEY" \ "https://app.shr-consignorconnect.com/rose/api/v1/store"
const r = await fetch("https://app.shr-consignorconnect.com/rose/api/v1/store", {
headers: { Authorization: `Bearer ${process.env.ROSE_API_KEY}` }
});
const { data } = await r.json();import os, requests
r = requests.get("https://app.shr-consignorconnect.com/rose/api/v1/store",
headers={"Authorization": "Bearer " + os.environ["ROSE_API_KEY"]}, timeout=30)
r.raise_for_status()
data = r.json()["data"]
Example response
{
"data": {
"store": "MyStore",
"name": "My Store",
"preview": false,
"currency_symbol": "$",
"timezone": "America/New_York",
"locations": [
{
"code": "1",
"name": "Main Street"
}
]
}
}
Try it
/itemsItemsList items in stock
Items on the floor, in SKU order. Sold items are under /sales.
Parameters
| Parameter | In | Description |
|---|---|---|
account | query · string | Only this consignor / vendor account. |
location | query · string | Only this location code. |
category | query · string | Only this category name. |
limit | query · integer | Rows per page, 1-500. |
offset | query · integer | Rows to skip: use next_offset from the previous page. |
Response fields (each item of data)
| Field | Type | Description |
|---|---|---|
sku | string | |
account | string | The consignor / vendor account the item belongs to. |
description | string | |
brand | string | |
category | string | |
size | string | |
color | string | |
quantity | number | |
price | number | Selling price. |
cost | number | |
consignor_split_percent | number | The consignor's share of the sale, in %. |
shelf_date | string | null | yyyy-MM-dd |
expires | string | null | yyyy-MM-dd |
never_expires | boolean | |
no_discounts | boolean | true = the item is never discounted. |
location | Location | |
status | string |
curl -H "Authorization: Bearer $ROSE_API_KEY" \ "https://app.shr-consignorconnect.com/rose/api/v1/items?limit=50"
const r = await fetch("https://app.shr-consignorconnect.com/rose/api/v1/items?limit=50", {
headers: { Authorization: `Bearer ${process.env.ROSE_API_KEY}` }
});
const { data } = await r.json();import os, requests
r = requests.get("https://app.shr-consignorconnect.com/rose/api/v1/items?limit=50",
headers={"Authorization": "Bearer " + os.environ["ROSE_API_KEY"]}, timeout=30)
r.raise_for_status()
data = r.json()["data"]
Example response
{
"data": [
{
"sku": "100245",
"account": "1042",
"description": "Blue denim jacket",
"brand": "Levi's",
"category": "Outerwear",
"size": "M",
"color": "Blue",
"quantity": 1,
"price": 38.0,
"cost": 0,
"consignor_split_percent": 50,
"shelf_date": "2026-10-02",
"expires": "2026-12-31",
"never_expires": false,
"no_discounts": false,
"location": {
"code": "1",
"name": "Main Street"
},
"status": ""
}
],
"limit": 50,
"offset": 0,
"next_offset": null
}
Try it
/items/{sku}ItemsGet one item
One item in stock by SKU. 404 when it is not in stock (a sold item: /sales?sku=).
Parameters
| Parameter | In | Description |
|---|---|---|
sku required | path · string | The item's SKU. |
Response fields (data)
| Field | Type | Description |
|---|---|---|
sku | string | |
account | string | The consignor / vendor account the item belongs to. |
description | string | |
brand | string | |
category | string | |
size | string | |
color | string | |
quantity | number | |
price | number | Selling price. |
cost | number | |
consignor_split_percent | number | The consignor's share of the sale, in %. |
shelf_date | string | null | yyyy-MM-dd |
expires | string | null | yyyy-MM-dd |
never_expires | boolean | |
no_discounts | boolean | true = the item is never discounted. |
location | Location | |
status | string |
curl -H "Authorization: Bearer $ROSE_API_KEY" \ "https://app.shr-consignorconnect.com/rose/api/v1/items/100245"
const r = await fetch("https://app.shr-consignorconnect.com/rose/api/v1/items/100245", {
headers: { Authorization: `Bearer ${process.env.ROSE_API_KEY}` }
});
const { data } = await r.json();import os, requests
r = requests.get("https://app.shr-consignorconnect.com/rose/api/v1/items/100245",
headers={"Authorization": "Bearer " + os.environ["ROSE_API_KEY"]}, timeout=30)
r.raise_for_status()
data = r.json()["data"]
Example response
{
"data": {
"sku": "100245",
"account": "1042",
"description": "Blue denim jacket",
"brand": "Levi's",
"category": "Outerwear",
"size": "M",
"color": "Blue",
"quantity": 1,
"price": 38.0,
"cost": 0,
"consignor_split_percent": 50,
"shelf_date": "2026-10-02",
"expires": "2026-12-31",
"never_expires": false,
"no_discounts": false,
"location": {
"code": "1",
"name": "Main Street"
},
"status": ""
}
}
Try it
/salesSalesList sales
Sold item lines (sales and returns) by date sold. Fees, charges, credits and payouts are not sales and are left out.
Parameters
| Parameter | In | Description |
|---|---|---|
from required | query · string | First day, yyyy-MM-dd (included). |
to required | query · string | Last day, yyyy-MM-dd (included). At most 366 days after from. |
account | query · string | Only this account. |
location | query · string | Only this location code. |
sku | query · string | Only this SKU. |
limit | query · integer | Rows per page, 1-500. |
offset | query · integer | Rows to skip: use next_offset from the previous page. |
Response fields (each item of data)
| Field | Type | Description |
|---|---|---|
sku | string | |
account | string | |
description | string | |
brand | string | |
category | string | |
size | string | |
quantity | number | Negative for a return. |
sold_price | number | |
consignor_share | number | What the consignor / vendor gets for this line. |
fee | number | |
card_fee | number | |
discount | number | |
tax | number | |
date_sold | string | yyyy-MM-dd |
paid_to_consignor | boolean | Whether the consignor's share has been paid out yet. |
date_paid | string | null | yyyy-MM-dd |
location | Location |
curl -H "Authorization: Bearer $ROSE_API_KEY" \ "https://app.shr-consignorconnect.com/rose/api/v1/sales?from=2026-10-01&to=2026-10-31&limit=50"
const r = await fetch("https://app.shr-consignorconnect.com/rose/api/v1/sales?from=2026-10-01&to=2026-10-31&limit=50", {
headers: { Authorization: `Bearer ${process.env.ROSE_API_KEY}` }
});
const { data } = await r.json();import os, requests
r = requests.get("https://app.shr-consignorconnect.com/rose/api/v1/sales?from=2026-10-01&to=2026-10-31&limit=50",
headers={"Authorization": "Bearer " + os.environ["ROSE_API_KEY"]}, timeout=30)
r.raise_for_status()
data = r.json()["data"]
Example response
{
"data": [
{
"sku": "100245",
"account": "1042",
"description": "Blue denim jacket",
"brand": "Levi's",
"category": "Outerwear",
"size": "M",
"quantity": 1,
"sold_price": 38.0,
"consignor_share": 19.0,
"fee": 0,
"card_fee": 1.1,
"discount": 0,
"tax": 2.66,
"date_sold": "2026-11-03",
"paid_to_consignor": false,
"date_paid": null,
"location": {
"code": "1",
"name": "Main Street"
}
}
],
"limit": 50,
"offset": 0,
"next_offset": null
}
Try it
/consignorsConsignorsList consignors and vendors
Accounts in account-number order, with their balance due. Contact details only for keys allowed to read them.
Parameters
| Parameter | In | Description |
|---|---|---|
vendor | query · boolean | true = vendors only, false = consignors only. |
limit | query · integer | Rows per page, 1-500. |
offset | query · integer | Rows to skip: use next_offset from the previous page. |
Response fields (each item of data)
| Field | Type | Description |
|---|---|---|
account | string | |
name | string | |
business | string | |
vendor | boolean | true = a vendor (booth renter, maker) rather than a consignor. |
store_account | boolean | The store's own house account. |
split_percent | number | |
balance_due | number | What the store owes this account now. |
paid_ytd | number | |
last_paid | string | null | yyyy-MM-dd |
created | string | null | yyyy-MM-dd |
status | string | |
email | string | Only for keys allowed to read contact details. |
phone_cell | string | Contact-details keys only. |
phone_home | string | Contact-details keys only. |
phone_business | string | Contact-details keys only. |
address | Address | Contact-details keys only. |
curl -H "Authorization: Bearer $ROSE_API_KEY" \ "https://app.shr-consignorconnect.com/rose/api/v1/consignors?limit=50"
const r = await fetch("https://app.shr-consignorconnect.com/rose/api/v1/consignors?limit=50", {
headers: { Authorization: `Bearer ${process.env.ROSE_API_KEY}` }
});
const { data } = await r.json();import os, requests
r = requests.get("https://app.shr-consignorconnect.com/rose/api/v1/consignors?limit=50",
headers={"Authorization": "Bearer " + os.environ["ROSE_API_KEY"]}, timeout=30)
r.raise_for_status()
data = r.json()["data"]
Example response
{
"data": [
{
"account": "1042",
"name": "Jane Smith",
"business": "",
"vendor": false,
"store_account": false,
"split_percent": 50,
"balance_due": 57.25,
"paid_ytd": 412.0,
"last_paid": "2026-10-15",
"created": "2025-03-08",
"status": "",
"email": "jane@example.com",
"phone_cell": "555-0100",
"phone_home": "",
"phone_business": "",
"address": {
"line1": "1 Main St",
"line2": "",
"city": "Springfield",
"state": "IL",
"zip": "62701"
}
}
],
"limit": 50,
"offset": 0,
"next_offset": null
}
Try it
/consignors/{account}ConsignorsGet one consignor or vendor
One account by its number.
Parameters
| Parameter | In | Description |
|---|---|---|
account required | path · string | The account number. |
Response fields (data)
| Field | Type | Description |
|---|---|---|
account | string | |
name | string | |
business | string | |
vendor | boolean | true = a vendor (booth renter, maker) rather than a consignor. |
store_account | boolean | The store's own house account. |
split_percent | number | |
balance_due | number | What the store owes this account now. |
paid_ytd | number | |
last_paid | string | null | yyyy-MM-dd |
created | string | null | yyyy-MM-dd |
status | string | |
email | string | Only for keys allowed to read contact details. |
phone_cell | string | Contact-details keys only. |
phone_home | string | Contact-details keys only. |
phone_business | string | Contact-details keys only. |
address | Address | Contact-details keys only. |
curl -H "Authorization: Bearer $ROSE_API_KEY" \ "https://app.shr-consignorconnect.com/rose/api/v1/consignors/1042"
const r = await fetch("https://app.shr-consignorconnect.com/rose/api/v1/consignors/1042", {
headers: { Authorization: `Bearer ${process.env.ROSE_API_KEY}` }
});
const { data } = await r.json();import os, requests
r = requests.get("https://app.shr-consignorconnect.com/rose/api/v1/consignors/1042",
headers={"Authorization": "Bearer " + os.environ["ROSE_API_KEY"]}, timeout=30)
r.raise_for_status()
data = r.json()["data"]
Example response
{
"data": {
"account": "1042",
"name": "Jane Smith",
"business": "",
"vendor": false,
"store_account": false,
"split_percent": 50,
"balance_due": 57.25,
"paid_ytd": 412.0,
"last_paid": "2026-10-15",
"created": "2025-03-08",
"status": "",
"email": "jane@example.com",
"phone_cell": "555-0100",
"phone_home": "",
"phone_business": "",
"address": {
"line1": "1 Main St",
"line2": "",
"city": "Springfield",
"state": "IL",
"zip": "62701"
}
}
}
Try it
/payoutsPayoutsList payouts
Payouts made to consignors and vendors, by date.
Parameters
| Parameter | In | Description |
|---|---|---|
from required | query · string | First day, yyyy-MM-dd (included). |
to required | query · string | Last day, yyyy-MM-dd (included). At most 366 days after from. |
account | query · string | Only this account. |
limit | query · integer | Rows per page, 1-500. |
offset | query · integer | Rows to skip: use next_offset from the previous page. |
Response fields (each item of data)
| Field | Type | Description |
|---|---|---|
id | string | Links the payout's receipt. |
account | string | |
type | string | |
amount | number | A negative PARTIAL PAYOUT reverses one. |
date | string | yyyy-MM-dd |
method | string | How it was paid, as typed in Rose. |
reference | string | Check or transfer number. |
location | Location |
curl -H "Authorization: Bearer $ROSE_API_KEY" \ "https://app.shr-consignorconnect.com/rose/api/v1/payouts?from=2026-10-01&to=2026-10-31&limit=50"
const r = await fetch("https://app.shr-consignorconnect.com/rose/api/v1/payouts?from=2026-10-01&to=2026-10-31&limit=50", {
headers: { Authorization: `Bearer ${process.env.ROSE_API_KEY}` }
});
const { data } = await r.json();import os, requests
r = requests.get("https://app.shr-consignorconnect.com/rose/api/v1/payouts?from=2026-10-01&to=2026-10-31&limit=50",
headers={"Authorization": "Bearer " + os.environ["ROSE_API_KEY"]}, timeout=30)
r.raise_for_status()
data = r.json()["data"]
Example response
{
"data": [
{
"id": "6f1c2a\u2026",
"account": "1042",
"type": "PAYOUT",
"amount": 412.0,
"date": "2026-10-15",
"method": "CHECK",
"reference": "10233",
"location": {
"code": "1",
"name": "Main Street"
}
}
],
"limit": 50,
"offset": 0,
"next_offset": null
}
Try it
OpenAPI & Postman
The whole API as an OpenAPI 3 file: openapi.json. Import it into Postman or Insomnia (Import › File), or generate a client with openapi-generator. Set the collection’s auth to Bearer Token with your key.
Changelog
| Date | Change |
|---|---|
| 2026-11-05 | v1: store, items, sales, consignors / vendors, payouts. Read-only. |
Support
Questions or a field you need: support@consignorconnect.com. Include the request URL and the time (never your key).
ROSE API