---
name: recircleos-migrate
description: Move a consignment store's consignors, inventory and balances into RecircleOS from a spreadsheet or another system (ConsignCloud, SimpleConsign, Ricochet, Shopify) using the RecircleOS REST API. Use when an owner wants to switch to RecircleOS or set up a new RecircleOS store from existing data.
---

# Migrate a consignment store to RecircleOS

You move the owner's existing data in with the ordinary REST API — there is no bulk-import endpoint. Base URL `https://www.recircleos.com/api/v1`; auth `Authorization: Bearer <key>`. 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 an anonymous sandbox — no signup: `POST https://www.recircleos.com/api/v1/anonymous` (optionally `{"store_name": "...", "email": "owner@..."}`). Keep `api_key` and `claim_url`.

## 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=<number>` (or `?email=<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": "<id>", "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=<sku>`.
2. `POST https://www.recircleos.com/api/v1/items` with `{"sku": "1001", "title": "Silk Dress", "brand": "Reformation", "tag_price": 4500, "quantity": 1, "account": "<consignor id>", "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

- Sandbox: 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 rest of the migration needs the paid plan.
- 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. Sandbox: send the owner `claim_url`. They sign up with an email they confirm, the store becomes theirs, and your key keeps working.