{"openapi":"3.1.0","info":{"title":"Birl Resale API","version":"0.1.0","description":"Query Shopify products across installed partner stores. Authenticated with Bearer API keys."},"servers":[{"url":"https://birl-resale-app.workers.dev","description":"production"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"brl_<env>_<publicId>_<secret>"}},"schemas":{"Store":{"type":"object","properties":{"id":{"type":"string","description":"Tenant UUID"},"shopDomain":{"type":"string","example":"clientshop.myshopify.com"},"shopHandle":{"type":"string","example":"clientshop"},"shopifyAppSlug":{"type":"string","description":"Slug of the Partner app this shop installed through.","example":"birl-odd-muse"},"scopes":{"type":"array","items":{"type":"string"}},"installedAt":{"type":"string","format":"date-time"},"uninstalledAt":{"type":"string","nullable":true,"format":"date-time"},"channels":{"type":"array","items":{"type":"string","enum":["shopify","vinted","ebay"]},"description":"Resale channels enabled for this store."}},"required":["id","shopDomain","shopHandle","shopifyAppSlug","scopes","installedAt","uninstalledAt","channels"]},"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]},"Product":{"type":"object","properties":{"id":{"type":"string","example":"gid://shopify/Product/1234567890"},"handle":{"type":"string"},"title":{"type":"string"},"vendor":{"type":"string","nullable":true},"productType":{"type":"string","nullable":true},"status":{"type":"string","enum":["ACTIVE","ARCHIVED","DRAFT"]},"tags":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"raw":{"type":"object","additionalProperties":{"nullable":true},"description":"Full Shopify product JSON. Stable fields promoted above, all others here."}},"required":["id","handle","title","vendor","productType","status","tags","createdAt","updatedAt","raw"]},"ShopifyGraphqlRequest":{"type":"object","properties":{"query":{"type":"string","minLength":1},"variables":{"type":"object","additionalProperties":{"nullable":true}},"operationName":{"type":"string"}},"required":["query"]},"AppSummary":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"clientId":{"type":"string"},"anchorShopDomain":{"type":"string","nullable":true},"partnerAppHandle":{"type":"string","nullable":true},"shopifyPartnerAppId":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"disabledAt":{"type":"string","nullable":true,"format":"date-time"},"installUrl":{"type":"string","format":"uri"},"partnerDashboardUrl":{"type":"string","nullable":true}},"required":["id","slug","name","clientId","anchorShopDomain","partnerAppHandle","shopifyPartnerAppId","createdAt","disabledAt","installUrl","partnerDashboardUrl"]},"RegisterAppRequest":{"type":"object","properties":{"slug":{"type":"string","minLength":2,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"clientId":{"type":"string","minLength":8},"clientSecret":{"type":"string","minLength":8},"anchorShopDomain":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]*\\.myshopify\\.com$/i"},"partnerAppHandle":{"type":"string"}},"required":["slug","name","clientId","clientSecret"]},"SeedP2pListingRequest":{"type":"object","properties":{"tenantId":{"type":"string","minLength":1},"sku":{"type":"string","minLength":1},"title":{"type":"string","minLength":1},"imageUrl":{"type":"string","format":"uri"},"priceMinor":{"type":"integer","minimum":0,"exclusiveMinimum":true}},"required":["tenantId","sku","title","priceMinor"]},"P2pNativeEnableRequest":{"type":"object","properties":{"tenantId":{"type":"string","minLength":1},"enabled":{"type":"boolean","default":true}},"required":["tenantId"]},"P2pNativeBackfillRequest":{"type":"object","properties":{"tenantId":{"type":"string","minLength":1},"limit":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":200,"default":50},"reproject":{"type":"boolean","default":false}},"required":["tenantId"]},"EmbedStatusResponse":{"type":"object","properties":{"tenantId":{"type":"string"},"shopDomain":{"type":"string"},"wmsInstalled":{"type":"boolean"},"resaleEmbedInstalledOnMerchant":{"type":"boolean"},"resaleEmbedMerchantInstallUrl":{"type":"string","nullable":true},"resaleTokensConfigured":{"type":"boolean"},"embedFinalized":{"type":"boolean"},"resaleShopDomain":{"type":"string","nullable":true},"embedPublicKey":{"type":"string","nullable":true},"embedEnabledAt":{"type":"string","nullable":true,"format":"date-time"},"scriptSrc":{"type":"string","nullable":true,"format":"uri"}},"required":["tenantId","shopDomain","wmsInstalled","resaleEmbedInstalledOnMerchant","resaleEmbedMerchantInstallUrl","resaleTokensConfigured","embedFinalized","resaleShopDomain","embedPublicKey","embedEnabledAt","scriptSrc"]},"EmbedTokensRequest":{"type":"object","properties":{"resaleShopDomain":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]*\\.myshopify\\.com$/i"},"resaleAdminToken":{"type":"string","minLength":20},"resaleStorefrontToken":{"type":"string","minLength":20}},"required":["resaleShopDomain","resaleAdminToken"]},"EmbedFinalizeResponse":{"type":"object","properties":{"tenantId":{"type":"string"},"embedPublicKey":{"type":"string"},"embedEnabledAt":{"type":"string","format":"date-time"},"scriptSrc":{"type":"string","format":"uri"}},"required":["tenantId","embedPublicKey","embedEnabledAt","scriptSrc"]},"ProvisionInternalAppRequest":{"type":"object","properties":{"resaleShopDomain":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]*\\.myshopify\\.com$/i"}},"required":["resaleShopDomain"]},"P2pChannelConfig":{"type":"object","properties":{"tenantId":{"type":"string"},"nativeEnabled":{"type":"boolean"},"buyerFeeBps":{"type":"integer"},"buyerFeeFixedMinor":{"type":"integer"},"brandFeeShareBps":{"type":"integer"},"voucherUpliftBps":{"type":"integer"},"billingPlan":{"type":"string","enum":["free","growth"]},"freeMonthlyReleaseCap":{"type":"integer"},"growthRecurringMinor":{"type":"integer"},"currency":{"type":"string","nullable":true},"billing":{"type":"object","properties":{"subscriptionId":{"type":"string","nullable":true},"activatedAt":{"type":"string","nullable":true,"format":"date-time"},"cappedAmountMinor":{"type":"integer","nullable":true}},"required":["subscriptionId","activatedAt","cappedAmountMinor"]}},"required":["tenantId","nativeEnabled","buyerFeeBps","buyerFeeFixedMinor","brandFeeShareBps","voucherUpliftBps","billingPlan","freeMonthlyReleaseCap","growthRecurringMinor","currency","billing"]},"P2pChannelConfigUpdate":{"type":"object","properties":{"buyerFeeBps":{"type":"integer","minimum":0,"maximum":5000},"buyerFeeFixedMinor":{"type":"integer","minimum":0,"maximum":1000},"brandFeeShareBps":{"type":"integer","minimum":0,"maximum":10000},"voucherUpliftBps":{"type":"integer","minimum":0,"maximum":5000},"billingPlan":{"type":"string","enum":["free","growth"]},"freeMonthlyReleaseCap":{"type":"integer","minimum":0,"maximum":100000},"growthRecurringMinor":{"type":"integer","minimum":0,"maximum":1000000}}},"P2pChannelBillingSubscribe":{"type":"object","properties":{"cappedAmountMinor":{"type":"integer","minimum":1000},"test":{"type":"boolean","default":false}}},"P2pChannelLedgerEntry":{"type":"object","properties":{"id":{"type":"string"},"orderId":{"type":"string","nullable":true},"orderName":{"type":"string","nullable":true},"type":{"type":"string"},"amountMinor":{"type":"number"},"currency":{"type":"string"},"billingState":{"type":"string"},"usageRecordId":{"type":"string","nullable":true},"settledAt":{"type":"string","nullable":true,"format":"date-time"},"note":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","orderId","orderName","type","amountMinor","currency","billingState","usageRecordId","settledAt","note","createdAt"]},"TenantSummary":{"type":"object","properties":{"id":{"type":"string"},"shopHandle":{"type":"string"},"shopDomain":{"type":"string"},"visionIndexedAt":{"type":"string","nullable":true,"format":"date-time"},"manualStockEnabledAt":{"type":"string","nullable":true,"format":"date-time"},"resaleEmbedMerchantInstalledAt":{"type":"string","nullable":true,"format":"date-time"},"ready":{"type":"boolean"},"channels":{"type":"array","items":{"type":"string","enum":["shopify","vinted","ebay"]}},"resaleShopifyMode":{"type":"string","enum":["legacy_resale_store","native_brand_store"]},"doesNotNeedPhotos":{"type":"boolean"},"ebayChannel":{"type":"string"},"defaultBoxCapacity":{"type":"integer"},"supportEmail":{"type":"string","nullable":true}},"required":["id","shopHandle","shopDomain","visionIndexedAt","manualStockEnabledAt","resaleEmbedMerchantInstalledAt","ready","channels","resaleShopifyMode","doesNotNeedPhotos","ebayChannel","defaultBoxCapacity","supportEmail"]},"TagResolution":{"type":"object","properties":{"id":{"type":"string"},"tenantId":{"type":"string"},"sku":{"type":"string","nullable":true},"status":{"type":"string"},"productId":{"type":"string","nullable":true},"productTitle":{"type":"string","nullable":true},"size":{"type":"string","nullable":true},"colour":{"type":"string","nullable":true},"lookup":{"type":"object","nullable":true,"properties":{"known":{"type":"boolean"},"productId":{"type":"string","nullable":true},"variantId":{"type":"string","nullable":true},"variantSku":{"type":"string","nullable":true},"productTitle":{"type":"string","nullable":true},"libraryPhotos":{"type":"number"},"liveCount":{"type":"number"},"waitingCount":{"type":"number"},"variantLiveCount":{"type":"number"},"variantWaitingCount":{"type":"number"}},"required":["known","productId","variantId","variantSku","productTitle","libraryPhotos","liveCount","waitingCount","variantLiveCount","variantWaitingCount"]}},"required":["id","tenantId","sku","status","productId","productTitle","size","colour","lookup"]},"SkuLookup":{"type":"object","properties":{"known":{"type":"boolean"},"productId":{"type":"string","nullable":true},"variantId":{"type":"string","nullable":true},"variantSku":{"type":"string","nullable":true},"productTitle":{"type":"string","nullable":true},"libraryPhotos":{"type":"number"},"liveCount":{"type":"number"},"waitingCount":{"type":"number"},"variantLiveCount":{"type":"number"},"variantWaitingCount":{"type":"number"}},"required":["known","productId","variantId","variantSku","productTitle","libraryPhotos","liveCount","waitingCount","variantLiveCount","variantWaitingCount"]},"LocateRow":{"type":"object","properties":{"itemId":{"type":"string"},"status":{"type":"string"},"grade":{"type":"string","nullable":true},"boxId":{"type":"string","nullable":true},"boxLabel":{"type":"string","nullable":true},"zone":{"type":"string","nullable":true},"confirmed":{"type":"boolean"}},"required":["itemId","status","grade","boxId","boxLabel","zone","confirmed"]},"BoxContents":{"type":"object","properties":{"box":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"zone":{"type":"string"},"tenantId":{"type":"string"},"capacity":{"type":"number"},"itemCount":{"type":"number"},"status":{"type":"string"}},"required":["id","label","zone","tenantId","capacity","itemCount","status"]},"inside":{"type":"array","items":{"$ref":"#/components/schemas/BoxItem"}},"allocated":{"type":"array","items":{"$ref":"#/components/schemas/BoxItem"}}},"required":["box","inside","allocated"]},"BoxItem":{"type":"object","properties":{"itemId":{"type":"string"},"sku":{"type":"string","nullable":true},"status":{"type":"string"},"grade":{"type":"string","nullable":true},"confirmed":{"type":"boolean"}},"required":["itemId","sku","status","grade","confirmed"]},"IntakeRow":{"type":"object","properties":{"id":{"type":"string"},"tenantId":{"type":"string"},"warehouseId":{"type":"string"},"storageBoxId":{"type":"string","nullable":true},"storageBox":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"label":{"type":"string"},"zone":{"type":"string"}},"required":["id","label","zone"]},"boxLabel":{"type":"string","nullable":true},"boxConfirmed":{"type":"boolean"},"everBoxed":{"type":"boolean"},"awaitingPhotos":{"type":"boolean"},"status":{"type":"string","enum":["processing","needs_review","ready","needs_work","listed","sold","failed"]},"uploadedAt":{"type":"string","format":"date-time"},"processedAt":{"type":"string","nullable":true,"format":"date-time"},"matchProductId":{"type":"string","nullable":true},"matchVariantId":{"type":"string","nullable":true},"matchConfidence":{"type":"number","nullable":true},"matchAlternatives":{"type":"array","nullable":true,"items":{"type":"object","properties":{"productId":{"type":"string"},"variantId":{"type":"string","nullable":true},"sku":{"type":"string","nullable":true},"imageUrl":{"type":"string"},"score":{"type":"number"},"best_role":{"type":"string","enum":["product","variant","detail"]}},"required":["productId","variantId","sku","imageUrl","score","best_role"]}},"selectedVariantId":{"type":"string","nullable":true},"price":{"type":"string","nullable":true},"condition":{"type":"string","nullable":true,"enum":["New with tags","New without tags","Very good","Good","Satisfactory",null]},"imageKey":{"type":"string","nullable":true},"extraImageKeys":{"type":"array","nullable":true,"items":{"type":"string"}},"tagDetectedSize":{"type":"string","nullable":true},"tagVisible":{"type":"boolean"},"mobileIdentityRequired":{"type":"boolean"},"skipVision":{"type":"boolean"},"grade":{"type":"string","nullable":true,"enum":["A1","A2","B1","B2","C","D","A","B","C1","C2",null]},"suggestedGrade":{"type":"string","nullable":true,"enum":["A1","A2","B1","B2","C","D","A","B","C1","C2",null]},"suggestedGradeReasoning":{"type":"string","nullable":true},"gradeSource":{"type":"string","nullable":true,"enum":["ai","operator",null]},"triageReason":{"type":"string","nullable":true},"operativeId":{"type":"string","nullable":true},"triagedAt":{"type":"string","nullable":true,"format":"date-time"},"damageTags":{"type":"array","items":{"type":"string"}},"damageNotes":{"type":"string","nullable":true},"rrpPence":{"type":"integer","nullable":true},"categorySnapshot":{"type":"string","nullable":true},"skuSnapshot":{"type":"string","nullable":true},"tagOnly":{"type":"boolean"},"photoSource":{"type":"string","enum":["captured","reused","catalog","pending"]},"photoEnhancementStatus":{"type":"string","enum":["not_applicable","processing","partial","enhanced","stalled"]},"photoEnhancementTotal":{"type":"integer"},"photoEnhancementEnhanced":{"type":"integer"},"photoEnhancementPending":{"type":"integer"},"photoOrigin":{"type":"string","nullable":true,"enum":["generated","operator","supplied",null]},"photoRegenStartedAt":{"type":"string","nullable":true},"photoRegenScope":{"type":"string","nullable":true},"photoRegenError":{"type":"string","nullable":true},"reusedFromIntakeId":{"type":"string","nullable":true},"workType":{"type":"string","nullable":true,"enum":["cleaning","repair","hold",null]},"workState":{"type":"string","nullable":true,"enum":["waiting","in_progress","done",null]},"workStartedAt":{"type":"string","nullable":true,"format":"date-time"},"workCompletedAt":{"type":"string","nullable":true,"format":"date-time"},"resaleProductId":{"type":"string","nullable":true},"resaleProductUrl":{"type":"string","nullable":true},"failedReason":{"type":"string","nullable":true},"listedAt":{"type":"string","nullable":true,"format":"date-time"},"imageUrl":{"type":"string"},"extraImageUrls":{"type":"array","items":{"type":"string"}},"tagImageUrl":{"type":"string"},"normalisedPayload":{"type":"object","nullable":true,"properties":{"productName":{"type":"string"},"titleOverride":{"type":"string","nullable":true},"description":{"type":"string"},"brand":{"type":"string","nullable":true},"size":{"type":"string","nullable":true},"vintedCategoryPath":{"type":"string","nullable":true},"vintedColorId":{"type":"number","nullable":true},"vintedMaterialId":{"type":"number","nullable":true},"ebayCategoryId":{"type":"string","nullable":true},"ebayAspects":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["productName","description","brand","size","vintedCategoryPath","vintedColorId","vintedMaterialId","ebayCategoryId","ebayAspects"]},"sourceProvider":{"type":"string","nullable":true},"productTitle":{"type":"string","nullable":true},"pickSize":{"type":"string","nullable":true},"pickColour":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"sale":{"type":"object","nullable":true,"properties":{"soldPricePence":{"type":"number","nullable":true},"currency":{"type":"string"},"channel":{"type":"string","nullable":true},"soldAt":{"type":"string","nullable":true},"fulfilmentState":{"type":"string","enum":["pending","picked","packed","dispatched","delivered","returned"]}},"required":["soldPricePence","currency","channel","soldAt","fulfilmentState"]}},"required":["id","tenantId","warehouseId","storageBoxId","boxLabel","boxConfirmed","everBoxed","awaitingPhotos","status","uploadedAt","processedAt","matchProductId","matchVariantId","matchConfidence","matchAlternatives","selectedVariantId","price","condition","imageKey","extraImageKeys","tagDetectedSize","tagVisible","mobileIdentityRequired","skipVision","grade","suggestedGrade","suggestedGradeReasoning","gradeSource","triageReason","operativeId","triagedAt","damageTags","damageNotes","rrpPence","categorySnapshot","skuSnapshot","tagOnly","photoSource","photoEnhancementStatus","photoEnhancementTotal","photoEnhancementEnhanced","photoEnhancementPending","photoOrigin","photoRegenStartedAt","photoRegenScope","photoRegenError","reusedFromIntakeId","workType","workState","workStartedAt","workCompletedAt","resaleProductId","resaleProductUrl","failedReason","listedAt","imageUrl","extraImageUrls","tagImageUrl","normalisedPayload","sourceProvider","description","sale"]},"BoxSummary":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"zone":{"type":"string"},"itemCount":{"type":"number"},"capacity":{"type":"number"},"status":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","label","zone","itemCount","capacity","status","createdAt"]},"ItemOutcome":{"type":"object","properties":{"intakeItemId":{"type":"string"},"tenantId":{"type":"string"},"outcome":{"type":"string","enum":["sold","donated","recycled","unsold"]},"channel":{"type":"string","nullable":true,"enum":["shopify","vinted","ebay","donation","recycle",null]},"soldPricePence":{"type":"integer","nullable":true},"currency":{"type":"string"},"soldAt":{"type":"string","nullable":true,"format":"date-time"},"buyerCountry":{"type":"string","nullable":true},"buyerRegion":{"type":"string","nullable":true},"co2SavedKg":{"type":"number","nullable":true},"carbonMethodVersion":{"type":"string","nullable":true},"source":{"type":"string","enum":["webhook","ebay_sync","shopify_sync","extension","manual","email","migration"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["intakeItemId","tenantId","outcome","channel","soldPricePence","currency","soldAt","buyerCountry","buyerRegion","co2SavedKg","carbonMethodVersion","source","createdAt","updatedAt"]},"CaptureContext":{"type":"object","properties":{"label":{"type":"string"},"warehouse":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]},"tenants":{"type":"array","items":{"$ref":"#/components/schemas/CaptureTenant"}}},"required":["label","warehouse","tenants"]},"CaptureTenant":{"type":"object","properties":{"id":{"type":"string"},"shopHandle":{"type":"string"},"shopDomain":{"type":"string"},"brandAliases":{"type":"array","nullable":true,"items":{"type":"string"}},"doesNotNeedPhotos":{"type":"boolean"},"imageRecognitionEnabled":{"type":"boolean"}},"required":["id","shopHandle","shopDomain","brandAliases","doesNotNeedPhotos","imageRecognitionEnabled"]},"CaptureBoxContents":{"type":"object","properties":{"box":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"zone":{"type":"string"},"tenantId":{"type":"string"},"warehouseId":{"type":"string"},"capacity":{"type":"number"},"itemCount":{"type":"number"},"status":{"type":"string"}},"required":["id","label","zone","tenantId","warehouseId","capacity","itemCount","status"]},"inside":{"type":"array","items":{"$ref":"#/components/schemas/CaptureBoxItem"}},"allocated":{"type":"array","items":{"$ref":"#/components/schemas/CaptureBoxItem"}}},"required":["box","inside","allocated"]},"CaptureBoxItem":{"type":"object","properties":{"itemId":{"type":"string"},"sku":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"imageUrl":{"type":"string","nullable":true},"status":{"type":"string"},"grade":{"type":"string","nullable":true},"confirmed":{"type":"boolean"}},"required":["itemId","sku","status","grade","confirmed"]},"CaptureTokenTenantRef":{"type":"object","properties":{"id":{"type":"string"},"shopHandle":{"type":"string"}},"required":["id","shopHandle"]},"CaptureTokenListItem":{"type":"object","properties":{"id":{"type":"string"},"publicId":{"type":"string"},"label":{"type":"string"},"isActive":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"lastUsedAt":{"type":"string","nullable":true,"format":"date-time"},"revokedAt":{"type":"string","nullable":true,"format":"date-time"},"revokedReason":{"type":"string","nullable":true},"warehouse":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]},"tenants":{"type":"array","items":{"$ref":"#/components/schemas/CaptureTokenTenantRef"}}},"required":["id","publicId","label","isActive","createdAt","lastUsedAt","revokedAt","revokedReason","warehouse","tenants"]},"CaptureTokenSecret":{"type":"object","properties":{"wireToken":{"type":"string"},"qrSvg":{"type":"string"}},"required":["wireToken","qrSvg"]},"Warehouse":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"isUnknown":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","isUnknown","createdAt","updatedAt"]},"FulfilmentRow":{"type":"object","properties":{"outcomeId":{"type":"string"},"intakeItemId":{"type":"string"},"tenantId":{"type":"string"},"channel":{"type":"string","nullable":true},"soldPricePence":{"type":"integer","nullable":true},"currency":{"type":"string"},"soldAt":{"type":"string","nullable":true,"format":"date-time"},"buyerCountry":{"type":"string","nullable":true},"buyerRegion":{"type":"string","nullable":true},"orderRef":{"type":"string","nullable":true},"orderName":{"type":"string","nullable":true},"shippingMethod":{"type":"string","nullable":true},"buyerName":{"type":"string","nullable":true},"buyerEmail":{"type":"string","nullable":true},"buyerPhone":{"type":"string","nullable":true},"shipAddress1":{"type":"string","nullable":true},"shipAddress2":{"type":"string","nullable":true},"shipAddress3":{"type":"string","nullable":true},"shipCity":{"type":"string","nullable":true},"shipPostcode":{"type":"string","nullable":true},"shipCountry":{"type":"string","nullable":true},"warehouseId":{"type":"string"},"warehouseName":{"type":"string"},"boxLabel":{"type":"string","nullable":true},"wasInBox":{"type":"string","nullable":true},"fulfilmentState":{"type":"string","enum":["pending","picked","packed","dispatched","delivered","returned","refunded"]},"trackingNumber":{"type":"string","nullable":true},"trackingCarrier":{"type":"string","nullable":true},"dispatchedAt":{"type":"string","nullable":true,"format":"date-time"},"deliveredAt":{"type":"string","nullable":true,"format":"date-time"},"fulfilmentProvider":{"type":"string","nullable":true},"fulfilmentProviderRef":{"type":"string","nullable":true},"shippingLabelUrl":{"type":"string","nullable":true},"intakeImageUrl":{"type":"string"},"intakeTagImageUrl":{"type":"string"}},"required":["outcomeId","intakeItemId","tenantId","channel","soldPricePence","currency","soldAt","buyerCountry","buyerRegion","orderRef","buyerName","buyerEmail","buyerPhone","shipAddress1","shipAddress2","shipAddress3","shipCity","shipPostcode","shipCountry","warehouseId","warehouseName","boxLabel","fulfilmentState","trackingNumber","trackingCarrier","dispatchedAt","deliveredAt","fulfilmentProvider","fulfilmentProviderRef","shippingLabelUrl","intakeImageUrl","intakeTagImageUrl"]},"FulfilmentTransition":{"allOf":[{"$ref":"#/components/schemas/FulfilmentRow"},{"type":"object","properties":{"dispatch":{"$ref":"#/components/schemas/DispatchStatus"}}}]},"DispatchStatus":{"type":"object","nullable":true,"properties":{"channel":{"type":"string"},"ok":{"type":"boolean"},"detail":{"type":"string"},"providerRef":{"type":"string","nullable":true},"manual":{"type":"boolean"},"labelUrl":{"type":"string","nullable":true},"trackingNumber":{"type":"string","nullable":true},"trackingCarrier":{"type":"string","nullable":true}},"required":["channel","ok","detail"]},"ShipAddress":{"type":"object","properties":{"name":{"type":"string","nullable":true},"line1":{"type":"string","nullable":true},"line2":{"type":"string","nullable":true},"line3":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"region":{"type":"string","nullable":true},"postcode":{"type":"string","nullable":true},"country":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"orderRef":{"type":"string","nullable":true},"channel":{"type":"string","nullable":true},"items":{"type":"array","items":{"type":"string"}}},"required":["name","line1","line2","line3","city","region","postcode","country","phone","orderRef","channel","items"]},"VintedPublishResponse":{"type":"object","properties":{"jobId":{"type":"string"},"channel":{"type":"string","enum":["vinted"]},"status":{"type":"string","enum":["queued","processing","drafted","published","failed","delisted"]},"mode":{"type":"string","enum":["draft","publish"]},"externalUrl":{"type":"string","nullable":true}},"required":["jobId","channel","status","mode","externalUrl"]},"VintedPublishRequest":{"type":"object","properties":{"mode":{"type":"string","enum":["draft","publish"]},"intakeItemId":{"type":"string","minLength":1},"sku":{"type":"string","minLength":1},"title":{"type":"string","minLength":1},"price":{"type":"string","pattern":"^\\d+(\\.\\d{1,2})?$"},"condition":{"type":"string"},"category":{"type":"string"},"brand":{"type":"string"},"description":{"type":"string"},"imageUrls":{"type":"array","items":{"type":"string","format":"uri"}},"vinted":{"type":"object","properties":{"size":{"type":"string"},"color":{"type":"string"},"material":{"type":"string"},"parcelSize":{"type":"string","enum":["Small","Medium","Large"]}}}},"required":["mode","intakeItemId","sku","title","price"]},"VintedJob":{"type":"object","properties":{"id":{"type":"string"},"intakeItemId":{"type":"string"},"tenantId":{"type":"string"},"channel":{"type":"string","enum":["vinted"]},"mode":{"type":"string","enum":["draft","publish"]},"action":{"type":"string","enum":["list","delist"]},"status":{"type":"string","enum":["queued","processing","drafted","published","failed","delisted"]},"attempts":{"type":"number"},"externalId":{"type":"string","nullable":true},"externalUrl":{"type":"string","nullable":true},"error":{"type":"string","nullable":true},"payload":{"type":"object","nullable":true,"properties":{"sku":{"type":"string"},"title":{"type":"string"},"price":{"type":"string"},"condition":{"type":"string"},"category":{"type":"string"},"brand":{"type":"string"},"description":{"type":"string"},"imageUrls":{"type":"array","items":{"type":"string"}},"vinted":{"type":"object","properties":{"size":{"type":"string"},"color":{"type":"string"},"material":{"type":"string"},"parcelSize":{"type":"string","enum":["Small","Medium","Large"]}}}},"required":["sku","title","price"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","intakeItemId","tenantId","channel","mode","action","status","attempts","externalId","externalUrl","error","payload","createdAt","updatedAt"]},"VintedJobResult":{"type":"object","properties":{"status":{"type":"string","enum":["drafted","published","failed","delisted"]},"externalId":{"type":"string"},"externalUrl":{"type":"string","format":"uri"},"error":{"type":"string"}},"required":["status"]},"PublishRenewedResponse":{"type":"object","properties":{"ok":{"type":"boolean"},"productId":{"type":"string"},"productUrl":{"type":"string"},"variantsCreated":{"type":"number"},"variantsRestocked":{"type":"number"},"error":{"type":"string"}},"required":["ok"]},"PublishRenewedRequest":{"type":"object","properties":{"intakeItemId":{"type":"string","minLength":1},"intakeItemIds":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"maxItems":250},"sku":{"type":"string","minLength":1},"title":{"type":"string"},"price":{"type":"string","pattern":"^\\d+(\\.\\d{1,2})?$"},"condition":{"type":"string"},"description":{"type":"string"},"imageUrls":{"type":"array","items":{"type":"string","format":"uri"}},"taxable":{"type":"boolean"}},"required":["intakeItemId","price"]},"EbayPublishResponse":{"type":"object","properties":{"jobId":{"type":"string"},"channel":{"type":"string","enum":["ebay"]},"status":{"type":"string","enum":["queued","processing","drafted","published","failed","delisted"]},"mode":{"type":"string","enum":["draft","publish"]},"externalUrl":{"type":"string","nullable":true},"error":{"type":"string","nullable":true}},"required":["jobId","channel","status","mode","externalUrl","error"]},"EbayPublishRequest":{"type":"object","properties":{"mode":{"type":"string","enum":["draft","publish"]},"intakeItemId":{"type":"string","minLength":1},"sku":{"type":"string","minLength":1},"title":{"type":"string","minLength":1},"price":{"type":"string","pattern":"^\\d+(\\.\\d{1,2})?$"},"condition":{"type":"string"},"brand":{"type":"string"},"description":{"type":"string"},"imageUrls":{"type":"array","items":{"type":"string","format":"uri"}},"categoryId":{"type":"string"}},"required":["mode","intakeItemId","sku","title","price"]},"EbayGroupPublishResponse":{"type":"object","properties":{"channel":{"type":"string","enum":["ebay"]},"path":{"type":"string","enum":["group","per_size"]},"listingId":{"type":"string","nullable":true},"externalUrl":{"type":"string","nullable":true},"variants":{"type":"number"},"units":{"type":"number"},"error":{"type":"string","nullable":true}},"required":["channel","path","listingId","externalUrl","variants","units","error"]},"EbayGroupPublishRequest":{"type":"object","properties":{"intakeItemId":{"type":"string","minLength":1},"condition":{"type":"string","minLength":1},"imageUrls":{"type":"array","items":{"type":"string","format":"uri"}},"categoryId":{"type":"string"}},"required":["intakeItemId","condition"]},"EbayJob":{"type":"object","properties":{"id":{"type":"string"},"intakeItemId":{"type":"string"},"tenantId":{"type":"string"},"channel":{"type":"string","enum":["ebay"]},"mode":{"type":"string","enum":["draft","publish"]},"status":{"type":"string","enum":["queued","processing","drafted","published","failed","delisted"]},"attempts":{"type":"number"},"externalId":{"type":"string","nullable":true},"externalUrl":{"type":"string","nullable":true},"error":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","intakeItemId","tenantId","channel","mode","status","attempts","externalId","externalUrl","error","createdAt","updatedAt"]},"CieReport":{"type":"object","properties":{"range":{"type":"object","properties":{"from":{"type":"number"},"to":{"type":"number"}},"required":["from","to"]},"summary":{"type":"object","properties":{"itemsProcessed":{"type":"number"},"itemsListed":{"type":"number"},"itemsSold":{"type":"number"},"itemsDonated":{"type":"number"},"itemsRecycled":{"type":"number"},"itemsUnsold":{"type":"number"},"sellThroughRate":{"type":"number"},"grossRevenuePence":{"type":"number"},"avgSalePricePence":{"type":"number"},"recoveryRate":{"type":"number"},"totalCo2SavedKg":{"type":"number"},"avgCo2SavedPerItemKg":{"type":"number"},"avgDaysToSell":{"type":"number"},"importedFromEbay":{"type":"number"}},"required":["itemsProcessed","itemsListed","itemsSold","itemsDonated","itemsRecycled","itemsUnsold","sellThroughRate","grossRevenuePence","avgSalePricePence","recoveryRate","totalCo2SavedKg","avgCo2SavedPerItemKg","avgDaysToSell","importedFromEbay"]},"intakeByGrade":{"type":"array","items":{"type":"object","properties":{"grade":{"type":"string"},"count":{"type":"number"}},"required":["grade","count"]}},"damageBreakdown":{"type":"array","items":{"type":"object","properties":{"tag":{"type":"string"},"count":{"type":"number"}},"required":["tag","count"]}},"salesByChannel":{"type":"array","items":{"type":"object","properties":{"channel":{"type":"string"},"soldCount":{"type":"number"},"revenuePence":{"type":"number"}},"required":["channel","soldCount","revenuePence"]}},"geography":{"type":"array","items":{"type":"object","properties":{"country":{"type":"string"},"soldCount":{"type":"number"}},"required":["country","soldCount"]}},"timeToSell":{"type":"array","items":{"type":"object","properties":{"bucket":{"type":"string"},"count":{"type":"number"}},"required":["bucket","count"]}},"skuPerformance":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string"},"category":{"type":"string","nullable":true},"intakeCount":{"type":"number"},"soldCount":{"type":"number"},"sellThroughRate":{"type":"number"},"recoveryRate":{"type":"number"},"revenuePence":{"type":"number"},"avgDaysToSell":{"type":"number","nullable":true}},"required":["sku","category","intakeCount","soldCount","sellThroughRate","recoveryRate","revenuePence","avgDaysToSell"]}},"timeSeries":{"type":"object","properties":{"intake":{"type":"array","items":{"type":"object","properties":{"day":{"type":"string"},"count":{"type":"number"}},"required":["day","count"]}},"sales":{"type":"array","items":{"type":"object","properties":{"day":{"type":"string"},"count":{"type":"number"},"revenuePence":{"type":"number"}},"required":["day","count","revenuePence"]}}},"required":["intake","sales"]}},"required":["range","summary","intakeByGrade","damageBreakdown","salesByChannel","geography","timeToSell","skuPerformance","timeSeries"]},"StatsOverview":{"type":"object","properties":{"range":{"type":"object","properties":{"from":{"type":"number"},"to":{"type":"number"}},"required":["from","to"]},"throughput":{"type":"object","properties":{"byDay":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"triaged":{"type":"number"},"processed":{"type":"number"},"listed":{"type":"number"},"sold":{"type":"number"}},"required":["date","triaged","processed","listed","sold"]}},"totals":{"type":"object","properties":{"triagedToday":{"type":"number"},"processedToday":{"type":"number"},"listedToday":{"type":"number"},"soldToday":{"type":"number"}},"required":["triagedToday","processedToday","listedToday","soldToday"]}},"required":["byDay","totals"]},"commercial":{"type":"object","properties":{"byBrand":{"type":"array","items":{"type":"object","properties":{"tenantId":{"type":"string"},"brand":{"type":"string"},"itemsSold":{"type":"number"},"revenuePence":{"type":"number"}},"required":["tenantId","brand","itemsSold","revenuePence"]}},"revenueByDay":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"revenuePence":{"type":"number"}},"required":["date","revenuePence"]}},"itemsSoldByDay":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"count":{"type":"number"}},"required":["date","count"]}},"totals":{"type":"object","properties":{"itemsSold":{"type":"number"},"revenuePence":{"type":"number"}},"required":["itemsSold","revenuePence"]}},"required":["byBrand","revenueByDay","itemsSoldByDay","totals"]}},"required":["range","throughput","commercial"]},"RoutingRule":{"type":"object","properties":{"id":{"type":"string"},"tenantId":{"type":"string"},"priority":{"type":"integer"},"name":{"type":"string"},"conditions":{"type":"object","properties":{"grade":{"type":"array","items":{"type":"string","enum":["A","B1","B2","C1","C2","D","B","C"]}},"categories":{"type":"array","items":{"type":"string"}},"damageTags":{"type":"array","items":{"type":"string"}},"minRrpPence":{"type":"integer"},"maxRrpPence":{"type":"integer"}}},"action":{"type":"object","properties":{"channel":{"type":"string","enum":["shopify","vinted","ebay","donation","recycle"]}},"required":["channel"]},"enabled":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","tenantId","priority","name","conditions","action","enabled","createdAt","updatedAt"]},"PricingSettings":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"tenantId":{"type":"string"},"enabled":{"type":"boolean"},"floorPercent":{"type":"integer"},"cooldownDays":{"type":"integer"},"priceEnding":{"type":"string","enum":["95","99","00","none"]},"ladder":{"type":"array","items":{"type":"object","properties":{"afterDays":{"type":"integer","minimum":0,"maximum":365},"minWatchers":{"type":"integer","nullable":true,"minimum":0},"dropPercent":{"type":"integer","minimum":1,"maximum":90},"applyMode":{"type":"string","enum":["auto","suggest"]}},"required":["afterDays","dropPercent","applyMode"]}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","tenantId","enabled","floorPercent","cooldownDays","priceEnding","ladder","createdAt","updatedAt"]},"PriceChange":{"type":"object","properties":{"id":{"type":"string"},"intakeItemId":{"type":"string"},"channel":{"type":"string","enum":["ebay","vinted"]},"sku":{"type":"string"},"title":{"type":"string","nullable":true},"listingId":{"type":"string","nullable":true},"oldPricePence":{"type":"integer"},"newPricePence":{"type":"integer"},"dropPercent":{"type":"integer"},"status":{"type":"string","enum":["suggested","applied","rejected","failed"]},"signals":{"type":"object","properties":{"daysListed":{"type":"integer"},"watchCount":{"type":"integer"},"rungAfterDays":{"type":"integer"},"views":{"type":"integer"}},"required":["daysListed","watchCount","rungAfterDays"]},"reason":{"type":"string"},"error":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"appliedAt":{"type":"string","nullable":true,"format":"date-time"}},"required":["id","intakeItemId","channel","sku","title","listingId","oldPricePence","newPricePence","dropPercent","status","signals","reason","error","createdAt","appliedAt"]},"ListingMetric":{"type":"object","properties":{"id":{"type":"string"},"intakeItemId":{"type":"string","nullable":true},"channel":{"type":"string","enum":["ebay","vinted"]},"sku":{"type":"string"},"listingId":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"currentPricePence":{"type":"integer","nullable":true},"originalPricePence":{"type":"integer","nullable":true},"daysListed":{"type":"integer","nullable":true},"watchCount":{"type":"integer"},"views":{"type":"integer","nullable":true},"lastChangeAt":{"type":"string","nullable":true,"format":"date-time"},"evaluatedAt":{"type":"string","format":"date-time"}},"required":["id","intakeItemId","channel","sku","listingId","title","currentPricePence","originalPricePence","daysListed","watchCount","views","lastChangeAt","evaluatedAt"]},"Conversation":{"type":"object","properties":{"id":{"type":"string"},"channel":{"type":"string","enum":["ebay","vinted","shopify"]},"externalThreadId":{"type":"string"},"counterpartyId":{"type":"string","nullable":true},"counterpartyName":{"type":"string","nullable":true},"intakeItemId":{"type":"string","nullable":true},"externalItemId":{"type":"string","nullable":true},"eligibilityBasis":{"type":"string"},"subject":{"type":"string","nullable":true},"category":{"type":"string","nullable":true},"aiSummary":{"type":"string","nullable":true},"status":{"type":"string","enum":["open","snoozed","closed"]},"unread":{"type":"integer"},"lastMessageAt":{"type":"string","nullable":true,"format":"date-time"},"lastDirection":{"type":"string","nullable":true,"enum":["inbound","outbound",null]}},"required":["id","channel","externalThreadId","counterpartyId","counterpartyName","intakeItemId","externalItemId","eligibilityBasis","subject","category","aiSummary","status","unread","lastMessageAt","lastDirection"]},"InboxMessage":{"type":"object","properties":{"id":{"type":"string"},"direction":{"type":"string","enum":["inbound","outbound"]},"author":{"type":"string","enum":["counterparty","operator","system"]},"body":{"type":"string"},"status":{"type":"string","enum":["received","queued","sending","sent","failed"]},"error":{"type":"string","nullable":true},"sentAt":{"type":"string","nullable":true,"format":"date-time"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","direction","author","body","status","error","sentAt","createdAt"]},"OutboundJob":{"type":"object","properties":{"id":{"type":"string"},"channel":{"type":"string","enum":["ebay","vinted","shopify"]},"externalThreadId":{"type":"string"},"counterpartyId":{"type":"string","nullable":true},"body":{"type":"string"}},"required":["id","channel","externalThreadId","counterpartyId","body"]}},"parameters":{}},"paths":{"/healthz":{"get":{"tags":["meta"],"summary":"Liveness probe","responses":{"200":{"description":"Service is up","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"version":{"type":"string"}},"required":["status","version"]}}}}}}},"/install/{slug}":{"get":{"tags":["oauth"],"summary":"Begin install flow for a specific client's Shopify app","parameters":[{"schema":{"type":"string"},"required":true,"name":"slug","in":"path"},{"schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]*\\.myshopify\\.com$/i","example":"clientshop.myshopify.com"},"required":true,"name":"shop","in":"query"},{"schema":{"type":"string"},"required":false,"name":"tenantId","in":"query"}],"responses":{"302":{"description":"Redirect to Shopify OAuth consent URL"},"400":{"description":"Invalid shop domain or unknown app slug","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"404":{"description":"App slug not registered","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/oauth/callback":{"get":{"tags":["oauth"],"summary":"OAuth callback — Shopify redirects here after merchant consent","parameters":[{"schema":{"type":"string"},"required":true,"name":"code","in":"query"},{"schema":{"type":"string"},"required":true,"name":"state","in":"query"},{"schema":{"type":"string"},"required":true,"name":"shop","in":"query"},{"schema":{"type":"string"},"required":true,"name":"hmac","in":"query"},{"schema":{"type":"string"},"required":false,"name":"host","in":"query"},{"schema":{"type":"string"},"required":false,"name":"timestamp","in":"query"}],"responses":{"200":{"description":"Install successful","content":{"text/html":{"schema":{"type":"string"}}}},"400":{"description":"Invalid callback","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/webhooks/shopify":{"post":{"tags":["webhooks"],"summary":"Shopify webhook delivery endpoint (multi-client HMAC verified)","responses":{"200":{"description":"Accepted and enqueued","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]}},"required":["ok"]}}}},"400":{"description":"Missing required Shopify headers","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"401":{"description":"HMAC verification failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/v1/stores":{"get":{"tags":["stores"],"summary":"List installed shops visible to this API key","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Installed, non-uninstalled shops","content":{"application/json":{"schema":{"type":"object","properties":{"stores":{"type":"array","items":{"$ref":"#/components/schemas/Store"}}},"required":["stores"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/stores/{storeId}/products":{"get":{"tags":["products"],"summary":"List products for a store","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"storeId","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":250,"default":50},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Opaque cursor from previous page's `nextCursor`"},"required":false,"description":"Opaque cursor from previous page's `nextCursor`","name":"cursor","in":"query"},{"schema":{"type":"string","enum":["ACTIVE","ARCHIVED","DRAFT"]},"required":false,"name":"status","in":"query"},{"schema":{"type":"string","description":"Filter by title substring (case-insensitive)"},"required":false,"description":"Filter by title substring (case-insensitive)","name":"q","in":"query"}],"responses":{"200":{"description":"Paginated product list","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"nextCursor":{"type":"string","nullable":true}},"required":["items","nextCursor"]}}}},"400":{"description":"Malformed request (e.g. invalid cursor)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Store not found or uninstalled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/stores/{storeId}/products/{productId}":{"get":{"tags":["products"],"summary":"Fetch a single product by Shopify GID","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"storeId","in":"path"},{"schema":{"type":"string","description":"Shopify GID, numeric id, or handle","example":"gid://shopify/Product/1234567890"},"required":true,"description":"Shopify GID, numeric id, or handle","name":"productId","in":"path"}],"responses":{"200":{"description":"Product detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/stores/{storeId}/shopify/graphql":{"post":{"tags":["shopify-proxy"],"summary":"Proxy a GraphQL request to Shopify Admin API on behalf of a tenant","description":"Forward a raw Shopify Admin GraphQL document for the specified store. The per-shop offline token is applied server-side. Response is relayed verbatim, including Shopify's cost/throttle extensions.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"storeId","in":"path"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}$"},"required":false,"name":"apiVersion","in":"query"},{"schema":{"type":"string","enum":["main","resale"]},"required":false,"name":"store","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShopifyGraphqlRequest"}}}},"responses":{"200":{"description":"Shopify GraphQL response relayed unchanged","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"nullable":true}}}}},"400":{"description":"Malformed request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Store not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"502":{"description":"Upstream Shopify error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/apps":{"post":{"tags":["admin"],"summary":"Register a new client's Shopify Partner app","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterAppRequest"}}}},"responses":{"201":{"description":"App registered, client secret stored encrypted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppSummary"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"409":{"description":"Slug or client_id already registered","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}},"get":{"tags":["admin"],"summary":"List all registered Shopify Partner apps","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Apps list (secrets omitted)","content":{"application/json":{"schema":{"type":"object","properties":{"apps":{"type":"array","items":{"$ref":"#/components/schemas/AppSummary"}}},"required":["apps"]}}}}}}},"/admin/apps/{slug}":{"delete":{"tags":["admin"],"summary":"Remove a registered Shopify Partner app from Birl","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":2,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9-]*$"},"required":true,"name":"slug","in":"path"},{"schema":{"type":"string","enum":["0","1","true","false"],"description":"If '1' or 'true', also delete the Partner app from Shopify's Dev Dashboard via the App Management API."},"required":false,"description":"If '1' or 'true', also delete the Partner app from Shopify's Dev Dashboard via the App Management API.","name":"fromShopify","in":"query"}],"responses":{"200":{"description":"App + its tenants removed","content":{"application/json":{"schema":{"type":"object","properties":{"slug":{"type":"string"},"shopifyDeleted":{"type":"boolean"},"shopifyDeleteError":{"type":"string","nullable":true}},"required":["slug","shopifyDeleted"]}}}},"404":{"description":"App not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"412":{"description":"Identity not configured (needed for Shopify-side delete)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/p2p/listings":{"post":{"tags":["admin"],"summary":"Seed a P2P listing (creates a seller if needed)","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeedP2pListingRequest"}}}},"responses":{"201":{"description":"Listing seeded","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"sellerId":{"type":"string"},"tenantId":{"type":"string"},"sku":{"type":"string"},"title":{"type":"string"},"priceMinor":{"type":"integer"},"status":{"type":"string"}},"required":["id","sellerId","tenantId","sku","title","priceMinor","status"]}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/p2p/native/enable":{"post":{"tags":["admin"],"summary":"Enable the native (consignment) P2P model for a tenant","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/P2pNativeEnableRequest"}}}},"responses":{"200":{"description":"Native model flag + infra state","content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"},"locationId":{"type":"string","nullable":true},"publicationId":{"type":"string","nullable":true}},"required":["enabled","locationId","publicationId"]}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"502":{"description":"Shopify infra setup failed (likely missing scopes)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"]}}}}}}},"/admin/p2p/native/backfill":{"post":{"tags":["admin"],"summary":"Backfill listed P2P rows as Shopify products","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/P2pNativeBackfillRequest"}}}},"responses":{"200":{"description":"Backfill batch result","content":{"application/json":{"schema":{"type":"object","properties":{"synced":{"type":"integer"},"failed":{"type":"integer"},"remaining":{"type":"integer"}},"required":["synced","failed","remaining"]}}}},"404":{"description":"Tenant not found or native model not enabled","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/p2p/orders/{orderId}/release":{"post":{"tags":["admin"],"summary":"Release a paid P2P order's store credit to its seller","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"orderId","in":"path"}],"responses":{"200":{"description":"Funds released (alreadyReleased=false) or already released on a prior call (alreadyReleased=true)","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"orderId":{"type":"string"},"alreadyReleased":{"type":"boolean"},"payout":{"type":"object","properties":{"id":{"type":"string"},"sellerId":{"type":"string"},"orderId":{"type":"string"},"payoutTransactionId":{"type":"string","nullable":true},"amountMinor":{"type":"integer"},"currency":{"type":"string"},"state":{"type":"string"}},"required":["id","sellerId","orderId","payoutTransactionId","amountMinor","currency","state"]}},"required":["ok","orderId","alreadyReleased","payout"]}}}},"404":{"description":"Order not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"409":{"description":"Order isn't in a releasable state (refunded, disputed, failed, escrow not held, seller not ready)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"502":{"description":"Store-credit issuance failed — retry safe","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/admin/p2p/orders/{orderId}/refund":{"post":{"tags":["admin"],"summary":"Refund a P2P order — RETIRED (refund via Shopify)","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"orderId","in":"path"}],"responses":{"410":{"description":"Retired — native orders refund through Shopify, not this endpoint","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}":{"delete":{"tags":["admin"],"summary":"Delete a tenant row + all dependent products / sync jobs","description":"Hard-delete the tenant. Cascades to products and sync_jobs via FK ON DELETE CASCADE. Use after the underlying Shopify store has been deleted on the Shopify side, or to clean up test/demo tenants. Does not touch Shopify itself.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":8},"required":true,"name":"tenantId","in":"path"}],"responses":{"200":{"description":"Tenant + cascade rows deleted","content":{"application/json":{"schema":{"type":"object","properties":{"tenantId":{"type":"string"}},"required":["tenantId"]}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/embed/status":{"get":{"tags":["admin"],"summary":"Embed onboarding status for a tenant","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":8},"required":true,"name":"tenantId","in":"path"}],"responses":{"200":{"description":"Current embed configuration state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmbedStatusResponse"}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/embed/tokens":{"post":{"tags":["admin"],"summary":"Store resale store domain + Admin + Storefront tokens","description":"Called by the extension wizard after the ops user pastes the Admin + Storefront tokens from the resale store's custom app. Tokens are AES-GCM encrypted before writing.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":8},"required":true,"name":"tenantId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmbedTokensRequest"}}}},"responses":{"200":{"description":"Tokens stored","content":{"application/json":{"schema":{"type":"object","properties":{"tenantId":{"type":"string"}},"required":["tenantId"]}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"409":{"description":"Resale shop domain already claimed by another tenant","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"502":{"description":"Auto-mint of Storefront token via Shopify REST failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"status":{"type":"number"},"body":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/embed/resale":{"delete":{"tags":["admin"],"summary":"Disconnect resale store from a tenant","description":"Clears the resale shop domain, encrypted Admin + Storefront tokens, embed public key and embed-enabled timestamp. Use after the resale store has been deleted on Shopify, or to re-onboard against a different store.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":8},"required":true,"name":"tenantId","in":"path"}],"responses":{"200":{"description":"Resale config cleared","content":{"application/json":{"schema":{"type":"object","properties":{"tenantId":{"type":"string"}},"required":["tenantId"]}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/embed/provision-storefront":{"post":{"tags":["admin"],"summary":"Mint a Storefront access token using the stored Admin token","description":"Uses the tenant's resale Admin API token to call Shopify's `storefrontAccessTokenCreate` mutation on the resale store, then encrypts and stores the issued Storefront token. Dev Dashboard apps cannot expose Storefront tokens via the Partners UI, so we mint one server-side here.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":8},"required":true,"name":"tenantId","in":"path"}],"responses":{"200":{"description":"Storefront token stored","content":{"application/json":{"schema":{"type":"object","properties":{"tenantId":{"type":"string"}},"required":["tenantId"]}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"409":{"description":"Tenant has no resale Admin token configured yet","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"502":{"description":"Shopify rejected the storefront-token mutation","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/embed/seed-demo":{"post":{"tags":["admin"],"summary":"Seed N demo resale products sharing a main SKU at varied prices","description":"One-off helper for end-to-end demos. Takes a main SKU, price range, and count, then creates N active resale products on the tenant's resale store, each with the same SKU but a different price. Gives us realistic inventory for the condition-tabs UI (e.g. 'Renewed · 6 available · from £300').","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":8},"required":true,"name":"tenantId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"titleTemplate":{"type":"string","minLength":1},"sku":{"type":"string","minLength":1},"count":{"type":"integer","minimum":1,"maximum":20},"priceMin":{"type":"number","minimum":0},"priceMax":{"type":"number","minimum":0}},"required":["titleTemplate","sku","count","priceMin","priceMax"]}}}},"responses":{"200":{"description":"Products created","content":{"application/json":{"schema":{"type":"object","properties":{"created":{"type":"number"},"productIds":{"type":"array","items":{"type":"string"}}},"required":["created","productIds"]}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"409":{"description":"Tenant has no resale Admin token configured yet","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"502":{"description":"Shopify rejected a product create","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"status":{"type":"number"},"body":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/embed/finalize":{"post":{"tags":["admin"],"summary":"Mint embed public key + enable embed for this tenant","description":"Generates a new `embed_public_key` (idempotent: reuses existing key if already set) and sets `embed_enabled_at`. Returns everything the wizard needs to render the install snippet.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":8},"required":true,"name":"tenantId","in":"path"}],"responses":{"200":{"description":"Embed enabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmbedFinalizeResponse"}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"409":{"description":"Tenant has no resale tokens configured yet","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/internal/sync-skus":{"post":{"tags":["admin/embed"],"summary":"Copy SKUs from main store products onto matching resale store products","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":8},"required":true,"name":"tenantId","in":"path"},{"schema":{"type":"string","enum":["true","false"],"description":"When true, report the plan without writing."},"required":false,"description":"When true, report the plan without writing.","name":"dryRun","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"Blank stale false-match SKUs that have no correct twin."},"required":false,"description":"Blank stale false-match SKUs that have no correct twin.","name":"clearFalseMatches","in":"query"}],"responses":{"200":{"description":"SKU sync complete (or planned, when dryRun=true)","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean"},"productsScanned":{"type":"number"},"productsMatched":{"type":"number"},"variantsUpdated":{"type":"number"},"variantsCleared":{"type":"number"},"unmatchedTitles":{"type":"array","items":{"type":"string"}},"changes":{"type":"array","items":{"type":"object","properties":{"product":{"type":"string"},"variant":{"type":"string"},"variantId":{"type":"number"},"from":{"type":"string"},"to":{"type":"string"},"via":{"type":"string"}},"required":["product","variant","variantId","from","to","via"]}},"cleared":{"type":"array","items":{"type":"object","properties":{"product":{"type":"string"},"variant":{"type":"string"},"variantId":{"type":"number"},"from":{"type":"string"},"reason":{"type":"string"}},"required":["product","variant","variantId","from","reason"]}},"skipped":{"type":"array","items":{"type":"object","properties":{"product":{"type":"string"},"variant":{"type":"string"},"reason":{"type":"string"}},"required":["product","variant","reason"]}}},"required":["dryRun","productsScanned","productsMatched","variantsUpdated","variantsCleared","unmatchedTitles","changes","cleared","skipped"]}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"409":{"description":"Tenant missing main or resale Admin token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/internal/clone-by-sku":{"post":{"tags":["admin/embed"],"summary":"Clone main-store variants into the resale store as 1-of-1 listings","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":8},"required":true,"name":"tenantId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"mode":{"type":"string","enum":["draft","publish"],"default":"publish"},"items":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string","minLength":1},"selectedVariantId":{"type":"string","minLength":1},"matchProductId":{"type":"string","minLength":1},"price":{"type":"string","pattern":"^\\d+(\\.\\d{1,2})?$"},"intakeItemIds":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"maxItems":250},"condition":{"type":"string"},"extraImages":{"type":"array","items":{"anyOf":[{"type":"string","format":"uri"},{"type":"object","properties":{"src":{"type":"string","format":"uri"},"attachment":{"type":"string"},"filename":{"type":"string"},"alt":{"type":"string"}}}]}},"replaceMainImages":{"type":"boolean"}},"required":["sku"]},"minItems":1,"maxItems":50}},"required":["items"]}}}},"responses":{"200":{"description":"Clone results","content":{"application/json":{"schema":{"type":"object","properties":{"cloned":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string"},"productId":{"type":"string"},"variantId":{"type":"string"},"handle":{"type":"string"},"productUrl":{"type":"string"},"published":{"type":"boolean"},"options":{"type":"object","additionalProperties":{"type":"string"}}},"required":["sku","productId","variantId","handle","productUrl","published","options"]}},"skipped":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string"},"reason":{"type":"string"}},"required":["sku","reason"]}}},"required":["cloned","skipped"]}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"409":{"description":"Tenant missing main or resale Admin token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"detail":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/internal/products/{productId}/publish":{"post":{"tags":["admin/embed"],"summary":"Publish a resale product to the Online Store sales channel","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"},{"schema":{"type":"string","pattern":"^\\d+$"},"required":true,"name":"productId","in":"path"}],"responses":{"200":{"description":"Publish result","content":{"application/json":{"schema":{"type":"object","properties":{"productId":{"type":"string"},"published":{"type":"boolean"},"productUrl":{"type":"string"},"userErrors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string","nullable":true},"message":{"type":"string"}},"required":["field","message"]}}},"required":["productId","published","productUrl"]}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"409":{"description":"Tenant missing resale Admin token, or no Online Store publication","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/internal/onboard":{"post":{"tags":["admin/embed"],"summary":"Create a per-tenant Birl Internal Partner app for the tenant's resale dev store","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":8},"required":true,"name":"tenantId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProvisionInternalAppRequest"}}}},"responses":{"200":{"description":"Internal Partner app created + linked to tenant","content":{"application/json":{"schema":{"type":"object","properties":{"slug":{"type":"string"},"clientId":{"type":"string"},"installUrl":{"type":"string"},"partnerDashboardUrl":{"type":"string"},"resaleShopDomain":{"type":"string"}},"required":["slug","clientId","installUrl","partnerDashboardUrl","resaleShopDomain"]}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"409":{"description":"Tenant already has an internal app, or slug/client_id collision","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"412":{"description":"Identity not configured — run /admin/shopify/auth/start","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/internal/release-scopes":{"post":{"tags":["admin/embed"],"summary":"Release a new internal-app version with the current INTERNAL_SCOPES","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":8},"required":true,"name":"tenantId","in":"path"}],"responses":{"200":{"description":"New app version released","content":{"application/json":{"schema":{"type":"object","properties":{"appSlug":{"type":"string"},"versionId":{"type":"string"},"released":{"type":"boolean"},"scopes":{"type":"string"}},"required":["appSlug","versionId","released","scopes"]}}}},"404":{"description":"Tenant or internal app not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"412":{"description":"Identity not configured","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/internal/release-main-scopes":{"post":{"tags":["admin/embed"],"summary":"Release a new MAIN-app version with DEFAULT_SCOPES (adds read_discounts)","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":8},"required":true,"name":"tenantId","in":"path"},{"schema":{"type":"string","enum":["0","1"],"default":"1"},"required":false,"name":"dryRun","in":"query"}],"responses":{"200":{"description":"Proposed manifest (dry-run) or released version","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{"nullable":true}}}}},"404":{"description":"Tenant or main app not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"412":{"description":"Identity not configured","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/internal/reprice-intake-from-catalogue":{"post":{"tags":["admin/quantize"],"summary":"Set intake_items.price from the live Shopify catalogue via the renewed rule (dry-run-first)","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"},{"schema":{"type":"string","enum":["0","1"]},"required":false,"name":"dryRun","in":"query"},{"schema":{"type":"string"},"required":false,"name":"status","in":"query"},{"schema":{"type":"string","enum":["0","1"]},"required":false,"name":"onlyMissing","in":"query"},{"schema":{"type":"string"},"required":false,"name":"channel","in":"query"},{"schema":{"type":"string"},"required":false,"name":"globalDiscountPct","in":"query"}],"responses":{"200":{"description":"Repricing plan (dryRun) or applied result","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean"},"tenantId":{"type":"string"},"discounts":{"type":"object","properties":{"overrideFlatPct":{"type":"number","nullable":true},"allItemsPct":{"type":"number","nullable":true},"collections":{"type":"number"},"productsDiscounted":{"type":"number"}},"required":["overrideFlatPct","allItemsPct","collections","productsDiscounted"]},"considered":{"type":"number"},"repriced":{"type":"number"},"skipped":{"type":"number"},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"sku":{"type":"string","nullable":true},"mainPrice":{"type":"string","nullable":true},"compareAtPrice":{"type":"string","nullable":true},"current":{"type":"string","nullable":true},"suggested":{"type":"string","nullable":true},"skipReason":{"type":"string","nullable":true}},"required":["id","sku","mainPrice","compareAtPrice","current","suggested","skipReason"]}}},"required":["dryRun","tenantId","discounts","considered","repriced","skipped","items"]}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/internal/discount-debug":{"get":{"tags":["admin/quantize"],"summary":"Diagnose site-wide discount detection (granted scopes + raw discounts)","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"}],"responses":{"200":{"description":"Granted scopes + raw discount nodes","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{"nullable":true}}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/internal/quantize-flatten":{"post":{"tags":["admin/quantize"],"summary":"Flatten legacy one-product-per-unit resale stock into the quantized model (dry-run-first)","description":"AYM-only by default. dryRun=1 (default) returns a PLAN ONLY and makes ZERO mutations. dryRun=0 consolidates each duplicated matched product via the quantized publisher, archives the now-redundant separate resale-store products (never deletes), backfills resaleProductId, and journals the migration for reversibility.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":2},"required":true,"name":"tenantId","in":"path"},{"schema":{"type":"string","enum":["0","1"],"default":"1","description":"1 = plan only (default), 0 = execute"},"required":false,"description":"1 = plan only (default), 0 = execute","name":"dryRun","in":"query"},{"schema":{"type":"string","description":"Scope to a single catalogue product GID"},"required":false,"description":"Scope to a single catalogue product GID","name":"matchProductId","in":"query"},{"schema":{"type":"string","enum":["0","1"],"default":"0"},"required":false,"name":"includeImages","in":"query"}],"responses":{"200":{"description":"Plan (dry-run) or execution results","content":{"application/json":{"schema":{"type":"object","properties":{"tenantId":{"type":"string"},"dryRun":{"type":"boolean"},"extraManagedProviders":{"type":"array","items":{"type":"string"}},"productsWithDuplicates":{"type":"number"},"productsConsidered":{"type":"number"},"plan":{"type":"array","items":{"type":"object","properties":{"matchProductId":{"type":"string"},"title":{"type":"string"},"totalUnits":{"type":"number"},"hasDuplicates":{"type":"boolean"},"buckets":{"type":"array","items":{"type":"object","properties":{"selectedVariantId":{"type":"string"},"condition":{"type":"string","nullable":true},"sku":{"type":"string"},"size":{"type":"string","nullable":true},"currentUnits":{"type":"number"},"expectedQuantity":{"type":"number"},"intakeItemIds":{"type":"array","items":{"type":"string"}}},"required":["selectedVariantId","condition","sku","size","currentUnits","expectedQuantity","intakeItemIds"]}},"redundantProductIds":{"type":"array","items":{"type":"string"}}},"required":["matchProductId","title","totalUnits","hasDuplicates","buckets","redundantProductIds"]}},"results":{"type":"array","nullable":true,"items":{"type":"object","properties":{"matchProductId":{"type":"string"},"ok":{"type":"boolean"},"survivorProductId":{"type":"string","nullable":true},"survivorProductUrl":{"type":"string","nullable":true},"variantsCreated":{"type":"number"},"variantsRestocked":{"type":"number"},"archivedProductIds":{"type":"array","items":{"type":"string"}},"archiveErrors":{"type":"array","items":{"type":"object","properties":{"productId":{"type":"string"},"error":{"type":"string"}},"required":["productId","error"]}},"unitsBackfilled":{"type":"number"},"error":{"type":"string","nullable":true}},"required":["matchProductId","ok","survivorProductId","survivorProductUrl","variantsCreated","variantsRestocked","archivedProductIds","archiveErrors","unitsBackfilled","error"]}}},"required":["tenantId","dryRun","extraManagedProviders","productsWithDuplicates","productsConsidered","plan","results"]}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"409":{"description":"Native tenant, or resale Admin token missing","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/internal/quantize-reprice":{"post":{"tags":["admin/quantize"],"summary":"Re-apply the resale price formula to every listed resale variant (dry-run-first)","description":"AYM-only by default. dryRun=1 (default) returns the current→proposed price table and makes ZERO mutations. dryRun=0 updates the resale-store variant price and writes intake_items.price back.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":2},"required":true,"name":"tenantId","in":"path"},{"schema":{"type":"string","enum":["0","1"],"default":"1"},"required":false,"name":"dryRun","in":"query"},{"schema":{"type":"string"},"required":false,"name":"ungradedAs","in":"query"},{"schema":{"type":"string"},"required":false,"name":"globalDiscountPct","in":"query"}],"responses":{"200":{"description":"Reprice plan (dry-run) or execution results","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{"nullable":true}}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"409":{"description":"Native tenant, or resale Admin token missing","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/internal/flatten-imports":{"post":{"tags":["admin/quantize"],"summary":"Flatten unmatched legacy import clones into the quantized model (dry-run-first)","description":"AYM-only by default. Resolves each clone's main-store variant by SKU, stamps selectedVariantId, quantize-publishes, and archives the redundant clone product. Custom variants (no main variant) are reported only. dryRun=1 writes nothing.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":2},"required":true,"name":"tenantId","in":"path"},{"schema":{"type":"string","enum":["0","1"],"default":"1"},"required":false,"name":"dryRun","in":"query"},{"schema":{"type":"string","enum":["0","1"],"default":"0"},"required":false,"name":"includeImages","in":"query"}],"responses":{"200":{"description":"Flatten plan (dry-run) or execution results","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{"nullable":true}}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"409":{"description":"Native tenant, or resale Admin token missing","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/internal/fix-import-skus":{"post":{"tags":["admin/quantize"],"summary":"Rename resale variant SKUs to the clean catalogue SKU (dry-run-first)","description":"AYM-only by default. Renames each managed resale variant to its catalogue SKU (no __COND suffix) and deletes stale duplicate variants so the dual-price widget matches. dryRun=1 writes nothing.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":2},"required":true,"name":"tenantId","in":"path"},{"schema":{"type":"string","enum":["0","1"],"default":"1"},"required":false,"name":"dryRun","in":"query"}],"responses":{"200":{"description":"Plan or results","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{"nullable":true}}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"409":{"description":"Native tenant, or resale Admin token missing","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/internal/backfill-sku-snapshot":{"post":{"tags":["admin/quantize"],"summary":"Stamp sku_snapshot from the matched main variant (dry-run-first)","description":"AYM-only by default. For ready/listed items with a real selectedVariantId but null sku_snapshot, sets sku_snapshot to the main-store variant's SKU. dryRun=1 writes nothing.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":2},"required":true,"name":"tenantId","in":"path"},{"schema":{"type":"string","enum":["0","1"],"default":"1"},"required":false,"name":"dryRun","in":"query"}],"responses":{"200":{"description":"Plan or results","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{"nullable":true}}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"409":{"description":"Native tenant, or main token missing","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/internal/activate-products":{"post":{"tags":["admin/quantize"],"summary":"Set DRAFT managed resale products to ACTIVE + publish (dry-run-first)","description":"AYM-only by default. Lists each managed resale product's status; on execute sets DRAFT ones to ACTIVE and publishes them to the Online Store. dryRun=1 writes nothing.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":2},"required":true,"name":"tenantId","in":"path"},{"schema":{"type":"string","enum":["0","1"],"default":"1"},"required":false,"name":"dryRun","in":"query"}],"responses":{"200":{"description":"Plan or results","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{"nullable":true}}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"409":{"description":"Native tenant, or resale Admin token missing","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/internal/link-colour-photos":{"post":{"tags":["admin/quantize"],"summary":"Associate resale colour variants with the catalogue colour image (dry-run-first)","description":"AYM-only by default. Mirrors the main store's colour→image association onto resale products. dryRun=1 reports the plan and writes nothing.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":2},"required":true,"name":"tenantId","in":"path"},{"schema":{"type":"string","enum":["0","1"],"default":"1"},"required":false,"name":"dryRun","in":"query"},{"schema":{"type":"string"},"required":false,"name":"onlyProduct","in":"query"}],"responses":{"200":{"description":"Plan or results","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{"nullable":true}}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"409":{"description":"Native tenant, or resale Admin token missing","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/internal/resale-collection-fix":{"post":{"tags":["admin/quantize"],"summary":"Update resale collection blurbs + fix the stale 'all' collection (dry-run-first)","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":2},"required":true,"name":"tenantId","in":"path"},{"schema":{"type":"string","enum":["0","1"],"default":"1"},"required":false,"name":"dryRun","in":"query"}],"responses":{"200":{"description":"Plan or results","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{"nullable":true}}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"409":{"description":"Native tenant, or resale Admin token missing","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/internal/condition-tier-backfill":{"post":{"tags":["admin/quantize"],"summary":"Backfill condition tier (Pre-loved -> Excellent) + pull main Aym descriptions","description":"AYM-only by default. Renames the 'Pre-loved' Condition option value to 'Excellent' and (descriptions=1) replaces each resale product description with the matched main Aym description + the approved Birl partner line. dryRun=1 writes nothing.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":2},"required":true,"name":"tenantId","in":"path"},{"schema":{"type":"string","enum":["0","1"],"default":"1"},"required":false,"name":"dryRun","in":"query"},{"schema":{"type":"string","enum":["0","1"],"default":"1"},"required":false,"name":"descriptions","in":"query"}],"responses":{"200":{"description":"Plan or results","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{"nullable":true}}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"409":{"description":"Native tenant, or tokens missing","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/internal/catalogue-audit":{"get":{"tags":["admin/quantize"],"summary":"Audit resale product names/colours/sizes/RRP vs the main Aym catalogue","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":2},"required":true,"name":"tenantId","in":"path"}],"responses":{"200":{"description":"Audit findings","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{"nullable":true}}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"409":{"description":"Native tenant or tokens missing","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/internal/sweep-orphan-duplicates":{"post":{"tags":["admin/quantize"],"summary":"Archive birl-renewed resale products no intake unit references (dry-run-first)","description":"AYM-only by default. Finds resale-store products tagged birl-renewed that no intake_items.resale_product_id references (the `-1` duplicate-listing artifact) and unpublishes + archives them. Untagged unmanaged products are reported, not archived. dryRun=1 writes nothing.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":2},"required":true,"name":"tenantId","in":"path"},{"schema":{"type":"string","enum":["0","1"],"default":"1"},"required":false,"name":"dryRun","in":"query"}],"responses":{"200":{"description":"Plan or results","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{"nullable":true}}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"409":{"description":"Native tenant, or resale Admin token missing","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/internal/unlist-unboxed":{"post":{"tags":["admin/quantize"],"summary":"Revert wrongly-swept listed units to ready and re-assert resale quantities","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":2},"required":true,"name":"tenantId","in":"path"},{"schema":{"type":"string","enum":["0","1"],"default":"1"},"required":false,"name":"dryRun","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"itemIds":{"type":"array","items":{"type":"string","minLength":8},"minItems":1}},"required":["itemIds"]}}}},"responses":{"200":{"description":"Undo plan (dry-run) or execution results","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{"nullable":true}}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"409":{"description":"Native tenant, or resale Admin token missing","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/p2p-channel/config":{"get":{"tags":["admin/p2p-channel"],"summary":"Read a brand's channel money-model config","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"tenantId","in":"path"}],"responses":{"200":{"description":"Current config","content":{"application/json":{"schema":{"$ref":"#/components/schemas/P2pChannelConfig"}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}},"post":{"tags":["admin/p2p-channel"],"summary":"Update a brand's channel money-model config","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"tenantId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/P2pChannelConfigUpdate"}}}},"responses":{"200":{"description":"Updated config","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/P2pChannelConfig"},{"type":"object","properties":{"reprojectionNeeded":{"type":"boolean"}},"required":["reprojectionNeeded"]}]}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/p2p-channel/billing/subscribe":{"post":{"tags":["admin/p2p-channel"],"summary":"Create the usage-billing subscription; returns the merchant approval URL","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"tenantId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/P2pChannelBillingSubscribe"}}}},"responses":{"200":{"description":"Send the merchant to confirmationUrl to approve","content":{"application/json":{"schema":{"type":"object","properties":{"confirmationUrl":{"type":"string"},"subscriptionId":{"type":"string"}},"required":["confirmationUrl","subscriptionId"]}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"502":{"description":"Shopify rejected the subscription create","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"]}}}}}}},"/admin/tenants/{tenantId}/p2p-channel/billing/status":{"get":{"tags":["admin/p2p-channel"],"summary":"Live billing-subscription state (polled during onboarding)","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"tenantId","in":"path"}],"responses":{"200":{"description":"Subscription state from Shopify","content":{"application/json":{"schema":{"type":"object","properties":{"active":{"type":"boolean"},"subscriptionId":{"type":"string","nullable":true},"test":{"type":"boolean","nullable":true},"balanceUsedMinor":{"type":"number","nullable":true},"cappedAmountMinor":{"type":"number","nullable":true},"currency":{"type":"string","nullable":true}},"required":["active","subscriptionId","test","balanceUsedMinor","cappedAmountMinor","currency"]}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/p2p-channel/ledger":{"get":{"tags":["admin/p2p-channel"],"summary":"Brand statement: totals per type + recent entries","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"tenantId","in":"path"}],"responses":{"200":{"description":"Statement","content":{"application/json":{"schema":{"type":"object","properties":{"totals":{"type":"object","additionalProperties":{"type":"number"}},"parkedBillingCount":{"type":"number"},"unsettledCount":{"type":"number"},"entries":{"type":"array","items":{"$ref":"#/components/schemas/P2pChannelLedgerEntry"}}},"required":["totals","parkedBillingCount","unsettledCount","entries"]}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/p2p-channel/ledger.csv":{"get":{"tags":["admin/p2p-channel"],"summary":"Brand statement as CSV","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"tenantId","in":"path"}],"responses":{"200":{"description":"CSV export","content":{"text/csv":{"schema":{"type":"string"}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/p2p-channel/ledger/settle":{"post":{"tags":["admin/p2p-channel"],"summary":"Mark all unsettled ledger rows reconciled","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"tenantId","in":"path"}],"responses":{"200":{"description":"Rows stamped","content":{"application/json":{"schema":{"type":"object","properties":{"settled":{"type":"number"}},"required":["settled"]}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/shopify/auth/start":{"get":{"tags":["admin/shopify"],"summary":"Start Shopify Identity device-flow login","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Device authorization issued","content":{"application/json":{"schema":{"type":"object","properties":{"deviceCode":{"type":"string"},"userCode":{"type":"string"},"verificationUriComplete":{"type":"string"},"expiresIn":{"type":"number"},"interval":{"type":"number"}},"required":["deviceCode","userCode","verificationUriComplete","expiresIn","interval"]}}}}}}},"/admin/shopify/auth/poll":{"post":{"tags":["admin/shopify"],"summary":"Poll for device-flow completion","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"deviceCode":{"type":"string"}},"required":["deviceCode"]}}}},"responses":{"200":{"description":"Status of pending device authorization","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["pending","ok"]},"userEmail":{"type":"string","nullable":true}},"required":["status"]}}}},"404":{"description":"Unknown or expired device_code","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/shopify/auth/status":{"get":{"tags":["admin/shopify"],"summary":"Whether Shopify Identity is configured","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Status","content":{"application/json":{"schema":{"type":"object","properties":{"configured":{"type":"boolean"},"userEmail":{"type":"string","nullable":true},"organizationId":{"type":"string","nullable":true},"updatedAt":{"type":"string","nullable":true}},"required":["configured"]}}}}}}},"/admin/shopify/stores":{"get":{"tags":["admin/shopify"],"summary":"List shops accessible to the Birl partner organization","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Accessible shops","content":{"application/json":{"schema":{"type":"object","properties":{"shops":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"externalId":{"type":"string","nullable":true},"name":{"type":"string"},"storeType":{"type":"string","nullable":true},"primaryDomain":{"type":"string","nullable":true},"shortName":{"type":"string","nullable":true},"url":{"type":"string","nullable":true}},"required":["id","externalId","name","storeType","primaryDomain","shortName","url"]}}},"required":["shops"]}}}},"412":{"description":"Identity not configured","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/shopify/onboard":{"post":{"tags":["admin/shopify"],"summary":"Create a Shopify Partner app + register in shopify_apps","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"slug":{"type":"string","minLength":2,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9-]*$"},"name":{"type":"string","minLength":1,"maxLength":120},"anchorShopDomain":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]*\\.myshopify\\.com$/i"},"scopes":{"type":"string"}},"required":["slug","name"]}}}},"responses":{"200":{"description":"App created and registered","content":{"application/json":{"schema":{"type":"object","properties":{"slug":{"type":"string"},"clientId":{"type":"string"},"installUrl":{"type":"string"},"resaleEmbedInstallUrl":{"type":"string","nullable":true},"partnerDashboardUrl":{"type":"string"},"anchorShopDomain":{"type":"string","nullable":true}},"required":["slug","clientId","installUrl","resaleEmbedInstallUrl","partnerDashboardUrl"]}}}},"409":{"description":"Slug already in use","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"412":{"description":"Identity not configured — run /auth/start","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/intake/pick-colours":{"post":{"tags":["admin/intake"],"summary":"Resolve human colour names for a pick list (Gemini-assisted)","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"itemIds":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":400}},"required":["itemIds"]}}}},"responses":{"200":{"description":"Resolved colour names, keyed by intake item id","content":{"application/json":{"schema":{"type":"object","properties":{"colours":{"type":"object","additionalProperties":{"type":"string"}}},"required":["colours"]}}}}}}},"/admin/tenants":{"get":{"tags":["admin/intake"],"summary":"List tenants (optionally filtered to those ready for intake)","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","enum":["true","false"],"description":"If 'true', only tenants ready for warehouse intake or manual stock registration."},"required":false,"description":"If 'true', only tenants ready for warehouse intake or manual stock registration.","name":"ready","in":"query"}],"responses":{"200":{"description":"Tenant list","content":{"application/json":{"schema":{"type":"object","properties":{"tenants":{"type":"array","items":{"$ref":"#/components/schemas/TenantSummary"}}},"required":["tenants"]}}}}}}},"/admin/tenants/manual":{"post":{"tags":["admin/intake"],"summary":"Create or return a manual-stock tenant","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"shopHandle":{"type":"string","minLength":2,"maxLength":80,"pattern":"^[a-z0-9][a-z0-9-]*$"},"brandName":{"type":"string","minLength":1,"maxLength":120},"brandAliases":{"type":"array","items":{"type":"string","minLength":1,"maxLength":120}}},"required":["shopHandle"]}}}},"responses":{"200":{"description":"Existing manual tenant","content":{"application/json":{"schema":{"type":"object","properties":{"tenant":{"$ref":"#/components/schemas/TenantSummary"}},"required":["tenant"]}}}},"201":{"description":"Manual tenant created","content":{"application/json":{"schema":{"type":"object","properties":{"tenant":{"$ref":"#/components/schemas/TenantSummary"}},"required":["tenant"]}}}},"409":{"description":"Handle belongs to a non-manual tenant","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/channels":{"patch":{"tags":["admin/intake"],"summary":"Update a tenant's enabled resale channels","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"channels":{"type":"array","items":{"type":"string","enum":["shopify","vinted","ebay"]},"minItems":1}},"required":["channels"]}}}},"responses":{"200":{"description":"Updated tenant","content":{"application/json":{"schema":{"type":"object","properties":{"tenant":{"$ref":"#/components/schemas/TenantSummary"}},"required":["tenant"]}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/photo-policy":{"patch":{"tags":["admin/intake"],"summary":"Update a tenant's no-photos intake policy","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"doesNotNeedPhotos":{"type":"boolean"}},"required":["doesNotNeedPhotos"]}}}},"responses":{"200":{"description":"Updated tenant","content":{"application/json":{"schema":{"type":"object","properties":{"tenant":{"$ref":"#/components/schemas/TenantSummary"}},"required":["tenant"]}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/library/catalog-backfill":{"post":{"tags":["admin/intake"],"summary":"Seed the SKU photo library with size-agnostic catalogue photos","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"products":{"type":"array","items":{"type":"object","properties":{"productId":{"type":"string"},"sku":{"type":"string"},"frontUrl":{"type":"string","format":"uri"},"backUrl":{"type":"string","format":"uri"}},"required":["productId","frontUrl"]},"minItems":1,"maxItems":40}},"required":["products"]}}}},"responses":{"200":{"description":"Library seeded","content":{"application/json":{"schema":{"type":"object","properties":{"products":{"type":"number"},"seeded":{"type":"number"},"skipped":{"type":"array","items":{"type":"object","properties":{"productId":{"type":"string"},"reason":{"type":"string"}},"required":["productId","reason"]}}},"required":["products","seeded","skipped"]}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/generate-listing-photos":{"post":{"tags":["admin/intake"],"summary":"Generate AI listing photos (mannequin set) for a catalogue product and attach to its Needs-Photo items","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"productId":{"type":"string"}},"required":["productId"]}}}},"responses":{"200":{"description":"Generated + attached","content":{"application/json":{"schema":{"type":"object","properties":{"ingested":{"type":"number"},"attached":{"type":"number"}},"required":["ingested","attached"]}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"502":{"description":"Generation failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/debug/product-photos":{"post":{"tags":["admin/intake"],"summary":"EPHEMERAL: return mannequin front and mannequin back","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tenantId":{"type":"string"},"productId":{"type":"string"},"dumpOnly":{"type":"boolean"}},"required":["tenantId","productId"]}}}},"responses":{"200":{"description":"front-no-mannequin/front-with-mannequin/back-with-mannequin (base64)","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{"nullable":true}}}}},"404":{"description":"Tenant / product / image not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tag/{code}":{"get":{"tags":["admin/intake"],"summary":"Resolve a scanned stock-tag QR code to its intake unit","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"code","in":"path"}],"responses":{"200":{"description":"The unit this tag belongs to","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TagResolution"}}}},"404":{"description":"Unknown or ambiguous tag code","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/box-capacity":{"patch":{"tags":["admin/intake"],"summary":"Update a tenant's default box capacity (items per box)","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"defaultBoxCapacity":{"type":"integer","minimum":1,"maximum":500}},"required":["defaultBoxCapacity"]}}}},"responses":{"200":{"description":"Updated tenant","content":{"application/json":{"schema":{"type":"object","properties":{"tenant":{"$ref":"#/components/schemas/TenantSummary"}},"required":["tenant"]}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/support-email":{"patch":{"tags":["admin/intake"],"summary":"Set a tenant's brand support email (shopper-facing inbox)","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"supportEmail":{"type":"string","maxLength":200}},"required":["supportEmail"]}}}},"responses":{"200":{"description":"Updated tenant","content":{"application/json":{"schema":{"type":"object","properties":{"tenant":{"$ref":"#/components/schemas/TenantSummary"}},"required":["tenant"]}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/sku-lookup":{"get":{"tags":["admin/intake"],"summary":"Resolve a scanned SKU/barcode to catalogue + photo library","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"},{"schema":{"type":"string"},"required":false,"name":"sku","in":"query"},{"schema":{"type":"string"},"required":false,"name":"barcode","in":"query"},{"schema":{"type":"string","enum":["scan","ocr"]},"required":false,"name":"barcodeSource","in":"query"},{"schema":{"type":"string"},"required":false,"name":"sizeLabel","in":"query"}],"responses":{"200":{"description":"Lookup result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SkuLookup"}}}},"400":{"description":"Neither sku nor barcode given","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/locate":{"get":{"tags":["admin/boxes"],"summary":"Find every unit of a SKU and its current box","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"},{"schema":{"type":"string"},"required":true,"name":"sku","in":"query"}],"responses":{"200":{"description":"Units of this SKU and where they are","content":{"application/json":{"schema":{"type":"object","properties":{"units":{"type":"array","items":{"$ref":"#/components/schemas/LocateRow"}}},"required":["units"]}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/boxes/{boxId}":{"get":{"tags":["admin/boxes"],"summary":"Box contents: what's inside + what's allocated but not yet in","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"boxId","in":"path"}],"responses":{"200":{"description":"Box contents","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoxContents"}}}},"404":{"description":"Box not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/boxes/{boxId}/confirm":{"post":{"tags":["admin/boxes"],"summary":"Confirm an allocated item is physically in the box","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"boxId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"itemId":{"type":"string"}},"required":["itemId"]}}}},"responses":{"200":{"description":"Confirmed","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}},"required":["ok"]}}}}}}},"/admin/intake/{id}/box":{"post":{"tags":["admin/intake"],"summary":"Assign and/or confirm an item's storage box (Boxing stage)","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"boxId":{"type":"string"},"confirm":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Updated row","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntakeRow"}}}},"404":{"description":"Item not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"409":{"description":"Not boxable, or no box has room","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/boxes":{"get":{"tags":["admin/boxes"],"summary":"List / search a tenant's storage boxes (for label printing)","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenant","in":"query"},{"schema":{"type":"string"},"required":false,"name":"q","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":500},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Boxes, newest first","content":{"application/json":{"schema":{"type":"object","properties":{"boxes":{"type":"array","items":{"$ref":"#/components/schemas/BoxSummary"}}},"required":["boxes"]}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}},"post":{"tags":["admin/boxes"],"summary":"Register a new empty box so its label can be pre-printed","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tenant":{"type":"string"},"zone":{"type":"string"},"warehouseId":{"type":"string"},"label":{"type":"string"}},"required":["tenant"]}}}},"responses":{"200":{"description":"Box created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoxSummary"}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/boxes/{boxId}/qr":{"get":{"tags":["admin/boxes"],"summary":"Printable QR (SVG) encoding the box's mobile page URL","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"boxId","in":"path"},{"schema":{"type":"string"},"required":false,"name":"origin","in":"query"}],"responses":{"200":{"description":"QR SVG + label","content":{"application/json":{"schema":{"type":"object","properties":{"qrSvg":{"type":"string"},"label":{"type":"string"},"zone":{"type":"string"},"url":{"type":"string"},"brand":{"type":"string"}},"required":["qrSvg","label","zone","url","brand"]}}}},"404":{"description":"Box not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tag-read":{"post":{"tags":["admin/intake"],"summary":"OCR a hangtag photo for brand/size/barcode/sku (Gemini)","security":[{"bearerAuth":[]}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"image":{"nullable":true}}}}}},"responses":{"200":{"description":"Tag read","content":{"application/json":{"schema":{"type":"object","properties":{"brand":{"type":"string","nullable":true},"size":{"type":"string","nullable":true},"barcode":{"type":"string","nullable":true},"sku":{"type":"string","nullable":true},"tag_visible":{"type":"boolean"},"raw_text":{"type":"string"},"read_status":{"type":"string","enum":["ok","unavailable"]},"tag_code":{"type":"string","nullable":true}},"required":["brand","size","barcode","sku","tag_visible","raw_text","read_status","tag_code"]}}}},"400":{"description":"Missing image","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/label-detect":{"post":{"tags":["admin/intake"],"summary":"Detect the shipping-label bounding box on a page (Gemini)","security":[{"bearerAuth":[]}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"image":{"nullable":true}}}}}},"responses":{"200":{"description":"Label bounding box (0-1000 normalised, top-left origin)","content":{"application/json":{"schema":{"type":"object","properties":{"found":{"type":"boolean"},"xmin":{"type":"number"},"ymin":{"type":"number"},"xmax":{"type":"number"},"ymax":{"type":"number"}},"required":["found","xmin","ymin","xmax","ymax"]}}}},"400":{"description":"Missing image","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/channel-image-rules":{"get":{"tags":["admin/intake"],"summary":"Get a tenant's per-channel image-selection rules","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"}],"responses":{"200":{"description":"Rules","content":{"application/json":{"schema":{"type":"object","properties":{"vinted":{"type":"string"},"ebay":{"type":"string"}}}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}},"patch":{"tags":["admin/intake"],"summary":"Update a tenant's per-channel image-selection rules","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"vinted":{"type":"string"},"ebay":{"type":"string"}}}}}},"responses":{"200":{"description":"Updated rules","content":{"application/json":{"schema":{"type":"object","properties":{"vinted":{"type":"string"},"ebay":{"type":"string"}}}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/ebay-channel":{"get":{"tags":["admin/intake"],"summary":"Get a tenant's eBay seller account + the configured accounts","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"}],"responses":{"200":{"description":"Channel","content":{"application/json":{"schema":{"type":"object","properties":{"ebayChannel":{"type":"string"},"available":{"type":"array","items":{"type":"string"}}},"required":["ebayChannel","available"]}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}},"patch":{"tags":["admin/intake"],"summary":"Set which eBay seller account a tenant publishes to","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"ebayChannel":{"type":"string"}},"required":["ebayChannel"]}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"ebayChannel":{"type":"string"},"available":{"type":"array","items":{"type":"string"}}},"required":["ebayChannel","available"]}}}},"400":{"description":"Unknown channel","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/ebay/channels":{"get":{"tags":["admin/intake"],"summary":"List the configured eBay seller accounts","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Configured accounts","content":{"application/json":{"schema":{"type":"object","properties":{"channels":{"type":"array","items":{"type":"string"}}},"required":["channels"]}}}}}}},"/admin/tenants/{tenantId}/intake":{"post":{"tags":["admin/intake"],"summary":"Create a new warehouse intake from a photo upload","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"image":{"nullable":true},"skipVision":{"type":"string"},"tagOnly":{"type":"string"},"damageTags":{"type":"string"},"damageNotes":{"type":"string"},"triageGrade":{"type":"string"},"bucket":{"type":"string"},"triageReason":{"type":"string"}}}}}},"responses":{"200":{"description":"Intake row created and enqueued","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"]}}}},"400":{"description":"Bad request (e.g. missing image field)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/manual-stock/import":{"post":{"tags":["admin/intake"],"summary":"Register manual stock from a CSV file","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"nullable":true},"csv":{"type":"string"},"warehouseId":{"type":"string"},"provider":{"type":"string"}},"required":["warehouseId"]}}}},"responses":{"200":{"description":"Manual stock import result","content":{"application/json":{"schema":{"type":"object","properties":{"provider":{"type":"string"},"tenantId":{"type":"string"},"warehouseId":{"type":"string"},"sourceRows":{"type":"integer"},"totalUnits":{"type":"integer"},"created":{"type":"integer"},"skippedDuplicate":{"type":"integer"},"failed":{"type":"integer"},"rows":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"status":{"type":"string","enum":["created"]},"externalId":{"type":"string"},"intakeId":{"type":"string"}},"required":["status","externalId","intakeId"]},{"type":"object","properties":{"status":{"type":"string","enum":["skipped_duplicate"]},"externalId":{"type":"string"}},"required":["status","externalId"]},{"type":"object","properties":{"status":{"type":"string","enum":["failed"]},"externalId":{"type":"string"},"reason":{"type":"string"}},"required":["status","externalId","reason"]}]}}},"required":["provider","tenantId","warehouseId","sourceRows","totalUnits","created","skippedDuplicate","failed","rows"]}}}},"400":{"description":"Invalid CSV or import options","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Tenant or warehouse not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/manual-stock/photos":{"post":{"tags":["admin/intake"],"summary":"Backfill manual-stock item photos from verified image URLs","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"provider":{"type":"string"},"products":{"type":"array","items":{"type":"object","properties":{"productId":{"type":"string","minLength":1},"variantId":{"type":"string","nullable":true,"minLength":1},"sku":{"type":"string","nullable":true,"minLength":1},"intakeIds":{"type":"array","items":{"type":"string","minLength":1},"maxItems":100},"sourcePageUrl":{"type":"string","nullable":true,"format":"uri"},"imageUrls":{"type":"array","items":{"type":"string","format":"uri"},"minItems":1,"maxItems":8},"kinds":{"type":"array","items":{"type":"string","enum":["garment_front","garment_back","garment_detail","flatlay","studio","on_model"]},"maxItems":8}},"required":["productId","imageUrls"]},"minItems":1,"maxItems":40},"statuses":{"type":"array","items":{"type":"string","enum":["processing","needs_review","ready","needs_work","listed","sold","failed"]},"minItems":1,"maxItems":4},"attachLimit":{"type":"integer","minimum":0,"maximum":100},"force":{"type":"boolean"},"dryRun":{"type":"boolean"},"deferEnhancement":{"type":"boolean"}},"required":["products"],"additionalProperties":false}}}},"responses":{"200":{"description":"Manual stock photo backfill result","content":{"application/json":{"schema":{"type":"object","properties":{"tenantId":{"type":"string"},"provider":{"type":"string"},"dryRun":{"type":"boolean"},"force":{"type":"boolean"},"attachLimit":{"type":"integer"},"products":{"type":"array","items":{"type":"object","properties":{"productId":{"type":"string"},"variantId":{"type":"string","nullable":true},"sku":{"type":"string","nullable":true},"sourcePageUrl":{"type":"string","nullable":true},"imageUrls":{"type":"array","items":{"type":"string"}},"fetchedImages":{"type":"integer"},"ingested":{"type":"integer"},"libraryPhotos":{"type":"integer"},"selectedRows":{"type":"integer"},"attachedRows":{"type":"integer"},"skippedRows":{"type":"integer"},"skippedReasons":{"type":"object","additionalProperties":{"type":"integer"}},"batchMayHaveMore":{"type":"boolean"},"error":{"type":"string","nullable":true}},"required":["productId","variantId","sku","sourcePageUrl","imageUrls","fetchedImages","ingested","libraryPhotos","selectedRows","attachedRows","skippedRows","skippedReasons","batchMayHaveMore","error"]}}},"required":["tenantId","provider","dryRun","force","attachLimit","products"]}}}},"400":{"description":"Invalid photo backfill request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/intake/import":{"post":{"tags":["admin/intake"],"summary":"Bulk import intake items from a provider feed (generic JSON by default)","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"provider":{"type":"string"},"payload":{"nullable":true}},"additionalProperties":false}}}},"responses":{"200":{"description":"Import results per row","content":{"application/json":{"schema":{"type":"object","properties":{"provider":{"type":"string"},"tenantId":{"type":"string"},"created":{"type":"integer"},"skippedDuplicate":{"type":"integer"},"skippedNoImages":{"type":"integer"},"failed":{"type":"integer"},"rows":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"status":{"type":"string","enum":["created"]},"externalId":{"type":"string"},"intakeId":{"type":"string"}},"required":["status","externalId","intakeId"]},{"type":"object","properties":{"status":{"type":"string","enum":["skipped_duplicate"]},"externalId":{"type":"string"}},"required":["status","externalId"]},{"type":"object","properties":{"status":{"type":"string","enum":["skipped_no_images"]},"externalId":{"type":"string"}},"required":["status","externalId"]},{"type":"object","properties":{"status":{"type":"string","enum":["failed"]},"externalId":{"type":"string"},"reason":{"type":"string"}},"required":["status","externalId","reason"]}]}}},"required":["provider","tenantId","created","skippedDuplicate","skippedNoImages","failed","rows"]}}}},"400":{"description":"Unknown provider OR adapter rejected the payload shape","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/intake":{"get":{"tags":["admin/intake"],"summary":"List intake rows across tenants (newest first)","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Filter to a single tenant (id, handle, or domain)"},"required":false,"description":"Filter to a single tenant (id, handle, or domain)","name":"tenant","in":"query"},{"schema":{"type":"string","description":"Comma-separated status filter, e.g. needs_review,ready"},"required":false,"description":"Comma-separated status filter, e.g. needs_review,ready","name":"status","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":2000,"default":50},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Filter to a warehouse id"},"required":false,"description":"Filter to a warehouse id","name":"warehouse","in":"query"}],"responses":{"200":{"description":"Filtered list","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/IntakeRow"}}},"required":["items"]}}}}}}},"/admin/intake/{id}":{"get":{"tags":["admin/intake"],"summary":"Get a single intake row","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Row","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntakeRow"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}},"patch":{"tags":["admin/intake"],"summary":"Update operator overrides on an intake row","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"selectedVariantId":{"type":"string","nullable":true},"matchProductId":{"type":"string","nullable":true},"matchProductTitle":{"type":"string","nullable":true},"matchProductHandle":{"type":"string","nullable":true},"price":{"type":"string","nullable":true},"condition":{"type":"string","nullable":true,"enum":["New with tags","New without tags","Very good","Good","Satisfactory",null]},"deleteImageKey":{"type":"string"},"extraImageKeys":{"type":"array","nullable":true,"items":{"type":"string"}},"imageOrder":{"type":"array","items":{"type":"string"}},"tagDetectedSize":{"type":"string","nullable":true},"triageGrade":{"type":"string","enum":["A1","A2","B1","B2","C","D"]},"bucket":{"type":"string","enum":["A1","A2","B1","B2","C","D"]},"triageReason":{"type":"string","nullable":true},"grade":{"type":"string","nullable":true,"enum":["A1","A2","B1","B2","C","D","A","B","C1","C2",null]},"gradeSource":{"type":"string","nullable":true,"enum":["ai","operator",null]},"damageTags":{"type":"array","items":{"type":"string"}},"damageNotes":{"type":"string","nullable":true},"rrpPence":{"type":"integer","nullable":true},"categorySnapshot":{"type":"string","nullable":true},"skuSnapshot":{"type":"string","nullable":true},"mobileIdentityRequired":{"type":"boolean"},"titleOverride":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"workType":{"type":"string","nullable":true,"enum":["cleaning","repair","hold",null]},"workState":{"type":"string","nullable":true,"enum":["waiting","in_progress","done",null]},"photoSource":{"type":"string","enum":["captured","reused","catalog","pending"]},"status":{"type":"string","enum":["processing","needs_review","ready","needs_work","listed","sold","failed"]}}}}}},"responses":{"200":{"description":"Updated row","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntakeRow"}}}},"400":{"description":"Invalid photo update","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}},"delete":{"tags":["admin/intake"],"summary":"Discard an intake row (and its R2 photo)","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"}},"required":["deleted"]}}}}}}},"/admin/intake/{id}/renormalise":{"post":{"tags":["admin/intake"],"summary":"Re-run the multi-channel normaliser for one intake row","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Row with refreshed normalised_payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntakeRow"}}}},"404":{"description":"Row not found or no matched product","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"502":{"description":"Normaliser unavailable (vision down / Shopify lookup failed)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/intake/{id}/complete-work":{"post":{"tags":["admin/intake"],"summary":"Mark a needs_work item's cleaning/repair as done and return it to the listing queue","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Row back at status='ready'","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntakeRow"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"409":{"description":"Row isn't in the work queue, or is a hold item (needs a manager decision instead)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/product-photos":{"post":{"tags":["admin/intake"],"summary":"Upload product photos into the SKU library (and optionally attach to an item)","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"productId":{"type":"string"},"image":{"nullable":true},"imageUrl":{"type":"string"},"sku":{"type":"string"},"intakeItemId":{"type":"string"}},"required":["productId"]}}}},"responses":{"200":{"description":"Photos ingested (+ optionally the refreshed item row)","content":{"application/json":{"schema":{"type":"object","properties":{"ingested":{"type":"integer"},"attachedToItem":{"type":"boolean"},"item":{"allOf":[{"$ref":"#/components/schemas/IntakeRow"},{"nullable":true}]}},"required":["ingested","attachedToItem","item"]}}}},"400":{"description":"Missing productId or image","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/intake/backfill-tag-matches":{"post":{"tags":["admin/intake"],"summary":"Re-read saved tag photos for unmatched registrations and resolve catalogue matches","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":false,"name":"tenant","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","enum":["1","true","yes"]},"required":false,"name":"dryRun","in":"query"}],"responses":{"200":{"description":"Backfill batch result","content":{"application/json":{"schema":{"type":"object","properties":{"processed":{"type":"number"},"matched":{"type":"number"},"unresolved":{"type":"number"},"failed":{"type":"number"},"dryRun":{"type":"boolean"},"results":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["matched","unresolved","failed","dry_run_match"]},"productId":{"type":"string","nullable":true},"variantId":{"type":"string","nullable":true},"source":{"type":"string","enum":["barcode","sku"]},"sku":{"type":"string","nullable":true},"barcode":{"type":"string","nullable":true},"reason":{"type":"string"}},"required":["id","status"]}}},"required":["processed","matched","unresolved","failed","dryRun","results"]}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/intake/backfill-library":{"post":{"tags":["admin/intake"],"summary":"Seed product_photos from existing reviewed intake rows (idempotent, cursor-batched)","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":false,"name":"tenant","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"required":false,"name":"limit","in":"query"},{"schema":{"type":"integer","nullable":true,"description":"Unix-seconds component of a prior call's nextCursor"},"required":false,"description":"Unix-seconds component of a prior call's nextCursor","name":"afterUploadedAt","in":"query"},{"schema":{"type":"string","description":"Row-id component of a prior call's nextCursor (tie-break)"},"required":false,"description":"Row-id component of a prior call's nextCursor (tie-break)","name":"afterId","in":"query"}],"responses":{"200":{"description":"Batch result + cursor for the next call","content":{"application/json":{"schema":{"type":"object","properties":{"processedRows":{"type":"integer"},"ingestedPhotos":{"type":"integer"},"nextCursor":{"type":"object","nullable":true,"properties":{"uploadedAt":{"type":"integer"},"id":{"type":"string"}},"required":["uploadedAt","id"]}},"required":["processedRows","ingestedPhotos","nextCursor"]}}}}}}},"/admin/intake/backfill-photo-enhancements":{"post":{"tags":["admin/intake"],"summary":"Enhance existing SKU-library product photos and refresh reused item copies","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":false,"name":"tenant","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":50,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"integer","nullable":true,"description":"Product-photo cursor unix-seconds component"},"required":false,"description":"Product-photo cursor unix-seconds component","name":"afterCreatedAt","in":"query"},{"schema":{"type":"string","description":"Product-photo cursor id component"},"required":false,"description":"Product-photo cursor id component","name":"afterId","in":"query"},{"schema":{"type":"string","description":"Defaults on. Set to false/0/off/no to skip refreshing reused intake copies."},"required":false,"description":"Defaults on. Set to false/0/off/no to skip refreshing reused intake copies.","name":"refreshReused","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"required":false,"name":"refreshLimit","in":"query"},{"schema":{"type":"integer","nullable":true,"description":"Reused-intake cursor unix-seconds component"},"required":false,"description":"Reused-intake cursor unix-seconds component","name":"afterUploadedAt","in":"query"},{"schema":{"type":"string","description":"Reused-intake cursor id component"},"required":false,"description":"Reused-intake cursor id component","name":"afterIntakeId","in":"query"}],"responses":{"200":{"description":"Batch result. Repeat with returned cursors until both are null.","content":{"application/json":{"schema":{"type":"object","properties":{"library":{"type":"object","properties":{"processedRows":{"type":"integer"},"enhancedPhotos":{"type":"integer"},"skippedAlreadyEnhanced":{"type":"integer"},"skippedManualStock":{"type":"integer"},"skippedNonListing":{"type":"integer"},"missingObjects":{"type":"integer"},"failed":{"type":"integer"},"nextCursor":{"type":"object","nullable":true,"properties":{"createdAt":{"type":"integer"},"id":{"type":"string"}},"required":["createdAt","id"]}},"required":["processedRows","enhancedPhotos","skippedAlreadyEnhanced","skippedManualStock","skippedNonListing","missingObjects","failed","nextCursor"]},"reused":{"type":"object","nullable":true,"properties":{"processedRows":{"type":"integer"},"refreshedRows":{"type":"integer"},"failed":{"type":"integer"},"nextCursor":{"type":"object","nullable":true,"properties":{"uploadedAt":{"type":"integer"},"id":{"type":"string"}},"required":["uploadedAt","id"]}},"required":["processedRows","refreshedRows","failed","nextCursor"]}},"required":["library","reused"]}}}}}}},"/admin/intake/{id}/outcome":{"post":{"tags":["admin/intake"],"summary":"Record an item's terminal outcome (sold / donated / recycled / unsold)","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["sold","donated","recycled","unsold"]},"channel":{"type":"string","nullable":true,"enum":["shopify","vinted","ebay","donation","recycle",null]},"soldPricePence":{"type":"integer","nullable":true,"minimum":0},"currency":{"type":"string"},"soldAt":{"type":"string","nullable":true,"format":"date-time"},"buyerCountry":{"type":"string","nullable":true},"buyerRegion":{"type":"string","nullable":true}},"required":["outcome"]}}}},"responses":{"200":{"description":"Outcome recorded (carbon computed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ItemOutcome"}}}},"404":{"description":"Intake item not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}},"get":{"tags":["admin/intake"],"summary":"Get an item's recorded outcome","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Recorded outcome","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ItemOutcome"}}}},"404":{"description":"No outcome recorded for this item","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/capture/context":{"get":{"tags":["capture"],"summary":"Resolve a warehouse capture token to its label + allowed tenants","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Token context","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CaptureContext"}}}},"401":{"description":"Missing or invalid capture token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/capture/identity-queue":{"get":{"tags":["capture"],"summary":"List unresolved identity work for this capture location","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Unresolved Units for the token's warehouse and tenants","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"tenantId":{"type":"string"},"uploadedAt":{"type":"string"},"state":{"type":"string","enum":["processing","candidates","no_match"]},"candidateCount":{"type":"number"},"evidenceUrl":{"type":"string","nullable":true},"label":{"type":"string","nullable":true},"tagOnly":{"type":"boolean"},"grade":{"type":"string","nullable":true}},"required":["id","tenantId","uploadedAt","state","candidateCount","evidenceUrl","label","tagOnly","grade"]}}},"required":["items"]}}}},"401":{"description":"Missing or invalid capture token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/capture/intake":{"post":{"tags":["capture"],"summary":"Submit warehouse intake photos for one tenant via a capture token","security":[{"bearerAuth":[]}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"tenantId":{"type":"string"},"image":{"nullable":true},"skipVision":{"type":"string"},"tagOnly":{"type":"string"},"damageTags":{"type":"string"},"damageNotes":{"type":"string"},"triageGrade":{"type":"string"},"bucket":{"type":"string"},"triageReason":{"type":"string"},"tagVisible":{"type":"string"}},"required":["tenantId"]}}}},"responses":{"200":{"description":"Intake row created and enqueued","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"box":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"label":{"type":"string"},"zone":{"type":"string"}},"required":["id","label","zone"]}},"required":["id"]}}}},"400":{"description":"Bad request — missing image, missing tenantId, or token lacks access to that tenant","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Missing or invalid capture token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"409":{"description":"Idempotency key was already used for another Unit","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/capture/intake/{id}":{"get":{"tags":["capture"],"summary":"Poll a phone-only image-recognition result","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Recognition state and hydrated candidates","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"state":{"type":"string","enum":["processing","candidates","selected","no_match"]},"candidates":{"type":"array","items":{"type":"object","properties":{"productId":{"type":"string"},"title":{"type":"string"},"imageUrl":{"type":"string","nullable":true},"score":{"type":"number"},"suggestedVariantId":{"type":"string","nullable":true},"variants":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"sku":{"type":"string","minLength":1},"price":{"type":"string"},"selectedOptions":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"value":{"type":"string"}},"required":["name","value"]}},"imageUrl":{"type":"string","nullable":true}},"required":["id","sku","price","selectedOptions","imageUrl"]}}},"required":["productId","title","imageUrl","score","suggestedVariantId","variants"]}},"catalogueAvailable":{"type":"boolean"},"selected":{"type":"object","nullable":true,"properties":{"productId":{"type":"string"},"variantId":{"type":"string"},"productTitle":{"type":"string","nullable":true}},"required":["productId","variantId","productTitle"]}},"required":["id","state","candidates","catalogueAvailable","selected"]}}}},"401":{"description":"Missing or invalid capture token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Unit not found or outside this token's tenants","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/capture/intake/{id}/catalogue-search":{"get":{"tags":["capture"],"summary":"Search the tenant catalogue for unresolved phone identity","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","minLength":2,"maxLength":100},"required":true,"name":"q","in":"query"}],"responses":{"200":{"description":"Catalogue Products available for human selection","content":{"application/json":{"schema":{"type":"object","properties":{"candidates":{"type":"array","items":{"type":"object","properties":{"productId":{"type":"string"},"title":{"type":"string"},"imageUrl":{"type":"string","nullable":true},"score":{"type":"number"},"suggestedVariantId":{"type":"string","nullable":true},"variants":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"sku":{"type":"string","minLength":1},"price":{"type":"string"},"selectedOptions":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"value":{"type":"string"}},"required":["name","value"]}},"imageUrl":{"type":"string","nullable":true}},"required":["id","sku","price","selectedOptions","imageUrl"]}}},"required":["productId","title","imageUrl","score","suggestedVariantId","variants"]}}},"required":["candidates"]}}}},"401":{"description":"Missing or invalid capture token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Unit not found or not eligible for phone identity","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"503":{"description":"Catalogue search is temporarily unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/capture/intake/{id}/selection":{"patch":{"tags":["capture"],"summary":"Confirm a FashionSigLIP candidate on the warehouse phone","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"productId":{"type":"string"},"variantId":{"type":"string"},"source":{"type":"string","enum":["candidate","manual"],"default":"candidate"}},"required":["productId","variantId"]}}}},"responses":{"200":{"description":"Identity confirmed","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"state":{"type":"string","enum":["processing","candidates","selected","no_match"]},"candidates":{"type":"array","items":{"type":"object","properties":{"productId":{"type":"string"},"title":{"type":"string"},"imageUrl":{"type":"string","nullable":true},"score":{"type":"number"},"suggestedVariantId":{"type":"string","nullable":true},"variants":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"sku":{"type":"string","minLength":1},"price":{"type":"string"},"selectedOptions":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"value":{"type":"string"}},"required":["name","value"]}},"imageUrl":{"type":"string","nullable":true}},"required":["id","sku","price","selectedOptions","imageUrl"]}}},"required":["productId","title","imageUrl","score","suggestedVariantId","variants"]}},"catalogueAvailable":{"type":"boolean"},"selected":{"type":"object","nullable":true,"properties":{"productId":{"type":"string"},"variantId":{"type":"string"},"productTitle":{"type":"string","nullable":true}},"required":["productId","variantId","productTitle"]}},"required":["id","state","candidates","catalogueAvailable","selected"]}}}},"400":{"description":"Product or Variant is not a valid candidate","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Missing or invalid capture token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Unit not found or outside this token's tenants","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"409":{"description":"Recognition is still processing or already resolved","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"503":{"description":"Catalogue validation is temporarily unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/capture/register":{"post":{"tags":["capture"],"summary":"Register a warehouse item to inventory with no photo (tag-only identity)","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tenantId":{"type":"string"},"sku":{"type":"string"},"barcode":{"type":"string"},"barcodeSource":{"type":"string","enum":["scan","ocr"]},"brand":{"type":"string"},"sizeLabel":{"type":"string"},"triageGrade":{"type":"string","enum":["A1","A2","B1","B2","C","D"]},"bucket":{"type":"string","enum":["A1","A2","B1","B2","C","D"]},"triageReason":{"type":"string"},"damageTags":{"type":"array","items":{"type":"string"}},"damageNotes":{"type":"string"},"tagVisible":{"type":"boolean"},"suggestedGrade":{"type":"string","enum":["A1","A2","B1","B2","C","D"]},"suggestedGradeReasoning":{"type":"string"},"productName":{"type":"string"},"colour":{"type":"string"},"rawText":{"type":"string"}},"required":["tenantId"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"tenantId":{"type":"string"},"tagImage":{"nullable":true}},"required":["tenantId"]}}}},"responses":{"200":{"description":"Registration row created (needs photo)","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"matched":{"type":"boolean"},"mobileIdentityRequired":{"type":"boolean"},"productTitle":{"type":"string","nullable":true},"box":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"label":{"type":"string"},"zone":{"type":"string"}},"required":["id","label","zone"]}},"required":["id","matched","mobileIdentityRequired"]}}}},"400":{"description":"Bad request — missing tenantId or token lacks access to that tenant","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Missing or invalid capture token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"409":{"description":"Idempotency key was already used for another Unit","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/capture/grade-suggest":{"post":{"tags":["capture"],"summary":"Suggest a triage grade from operative-declared damage","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"damageTags":{"type":"array","items":{"type":"string"}},"damageNotes":{"type":"string"},"productTitle":{"type":"string"},"tagVisible":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Suggested grade","content":{"application/json":{"schema":{"type":"object","properties":{"grade":{"type":"string","enum":["A1","A2","B1","B2","C","D"]},"confidence":{"type":"string","enum":["high","medium","low"]},"reasoning":{"type":"string"},"source":{"type":"string","enum":["ai","rules"]}},"required":["grade","confidence","reasoning","source"]}}}},"401":{"description":"Missing or invalid capture token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/capture/photos":{"post":{"tags":["capture"],"summary":"Photograph already-triaged items: ingest garment photos + clear the Needs-Photo pile for that SKU","security":[{"bearerAuth":[]}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"tenantId":{"type":"string"},"image":{"nullable":true},"productId":{"type":"string"},"sku":{"type":"string"},"barcode":{"type":"string"},"barcodeSource":{"type":"string","enum":["scan","ocr"]},"sizeLabel":{"type":"string"},"brand":{"type":"string"},"productName":{"type":"string"},"colour":{"type":"string"},"rawText":{"type":"string"}},"required":["tenantId"]}}}},"responses":{"200":{"description":"Photos ingested + Needs-Photo rows cleared","content":{"application/json":{"schema":{"type":"object","properties":{"ingested":{"type":"number"},"attached":{"type":"number"},"productId":{"type":"string","nullable":true},"productTitle":{"type":"string","nullable":true}},"required":["ingested","attached","productId","productTitle"]}}}},"400":{"description":"Missing tenantId/image, token lacks tenant access, or the tag didn't resolve to a product","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Missing or invalid capture token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/capture/tag-read":{"post":{"tags":["capture"],"summary":"OCR a hangtag photo for brand/size/barcode/sku (Gemini)","security":[{"bearerAuth":[]}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"image":{"nullable":true}}}}}},"responses":{"200":{"description":"Tag read","content":{"application/json":{"schema":{"type":"object","properties":{"brand":{"type":"string","nullable":true},"size":{"type":"string","nullable":true},"barcode":{"type":"string","nullable":true},"sku":{"type":"string","nullable":true},"product_name":{"type":"string","nullable":true},"colour":{"type":"string","nullable":true},"tag_visible":{"type":"boolean"},"raw_text":{"type":"string"},"read_status":{"type":"string","enum":["ok","unavailable"]},"tag_code":{"type":"string","nullable":true}},"required":["brand","size","barcode","sku","product_name","colour","tag_visible","raw_text","read_status","tag_code"]}}}},"400":{"description":"Missing image","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Missing or invalid capture token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/capture/tag-code/{code}":{"get":{"tags":["capture"],"summary":"Resolve a scanned Birl stock-tag QR to its unit","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"code","in":"path"}],"responses":{"200":{"description":"The unit this tag belongs to","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"tenantId":{"type":"string"},"sku":{"type":"string","nullable":true},"size":{"type":"string","nullable":true},"status":{"type":"string"},"lookup":{"type":"object","nullable":true,"properties":{"known":{"type":"boolean"},"productId":{"type":"string","nullable":true},"variantId":{"type":"string","nullable":true},"variantSku":{"type":"string","nullable":true},"productTitle":{"type":"string","nullable":true},"libraryPhotos":{"type":"number"},"liveCount":{"type":"number"},"waitingCount":{"type":"number"},"variantLiveCount":{"type":"number"},"variantWaitingCount":{"type":"number"}},"required":["known","productId","variantId","variantSku","productTitle","libraryPhotos","liveCount","waitingCount","variantLiveCount","variantWaitingCount"]}},"required":["id","tenantId","sku","size","status","lookup"]}}}},"401":{"description":"Missing or invalid capture token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Unknown, ambiguous, or not-permitted tag code","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/capture/sku-lookup":{"get":{"tags":["capture"],"summary":"Resolve a scanned SKU/barcode to catalogue + photo library","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"query"},{"schema":{"type":"string"},"required":false,"name":"sku","in":"query"},{"schema":{"type":"string"},"required":false,"name":"barcode","in":"query"},{"schema":{"type":"string"},"required":false,"name":"sizeLabel","in":"query"},{"schema":{"type":"string","enum":["scan","ocr"]},"required":false,"name":"barcodeSource","in":"query"},{"schema":{"type":"string"},"required":false,"name":"brand","in":"query"},{"schema":{"type":"string"},"required":false,"name":"productName","in":"query"},{"schema":{"type":"string"},"required":false,"name":"colour","in":"query"},{"schema":{"type":"string"},"required":false,"name":"rawText","in":"query"}],"responses":{"200":{"description":"Lookup result","content":{"application/json":{"schema":{"type":"object","properties":{"known":{"type":"boolean"},"productId":{"type":"string","nullable":true},"variantId":{"type":"string","nullable":true},"variantSku":{"type":"string","nullable":true},"productTitle":{"type":"string","nullable":true},"libraryPhotos":{"type":"number"},"liveCount":{"type":"number"},"waitingCount":{"type":"number"},"variantLiveCount":{"type":"number"},"variantWaitingCount":{"type":"number"}},"required":["known","productId","variantId","variantSku","productTitle","libraryPhotos","liveCount","waitingCount","variantLiveCount","variantWaitingCount"]}}}},"400":{"description":"Missing label identity signals, or token lacks access to that tenant","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Missing or invalid capture token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/capture/box/{boxId}":{"get":{"tags":["capture"],"summary":"Box contents for the mobile QR page (capture token)","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"boxId","in":"path"}],"responses":{"200":{"description":"Box contents","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CaptureBoxContents"}}}},"401":{"description":"Missing or invalid capture token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Box not found or not permitted for this token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/capture/box/{boxId}/confirm":{"post":{"tags":["capture"],"summary":"Confirm an allocated item is in the box (capture token)","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"boxId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"itemId":{"type":"string"}},"required":["itemId"]}}}},"responses":{"200":{"description":"Confirmed","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}},"required":["ok"]}}}},"401":{"description":"Missing or invalid capture token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Box not found or not permitted for this token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/capture-tokens":{"post":{"tags":["admin/capture-tokens"],"summary":"Mint a new warehouse capture token (returns plaintext once)","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string","minLength":1,"maxLength":120},"tenantIds":{"type":"array","items":{"type":"string"},"minItems":1},"warehouseId":{"type":"string"},"captureOrigin":{"type":"string","format":"uri"},"createdBy":{"type":"string"}},"required":["label","tenantIds"]}}}},"responses":{"200":{"description":"Token minted. wireToken and qrSvg are ONLY shown here — store them now.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"publicId":{"type":"string"},"label":{"type":"string"},"isActive":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"lastUsedAt":{"type":"string","nullable":true,"format":"date-time"},"revokedAt":{"type":"string","nullable":true,"format":"date-time"},"revokedReason":{"type":"string","nullable":true},"warehouse":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]},"tenants":{"type":"array","items":{"$ref":"#/components/schemas/CaptureTokenTenantRef"}},"wireToken":{"type":"string"},"qrSvg":{"type":"string"}},"required":["id","publicId","label","isActive","createdAt","lastUsedAt","revokedAt","revokedReason","warehouse","tenants","wireToken","qrSvg"]}}}},"400":{"description":"One or more tenantIds invalid","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}},"get":{"tags":["admin/capture-tokens"],"summary":"List capture tokens","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Tokens","content":{"application/json":{"schema":{"type":"object","properties":{"tokens":{"type":"array","items":{"$ref":"#/components/schemas/CaptureTokenListItem"}}},"required":["tokens"]}}}}}}},"/admin/capture-tokens/{id}":{"get":{"tags":["admin/capture-tokens"],"summary":"Get one capture token","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CaptureTokenListItem"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}},"patch":{"tags":["admin/capture-tokens"],"summary":"Update capture token metadata","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string","minLength":1,"maxLength":120},"warehouseId":{"type":"string"}}}}}},"responses":{"200":{"description":"Updated token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CaptureTokenListItem"}}}},"400":{"description":"Invalid warehouse","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Token not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}},"delete":{"tags":["admin/capture-tokens"],"summary":"Revoke a capture token (soft delete + audit reason)","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}},"responses":{"200":{"description":"Revoked","content":{"application/json":{"schema":{"type":"object","properties":{"revoked":{"type":"boolean"}},"required":["revoked"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/capture-tokens/{id}/rotate":{"post":{"tags":["admin/capture-tokens"],"summary":"Rotate a token's secret (invalidates the old QR, returns a new one)","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"captureOrigin":{"type":"string","format":"uri"}}}}}},"responses":{"200":{"description":"New wireToken + new QR SVG (old token now invalid)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CaptureTokenSecret"}}}},"404":{"description":"Token not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/capture-tokens/{id}/qr":{"get":{"tags":["admin/capture-tokens"],"summary":"Re-render an existing token's QR without rotating it","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uri"},"required":false,"name":"captureOrigin","in":"query"}],"responses":{"200":{"description":"Existing wireToken + its QR SVG (unchanged token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CaptureTokenSecret"}}}},"404":{"description":"Token not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"409":{"description":"Token predates stored QR — rotate once to enable print","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/capture-tokens/{id}/tenants":{"post":{"tags":["admin/capture-tokens"],"summary":"Grant a token access to one more tenant","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tenantId":{"type":"string"}},"required":["tenantId"]}}}},"responses":{"200":{"description":"Updated token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CaptureTokenListItem"}}}},"404":{"description":"Token or tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/capture-tokens/{id}/tenants/{tenantId}":{"delete":{"tags":["admin/capture-tokens"],"summary":"Revoke a token's access to one tenant","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"}],"responses":{"200":{"description":"Updated token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CaptureTokenListItem"}}}},"404":{"description":"Token not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/warehouses":{"get":{"tags":["admin/warehouses"],"summary":"List stock warehouses","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Warehouse list","content":{"application/json":{"schema":{"type":"object","properties":{"warehouses":{"type":"array","items":{"$ref":"#/components/schemas/Warehouse"}}},"required":["warehouses"]}}}}}},"post":{"tags":["admin/warehouses"],"summary":"Create a stock warehouse","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120}},"required":["name"]}}}},"responses":{"200":{"description":"Created warehouse","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Warehouse"}}}}}}},"/admin/warehouses/{id}":{"patch":{"tags":["admin/warehouses"],"summary":"Update a stock warehouse","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120}}}}}},"responses":{"200":{"description":"Updated warehouse","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Warehouse"}}}},"404":{"description":"Warehouse not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/fulfilment":{"get":{"tags":["admin/fulfilment"],"summary":"List sold items grouped by fulfilment state","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Filter to a single tenant (id / handle / domain)"},"required":false,"description":"Filter to a single tenant (id / handle / domain)","name":"tenant","in":"query"},{"schema":{"type":"string","description":"Comma-separated fulfilment states. Defaults to pending,picked,packed."},"required":false,"description":"Comma-separated fulfilment states. Defaults to pending,picked,packed.","name":"state","in":"query"},{"schema":{"type":"string","description":"Filter to a warehouse id"},"required":false,"description":"Filter to a warehouse id","name":"warehouse","in":"query"},{"schema":{"type":"string","enum":["1","true"],"description":"When true, reconcile eBay rows against eBay fulfilment status before returning."},"required":false,"description":"When true, reconcile eBay rows against eBay fulfilment status before returning.","name":"syncEbay","in":"query"},{"schema":{"type":"string","enum":["awaiting","dispatched","refunded"]},"required":false,"name":"view","in":"query"},{"schema":{"type":"integer","nullable":true,"minimum":0,"maximum":10000,"default":0},"required":false,"name":"offset","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":500,"default":100},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Fulfilment rows","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/FulfilmentRow"}},"hasMore":{"type":"boolean"},"nextOffset":{"type":"integer","nullable":true},"totalOrders":{"type":"integer"},"liveErrors":{"type":"array","items":{"type":"object","properties":{"tenantId":{"type":"string"},"channel":{"type":"string"},"orderRef":{"type":"string","nullable":true},"error":{"type":"string"}},"required":["tenantId","channel","orderRef","error"]}}},"required":["items","hasMore","nextOffset","totalOrders","liveErrors"]}}}}}}},"/admin/fulfilment/{id}/state":{"post":{"tags":["admin/fulfilment"],"summary":"Transition fulfilment state (+ optional tracking)","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"state":{"type":"string","enum":["pending","picked","packed","dispatched","delivered","returned"]},"trackingNumber":{"type":"string","nullable":true},"trackingCarrier":{"type":"string","nullable":true}},"required":["state"]}}}},"responses":{"200":{"description":"Updated row","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FulfilmentTransition"}}}},"404":{"description":"Outcome not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"409":{"description":"Outcome changed or is no longer dispatchable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/fulfilment/order/dispatch":{"post":{"tags":["admin/fulfilment"],"summary":"Dispatch a whole order's units in one action (+ tracking)","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"outcomeIds":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":50},"trackingNumber":{"type":"string","nullable":true},"trackingCarrier":{"type":"string","nullable":true}},"required":["outcomeIds"]}}}},"responses":{"200":{"description":"Per-order dispatch results","content":{"application/json":{"schema":{"type":"object","properties":{"dispatch":{"type":"array","items":{"$ref":"#/components/schemas/DispatchStatus"}}},"required":["dispatch"]}}}},"404":{"description":"No matching outcomes","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"409":{"description":"An outcome changed or is no longer dispatchable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/fulfilment/order/label":{"post":{"tags":["admin/fulfilment"],"summary":"Buy the Evri Next Day shipping label (Shippo) for an order","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"outcomeIds":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":50}},"required":["outcomeIds"]}}}},"responses":{"200":{"description":"Label purchase result","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"labelUrl":{"type":"string","nullable":true},"detail":{"type":"string"},"trackingNumber":{"type":"string","nullable":true},"trackingCarrier":{"type":"string","nullable":true}},"required":["ok","labelUrl","detail","trackingNumber","trackingCarrier"]}}}},"404":{"description":"No matching outcomes","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/fulfilment/order/refund":{"post":{"tags":["admin/fulfilment"],"summary":"Refund an amount to the buyer's original payment method","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"outcomeId":{"type":"string"},"amountPence":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":1000000},"reason":{"type":"string","maxLength":500},"notify":{"type":"boolean","default":true}},"required":["outcomeId","amountPence"]}}}},"responses":{"200":{"description":"Refund result","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"refundId":{"type":"string","nullable":true},"error":{"type":"string","nullable":true},"alreadyRefundedPence":{"type":"number","nullable":true},"maxRefundablePence":{"type":"number","nullable":true}},"required":["ok","refundId","error"]}}}},"404":{"description":"Outcome not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/fulfilment/order/voucher":{"post":{"tags":["admin/fulfilment"],"summary":"Generate a goodwill discount code for the buyer","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"outcomeId":{"type":"string"},"amountPence":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":1000000},"expiresInDays":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":365}},"required":["outcomeId","amountPence"]}}}},"responses":{"200":{"description":"Voucher result","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"code":{"type":"string","nullable":true},"endsAt":{"type":"string","nullable":true},"error":{"type":"string","nullable":true}},"required":["ok","code","endsAt","error"]}}}},"404":{"description":"Outcome not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/fulfilment/{id}/address":{"get":{"tags":["admin/fulfilment"],"summary":"Resolve the shipping address for a sold item's label","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Resolved shipping address","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShipAddress"}}}},"404":{"description":"Outcome not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/fulfilment/sync-shopify":{"post":{"tags":["admin/fulfilment"],"summary":"Backfill dispatch state from Shopify fulfilments","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tenant":{"type":"string"},"limit":{"type":"integer","minimum":1,"maximum":1000}}}}}},"responses":{"200":{"description":"Per-tenant reconciliation summary","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"tenantId":{"type":"string"},"ordersChecked":{"type":"number"},"rowsUpdated":{"type":"number"},"webhookSubscribed":{"type":"boolean"},"error":{"type":"string","nullable":true}},"required":["tenantId","ordersChecked","rowsUpdated","webhookSubscribed","error"]}}},"required":["results"]}}}}}}},"/admin/fulfilment/reconcile-orders":{"post":{"tags":["admin/fulfilment"],"summary":"Re-ingest recent paid resale orders from Shopify","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tenant":{"type":"string"},"limit":{"type":"integer","minimum":1,"maximum":500}},"required":["tenant"]}}}},"responses":{"200":{"description":"Reconciliation summary","content":{"application/json":{"schema":{"type":"object","properties":{"tenantId":{"type":"string"},"ordersProcessed":{"type":"number"},"linesTotal":{"type":"number"},"linesMatched":{"type":"number"},"linesUnresolved":{"type":"number"}},"required":["tenantId","ordersProcessed","linesTotal","linesMatched","linesUnresolved"]}}}},"404":{"description":"Tenant not found / resale store not connected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/internal/publish-vinted":{"post":{"tags":["admin/vinted"],"summary":"Enqueue a Vinted publish/draft job","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VintedPublishRequest"}}}},"responses":{"200":{"description":"Job enqueued (or existing job updated)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VintedPublishResponse"}}}},"404":{"description":"Tenant or intake item not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"409":{"description":"Channel not enabled for tenant","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/integrations/vinted/jobs/next":{"get":{"tags":["admin/vinted"],"summary":"Claim (or peek) the next queued Vinted job","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","enum":["true","false"]},"required":false,"name":"claim","in":"query"},{"schema":{"type":"string","description":"Free-form id of the extension instance (chrome installId, hostname, …) for tracing."},"required":false,"description":"Free-form id of the extension instance (chrome installId, hostname, …) for tracing.","name":"claimedBy","in":"query"}],"responses":{"200":{"description":"Job returned","content":{"application/json":{"schema":{"type":"object","properties":{"job":{"$ref":"#/components/schemas/VintedJob"}},"required":["job"]}}}},"204":{"description":"No queued jobs"}}}},"/admin/integrations/vinted/jobs/{jobId}/result":{"post":{"tags":["admin/vinted"],"summary":"Report final result for a Vinted job","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"jobId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VintedJobResult"}}}},"responses":{"200":{"description":"Updated job","content":{"application/json":{"schema":{"type":"object","properties":{"job":{"$ref":"#/components/schemas/VintedJob"}},"required":["job"]}}}},"404":{"description":"Job not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/integrations/vinted/jobs":{"get":{"tags":["admin/vinted"],"summary":"List Vinted listings for an intake item","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"intakeItemId","in":"query"}],"responses":{"200":{"description":"Jobs for that intake item","content":{"application/json":{"schema":{"type":"object","properties":{"jobs":{"type":"array","items":{"$ref":"#/components/schemas/VintedJob"}}},"required":["jobs"]}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/internal/publish-renewed":{"post":{"tags":["admin/renewed"],"summary":"Publish an intake unit to the brand's own store (native Renewed)","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublishRenewedRequest"}}}},"responses":{"200":{"description":"Publish result (ok=false carries the sync error)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublishRenewedResponse"}}}},"404":{"description":"Tenant or intake item not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"409":{"description":"Tenant is not in native_brand_store mode, or the unit is unmatched","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/internal/publish-ebay":{"post":{"tags":["admin/ebay"],"summary":"Publish a listing to eBay (synchronous)","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EbayPublishRequest"}}}},"responses":{"200":{"description":"Listing created (status reflects final outcome)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EbayPublishResponse"}}}},"404":{"description":"Tenant or intake item not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"409":{"description":"Channel not enabled for tenant","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/internal/publish-ebay-group":{"post":{"tags":["admin/ebay"],"summary":"Publish a product's sizes as one multi-variation eBay listing","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EbayGroupPublishRequest"}}}},"responses":{"200":{"description":"Listing(s) created (path reflects group vs per-size)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EbayGroupPublishResponse"}}}},"404":{"description":"Tenant or intake item not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"409":{"description":"Channel not enabled, no product match, or no stock","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/internal/unpublish-ebay":{"post":{"tags":["admin/ebay"],"summary":"End an eBay listing (withdraw offer + drop local row)","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"intakeItemId":{"type":"string","minLength":1}},"required":["intakeItemId"]}}}},"responses":{"200":{"description":"Listing ended","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"withdrawn":{"type":"boolean"}},"required":["ok","withdrawn"]}}}},"404":{"description":"Tenant or listing not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"502":{"description":"eBay withdraw failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/internal/withdraw-ebay-group":{"post":{"tags":["admin/ebay"],"summary":"End a multi-variation eBay listing by group key","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"groupKey":{"type":"string","minLength":1},"channel":{"type":"string"}},"required":["groupKey"]}}}},"responses":{"200":{"description":"Group listing ended (withdrawn=false when already gone)","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"withdrawn":{"type":"boolean"}},"required":["ok","withdrawn"]}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"502":{"description":"eBay withdraw failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/internal/delete-ebay-inventory":{"post":{"tags":["admin/ebay"],"summary":"Delete an eBay inventory item (and its offers) by SKU","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sku":{"type":"string","minLength":1},"channel":{"type":"string"}},"required":["sku"]}}}},"responses":{"200":{"description":"Inventory item removed (deleted=false when absent)","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"deleted":{"type":"boolean"}},"required":["ok","deleted"]}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"502":{"description":"eBay delete failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/integrations/ebay/teardown-active":{"post":{"tags":["admin/ebay"],"summary":"End all of a brand's live eBay listings (dry-run by default)","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean"},"aliases":{"type":"array","items":{"type":"string"}},"maxPages":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":50},"excludeItemIds":{"type":"array","items":{"type":"string"}},"keepTracked":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Matched listings (and end results when dryRun=false)","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean"},"channel":{"type":"string"},"needles":{"type":"array","items":{"type":"string"}},"totalActive":{"type":"number"},"matched":{"type":"number"},"ended":{"type":"number"},"items":{"type":"array","items":{"type":"object","properties":{"itemId":{"type":"string"},"title":{"type":"string","nullable":true},"sku":{"type":"string","nullable":true},"pricePence":{"type":"number","nullable":true},"watchCount":{"type":"number"},"startTime":{"type":"string","nullable":true},"ended":{"type":"boolean"},"error":{"type":"string"}},"required":["itemId","title","sku","pricePence","watchCount","startTime"]}}},"required":["dryRun","channel","needles","totalActive","matched","ended","items"]}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/integrations/ebay/api-usage":{"get":{"tags":["admin/ebay"],"summary":"Trading API per-call usage vs daily limits","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"},{"schema":{"type":"string"},"required":false,"name":"channel","in":"query"}],"responses":{"200":{"description":"Per-call usage, highest daily usage first","content":{"application/json":{"schema":{"type":"object","properties":{"channel":{"type":"string"},"rules":{"type":"array","items":{"type":"object","properties":{"apiName":{"type":"string"},"resource":{"type":"string"},"used":{"type":"number"},"limit":{"type":"number"},"remaining":{"type":"number"},"reset":{"type":"string","nullable":true},"timeWindowSecs":{"type":"number"}},"required":["apiName","resource","used","limit","remaining","reset","timeWindowSecs"]}}},"required":["channel","rules"]}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/internal/revise-ebay-price":{"post":{"tags":["admin/ebay"],"summary":"Revise live eBay listing prices for intake items","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"intakeItemId":{"type":"string","minLength":1},"price":{"type":"string","pattern":"^\\d+(\\.\\d{1,2})?$"}},"required":["intakeItemId","price"]},"minItems":1,"maxItems":200}},"required":["items"]}}}},"responses":{"200":{"description":"Per-item revise results","content":{"application/json":{"schema":{"type":"object","properties":{"revised":{"type":"number"},"results":{"type":"array","items":{"type":"object","properties":{"intakeItemId":{"type":"string"},"sku":{"type":"string","nullable":true},"price":{"type":"string"},"revised":{"type":"boolean"},"error":{"type":"string"}},"required":["intakeItemId","sku","price","revised"]}}},"required":["revised","results"]}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/internal/revise-ebay-titles":{"post":{"tags":["admin/ebay"],"summary":"Rebuild + push SEO titles (with colour) to live eBay listings","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"intakeItemIds":{"type":"array","items":{"type":"string","minLength":1}}}}}}},"responses":{"200":{"description":"Per-item title revise results","content":{"application/json":{"schema":{"type":"object","properties":{"revised":{"type":"number"},"results":{"type":"array","items":{"type":"object","properties":{"intakeItemId":{"type":"string"},"title":{"type":"string"},"scope":{"type":"string","enum":["item","group"]},"revised":{"type":"boolean"},"error":{"type":"string"}},"required":["intakeItemId","title","scope","revised"]}}},"required":["revised","results"]}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/internal/revise-ebay-images":{"post":{"tags":["admin/ebay"],"summary":"Re-push current item photos to live eBay listings","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"intakeItemIds":{"type":"array","items":{"type":"string","minLength":1}}}}}}},"responses":{"200":{"description":"Per-listing image revise results","content":{"application/json":{"schema":{"type":"object","properties":{"revised":{"type":"number"},"results":{"type":"array","items":{"type":"object","properties":{"listing":{"type":"string"},"scope":{"type":"string","enum":["item","group"]},"images":{"type":"number"},"revised":{"type":"boolean"},"error":{"type":"string"}},"required":["listing","scope","images","revised"]}}},"required":["revised","results"]}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/integrations/ebay/jobs":{"get":{"tags":["admin/ebay"],"summary":"List eBay listings for an intake item","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"intakeItemId","in":"query"}],"responses":{"200":{"description":"Jobs for that intake item","content":{"application/json":{"schema":{"type":"object","properties":{"jobs":{"type":"array","items":{"$ref":"#/components/schemas/EbayJob"}}},"required":["jobs"]}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/integrations/ebay/backfill":{"post":{"tags":["admin/ebay"],"summary":"Backfill a brand's CIE data from eBay sold-order history","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean"},"sinceDays":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":720},"aliases":{"type":"array","items":{"type":"string"}},"maxItems":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":50}}}}}},"responses":{"200":{"description":"Backfill report / result","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean"},"tenantId":{"type":"string"},"shopHandle":{"type":"string"},"needles":{"type":"array","items":{"type":"string"}},"ordersScanned":{"type":"number"},"linesScanned":{"type":"number"},"matchedLines":{"type":"number"},"matchedSample":{"type":"array","items":{"type":"object","properties":{"legacyItemId":{"type":"string"},"sku":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"pricePence":{"type":"number"},"currency":{"type":"string"},"soldAt":{"type":"string"},"country":{"type":"string","nullable":true}},"required":["legacyItemId","sku","title","pricePence","currency","soldAt","country"]}},"unmatchedTitleSample":{"type":"array","items":{"type":"string"}},"created":{"type":"number"},"skippedDuplicate":{"type":"number"},"failed":{"type":"number"},"remaining":{"type":"number"},"note":{"type":"string"}},"required":["dryRun","tenantId","shopHandle","needles","ordersScanned","linesScanned","matchedLines"]}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/integrations/ebay/backfill/enrich":{"post":{"tags":["admin/ebay"],"summary":"Match imported eBay rows to the catalogue (names + RRP + category)","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean"},"sinceDays":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":720},"maxItems":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":200}}}}}},"responses":{"200":{"description":"Enrichment report / result","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean"},"tenantId":{"type":"string"},"catalogueSize":{"type":"number"},"candidates":{"type":"number"},"matched":{"type":"number"},"rrpFilled":{"type":"number"},"updated":{"type":"number"},"sample":{"type":"array","items":{"type":"object","properties":{"ebayTitle":{"type":"string"},"productTitle":{"type":"string"},"score":{"type":"number"},"rrpPence":{"type":"number","nullable":true}},"required":["ebayTitle","productTitle","score","rrpPence"]}},"unmatchedSample":{"type":"array","items":{"type":"string"}},"note":{"type":"string"}},"required":["dryRun","tenantId","catalogueSize","candidates","matched","rrpFilled","updated","sample","unmatchedSample"]}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/integrations/ebay/backfill/order-details":{"post":{"tags":["admin/ebay"],"summary":"Backfill eBay order ref and ship-to fields for ASC export","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean"},"sinceDays":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":720},"maxItems":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":500},"missingOnly":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Order-detail backfill result","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean"},"tenantId":{"type":"string"},"ordersScanned":{"type":"number"},"candidates":{"type":"number"},"matched":{"type":"number"},"updated":{"type":"number"},"skippedNoOrder":{"type":"number"},"sample":{"type":"array","items":{"type":"object","properties":{"intakeItemId":{"type":"string"},"legacyItemId":{"type":"string"},"orderRef":{"type":"string","nullable":true},"buyerName":{"type":"string","nullable":true},"postcode":{"type":"string","nullable":true},"country":{"type":"string","nullable":true}},"required":["intakeItemId","legacyItemId","orderRef","buyerName","postcode","country"]}},"note":{"type":"string"}},"required":["dryRun","tenantId","ordersScanned","candidates","matched","updated","skippedNoOrder","sample","note"]}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/integrations/ebay/backfill/link-listings":{"post":{"tags":["admin/ebay"],"summary":"Create eBay listing records for imported sales (dashboard link)","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"}],"responses":{"200":{"description":"Listing records ensured","content":{"application/json":{"schema":{"type":"object","properties":{"tenantId":{"type":"string"},"imported":{"type":"number"},"created":{"type":"number"},"alreadyLinked":{"type":"number"}},"required":["tenantId","imported","created","alreadyLinked"]}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/integrations/ebay/backfill/active":{"post":{"tags":["admin/ebay"],"summary":"Import a brand's current live eBay listings","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean"},"seller":{"type":"string"},"query":{"type":"string"},"maxItems":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":50}}}}}},"responses":{"200":{"description":"Active-listing import report / result","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean"},"tenantId":{"type":"string"},"seller":{"type":"string"},"query":{"type":"string"},"found":{"type":"number"},"matched":{"type":"number"},"created":{"type":"number"},"skippedDuplicate":{"type":"number"},"failed":{"type":"number"},"remaining":{"type":"number"},"sample":{"type":"array","items":{"type":"object","properties":{"legacyItemId":{"type":"string"},"title":{"type":"string"},"pricePence":{"type":"number","nullable":true}},"required":["legacyItemId","title","pricePence"]}},"note":{"type":"string"}},"required":["dryRun","tenantId","seller","query","found","matched","sample"]}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/integrations/ebay/backfill/enrich-imports":{"post":{"tags":["admin/ebay"],"summary":"Backfill price/photos/description onto imported live listings","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean"},"maxItems":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":25},"offset":{"type":"integer","minimum":0}}}}}},"responses":{"200":{"description":"Enrichment batch result","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean"},"tenantId":{"type":"string"},"total":{"type":"number"},"processed":{"type":"number"},"updatedPrice":{"type":"number"},"updatedPhotos":{"type":"number"},"updatedDescription":{"type":"number"},"failed":{"type":"number"},"offset":{"type":"number"},"nextOffset":{"type":"number"},"remaining":{"type":"number"},"hasMore":{"type":"boolean"},"note":{"type":"string"}},"required":["dryRun","tenantId","total","processed","updatedPrice","updatedPhotos","updatedDescription","failed","offset","nextOffset","remaining","hasMore"]}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/integrations/ebay/backfill/fix-dates":{"post":{"tags":["admin/ebay"],"summary":"Backdate eBay imports to their real listing/sale date","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean"},"maxItems":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":40},"offset":{"type":"integer","minimum":0}}}}}},"responses":{"200":{"description":"Date-fix batch result","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean"},"tenantId":{"type":"string"},"total":{"type":"number"},"processed":{"type":"number"},"updated":{"type":"number"},"noDate":{"type":"number"},"offset":{"type":"number"},"nextOffset":{"type":"number"},"remaining":{"type":"number"},"hasMore":{"type":"boolean"},"sample":{"type":"array","items":{"type":"object","properties":{"status":{"type":"string"},"source":{"type":"string"},"date":{"type":"string","nullable":true}},"required":["status","source","date"]}}},"required":["dryRun","tenantId","total","processed","updated","noDate","offset","nextOffset","remaining","hasMore","sample"]}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/integrations/shopify/backfill":{"post":{"tags":["admin/shopify"],"summary":"Backfill CIE rows from a tenant's resale Shopify store","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean"},"mode":{"type":"string","enum":["sold","listed"]},"cursor":{"type":"string","nullable":true},"maxItems":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":50},"productStatus":{"type":"string","enum":["active","any"]},"includeOutOfStock":{"type":"boolean"}},"required":["mode"]}}}},"responses":{"200":{"description":"Backfill batch result","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean"},"tenantId":{"type":"string"},"mode":{"type":"string","enum":["sold","listed"]},"resaleShopDomain":{"type":"string"},"totalInStore":{"type":"number","nullable":true},"created":{"type":"number"},"skippedDuplicate":{"type":"number"},"updatedDescriptions":{"type":"number"},"failed":{"type":"number"},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"sample":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"pricePence":{"type":"number","nullable":true},"soldAt":{"type":"string","nullable":true},"status":{"type":"string","nullable":true},"inventory":{"type":"number","nullable":true}},"required":["title","pricePence","soldAt"]}},"note":{"type":"string"}},"required":["dryRun","tenantId","mode","resaleShopDomain","totalInStore","created","skippedDuplicate","updatedDescriptions","failed","nextCursor","hasMore","sample"]}}}},"404":{"description":"Tenant not found / resale store not connected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/integrations/shopify/publish-draft":{"post":{"tags":["admin/shopify"],"summary":"Publish an imported resale-store draft to live","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"intakeItemId":{"type":"string"}},"required":["intakeItemId"]}}}},"responses":{"200":{"description":"Publish result","content":{"application/json":{"schema":{"type":"object","properties":{"published":{"type":"boolean"},"productUrl":{"type":"string"},"userErrors":{"type":"array","items":{"type":"string"}}},"required":["published","productUrl","userErrors"]}}}},"404":{"description":"Tenant / item not found, or no resale product","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/internal/vision/reindex":{"post":{"tags":["admin/vision"],"summary":"Index one page of the tenant's catalog into the vision service","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"seedLora":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Page result","content":{"application/json":{"schema":{"type":"object","properties":{"processedProducts":{"type":"number"},"indexedItems":{"type":"number"},"skippedItems":{"type":"number"},"failedItems":{"type":"number"},"hasNextPage":{"type":"boolean"},"nextCursor":{"type":"string","nullable":true},"complete":{"type":"boolean"}},"required":["processedProducts","indexedItems","skippedItems","failedItems","hasNextPage","nextCursor","complete"]}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"410":{"description":"Reindex cancelled by operator — dashboard should stop polling","content":{"application/json":{"schema":{"type":"object","properties":{"processedProducts":{"type":"number"},"indexedItems":{"type":"number"},"skippedItems":{"type":"number"},"failedItems":{"type":"number"},"hasNextPage":{"type":"boolean"},"nextCursor":{"type":"string","nullable":true},"complete":{"type":"boolean"}},"required":["processedProducts","indexedItems","skippedItems","failedItems","hasNextPage","nextCursor","complete"]}}}}}}},"/admin/tenants/{tenantId}/internal/vision/onboard-status":{"get":{"tags":["admin/vision"],"summary":"Unified vision onboarding state for one-click flow","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"}],"responses":{"200":{"description":"Onboard status","content":{"application/json":{"schema":{"type":"object","properties":{"tenantId":{"type":"string"},"shopHandle":{"type":"string"},"phase":{"type":"string","enum":["idle","normalising","indexing","training","ready","failed"]},"message":{"type":"string"},"vectorCount":{"type":"number","nullable":true},"visionIndexedAt":{"type":"string","nullable":true,"format":"date-time"},"loraVersion":{"type":"number","nullable":true},"loraEvalRecallAt1":{"type":"number","nullable":true},"loraTrainStatus":{"type":"string","nullable":true},"hasNormalisation":{"type":"boolean"},"error":{"type":"string","nullable":true}},"required":["tenantId","shopHandle","phase","message","vectorCount","visionIndexedAt","loraVersion","loraEvalRecallAt1","loraTrainStatus","hasNormalisation","error"]}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/internal/vision/reindex/cancel":{"post":{"tags":["admin/vision"],"summary":"Cancel a running vision reindex","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"}],"responses":{"200":{"description":"Cancellation flag set","content":{"application/json":{"schema":{"type":"object","properties":{"tenantId":{"type":"string"},"cancelled":{"type":"boolean"},"previousStatus":{"type":"string","nullable":true}},"required":["tenantId","cancelled","previousStatus"]}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/internal/vision/train/cancel":{"post":{"tags":["admin/vision"],"summary":"Cancel a queued/in-flight LoRA train (fall back to base model)","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"}],"responses":{"200":{"description":"Train status cleared","content":{"application/json":{"schema":{"type":"object","properties":{"tenantId":{"type":"string"},"cleared":{"type":"boolean"},"previousStatus":{"type":"string","nullable":true}},"required":["tenantId","cleared","previousStatus"]}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/internal/vision/status":{"get":{"tags":["admin/vision"],"summary":"Vision indexing status snapshot for a tenant","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"}],"responses":{"200":{"description":"Status","content":{"application/json":{"schema":{"type":"object","properties":{"tenantId":{"type":"string"},"shopHandle":{"type":"string"},"namespace":{"type":"string"},"visionIndexedAt":{"type":"string","nullable":true,"format":"date-time"},"visionLastFailedReason":{"type":"string","nullable":true},"vectorCount":{"type":"number","nullable":true}},"required":["tenantId","shopHandle","namespace","visionIndexedAt","visionLastFailedReason","vectorCount"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/internal/vision/lora/train":{"post":{"tags":["admin/vision"],"summary":"Trigger a per-tenant LoRA retrain","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"}],"responses":{"200":{"description":"Train queued","content":{"application/json":{"schema":{"type":"object","properties":{"runId":{"type":"string"},"status":{"type":"string"},"operationName":{"type":"string","nullable":true}},"required":["runId","status","operationName"]}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"409":{"description":"Train already in flight","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/internal/vision/train/poll":{"get":{"tags":["admin/vision"],"summary":"Local trainer agent — pull next queued job","responses":{"200":{"description":"Next queued job (or null when the queue is empty)","content":{"application/json":{"schema":{"type":"object","properties":{"job":{"type":"object","nullable":true,"properties":{"tenantId":{"type":"string"},"runId":{"type":"string"},"namespace":{"type":"string"},"activeSide":{"type":"string"},"incumbentLoraVersion":{"type":"string"},"incumbentEvalJson":{"type":"string"}},"required":["tenantId","runId","namespace","activeSide","incumbentLoraVersion","incumbentEvalJson"]}},"required":["job"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/vision/lora/result":{"post":{"tags":["admin/vision"],"summary":"Modal callback — record train outcome","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tenantId":{"type":"string"},"runId":{"type":"string"},"promoted":{"type":"boolean"},"reason":{"type":"string"},"newLoraVersion":{"type":"number"},"newAdapterR2Key":{"type":"string"},"newAdapterName":{"type":"string"},"newActiveSide":{"type":"string","enum":["a","b"]},"newCrossEncoderR2Key":{"type":"string","nullable":true},"newCrossEncoderName":{"type":"string","nullable":true},"evalReport":{"type":"object","properties":{"recall_at_1_clean":{"type":"number"},"recall_at_3_clean":{"type":"number"},"recall_at_10_clean":{"type":"number"},"recall_at_1_synth":{"type":"number"},"recall_at_3_synth":{"type":"number"},"recall_at_10_synth":{"type":"number"},"n_eval_queries":{"type":"number"},"n_corpus":{"type":"number"},"calibration_a":{"type":"number","nullable":true},"calibration_b":{"type":"number","nullable":true}},"required":["recall_at_1_clean","recall_at_3_clean","recall_at_10_clean","recall_at_1_synth","recall_at_3_synth","recall_at_10_synth","n_eval_queries","n_corpus"]},"reindex":{"type":"object","properties":{"indexed":{"type":"number"},"skipped":{"type":"number"},"failed":{"type":"number"}},"required":["indexed","skipped","failed"]},"trainSeconds":{"type":"number"}},"required":["tenantId","runId","promoted"]}}}},"responses":{"200":{"description":"Result recorded","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"accepted":{"type":"boolean"}},"required":["ok","accepted"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/internal/vision/lora/status":{"get":{"tags":["admin/vision"],"summary":"Read per-tenant LoRA state","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"}],"responses":{"200":{"description":"LoRA status","content":{"application/json":{"schema":{"type":"object","properties":{"tenantId":{"type":"string"},"activeNamespace":{"type":"string"},"loraVersion":{"type":"number","nullable":true},"loraR2Key":{"type":"string","nullable":true},"loraTrainedAt":{"type":"string","nullable":true,"format":"date-time"},"loraEvalRecallAt1":{"type":"number","nullable":true},"loraTrainStatus":{"type":"string","nullable":true},"loraLastFailedReason":{"type":"string","nullable":true},"loraTrainQueuedAt":{"type":"string","nullable":true,"format":"date-time"}},"required":["tenantId","activeNamespace","loraVersion","loraR2Key","loraTrainedAt","loraEvalRecallAt1","loraTrainStatus","loraLastFailedReason","loraTrainQueuedAt"]}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/onboard":{"post":{"tags":["admin/onboarding"],"summary":"Phase-1 onboarding: enqueue catalog normaliser run (async)","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"manualStripper":{"type":"string"}}}}}},"responses":{"200":{"description":"Onboard run queued","content":{"application/json":{"schema":{"type":"object","properties":{"tenantId":{"type":"string"},"runId":{"type":"string"},"status":{"type":"string"}},"required":["tenantId","runId","status"]}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"409":{"description":"Onboard run already in flight","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/onboard/cancel":{"post":{"tags":["admin/onboarding"],"summary":"Cancel a running onboard pipeline","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"}],"responses":{"200":{"description":"Cancellation flag set","content":{"application/json":{"schema":{"type":"object","properties":{"tenantId":{"type":"string"},"cancelled":{"type":"boolean"},"previousStatus":{"type":"string","nullable":true}},"required":["tenantId","cancelled","previousStatus"]}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/cie/report":{"get":{"tags":["cie"],"summary":"Circular Intelligence Engine report for one tenant","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"},{"schema":{"type":"string","description":"ISO date — lower bound on intake date. Defaults to all-time."},"required":false,"description":"ISO date — lower bound on intake date. Defaults to all-time.","name":"from","in":"query"},{"schema":{"type":"string","description":"ISO date — upper bound on intake date. Defaults to now."},"required":false,"description":"ISO date — upper bound on intake date. Defaults to now.","name":"to","in":"query"}],"responses":{"200":{"description":"Circular-performance report","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CieReport"}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/cie/recompute-carbon":{"post":{"tags":["cie"],"summary":"Recompute CO2-saved for all of a tenant's outcomes","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"}],"responses":{"200":{"description":"Number of outcomes recomputed","content":{"application/json":{"schema":{"type":"object","properties":{"recomputed":{"type":"integer"}},"required":["recomputed"]}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/stats/overview":{"get":{"tags":["admin/stats"],"summary":"Operator-wide throughput + commercial rollups across all tenants","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"ISO date — lower bound. Defaults to 30 days ago."},"required":false,"description":"ISO date — lower bound. Defaults to 30 days ago.","name":"from","in":"query"},{"schema":{"type":"string","description":"ISO date — upper bound. Defaults to now."},"required":false,"description":"ISO date — upper bound. Defaults to now.","name":"to","in":"query"}],"responses":{"200":{"description":"Throughput + commercial overview","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatsOverview"}}}}}}},"/admin/tenants/{tenantId}/routing/rules":{"get":{"tags":["routing"],"summary":"List a tenant's routing rules (priority order)","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"}],"responses":{"200":{"description":"Routing rules","content":{"application/json":{"schema":{"type":"object","properties":{"rules":{"type":"array","items":{"$ref":"#/components/schemas/RoutingRule"}}},"required":["rules"]}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}},"post":{"tags":["routing"],"summary":"Create a routing rule","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"priority":{"type":"integer"},"name":{"type":"string","minLength":1},"conditions":{"type":"object","properties":{"grade":{"type":"array","items":{"type":"string","enum":["A","B1","B2","C1","C2","D","B","C"]}},"categories":{"type":"array","items":{"type":"string"}},"damageTags":{"type":"array","items":{"type":"string"}},"minRrpPence":{"type":"integer"},"maxRrpPence":{"type":"integer"}}},"action":{"type":"object","properties":{"channel":{"type":"string","enum":["shopify","vinted","ebay","donation","recycle"]}},"required":["channel"]},"enabled":{"type":"boolean"}},"required":["priority","name","action"]}}}},"responses":{"200":{"description":"Created rule","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoutingRule"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/routing/rules/{ruleId}":{"patch":{"tags":["routing"],"summary":"Update a routing rule","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"},{"schema":{"type":"string"},"required":true,"name":"ruleId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"priority":{"type":"integer"},"name":{"type":"string","minLength":1},"conditions":{"type":"object","properties":{"grade":{"type":"array","items":{"type":"string","enum":["A","B1","B2","C1","C2","D","B","C"]}},"categories":{"type":"array","items":{"type":"string"}},"damageTags":{"type":"array","items":{"type":"string"}},"minRrpPence":{"type":"integer"},"maxRrpPence":{"type":"integer"}}},"action":{"type":"object","properties":{"channel":{"type":"string","enum":["shopify","vinted","ebay","donation","recycle"]}},"required":["channel"]},"enabled":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Updated rule","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoutingRule"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}},"delete":{"tags":["routing"],"summary":"Delete a routing rule","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"},{"schema":{"type":"string"},"required":true,"name":"ruleId","in":"path"}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"}},"required":["deleted"]}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/routing/seed-defaults":{"post":{"tags":["routing"],"summary":"Seed the default routing rule set (no-op if the tenant has rules)","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"}],"responses":{"200":{"description":"Number of rules seeded (0 when rules already exist)","content":{"application/json":{"schema":{"type":"object","properties":{"seeded":{"type":"integer"}},"required":["seeded"]}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/routing/suggest":{"get":{"tags":["routing"],"summary":"Suggest a channel for an item's condition attributes","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"},{"schema":{"type":"string","enum":["A","B1","B2","C1","C2","D","B","C"]},"required":false,"name":"grade","in":"query"},{"schema":{"type":"string"},"required":false,"name":"category","in":"query"},{"schema":{"type":"string","description":"Comma-separated damage tags"},"required":false,"description":"Comma-separated damage tags","name":"damageTags","in":"query"},{"schema":{"type":"integer","nullable":true},"required":false,"name":"rrpPence","in":"query"}],"responses":{"200":{"description":"Suggested channel, or null when no rule matches","content":{"application/json":{"schema":{"type":"object","properties":{"suggestion":{"type":"object","nullable":true,"properties":{"channel":{"type":"string","enum":["shopify","vinted","ebay","donation","recycle"]},"ruleId":{"type":"string"},"ruleName":{"type":"string"}},"required":["channel","ruleId","ruleName"]}},"required":["suggestion"]}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/pricing/automation":{"get":{"tags":["pricing"],"summary":"Whether the automatic daily pricing cron is enabled (global)","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Master-switch state","content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"}},"required":["enabled"]}}}}}},"put":{"tags":["pricing"],"summary":"Enable/disable the automatic daily pricing cron (global)","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"}},"required":["enabled"]}}}},"responses":{"200":{"description":"New master-switch state","content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"}},"required":["enabled"]}}}}}}},"/admin/tenants/{tenantId}/pricing/settings":{"get":{"tags":["pricing"],"summary":"Get a tenant's dynamic-pricing settings (null if never set)","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"}],"responses":{"200":{"description":"Settings, or null when the tenant hasn't configured any","content":{"application/json":{"schema":{"type":"object","properties":{"settings":{"$ref":"#/components/schemas/PricingSettings"}},"required":["settings"]}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}},"put":{"tags":["pricing"],"summary":"Create or update a tenant's dynamic-pricing settings","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"},"floorPercent":{"type":"integer","minimum":1,"maximum":95},"cooldownDays":{"type":"integer","minimum":0,"maximum":90},"priceEnding":{"type":"string","enum":["95","99","00","none"]},"ladder":{"type":"array","items":{"type":"object","properties":{"afterDays":{"type":"integer","minimum":0,"maximum":365},"minWatchers":{"type":"integer","nullable":true,"minimum":0},"dropPercent":{"type":"integer","minimum":1,"maximum":90},"applyMode":{"type":"string","enum":["auto","suggest"]}},"required":["afterDays","dropPercent","applyMode"]}}}}}}},"responses":{"200":{"description":"Saved settings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PricingSettings"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/pricing/changes":{"get":{"tags":["pricing"],"summary":"List price changes — suggestions awaiting approval, and history","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"},{"schema":{"type":"string","enum":["suggested","applied","rejected","failed"]},"required":false,"name":"status","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":200},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Price changes, newest first","content":{"application/json":{"schema":{"type":"object","properties":{"changes":{"type":"array","items":{"$ref":"#/components/schemas/PriceChange"}}},"required":["changes"]}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/pricing/changes/{changeId}/apply":{"post":{"tags":["pricing"],"summary":"Approve a suggested change — push the new price to eBay","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"},{"schema":{"type":"string"},"required":true,"name":"changeId","in":"path"}],"responses":{"200":{"description":"Apply result","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"reason":{"type":"string"}},"required":["ok"]}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/pricing/changes/{changeId}/reject":{"post":{"tags":["pricing"],"summary":"Dismiss a suggested change without touching eBay","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"},{"schema":{"type":"string"},"required":true,"name":"changeId","in":"path"}],"responses":{"200":{"description":"Reject result","content":{"application/json":{"schema":{"type":"object","properties":{"rejected":{"type":"boolean"}},"required":["rejected"]}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/pricing/listings":{"get":{"tags":["pricing"],"summary":"Latest engagement snapshot for the tenant's live listings","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"}],"responses":{"200":{"description":"Listing metrics, most-watched first","content":{"application/json":{"schema":{"type":"object","properties":{"listings":{"type":"array","items":{"$ref":"#/components/schemas/ListingMetric"}}},"required":["listings"]}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/pricing/listings/{intakeItemId}":{"get":{"tags":["pricing"],"summary":"Latest engagement snapshot for a single intake item","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"},{"schema":{"type":"string"},"required":true,"name":"intakeItemId","in":"path"}],"responses":{"200":{"description":"Latest metric for the item, or null","content":{"application/json":{"schema":{"type":"object","properties":{"metric":{"allOf":[{"$ref":"#/components/schemas/ListingMetric"},{"nullable":true}]}},"required":["metric"]}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/pricing/run":{"post":{"tags":["pricing"],"summary":"Run the dynamic-pricing evaluation now","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"}],"responses":{"200":{"description":"Run summary","content":{"application/json":{"schema":{"type":"object","properties":{"skipped":{"type":"string"},"evaluated":{"type":"integer"},"suggested":{"type":"integer"},"applied":{"type":"integer"},"unchanged":{"type":"integer"},"failed":{"type":"integer"}},"required":["evaluated","suggested","applied","unchanged","failed"]}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/inbox/conversations":{"get":{"tags":["admin/inbox"],"summary":"List inbox conversations for a tenant","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"},{"schema":{"type":"string","enum":["open","snoozed","closed"]},"required":false,"name":"status","in":"query"},{"schema":{"type":"string","enum":["ebay","vinted","shopify"]},"required":false,"name":"channel","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":200,"default":100},"required":false,"name":"limit","in":"query"},{"schema":{"type":"integer","nullable":true,"minimum":0,"default":0},"required":false,"name":"offset","in":"query"}],"responses":{"200":{"description":"Conversations, newest activity first","content":{"application/json":{"schema":{"type":"object","properties":{"conversations":{"type":"array","items":{"$ref":"#/components/schemas/Conversation"}}},"required":["conversations"]}}}}}}},"/admin/tenants/{tenantId}/inbox/conversations/{id}":{"get":{"tags":["admin/inbox"],"summary":"Get a conversation with its messages (marks it read)","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"},{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Conversation thread","content":{"application/json":{"schema":{"type":"object","properties":{"conversation":{"$ref":"#/components/schemas/Conversation"},"messages":{"type":"array","items":{"$ref":"#/components/schemas/InboxMessage"}}},"required":["conversation","messages"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/inbox/conversations/{id}/reply":{"post":{"tags":["admin/inbox"],"summary":"Reply to a conversation (passes the anti-spam send guard)","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"},{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string","minLength":1,"maxLength":2000}},"required":["body"]}}}},"responses":{"200":{"description":"Reply sent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InboxMessage"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"422":{"description":"Blocked by the send guard","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"reason":{"type":"string"},"detail":{"type":"string"},"violations":{"type":"array","items":{"type":"string"}}},"required":["error","reason"]}}}},"501":{"description":"Channel send not yet implemented","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"502":{"description":"Channel rejected the message","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/inbox/suppression":{"post":{"tags":["admin/inbox"],"summary":"Add a counterparty to the do-not-contact list","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"counterpartyId":{"type":"string","minLength":1},"channel":{"type":"string","enum":["ebay","vinted","shopify"]},"reason":{"type":"string"},"closeConversations":{"type":"boolean"}},"required":["counterpartyId"]}}}},"responses":{"200":{"description":"Suppressed","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}},"required":["ok"]}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/inbox/ingest":{"post":{"tags":["admin/inbox"],"summary":"Ingest normalised conversations pushed by the extension","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"conversations":{"type":"array","items":{"type":"object","properties":{"channel":{"type":"string","enum":["ebay","vinted","shopify"]},"externalThreadId":{"type":"string","minLength":1},"counterpartyId":{"type":"string","nullable":true},"counterpartyName":{"type":"string","nullable":true},"externalItemId":{"type":"string","nullable":true},"subject":{"type":"string","nullable":true},"eligibilityBasis":{"type":"string","enum":["buyer_initiated","question","order","offer","platform_offer"]},"lastMessageAt":{"type":"string","nullable":true,"format":"date-time"},"lastDirection":{"type":"string","nullable":true,"enum":["inbound","outbound",null]},"unread":{"type":"integer","minimum":0},"latestInboundText":{"type":"string","nullable":true}},"required":["channel","externalThreadId","counterpartyId","counterpartyName","externalItemId","subject","eligibilityBasis","lastMessageAt","lastDirection","unread","latestInboundText"]},"maxItems":500}},"required":["conversations"]}}}},"responses":{"200":{"description":"Ingest summary","content":{"application/json":{"schema":{"type":"object","properties":{"conversationsUpserted":{"type":"integer"},"skippedNoListing":{"type":"integer"}},"required":["conversationsUpserted","skippedNoListing"]}}}},"502":{"description":"Ingest failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/inbox/ebay/sync":{"post":{"tags":["admin/inbox"],"summary":"Deprecated no-op — eBay sync now runs in the extension","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","nullable":true},"required":false,"name":"hours","in":"query"}],"responses":{"200":{"description":"No-op result (extension does the syncing)","content":{"application/json":{"schema":{"type":"object","properties":{"scanned":{"type":"integer"},"ingested":{"type":"integer"},"skippedNoListing":{"type":"integer"}},"required":["scanned","ingested","skippedNoListing"]}}}}}}},"/admin/inbox/outbound/next":{"get":{"tags":["admin/inbox"],"summary":"Claim the next queued outbound message for the extension to send","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","enum":["ebay","vinted","shopify"],"default":"ebay"},"required":false,"name":"channel","in":"query"}],"responses":{"200":{"description":"A claimed outbound job","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OutboundJob"}}}},"204":{"description":"Queue empty"}}}},"/admin/inbox/outbound/{id}/result":{"post":{"tags":["admin/inbox"],"summary":"Report the result of an outbound send","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["sent","failed","queued"]},"externalMessageId":{"type":"string"},"error":{"type":"string"}},"required":["status"]}}}},"responses":{"200":{"description":"Recorded","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}},"required":["ok"]}}}},"404":{"description":"Message not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/legacy/sync/preview":{"get":{"tags":["admin"],"summary":"Detect legacy data waiting to migrate into this tenant","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"tenantId","in":"path"}],"responses":{"200":{"description":"Preview","content":{"application/json":{"schema":{"type":"object","properties":{"brands":{"type":"array","items":{"type":"object","properties":{"legacyBrandId":{"type":"string"},"brandName":{"type":"string","nullable":true},"sourceHandle":{"type":"string","nullable":true},"matchMethod":{"type":"string","nullable":true},"confirmed":{"type":"boolean"}},"required":["legacyBrandId","brandName","sourceHandle","matchMethod","confirmed"]}},"confirmed":{"type":"boolean"},"cursor":{"type":"string","nullable":true},"newItems":{"type":"number","nullable":true}},"required":["brands","confirmed","cursor","newItems"]}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"503":{"description":"Legacy sync not configured","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/legacy/brand-map/confirm":{"post":{"tags":["admin"],"summary":"Confirm the legacy brand(s) mapped to this tenant","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"tenantId","in":"path"}],"responses":{"200":{"description":"Confirmed","content":{"application/json":{"schema":{"type":"object","properties":{"confirmed":{"type":"integer"}},"required":["confirmed"]}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/legacy/sync":{"post":{"tags":["admin"],"summary":"Import one batch of new legacy items into this tenant","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"tenantId","in":"path"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"maxItems":{"type":"integer","minimum":1,"maximum":50},"reset":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Sync result","content":{"application/json":{"schema":{"type":"object","properties":{"itemsCreated":{"type":"integer"},"outcomesCreated":{"type":"integer"},"skippedDuplicate":{"type":"integer"},"skippedNoImages":{"type":"integer"},"failed":{"type":"integer"},"remaining":{"type":"integer"},"cursor":{"type":"string","nullable":true}},"required":["itemsCreated","outcomesCreated","skippedDuplicate","skippedNoImages","failed","remaining","cursor"]}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"409":{"description":"No confirmed brand mapping","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"503":{"description":"Legacy sync not configured","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/portal/cie/report":{"get":{"tags":["portal"],"summary":"Circular Intelligence Engine report for the signed-in brand","parameters":[{"schema":{"type":"string","description":"ISO date — lower bound on intake date."},"required":false,"description":"ISO date — lower bound on intake date.","name":"from","in":"query"},{"schema":{"type":"string"},"required":false,"name":"to","in":"query"},{"schema":{"type":"string","description":"Birl operators only: view another brand's report. Ignored for brand users (pinned to their own tenant)."},"required":false,"description":"Birl operators only: view another brand's report. Ignored for brand users (pinned to their own tenant).","name":"tenantId","in":"query"}],"responses":{"200":{"description":"CIE report (shape: see the /admin CIE schema)","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{"nullable":true}}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/portal/brands":{"get":{"tags":["portal"],"summary":"List all brands (Birl operators only)","responses":{"200":{"description":"Brand list","content":{"application/json":{"schema":{"type":"object","properties":{"brands":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"handle":{"type":"string"},"domain":{"type":"string"}},"required":["id","handle","domain"]}}},"required":["brands"]}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/admin/tenants/{tenantId}/portal/provision":{"post":{"tags":["portal"],"summary":"Provision (or re-point) a brand portal user","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tenantId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"name":{"type":"string"}},"required":["email"]}}}},"responses":{"200":{"description":"Brand user provisioned","content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"},"tenantId":{"type":"string"},"created":{"type":"boolean"}},"required":["email","tenantId","created"]}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}}}}