# Ecommerce Seller Profitability API > 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. Each paid operation uses a fixed USDC price on Base with the x402 exact scheme. Unpaid GET, HEAD, and POST return 402 payment terms (POST validates the body only after payment terms are satisfied). A request that carries payment-signature is not yet charged: settlement happens only after a successful (2xx) result. HTTP 4xx/5xx are not charged. Coverage bodies with status complete, partial, or failed all return HTTP 200 and are charged at the full listed price. Settled 2xx responses include a payment-response header; 4xx/5xx do not. Follow https://www.brainiac.software/agent-instructions.txt for install, payment pins, idempotency, and billing rules. - Product: https://www.brainiac.software/api/ecommerce-profitability - Docs: https://www.brainiac.software/api/ecommerce-profitability/docs - OpenAPI: https://www.brainiac.software/api/ecommerce-profitability/openapi.json - Contact: support@brainiac.software (https://www.brainiac.software/contact) ## Operations ### POST /api/v1/ecommerce-profitability/unit-economics $0.03 USDC. 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. Inputs: currency, pricePerUnit, costs, marketplaceFeeRate?, returnRate, returnLossPerUnit, salesTaxIncluded? Docs: https://www.brainiac.software/api/ecommerce-profitability/docs#ecommerce-profitability-unit-economics Example request: ```json { "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 } ``` Example response: ```json { "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 −…", "…" ] } ``` ### POST /api/v1/ecommerce-profitability/ppc-report-analyze $0.04 USDC. Aggregate ACoS, ROAS, TACoS, CTR and CVR for a search-term report and flag negate, promote and insufficient-data candidates from caller rules. Inputs: currency, rows, totalSales, rules Docs: https://www.brainiac.software/api/ecommerce-profitability/docs#ecommerce-profitability-ppc-report-analyze Example request: ```json { "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 } } ``` Example response: ```json { "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…", "…" ] } ``` ### POST /api/v1/ecommerce-profitability/listing-keyword-coverage $0.02 USDC. Token-match caller keywords against title, bullets, description and backend terms, including simple plurals, and check caller-supplied title and backend length limits. Inputs: title, bullets?, description?, backendTerms?, keywords, limits Docs: https://www.brainiac.software/api/ecommerce-profitability/docs#ecommerce-profitability-listing-keyword-coverage Example request: ```json { "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 } } ``` Example response: ```json { "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.", "…" ] } ``` ### POST /api/v1/ecommerce-profitability/landed-cost-import $0.04 USDC. 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. Inputs: currency, lines, freight, insurance, allocation, dutyBasis, importVatRate, vatRecoverable Docs: https://www.brainiac.software/api/ecommerce-profitability/docs#ecommerce-profitability-landed-cost-import Example request: ```json { "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 } ``` Example response: ```json { "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; …", "…" ] } ``` ### POST /api/v1/ecommerce-profitability/price-elasticity-estimate $0.04 USDC. 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. Inputs: observations, seasonality?, promoFlagField? Docs: https://www.brainiac.software/api/ecommerce-profitability/docs#ecommerce-profitability-price-elasticity-estimate Example request: ```json { "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 } ``` Example response: ```json { "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.", "…" ] } ``` ### POST /api/v1/ecommerce-profitability/competitive-price-index $0.02 USDC. Compare our landed price (price + shipping) with in-stock competitor landed prices to return median index, min and rank. Inputs: ourPrice, ourShipping?, competitors Docs: https://www.brainiac.software/api/ecommerce-profitability/docs#ecommerce-profitability-competitive-price-index Example request: ```json { "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 } ] } ``` Example response: ```json { "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.", "…" ] } ``` ### POST /api/v1/ecommerce-profitability/bundle-pricing $0.02 USDC. Compute separate and bundle margins, discount depth, margin delta and the break-even bundle price from caller component and bundle fees. Inputs: components, bundle Docs: https://www.brainiac.software/api/ecommerce-profitability/docs#ecommerce-profitability-bundle-pricing Example request: ```json { "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 } } ``` Example response: ```json { "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.", "…" ] } ``` ### POST /api/v1/ecommerce-profitability/packaging-optimize $0.03 USDC. 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. Inputs: items, boxes, paddingCm?, dimDivisor, objective? Docs: https://www.brainiac.software/api/ecommerce-profitability/docs#ecommerce-profitability-packaging-optimize Example request: ```json { "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" } ``` Example response: ```json { "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…", "…" ] } ``` ### POST /api/v1/ecommerce-profitability/settlement-tax-reconcile $0.03 USDC. Match order tax charged to settlement tax, marketplace-facilitator tax and refund lines within a tolerance and total seller vs marketplace collected tax. Inputs: orders, settlementLines?, tolerance? Docs: https://www.brainiac.software/api/ecommerce-profitability/docs#ecommerce-profitability-settlement-tax-reconcile Example request: ```json { "orders": [ { "orderId": "1", "taxCharged": 825, "jurisdiction": "TX" } ], "settlementLines": [ { "orderId": "1", "type": "marketplace_facilitator_tax", "amount": 825 } ], "tolerance": 1 } ``` Example response: ```json { "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.", "…" ] } ```