{"openapi":"3.0.0","paths":{"/api/developer/v1/account":{"get":{"description":"Merchant id, plan, API key scope, and accessible shop count.","operationId":"getAccount","parameters":[],"responses":{"200":{"description":"Account details wrapped in the standard envelope.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/DeveloperAccountData"},"meta":{"$ref":"#/components/schemas/DeveloperMeta"}}}}}},"400":{"description":"Invalid query, body, shop selection, or idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"401":{"description":"Missing/invalid/expired/revoked key or missing read permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"403":{"description":"Account not API-entitled, or shop outside the key scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"404":{"description":"The selected shop or resource was not found in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"409":{"description":"Disconnected shop, feature conflict, or idempotency conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"429":{"description":"Per-key rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, per RFC 9110. Mirrors `error.retryAfter` in the body.","schema":{"type":"integer","minimum":1,"example":60}}}},"500":{"description":"Unexpected server error. Provide requestId to Dashboardly support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}}},"security":[{"bearer":[]}],"summary":"Account info","tags":["Developer API v1"]}},"/api/developer/v1/shops":{"get":{"description":"Shops the key can access. A shop-scoped key returns only its shop; a merchant-wide key returns all shops.","operationId":"getShops","parameters":[],"responses":{"200":{"description":"Shops list wrapped in the standard envelope.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/DeveloperShopsData"},"meta":{"$ref":"#/components/schemas/DeveloperMeta"}}}}}},"400":{"description":"Invalid query, body, shop selection, or idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"401":{"description":"Missing/invalid/expired/revoked key or missing read permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"403":{"description":"Account not API-entitled, or shop outside the key scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"404":{"description":"The selected shop or resource was not found in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"409":{"description":"Disconnected shop, feature conflict, or idempotency conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"429":{"description":"Per-key rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, per RFC 9110. Mirrors `error.retryAfter` in the body.","schema":{"type":"integer","minimum":1,"example":60}}}},"500":{"description":"Unexpected server error. Provide requestId to Dashboardly support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}}},"security":[{"bearer":[]}],"summary":"List shops","tags":["Developer API v1"]}},"/api/developer/v1/dashboard/summary":{"get":{"description":"Headline KPIs (gross/net sales, profit, COGS, ad spend, GMV, orders, margins) plus order-status breakdown for the date range. Same source as the Dashboard page.","operationId":"getDashboardSummary","parameters":[{"name":"shopId","required":false,"in":"query","description":"Shop UUID. Optional. Required only when a merchant-wide key has more than one shop. A shop-scoped key may omit it (or pass its own shop).","schema":{"format":"uuid","example":"f47ac10b-58cc-4372-a567-0e02b2c3d479","type":"string"}},{"name":"startDate","required":true,"in":"query","description":"Inclusive start date (YYYY-MM-DD), interpreted in the shop timezone.","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-06-01","type":"string"}},{"name":"endDate","required":true,"in":"query","description":"Inclusive end date (YYYY-MM-DD), interpreted in the shop timezone. Must be ≥ startDate and within the max range (365 days by default).","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-06-30","type":"string"}},{"name":"timezone","required":false,"in":"query","description":"IANA timezone override (e.g. \"America/New_York\"). Defaults to the shop timezone.","schema":{"example":"America/New_York","type":"string"}}],"responses":{"200":{"description":"Dashboard KPIs wrapped in the standard envelope.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/DeveloperDashboardSummaryData"},"meta":{"$ref":"#/components/schemas/DeveloperMeta"}}}}}},"400":{"description":"Invalid query, body, shop selection, or idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"401":{"description":"Missing/invalid/expired/revoked key or missing read permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"403":{"description":"Account not API-entitled, or shop outside the key scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"404":{"description":"The selected shop or resource was not found in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"409":{"description":"Disconnected shop, feature conflict, or idempotency conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"429":{"description":"Per-key rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, per RFC 9110. Mirrors `error.retryAfter` in the body.","schema":{"type":"integer","minimum":1,"example":60}}}},"500":{"description":"Unexpected server error. Provide requestId to Dashboardly support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}}},"security":[{"bearer":[]}],"summary":"Dashboard summary","tags":["Developer API v1"]}},"/api/developer/v1/dashboard/top-products":{"get":{"description":"Top-product ranking from the same source as the Dashboard.","operationId":"getTopProducts","parameters":[{"name":"shopId","required":false,"in":"query","description":"Shop UUID. Required for merchant-wide keys when more than one connected shop is available.","schema":{"format":"uuid","type":"string"}},{"name":"timePeriod","required":false,"in":"query","schema":{"default":"month","type":"string","enum":["week","month","year"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/DeveloperTopProductsData"},"meta":{"$ref":"#/components/schemas/DeveloperMeta"}}}}}},"400":{"description":"Invalid query, body, shop selection, or idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"401":{"description":"Missing/invalid/expired/revoked key or missing read permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"403":{"description":"Account not API-entitled, or shop outside the key scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"404":{"description":"The selected shop or resource was not found in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"409":{"description":"Disconnected shop, feature conflict, or idempotency conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"429":{"description":"Per-key rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, per RFC 9110. Mirrors `error.retryAfter` in the body.","schema":{"type":"integer","minimum":1,"example":60}}}},"500":{"description":"Unexpected server error. Provide requestId to Dashboardly support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}}},"security":[{"bearer":[]}],"summary":"List top products","tags":["Developer API v1"]}},"/api/developer/v1/orders/statistics":{"get":{"operationId":"getOrderStatistics","parameters":[{"name":"shopId","required":false,"in":"query","description":"Shop UUID. Optional. Required only when a merchant-wide key has more than one shop. A shop-scoped key may omit it (or pass its own shop).","schema":{"format":"uuid","example":"f47ac10b-58cc-4372-a567-0e02b2c3d479","type":"string"}},{"name":"startDate","required":true,"in":"query","description":"Inclusive start date (YYYY-MM-DD), interpreted in the shop timezone.","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-06-01","type":"string"}},{"name":"endDate","required":true,"in":"query","description":"Inclusive end date (YYYY-MM-DD), interpreted in the shop timezone. Must be ≥ startDate and within the max range (365 days by default).","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-06-30","type":"string"}},{"name":"timezone","required":false,"in":"query","description":"IANA timezone override (e.g. \"America/New_York\"). Defaults to the shop timezone.","schema":{"example":"America/New_York","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/DeveloperOrderStatisticsData"},"meta":{"$ref":"#/components/schemas/DeveloperMeta"}}}}}},"400":{"description":"Invalid query, body, shop selection, or idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"401":{"description":"Missing/invalid/expired/revoked key or missing read permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"403":{"description":"Account not API-entitled, or shop outside the key scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"404":{"description":"The selected shop or resource was not found in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"409":{"description":"Disconnected shop, feature conflict, or idempotency conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"429":{"description":"Per-key rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, per RFC 9110. Mirrors `error.retryAfter` in the body.","schema":{"type":"integer","minimum":1,"example":60}}}},"500":{"description":"Unexpected server error. Provide requestId to Dashboardly support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}}},"security":[{"bearer":[]}],"summary":"Order status statistics","tags":["Developer API v1"]}},"/api/developer/v1/orders/geographic":{"get":{"description":"Aggregate order count and revenue by region. Regions with fewer than three orders are grouped into Other.","operationId":"getOrderGeography","parameters":[{"name":"shopId","required":false,"in":"query","description":"Shop UUID. Optional. Required only when a merchant-wide key has more than one shop. A shop-scoped key may omit it (or pass its own shop).","schema":{"format":"uuid","example":"f47ac10b-58cc-4372-a567-0e02b2c3d479","type":"string"}},{"name":"startDate","required":true,"in":"query","description":"Inclusive start date (YYYY-MM-DD), interpreted in the shop timezone.","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-06-01","type":"string"}},{"name":"endDate","required":true,"in":"query","description":"Inclusive end date (YYYY-MM-DD), interpreted in the shop timezone. Must be ≥ startDate and within the max range (365 days by default).","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-06-30","type":"string"}},{"name":"timezone","required":false,"in":"query","description":"IANA timezone override (e.g. \"America/New_York\"). Defaults to the shop timezone.","schema":{"example":"America/New_York","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/DeveloperOrderGeographyData"},"meta":{"$ref":"#/components/schemas/DeveloperMeta"}}}}}},"400":{"description":"Invalid query, body, shop selection, or idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"401":{"description":"Missing/invalid/expired/revoked key or missing read permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"403":{"description":"Account not API-entitled, or shop outside the key scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"404":{"description":"The selected shop or resource was not found in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"409":{"description":"Disconnected shop, feature conflict, or idempotency conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"429":{"description":"Per-key rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, per RFC 9110. Mirrors `error.retryAfter` in the body.","schema":{"type":"integer","minimum":1,"example":60}}}},"500":{"description":"Unexpected server error. Provide requestId to Dashboardly support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}}},"security":[{"bearer":[]}],"summary":"Order geography","tags":["Developer API v1"]}},"/api/developer/v1/orders/hourly":{"get":{"operationId":"getHourlyOrders","parameters":[{"name":"shopId","required":false,"in":"query","description":"Shop UUID. Optional. Required only when a merchant-wide key has more than one shop. A shop-scoped key may omit it (or pass its own shop).","schema":{"format":"uuid","example":"f47ac10b-58cc-4372-a567-0e02b2c3d479","type":"string"}},{"name":"startDate","required":true,"in":"query","description":"Inclusive start date (YYYY-MM-DD), interpreted in the shop timezone.","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-06-01","type":"string"}},{"name":"endDate","required":true,"in":"query","description":"Inclusive end date (YYYY-MM-DD), interpreted in the shop timezone. Must be ≥ startDate and within the max range (365 days by default).","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-06-30","type":"string"}},{"name":"timezone","required":false,"in":"query","description":"IANA timezone override (e.g. \"America/New_York\"). Defaults to the shop timezone.","schema":{"example":"America/New_York","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/DeveloperHourlyOrdersData"},"meta":{"$ref":"#/components/schemas/DeveloperMeta"}}}}}},"400":{"description":"Invalid query, body, shop selection, or idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"401":{"description":"Missing/invalid/expired/revoked key or missing read permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"403":{"description":"Account not API-entitled, or shop outside the key scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"404":{"description":"The selected shop or resource was not found in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"409":{"description":"Disconnected shop, feature conflict, or idempotency conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"429":{"description":"Per-key rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, per RFC 9110. Mirrors `error.retryAfter` in the body.","schema":{"type":"integer","minimum":1,"example":60}}}},"500":{"description":"Unexpected server error. Provide requestId to Dashboardly support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}}},"security":[{"bearer":[]}],"summary":"Hourly order analytics","tags":["Developer API v1"]}},"/api/developer/v1/refunds/summary":{"get":{"description":"Imported TikTok return/refund quantities for the selected shop and date range.","operationId":"getRefundsSummary","parameters":[{"name":"shopId","required":false,"in":"query","description":"Shop UUID. Optional. Required only when a merchant-wide key has more than one shop. A shop-scoped key may omit it (or pass its own shop).","schema":{"format":"uuid","example":"f47ac10b-58cc-4372-a567-0e02b2c3d479","type":"string"}},{"name":"startDate","required":true,"in":"query","description":"Inclusive start date (YYYY-MM-DD), interpreted in the shop timezone.","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-06-01","type":"string"}},{"name":"endDate","required":true,"in":"query","description":"Inclusive end date (YYYY-MM-DD), interpreted in the shop timezone. Must be ≥ startDate and within the max range (365 days by default).","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-06-30","type":"string"}},{"name":"timezone","required":false,"in":"query","description":"IANA timezone override (e.g. \"America/New_York\"). Defaults to the shop timezone.","schema":{"example":"America/New_York","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/DeveloperRefundSummaryData"},"meta":{"$ref":"#/components/schemas/DeveloperMeta"}}}}}},"400":{"description":"Invalid query, body, shop selection, or idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"401":{"description":"Missing/invalid/expired/revoked key or missing read permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"403":{"description":"Account not API-entitled, or shop outside the key scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"404":{"description":"The selected shop or resource was not found in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"409":{"description":"Disconnected shop, feature conflict, or idempotency conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"429":{"description":"Per-key rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, per RFC 9110. Mirrors `error.retryAfter` in the body.","schema":{"type":"integer","minimum":1,"example":60}}}},"500":{"description":"Unexpected server error. Provide requestId to Dashboardly support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}}},"security":[{"bearer":[]}],"summary":"Refund summary","tags":["Developer API v1"]}},"/api/developer/v1/inventory/summary":{"get":{"description":"Inventory totals plus optional paginated product/SKU rows and dated COGS coverage.","operationId":"getInventorySummary","parameters":[{"name":"shopId","required":false,"in":"query","description":"Shop UUID. Required for merchant-wide keys when more than one connected shop is available.","schema":{"format":"uuid","type":"string"}},{"name":"search","required":false,"in":"query","description":"Product or SKU search text.","schema":{"type":"string"}},{"name":"page","required":false,"in":"query","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"default":20,"type":"number"}},{"name":"sortBy","required":false,"in":"query","schema":{"type":"string","enum":["productName","sku","inventory","inventoryValue","unitsSold","revenue","unitCog"]}},{"name":"sortDir","required":false,"in":"query","schema":{"default":"desc","type":"string","enum":["asc","desc"]}},{"name":"showActiveOnly","required":false,"in":"query","schema":{"default":true,"type":"boolean"}},{"name":"showWithoutCogs","required":false,"in":"query","schema":{"default":false,"type":"boolean"}},{"name":"includeItems","required":false,"in":"query","schema":{"default":true,"type":"boolean"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/DeveloperInventorySummaryData"},"meta":{"$ref":"#/components/schemas/DeveloperMeta"}}}}}},"400":{"description":"Invalid query, body, shop selection, or idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"401":{"description":"Missing/invalid/expired/revoked key or missing read permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"403":{"description":"Account not API-entitled, or shop outside the key scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"404":{"description":"The selected shop or resource was not found in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"409":{"description":"Disconnected shop, feature conflict, or idempotency conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"429":{"description":"Per-key rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, per RFC 9110. Mirrors `error.retryAfter` in the body.","schema":{"type":"integer","minimum":1,"example":60}}}},"500":{"description":"Unexpected server error. Provide requestId to Dashboardly support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}}},"security":[{"bearer":[]}],"summary":"Inventory summary and products","tags":["Developer API v1"]}},"/api/developer/v1/warehouse/summary":{"get":{"operationId":"getWarehouseSummary","parameters":[{"name":"shopId","required":false,"in":"query","description":"Shop UUID. Required for merchant-wide keys when more than one connected shop is available.","schema":{"format":"uuid","type":"string"}},{"name":"includeSkuFees","required":false,"in":"query","schema":{"default":false,"type":"boolean"}},{"name":"feePage","required":false,"in":"query","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"feeLimit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"default":50,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/DeveloperWarehouseSummaryData"},"meta":{"$ref":"#/components/schemas/DeveloperMeta"}}}}}},"400":{"description":"Invalid query, body, shop selection, or idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"401":{"description":"Missing/invalid/expired/revoked key or missing read permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"403":{"description":"Account not API-entitled, or shop outside the key scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"404":{"description":"The selected shop or resource was not found in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"409":{"description":"Disconnected shop, feature conflict, or idempotency conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"429":{"description":"Per-key rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, per RFC 9110. Mirrors `error.retryAfter` in the body.","schema":{"type":"integer","minimum":1,"example":60}}}},"500":{"description":"Unexpected server error. Provide requestId to Dashboardly support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}}},"security":[{"bearer":[]}],"summary":"Warehouse analytics and fulfillment fees","tags":["Developer API v1"]}},"/api/developer/v1/cashflow/summary":{"get":{"description":"Cash-basis projection and optional paginated payout ledger. Available only when Cashflow is enabled for the shop.","operationId":"getCashflowSummary","parameters":[{"name":"shopId","required":false,"in":"query","description":"Shop UUID. Optional. Required only when a merchant-wide key has more than one shop. A shop-scoped key may omit it (or pass its own shop).","schema":{"format":"uuid","example":"f47ac10b-58cc-4372-a567-0e02b2c3d479","type":"string"}},{"name":"startDate","required":true,"in":"query","description":"Inclusive start date (YYYY-MM-DD), interpreted in the shop timezone.","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-06-01","type":"string"}},{"name":"endDate","required":true,"in":"query","description":"Inclusive end date (YYYY-MM-DD), interpreted in the shop timezone. Must be ≥ startDate and within the max range (365 days by default).","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-06-30","type":"string"}},{"name":"timezone","required":false,"in":"query","description":"IANA timezone override (e.g. \"America/New_York\"). Defaults to the shop timezone.","schema":{"example":"America/New_York","type":"string"}},{"name":"period","required":false,"in":"query","schema":{"default":"month","type":"string","enum":["day","week","month","quarter","year"]}},{"name":"basis","required":false,"in":"query","schema":{"default":"payout","type":"string","enum":["payout","month"]}},{"name":"cashDateMode","required":false,"in":"query","schema":{"default":"statement_date","type":"string","enum":["statement_date","paid_time"]}},{"name":"includeLedger","required":false,"in":"query","schema":{"default":false,"type":"boolean"}},{"name":"page","required":false,"in":"query","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"pageSize","required":false,"in":"query","schema":{"minimum":1,"maximum":500,"default":50,"type":"number"}},{"name":"typeFilter","required":false,"in":"query","schema":{"type":"string","enum":["cash_in","cash_out"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/DeveloperCashflowSummaryData"},"meta":{"$ref":"#/components/schemas/DeveloperMeta"}}}}}},"400":{"description":"Invalid query, body, shop selection, or idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"401":{"description":"Missing/invalid/expired/revoked key or missing read permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"403":{"description":"Account not API-entitled, or shop outside the key scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"404":{"description":"The selected shop or resource was not found in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"409":{"description":"Disconnected shop, feature conflict, or idempotency conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"429":{"description":"Per-key rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, per RFC 9110. Mirrors `error.retryAfter` in the body.","schema":{"type":"integer","minimum":1,"example":60}}}},"500":{"description":"Unexpected server error. Provide requestId to Dashboardly support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}}},"security":[{"bearer":[]}],"summary":"Cashflow summary","tags":["Developer API v1"]}},"/api/developer/v1/manual-adjustments":{"get":{"operationId":"getManualAdjustments","parameters":[{"name":"shopId","required":false,"in":"query","description":"Shop UUID. Required for merchant-wide keys when more than one connected shop is available.","schema":{"format":"uuid","type":"string"}},{"name":"page","required":false,"in":"query","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"search","required":false,"in":"query","schema":{"type":"string"}},{"name":"category","required":false,"in":"query","schema":{"type":"string","enum":["","SUPPLY_COSTS","AD_COSTS","OTHER","TAXES","MARKETING_COSTS","FULFILLMENT_FEES","SHIPPING_COSTS","FBS_MANUAL_SHIPPING","INBOUND_SHIPPING","PACKAGING_MATERIALS","CUSTOMER_REFUNDS","RETURN_SHIPPING","DAMAGED_GOODS","PLATFORM_FEES","PAYMENT_GATEWAY_FEES","STAFF_COSTS","LEGAL_FEES","VAT_GST","INTERNET_UTILITIES","SOFTWARE_SUBSCRIPTIONS","INVENTORY_PURCHASES","INVENTORY_WRITE_OFFS","INVENTORY_RESTOCK_CREDIT","ONE_TIME_REVENUE","AFFILIATE_COMMISSION","AGENCY_FEE"]}},{"name":"isPast","required":false,"in":"query","schema":{"type":"boolean"}},{"name":"timezone","required":false,"in":"query","schema":{"example":"America/New_York","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/DeveloperManualAdjustmentsData"},"meta":{"$ref":"#/components/schemas/DeveloperMeta"}}}}}},"400":{"description":"Invalid query, body, shop selection, or idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"401":{"description":"Missing/invalid/expired/revoked key or missing read permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"403":{"description":"Account not API-entitled, or shop outside the key scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"404":{"description":"The selected shop or resource was not found in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"409":{"description":"Disconnected shop, feature conflict, or idempotency conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"429":{"description":"Per-key rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, per RFC 9110. Mirrors `error.retryAfter` in the body.","schema":{"type":"integer","minimum":1,"example":60}}}},"500":{"description":"Unexpected server error. Provide requestId to Dashboardly support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}}},"security":[{"bearer":[]}],"summary":"List manual adjustments","tags":["Developer API v1"]},"post":{"description":"Requires a shop-scoped key with write:manual-adjustments. The created record is owned by this API key. An Idempotency-Key header is required: retrying with the same key and body replays the original result, and the same key with a different body returns 409.","operationId":"createManualAdjustment","parameters":[{"name":"idempotency-key","required":true,"in":"header","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","description":"Unique 8-128 character key. Reusing it with the same body replays the original result; a different body returns 409.","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperAdjustmentRequestDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/DeveloperManualAdjustmentMutationData"},"meta":{"$ref":"#/components/schemas/DeveloperMeta"}}}}}},"400":{"description":"Invalid query, body, shop selection, or idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"401":{"description":"Missing/invalid/expired/revoked key or missing read permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"403":{"description":"Account not API-entitled, or shop outside the key scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"404":{"description":"The selected shop or resource was not found in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"409":{"description":"Disconnected shop, feature conflict, or idempotency conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"429":{"description":"Per-key rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, per RFC 9110. Mirrors `error.retryAfter` in the body.","schema":{"type":"integer","minimum":1,"example":60}}}},"500":{"description":"Unexpected server error. Provide requestId to Dashboardly support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}}},"security":[{"bearer":[]}],"summary":"Create a manual adjustment","tags":["Developer API v1"]}},"/api/developer/v1/manual-adjustments/{id}":{"get":{"operationId":"getManualAdjustment","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}},{"name":"shopId","required":false,"in":"query","description":"Shop UUID. Required for merchant-wide keys when more than one connected shop is available.","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/DeveloperManualAdjustmentData"},"meta":{"$ref":"#/components/schemas/DeveloperMeta"}}}}}},"400":{"description":"Invalid query, body, shop selection, or idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"401":{"description":"Missing/invalid/expired/revoked key or missing read permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"403":{"description":"Account not API-entitled, or shop outside the key scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"404":{"description":"The selected shop or resource was not found in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"409":{"description":"Disconnected shop, feature conflict, or idempotency conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"429":{"description":"Per-key rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, per RFC 9110. Mirrors `error.retryAfter` in the body.","schema":{"type":"integer","minimum":1,"example":60}}}},"500":{"description":"Unexpected server error. Provide requestId to Dashboardly support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}}},"security":[{"bearer":[]}],"summary":"Read one shop-visible manual adjustment","tags":["Developer API v1"]},"put":{"description":"Only adjustments created by the same API key in its scoped shop may be changed.","operationId":"updateManualAdjustment","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperAdjustmentRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/DeveloperManualAdjustmentMutationData"},"meta":{"$ref":"#/components/schemas/DeveloperMeta"}}}}}},"400":{"description":"Invalid query, body, shop selection, or idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"401":{"description":"Missing/invalid/expired/revoked key or missing read permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"403":{"description":"Account not API-entitled, or shop outside the key scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"404":{"description":"The selected shop or resource was not found in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"409":{"description":"Disconnected shop, feature conflict, or idempotency conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"429":{"description":"Per-key rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, per RFC 9110. Mirrors `error.retryAfter` in the body.","schema":{"type":"integer","minimum":1,"example":60}}}},"500":{"description":"Unexpected server error. Provide requestId to Dashboardly support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}}},"security":[{"bearer":[]}],"summary":"Replace a manual adjustment","tags":["Developer API v1"]},"delete":{"operationId":"deleteManualAdjustment","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/DeveloperDeleteData"},"meta":{"$ref":"#/components/schemas/DeveloperMeta"}}}}}},"400":{"description":"Invalid query, body, shop selection, or idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"401":{"description":"Missing/invalid/expired/revoked key or missing read permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"403":{"description":"Account not API-entitled, or shop outside the key scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"404":{"description":"The selected shop or resource was not found in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"409":{"description":"Disconnected shop, feature conflict, or idempotency conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"429":{"description":"Per-key rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, per RFC 9110. Mirrors `error.retryAfter` in the body.","schema":{"type":"integer","minimum":1,"example":60}}}},"500":{"description":"Unexpected server error. Provide requestId to Dashboardly support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}}},"security":[{"bearer":[]}],"summary":"Delete a manual adjustment created by this key","tags":["Developer API v1"]}},"/api/developer/v1/manual-adjustments/{id}/suspend":{"patch":{"operationId":"suspendManualAdjustment","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/DeveloperManualAdjustmentMutationData"},"meta":{"$ref":"#/components/schemas/DeveloperMeta"}}}}}},"400":{"description":"Invalid query, body, shop selection, or idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"401":{"description":"Missing/invalid/expired/revoked key or missing read permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"403":{"description":"Account not API-entitled, or shop outside the key scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"404":{"description":"The selected shop or resource was not found in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"409":{"description":"Disconnected shop, feature conflict, or idempotency conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"429":{"description":"Per-key rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, per RFC 9110. Mirrors `error.retryAfter` in the body.","schema":{"type":"integer","minimum":1,"example":60}}}},"500":{"description":"Unexpected server error. Provide requestId to Dashboardly support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}}},"security":[{"bearer":[]}],"summary":"Suspend a recurring manual adjustment","tags":["Developer API v1"]}},"/api/developer/v1/manual-adjustments/{id}/resume":{"patch":{"operationId":"resumeManualAdjustment","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/DeveloperManualAdjustmentMutationData"},"meta":{"$ref":"#/components/schemas/DeveloperMeta"}}}}}},"400":{"description":"Invalid query, body, shop selection, or idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"401":{"description":"Missing/invalid/expired/revoked key or missing read permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"403":{"description":"Account not API-entitled, or shop outside the key scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"404":{"description":"The selected shop or resource was not found in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"409":{"description":"Disconnected shop, feature conflict, or idempotency conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"429":{"description":"Per-key rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, per RFC 9110. Mirrors `error.retryAfter` in the body.","schema":{"type":"integer","minimum":1,"example":60}}}},"500":{"description":"Unexpected server error. Provide requestId to Dashboardly support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}}},"security":[{"bearer":[]}],"summary":"Resume a suspended manual adjustment","tags":["Developer API v1"]}},"/api/developer/v1/customers/summary":{"get":{"description":"Aggregate customer metrics and top-customer pseudonyms. Names and email addresses are never returned.","operationId":"getCustomerSummary","parameters":[{"name":"shopId","required":false,"in":"query","description":"Shop UUID. Optional. Required only when a merchant-wide key has more than one shop. A shop-scoped key may omit it (or pass its own shop).","schema":{"format":"uuid","example":"f47ac10b-58cc-4372-a567-0e02b2c3d479","type":"string"}},{"name":"startDate","required":true,"in":"query","description":"Inclusive start date (YYYY-MM-DD), interpreted in the shop timezone.","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-06-01","type":"string"}},{"name":"endDate","required":true,"in":"query","description":"Inclusive end date (YYYY-MM-DD), interpreted in the shop timezone. Must be ≥ startDate and within the max range (365 days by default).","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-06-30","type":"string"}},{"name":"timezone","required":false,"in":"query","description":"IANA timezone override (e.g. \"America/New_York\"). Defaults to the shop timezone.","schema":{"example":"America/New_York","type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":50,"default":10,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/DeveloperCustomerSummaryData"},"meta":{"$ref":"#/components/schemas/DeveloperMeta"}}}}}},"400":{"description":"Invalid query, body, shop selection, or idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"401":{"description":"Missing/invalid/expired/revoked key or missing read permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"403":{"description":"Account not API-entitled, or shop outside the key scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"404":{"description":"The selected shop or resource was not found in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"409":{"description":"Disconnected shop, feature conflict, or idempotency conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"429":{"description":"Per-key rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, per RFC 9110. Mirrors `error.retryAfter` in the body.","schema":{"type":"integer","minimum":1,"example":60}}}},"500":{"description":"Unexpected server error. Provide requestId to Dashboardly support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}}},"security":[{"bearer":[]}],"summary":"Customer summary","tags":["Developer API v1"]}},"/api/developer/v1/customers":{"get":{"description":"Paginated LTV metrics with stable account-local pseudonyms and no direct buyer identifiers.","operationId":"getCustomers","parameters":[{"name":"shopId","required":false,"in":"query","description":"Shop UUID. Required for merchant-wide keys when more than one connected shop is available.","schema":{"format":"uuid","type":"string"}},{"name":"page","required":false,"in":"query","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"default":50,"type":"number"}},{"name":"sortBy","required":false,"in":"query","schema":{"default":"lifetimeValue","type":"string","enum":["lifetimeValue","projectedLTV","totalRevenue","netRevenue","totalOrders","averageOrderValue","firstOrderDate","lastOrderDate"]}},{"name":"sortOrder","required":false,"in":"query","schema":{"default":"desc","type":"string","enum":["asc","desc"]}},{"name":"segment","required":false,"in":"query","schema":{"type":"string","enum":["NEW","REGULAR","VIP","CHURNED"]}},{"name":"minLtv","required":false,"in":"query","schema":{"minimum":0,"type":"number"}},{"name":"maxLtv","required":false,"in":"query","schema":{"minimum":0,"type":"number"}},{"name":"dateFrom","required":false,"in":"query","schema":{"example":"2026-01-01","type":"string"}},{"name":"dateTo","required":false,"in":"query","schema":{"example":"2026-06-30","type":"string"}},{"name":"timezone","required":false,"in":"query","schema":{"example":"America/New_York","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/DeveloperCustomersData"},"meta":{"$ref":"#/components/schemas/DeveloperMeta"}}}}}},"400":{"description":"Invalid query, body, shop selection, or idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"401":{"description":"Missing/invalid/expired/revoked key or missing read permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"403":{"description":"Account not API-entitled, or shop outside the key scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"404":{"description":"The selected shop or resource was not found in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"409":{"description":"Disconnected shop, feature conflict, or idempotency conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"429":{"description":"Per-key rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, per RFC 9110. Mirrors `error.retryAfter` in the body.","schema":{"type":"integer","minimum":1,"example":60}}}},"500":{"description":"Unexpected server error. Provide requestId to Dashboardly support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}}},"security":[{"bearer":[]}],"summary":"List customer LTV rows","tags":["Developer API v1"]}},"/api/developer/v1/customers/lifetime-value":{"get":{"operationId":"getCustomersLifetime","parameters":[{"name":"shopId","required":false,"in":"query","description":"Shop UUID. Required for merchant-wide keys when more than one connected shop is available.","schema":{"format":"uuid","type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":50,"default":5,"type":"number"}},{"name":"mode","required":false,"in":"query","schema":{"default":"historical","type":"string","enum":["historical","projected"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/DeveloperCustomerLifetimeData"},"meta":{"$ref":"#/components/schemas/DeveloperMeta"}}}}}},"400":{"description":"Invalid query, body, shop selection, or idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"401":{"description":"Missing/invalid/expired/revoked key or missing read permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"403":{"description":"Account not API-entitled, or shop outside the key scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"404":{"description":"The selected shop or resource was not found in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"409":{"description":"Disconnected shop, feature conflict, or idempotency conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"429":{"description":"Per-key rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, per RFC 9110. Mirrors `error.retryAfter` in the body.","schema":{"type":"integer","minimum":1,"example":60}}}},"500":{"description":"Unexpected server error. Provide requestId to Dashboardly support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}}},"security":[{"bearer":[]}],"summary":"Top customers by historical or projected LTV","tags":["Developer API v1"]}},"/api/developer/v1/customers/cohorts":{"get":{"operationId":"getCustomerCohorts","parameters":[{"name":"shopId","required":false,"in":"query","description":"Shop UUID. Required for merchant-wide keys when more than one connected shop is available.","schema":{"format":"uuid","type":"string"}},{"name":"analysis","required":false,"in":"query","schema":{"default":"retention","type":"string","enum":["journey","retention"]}},{"name":"startMonth","required":false,"in":"query","schema":{"example":"2026-01","type":"string"}},{"name":"endMonth","required":false,"in":"query","schema":{"example":"2026-06","type":"string"}},{"name":"timezone","required":false,"in":"query","schema":{"example":"America/New_York","type":"string"}},{"name":"nodeGranularity","required":false,"in":"query","schema":{"type":"string","enum":["item","sku","category","brand"]}},{"name":"maxMonthsAfterPurchase","required":false,"in":"query","schema":{"minimum":1,"maximum":24,"default":6,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/DeveloperCustomerCohortData"},"meta":{"$ref":"#/components/schemas/DeveloperMeta"}}}}}},"400":{"description":"Invalid query, body, shop selection, or idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"401":{"description":"Missing/invalid/expired/revoked key or missing read permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"403":{"description":"Account not API-entitled, or shop outside the key scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"404":{"description":"The selected shop or resource was not found in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"409":{"description":"Disconnected shop, feature conflict, or idempotency conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"429":{"description":"Per-key rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, per RFC 9110. Mirrors `error.retryAfter` in the body.","schema":{"type":"integer","minimum":1,"example":60}}}},"500":{"description":"Unexpected server error. Provide requestId to Dashboardly support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}}},"security":[{"bearer":[]}],"summary":"Customer retention cohorts or purchase journeys","tags":["Developer API v1"]}},"/api/developer/v1/marketing/overview":{"get":{"operationId":"getMarketingOverview","parameters":[{"name":"shopId","required":false,"in":"query","description":"Shop UUID. Optional. Required only when a merchant-wide key has more than one shop. A shop-scoped key may omit it (or pass its own shop).","schema":{"format":"uuid","example":"f47ac10b-58cc-4372-a567-0e02b2c3d479","type":"string"}},{"name":"startDate","required":true,"in":"query","description":"Inclusive start date (YYYY-MM-DD), interpreted in the shop timezone.","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-06-01","type":"string"}},{"name":"endDate","required":true,"in":"query","description":"Inclusive end date (YYYY-MM-DD), interpreted in the shop timezone. Must be ≥ startDate and within the max range (365 days by default).","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-06-30","type":"string"}},{"name":"timezone","required":false,"in":"query","description":"IANA timezone override (e.g. \"America/New_York\"). Defaults to the shop timezone.","schema":{"example":"America/New_York","type":"string"}},{"name":"includePreviousPeriod","required":false,"in":"query","schema":{"default":false,"type":"boolean"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/DeveloperMarketingOverviewData"},"meta":{"$ref":"#/components/schemas/DeveloperMeta"}}}}}},"400":{"description":"Invalid query, body, shop selection, or idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"401":{"description":"Missing/invalid/expired/revoked key or missing read permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"403":{"description":"Account not API-entitled, or shop outside the key scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"404":{"description":"The selected shop or resource was not found in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"409":{"description":"Disconnected shop, feature conflict, or idempotency conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"429":{"description":"Per-key rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, per RFC 9110. Mirrors `error.retryAfter` in the body.","schema":{"type":"integer","minimum":1,"example":60}}}},"500":{"description":"Unexpected server error. Provide requestId to Dashboardly support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}}},"security":[{"bearer":[]}],"summary":"Marketing overview","tags":["Developer API v1"]}},"/api/developer/v1/marketing/live-streams":{"get":{"operationId":"getMarketingLiveStreams","parameters":[{"name":"shopId","required":false,"in":"query","description":"Shop UUID. Optional. Required only when a merchant-wide key has more than one shop. A shop-scoped key may omit it (or pass its own shop).","schema":{"format":"uuid","example":"f47ac10b-58cc-4372-a567-0e02b2c3d479","type":"string"}},{"name":"startDate","required":true,"in":"query","description":"Inclusive start date (YYYY-MM-DD), interpreted in the shop timezone.","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-06-01","type":"string"}},{"name":"endDate","required":true,"in":"query","description":"Inclusive end date (YYYY-MM-DD), interpreted in the shop timezone. Must be ≥ startDate and within the max range (365 days by default).","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-06-30","type":"string"}},{"name":"timezone","required":false,"in":"query","description":"IANA timezone override (e.g. \"America/New_York\"). Defaults to the shop timezone.","schema":{"example":"America/New_York","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/DeveloperMarketingLiveData"},"meta":{"$ref":"#/components/schemas/DeveloperMeta"}}}}}},"400":{"description":"Invalid query, body, shop selection, or idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"401":{"description":"Missing/invalid/expired/revoked key or missing read permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"403":{"description":"Account not API-entitled, or shop outside the key scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"404":{"description":"The selected shop or resource was not found in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"409":{"description":"Disconnected shop, feature conflict, or idempotency conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"429":{"description":"Per-key rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, per RFC 9110. Mirrors `error.retryAfter` in the body.","schema":{"type":"integer","minimum":1,"example":60}}}},"500":{"description":"Unexpected server error. Provide requestId to Dashboardly support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}}},"security":[{"bearer":[]}],"summary":"TikTok LIVE performance summary","tags":["Developer API v1"]}},"/api/developer/v1/marketing/ad-campaigns":{"get":{"operationId":"getAdCampaigns","parameters":[{"name":"shopId","required":false,"in":"query","description":"Shop UUID. Optional. Required only when a merchant-wide key has more than one shop. A shop-scoped key may omit it (or pass its own shop).","schema":{"format":"uuid","example":"f47ac10b-58cc-4372-a567-0e02b2c3d479","type":"string"}},{"name":"startDate","required":true,"in":"query","description":"Inclusive start date (YYYY-MM-DD), interpreted in the shop timezone.","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-06-01","type":"string"}},{"name":"endDate","required":true,"in":"query","description":"Inclusive end date (YYYY-MM-DD), interpreted in the shop timezone. Must be ≥ startDate and within the max range (365 days by default).","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-06-30","type":"string"}},{"name":"timezone","required":false,"in":"query","description":"IANA timezone override (e.g. \"America/New_York\"). Defaults to the shop timezone.","schema":{"example":"America/New_York","type":"string"}},{"name":"page","required":false,"in":"query","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"pageSize","required":false,"in":"query","schema":{"minimum":1,"maximum":200,"default":50,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/DeveloperAdCampaignsData"},"meta":{"$ref":"#/components/schemas/DeveloperMeta"}}}}}},"400":{"description":"Invalid query, body, shop selection, or idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"401":{"description":"Missing/invalid/expired/revoked key or missing read permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"403":{"description":"Account not API-entitled, or shop outside the key scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"404":{"description":"The selected shop or resource was not found in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"409":{"description":"Disconnected shop, feature conflict, or idempotency conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"429":{"description":"Per-key rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, per RFC 9110. Mirrors `error.retryAfter` in the body.","schema":{"type":"integer","minimum":1,"example":60}}}},"500":{"description":"Unexpected server error. Provide requestId to Dashboardly support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}}},"security":[{"bearer":[]}],"summary":"Paginated ad campaign metrics","tags":["Developer API v1"]}},"/api/developer/v1/marketing/affiliate-performance":{"get":{"description":"Creator and affiliate attribution for a US-region shop. Requires read:marketing and Marketing Analytics enabled for the shop. Window is capped at 90 days and is evaluated in the shop's own timezone (reported in meta.timezone); this route accepts no timezone override.","operationId":"getAffiliatePerformance","parameters":[{"name":"shopId","required":false,"in":"query","description":"Shop UUID. Required only when a merchant-wide key has more than one connected shop.","schema":{"format":"uuid","type":"string"}},{"name":"startDate","required":true,"in":"query","description":"Inclusive start date (YYYY-MM-DD), interpreted in the shop's own timezone.","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-06-01","type":"string"}},{"name":"endDate","required":true,"in":"query","description":"Inclusive end date (YYYY-MM-DD), interpreted in the shop's own timezone. Must be >= startDate, and the window may span at most 90 calendar days counting both endpoints (2026-01-01 to 2026-03-31 is the maximum).","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-06-30","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/DeveloperAffiliatePerformanceData"},"meta":{"$ref":"#/components/schemas/DeveloperMeta"}}}}}},"400":{"description":"Invalid query, body, shop selection, or idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"401":{"description":"Missing/invalid/expired/revoked key or missing read permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"403":{"description":"Account not API-entitled, or shop outside the key scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"404":{"description":"The selected shop or resource was not found in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"409":{"description":"Disconnected shop, feature conflict, or idempotency conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"429":{"description":"Per-key rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, per RFC 9110. Mirrors `error.retryAfter` in the body.","schema":{"type":"integer","minimum":1,"example":60}}}},"500":{"description":"Unexpected server error. Provide requestId to Dashboardly support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}}},"security":[{"bearer":[]}],"summary":"Affiliate performance","tags":["Developer API v1"]}},"/api/developer/v1/marketing/promotions":{"get":{"operationId":"getPromotions","parameters":[{"name":"shopId","required":false,"in":"query","description":"Shop UUID. Optional. Required only when a merchant-wide key has more than one shop. A shop-scoped key may omit it (or pass its own shop).","schema":{"format":"uuid","example":"f47ac10b-58cc-4372-a567-0e02b2c3d479","type":"string"}},{"name":"startDate","required":true,"in":"query","description":"Inclusive start date (YYYY-MM-DD), interpreted in the shop timezone.","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-06-01","type":"string"}},{"name":"endDate","required":true,"in":"query","description":"Inclusive end date (YYYY-MM-DD), interpreted in the shop timezone. Must be ≥ startDate and within the max range (365 days by default).","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-06-30","type":"string"}},{"name":"timezone","required":false,"in":"query","description":"IANA timezone override (e.g. \"America/New_York\"). Defaults to the shop timezone.","schema":{"example":"America/New_York","type":"string"}},{"name":"page","required":false,"in":"query","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"default":50,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/DeveloperPromotionsData"},"meta":{"$ref":"#/components/schemas/DeveloperMeta"}}}}}},"400":{"description":"Invalid query, body, shop selection, or idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"401":{"description":"Missing/invalid/expired/revoked key or missing read permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"403":{"description":"Account not API-entitled, or shop outside the key scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"404":{"description":"The selected shop or resource was not found in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"409":{"description":"Disconnected shop, feature conflict, or idempotency conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"429":{"description":"Per-key rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, per RFC 9110. Mirrors `error.retryAfter` in the body.","schema":{"type":"integer","minimum":1,"example":60}}}},"500":{"description":"Unexpected server error. Provide requestId to Dashboardly support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}}},"security":[{"bearer":[]}],"summary":"Promotion and coupon window exposure","tags":["Developer API v1"]}},"/api/developer/v1/profit-loss/summary":{"get":{"description":"Canonical P&L tree (columns + summary) for the date range, identical to the P&L page / MCP. Use `period` to set column granularity.","operationId":"getProfitLossSummary","parameters":[{"name":"shopId","required":false,"in":"query","description":"Shop UUID. Optional. Required only when a merchant-wide key has more than one shop. A shop-scoped key may omit it (or pass its own shop).","schema":{"format":"uuid","example":"f47ac10b-58cc-4372-a567-0e02b2c3d479","type":"string"}},{"name":"startDate","required":true,"in":"query","description":"Inclusive start date (YYYY-MM-DD), interpreted in the shop timezone.","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-06-01","type":"string"}},{"name":"endDate","required":true,"in":"query","description":"Inclusive end date (YYYY-MM-DD), interpreted in the shop timezone. Must be ≥ startDate and within the max range (365 days by default).","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-06-30","type":"string"}},{"name":"timezone","required":false,"in":"query","description":"IANA timezone override (e.g. \"America/New_York\"). Defaults to the shop timezone.","schema":{"example":"America/New_York","type":"string"}},{"name":"period","required":false,"in":"query","description":"Column granularity for the P&L breakdown. Defaults to \"month\".","schema":{"example":"month","type":"string","enum":["day","week","month","quarter","year"]}}],"responses":{"200":{"description":"P&L summary wrapped in the standard envelope.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/DeveloperProfitLossData"},"meta":{"$ref":"#/components/schemas/DeveloperMeta"}}}}}},"400":{"description":"Invalid query, body, shop selection, or idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"401":{"description":"Missing/invalid/expired/revoked key or missing read permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"403":{"description":"Account not API-entitled, or shop outside the key scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"404":{"description":"The selected shop or resource was not found in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"409":{"description":"Disconnected shop, feature conflict, or idempotency conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"429":{"description":"Per-key rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, per RFC 9110. Mirrors `error.retryAfter` in the body.","schema":{"type":"integer","minimum":1,"example":60}}}},"500":{"description":"Unexpected server error. Provide requestId to Dashboardly support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}}},"security":[{"bearer":[]}],"summary":"Profit & Loss summary","tags":["Developer API v1"]}},"/api/developer/v1/custom-pnl/reports":{"get":{"description":"Published Custom P&L definitions available to this shop. Use the report id to list immutable prepared evaluations.","operationId":"getCustomPnlReports","parameters":[{"name":"shopId","required":false,"in":"query","description":"Shop UUID. Required only when a merchant-wide key can access multiple shops.","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"Published Custom P&L report catalog.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/DeveloperCustomPnlReportsData"},"meta":{"$ref":"#/components/schemas/DeveloperMeta"}}}}}},"400":{"description":"Invalid query, body, shop selection, or idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"401":{"description":"Missing/invalid/expired/revoked key or missing read permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"403":{"description":"Account not API-entitled, or shop outside the key scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"404":{"description":"The selected shop or resource was not found in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"409":{"description":"Disconnected shop, feature conflict, or idempotency conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"429":{"description":"Per-key rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, per RFC 9110. Mirrors `error.retryAfter` in the body.","schema":{"type":"integer","minimum":1,"example":60}}}},"500":{"description":"Unexpected server error. Provide requestId to Dashboardly support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}}},"security":[{"bearer":[]}],"summary":"List published Custom P&L reports","tags":["Developer API v1"]}},"/api/developer/v1/custom-pnl/reports/{reportId}/evaluations":{"get":{"description":"Immutable prepared evaluations for the published report version. Select an evaluation id to read its SKU/day rows.","operationId":"getCustomPnlEvaluations","parameters":[{"name":"reportId","required":true,"in":"path","schema":{"type":"string"}},{"name":"shopId","required":false,"in":"query","description":"Shop UUID. Required only when a merchant-wide key can access multiple shops.","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"Prepared Custom P&L evaluation history.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/DeveloperCustomPnlEvaluationsData"},"meta":{"$ref":"#/components/schemas/DeveloperMeta"}}}}}},"400":{"description":"Invalid query, body, shop selection, or idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"401":{"description":"Missing/invalid/expired/revoked key or missing read permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"403":{"description":"Account not API-entitled, or shop outside the key scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"404":{"description":"The selected shop or resource was not found in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"409":{"description":"Disconnected shop, feature conflict, or idempotency conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"429":{"description":"Per-key rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, per RFC 9110. Mirrors `error.retryAfter` in the body.","schema":{"type":"integer","minimum":1,"example":60}}}},"500":{"description":"Unexpected server error. Provide requestId to Dashboardly support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}}},"security":[{"bearer":[]}],"summary":"List prepared Custom P&L evaluations","tags":["Developer API v1"]}},"/api/developer/v1/custom-pnl/evaluations/{evaluationId}":{"get":{"description":"Paginated SKU totals and optional day rows from the same immutable evaluation used by Dashboardly and Excel export.","operationId":"getCustomPnlEvaluation","parameters":[{"name":"evaluationId","required":true,"in":"path","schema":{"type":"string"}},{"name":"period","required":false,"in":"query","schema":{"default":"day","type":"string","enum":["day","week","month","quarter","year"]}},{"name":"search","required":false,"in":"query","description":"Server-side SKU, seller SKU, or product-title search.","schema":{"type":"string"}},{"name":"sortBy","required":false,"in":"query","schema":{"default":"netSales","type":"string","enum":["netSales","units","grossSales","grossProfit","sku","date"]}},{"name":"sortByRowId","required":false,"in":"query","description":"Stable report-row id used for numeric row sorting.","schema":{"type":"string"}},{"name":"sortDir","required":false,"in":"query","schema":{"default":"desc","type":"string","enum":["asc","desc"]}},{"name":"page","required":false,"in":"query","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","schema":{"maximum":200,"default":25,"type":"number"}},{"name":"rowDetail","required":false,"in":"query","schema":{"default":"all","type":"string","enum":["none","totals","expanded","all"]}},{"name":"expandedSkuIds","required":false,"in":"query","description":"SKU ids whose day rows are included when rowDetail is expanded.","schema":{"type":"array","items":{"type":"string"}}},{"name":"reportRowFormat","required":false,"in":"query","schema":{"default":"hydrated","type":"string","enum":["hydrated","catalog"]}},{"name":"shopId","required":false,"in":"query","description":"Shop UUID. Required only when a merchant-wide key can access multiple shops.","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"Prepared Custom P&L evaluation rows.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/DeveloperCustomPnlEvaluationData"},"meta":{"$ref":"#/components/schemas/DeveloperMeta"}}}}}},"400":{"description":"Invalid query, body, shop selection, or idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"401":{"description":"Missing/invalid/expired/revoked key or missing read permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"403":{"description":"Account not API-entitled, or shop outside the key scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"404":{"description":"The selected shop or resource was not found in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"409":{"description":"Disconnected shop, feature conflict, or idempotency conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"429":{"description":"Per-key rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, per RFC 9110. Mirrors `error.retryAfter` in the body.","schema":{"type":"integer","minimum":1,"example":60}}}},"500":{"description":"Unexpected server error. Provide requestId to Dashboardly support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}}},"security":[{"bearer":[]}],"summary":"Read a prepared Custom P&L evaluation","tags":["Developer API v1"]}},"/api/developer/v1/sales-profit":{"get":{"description":"Complete, paginated Sales & Profit rows at product or SKU grain plus the matching canonical summary and data-quality metadata. The response preserves every profitability field returned by the canonical MCP export path.","operationId":"getSalesProfit","parameters":[{"name":"shopId","required":false,"in":"query","description":"Shop UUID. Optional. Required only when a merchant-wide key has more than one shop. A shop-scoped key may omit it (or pass its own shop).","schema":{"format":"uuid","example":"f47ac10b-58cc-4372-a567-0e02b2c3d479","type":"string"}},{"name":"startDate","required":true,"in":"query","description":"Inclusive start date (YYYY-MM-DD), interpreted in the shop timezone.","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-06-01","type":"string"}},{"name":"endDate","required":true,"in":"query","description":"Inclusive end date (YYYY-MM-DD), interpreted in the shop timezone. Must be ≥ startDate and within the max range (365 days by default).","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-06-30","type":"string"}},{"name":"timezone","required":false,"in":"query","description":"IANA timezone override (e.g. \"America/New_York\"). Defaults to the shop timezone.","schema":{"example":"America/New_York","type":"string"}},{"name":"grain","required":false,"in":"query","description":"Return one row per product or one row per TikTok SKU.","schema":{"default":"product","type":"string","enum":["product","sku"]}},{"name":"limit","required":false,"in":"query","description":"Page size, 1–100. Defaults to 50.","schema":{"minimum":1,"maximum":100,"default":50,"type":"number"}},{"name":"offset","required":false,"in":"query","description":"Zero-based row offset. Must be a multiple of limit so pagination remains deterministic.","schema":{"minimum":0,"default":0,"type":"number"}},{"name":"search","required":false,"in":"query","description":"Product/SKU text search.","schema":{"type":"string"}},{"name":"productId","required":false,"in":"query","description":"Filter to one TikTok product ID.","schema":{"type":"string"}},{"name":"skuId","required":false,"in":"query","description":"Filter to one TikTok SKU ID.","schema":{"type":"string"}},{"name":"productIds","required":false,"in":"query","description":"Comma-separated or repeated TikTok product IDs (maximum 100).","schema":{"type":"array","items":{"type":"string"}}},{"name":"skuIds","required":false,"in":"query","description":"Comma-separated or repeated TikTok SKU IDs (maximum 100).","schema":{"type":"array","items":{"type":"string"}}},{"name":"includeSampleCosts","required":false,"in":"query","description":"Include sample-order costs in the canonical profitability calculation.","schema":{"default":false,"type":"boolean"}}],"responses":{"200":{"description":"Product/SKU profitability page wrapped in the standard envelope.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/DeveloperSalesProfitData"},"meta":{"$ref":"#/components/schemas/DeveloperMeta"}}}}}},"400":{"description":"Invalid query, body, shop selection, or idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"401":{"description":"Missing/invalid/expired/revoked key or missing read permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"403":{"description":"Account not API-entitled, or shop outside the key scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"404":{"description":"The selected shop or resource was not found in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"409":{"description":"Disconnected shop, feature conflict, or idempotency conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"429":{"description":"Per-key rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, per RFC 9110. Mirrors `error.retryAfter` in the body.","schema":{"type":"integer","minimum":1,"example":60}}}},"500":{"description":"Unexpected server error. Provide requestId to Dashboardly support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}}},"security":[{"bearer":[]}],"summary":"Export product or SKU profitability","tags":["Developer API v1"]}},"/api/developer/v1/orders":{"get":{"description":"Sanitized, paginated orders for the date range. Excludes buyer PII (no email, name, phone, address, tracking). Page size is capped at 100. By default, every row exposes all 67 Orders dashboard columns as top-level fields plus canonical financials, signed TikTok transaction breakdown, and SKU-level ledger. Pass includeFinancials=false only for a lightweight status/item lookup.","operationId":"getOrders","parameters":[{"name":"shopId","required":false,"in":"query","description":"Shop UUID. Optional. Required only when a merchant-wide key has more than one shop. A shop-scoped key may omit it (or pass its own shop).","schema":{"format":"uuid","example":"f47ac10b-58cc-4372-a567-0e02b2c3d479","type":"string"}},{"name":"startDate","required":true,"in":"query","description":"Inclusive start date (YYYY-MM-DD), interpreted in the shop timezone.","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-06-01","type":"string"}},{"name":"endDate","required":true,"in":"query","description":"Inclusive end date (YYYY-MM-DD), interpreted in the shop timezone. Must be ≥ startDate and within the max range (365 days by default).","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-06-30","type":"string"}},{"name":"timezone","required":false,"in":"query","description":"IANA timezone override (e.g. \"America/New_York\"). Defaults to the shop timezone.","schema":{"example":"America/New_York","type":"string"}},{"name":"includeFinancials","required":false,"in":"query","description":"Include the complete PII-safe 67-column Orders dashboard row, canonical financials, signed TikTok transaction breakdown, and SKU-level ledger. Defaults to true. Set false only for a lightweight status/item lookup.","schema":{"default":true,"example":true,"type":"boolean"}},{"name":"status","required":false,"in":"query","description":"Filter by order status. Omit for all statuses.","schema":{"example":"COMPLETED","type":"string","enum":["UNPAID","ON_HOLD","AWAITING_SHIPMENT","PARTIALLY_SHIPPING","AWAITING_COLLECTION","IN_TRANSIT","DELIVERED","COMPLETED","CANCELLED"]}},{"name":"limit","required":false,"in":"query","description":"Page size, 1–100. Defaults to 50.","schema":{"minimum":1,"maximum":100,"default":50,"example":50,"type":"number"}},{"name":"offset","required":false,"in":"query","description":"Pagination offset (≥0). Combine with limit to page through results.","schema":{"minimum":0,"default":0,"example":0,"type":"number"}}],"responses":{"200":{"description":"Orders page wrapped in the standard envelope.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/DeveloperOrdersData"},"meta":{"$ref":"#/components/schemas/DeveloperMeta"}}}}}},"400":{"description":"Invalid query, body, shop selection, or idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"401":{"description":"Missing/invalid/expired/revoked key or missing read permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"403":{"description":"Account not API-entitled, or shop outside the key scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"404":{"description":"The selected shop or resource was not found in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"409":{"description":"Disconnected shop, feature conflict, or idempotency conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"429":{"description":"Per-key rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, per RFC 9110. Mirrors `error.retryAfter` in the body.","schema":{"type":"integer","minimum":1,"example":60}}}},"500":{"description":"Unexpected server error. Provide requestId to Dashboardly support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}}},"security":[{"bearer":[]}],"summary":"List orders","tags":["Developer API v1"]}},"/api/developer/v1/costs":{"post":{"description":"Writes up to 1,000 dated Unit COG periods through the same canonical timeline as Inventory. Requires a shop-scoped API key with write:costs permission and an Idempotency-Key header.","operationId":"importCosts","parameters":[{"name":"idempotency-key","required":true,"in":"header","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated key, 8-128 chars of [A-Za-z0-9._:-]. Retrying with the same key and body replays the stored result (`replayed: true`) instead of applying the timeline twice; the same key with a different body returns 409.","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperCostImportDto"}}}},"responses":{"201":{"description":"COGS periods applied and wrapped in the standard envelope.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/DeveloperCostImportResultData"},"meta":{"$ref":"#/components/schemas/DeveloperMeta"}}}}}},"400":{"description":"Invalid query, body, shop selection, or idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"401":{"description":"Missing/invalid/expired/revoked key or missing read permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"403":{"description":"Account not API-entitled, or shop outside the key scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"404":{"description":"The selected shop or resource was not found in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"409":{"description":"Disconnected shop, feature conflict, or idempotency conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}},"429":{"description":"Per-key rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, per RFC 9110. Mirrors `error.retryAfter` in the body.","schema":{"type":"integer","minimum":1,"example":60}}}},"500":{"description":"Unexpected server error. Provide requestId to Dashboardly support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorEnvelope"}}}}},"security":[{"bearer":[]}],"summary":"Import dated product or SKU COGS","tags":["Developer API v1"]}}},"info":{"title":"Dashboardly Developer REST API","description":"\nDashboardly Developer REST API is a standard JSON/HTTP integration surface for\neligible accounts. It is separate from the MCP transport used by AI assistants.\n\n## Quick start\n\n1. In Dashboardly, open **Settings -> API Keys** as the account owner/admin.\n2. Create a key and enable **Developer REST API**. Scope write-enabled keys to\n   one shop. The secret is shown once.\n3. Send the secret as `Authorization: Bearer dk_live_...`.\n4. Call `GET /api/developer/v1/account`, then `GET /api/developer/v1/shops`.\n5. Pass `shopId` on report requests when a merchant-wide key can access more\n   than one connected shop.\n\n## Authorization and permissions\n\nEvery request must satisfy all of these checks:\n\n- The API key is active, unexpired, and has `read:developer-api`.\n- The owning account has Developer API access enabled and either a current\n  Agency plan or an operator-approved exception on a current plan.\n- Report routes have their module permission, such as `read:orders` or\n  `read:marketing`.\n- Write routes have either `write:costs` or\n  `write:manual-adjustments`, and the key is scoped to one shop.\n\n## Contract\n\n- **Success:** `{ \"data\": ..., \"meta\": { \"requestId\", \"generatedAt\", \"shopId\", ... } }`\n- **Error:** `{ \"error\": { \"code\", \"message\", \"details\"? }, \"meta\": { \"requestId\", \"generatedAt\" } }`\n- **Dates:** inclusive `YYYY-MM-DD` calendar dates in the shop's IANA timezone.\n- **Pagination:** `limit`, `offset`, `total`, and `hasMore` in\n  `meta.pagination`.\n\n## Safety and privacy\n\n- Orders exclude buyer names, emails, phone numbers, street addresses, and\n  tracking identifiers.\n- Customer routes return stable account-local pseudonyms and deliberately\n  provide no raw-email or name search.\n- Manual-adjustment creation requires an `Idempotency-Key`. Retrying the same\n  body with the same key returns the original result.\n- Each key is rate-limited. Usage auditing is best-effort operational telemetry;\n  authentication failures remain covered by application security logs and rate\n  limits.\n- Swagger UI does not persist authorization. Use a temporary, least-privilege\n  test key in Try it out and never paste a production key into a shared browser.\n\n## Support\n\n[Read the setup guide](https://help.dashboardly.io/features/developer-rest-api)\nor [book an onboarding call](https://cal.com/dashboardly/onboarding).\n","version":"1.0","contact":{}},"tags":[{"name":"Developer API v1","description":"Private REST/JSON integration API for eligible accounts. Separate from MCP."}],"servers":[{"url":"https://api.dashboardly.io","description":"Production"}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"Dashboardly API key","type":"http","description":"Dashboardly API key beginning with dk_live_. Do not expose it in browser code."}},"schemas":{"CommissionTierDto":{"type":"object","properties":{"upTo":{"type":"number","description":"Cumulative upper bound for this band. Omit/null only for the final unbounded tier.","example":100000,"nullable":true},"rate":{"type":"number","description":"Percentage applied only to the metric value inside this band","example":7}},"required":["rate"],"additionalProperties":false},"DeveloperSkuAmountDto":{"type":"object","properties":{"skuId":{"type":"string","description":"SKU ID from the selected shop.","example":"SKU12345"},"amount":{"type":"number","description":"Positive allocation magnitude, at most 2 decimal places. Allocations must sum exactly to the parent amount.","example":100.5,"minimum":0.01,"maximum":99999999.99,"multipleOf":0.01}},"required":["skuId","amount"],"additionalProperties":false},"DeveloperAdjustmentRequestDto":{"type":"object","properties":{"category":{"type":"string","description":"The category of the adjustment","enum":["","SUPPLY_COSTS","AD_COSTS","OTHER","TAXES","MARKETING_COSTS","FULFILLMENT_FEES","SHIPPING_COSTS","FBS_MANUAL_SHIPPING","INBOUND_SHIPPING","PACKAGING_MATERIALS","CUSTOMER_REFUNDS","RETURN_SHIPPING","DAMAGED_GOODS","PLATFORM_FEES","PAYMENT_GATEWAY_FEES","STAFF_COSTS","LEGAL_FEES","VAT_GST","INTERNET_UTILITIES","SOFTWARE_SUBSCRIPTIONS","INVENTORY_PURCHASES","INVENTORY_WRITE_OFFS","INVENTORY_RESTOCK_CREDIT","ONE_TIME_REVENUE","AFFILIATE_COMMISSION","AGENCY_FEE"],"example":"OTHER"},"adjustment_type":{"type":"string","description":"The type of adjustment","enum":["expenses","income"],"example":"income"},"skuDistributionMethod":{"type":"string","description":"Distribution method for multi-SKU adjustments (EQUAL = split evenly, CUSTOM = specify per SKU)","enum":["EQUAL","CUSTOM"],"example":"EQUAL"},"adjustment_recurrence_type":{"type":"string","description":"The recurrence type for the adjustment","enum":["One_Time","Daily","Weekly","Monthly","Yearly"],"example":"One_Time"},"is_formula":{"type":"boolean","description":"Whether this adjustment uses a formula (fixed + percentage)","example":false},"percentage_rate":{"type":"number","description":"Percentage rate for formula adjustments (0-100)","example":4},"percentage_metric":{"type":"string","description":"Metric to apply percentage to (required when percentage_rate > 0)","enum":["GMV","GMV_WITH_SUBSIDIES","REVENUE","NET_SALES","SELLER_CREDITED_NET_SALES"],"example":"GMV"},"commission_tiers":{"description":"Progressive marginal commission tiers. When present, these replace percentage_rate.","example":[{"upTo":100000,"rate":7},{"upTo":200000,"rate":6},{"upTo":null,"rate":5}],"type":"array","items":{"$ref":"#/components/schemas/CommissionTierDto"}},"allocation_mode":{"type":"string","description":"Allocation mode: FIXED (default) for flat amounts, PER_ORDER for per-order rate","enum":["FIXED","PER_ORDER"],"example":"FIXED"},"order_scope":{"type":"string","description":"Order scope for PER_ORDER mode: which orders to count (REGULAR_ONLY, ALL_ORDERS, SAMPLES_ONLY)","enum":["REGULAR_ONLY","ALL_ORDERS","SAMPLES_ONLY"],"example":"REGULAR_ONLY"},"suppress_tiktok_shipping":{"type":"boolean","description":"When true, TikTok estimated shipping is replaced by this per-order rate (only for FBS_MANUAL_SHIPPING + PER_ORDER)","example":true},"name":{"type":"string","example":"Monthly accounting software"},"date":{"type":"string","description":"Inclusive local accounting date in YYYY-MM-DD format.","example":"2026-08-01","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"endDate":{"type":"string","description":"Inclusive local end date for a recurring adjustment (YYYY-MM-DD).","example":"2026-12-31","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"amount":{"type":"number","description":"Absolute amount, at most 2 decimal places (stored as Decimal(10,2)). Expense/income determines the stored sign.","minimum":0,"maximum":99999999.99,"multipleOf":0.01,"example":99},"productId":{"type":"string","maxLength":255},"skuId":{"type":"string","maxLength":255,"deprecated":true},"skuIds":{"maxItems":500,"type":"array","items":{"type":"string"}},"skuAmounts":{"maxItems":500,"description":"CUSTOM distribution amounts. Every entry must reference an ID also present in skuIds.","type":"array","items":{"$ref":"#/components/schemas/DeveloperSkuAmountDto"}},"orderIds":{"maxItems":500,"description":"TikTok order IDs, as returned by GET /orders (`orderId`). Used by FBS_MANUAL_SHIPPING adjustments to bind specific orders.","example":["576123456789012345"],"type":"array","items":{"type":"string"}},"timezone":{"type":"string","description":"Valid IANA timezone used for adjustment date calculations.","example":"America/New_York","maxLength":64}},"required":["category","adjustment_type","name","date","amount"],"additionalProperties":false},"DeveloperCostItemDto":{"type":"object","properties":{"productId":{"type":"string","maxLength":64},"skuId":{"type":"string","maxLength":64},"unitCog":{"type":"number","minimum":0.01,"maximum":999999.99,"multipleOf":0.000001,"description":"Dated unit cost of goods. Between 0.01 and 999999.99 with at most 6 decimal places. Zero is not accepted on this dated-period route.","example":12.5},"effectiveDate":{"type":"string","description":"Inclusive local effective date in YYYY-MM-DD format.","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-08-01"}},"required":["productId","unitCog","effectiveDate"],"additionalProperties":false},"DeveloperCostImportDto":{"type":"object","properties":{"shopId":{"type":"string","format":"uuid"},"items":{"maxItems":1000,"minItems":1,"type":"array","items":{"$ref":"#/components/schemas/DeveloperCostItemDto"}}},"required":["items"],"additionalProperties":false},"DeveloperAdditiveMetric":{"description":"Value type for fields a canonical Dashboardly module adds additively inside v1. Scalar only — a new nested object or array is a contract change, not an additive field.","anyOf":[{"type":"string","nullable":true},{"type":"number","format":"double"},{"type":"boolean"}]},"DeveloperShop":{"type":"object","additionalProperties":false,"required":["id","name","region","currency","timezone","isDisconnected"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"region":{"type":"string","nullable":true},"currency":{"type":"string","nullable":true,"example":"USD"},"timezone":{"type":"string","example":"America/New_York"},"sellerType":{"type":"string","nullable":true},"isDisconnected":{"type":"boolean"}}},"DeveloperAccountData":{"type":"object","additionalProperties":false,"required":["merchantId","isAgency","plan","key","shopCount"],"properties":{"merchantId":{"type":"string","format":"uuid"},"isAgency":{"type":"boolean"},"plan":{"type":"object","additionalProperties":false,"required":["name"],"properties":{"name":{"type":"string"}}},"key":{"type":"object","additionalProperties":false,"required":["prefix","permissions","scope","scopedShopId"],"properties":{"prefix":{"type":"string","example":"dk_live_abcd"},"permissions":{"type":"array","items":{"type":"string"}},"scope":{"type":"string","enum":["merchant","shop"]},"scopedShopId":{"type":"string","format":"uuid","nullable":true}}},"shopCount":{"type":"integer","minimum":0}}},"DeveloperShopsData":{"type":"object","additionalProperties":false,"required":["shops"],"properties":{"shops":{"type":"array","items":{"$ref":"#/components/schemas/DeveloperShop"}}}},"DeveloperDashboardMetrics":{"type":"object","additionalProperties":false,"required":["grossSales","netSales","grossProfit","operatingProfit","netProfit","costOfGoodsSold","adSpend","gmv","refundsAndReturns","unitsSold","orders","averageOrderValue"],"properties":{"grossSales":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"netSales":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"grossProfit":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"operatingProfit":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"netProfit":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"costOfGoodsSold":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"adSpend":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"gmv":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"refundsAndReturns":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"unitsSold":{"type":"number","format":"double"},"orders":{"type":"integer"},"averageOrderValue":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"grossMargin":{"type":"number","format":"double","description":"Percent.","nullable":true},"operatingMargin":{"type":"number","format":"double","description":"Percent.","nullable":true},"netMargin":{"type":"number","format":"double","description":"Percent.","nullable":true},"roi":{"type":"number","format":"double","description":"Percent.","nullable":true}}},"DeveloperDashboardSummaryData":{"type":"object","additionalProperties":false,"required":["metrics","ordersByStatus","pendingOrders","estimatedData"],"properties":{"metrics":{"$ref":"#/components/schemas/DeveloperDashboardMetrics"},"ordersByStatus":{"type":"object","additionalProperties":{"type":"integer","minimum":0},"description":"Order count per canonical status. Keys are statuses present in the window."},"pendingOrders":{"type":"integer","minimum":0},"estimatedData":{"type":"object","additionalProperties":false,"required":["hasEstimatedData","estimatedOrderCount","totalOrderCount","estimatedPercentage"],"properties":{"hasEstimatedData":{"type":"boolean"},"estimatedOrderCount":{"type":"integer"},"totalOrderCount":{"type":"integer"},"estimatedPercentage":{"type":"number","format":"double"}}}}},"DeveloperTopProductRow":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/DeveloperAdditiveMetric"},"required":["productId","productName","totalSales","totalUnits","percentage"],"properties":{"productId":{"type":"string"},"productName":{"type":"string"},"skuImage":{"type":"string","nullable":true,"description":"Product image URL when TikTok supplied one."},"totalSales":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"totalUnits":{"type":"number","format":"double"},"percentage":{"type":"number","format":"double","description":"Share of `totalSales`, percent."}}},"DeveloperTopProductsData":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/DeveloperAdditiveMetric"},"required":["products","totalSales","periodTotalSales","timePeriod"],"properties":{"products":{"type":"array","items":{"$ref":"#/components/schemas/DeveloperTopProductRow"}},"totalSales":{"type":"number","format":"double","description":"Sum of sales across ONLY the returned products. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"periodTotalSales":{"type":"number","format":"double","description":"Sum of sales across ALL products in the period, same basis and window as `totalSales`. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"timePeriod":{"type":"string","enum":["week","month","year"]},"salesScope":{"type":"string"},"salesScopeApplied":{"type":"boolean"},"salesScopeReason":{"type":"string"},"salesScopeStats":{"$ref":"#/components/schemas/DeveloperAdditiveMetric"}}},"DeveloperOrderStatusRow":{"type":"object","additionalProperties":false,"required":["status","count","percentage"],"properties":{"status":{"type":"string","example":"COMPLETED"},"count":{"type":"integer","minimum":0},"percentage":{"type":"integer","minimum":0,"maximum":100}}},"DeveloperOrderStatisticsData":{"type":"object","additionalProperties":false,"description":"Exact payload returned by OrdersService.getOrderStatisticsByStatus.","required":["success","data","total"],"properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/DeveloperOrderStatusRow"},"description":"One row per canonical status, zero-filled, plus any real status not in the canonical list."},"total":{"type":"integer","minimum":0}}},"DeveloperOrderGeographyData":{"type":"object","additionalProperties":false,"required":["breakdown","total","privacy"],"properties":{"breakdown":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["region","orders","revenue"],"properties":{"region":{"type":"string"},"orders":{"type":"integer"},"revenue":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."}}}},"total":{"type":"object","additionalProperties":false,"required":["orders","revenue"],"properties":{"orders":{"type":"integer"},"revenue":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."}}},"privacy":{"type":"object","additionalProperties":false,"required":["minimumOrdersPerNamedRegion"],"properties":{"minimumOrdersPerNamedRegion":{"type":"integer"}}}}},"DeveloperHourlyOrdersData":{"type":"object","additionalProperties":false,"required":["hours","timezone","total"],"properties":{"hours":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["hour","orders","revenue"],"properties":{"hour":{"type":"string","description":"Local wall-clock hour in the `timezone` field of this response. Deliberately carries no UTC offset and no \"Z\" suffix: \"2026-08-12T14:00\" means 14:00 shop-local, never 14:00 UTC. Each order is bucketed by its shop-local hour, so an order created at 2026-08-13T01:30Z in America/New_York appears under \"2026-08-12T21:00\".","example":"2026-08-12T14:00"},"orders":{"type":"integer"},"revenue":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."}}}},"timezone":{"type":"string","description":"IANA timezone every `hour` key is expressed in — the shop timezone unless the request supplied a valid `timezone` override.","example":"America/New_York"},"total":{"type":"object","additionalProperties":false,"required":["orders","revenue"],"properties":{"orders":{"type":"integer"},"revenue":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."}}}}},"DeveloperRefundTotals":{"type":"object","additionalProperties":false,"required":["refundOrders","refundUnits","returns","refunds","replacements","grossSalesRefund","otherRefundCosts"],"properties":{"refundOrders":{"type":"integer","description":"Refunded orders completed in the window."},"refundUnits":{"type":"integer","description":"Units across those refunds."},"returns":{"type":"integer","description":"Items returned."},"refunds":{"type":"integer","description":"Items refunded."},"replacements":{"type":"integer","description":"Items replaced."},"grossSalesRefund":{"type":"number","format":"double","description":"Total refunded sales amount. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"otherRefundCosts":{"type":"number","format":"double","description":"Additional refund-side costs (shipping, etc.). Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."}}},"DeveloperRefundSummaryData":{"type":"object","additionalProperties":false,"description":"Canonical refund and return quantity summary for the selected window.","required":["refundOrders","refundUnits","returns","refunds","replacements","grossSalesRefund","otherRefundCosts"],"properties":{"refundOrders":{"type":"integer","description":"Refunded orders completed in the window."},"refundUnits":{"type":"integer","description":"Units across those refunds."},"returns":{"type":"integer","description":"Items returned."},"refunds":{"type":"integer","description":"Items refunded."},"replacements":{"type":"integer","description":"Items replaced."},"grossSalesRefund":{"type":"number","format":"double","description":"Total refunded sales amount. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"otherRefundCosts":{"type":"number","format":"double","description":"Additional refund-side costs (shipping, etc.). Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"byPeriod":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/DeveloperRefundTotals"},"description":"Present only for period-split requests. Keyed by period key."}}},"DeveloperInventoryItem":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/DeveloperAdditiveMetric"},"description":"Inventory product/SKU row. Canonical inventory adds scalar metrics additively inside v1.","properties":{"productId":{"type":"string","nullable":true},"skuId":{"type":"string","nullable":true},"productName":{"type":"string","nullable":true},"skuName":{"type":"string","nullable":true},"sellerSku":{"type":"string","nullable":true},"availableStock":{"type":"integer","nullable":true},"committedStock":{"type":"integer","nullable":true},"inboundStock":{"type":"integer","nullable":true},"cog":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization.","nullable":true},"inventoryValue":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization.","nullable":true},"estSales":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization.","nullable":true},"estProfit":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization.","nullable":true},"roi":{"type":"number","format":"double","nullable":true},"unitsSold30Days":{"type":"integer","nullable":true},"unitsSold90Days":{"type":"integer","nullable":true},"datedCogs":{"type":"array","nullable":true,"description":"Dated cost timeline entries covering the snapshot, when requested.","items":{"type":"object","additionalProperties":false,"required":["effectiveFrom","cost"],"properties":{"effectiveFrom":{"type":"string","format":"date-time"},"effectiveTo":{"type":"string","format":"date-time","nullable":true},"cost":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."}}}}}},"DeveloperInventoryFilteredTotals":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/DeveloperAdditiveMetric"},"description":"Totals recomputed over the filtered/paged population only.","properties":{"totalProducts":{"type":"integer","nullable":true},"totalAvailableStock":{"type":"integer","nullable":true},"totalInventoryValue":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization.","nullable":true},"totalCog":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization.","nullable":true},"totalEstSales":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization.","nullable":true},"totalEstProfit":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization.","nullable":true}}},"DeveloperInventorySummaryData":{"type":"object","additionalProperties":false,"description":"Inventory totals plus optional product/SKU rows and dated COGS coverage.","required":["snapshotDate","totalProducts","totalAvailableStock","totalCommittedStock","totalInboundStock","totalInventoryValue","totalEstSales","totalEstProfit","totalEstFbtStorageFee","totalShippingCost","totalCog","avgRoi","totalUnitsSold30Days","totalUnitsSold90Days","totalPhysicalUnitsSold30Days","totalPhysicalUnitsSold90Days","totalResearching","totalUnfulfillable","totalStrandedInventory","avgDailyUnits30Days","avgDailyUnits90Days","avgDailyPhysicalUnits30Days","avgDailyPhysicalUnits90Days","stock","createdAt","updatedAt"],"properties":{"snapshotDate":{"type":"string","format":"date-time"},"totalProducts":{"type":"integer"},"totalAvailableStock":{"type":"integer"},"totalCommittedStock":{"type":"integer"},"totalInboundStock":{"type":"integer"},"totalInventoryValue":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization.","nullable":true},"totalEstSales":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"totalEstProfit":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization.","nullable":true},"totalEstFbtStorageFee":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization.","nullable":true},"totalEstMonthlyStorageFee":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization.","nullable":true},"totalShippingCost":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"totalCog":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization.","nullable":true},"avgRoi":{"type":"number","format":"double","nullable":true},"totalUnitsSold30Days":{"type":"integer"},"totalUnitsSold90Days":{"type":"integer"},"totalPhysicalUnitsSold30Days":{"type":"integer"},"totalPhysicalUnitsSold90Days":{"type":"integer"},"totalResearching":{"type":"integer"},"totalUnfulfillable":{"type":"integer"},"totalStrandedInventory":{"type":"integer"},"avgDailyUnits30Days":{"type":"number","format":"double"},"avgDailyUnits90Days":{"type":"number","format":"double"},"avgDailyPhysicalUnits30Days":{"type":"number","format":"double"},"avgDailyPhysicalUnits90Days":{"type":"number","format":"double"},"stock":{"type":"integer"},"totalFbtShippingCost":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization.","nullable":true},"totalFbsTikTokShippingCost":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization.","nullable":true},"totalFbsManualShippingCost":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization.","nullable":true},"totalFbsTotalStorageFee":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization.","nullable":true},"totalEstFbsFulfillmentFee":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization.","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"items":{"type":"array","items":{"$ref":"#/components/schemas/DeveloperInventoryItem"}},"filteredTotals":{"$ref":"#/components/schemas/DeveloperInventoryFilteredTotals"},"pagination":{"type":"object","additionalProperties":false,"required":["page","pageSize","total","totalPages"],"properties":{"page":{"type":"integer"},"pageSize":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}}}},"DeveloperWarehouseRow":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/DeveloperAdditiveMetric"},"description":"Canonical warehouse metadata plus configured fee components.","required":["warehouse_id","warehouse_name","warehouse_type","currency","storageAndWarehousing","fulfillmentAndOps","shippingAndCustoms","hasConfiguration","isActive"],"properties":{"warehouse_id":{"type":"string"},"warehouse_name":{"type":"string"},"custom_label":{"type":"string","nullable":true},"warehouse_type":{"type":"string"},"warehouse_state":{"type":"string"},"warehouse_effect_status":{"type":"string"},"currency":{"type":"string","example":"USD"},"notes":{"type":"string","nullable":true},"storageAndWarehousing":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"fulfillmentAndOps":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"shippingAndCustoms":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"hasConfiguration":{"type":"boolean"},"isActive":{"type":"boolean"},"minimumMonthlyCost":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."}}},"DeveloperWarehouseAnalytics":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/DeveloperAdditiveMetric"},"required":["totalWarehouses","configuredWarehouses"],"properties":{"totalWarehouses":{"type":"integer"},"configuredWarehouses":{"type":"integer"},"totalMonthlyStorage":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"averageStorageCost":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"currencyDistribution":{"type":"object","additionalProperties":{"type":"integer","minimum":0},"description":"Warehouse count per ISO currency code."}}},"DeveloperWarehouseSkuFee":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/DeveloperAdditiveMetric"},"description":"One warehouse x SKU fee row from the strict database-paginated read.","properties":{"warehouseId":{"type":"string","nullable":true},"warehouseName":{"type":"string","nullable":true},"skuId":{"type":"string","nullable":true},"sellerSku":{"type":"string","nullable":true},"productName":{"type":"string","nullable":true},"currency":{"type":"string","nullable":true},"storageAndWarehousing":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization.","nullable":true},"fulfillmentAndOps":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization.","nullable":true},"shippingAndCustoms":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization.","nullable":true},"totalFee":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization.","nullable":true}}},"DeveloperWarehouseSummaryData":{"type":"object","additionalProperties":false,"description":"Warehouse metadata and fulfilment-fee analytics. Served entirely from locally imported and cached warehouse facts: the request performs no upstream TikTok Shop call and no refresh, so the data is as fresh as the last completed import.","required":["warehouses","analytics"],"properties":{"warehouses":{"type":"array","items":{"$ref":"#/components/schemas/DeveloperWarehouseRow"}},"analytics":{"$ref":"#/components/schemas/DeveloperWarehouseAnalytics"},"skuFees":{"type":"array","items":{"$ref":"#/components/schemas/DeveloperWarehouseSkuFee"},"description":"Present only when includeSkuFees=true."},"skuFeePagination":{"type":"object","additionalProperties":false,"required":["total","page","pageSize","totalPages"],"properties":{"total":{"type":"integer"},"page":{"type":"integer"},"pageSize":{"type":"integer"},"totalPages":{"type":"integer"}}}}},"DeveloperCashflowProjection":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/DeveloperAdditiveMetric"},"description":"Canonical settlement-anchored cash projection for the requested window.","properties":{"currency":{"type":"string","nullable":true},"basis":{"type":"string","enum":["payout","accrual"]},"cashDateMode":{"type":"string"},"granularity":{"type":"string","enum":["day","week","month"]},"periods":{"type":"array","items":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/DeveloperAdditiveMetric"},"required":["periodKey"],"properties":{"periodKey":{"type":"string"},"periodStart":{"type":"string","format":"date-time","nullable":true},"periodEnd":{"type":"string","format":"date-time","nullable":true},"inflow":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization.","nullable":true},"outflow":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization.","nullable":true},"net":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization.","nullable":true}}}},"totals":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/DeveloperAdditiveMetric"},"properties":{"inflow":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization.","nullable":true},"outflow":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization.","nullable":true},"net":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization.","nullable":true}}}}},"DeveloperCashflowLedgerRow":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/DeveloperAdditiveMetric"},"description":"One settlement ledger line. Contains no buyer identity.","properties":{"id":{"type":"string","nullable":true},"cashDate":{"type":"string","format":"date-time","nullable":true},"type":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"amount":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization.","nullable":true},"currency":{"type":"string","nullable":true},"orderId":{"type":"string","nullable":true},"statementId":{"type":"string","nullable":true}}},"DeveloperCashflowLedger":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/DeveloperAdditiveMetric"},"required":["total","page","pageSize","rows"],"properties":{"currency":{"type":"string","nullable":true},"total":{"type":"integer"},"page":{"type":"integer"},"pageSize":{"type":"integer"},"rows":{"type":"array","items":{"$ref":"#/components/schemas/DeveloperCashflowLedgerRow"}}}},"DeveloperCashflowSummaryData":{"type":"object","additionalProperties":false,"description":"Ledger is present only when includeLedger=true.","required":["projection"],"properties":{"projection":{"$ref":"#/components/schemas/DeveloperCashflowProjection"},"ledger":{"$ref":"#/components/schemas/DeveloperCashflowLedger"}}},"DeveloperManualAdjustment":{"type":"object","additionalProperties":false,"required":["id","name","category","date","amount"],"properties":{"id":{"type":"integer"},"name":{"type":"string"},"category":{"type":"string"},"date":{"type":"string","format":"date-time"},"endDate":{"type":"string","format":"date-time","nullable":true},"type":{"type":"string","nullable":true},"adjustment_type":{"type":"string","nullable":true},"amount":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"productId":{"type":"string","nullable":true},"skuId":{"type":"string","nullable":true},"isPast":{"type":"boolean"},"isVirtual":{"type":"boolean"},"periodLabel":{"type":"string"},"parentId":{"type":"integer","nullable":true},"percentage_rate":{"type":"number","format":"double","nullable":true},"percentage_metric":{"type":"string","nullable":true},"commission_tiers":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/CommissionTierDto"},"description":"Progressive marginal commission tiers. Each bounded upTo value is a cumulative ceiling; the final tier may be unbounded."},"calculated_amount":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization.","nullable":true},"formula_display":{"type":"string","nullable":true},"is_formula":{"type":"boolean"},"recurrenceType":{"type":"string","nullable":true},"adjustment_recurrence_type":{"type":"string","nullable":true},"isSuspended":{"type":"boolean"},"suspendedAt":{"type":"string","format":"date-time","nullable":true},"hasInventoryDefault":{"type":"boolean"},"inventoryDefaultAmount":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"distribution_mode":{"type":"string"},"exclude_weekends":{"type":"boolean"},"sales_days_only":{"type":"boolean"},"sku_distribution_method":{"type":"string"},"allocation_mode":{"type":"string"},"order_scope":{"type":"string"},"perOrderRate":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"suppress_tiktok_shipping":{"type":"boolean"},"adjustmentSkus":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["skuId","amount"],"properties":{"skuId":{"type":"string"},"amount":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization.","nullable":true}}}},"adjustmentOrders":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["orderId"],"properties":{"orderId":{"type":"string"}}}}}},"DeveloperManualAdjustmentsData":{"type":"object","additionalProperties":false,"required":["data","currentPage","totalPages"],"properties":{"data":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["month","entries"],"properties":{"month":{"type":"string","pattern":"^\\d{4}-\\d{2}$"},"entries":{"type":"array","items":{"$ref":"#/components/schemas/DeveloperManualAdjustment"}}}}},"currentPage":{"type":"integer"},"totalPages":{"type":"integer"}}},"DeveloperManualAdjustmentData":{"type":"object","additionalProperties":false,"required":["adjustment"],"properties":{"adjustment":{"$ref":"#/components/schemas/DeveloperManualAdjustment"}}},"DeveloperManualAdjustmentMutationData":{"type":"object","additionalProperties":false,"required":["adjustment"],"properties":{"adjustment":{"$ref":"#/components/schemas/DeveloperManualAdjustment"},"replayed":{"type":"boolean"}}},"DeveloperDeleteData":{"type":"object","additionalProperties":false,"required":["deleted","id"],"properties":{"deleted":{"type":"boolean"},"id":{"type":"integer"}}},"DeveloperCustomer":{"type":"object","additionalProperties":false,"required":["customerId"],"properties":{"customerId":{"type":"string","pattern":"^cust_[a-f0-9]{24}$","description":"Stable account-local pseudonym, not a buyer identifier."},"totalOrders":{"type":"integer"},"completedOrders":{"type":"integer"},"cancelledOrders":{"type":"integer"},"returnedOrders":{"type":"integer"},"totalRevenue":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"averageOrderValue":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"totalRefunds":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"netRevenue":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"purchaseFrequency":{"type":"number","format":"double"},"daysSinceFirstOrder":{"type":"integer"},"daysSinceLastOrder":{"type":"integer"},"lifetimeValue":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"projectedLTV":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"firstOrderDate":{"type":"string","format":"date-time","nullable":true},"lastOrderDate":{"type":"string","format":"date-time","nullable":true},"customerSegment":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"DeveloperTopCustomer":{"type":"object","additionalProperties":false,"required":["customerId","orderCount","revenue"],"properties":{"customerId":{"type":"string","pattern":"^cust_[a-f0-9]{24}$","description":"Stable pseudonym, namespaced per merchant account. The same buyer yields different ids in different accounts."},"orderCount":{"type":"integer","description":"Orders inside the requested window only."},"revenue":{"type":"number","format":"double","description":"Revenue from in-window orders only. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"firstOrderInWindowAt":{"type":"string","format":"date-time","nullable":true},"lastOrderInWindowAt":{"type":"string","format":"date-time","nullable":true}}},"DeveloperCustomerSummaryData":{"type":"object","additionalProperties":false,"required":["summary","topCustomers"],"properties":{"summary":{"type":"object","additionalProperties":false,"required":["totalCustomers","newCustomers","repeatCustomers","repeatRate","totalRevenue","totalOrders","avgOrdersPerCustomer"],"properties":{"totalCustomers":{"type":"integer","description":"Distinct buyers with at least one non-cancelled order INSIDE the window."},"newCustomers":{"type":"integer","description":"Subset whose first-ever order for this shop falls inside the window. This is the only lifetime-derived field."},"repeatCustomers":{"type":"integer","description":"Subset with more than one order inside the window."},"repeatRate":{"type":"number","format":"double","description":"repeatCustomers / totalCustomers, percent."},"totalRevenue":{"type":"number","format":"double","description":"Revenue from in-window orders only. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"totalOrders":{"type":"integer","description":"Non-cancelled orders inside the window."},"avgOrdersPerCustomer":{"type":"number","format":"double"}}},"topCustomers":{"type":"array","items":{"$ref":"#/components/schemas/DeveloperTopCustomer"}}}},"DeveloperCustomersData":{"type":"object","additionalProperties":false,"required":["customers"],"properties":{"customers":{"type":"array","items":{"$ref":"#/components/schemas/DeveloperCustomer"}}}},"DeveloperCustomerLifetimeData":{"type":"object","additionalProperties":false,"description":"Canonical historical or projected LTV response plus pseudonymized customer rows.","required":["customers"],"properties":{"customers":{"type":"array","items":{"$ref":"#/components/schemas/DeveloperCustomer"}},"summary":{"type":"object","additionalProperties":false,"required":["totalRevenue","percentageOfTotal"],"properties":{"totalRevenue":{"type":"number","format":"double","description":"Revenue across the returned customers. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"percentageOfTotal":{"type":"number","format":"double","description":"Their share of shop revenue on the same basis, percent."}}},"totalLifetimeValue":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."}}},"DeveloperCohortRetentionRow":{"type":"object","additionalProperties":false,"description":"One acquisition cohort and its month-by-month retention. Aggregate only; carries no buyer identifier.","required":["cohortMonth","totalCustomers","retentionByMonth"],"properties":{"cohortMonth":{"type":"string","description":"First-purchase month."},"totalCustomers":{"type":"integer","description":"Customers acquired in the cohort month."},"retentionByMonth":{"type":"object","additionalProperties":{"type":"number","format":"double","description":"Retention percentage, or null when not yet elapsed.","nullable":true},"description":"Keyed by months-after-first-purchase offset; values are retention percentages or null."}}},"DeveloperCohortRetentionSummary":{"type":"object","additionalProperties":false,"required":["totalCohorts"],"properties":{"totalCohorts":{"type":"integer"},"avgMonth1Retention":{"type":"number","format":"double","description":"Percent.","nullable":true},"avgMonth3Retention":{"type":"number","format":"double","description":"Percent.","nullable":true},"avgMonth6Retention":{"type":"number","format":"double","description":"Percent.","nullable":true}}},"DeveloperCohortFlowNodeMetadata":{"type":"object","additionalProperties":false,"properties":{"productCount":{"type":"integer","nullable":true},"customerCount":{"type":"integer","nullable":true},"revenue":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization.","nullable":true},"description":{"type":"string","nullable":true},"cohortMonth":{"type":"string","nullable":true}}},"DeveloperCohortFlowNode":{"type":"object","additionalProperties":false,"description":"Aggregate journey node (a product, SKU, category or brand) — never a buyer.","required":["nodeId","nodeName","nodeType"],"properties":{"nodeId":{"type":"string"},"nodeName":{"type":"string"},"nodeType":{"type":"string"},"averagePrice":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization.","nullable":true},"minPrice":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization.","nullable":true},"maxPrice":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization.","nullable":true},"metadata":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/DeveloperCohortFlowNodeMetadata"}]}}},"DeveloperCohortFlow":{"type":"object","additionalProperties":false,"required":["fromStage","toStage","customersCount","revenueSum","avgOrderValue"],"properties":{"fromStage":{"type":"integer"},"toStage":{"type":"integer"},"fromNode":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/DeveloperCohortFlowNode"}]},"toNode":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/DeveloperCohortFlowNode"}]},"customersCount":{"type":"integer"},"revenueSum":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"avgOrderValue":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."}}},"DeveloperCohortJourneyMetrics":{"type":"object","additionalProperties":false,"required":["totalCustomers","totalRevenue","avgCustomerValue"],"properties":{"cohortMonth":{"type":"string"},"totalCustomers":{"type":"integer"},"totalOrders":{"type":"integer"},"totalRevenue":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"averageOrderValue":{"type":"number","format":"double"},"avgFirstOrderValue":{"type":"number","format":"double"},"repeatPurchaseRate":{"type":"number","format":"double","description":"Percent."},"avgRetentionRate":{"type":"number","format":"double","description":"Percent."},"valuedOrders":{"type":"integer"},"missingValueOrders":{"type":"integer"},"avgCustomerValue":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."}}},"DeveloperCohortDropoff":{"type":"object","additionalProperties":false,"required":["stage","customersDropped","dropoffRate"],"properties":{"stage":{"type":"integer"},"customersDropped":{"type":"integer"},"dropoffRate":{"type":"number","format":"double","description":"Percent."}}},"DeveloperCohortJourneyRow":{"type":"object","additionalProperties":false,"required":["cohortMonth","flows","cohortMetrics","dropoffs"],"properties":{"cohortMonth":{"type":"string"},"flows":{"type":"array","items":{"$ref":"#/components/schemas/DeveloperCohortFlow"}},"cohortMetrics":{"$ref":"#/components/schemas/DeveloperCohortJourneyMetrics"},"dropoffs":{"type":"array","items":{"$ref":"#/components/schemas/DeveloperCohortDropoff"}}}},"DeveloperCohortJourneySummary":{"type":"object","additionalProperties":false,"required":["totalCohorts","totalCustomers","totalRevenue","avgCustomerValue"],"properties":{"totalCohorts":{"type":"integer"},"totalCustomers":{"type":"integer"},"totalOrders":{"type":"integer"},"totalRevenue":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"averageOrderValue":{"type":"number","format":"double"},"avgFirstOrderValue":{"type":"number","format":"double"},"repeatPurchaseRate":{"type":"number","format":"double","description":"Percent."},"avgRetentionRate":{"type":"number","format":"double","description":"Percent."},"valuedOrders":{"type":"integer"},"missingValueOrders":{"type":"integer"},"avgCustomerValue":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."}}},"DeveloperCohortJourneyConfig":{"type":"object","additionalProperties":false,"description":"Echo of the fixed journey configuration this API requests from the canonical service.","properties":{"nodeGranularity":{"type":"string","enum":["item","sku","category","brand"]},"attributionMode":{"type":"string"},"analysisWindowDays":{"type":"integer"},"maxDaysBetweenStages":{"type":"integer","nullable":true},"includeReturns":{"type":"boolean"},"customerSegment":{"type":"string","nullable":true},"topProductsCount":{"type":"integer"},"minCustomers":{"type":"integer"},"maxStages":{"type":"integer"},"topProductsPerStage":{"type":"integer"}}},"DeveloperCustomerCohortData":{"type":"object","additionalProperties":false,"description":"Aggregate retention cohorts or purchase-journey flows; no buyer identifiers are returned.","required":["analysis","cohorts"],"properties":{"analysis":{"type":"string","enum":["retention","journey"]},"cohorts":{"type":"array","items":{"anyOf":[{"$ref":"#/components/schemas/DeveloperCohortRetentionRow"},{"$ref":"#/components/schemas/DeveloperCohortJourneyRow"}]},"description":"Retention rows when analysis=retention, journey rows when analysis=journey."},"summary":{"anyOf":[{"$ref":"#/components/schemas/DeveloperCohortRetentionSummary"},{"$ref":"#/components/schemas/DeveloperCohortJourneySummary"}]},"config":{"$ref":"#/components/schemas/DeveloperCohortJourneyConfig"}}},"DeveloperMarketingKpiSummary":{"type":"object","additionalProperties":false,"required":["totalSpend","totalRevenue","overallROI","newCustomersGMV"],"properties":{"totalSpend":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"totalRevenue":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"overallROI":{"type":"number","format":"double","description":"ROAS multiplier (totalRevenue / totalSpend); 0 when spend is 0. Name kept for backward compatibility."},"newCustomersGMV":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"previousPeriod":{"type":"object","additionalProperties":false,"required":["totalSpend","totalRevenue","overallROI","newCustomersGMV"],"properties":{"totalSpend":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"totalRevenue":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"overallROI":{"type":"number","format":"double"},"newCustomersGMV":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."}},"nullable":true},"percentageChange":{"type":"object","additionalProperties":false,"properties":{"totalSpend":{"type":"number","format":"double"},"totalRevenue":{"type":"number","format":"double"},"overallROI":{"type":"number","format":"double"},"newCustomersGMV":{"type":"number","format":"double"}},"nullable":true}}},"DeveloperLiveStreamRow":{"type":"object","additionalProperties":false,"required":["streamId","streamName","date","gmv","viewers","conversionRate"],"properties":{"streamId":{"type":"string"},"streamName":{"type":"string"},"hostName":{"type":"string","nullable":true,"description":"Creator/host display name published by TikTok for the session. Not a buyer identity."},"date":{"type":"string"},"gmv":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"viewers":{"type":"integer"},"conversionRate":{"type":"number","format":"double","description":"Percent."},"duration":{"type":"integer","nullable":true,"description":"Seconds."},"orders":{"type":"integer","nullable":true},"peakViewers":{"type":"integer","nullable":true},"avgViewers":{"type":"integer","nullable":true},"totalLikes":{"type":"integer","nullable":true},"totalComments":{"type":"integer","nullable":true},"totalShares":{"type":"integer","nullable":true},"startTime":{"type":"string","nullable":true},"endTime":{"type":"string","nullable":true},"status":{"type":"string","nullable":true},"hasUnresolvedTempSkus":{"type":"boolean"}}},"DeveloperMarketingLiveData":{"type":"object","additionalProperties":false,"description":"Canonical TikTok LIVE performance summary. Null when the shop has no LIVE data.","required":["totalLiveRevenue","avgConversionRate","topStreams"],"properties":{"totalLiveRevenue":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"avgConversionRate":{"type":"number","format":"double","description":"Percent."},"totalViewers":{"type":"integer","nullable":true},"totalStreams":{"type":"integer","nullable":true},"topStreams":{"type":"array","items":{"$ref":"#/components/schemas/DeveloperLiveStreamRow"}}}},"DeveloperAdPerformanceSummary":{"type":"object","additionalProperties":false,"required":["totalAdSpend","totalAdRevenue","overallROI","totalImpressions","totalClicks","avgCTR","topCampaigns"],"properties":{"totalAdSpend":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"totalAdRevenue":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"overallROI":{"type":"number","format":"double","description":"ROAS multiplier."},"totalImpressions":{"type":"integer"},"totalClicks":{"type":"integer"},"avgCTR":{"type":"number","format":"double","description":"Percent."},"topCampaigns":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["id","name","status","spend","revenue","roi"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["ACTIVE","PAUSED","ENDED"]},"spend":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"revenue":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"roi":{"type":"number","format":"double"}}}},"spendVsRevenueChart":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["date","spend","revenue"],"properties":{"date":{"type":"string"},"spend":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"revenue":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."}}}}}},"DeveloperPromoPerformanceSummary":{"type":"object","additionalProperties":false,"required":["revenueFromPromotions","topCouponsUsed","topPromotions","topCoupons"],"properties":{"revenueFromPromotions":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"topCouponsUsed":{"type":"integer"},"topPromotions":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["id","name","type","revenue"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"},"revenue":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."}}}},"topCoupons":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["id","code","type","timesUsed"],"properties":{"id":{"type":"string"},"code":{"type":"string"},"type":{"type":"string"},"timesUsed":{"type":"integer"}}}}}},"DeveloperMarketingOverviewData":{"type":"object","additionalProperties":false,"description":"Canonical Marketing Analytics overview, including optional previous-period comparison inside kpiSummary.","required":["kpiSummary","hasAdsApiAccess","dataAvailability"],"properties":{"kpiSummary":{"$ref":"#/components/schemas/DeveloperMarketingKpiSummary"},"livePerformance":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/DeveloperMarketingLiveData"}]},"adPerformance":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/DeveloperAdPerformanceSummary"}]},"promoPerformance":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/DeveloperPromoPerformanceSummary"}]},"hasAdsApiAccess":{"type":"boolean"},"dataAvailability":{"type":"object","additionalProperties":false,"required":["hasLiveData","hasAdData","hasPromoData"],"properties":{"hasLiveData":{"type":"boolean"},"hasAdData":{"type":"boolean"},"hasPromoData":{"type":"boolean"}}}}},"DeveloperAdCampaignRow":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/DeveloperAdditiveMetric"},"properties":{"id":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"status":{"type":"string","nullable":true},"spend":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization.","nullable":true},"revenue":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization.","nullable":true},"orders":{"type":"integer","nullable":true},"roi":{"type":"number","format":"double","description":"ROAS multiplier.","nullable":true},"impressions":{"type":"integer","nullable":true},"clicks":{"type":"integer","nullable":true},"ctr":{"type":"number","format":"double","description":"Percent.","nullable":true},"cpc":{"type":"number","format":"double","nullable":true},"cpm":{"type":"number","format":"double","nullable":true},"campaignType":{"type":"string","nullable":true}}},"DeveloperAdCampaignsData":{"type":"object","additionalProperties":false,"description":"Paginated canonical advertising campaign metrics.","required":["campaigns","pagination"],"properties":{"campaigns":{"type":"array","items":{"$ref":"#/components/schemas/DeveloperAdCampaignRow"}},"pagination":{"type":"object","additionalProperties":false,"required":["page","pageSize","total","totalPages"],"properties":{"page":{"type":"integer"},"pageSize":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"summary":{"type":"object","additionalProperties":false,"required":["totalSpend","totalRevenue","averageROI","totalOrders","totalCampaigns","activeCampaigns"],"properties":{"totalSpend":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"totalRevenue":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"averageROI":{"type":"number","format":"double","description":"Ratio of sums, not a mean of per-campaign ROI."},"totalOrders":{"type":"integer"},"totalCampaigns":{"type":"integer"},"activeCampaigns":{"type":"integer"},"roas":{"type":"number","format":"double","description":"Null when totalSpend <= 0.","nullable":true},"acos":{"type":"number","format":"double","description":"Percent. Null when totalRevenue <= 0.","nullable":true},"tacos":{"type":"number","format":"double","description":"Percent of shop product sales. Null when the denominator is unavailable or the request has no shop scope.","nullable":true},"costPerOrder":{"type":"number","format":"double","description":"Null when totalOrders <= 0.","nullable":true},"cpc":{"type":"number","format":"double","nullable":true},"cpm":{"type":"number","format":"double","nullable":true}}},"dailyBreakdown":{"type":"array","items":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/DeveloperAdditiveMetric"},"required":["date"],"properties":{"date":{"type":"string"}}}}}},"DeveloperAffiliateCurrencyRollup":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/DeveloperAdditiveMetric"},"properties":{"currency":{"type":"string","nullable":true},"affiliateOrders":{"type":"integer","nullable":true},"affiliateRevenue":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization.","nullable":true},"affiliateCommission":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization.","nullable":true},"affiliateAdsCommission":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization.","nullable":true},"partnerCommission":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization.","nullable":true},"netAffiliateProfit":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization.","nullable":true}}},"DeveloperAffiliateCreatorRow":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/DeveloperAdditiveMetric"},"properties":{"creatorId":{"type":"string","nullable":true},"creatorName":{"type":"string","nullable":true,"description":"TikTok creator/publisher display name. Business counterparty, not a buyer identity."},"currency":{"type":"string","nullable":true},"orders":{"type":"integer","nullable":true},"revenue":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization.","nullable":true},"commission":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization.","nullable":true}}},"DeveloperAffiliateShopRow":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/DeveloperAdditiveMetric"},"properties":{"shopId":{"type":"string","format":"uuid","nullable":true},"shopName":{"type":"string","nullable":true},"currency":{"type":"string","nullable":true},"orders":{"type":"integer","nullable":true},"revenue":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization.","nullable":true},"commission":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization.","nullable":true}}},"DeveloperAffiliatePerformanceData":{"type":"object","additionalProperties":false,"description":"Canonical affiliate performance for a US-region shop. Window is capped at 90 days and evaluated in the shop's own timezone, reported in meta.timezone.","required":["range","currencies","rollupByCurrency","creatorRollup","shops"],"properties":{"range":{"type":"object","additionalProperties":false,"required":["from","to"],"properties":{"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"}}},"currencies":{"type":"array","items":{"type":"string"}},"rollupByCurrency":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/DeveloperAffiliateCurrencyRollup"},"description":"Keyed by ISO currency code."},"creatorRollup":{"type":"array","items":{"$ref":"#/components/schemas/DeveloperAffiliateCreatorRow"}},"shops":{"type":"array","items":{"$ref":"#/components/schemas/DeveloperAffiliateShopRow"}},"dataAvailability":{"type":"object","additionalProperties":false,"required":["status"],"properties":{"namedCreatorAttribution":{"type":"boolean"},"status":{"type":"string","enum":["AVAILABLE","UNAVAILABLE","INCOMPLETE"]},"source":{"type":"string"},"reason":{"type":"string","nullable":true},"provenance":{"type":"array","items":{"type":"string"}}}}}},"DeveloperPromotionWindowRow":{"type":"object","additionalProperties":false,"required":["promotionId","tiktokPromotionId","promotionTitle","promotionType","startTime","endTime","status","windowRevenue","windowOrders"],"properties":{"promotionId":{"type":"string"},"tiktokPromotionId":{"type":"string"},"promotionTitle":{"type":"string"},"promotionType":{"type":"string"},"startTime":{"type":"string","format":"date-time"},"endTime":{"type":"string","format":"date-time"},"status":{"type":"string"},"windowRevenue":{"type":"number","format":"double","description":"Shop revenue recorded while this promotion window was active. Exposure, not causal attribution. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"windowOrders":{"type":"integer","description":"Shop orders recorded while this promotion window was active."},"windowUnits":{"type":"integer","description":"Units in those orders. Window exposure, not causal attribution."}}},"DeveloperCouponWindowRow":{"type":"object","additionalProperties":false,"required":["couponId","tiktokCouponId","couponTitle","discountType","startTime","endTime","status","windowRevenue","windowOrders"],"properties":{"couponId":{"type":"string"},"tiktokCouponId":{"type":"string"},"couponTitle":{"type":"string"},"discountType":{"type":"string"},"startTime":{"type":"string","format":"date-time"},"endTime":{"type":"string","format":"date-time"},"status":{"type":"string"},"windowRevenue":{"type":"number","format":"double","description":"Shop revenue recorded while this coupon window was active. Exposure, not causal attribution. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"windowOrders":{"type":"integer","description":"Shop orders recorded while this coupon window was active."},"windowUnits":{"type":"integer","description":"Units in those orders. Window exposure, not causal attribution."},"redemptionCount":{"type":"integer"}}},"DeveloperPromotionsData":{"type":"object","additionalProperties":false,"required":["promotions","coupons","summary","pagination"],"properties":{"estimateBasis":{"type":"string","enum":["temporal_window"]},"deduplicated":{"type":"boolean","enum":[false],"description":"Always false. Orders inside overlapping campaign windows are counted once per window."},"estimateDisclaimer":{"type":"string"},"promotions":{"type":"array","items":{"$ref":"#/components/schemas/DeveloperPromotionWindowRow"}},"coupons":{"type":"array","items":{"$ref":"#/components/schemas/DeveloperCouponWindowRow"}},"summary":{"type":"object","additionalProperties":false,"required":["promotionsPageWindowRevenue","couponsPageWindowRevenue","pageWindowOrderCounts","summaryScope"],"properties":{"promotionsPageWindowRevenue":{"type":"number","format":"double","description":"Sum of `windowRevenue` across the promotions ON THIS PAGE only. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"couponsPageWindowRevenue":{"type":"number","format":"double","description":"Sum of `windowRevenue` across the coupons ON THIS PAGE only. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"pageWindowOrderCounts":{"type":"integer","description":"Sum of per-campaign window order counts on this page. Not a distinct order count."},"summaryScope":{"type":"string","enum":["page"],"description":"Always `page`. Totals are scoped to the returned page: summing overlapping campaign windows across all pages would double-count the same shop sales into a figure that reads like shop revenue but is not."}}},"pagination":{"type":"object","additionalProperties":false,"required":["page","pageSize","promotionsTotal","promotionsTotalPages","couponsTotal","couponsTotalPages"],"properties":{"page":{"type":"integer"},"pageSize":{"type":"integer"},"promotionsTotal":{"type":"integer","description":"Exact count of ALL matching promotions, correct on every page including one past the last."},"promotionsTotalPages":{"type":"integer"},"couponsTotal":{"type":"integer","description":"Exact count of ALL matching coupons, correct on every page including one past the last."},"couponsTotalPages":{"type":"integer"}}}}},"DeveloperProfitLossColumn":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/DeveloperAdditiveMetric"},"description":"One P&L period column header.","properties":{"key":{"type":"string","nullable":true,"description":"Period key for this column."},"label":{"type":"string","nullable":true},"startDate":{"type":"string","nullable":true},"endDate":{"type":"string","nullable":true}}},"DeveloperProfitLossRow":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/DeveloperAdditiveMetric"},"description":"One P&L tree line. `values` is keyed by the column keys in `columns`.","properties":{"id":{"type":"string","nullable":true},"label":{"type":"string","nullable":true},"category":{"type":"string","nullable":true},"level":{"type":"integer","nullable":true},"parentId":{"type":"string","nullable":true},"isTotal":{"type":"boolean"},"values":{"type":"object","additionalProperties":{"type":"number","format":"double","nullable":true},"description":"Amount per period column key."}}},"DeveloperProfitLossData":{"type":"object","additionalProperties":false,"required":["period","columns","profitLossSummary"],"properties":{"period":{"type":"string","enum":["day","week","month","quarter","year"]},"columns":{"type":"array","items":{"$ref":"#/components/schemas/DeveloperProfitLossColumn"}},"profitLossSummary":{"type":"array","items":{"$ref":"#/components/schemas/DeveloperProfitLossRow"}}}},"DeveloperCustomPnlReport":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/DeveloperAdditiveMetric"},"description":"Custom P&L report definition metadata. Formula internals are not published.","properties":{"id":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time","nullable":true},"updatedAt":{"type":"string","format":"date-time","nullable":true},"isArchived":{"type":"boolean"}}},"DeveloperCustomPnlEvaluationSummary":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/DeveloperAdditiveMetric"},"description":"Immutable prepared-evaluation header.","properties":{"id":{"type":"string","nullable":true},"reportId":{"type":"string","nullable":true},"status":{"type":"string","nullable":true},"startDate":{"type":"string","nullable":true},"endDate":{"type":"string","nullable":true},"preparedAt":{"type":"string","format":"date-time","nullable":true},"revision":{"type":"integer","nullable":true}}},"DeveloperCustomPnlEvaluationRow":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/DeveloperAdditiveMetric"},"description":"One prepared SKU or day row of a Custom P&L evaluation.","properties":{"skuId":{"type":"string","nullable":true},"productId":{"type":"string","nullable":true},"productName":{"type":"string","nullable":true},"date":{"type":"string","nullable":true}}},"DeveloperCustomPnlReportsData":{"type":"object","additionalProperties":false,"required":["reports"],"properties":{"reports":{"type":"array","items":{"$ref":"#/components/schemas/DeveloperCustomPnlReport"}}}},"DeveloperCustomPnlEvaluationsData":{"type":"object","additionalProperties":false,"required":["evaluations"],"properties":{"evaluations":{"type":"array","items":{"$ref":"#/components/schemas/DeveloperCustomPnlEvaluationSummary"}}}},"DeveloperCustomPnlEvaluationPagination":{"type":"object","additionalProperties":false,"description":"Canonical page descriptor, echoed from the prepared evaluation. The same window is normalized into `meta.pagination`.","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"DeveloperCustomPnlEvaluationData":{"type":"object","additionalProperties":false,"description":"Prepared immutable Custom P&L evaluation with paginated SKU totals and optional day rows.","required":["rows"],"properties":{"evaluation":{"$ref":"#/components/schemas/DeveloperCustomPnlEvaluationSummary"},"rows":{"type":"array","items":{"$ref":"#/components/schemas/DeveloperCustomPnlEvaluationRow"}},"pagination":{"$ref":"#/components/schemas/DeveloperCustomPnlEvaluationPagination"}}},"DeveloperEstimatedDataInfo":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/DeveloperAdditiveMetric"},"properties":{"hasEstimatedData":{"type":"boolean"},"estimatedOrderCount":{"type":"integer","nullable":true},"totalOrderCount":{"type":"integer","nullable":true},"estimatedPercentage":{"type":"number","format":"double","nullable":true}}},"DeveloperDataQualityInfo":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/DeveloperAdditiveMetric"},"properties":{"level":{"type":"string","nullable":true},"message":{"type":"string","nullable":true}}},"DeveloperMetricDataQuality":{"type":"object","additionalProperties":false,"properties":{"hasTemporaryData":{"type":"boolean"},"hasEstimatedData":{"type":"boolean"}}},"DeveloperSalesProfitDataQuality":{"type":"object","additionalProperties":false,"required":["hasTemporaryData"],"properties":{"hasTemporaryData":{"type":"boolean"},"hasOnlyTemporaryData":{"type":"boolean","nullable":true},"estimatedDataInfo":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/DeveloperEstimatedDataInfo"}]},"dataQualityInfo":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/DeveloperDataQualityInfo"}]},"metricDataQualityByMetric":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/DeveloperMetricDataQuality"},"description":"Keyed by canonical metric id.","nullable":true}}},"DeveloperSalesProfitRow":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/DeveloperAdditiveMetric"},"description":"One product- or SKU-grain profitability row.","properties":{"productId":{"type":"string","nullable":true},"skuId":{"type":"string","nullable":true},"productName":{"type":"string","nullable":true},"skuName":{"type":"string","nullable":true},"sellerSku":{"type":"string","nullable":true},"unitsSold":{"type":"number","format":"double","nullable":true},"grossSales":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization.","nullable":true},"netSales":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization.","nullable":true},"costOfGoodsSold":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization.","nullable":true},"grossProfit":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization.","nullable":true},"operatingProfit":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization.","nullable":true},"netProfit":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization.","nullable":true},"grossMargin":{"type":"number","format":"double","description":"Percent.","nullable":true},"netMargin":{"type":"number","format":"double","description":"Percent.","nullable":true},"roi":{"type":"number","format":"double","description":"Percent.","nullable":true}}},"DeveloperSalesProfitSummary":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/DeveloperAdditiveMetric"},"properties":{"unitsSold":{"type":"number","format":"double","nullable":true},"grossSales":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization.","nullable":true},"netSales":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization.","nullable":true},"costOfGoodsSold":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization.","nullable":true},"grossProfit":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization.","nullable":true},"operatingProfit":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization.","nullable":true},"netProfit":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization.","nullable":true}}},"DeveloperSalesProfitData":{"type":"object","additionalProperties":false,"description":"Canonical product/SKU profitability export.","required":["grain","rows","summary","dataQuality"],"properties":{"grain":{"type":"string","enum":["product","sku"]},"rows":{"type":"array","items":{"$ref":"#/components/schemas/DeveloperSalesProfitRow"}},"summary":{"$ref":"#/components/schemas/DeveloperSalesProfitSummary"},"dataQuality":{"$ref":"#/components/schemas/DeveloperSalesProfitDataQuality"}}},"DeveloperOrderItem":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/DeveloperAdditiveMetric"},"description":"PII-free order line item.","properties":{"skuId":{"type":"string","nullable":true},"tikTokSkuId":{"type":"string","nullable":true},"sellerSku":{"type":"string","nullable":true},"productId":{"type":"string","nullable":true},"productName":{"type":"string","nullable":true},"skuName":{"type":"string","nullable":true},"quantity":{"type":"integer","nullable":true},"unitPrice":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization.","nullable":true},"salePrice":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization.","nullable":true},"costOfGoodsSold":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization.","nullable":true}}},"DeveloperOrderFlags":{"type":"object","additionalProperties":false,"description":"Boolean order markers, as emitted in the `orderFlags` dashboard column.","required":["isSampleOrder","isOnHoldOrder","isExchangeOrder"],"properties":{"isSampleOrder":{"type":"boolean"},"isOnHoldOrder":{"type":"boolean"},"isExchangeOrder":{"type":"boolean"}}},"DeveloperOrderProductRef":{"type":"object","additionalProperties":false,"description":"One line item as it appears in the `products` dashboard column.","properties":{"name":{"type":"string","nullable":true,"description":"Product name on the line item."},"quantity":{"type":"integer","nullable":true}}},"DeveloperOrderFinancials":{"type":"object","additionalProperties":false,"description":"Canonical OrderFinancialSnapshot plus the shop `currency` the Developer boundary adds. Present only when includeFinancials=true.","required":["grossSales","netRevenue","grossProfit","orderProfit","dataSource"],"properties":{"currency":{"type":"string","nullable":true,"description":"ISO currency for the shop region."},"grossSales":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"grossSalesRefund":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"sellerDiscount":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"sellerDiscountRefund":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"platformDiscount":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"platformDiscountRefund":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"customerPaid":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"netRevenue":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"settlementAmount":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization.","nullable":true},"shippingRevenue":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"customerPaidShipping":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"customerPaidShippingRefund":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"shippingSubsidy":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"returnShippingFee":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"costOfGoodsSold":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"feesAndTaxes":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"netShippingCost":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"fbsShipping":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"orderCosts":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"grossProfit":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"operatingProfit":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"orderProfit":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization."},"dataSource":{"type":"string","enum":["settled","preliminary","estimated"]}}},"DeveloperBreakdownComponent":{"type":"object","additionalProperties":false,"required":["key"],"properties":{"key":{"type":"string"},"label":{"type":"string","nullable":true},"amount":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization.","nullable":true},"isSynthetic":{"type":"boolean"}}},"DeveloperOrderTransactionBreakdown":{"type":"object","additionalProperties":false,"description":"Signed TikTok settlement and transaction components. Ledger signs are preserved.","required":["dataSource","statusLabel","shipping","fees","taxes","skus"],"properties":{"dataSource":{"type":"string"},"statusLabel":{"type":"string"},"currency":{"type":"string","nullable":true},"reconciliation":{"type":"object","additionalProperties":false,"properties":{"settlementAmount":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization.","nullable":true},"componentTotal":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization.","nullable":true},"difference":{"type":"number","format":"double","description":"Monetary amount in the shop currency. Serialized as a JSON number; Prisma Decimal and BigInt values are converted before serialization.","nullable":true},"isBalanced":{"type":"boolean"}}},"shipping":{"type":"array","items":{"$ref":"#/components/schemas/DeveloperBreakdownComponent"}},"fees":{"type":"array","items":{"$ref":"#/components/schemas/DeveloperBreakdownComponent"}},"taxes":{"type":"array","items":{"$ref":"#/components/schemas/DeveloperBreakdownComponent"}},"skus":{"type":"array","items":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/DeveloperAdditiveMetric"},"properties":{"skuId":{"type":"string","nullable":true},"skuName":{"type":"string","nullable":true},"productName":{"type":"string","nullable":true},"quantity":{"type":"integer","nullable":true}}}}}},"DeveloperOrderDashboardColumns":{"type":"object","additionalProperties":false,"description":"All 67 Orders dashboard export columns, always materialized. The same fields are also flattened onto the order row.","properties":{"orderId":{"type":"string","nullable":true},"date":{"type":"string","nullable":true},"customer":{"type":"string","nullable":true,"description":"ALWAYS null on this API. Buyer-derived column kept present so the 67-column schema is stable; see orderDashboardSchema.redactedColumnIds."},"state":{"type":"string","nullable":true,"description":"ALWAYS null on this API. Buyer-derived column kept present so the 67-column schema is stable."},"fulfillmentType":{"type":"string","nullable":true},"orderFlags":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/DeveloperOrderFlags"}],"description":"Sample / on-hold / exchange markers present on the order."},"products":{"type":"array","items":{"$ref":"#/components/schemas/DeveloperOrderProductRef"},"nullable":true,"description":"Product name and quantity for each line item on the order."},"tikTokSkuIds":{"type":"array","items":{"type":"string"},"nullable":true},"totalItems":{"type":"integer","nullable":true},"status":{"type":"string","nullable":true},"totalAmount":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"grossSales":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"grossSalesRefund":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"sellerDiscount":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"sellerDiscountRefund":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"platformDiscount":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"platformDiscountRefund":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"netRevenue":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"settlementAmount":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"costOfGoodsSold":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"feesAndTaxes":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"actualShippingCost":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"costs":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"manualShippingCost":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"grossProfit":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"operatingProfit":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"netProfit":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"dataQuality":{"type":"string","nullable":true,"description":"Settlement provenance label for the row."},"customerPaymentAmount":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"customerRefundAmount":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"sellerCofundedVoucherDiscountAmount":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"sellerCofundedVoucherDiscountRefundAmount":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"platformCofundedVoucherDiscountAmount":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"platformCofundedVoucherDiscountRefundAmount":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"shippingRevenue":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"customerPaidShipping":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"customerPaidShippingRefund":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"shippingSubsidy":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"returnShippingFee":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"actualShippingFeeAmount":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"fbmShippingCostAmount":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"fbtShippingCostAmount":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"shippingFeeDiscountAmount":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"platformShippingFeeDiscountAmount":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"promoShippingIncentiveAmount":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"promoShippingIncentiveRefundAmount":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"sellerShippingFeeDiscountAmount":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"customerShippingFeeOffsetAmount":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"returnShippingLabelFeeAmount":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"shippingFeeGuaranteeReimbursement":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"fbtFulfillmentFeeReimbursementAmount":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"platformCommissionAmount":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"referralFeeAmount":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"transactionFeeAmount":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"affiliateCommissionAmount":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"affiliatePartnerCommission":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"affiliateAdsCommissionAmount":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"smartPromotionFeeAmount":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"cofundedPromotionServiceFee":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"campaignPeriodFeeCfpAmount":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"campaignPeriodFeeSpAmount":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"gmvMaxAdFeeAmount":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"platformSemiManagedCommissionFee":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"sellerGrowthFeeAmount":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"vatAmount":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"localVatAmount":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"salesTaxAmount":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true}}},"DeveloperOrderDashboardSchema":{"type":"object","additionalProperties":false,"required":["preset","columnCount","columnIds","redactedColumnIds"],"properties":{"preset":{"type":"string","enum":["full-tiktok-breakdown"]},"columnCount":{"type":"integer"},"columnIds":{"type":"array","items":{"type":"string"}},"redactedColumnIds":{"type":"array","items":{"type":"string"},"description":"Columns always returned as null on this API (buyer-derived)."},"signConvention":{"type":"string"}}},"DeveloperOrder":{"type":"object","additionalProperties":false,"description":"PII-free order row. The 67 dashboard columns are also flattened onto this row, so they are declared explicitly rather than as an open extension.","required":["orderId","tikTokOrderId","status","totalAmount","itemCount","items"],"properties":{"orderId":{"type":"string","nullable":true},"tikTokOrderId":{"type":"string"},"status":{"type":"string","nullable":true},"totalAmount":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"paymentMethod":{"type":"string","nullable":true},"fulfillmentType":{"type":"string","nullable":true},"deliveryType":{"type":"string","nullable":true},"shippingType":{"type":"string","nullable":true},"isCancelled":{"type":"boolean"},"isSampleOrder":{"type":"boolean"},"isOnHoldOrder":{"type":"boolean"},"isExchangeOrder":{"type":"boolean"},"createTime":{"type":"string","format":"date-time","nullable":true},"updateTime":{"type":"string","format":"date-time","nullable":true},"paidTime":{"type":"string","format":"date-time","nullable":true},"deliveryTime":{"type":"string","format":"date-time","nullable":true},"cancelTime":{"type":"string","format":"date-time","nullable":true},"itemCount":{"type":"integer"},"items":{"type":"array","items":{"$ref":"#/components/schemas/DeveloperOrderItem"}},"financials":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/DeveloperOrderFinancials"}]},"transactionBreakdown":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/DeveloperOrderTransactionBreakdown"}]},"dashboardColumns":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/DeveloperOrderDashboardColumns"}]},"date":{"type":"string","nullable":true},"customer":{"type":"string","nullable":true,"description":"ALWAYS null on this API. Buyer-derived column kept present so the 67-column schema is stable; see orderDashboardSchema.redactedColumnIds."},"state":{"type":"string","nullable":true,"description":"ALWAYS null on this API. Buyer-derived column kept present so the 67-column schema is stable."},"orderFlags":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/DeveloperOrderFlags"}],"description":"Sample / on-hold / exchange markers present on the order."},"products":{"type":"array","items":{"$ref":"#/components/schemas/DeveloperOrderProductRef"},"nullable":true,"description":"Product name and quantity for each line item on the order."},"tikTokSkuIds":{"type":"array","items":{"type":"string"},"nullable":true},"totalItems":{"type":"integer","nullable":true},"grossSales":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"grossSalesRefund":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"sellerDiscount":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"sellerDiscountRefund":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"platformDiscount":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"platformDiscountRefund":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"netRevenue":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"settlementAmount":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"costOfGoodsSold":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"feesAndTaxes":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"actualShippingCost":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"costs":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"manualShippingCost":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"grossProfit":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"operatingProfit":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"netProfit":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"dataQuality":{"type":"string","nullable":true,"description":"Settlement provenance label for the row."},"customerPaymentAmount":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"customerRefundAmount":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"sellerCofundedVoucherDiscountAmount":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"sellerCofundedVoucherDiscountRefundAmount":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"platformCofundedVoucherDiscountAmount":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"platformCofundedVoucherDiscountRefundAmount":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"shippingRevenue":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"customerPaidShipping":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"customerPaidShippingRefund":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"shippingSubsidy":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"returnShippingFee":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"actualShippingFeeAmount":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"fbmShippingCostAmount":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"fbtShippingCostAmount":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"shippingFeeDiscountAmount":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"platformShippingFeeDiscountAmount":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"promoShippingIncentiveAmount":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"promoShippingIncentiveRefundAmount":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"sellerShippingFeeDiscountAmount":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"customerShippingFeeOffsetAmount":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"returnShippingLabelFeeAmount":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"shippingFeeGuaranteeReimbursement":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"fbtFulfillmentFeeReimbursementAmount":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"platformCommissionAmount":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"referralFeeAmount":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"transactionFeeAmount":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"affiliateCommissionAmount":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"affiliatePartnerCommission":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"affiliateAdsCommissionAmount":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"smartPromotionFeeAmount":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"cofundedPromotionServiceFee":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"campaignPeriodFeeCfpAmount":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"campaignPeriodFeeSpAmount":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"gmvMaxAdFeeAmount":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"platformSemiManagedCommissionFee":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"sellerGrowthFeeAmount":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"vatAmount":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"localVatAmount":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true},"salesTaxAmount":{"type":"number","format":"double","description":"TikTok ledger sign is preserved. Null until the order has ledger data.","nullable":true}}},"DeveloperOrdersData":{"type":"object","additionalProperties":false,"required":["orders"],"properties":{"orderDashboardSchema":{"$ref":"#/components/schemas/DeveloperOrderDashboardSchema"},"orders":{"type":"array","items":{"$ref":"#/components/schemas/DeveloperOrder"}}}},"DeveloperCostImportResultData":{"type":"object","additionalProperties":false,"required":["operationId","imported","productRows","skuRows","replayed"],"properties":{"operationId":{"type":"string","format":"uuid"},"imported":{"type":"integer"},"productRows":{"type":"integer"},"skuRows":{"type":"integer"},"replayed":{"type":"boolean","description":"True when this Idempotency-Key replayed an earlier apply instead of writing a new COGS timeline."}}},"DeveloperPagination":{"type":"object","additionalProperties":false,"required":["limit","offset","total","hasMore"],"properties":{"limit":{"type":"integer","minimum":1},"offset":{"type":"integer","minimum":0},"total":{"type":"integer","minimum":0},"hasMore":{"type":"boolean"}}},"DeveloperMeta":{"type":"object","additionalProperties":false,"required":["requestId","generatedAt","shopId"],"properties":{"requestId":{"type":"string","format":"uuid"},"generatedAt":{"type":"string","format":"date-time"},"shopId":{"type":"string","format":"uuid","nullable":true},"timezone":{"type":"string","example":"America/New_York"},"pagination":{"$ref":"#/components/schemas/DeveloperPagination"}}},"DeveloperErrorDetail":{"type":"object","description":"One validation or domain failure. Extra keys are scalar diagnostics only.","properties":{"field":{"type":"string"},"message":{"type":"string"},"code":{"type":"string"}},"additionalProperties":{"$ref":"#/components/schemas/DeveloperAdditiveMetric"}},"DeveloperErrorEnvelope":{"type":"object","additionalProperties":false,"required":["error","meta"],"properties":{"error":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","example":"forbidden"},"message":{"type":"string"},"retryAfter":{"type":"integer","minimum":1,"description":"Seconds to wait before retrying. Present on rate-limit errors."},"details":{"type":"array","items":{"$ref":"#/components/schemas/DeveloperErrorDetail"}}}},"meta":{"type":"object","additionalProperties":false,"required":["requestId","generatedAt"],"properties":{"requestId":{"type":"string","format":"uuid"},"generatedAt":{"type":"string","format":"date-time"}}}}}}}}