Recipe — create a plan

This is the canonical write flow: create a restock plan, then add an item. The same shape applies to other plan types (rebalance, etc.) — only the paths and fields differ.

This creates real data in your organization. Use a token with the right write permission, and test against a non-production organization first if you can.

1. Create the plan

POST /api/restock-plans with name (and optionally brandId, collectionId, description). It returns the new plan’s id and status (DRAFT).

cURL
Python
JavaScript

curl -X POST https://app.solya.app/api/restock-plans \
  -H "Authorization: Bearer solya_sa_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Adidas FW25 Restock Wave 1",
    "brandId": "brand-uuid-adidas",
    "collectionId": "coll-uuid-fw25",
    "description": "First restock order for Adidas FW25"
  }'

import requests
BASE, TOKEN = "https://app.solya.app", "solya_sa_xxx"
headers = {"Authorization": f"Bearer {TOKEN}", "Content-Type": "application/json"}

plan = requests.post(f"{BASE}/api/restock-plans", headers=headers, json={
    "name": "Adidas FW25 Restock Wave 1",
    "brandId": "brand-uuid-adidas",
    "collectionId": "coll-uuid-fw25",
}).json()
plan_id = plan["id"]   # e.g. "rop-uuid-001"; status == "DRAFT"

const BASE = "https://app.solya.app", TOKEN = "solya_sa_xxx"
const headers = { Authorization: `Bearer ${TOKEN}`, "Content-Type": "application/json" }

const plan = await (await fetch(`${BASE}/api/restock-plans`, {
  method: "POST", headers,
  body: JSON.stringify({
    name: "Adidas FW25 Restock Wave 1",
    brandId: "brand-uuid-adidas",
    collectionId: "coll-uuid-fw25",
  }),
})).json()
const planId = plan.id // status: "DRAFT"

Response:

{ "id": "rop-uuid-001", "brandId": "brand-uuid-adidas", "collectionId": "coll-uuid-fw25", "status": "DRAFT" }

2. Add an item

POST /api/restock-plans/{planId}/items with variantId, sizeId, shopId, quantity. It returns { "success": true, "itemId": "…" }.

cURL
Python
JavaScript

curl -X POST https://app.solya.app/api/restock-plans/rop-uuid-001/items \
  -H "Authorization: Bearer solya_sa_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "variantId": "var-uuid-adidas-stan", "sizeId": "sz-uuid-43", "shopId": "shop-uuid-paris-opera", "quantity": 12 }'

res = requests.post(
    f"{BASE}/api/restock-plans/{plan_id}/items",
    headers=headers,
    json={"variantId": "var-uuid-adidas-stan", "sizeId": "sz-uuid-43",
          "shopId": "shop-uuid-paris-opera", "quantity": 12},
).json()

if not res.get("success"):
    raise RuntimeError(f"add item failed: {res.get('errorCode')}")
print("added item", res["itemId"])

const res = await (await fetch(`${BASE}/api/restock-plans/${planId}/items`, {
  method: "POST", headers,
  body: JSON.stringify({
    variantId: "var-uuid-adidas-stan", sizeId: "sz-uuid-43",
    shopId: "shop-uuid-paris-opera", quantity: 12,
  }),
})).json()
if (!res.success) throw new Error(`add item failed: ${res.errorCode}`)
console.log("added item", res.itemId)

Handle the response

Adding items runs through business rules, so plan for these outcomes:

Success — { "success": true, "itemId": "…" }.
Blocked by a rule — success: false with errorCode: "BUSINESS_RULE_VIOLATION"; read the message and adjust.
Validation — errorCode: "VARIANT_REQUIRED", "QUANTITY_INVALID", etc. Fix the payload.
Auth — 401 UNAUTHORIZED (bad/expired token) or 403 FORBIDDEN (missing permission).

See Error codes for the full mapping.

Other plan types follow the same pattern — e.g. rebalance is POST /api/rebalance-plans then POST /api/rebalance-plans/{id}/items. Browse the exact fields per endpoint in the API Reference tab.

​1. Create the plan

​2. Add an item

​Handle the response

1. Create the plan

2. Add an item

Handle the response