{"openapi":"3.1.0","info":{"title":"Ecommerce Seller Profitability API","version":"1.0.0","description":"Unit economics, PPC search-term analysis, listing keyword coverage, import landed cost, price elasticity, competitive price index, bundle pricing, packaging fit and settlement tax reconcile from caller-supplied fees, costs and reports. Paid with x402 exact USDC on Base. No account is required.","contact":{"email":"support@brainiac.software"},"x-guidance":"BRAINIAC.software is a pay-per-call API for software agents. No account or API key is required.\nPayment uses x402 with exact USDC on Base (8453). Each paid resource accepts POST for the call; unpaid GET/HEAD return the same 402 payment challenge for discovery.\nHow to call an operation:\n1. POST JSON matching the requestBody. An unpaid POST (including empty body) returns 402 payment terms before body validation.\n2. Compare 402 payTo, asset, and network with /api/v1/catalog and /.well-known/x402 — not only with the 402 itself.\n3. Pay and retry with payment-signature. Invalid JSON/schema after payment-signature returns 400 and is not charged. Settlement (a charge) only on 2xx. payment-signature attached ≠ charged.\nIdempotency-Key: 64 hex chars from 32 random bytes. Reuse only for the same operation and body (replays stored response, including status=partial). A new key runs a fresh call.\nIdempotency after errors: unpaid 402 does not store the key. Post-signature 402/503 release it (retry same key). Pre-reserve schema 400 does not store it. Other post-signature responses (2xx/4xx/5xx) are stored: same key+body replays; different body → 409. Stored 4xx/5xx replays are not a second charge. Prefer a new key after fixing a 4xx; after 5xx reuse the same key only for the stored error.\nPost-signature 402/503 include prior-payment-attempt (nonce, settled false|unknown). A facilitator 502 is SETTLEMENT_UNKNOWN (stored under the Idempotency-Key; cross-instance replay needs the shared store; may already be charged) — check USDC authorizationState(payer, nonce) on Base before re-signing.\nSettlement signal: settled 2xx include payment-response. 4xx/5xx do not. Do not book a cost from payment-signature alone.\nCoverage billing: HTTP 200 with status complete, partial, or failed is charged at the full listed price. Retrying missing checks needs a new settled call. 4xx/5xx are not charged.\nmissing_items.reason: timeout/rate_limited → one delayed retry (new key); upstream_down → after recovery; not_supported → never.\nInvariants: any missing_items ⇒ not status complete; sources[] is provenance only (source, url, retrievedAt), never success/error keyed by check.\nFree lookup: GET /api/v1/results/{result_id} returns stored coverage JSON (404 RESULT_NOT_FOUND if unknown/expired; not a 402). Prior-Result-Id sets replaces_result_id.\nOutputs are prechecks/drafts for human review — not official determinations, legal advice, or certified filings."},"servers":[{"url":"https://www.brainiac.software"}],"paths":{"/api/v1/ecommerce-profitability/unit-economics":{"post":{"operationId":"per_unit_contribution_margin_and_break_even","summary":"Per-unit contribution margin and break-even","description":"Compute landed cost, total cost per unit, contribution margin, ROI, break-even price and break-even ACoS from caller-supplied product costs and marketplace fees or fee rates.","tags":["ecommerce-profitability"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"currency":{"type":"string","minLength":3,"maxLength":3},"pricePerUnit":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"costs":{"type":"object","properties":{"product":{"type":"integer","minimum":0,"maximum":9007199254740991},"inboundFreight":{"type":"integer","minimum":0,"maximum":9007199254740991},"duty":{"type":"integer","minimum":0,"maximum":9007199254740991},"packaging":{"type":"integer","minimum":0,"maximum":9007199254740991},"marketplaceFees":{"type":"integer","minimum":0,"maximum":9007199254740991},"fulfilmentFees":{"type":"integer","minimum":0,"maximum":9007199254740991},"storage":{"type":"integer","minimum":0,"maximum":9007199254740991},"other":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["product","inboundFreight","duty","packaging","fulfilmentFees","storage"],"additionalProperties":false},"marketplaceFeeRate":{"type":"number","minimum":0,"exclusiveMaximum":1},"returnRate":{"type":"number","minimum":0,"maximum":1},"returnLossPerUnit":{"type":"integer","minimum":0,"maximum":9007199254740991},"salesTaxIncluded":{"default":false,"type":"boolean"}},"required":["currency","pricePerUnit","costs","returnRate","returnLossPerUnit"],"additionalProperties":false},"example":{"currency":"USD","pricePerUnit":2999,"costs":{"product":800,"inboundFreight":120,"duty":60,"packaging":30,"marketplaceFees":750,"fulfilmentFees":420,"storage":25,"other":0},"returnRate":0.05,"returnLossPerUnit":1200,"salesTaxIncluded":false}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Fresh random 32-byte value encoded as 64 hexadecimal characters. Reuse unchanged only for retries of the same operation and request.","schema":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"}}],"responses":{"200":{"description":"Illustrative endpoint-specific JSON response shape. For coverage operations, HTTP 200 is used for status complete, partial, and failed; all three settle and are charged at the full listed price. A settled 2xx includes a payment-response response header (facilitator settlement receipt; may include a transaction reference). Conditional fields depend on the result and data-source availability.","headers":{"payment-response":{"description":"Present on settled 2xx only. Facilitator settlement receipt for the x402 payment (not present on 4xx/5xx, which are not charged).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"currency":{"type":"string"},"landedCost":{"type":"number"},"marketplaceFees":{"type":"number"},"returnsAllowance":{"type":"number"},"totalCostPerUnit":{"type":"number"},"contributionMargin":{"type":"number"},"marginPct":{"type":"number"},"roi":{"type":"number"},"breakEvenPrice":{"type":"number"},"breakEvenAcos":{"type":"number"},"salesTaxIncluded":{"type":"boolean"},"sources":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string"},"url":{"type":"string"},"retrievedAt":{"type":"string"},"status":{"type":"string"}},"additionalProperties":true},"description":"Provenance only (source, url, retrievedAt). Not keyed by check id and does not carry success or error. A check in missing_items does not remove its upstream from sources[]; unavailability is only in missing_items (and unavailable findings)."},"limitations":{"type":"array","items":{"type":"string"}}},"additionalProperties":true},"example":{"currency":"USD","landedCost":1010,"marketplaceFees":750,"returnsAllowance":60,"totalCostPerUnit":2265,"contributionMargin":734,"marginPct":0.2447,"roi":0.7267,"breakEvenPrice":2265,"breakEvenAcos":0.2447,"salesTaxIncluded":false,"sources":[{"source":"Caller-supplied marketplace fees, costs, ads rows and listing text processed locally","url":"https://www.brainiac.software/api/v1/ecommerce-profitability","retrievedAt":"2026-11-14","status":"ok"}],"limitations":["landedCost = product + inboundFreight + duty + packaging. Returns allowance = returnRate × returnLossPerUnit.","When marketplaceFeeRate is set, marketplace fees = price × rate and break-even price = ceil((total without fees) / (1 −…","…"]}}}},"400":{"description":"Invalid JSON or request schema. Not charged (no payment-response). If this 400 is returned before the Idempotency-Key is reserved, the key is not stored — fix the body and you may reuse the key. If an operation-path 400 was stored after a payment-signature was attached, the same key + same body replays it; the same key + a different body returns 409."},"402":{"description":"Payment required. The JSON body is the x402 PaymentRequired object. An unpaid 402 does not store the Idempotency-Key. A 402 after payment-signature releases the key and includes prior-payment-attempt (nonce, settled false|unknown). Not charged; no payment-response. Before re-signing after a post-signature 402, check USDC authorizationState(payer, nonce) on Base."},"409":{"description":"Idempotency conflict, in-progress payment, or expired result cache. Same key with a different body after a stored result returns conflict. Reusing the key cannot trigger a second charge. Not charged when settlement did not occur."},"413":{"description":"Request body exceeds the 24 MB limit. Not charged."},"500":{"description":"Operation failed before settlement, so no payment is taken (no payment-response). The error is stored: reuse the same Idempotency-Key and body to retrieve it without paying again. Use a new key for a fresh attempt with a new payment-signature."},"502":{"description":"Facilitator verify/settle transport failure (often timeout). After payment-signature this is returned as SETTLEMENT_UNKNOWN with prior-payment-attempt; the outcome is stored under the Idempotency-Key. With the shared store configured, other instances replay it instead of settling again; without it, each instance keeps its own memory. The authorization may already be settled on-chain — do not re-sign until USDC authorizationState(payer, nonce) on Base is false."},"503":{"description":"Payment or retry-safe result storage is unavailable; the operation is not run. Not charged; no payment-response. A 503 after payment-signature releases the Idempotency-Key and includes prior-payment-attempt."}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.03"},"protocols":[{"x402":{"facilitator":"https://api.cdp.coinbase.com/platform/v2/x402"}}],"facilitator":"https://api.cdp.coinbase.com/platform/v2/x402"}}},"/api/v1/ecommerce-profitability/ppc-report-analyze":{"post":{"operationId":"analyse_a_sponsored_ads_search_term_report","summary":"Analyse a sponsored-ads search-term report","description":"Aggregate ACoS, ROAS, TACoS, CTR and CVR for a search-term report and flag negate, promote and insufficient-data candidates from caller rules.","tags":["ecommerce-profitability"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"currency":{"type":"string","minLength":3,"maxLength":3},"rows":{"minItems":1,"maxItems":100000,"type":"array","items":{"type":"object","properties":{"campaign":{"type":"string","minLength":1,"maxLength":120},"adGroup":{"type":"string","minLength":1,"maxLength":120},"searchTerm":{"type":"string","minLength":1,"maxLength":200},"matchType":{"type":"string","minLength":1,"maxLength":40},"impressions":{"type":"integer","minimum":0,"maximum":1000000000},"clicks":{"type":"integer","minimum":0,"maximum":1000000000},"spend":{"type":"integer","minimum":0,"maximum":9007199254740991},"orders":{"type":"integer","minimum":0,"maximum":1000000000},"sales":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["campaign","adGroup","searchTerm","matchType","impressions","clicks","spend","orders","sales"],"additionalProperties":false}},"totalSales":{"type":"integer","minimum":0,"maximum":9007199254740991},"rules":{"type":"object","properties":{"targetAcos":{"type":"number","minimum":0,"maximum":1},"minClicksNegate":{"type":"integer","minimum":0,"maximum":1000000},"minOrdersPromote":{"type":"integer","minimum":0,"maximum":1000000}},"required":["targetAcos","minClicksNegate","minOrdersPromote"],"additionalProperties":false}},"required":["currency","rows","totalSales","rules"],"additionalProperties":false},"example":{"currency":"USD","rows":[{"campaign":"A","adGroup":"g1","searchTerm":"steel bottle","matchType":"broad","impressions":1000,"clicks":40,"spend":3200,"orders":4,"sales":11996}],"totalSales":500000,"rules":{"targetAcos":0.3,"minClicksNegate":15,"minOrdersPromote":2}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Fresh random 32-byte value encoded as 64 hexadecimal characters. Reuse unchanged only for retries of the same operation and request.","schema":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"}}],"responses":{"200":{"description":"Illustrative endpoint-specific JSON response shape. For coverage operations, HTTP 200 is used for status complete, partial, and failed; all three settle and are charged at the full listed price. A settled 2xx includes a payment-response response header (facilitator settlement receipt; may include a transaction reference). Conditional fields depend on the result and data-source availability.","headers":{"payment-response":{"description":"Present on settled 2xx only. Facilitator settlement receipt for the x402 payment (not present on 4xx/5xx, which are not charged).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"currency":{"type":"string"},"totals":{"type":"object","properties":{"spend":{"type":"number"},"sales":{"type":"number"},"acos":{"type":"number"},"roas":{"type":"number"},"tacos":{"type":"number"},"ctr":{"type":"number"},"cvr":{"type":"number"}},"additionalProperties":true},"negate":{"type":"array","items":{}},"promote":{"type":"array","items":{"type":"object","properties":{"searchTerm":{"type":"string"},"reason":{"type":"string"},"acos":{"type":"number"}},"additionalProperties":true}},"insufficientData":{"type":"array","items":{}},"wastedSpend":{"type":"number"},"sources":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string"},"url":{"type":"string"},"retrievedAt":{"type":"string"},"status":{"type":"string"}},"additionalProperties":true},"description":"Provenance only (source, url, retrievedAt). Not keyed by check id and does not carry success or error. A check in missing_items does not remove its upstream from sources[]; unavailability is only in missing_items (and unavailable findings)."},"limitations":{"type":"array","items":{"type":"string"}}},"additionalProperties":true},"example":{"currency":"USD","totals":{"spend":3200,"sales":11996,"acos":0.2668,"roas":3.749,"tacos":0.0064,"ctr":0.04,"cvr":0.1},"negate":[],"promote":[{"searchTerm":"steel bottle","reason":"orders>=2 and acos<=target","acos":0.2668}],"insufficientData":[],"wastedSpend":0,"sources":[{"source":"Caller-supplied marketplace fees, costs, ads rows and listing text processed locally","url":"https://www.brainiac.software/api/v1/ecommerce-profitability","retrievedAt":"2026-11-14","status":"ok"}],"limitations":["ACoS = spend/sales (null when sales are 0). ROAS = sales/spend. TACoS = spend/totalSales.","Negate candidates need clicks ≥ minClicksNegate and zero orders. Promote needs orders ≥ minOrdersPromote, ACoS ≤ target…","…"]}}}},"400":{"description":"Invalid JSON or request schema. Not charged (no payment-response). If this 400 is returned before the Idempotency-Key is reserved, the key is not stored — fix the body and you may reuse the key. If an operation-path 400 was stored after a payment-signature was attached, the same key + same body replays it; the same key + a different body returns 409."},"402":{"description":"Payment required. The JSON body is the x402 PaymentRequired object. An unpaid 402 does not store the Idempotency-Key. A 402 after payment-signature releases the key and includes prior-payment-attempt (nonce, settled false|unknown). Not charged; no payment-response. Before re-signing after a post-signature 402, check USDC authorizationState(payer, nonce) on Base."},"409":{"description":"Idempotency conflict, in-progress payment, or expired result cache. Same key with a different body after a stored result returns conflict. Reusing the key cannot trigger a second charge. Not charged when settlement did not occur."},"413":{"description":"Request body exceeds the 24 MB limit. Not charged."},"500":{"description":"Operation failed before settlement, so no payment is taken (no payment-response). The error is stored: reuse the same Idempotency-Key and body to retrieve it without paying again. Use a new key for a fresh attempt with a new payment-signature."},"502":{"description":"Facilitator verify/settle transport failure (often timeout). After payment-signature this is returned as SETTLEMENT_UNKNOWN with prior-payment-attempt; the outcome is stored under the Idempotency-Key. With the shared store configured, other instances replay it instead of settling again; without it, each instance keeps its own memory. The authorization may already be settled on-chain — do not re-sign until USDC authorizationState(payer, nonce) on Base is false."},"503":{"description":"Payment or retry-safe result storage is unavailable; the operation is not run. Not charged; no payment-response. A 503 after payment-signature releases the Idempotency-Key and includes prior-payment-attempt."}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.04"},"protocols":[{"x402":{"facilitator":"https://api.cdp.coinbase.com/platform/v2/x402"}}],"facilitator":"https://api.cdp.coinbase.com/platform/v2/x402"}}},"/api/v1/ecommerce-profitability/listing-keyword-coverage":{"post":{"operationId":"check_listing_keyword_coverage_and_length_limits","summary":"Check listing keyword coverage and length limits","description":"Token-match caller keywords against title, bullets, description and backend terms, including simple plurals, and check caller-supplied title and backend length limits.","tags":["ecommerce-profitability"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"title":{"type":"string","maxLength":2000},"bullets":{"default":[],"maxItems":20,"type":"array","items":{"type":"string","maxLength":2000}},"description":{"default":"","type":"string","maxLength":20000},"backendTerms":{"default":"","type":"string","maxLength":2000},"keywords":{"minItems":1,"maxItems":500,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}},"limits":{"type":"object","properties":{"titleChars":{"type":"integer","exclusiveMinimum":0,"maximum":10000},"backendBytes":{"type":"integer","exclusiveMinimum":0,"maximum":10000}},"required":["titleChars","backendBytes"],"additionalProperties":false}},"required":["title","keywords","limits"],"additionalProperties":false},"example":{"title":"Insulated Steel Bottle 750ml","bullets":["Keeps drinks cold"],"description":"A durable bottle.","backendTerms":"steel water bottle insulated","keywords":["steel water bottle","insulated"],"limits":{"titleChars":200,"backendBytes":249}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Fresh random 32-byte value encoded as 64 hexadecimal characters. Reuse unchanged only for retries of the same operation and request.","schema":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"}}],"responses":{"200":{"description":"Illustrative endpoint-specific JSON response shape. For coverage operations, HTTP 200 is used for status complete, partial, and failed; all three settle and are charged at the full listed price. A settled 2xx includes a payment-response response header (facilitator settlement receipt; may include a transaction reference). Conditional fields depend on the result and data-source availability.","headers":{"payment-response":{"description":"Present on settled 2xx only. Facilitator settlement receipt for the x402 payment (not present on 4xx/5xx, which are not charged).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"coverage":{"type":"number"},"keywords":{"type":"array","items":{"type":"object","properties":{"keyword":{"type":"string"},"found":{"type":"boolean"},"fields":{"type":"array","items":{"type":"string"}}},"additionalProperties":true}},"duplicatesInBackend":{"type":"array","items":{"type":"string"}},"lengths":{"type":"object","properties":{"titleChars":{"type":"number"},"backendBytes":{"type":"number"}},"additionalProperties":true},"overLimit":{"type":"array","items":{}},"sources":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string"},"url":{"type":"string"},"retrievedAt":{"type":"string"},"status":{"type":"string"}},"additionalProperties":true},"description":"Provenance only (source, url, retrievedAt). Not keyed by check id and does not carry success or error. A check in missing_items does not remove its upstream from sources[]; unavailability is only in missing_items (and unavailable findings)."},"limitations":{"type":"array","items":{"type":"string"}}},"additionalProperties":true},"example":{"coverage":1,"keywords":[{"keyword":"steel water bottle","found":true,"fields":["backendTerms"]},{"keyword":"insulated","found":true,"fields":["title","backendTerms"]}],"duplicatesInBackend":["steel","bottle","…"],"lengths":{"titleChars":28,"backendBytes":28},"overLimit":[],"sources":[{"source":"Caller-supplied marketplace fees, costs, ads rows and listing text processed locally","url":"https://www.brainiac.software/api/v1/ecommerce-profitability","retrievedAt":"2026-11-14","status":"ok"}],"limitations":["Text is lowercased NFC and tokenised on non-letters/digits. A keyword matches a field when every token appears there (o…","Backend duplicates are tokens also present in the title or repeated in backend terms. Byte length uses UTF-8.","…"]}}}},"400":{"description":"Invalid JSON or request schema. Not charged (no payment-response). If this 400 is returned before the Idempotency-Key is reserved, the key is not stored — fix the body and you may reuse the key. If an operation-path 400 was stored after a payment-signature was attached, the same key + same body replays it; the same key + a different body returns 409."},"402":{"description":"Payment required. The JSON body is the x402 PaymentRequired object. An unpaid 402 does not store the Idempotency-Key. A 402 after payment-signature releases the key and includes prior-payment-attempt (nonce, settled false|unknown). Not charged; no payment-response. Before re-signing after a post-signature 402, check USDC authorizationState(payer, nonce) on Base."},"409":{"description":"Idempotency conflict, in-progress payment, or expired result cache. Same key with a different body after a stored result returns conflict. Reusing the key cannot trigger a second charge. Not charged when settlement did not occur."},"413":{"description":"Request body exceeds the 24 MB limit. Not charged."},"500":{"description":"Operation failed before settlement, so no payment is taken (no payment-response). The error is stored: reuse the same Idempotency-Key and body to retrieve it without paying again. Use a new key for a fresh attempt with a new payment-signature."},"502":{"description":"Facilitator verify/settle transport failure (often timeout). After payment-signature this is returned as SETTLEMENT_UNKNOWN with prior-payment-attempt; the outcome is stored under the Idempotency-Key. With the shared store configured, other instances replay it instead of settling again; without it, each instance keeps its own memory. The authorization may already be settled on-chain — do not re-sign until USDC authorizationState(payer, nonce) on Base is false."},"503":{"description":"Payment or retry-safe result storage is unavailable; the operation is not run. Not charged; no payment-response. A 503 after payment-signature releases the Idempotency-Key and includes prior-payment-attempt."}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.02"},"protocols":[{"x402":{"facilitator":"https://api.cdp.coinbase.com/platform/v2/x402"}}],"facilitator":"https://api.cdp.coinbase.com/platform/v2/x402"}}},"/api/v1/ecommerce-profitability/landed-cost-import":{"post":{"operationId":"allocate_import_costs_to_sku_landed_cost","summary":"Allocate import costs to SKU landed cost","description":"Allocate shipment freight and insurance by value, weight or volume, compute CIF or FOB customs value, duty and import VAT from caller rates, and return per-unit landed cost.","tags":["ecommerce-profitability"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"currency":{"type":"string","minLength":3,"maxLength":3},"lines":{"minItems":1,"maxItems":5000,"type":"array","items":{"type":"object","properties":{"sku":{"type":"string","minLength":1,"maxLength":80},"units":{"type":"integer","exclusiveMinimum":0,"maximum":10000000},"unitCost":{"type":"integer","minimum":0,"maximum":9007199254740991},"weightKg":{"type":"number","minimum":0,"maximum":1000000},"volumeM3":{"type":"number","minimum":0,"maximum":1000000},"dutyRate":{"type":"number","minimum":0,"maximum":1}},"required":["sku","units","unitCost","weightKg","volumeM3","dutyRate"],"additionalProperties":false}},"freight":{"type":"integer","minimum":0,"maximum":9007199254740991},"insurance":{"type":"integer","minimum":0,"maximum":9007199254740991},"allocation":{"type":"string","enum":["value","weight","volume"]},"dutyBasis":{"type":"string","enum":["CIF","FOB"]},"importVatRate":{"type":"number","minimum":0,"maximum":1},"vatRecoverable":{"type":"boolean"}},"required":["currency","lines","freight","insurance","allocation","dutyBasis","importVatRate","vatRecoverable"],"additionalProperties":false},"example":{"currency":"GBP","lines":[{"sku":"A","units":100,"unitCost":500,"weightKg":50,"volumeM3":0.2,"dutyRate":0.12},{"sku":"B","units":50,"unitCost":1000,"weightKg":50,"volumeM3":0.3,"dutyRate":0}],"freight":20000,"insurance":1000,"allocation":"value","dutyBasis":"CIF","importVatRate":0.2,"vatRecoverable":true}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Fresh random 32-byte value encoded as 64 hexadecimal characters. Reuse unchanged only for retries of the same operation and request.","schema":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"}}],"responses":{"200":{"description":"Illustrative endpoint-specific JSON response shape. For coverage operations, HTTP 200 is used for status complete, partial, and failed; all three settle and are charged at the full listed price. A settled 2xx includes a payment-response response header (facilitator settlement receipt; may include a transaction reference). Conditional fields depend on the result and data-source availability.","headers":{"payment-response":{"description":"Present on settled 2xx only. Facilitator settlement receipt for the x402 payment (not present on 4xx/5xx, which are not charged).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"currency":{"type":"string"},"lines":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string"},"goods":{"type":"number"},"freight":{"type":"number"},"insurance":{"type":"number"},"customsValue":{"type":"number"},"duty":{"type":"number"},"importVat":{"type":"number"},"landedTotal":{"type":"number"},"landedPerUnit":{"type":"number"}},"additionalProperties":true}},"totals":{"type":"object","properties":{"goods":{"type":"number"},"freight":{"type":"number"},"insurance":{"type":"number"},"duty":{"type":"number"},"importVat":{"type":"number"},"landedTotal":{"type":"number"}},"additionalProperties":true},"sources":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string"},"url":{"type":"string"},"retrievedAt":{"type":"string"},"status":{"type":"string"}},"additionalProperties":true},"description":"Provenance only (source, url, retrievedAt). Not keyed by check id and does not carry success or error. A check in missing_items does not remove its upstream from sources[]; unavailability is only in missing_items (and unavailable findings)."},"limitations":{"type":"array","items":{"type":"string"}}},"additionalProperties":true},"example":{"currency":"GBP","lines":[{"sku":"A","goods":50000,"freight":10000,"insurance":500,"customsValue":60500,"duty":7260,"importVat":13552,"landedTotal":67760,"landedPerUnit":678},{"sku":"B","goods":50000,"freight":10000,"insurance":500,"customsValue":60500,"duty":0,"importVat":12100,"landedTotal":60500,"landedPerUnit":1210}],"totals":{"goods":100000,"freight":20000,"insurance":1000,"duty":7260,"importVat":25652,"landedTotal":128260},"sources":[{"source":"Caller-supplied marketplace fees, costs, ads rows and listing text processed locally","url":"https://www.brainiac.software/api/v1/ecommerce-profitability","retrievedAt":"2026-11-14","status":"ok"}],"limitations":["Freight and insurance are allocated by value, weight or volume with largest-remainder rounding so line totals match the…","CIF customs value includes allocated freight and insurance; FOB uses goods only. Duty and import VAT use caller rates; …","…"]}}}},"400":{"description":"Invalid JSON or request schema. Not charged (no payment-response). If this 400 is returned before the Idempotency-Key is reserved, the key is not stored — fix the body and you may reuse the key. If an operation-path 400 was stored after a payment-signature was attached, the same key + same body replays it; the same key + a different body returns 409."},"402":{"description":"Payment required. The JSON body is the x402 PaymentRequired object. An unpaid 402 does not store the Idempotency-Key. A 402 after payment-signature releases the key and includes prior-payment-attempt (nonce, settled false|unknown). Not charged; no payment-response. Before re-signing after a post-signature 402, check USDC authorizationState(payer, nonce) on Base."},"409":{"description":"Idempotency conflict, in-progress payment, or expired result cache. Same key with a different body after a stored result returns conflict. Reusing the key cannot trigger a second charge. Not charged when settlement did not occur."},"413":{"description":"Request body exceeds the 24 MB limit. Not charged."},"500":{"description":"Operation failed before settlement, so no payment is taken (no payment-response). The error is stored: reuse the same Idempotency-Key and body to retrieve it without paying again. Use a new key for a fresh attempt with a new payment-signature."},"502":{"description":"Facilitator verify/settle transport failure (often timeout). After payment-signature this is returned as SETTLEMENT_UNKNOWN with prior-payment-attempt; the outcome is stored under the Idempotency-Key. With the shared store configured, other instances replay it instead of settling again; without it, each instance keeps its own memory. The authorization may already be settled on-chain — do not re-sign until USDC authorizationState(payer, nonce) on Base is false."},"503":{"description":"Payment or retry-safe result storage is unavailable; the operation is not run. Not charged; no payment-response. A 503 after payment-signature releases the Idempotency-Key and includes prior-payment-attempt."}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.04"},"protocols":[{"x402":{"facilitator":"https://api.cdp.coinbase.com/platform/v2/x402"}}],"facilitator":"https://api.cdp.coinbase.com/platform/v2/x402"}}},"/api/v1/ecommerce-profitability/price-elasticity-estimate":{"post":{"operationId":"estimate_own_price_elasticity_from_history","summary":"Estimate own-price elasticity from history","description":"OLS of ln(units) on ln(price) with optional week or month seasonal dummies, classical standard errors and a 95% t interval from caller price/quantity history.","tags":["ecommerce-profitability"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"observations":{"minItems":12,"maxItems":20000,"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"price":{"type":"number","exclusiveMinimum":0},"units":{"type":"number","minimum":0},"promo":{"type":"boolean"}},"required":["date","price","units"],"additionalProperties":false}},"seasonality":{"default":"none","type":"string","enum":["none","week_of_year","month"]},"promoFlagField":{"anyOf":[{"type":"string","const":"promo"},{"type":"null"}]}},"required":["observations"],"additionalProperties":false},"example":{"observations":[{"date":"2026-01-01","price":10,"units":10},{"date":"2026-01-02","price":12,"units":6.944444444444445},{"date":"2026-01-03","price":14,"units":5.1020408163265305},{"date":"2026-01-04","price":16,"units":3.90625},{"date":"2026-01-05","price":18,"units":3.0864197530864197},{"date":"2026-01-06","price":20,"units":2.5},{"date":"2026-01-07","price":22,"units":2.066115702479339},{"date":"2026-01-08","price":24,"units":1.7361111111111112},{"date":"2026-01-09","price":26,"units":1.4792899408284024},{"date":"2026-01-10","price":28,"units":1.2755102040816326},{"date":"2026-01-11","price":30,"units":1.1111111111111112},{"date":"2026-01-12","price":32,"units":0.9765625}],"seasonality":"none","promoFlagField":null}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Fresh random 32-byte value encoded as 64 hexadecimal characters. Reuse unchanged only for retries of the same operation and request.","schema":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"}}],"responses":{"200":{"description":"Illustrative endpoint-specific JSON response shape. For coverage operations, HTTP 200 is used for status complete, partial, and failed; all three settle and are charged at the full listed price. A settled 2xx includes a payment-response response header (facilitator settlement receipt; may include a transaction reference). Conditional fields depend on the result and data-source availability.","headers":{"payment-response":{"description":"Present on settled 2xx only. Facilitator settlement receipt for the x402 payment (not present on 4xx/5xx, which are not charged).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"elasticity":{"type":"number"},"stdError":{"type":"number"},"ci95":{"type":"array","items":{"type":"number"}},"r2":{"type":"number"},"n":{"type":"number"},"droppedZeroUnits":{"type":"number"},"priceVariationCv":{"type":"number"},"warnings":{"type":"array","items":{}},"sources":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string"},"url":{"type":"string"},"retrievedAt":{"type":"string"},"status":{"type":"string"}},"additionalProperties":true},"description":"Provenance only (source, url, retrievedAt). Not keyed by check id and does not carry success or error. A check in missing_items does not remove its upstream from sources[]; unavailability is only in missing_items (and unavailable findings)."},"limitations":{"type":"array","items":{"type":"string"}}},"additionalProperties":true},"example":{"elasticity":-2,"stdError":0,"ci95":[-2,-2],"r2":1,"n":12,"droppedZeroUnits":0,"priceVariationCv":0.328767,"warnings":[],"sources":[{"source":"Caller-supplied marketplace fees, costs, ads rows and listing text processed locally","url":"https://www.brainiac.software/api/v1/ecommerce-profitability","retrievedAt":"2026-11-14","status":"ok"}],"limitations":["OLS of ln(units) on ln(price) plus seasonal dummies (one level dropped). Observations with units = 0 are dropped.","Classical standard errors; ci95 uses the two-sided t critical value at 95% with residual degrees of freedom.","…"]}}}},"400":{"description":"Invalid JSON or request schema. Not charged (no payment-response). If this 400 is returned before the Idempotency-Key is reserved, the key is not stored — fix the body and you may reuse the key. If an operation-path 400 was stored after a payment-signature was attached, the same key + same body replays it; the same key + a different body returns 409."},"402":{"description":"Payment required. The JSON body is the x402 PaymentRequired object. An unpaid 402 does not store the Idempotency-Key. A 402 after payment-signature releases the key and includes prior-payment-attempt (nonce, settled false|unknown). Not charged; no payment-response. Before re-signing after a post-signature 402, check USDC authorizationState(payer, nonce) on Base."},"409":{"description":"Idempotency conflict, in-progress payment, or expired result cache. Same key with a different body after a stored result returns conflict. Reusing the key cannot trigger a second charge. Not charged when settlement did not occur."},"413":{"description":"Request body exceeds the 24 MB limit. Not charged."},"500":{"description":"Operation failed before settlement, so no payment is taken (no payment-response). The error is stored: reuse the same Idempotency-Key and body to retrieve it without paying again. Use a new key for a fresh attempt with a new payment-signature."},"502":{"description":"Facilitator verify/settle transport failure (often timeout). After payment-signature this is returned as SETTLEMENT_UNKNOWN with prior-payment-attempt; the outcome is stored under the Idempotency-Key. With the shared store configured, other instances replay it instead of settling again; without it, each instance keeps its own memory. The authorization may already be settled on-chain — do not re-sign until USDC authorizationState(payer, nonce) on Base is false."},"503":{"description":"Payment or retry-safe result storage is unavailable; the operation is not run. Not charged; no payment-response. A 503 after payment-signature releases the Idempotency-Key and includes prior-payment-attempt."}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.04"},"protocols":[{"x402":{"facilitator":"https://api.cdp.coinbase.com/platform/v2/x402"}}],"facilitator":"https://api.cdp.coinbase.com/platform/v2/x402"}}},"/api/v1/ecommerce-profitability/competitive-price-index":{"post":{"operationId":"price_index_and_rank_vs_competitors","summary":"Price index and rank vs competitors","description":"Compare our landed price (price + shipping) with in-stock competitor landed prices to return median index, min and rank.","tags":["ecommerce-profitability"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"ourPrice":{"type":"integer","minimum":0,"maximum":9007199254740991},"ourShipping":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991},"competitors":{"minItems":1,"maxItems":5000,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"price":{"type":"integer","minimum":0,"maximum":9007199254740991},"shipping":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991},"inStock":{"type":"boolean"}},"required":["name","price","inStock"],"additionalProperties":false}}},"required":["ourPrice","competitors"],"additionalProperties":false},"example":{"ourPrice":2499,"ourShipping":0,"competitors":[{"name":"X","price":2299,"shipping":399,"inStock":true},{"name":"Y","price":2599,"shipping":0,"inStock":true},{"name":"Z","price":1999,"shipping":0,"inStock":false}]}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Fresh random 32-byte value encoded as 64 hexadecimal characters. Reuse unchanged only for retries of the same operation and request.","schema":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"}}],"responses":{"200":{"description":"Illustrative endpoint-specific JSON response shape. For coverage operations, HTTP 200 is used for status complete, partial, and failed; all three settle and are charged at the full listed price. A settled 2xx includes a payment-response response header (facilitator settlement receipt; may include a transaction reference). Conditional fields depend on the result and data-source availability.","headers":{"payment-response":{"description":"Present on settled 2xx only. Facilitator settlement receipt for the x402 payment (not present on 4xx/5xx, which are not charged).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"ourLanded":{"type":"number"},"competitorMedian":{"type":"number"},"competitorMin":{"type":"number"},"index":{"type":"number"},"rank":{"type":"number"},"of":{"type":"number"},"excludedOutOfStock":{"type":"number"},"sources":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string"},"url":{"type":"string"},"retrievedAt":{"type":"string"},"status":{"type":"string"}},"additionalProperties":true},"description":"Provenance only (source, url, retrievedAt). Not keyed by check id and does not carry success or error. A check in missing_items does not remove its upstream from sources[]; unavailability is only in missing_items (and unavailable findings)."},"limitations":{"type":"array","items":{"type":"string"}}},"additionalProperties":true},"example":{"ourLanded":2499,"competitorMedian":2648.5,"competitorMin":2599,"index":94.36,"rank":1,"of":3,"excludedOutOfStock":1,"sources":[{"source":"Caller-supplied marketplace fees, costs, ads rows and listing text processed locally","url":"https://www.brainiac.software/api/v1/ecommerce-profitability","retrievedAt":"2026-11-14","status":"ok"}],"limitations":["Landed price = price + shipping. Out-of-stock competitors are excluded from the median, min and rank pool.","Index = 100 × our landed / median competitor landed. Rank 1 is the cheapest among us and in-stock competitors.","…"]}}}},"400":{"description":"Invalid JSON or request schema. Not charged (no payment-response). If this 400 is returned before the Idempotency-Key is reserved, the key is not stored — fix the body and you may reuse the key. If an operation-path 400 was stored after a payment-signature was attached, the same key + same body replays it; the same key + a different body returns 409."},"402":{"description":"Payment required. The JSON body is the x402 PaymentRequired object. An unpaid 402 does not store the Idempotency-Key. A 402 after payment-signature releases the key and includes prior-payment-attempt (nonce, settled false|unknown). Not charged; no payment-response. Before re-signing after a post-signature 402, check USDC authorizationState(payer, nonce) on Base."},"409":{"description":"Idempotency conflict, in-progress payment, or expired result cache. Same key with a different body after a stored result returns conflict. Reusing the key cannot trigger a second charge. Not charged when settlement did not occur."},"413":{"description":"Request body exceeds the 24 MB limit. Not charged."},"500":{"description":"Operation failed before settlement, so no payment is taken (no payment-response). The error is stored: reuse the same Idempotency-Key and body to retrieve it without paying again. Use a new key for a fresh attempt with a new payment-signature."},"502":{"description":"Facilitator verify/settle transport failure (often timeout). After payment-signature this is returned as SETTLEMENT_UNKNOWN with prior-payment-attempt; the outcome is stored under the Idempotency-Key. With the shared store configured, other instances replay it instead of settling again; without it, each instance keeps its own memory. The authorization may already be settled on-chain — do not re-sign until USDC authorizationState(payer, nonce) on Base is false."},"503":{"description":"Payment or retry-safe result storage is unavailable; the operation is not run. Not charged; no payment-response. A 503 after payment-signature releases the Idempotency-Key and includes prior-payment-attempt."}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.02"},"protocols":[{"x402":{"facilitator":"https://api.cdp.coinbase.com/platform/v2/x402"}}],"facilitator":"https://api.cdp.coinbase.com/platform/v2/x402"}}},"/api/v1/ecommerce-profitability/bundle-pricing":{"post":{"operationId":"compare_bundle_margin_with_separate_sales","summary":"Compare bundle margin with separate sales","description":"Compute separate and bundle margins, discount depth, margin delta and the break-even bundle price from caller component and bundle fees.","tags":["ecommerce-profitability"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"components":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"object","properties":{"sku":{"type":"string","minLength":1,"maxLength":80},"price":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"unitCost":{"type":"integer","minimum":0,"maximum":9007199254740991},"feeRate":{"type":"number","minimum":0,"maximum":1},"fulfilmentFee":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["sku","price","unitCost","feeRate","fulfilmentFee"],"additionalProperties":false}},"bundle":{"type":"object","properties":{"price":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"feeRate":{"type":"number","minimum":0,"exclusiveMaximum":1},"fulfilmentFee":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["price","feeRate","fulfilmentFee"],"additionalProperties":false}},"required":["components","bundle"],"additionalProperties":false},"example":{"components":[{"sku":"A","price":1500,"unitCost":500,"feeRate":0.15,"fulfilmentFee":300},{"sku":"B","price":1000,"unitCost":300,"feeRate":0.15,"fulfilmentFee":300}],"bundle":{"price":2200,"feeRate":0.15,"fulfilmentFee":400}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Fresh random 32-byte value encoded as 64 hexadecimal characters. Reuse unchanged only for retries of the same operation and request.","schema":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"}}],"responses":{"200":{"description":"Illustrative endpoint-specific JSON response shape. For coverage operations, HTTP 200 is used for status complete, partial, and failed; all three settle and are charged at the full listed price. A settled 2xx includes a payment-response response header (facilitator settlement receipt; may include a transaction reference). Conditional fields depend on the result and data-source availability.","headers":{"payment-response":{"description":"Present on settled 2xx only. Facilitator settlement receipt for the x402 payment (not present on 4xx/5xx, which are not charged).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"separate":{"type":"object","properties":{"revenue":{"type":"number"},"margin":{"type":"number"},"items":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string"},"revenue":{"type":"number"},"margin":{"type":"number"}},"additionalProperties":true}}},"additionalProperties":true},"bundle":{"type":"object","properties":{"revenue":{"type":"number"},"margin":{"type":"number"}},"additionalProperties":true},"discountDepth":{"type":"number"},"marginDelta":{"type":"number"},"breakEvenBundlePrice":{"type":"number"},"sources":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string"},"url":{"type":"string"},"retrievedAt":{"type":"string"},"status":{"type":"string"}},"additionalProperties":true},"description":"Provenance only (source, url, retrievedAt). Not keyed by check id and does not carry success or error. A check in missing_items does not remove its upstream from sources[]; unavailability is only in missing_items (and unavailable findings)."},"limitations":{"type":"array","items":{"type":"string"}}},"additionalProperties":true},"example":{"separate":{"revenue":2500,"margin":725,"items":[{"sku":"A","revenue":1500,"margin":475},{"sku":"B","revenue":1000,"margin":250}]},"bundle":{"revenue":2200,"margin":670},"discountDepth":0.12,"marginDelta":-55,"breakEvenBundlePrice":2265,"sources":[{"source":"Caller-supplied marketplace fees, costs, ads rows and listing text processed locally","url":"https://www.brainiac.software/api/v1/ecommerce-profitability","retrievedAt":"2026-11-14","status":"ok"}],"limitations":["Margin = price − unitCost − price × feeRate − fulfilmentFee. Fees are caller-supplied.","Discount depth = 1 − bundle price / Σ component prices.","…"]}}}},"400":{"description":"Invalid JSON or request schema. Not charged (no payment-response). If this 400 is returned before the Idempotency-Key is reserved, the key is not stored — fix the body and you may reuse the key. If an operation-path 400 was stored after a payment-signature was attached, the same key + same body replays it; the same key + a different body returns 409."},"402":{"description":"Payment required. The JSON body is the x402 PaymentRequired object. An unpaid 402 does not store the Idempotency-Key. A 402 after payment-signature releases the key and includes prior-payment-attempt (nonce, settled false|unknown). Not charged; no payment-response. Before re-signing after a post-signature 402, check USDC authorizationState(payer, nonce) on Base."},"409":{"description":"Idempotency conflict, in-progress payment, or expired result cache. Same key with a different body after a stored result returns conflict. Reusing the key cannot trigger a second charge. Not charged when settlement did not occur."},"413":{"description":"Request body exceeds the 24 MB limit. Not charged."},"500":{"description":"Operation failed before settlement, so no payment is taken (no payment-response). The error is stored: reuse the same Idempotency-Key and body to retrieve it without paying again. Use a new key for a fresh attempt with a new payment-signature."},"502":{"description":"Facilitator verify/settle transport failure (often timeout). After payment-signature this is returned as SETTLEMENT_UNKNOWN with prior-payment-attempt; the outcome is stored under the Idempotency-Key. With the shared store configured, other instances replay it instead of settling again; without it, each instance keeps its own memory. The authorization may already be settled on-chain — do not re-sign until USDC authorizationState(payer, nonce) on Base is false."},"503":{"description":"Payment or retry-safe result storage is unavailable; the operation is not run. Not charged; no payment-response. A 503 after payment-signature releases the Idempotency-Key and includes prior-payment-attempt."}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.02"},"protocols":[{"x402":{"facilitator":"https://api.cdp.coinbase.com/platform/v2/x402"}}],"facilitator":"https://api.cdp.coinbase.com/platform/v2/x402"}}},"/api/v1/ecommerce-profitability/packaging-optimize":{"post":{"operationId":"pick_the_box_that_minimises_billable_weight","summary":"Pick the box that minimises billable weight","description":"Try caller boxes and orientations with padding, compute dimensional and billable weight from a caller divisor, and pick the best by billable weight or box cost.","tags":["ecommerce-profitability"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"items":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"object","properties":{"l":{"type":"number","exclusiveMinimum":0},"w":{"type":"number","exclusiveMinimum":0},"h":{"type":"number","exclusiveMinimum":0},"weightG":{"type":"number","exclusiveMinimum":0},"qty":{"default":1,"type":"integer","exclusiveMinimum":0,"maximum":1000}},"required":["l","w","h","weightG"],"additionalProperties":false}},"boxes":{"minItems":1,"maxItems":200,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40},"l":{"type":"number","exclusiveMinimum":0},"w":{"type":"number","exclusiveMinimum":0},"h":{"type":"number","exclusiveMinimum":0},"tareG":{"type":"number","minimum":0},"cost":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["id","l","w","h","tareG"],"additionalProperties":false}},"paddingCm":{"default":0,"type":"number","minimum":0,"maximum":100},"dimDivisor":{"type":"number","exclusiveMinimum":0},"objective":{"default":"billable_weight","type":"string","enum":["billable_weight","box_cost"]}},"required":["items","boxes","dimDivisor"],"additionalProperties":false},"example":{"items":[{"l":30,"w":20,"h":10,"weightG":1500,"qty":1}],"boxes":[{"id":"S","l":32,"w":22,"h":12,"tareG":200,"cost":40}],"paddingCm":1,"dimDivisor":5000,"objective":"billable_weight"}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Fresh random 32-byte value encoded as 64 hexadecimal characters. Reuse unchanged only for retries of the same operation and request.","schema":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"}}],"responses":{"200":{"description":"Illustrative endpoint-specific JSON response shape. For coverage operations, HTTP 200 is used for status complete, partial, and failed; all three settle and are charged at the full listed price. A settled 2xx includes a payment-response response header (facilitator settlement receipt; may include a transaction reference). Conditional fields depend on the result and data-source availability.","headers":{"payment-response":{"description":"Present on settled 2xx only. Facilitator settlement receipt for the x402 payment (not present on 4xx/5xx, which are not charged).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"best":{"type":"object","properties":{"boxId":{"type":"string"},"orientation":{"type":"array","items":{"type":"number"}},"actualG":{"type":"number"},"dimWeightG":{"type":"number"},"billableG":{"type":"number"}},"additionalProperties":true},"rejected":{"type":"array","items":{}},"sources":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string"},"url":{"type":"string"},"retrievedAt":{"type":"string"},"status":{"type":"string"}},"additionalProperties":true},"description":"Provenance only (source, url, retrievedAt). Not keyed by check id and does not carry success or error. A check in missing_items does not remove its upstream from sources[]; unavailability is only in missing_items (and unavailable findings)."},"limitations":{"type":"array","items":{"type":"string"}}},"additionalProperties":true},"example":{"best":{"boxId":"S","orientation":[30,20,"…"],"actualG":1700,"dimWeightG":1690,"billableG":1700},"rejected":[],"sources":[{"source":"Caller-supplied marketplace fees, costs, ads rows and listing text processed locally","url":"https://www.brainiac.software/api/v1/ecommerce-profitability","retrievedAt":"2026-11-14","status":"ok"}],"limitations":["Items form one bounding block (identical items stack on the smallest edge). Each box tries all six orientations with pa…","Dimensional weight (g) = ceil(l × w × h / dimDivisor × 1000). Billable = max(actual + tare, dim). Ties prefer smaller b…","…"]}}}},"400":{"description":"Invalid JSON or request schema. Not charged (no payment-response). If this 400 is returned before the Idempotency-Key is reserved, the key is not stored — fix the body and you may reuse the key. If an operation-path 400 was stored after a payment-signature was attached, the same key + same body replays it; the same key + a different body returns 409."},"402":{"description":"Payment required. The JSON body is the x402 PaymentRequired object. An unpaid 402 does not store the Idempotency-Key. A 402 after payment-signature releases the key and includes prior-payment-attempt (nonce, settled false|unknown). Not charged; no payment-response. Before re-signing after a post-signature 402, check USDC authorizationState(payer, nonce) on Base."},"409":{"description":"Idempotency conflict, in-progress payment, or expired result cache. Same key with a different body after a stored result returns conflict. Reusing the key cannot trigger a second charge. Not charged when settlement did not occur."},"413":{"description":"Request body exceeds the 24 MB limit. Not charged."},"500":{"description":"Operation failed before settlement, so no payment is taken (no payment-response). The error is stored: reuse the same Idempotency-Key and body to retrieve it without paying again. Use a new key for a fresh attempt with a new payment-signature."},"502":{"description":"Facilitator verify/settle transport failure (often timeout). After payment-signature this is returned as SETTLEMENT_UNKNOWN with prior-payment-attempt; the outcome is stored under the Idempotency-Key. With the shared store configured, other instances replay it instead of settling again; without it, each instance keeps its own memory. The authorization may already be settled on-chain — do not re-sign until USDC authorizationState(payer, nonce) on Base is false."},"503":{"description":"Payment or retry-safe result storage is unavailable; the operation is not run. Not charged; no payment-response. A 503 after payment-signature releases the Idempotency-Key and includes prior-payment-attempt."}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.03"},"protocols":[{"x402":{"facilitator":"https://api.cdp.coinbase.com/platform/v2/x402"}}],"facilitator":"https://api.cdp.coinbase.com/platform/v2/x402"}}},"/api/v1/ecommerce-profitability/settlement-tax-reconcile":{"post":{"operationId":"reconcile_marketplace_settlement_tax_lines","summary":"Reconcile marketplace settlement tax lines","description":"Match order tax charged to settlement tax, marketplace-facilitator tax and refund lines within a tolerance and total seller vs marketplace collected tax.","tags":["ecommerce-profitability"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"orders":{"minItems":1,"maxItems":50000,"type":"array","items":{"type":"object","properties":{"orderId":{"type":"string","minLength":1,"maxLength":80},"taxCharged":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"jurisdiction":{"type":"string","minLength":1,"maxLength":40}},"required":["orderId","taxCharged"],"additionalProperties":false}},"settlementLines":{"default":[],"maxItems":200000,"type":"array","items":{"type":"object","properties":{"orderId":{"type":"string","minLength":1,"maxLength":80},"type":{"type":"string","enum":["tax","marketplace_facilitator_tax","refund_tax"]},"amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["orderId","type","amount"],"additionalProperties":false}},"tolerance":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["orders"],"additionalProperties":false},"example":{"orders":[{"orderId":"1","taxCharged":825,"jurisdiction":"TX"}],"settlementLines":[{"orderId":"1","type":"marketplace_facilitator_tax","amount":825}],"tolerance":1}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Fresh random 32-byte value encoded as 64 hexadecimal characters. Reuse unchanged only for retries of the same operation and request.","schema":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"}}],"responses":{"200":{"description":"Illustrative endpoint-specific JSON response shape. For coverage operations, HTTP 200 is used for status complete, partial, and failed; all three settle and are charged at the full listed price. A settled 2xx includes a payment-response response header (facilitator settlement receipt; may include a transaction reference). Conditional fields depend on the result and data-source availability.","headers":{"payment-response":{"description":"Present on settled 2xx only. Facilitator settlement receipt for the x402 payment (not present on 4xx/5xx, which are not charged).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"matched":{"type":"number"},"matchedOrderIds":{"type":"array","items":{"type":"string"}},"mismatches":{"type":"array","items":{}},"missingInSettlement":{"type":"array","items":{}},"unknownOrders":{"type":"array","items":{}},"totals":{"type":"object","properties":{"sellerCollected":{"type":"number"},"marketplaceCollected":{"type":"number"},"refunded":{"type":"number"}},"additionalProperties":true},"sources":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string"},"url":{"type":"string"},"retrievedAt":{"type":"string"},"status":{"type":"string"}},"additionalProperties":true},"description":"Provenance only (source, url, retrievedAt). Not keyed by check id and does not carry success or error. A check in missing_items does not remove its upstream from sources[]; unavailability is only in missing_items (and unavailable findings)."},"limitations":{"type":"array","items":{"type":"string"}}},"additionalProperties":true},"example":{"matched":1,"matchedOrderIds":["1"],"mismatches":[],"missingInSettlement":[],"unknownOrders":[],"totals":{"sellerCollected":0,"marketplaceCollected":825,"refunded":0},"sources":[{"source":"Caller-supplied marketplace fees, costs, ads rows and listing text processed locally","url":"https://www.brainiac.software/api/v1/ecommerce-profitability","retrievedAt":"2026-11-14","status":"ok"}],"limitations":["Seller-collected tax uses type tax; marketplace-collected uses marketplace_facilitator_tax; refund_tax nets against the…","An order matches when |taxCharged − (seller + marketplace − refunds)| ≤ tolerance.","…"]}}}},"400":{"description":"Invalid JSON or request schema. Not charged (no payment-response). If this 400 is returned before the Idempotency-Key is reserved, the key is not stored — fix the body and you may reuse the key. If an operation-path 400 was stored after a payment-signature was attached, the same key + same body replays it; the same key + a different body returns 409."},"402":{"description":"Payment required. The JSON body is the x402 PaymentRequired object. An unpaid 402 does not store the Idempotency-Key. A 402 after payment-signature releases the key and includes prior-payment-attempt (nonce, settled false|unknown). Not charged; no payment-response. Before re-signing after a post-signature 402, check USDC authorizationState(payer, nonce) on Base."},"409":{"description":"Idempotency conflict, in-progress payment, or expired result cache. Same key with a different body after a stored result returns conflict. Reusing the key cannot trigger a second charge. Not charged when settlement did not occur."},"413":{"description":"Request body exceeds the 24 MB limit. Not charged."},"500":{"description":"Operation failed before settlement, so no payment is taken (no payment-response). The error is stored: reuse the same Idempotency-Key and body to retrieve it without paying again. Use a new key for a fresh attempt with a new payment-signature."},"502":{"description":"Facilitator verify/settle transport failure (often timeout). After payment-signature this is returned as SETTLEMENT_UNKNOWN with prior-payment-attempt; the outcome is stored under the Idempotency-Key. With the shared store configured, other instances replay it instead of settling again; without it, each instance keeps its own memory. The authorization may already be settled on-chain — do not re-sign until USDC authorizationState(payer, nonce) on Base is false."},"503":{"description":"Payment or retry-safe result storage is unavailable; the operation is not run. Not charged; no payment-response. A 503 after payment-signature releases the Idempotency-Key and includes prior-payment-attempt."}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.03"},"protocols":[{"x402":{"facilitator":"https://api.cdp.coinbase.com/platform/v2/x402"}}],"facilitator":"https://api.cdp.coinbase.com/platform/v2/x402"}}}},"components":{"schemas":{"ApiError":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}