ROSE APIv1 OpenAPI fileStore guide

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.

REST · JSON · HTTPSRead-onlyBearer API keysRose Enterprise
Your API keyKept in this tab only.

Quickstart

  1. 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.
  2. Keep it on your server, e.g. in an environment variable ROSE_API_KEY. Never in a web page, mobile app or public repository.
  3. 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 / 403 at 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" } }
StatuscodeMeaning
400bad_dates bad_limit bad_offsetA parameter is missing or out of range
401unauthorizedNo key, a wrong key, or a revoked key
403no_enterprise store_closedThe store doesn’t have Rose Enterprise, or its account isn’t open
404not_foundNo such item or account
429rate_limitedToo many requests — wait and retry
500server_errorTry 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-dd strings, in the store’s time zone (/store). Date ranges include both from and to, 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

GET/storeStore

Get 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)

FieldTypeDescription
storestringThe store's account name in Consignor Connect.
namestringThe store's full name.
previewbooleantrue while the store is trying the new Rose (a copy of its data).
currency_symbolstring
timezonestring
locationsarray of Location
curl -H "Authorization: Bearer $ROSE_API_KEY" \
  "https://app.shr-consignorconnect.com/rose/api/v1/store"

Example response

{
  "data": {
    "store": "MyStore",
    "name": "My Store",
    "preview": false,
    "currency_symbol": "$",
    "timezone": "America/New_York",
    "locations": [
      {
        "code": "1",
        "name": "Main Street"
      }
    ]
  }
}
Try it
GET/itemsItems

List items in stock

Items on the floor, in SKU order. Sold items are under /sales.

Parameters

ParameterInDescription
accountquery · stringOnly this consignor / vendor account.
locationquery · stringOnly this location code.
categoryquery · stringOnly this category name.
limitquery · integerRows per page, 1-500.
offsetquery · integerRows to skip: use next_offset from the previous page.

Response fields (each item of data)

FieldTypeDescription
skustring
accountstringThe consignor / vendor account the item belongs to.
descriptionstring
brandstring
categorystring
sizestring
colorstring
quantitynumber
pricenumberSelling price.
costnumber
consignor_split_percentnumberThe consignor's share of the sale, in %.
shelf_datestring | nullyyyy-MM-dd
expiresstring | nullyyyy-MM-dd
never_expiresboolean
no_discountsbooleantrue = the item is never discounted.
locationLocation
statusstring
curl -H "Authorization: Bearer $ROSE_API_KEY" \
  "https://app.shr-consignorconnect.com/rose/api/v1/items?limit=50"

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
GET/items/{sku}Items

Get one item

One item in stock by SKU. 404 when it is not in stock (a sold item: /sales?sku=).

Parameters

ParameterInDescription
sku requiredpath · stringThe item's SKU.

Response fields (data)

FieldTypeDescription
skustring
accountstringThe consignor / vendor account the item belongs to.
descriptionstring
brandstring
categorystring
sizestring
colorstring
quantitynumber
pricenumberSelling price.
costnumber
consignor_split_percentnumberThe consignor's share of the sale, in %.
shelf_datestring | nullyyyy-MM-dd
expiresstring | nullyyyy-MM-dd
never_expiresboolean
no_discountsbooleantrue = the item is never discounted.
locationLocation
statusstring
curl -H "Authorization: Bearer $ROSE_API_KEY" \
  "https://app.shr-consignorconnect.com/rose/api/v1/items/100245"

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
GET/salesSales

List sales

Sold item lines (sales and returns) by date sold. Fees, charges, credits and payouts are not sales and are left out.

Parameters

ParameterInDescription
from requiredquery · stringFirst day, yyyy-MM-dd (included).
to requiredquery · stringLast day, yyyy-MM-dd (included). At most 366 days after from.
accountquery · stringOnly this account.
locationquery · stringOnly this location code.
skuquery · stringOnly this SKU.
limitquery · integerRows per page, 1-500.
offsetquery · integerRows to skip: use next_offset from the previous page.

Response fields (each item of data)

FieldTypeDescription
skustring
accountstring
descriptionstring
brandstring
categorystring
sizestring
quantitynumberNegative for a return.
sold_pricenumber
consignor_sharenumberWhat the consignor / vendor gets for this line.
feenumber
card_feenumber
discountnumber
taxnumber
date_soldstringyyyy-MM-dd
paid_to_consignorbooleanWhether the consignor's share has been paid out yet.
date_paidstring | nullyyyy-MM-dd
locationLocation
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"

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
GET/consignorsConsignors

List consignors and vendors

Accounts in account-number order, with their balance due. Contact details only for keys allowed to read them.

Parameters

ParameterInDescription
vendorquery · booleantrue = vendors only, false = consignors only.
limitquery · integerRows per page, 1-500.
offsetquery · integerRows to skip: use next_offset from the previous page.

Response fields (each item of data)

FieldTypeDescription
accountstring
namestring
businessstring
vendorbooleantrue = a vendor (booth renter, maker) rather than a consignor.
store_accountbooleanThe store's own house account.
split_percentnumber
balance_duenumberWhat the store owes this account now.
paid_ytdnumber
last_paidstring | nullyyyy-MM-dd
createdstring | nullyyyy-MM-dd
statusstring
emailstringOnly for keys allowed to read contact details.
phone_cellstringContact-details keys only.
phone_homestringContact-details keys only.
phone_businessstringContact-details keys only.
addressAddressContact-details keys only.
curl -H "Authorization: Bearer $ROSE_API_KEY" \
  "https://app.shr-consignorconnect.com/rose/api/v1/consignors?limit=50"

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
GET/consignors/{account}Consignors

Get one consignor or vendor

One account by its number.

Parameters

ParameterInDescription
account requiredpath · stringThe account number.

Response fields (data)

FieldTypeDescription
accountstring
namestring
businessstring
vendorbooleantrue = a vendor (booth renter, maker) rather than a consignor.
store_accountbooleanThe store's own house account.
split_percentnumber
balance_duenumberWhat the store owes this account now.
paid_ytdnumber
last_paidstring | nullyyyy-MM-dd
createdstring | nullyyyy-MM-dd
statusstring
emailstringOnly for keys allowed to read contact details.
phone_cellstringContact-details keys only.
phone_homestringContact-details keys only.
phone_businessstringContact-details keys only.
addressAddressContact-details keys only.
curl -H "Authorization: Bearer $ROSE_API_KEY" \
  "https://app.shr-consignorconnect.com/rose/api/v1/consignors/1042"

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
GET/payoutsPayouts

List payouts

Payouts made to consignors and vendors, by date.

Parameters

ParameterInDescription
from requiredquery · stringFirst day, yyyy-MM-dd (included).
to requiredquery · stringLast day, yyyy-MM-dd (included). At most 366 days after from.
accountquery · stringOnly this account.
limitquery · integerRows per page, 1-500.
offsetquery · integerRows to skip: use next_offset from the previous page.

Response fields (each item of data)

FieldTypeDescription
idstringLinks the payout's receipt.
accountstring
typestring
amountnumberA negative PARTIAL PAYOUT reverses one.
datestringyyyy-MM-dd
methodstringHow it was paid, as typed in Rose.
referencestringCheck or transfer number.
locationLocation
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"

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

DateChange
2026-11-05v1: 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).