{"openapi":"3.1.0","info":{"title":"Fliprofit reseller fee API","version":"1.2.0","summary":"Free, keyless US reseller fee and profit calculations.","description":"Free, read-only fee and profit calculations for US resale marketplaces, using the same engine as https://www.fliprofit.com. No key needed. Rates last checked 2026-10-24. Not tax advice; link the calculator page when citing.\n\n**Errors:** every 4xx/5xx response is RFC 9457 `application/problem+json` (Problem schema) with a stable machine-readable `code`.\n\n**Rate limit:** 60 requests per minute per IP. Every response carries `RateLimit` / `RateLimit-Policy` (IETF draft) plus `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset`; a 429 adds `Retry-After` (seconds).\n\n**Versioning and deprecation:** the major version is in the path (`/api/v1`). Within v1 we only make additive changes (new fields, endpoints, platforms or options); fee numbers update when marketplaces change their rates. A breaking change ships as `/api/v2`. Before any v1 endpoint is retired it returns a `Deprecation` header (RFC 9745) and a `Sunset` header (RFC 8594) with the retirement date at least 90 days ahead, plus a `Link` header (rel=\"deprecation\") to the notice. Policy: [object Object]/developers#versioning","contact":{"name":"Fliprofit","url":"https://www.fliprofit.com/contact","email":"hello@fliprofit.com"},"termsOfService":"https://www.fliprofit.com/developers#terms"},"externalDocs":{"description":"Developer docs and quickstart","url":"https://www.fliprofit.com/developers"},"servers":[{"url":"https://www.fliprofit.com","description":"Fee API (production)"}],"security":[],"tags":[{"name":"fees","description":"Fee, payout and profit calculations"},{"name":"changes","description":"Dated marketplace fee change log"}],"paths":{"/api/v1/fees":{"get":{"operationId":"listPlatforms","tags":["fees"],"summary":"List supported platforms, their options and categories","responses":{"200":{"description":"Platform list","headers":{"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlatformList"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/v1/fees/{platform}":{"get":{"operationId":"calculateFees","tags":["fees"],"summary":"Fees, payout and profit for one sale on one platform","description":"With `price`, returns a FeeResult. Without `price`, returns that platform's details (PlatformInfo).","parameters":[{"name":"platform","in":"path","required":true,"schema":{"type":"string","enum":["ebay","poshmark","mercari","whatnot","depop","etsy","facebook","amazon","grailed","reverb","tcgplayer","tiktok","vinted"]}},{"name":"price","required":false,"in":"query","schema":{"type":"number","minimum":0},"description":"Sale price in USD"},{"name":"shipCharged","in":"query","schema":{"type":"number","minimum":0},"description":"Shipping the buyer paid you, USD"},{"name":"taxRate","in":"query","schema":{"type":"number","minimum":0},"description":"Buyer sales tax %, e.g. 8 (used where the platform charges fees on tax)"},{"name":"itemCost","in":"query","schema":{"type":"number","minimum":0},"description":"What you paid for the item, USD"},{"name":"shipCost","in":"query","schema":{"type":"number","minimum":0},"description":"Your label/postage cost, USD"},{"name":"otherCost","in":"query","schema":{"type":"number","minimum":0},"description":"Packaging, promotion and other costs, USD"},{"name":"category","in":"query","required":false,"schema":{"type":"string"},"description":"Platform-specific option; see /api/v1/fees for allowed values"},{"name":"adRate","in":"query","required":false,"schema":{"type":"string"},"description":"Platform-specific option; see /api/v1/fees for allowed values"},{"name":"tier","in":"query","required":false,"schema":{"type":"string"},"description":"Platform-specific option; see /api/v1/fees for allowed values"},{"name":"highValue","in":"query","required":false,"schema":{"type":"string"},"description":"Platform-specific option; see /api/v1/fees for allowed values"},{"name":"boost","in":"query","required":false,"schema":{"type":"string"},"description":"Platform-specific option; see /api/v1/fees for allowed values"},{"name":"ownLabel","in":"query","required":false,"schema":{"type":"string"},"description":"Platform-specific option; see /api/v1/fees for allowed values"},{"name":"offsiteAds","in":"query","required":false,"schema":{"type":"string"},"description":"Platform-specific option; see /api/v1/fees for allowed values"},{"name":"mode","in":"query","required":false,"schema":{"type":"string"},"description":"Platform-specific option; see /api/v1/fees for allowed values"},{"name":"plan","in":"query","required":false,"schema":{"type":"string"},"description":"Platform-specific option; see /api/v1/fees for allowed values"},{"name":"fbaFee","in":"query","required":false,"schema":{"type":"string"},"description":"Platform-specific option; see /api/v1/fees for allowed values"},{"name":"grailedLabel","in":"query","required":false,"schema":{"type":"string"},"description":"Platform-specific option; see /api/v1/fees for allowed values"},{"name":"processing","in":"query","required":false,"schema":{"type":"string"},"description":"Platform-specific option; see /api/v1/fees for allowed values"},{"name":"preferred","in":"query","required":false,"schema":{"type":"string"},"description":"Platform-specific option; see /api/v1/fees for allowed values"},{"name":"sellerType","in":"query","required":false,"schema":{"type":"string"},"description":"Platform-specific option; see /api/v1/fees for allowed values"},{"name":"bump","in":"query","required":false,"schema":{"type":"string"},"description":"Platform-specific option; see /api/v1/fees for allowed values"}],"responses":{"200":{"description":"Fee breakdown (with price) or platform details (without price)","headers":{"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/FeeResult"},{"$ref":"#/components/schemas/PlatformInfo"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/v1/compare":{"get":{"operationId":"comparePlatforms","tags":["fees"],"summary":"One sale on every platform, ranked by profit (default options)","parameters":[{"name":"price","required":true,"in":"query","schema":{"type":"number","minimum":0},"description":"Sale price in USD"},{"name":"shipCharged","in":"query","schema":{"type":"number","minimum":0},"description":"Shipping the buyer paid you, USD"},{"name":"taxRate","in":"query","schema":{"type":"number","minimum":0},"description":"Buyer sales tax %, e.g. 8 (used where the platform charges fees on tax)"},{"name":"itemCost","in":"query","schema":{"type":"number","minimum":0},"description":"What you paid for the item, USD"},{"name":"shipCost","in":"query","schema":{"type":"number","minimum":0},"description":"Your label/postage cost, USD"},{"name":"otherCost","in":"query","schema":{"type":"number","minimum":0},"description":"Packaging, promotion and other costs, USD"}],"responses":{"200":{"description":"Ranked list","headers":{"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Comparison"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/v1/changes":{"servers":[{"url":"https://mcp.fliprofit.com","description":"Fee change log (MCP worker)"}],"get":{"operationId":"listFeeChanges","tags":["changes"],"summary":"Dated US marketplace fee changes with official sources","parameters":[{"name":"platform","in":"query","schema":{"type":"string","enum":["ebay","poshmark","mercari","whatnot","depop","etsy","facebook","amazon","grailed","reverb","tcgplayer","tiktok","vinted"]}},{"name":"since","in":"query","schema":{"type":"string","format":"date"},"description":"Only changes effective on or after this date"},{"name":"upcoming","in":"query","schema":{"type":"boolean"},"description":"Only changes not yet in effect"}],"responses":{"200":{"description":"Fee change log","headers":{"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeeChangeLog"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/v1/changes.atom":{"servers":[{"url":"https://mcp.fliprofit.com","description":"Fee change log (MCP worker)"}],"get":{"operationId":"feeChangesAtom","tags":["changes"],"summary":"Fee change log as an Atom feed","responses":{"200":{"description":"Atom 1.0 feed","headers":{"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/atom+xml":{"schema":{"type":"string"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}}}}},"components":{"headers":{"RateLimit":{"description":"Remaining quota and seconds until reset (IETF draft), e.g. `\"per-ip\";r=59;t=42`","schema":{"type":"string"}},"RateLimitPolicy":{"description":"Quota policy (IETF draft): `\"per-ip\";q=60;w=60` = 60 requests per 60 seconds per IP","schema":{"type":"string"}},"RateLimitLimit":{"description":"Requests allowed per window (60)","schema":{"type":"integer"}},"RateLimitRemaining":{"description":"Requests left in the current window","schema":{"type":"integer"}},"RateLimitReset":{"description":"Seconds until the window resets","schema":{"type":"integer"}},"RetryAfter":{"description":"Seconds to wait before retrying (RFC 9110)","schema":{"type":"integer"}}},"responses":{"BadRequest":{"description":"Missing or invalid parameter","headers":{"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"NotFound":{"description":"Unknown platform or endpoint","headers":{"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"TooManyRequests":{"description":"Rate limit exceeded (60 requests per minute per IP)","headers":{"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"ServerError":{"description":"Unexpected server error","headers":{"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"schemas":{"Problem":{"type":"object","description":"RFC 9457 problem details","required":["type","title","status","detail","code"],"properties":{"type":{"type":"string","format":"uri","description":"URI identifying the problem type (points to the docs)"},"title":{"type":"string"},"status":{"type":"integer","minimum":400,"maximum":599},"detail":{"type":"string"},"instance":{"type":"string"},"code":{"type":"string","enum":["missing_parameter","invalid_parameter","unknown_platform","not_found","method_not_allowed","rate_limited","internal_error"],"description":"Stable machine-readable error code"},"error":{"type":"string","description":"Same as detail (kept for older clients)"},"docs":{"type":"string","format":"uri"},"parameter":{"type":"string","description":"The offending parameter, when there is one"},"platforms":{"type":"array","items":{"type":"string"},"description":"Valid platform keys (unknown_platform only)"},"endpoints":{"type":"array","items":{"type":"string"}},"retryAfter":{"type":"integer","description":"Seconds to wait (rate_limited only)"}}},"FeeLine":{"type":"object","required":["label","amount"],"properties":{"label":{"type":"string"},"amount":{"type":"number"}}},"Option":{"type":"object","required":["key","type","label"],"properties":{"key":{"type":"string"},"type":{"type":"string","enum":["select","checkbox","number"]},"label":{"type":"string"},"choices":{"type":"object","additionalProperties":{"type":"string"},"description":"Allowed values (select only): value -> label"},"help":{"type":"string"}}},"PlatformInfo":{"type":"object","required":["key","name","calculator","endpoint","lastChecked","options"],"properties":{"key":{"type":"string"},"name":{"type":"string"},"headline":{"type":"string"},"feeBase":{"type":"string"},"calculator":{"type":"string","format":"uri"},"endpoint":{"type":"string","format":"uri"},"officialSource":{"type":"string","format":"uri"},"lastChecked":{"type":"string","format":"date"},"defaultOptions":{"type":"object","additionalProperties":{"type":["string","number","boolean"]}},"options":{"type":"array","items":{"$ref":"#/components/schemas/Option"}},"note":{"type":"string"},"docs":{"type":"string","format":"uri"},"openapi":{"type":"string","format":"uri"},"llms":{"type":"string","format":"uri"}}},"PlatformList":{"type":"object","required":["name","version","platforms"],"properties":{"name":{"type":"string"},"version":{"type":"string"},"lastChecked":{"type":"string"},"note":{"type":"string"},"docs":{"type":"string","format":"uri"},"openapi":{"type":"string","format":"uri"},"llms":{"type":"string","format":"uri"},"usage":{"type":"object","properties":{"oneSale":{"type":"string","format":"uri"},"compare":{"type":"string","format":"uri"}}},"inputs":{"type":"object","additionalProperties":{"type":"string"}},"platforms":{"type":"array","items":{"$ref":"#/components/schemas/PlatformInfo"}}}},"FeeResult":{"type":"object","required":["platform","key","fees","totalFees","gross","payout","profit"],"properties":{"platform":{"type":"string"},"key":{"type":"string"},"inputs":{"type":"object","properties":{"price":{"type":"number"},"shipCharged":{"type":"number"},"taxRate":{"type":"number"},"itemCost":{"type":"number"},"shipCost":{"type":"number"},"otherCost":{"type":"number"}},"required":["price","shipCharged","taxRate","itemCost","shipCost","otherCost"]},"options":{"type":"object","additionalProperties":{"type":["string","number","boolean"]}},"fees":{"type":"array","items":{"$ref":"#/components/schemas/FeeLine"}},"totalFees":{"type":"number"},"gross":{"type":"number"},"payout":{"type":"number"},"profit":{"type":"number"},"margin":{"type":["number","null"],"description":"profit / gross, 0-1"},"roi":{"type":["number","null"],"description":"profit / costs, null when costs are 0"},"notes":{"type":"array","items":{"type":"string"}},"calculator":{"type":"string","format":"uri"},"officialSource":{"type":"string","format":"uri"},"lastChecked":{"type":"string","format":"date"},"note":{"type":"string"}}},"ComparisonRow":{"type":"object","required":["platform","key","totalFees","payout","profit"],"properties":{"platform":{"type":"string"},"key":{"type":"string"},"totalFees":{"type":"number"},"payout":{"type":"number"},"profit":{"type":"number"},"margin":{"type":["number","null"]},"calculator":{"type":"string","format":"uri"},"officialSource":{"type":"string","format":"uri"}}},"Comparison":{"type":"object","required":["inputs","ranked"],"properties":{"inputs":{"type":"object","properties":{"price":{"type":"number"},"shipCharged":{"type":"number"},"taxRate":{"type":"number"},"itemCost":{"type":"number"},"shipCost":{"type":"number"},"otherCost":{"type":"number"}},"required":["price","shipCharged","taxRate","itemCost","shipCost","otherCost"]},"note":{"type":"string"},"lastChecked":{"type":"string","format":"date"},"ranked":{"type":"array","items":{"$ref":"#/components/schemas/ComparisonRow"}},"compareTool":{"type":"string","format":"uri"}}},"FeeChange":{"type":"object","required":["id","platform","effective","kind","title","summary","source","verified","status"],"properties":{"id":{"type":"string"},"platform":{"type":"string","enum":["ebay","poshmark","mercari","whatnot","depop","etsy","facebook","amazon","grailed","reverb","tcgplayer","tiktok","vinted"]},"effective":{"type":"string","format":"date"},"kind":{"type":"string","examples":["rate_change","fee_cap","promotion","discount_ending"]},"title":{"type":"string"},"summary":{"type":"string"},"before":{"type":"string"},"after":{"type":"string"},"fliprofit":{"type":"string","description":"Whether the Fliprofit calculator models this change"},"limitedTime":{"type":"boolean"},"announced":{"type":"string","format":"date"},"announcement":{"type":["string","null"],"format":"uri","description":"Link to the platform announcement, if any."},"source":{"type":"object","required":["url"],"properties":{"title":{"type":"string"},"url":{"type":"string","format":"uri"}}},"verified":{"type":"string","format":"date"},"status":{"type":"string","enum":["upcoming","in_effect"]}}},"FeeChangeLog":{"type":"object","required":["schemaVersion","updated","count","changes"],"properties":{"schemaVersion":{"type":"integer"},"updated":{"type":"string","format":"date"},"count":{"type":"integer"},"changes":{"type":"array","items":{"$ref":"#/components/schemas/FeeChange"}},"note":{"type":"string"},"feeds":{"type":"object","properties":{"json":{"type":"string","format":"uri"},"atom":{"type":"string","format":"uri"}}}}}}}}