--- name: recircleos description: Set up a consignment store on RecircleOS for its owner, starting from scratch or moving consignors, inventory and balances over from a spreadsheet or another system (ConsignCloud, SimpleConsign, Ricochet, Shopify), using the RecircleOS REST API. No signup is needed to start. Use when an owner wants to start using RecircleOS or switch to it. --- # Set up a consignment store on RecircleOS You work for a store owner, who may not be technical: explain in plain words, and don't show them API details unless they ask. Everything goes through the ordinary REST API — there is no bulk-import endpoint. Base URL `https://www.recircleos.com/api/v1`; auth `Authorization: Bearer `. Money is integer cents; `split` is the consignor's share as 0–1. Full reference: https://www.recircleos.com/api/v1/openapi and https://www.recircleos.com/llms.txt. ## 1. Get a key - Owner already on RecircleOS: ask them for an API key (Settings → API & Webhooks). - Otherwise start their store — no signup needed: `POST https://www.recircleos.com/api/v1/anonymous` with `{"store_name": "...", "email": "owner@..."}` if they told you (both optional). Keep `api_key` and `claim_url`; the claim link is how they take ownership in step 8. **Starting from scratch?** Skip to step 5 for any consignors or items they want to add now (it's fine to add none), then go to step 8. ## 2. Get the data out of the old system - **Excel or Google Sheets** — Share the workbook, or save each sheet (consignors, inventory) as CSV. Hand-made sheets vary most. Item names are often in a “Description” column; consignors may be referenced by name, number, or email. - **ConsignCloud** — Export accounts and items to CSV from ConsignCloud. On a plan with API access, the agent can read them straight from the ConsignCloud API instead — RecircleOS uses the same shapes, so records map field for field. “Split” is already the consignor’s share (0–1). Tag prices are in dollars in CSV exports, cents over their API. - **SimpleConsign** — Export the consignor list and the inventory report to CSV. Items reference consignors by “Consignor ID” — import consignors first so those IDs resolve. - **Ricochet** — Export consignors and inventory from the reports area to CSV. Check whether the percentage column is the consignor’s payout or the store’s commission. - **Shopify** — Products → Export → CSV (all products). Customers → Export if consignors are kept as customers. One product can span several rows (variants and extra images); rows without a price are image rows. “Vendor” is the consignor in some shops and the brand in others — ask. Read CSV or Excel files yourself. Consignors and items are usually separate files. ## 3. Map the columns | | Their column (examples) | RecircleOS | Note | |---|---|---|---| | Consignor | Account #, Consignor ID, Vendor ID | `number` | | | Consignor | Name, Full Name | `first_name + last_name` | split “Last, First” too | | Consignor | Email, Phone, Address, City, State, Zip | `email, phone_number, address_line_1, city, state, postal_code` | | | Consignor | Split, Consignor %, Payout % | `default_split` | 0–1, consignor’s share | | Consignor | Store %, Commission | `default_split = 1 − value` | only once the owner confirms it’s the store’s cut | | Consignor | Balance, Amount Owed | `POST /balance-entries` | opening balance, cents | | Item | SKU, Item #, Tag #, Barcode, Variant SKU | `sku` | also the re-run key | | Item | Title, Item Name, Description, Product | `title` | | | Item | Price, Tag Price, Retail, Variant Price | `tag_price` | cents: $45.00 → 4500 | | Item | Cost, Cost per item | `cost_per` | cents | | Item | Qty, Quantity, On Hand, Variant Inventory Qty | `quantity` | required; 1 if absent | | Item | Consignor, Account, Consignor ID | `account` | the consignor’s RecircleOS id | | Item | Brand, Designer · Color · Size · Condition | `brand · color · size · details` | | | Item | Category, Type, Tags | `tags (or category via /item-categories)` | | | Item | Expires, Expiration Date | `expires` | YYYY-MM-DD | Leave unmapped columns out and tell the owner which ones you skipped. ## 4. Ask only what the data can't tell you Don't hold the migration up with a questionnaire. Ask the owner only when getting it wrong would move money the wrong way, and otherwise pick the sensible default and say what you assumed — every setting can be changed later in the dashboard or over the API. Ask about: - **Commission / percentage columns** — is it the consignor's share or the store's cut? (Paying consignors the store's cut is the costly mistake.) - **Balances** — is the balance column money the shop owes each consignor today? If yes, carry it over as an opening balance. - **Shopify "Vendor"** — consignor or brand? - **Items whose consignor isn't in the consignor file** — create those consignors from the name/number, or leave the items out? Don't ask about taxes, time zone, receipts or other settings to migrate — mention they can be set later. ## 5. Consignors first For each consignor row: 1. Skip if already there: `GET https://www.recircleos.com/api/v1/accounts?number=` (or `?email=`); a non-empty `data` means it exists. 2. `POST https://www.recircleos.com/api/v1/accounts` with `{"number": "C-101", "first_name": "Jane", "last_name": "Doe", "email": "jane@example.com", "default_split": 0.6}`. 3. Opening balance (only if the owner said so): `POST https://www.recircleos.com/api/v1/balance-entries` with `{"account": "", "amount": 2000, "title": "Opening balance (migration)"}`. Keep a map from the old consignor reference (number, name, email) to the new account `id`. ## 6. Then items For each item row: 1. Skip if already there: `GET https://www.recircleos.com/api/v1/items?sku=`. 2. `POST https://www.recircleos.com/api/v1/items` with `{"sku": "1001", "title": "Silk Dress", "brand": "Reformation", "tag_price": 4500, "quantity": 1, "account": "", "split": 0.6}`. - `quantity` is required. Omit `split` to inherit the consignor's default. - Store-owned stock: `"inventory_type": "buy_outright"` (or `"retail"`) and no account. Checking by `sku`/`number` first makes the whole run safe to repeat after an interruption. ## 7. Limits - Before it's claimed: 100 active items, 50 consignors, 10 finalized sales, 1000 calls/day, deleted after 14 days unless claimed. A `402 sandbox_claim_required` response carries `claim_url`: stop and hand it to the owner. - A claimed store on the free plan answers `402 plan_upgrade_required` when it reaches the plan's limits; the paid plan for the rest is coming soon, so bring over the most important records first and point the owner to https://www.recircleos.com/waitlist?interest=pro. - Reads, updates and deletes keep working at any limit. ## 8. Check and hand over 1. Compare counts with the source: `GET https://www.recircleos.com/api/v1/accounts` and `GET https://www.recircleos.com/api/v1/items` return `count`. 2. Show the owner a few records to spot-check, and list what you skipped or assumed. 3. Give the owner `claim_url` and tell them what happens next: they open it, create their login, and click the link in the confirmation email. Then the store is theirs and opens in their browser — and your key keeps working. Stores nobody claims are deleted after 14 days.