{"openapi":"3.1.0","info":{"title":"eBay UK Buyer Protection Fee API","description":"Authoritative, maintained calculator for eBay UK's Buyer Protection Fee (BPF). Given a price, itemise what the buyer pays (the BPF + displayed total) and what the seller receives. Canonical published model, self-verified against eBay's own worked examples and watched by a drift canary.\n\nSources: [buyer](https://www.ebay.co.uk/help/buying/paying-items/buyer-protection-fee?id=5594) · [seller](https://www.ebay.co.uk/help/selling/selling/pricing-items/buyer-protection-information-sellers?id=5595).","contact":{"name":"ScalePass","url":"https://scalepass.io/"},"version":"2026-uk-v1"},"servers":[{"url":"https://api.hunta.io","description":"Public base URL"}],"paths":{"/v1/fee":{"get":{"tags":["fee"],"summary":"Itemise BPF for a price","description":"Given a price, itemise the Buyer Protection Fee for both sides of the trade.","operationId":"get_fee_v1_fee_get","parameters":[{"name":"item_price","in":"query","required":true,"schema":{"type":"number","minimum":0,"description":"Per-unit item price, delivery excluded (GBP)","title":"Item Price"},"description":"Per-unit item price, delivery excluded (GBP)"},{"name":"postage","in":"query","required":false,"schema":{"type":"number","minimum":0,"default":0,"title":"Postage"}},{"name":"quantity","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1,"title":"Quantity"}},{"name":"seller_type","in":"query","required":false,"schema":{"type":"string","default":"private","title":"Seller Type"}},{"name":"category","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ItemiseResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/inverse":{"post":{"tags":["fee"],"summary":"Recover item price from displayed price","description":"Given the buyer-displayed item price, recover the item price + embedded BPF.","operationId":"post_inverse_v1_inverse_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InverseRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InverseResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/batch":{"post":{"tags":["fee"],"summary":"Itemise many prices at once","description":"Itemise up to 1000 prices in one call (billed per item).","operationId":"post_batch_v1_batch_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/meta":{"get":{"tags":["meta"],"summary":"Current fee model + version","description":"The fee model in force: version, tiers, exclusions, sources, worked examples. Public (no key).","operationId":"get_meta_v1_meta_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetaResponse"}}}}}}},"/healthz":{"get":{"tags":["meta"],"summary":"Liveness","operationId":"healthz_healthz_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}}},"components":{"schemas":{"BatchItem":{"properties":{"item_price":{"type":"number","title":"Item Price"},"postage":{"type":"number","title":"Postage","default":0},"quantity":{"type":"integer","title":"Quantity","default":1},"seller_type":{"type":"string","title":"Seller Type","default":"private"},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category"}},"type":"object","required":["item_price"],"title":"BatchItem"},"BatchRequest":{"properties":{"items":{"items":{"$ref":"#/components/schemas/BatchItem"},"type":"array","maxItems":1000,"minItems":1,"title":"Items"}},"type":"object","required":["items"],"title":"BatchRequest"},"BatchResponse":{"properties":{"count":{"type":"integer","title":"Count"},"results":{"items":{"$ref":"#/components/schemas/ItemiseResponse"},"type":"array","title":"Results"}},"type":"object","required":["count","results"],"title":"BatchResponse"},"BuyerBlock":{"properties":{"item_price":{"type":"number","title":"Item Price","description":"Per-unit item price (delivery excluded)"},"quantity":{"type":"integer","title":"Quantity"},"item_total":{"type":"number","title":"Item Total","description":"item_price × quantity"},"buyer_protection_fee":{"type":"number","title":"Buyer Protection Fee","description":"Total BPF for the order line"},"postage":{"type":"number","title":"Postage"},"displayed_item_total":{"type":"number","title":"Displayed Item Total","description":"What the buyer sees for the item(s): item_total + BPF"},"displayed_total":{"type":"number","title":"Displayed Total","description":"displayed_item_total + postage"}},"type":"object","required":["item_price","quantity","item_total","buyer_protection_fee","postage","displayed_item_total","displayed_total"],"title":"BuyerBlock"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"Inputs":{"properties":{"item_price":{"type":"number","title":"Item Price"},"postage":{"type":"number","title":"Postage"},"quantity":{"type":"integer","title":"Quantity"},"seller_type":{"type":"string","title":"Seller Type"},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category"}},"type":"object","required":["item_price","postage","quantity","seller_type"],"title":"Inputs"},"InverseRequest":{"properties":{"displayed_item_price":{"type":"number","exclusiveMinimum":0.0,"title":"Displayed Item Price","description":"BPF-inclusive item price as shown to the buyer (delivery excluded)"},"seller_type":{"type":"string","title":"Seller Type","default":"private"},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category"}},"type":"object","required":["displayed_item_price"],"title":"InverseRequest"},"InverseResponse":{"properties":{"item_price":{"type":"number","title":"Item Price"},"embedded_bpf":{"type":"number","title":"Embedded Bpf"},"bpf_version":{"type":"string","title":"Bpf Version"}},"type":"object","required":["item_price","embedded_bpf","bpf_version"],"title":"InverseResponse"},"ItemiseResponse":{"properties":{"currency":{"type":"string","title":"Currency"},"bpf_version":{"type":"string","title":"Bpf Version"},"inputs":{"$ref":"#/components/schemas/Inputs"},"buyer":{"$ref":"#/components/schemas/BuyerBlock"},"seller":{"$ref":"#/components/schemas/SellerBlock"},"fee_breakdown":{"additionalProperties":{"type":"number"},"type":"object","title":"Fee Breakdown"},"flags":{"items":{"type":"string"},"type":"array","title":"Flags"}},"type":"object","required":["currency","bpf_version","inputs","buyer","seller","fee_breakdown","flags"],"title":"ItemiseResponse"},"MetaResponse":{"properties":{"bpf_version":{"type":"string","title":"Bpf Version"},"currency":{"type":"string","title":"Currency"},"marketplace":{"type":"string","title":"Marketplace"},"flat_fee":{"type":"number","title":"Flat Fee"},"tiers":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Tiers"},"excluded_categories":{"items":{"type":"string"},"type":"array","title":"Excluded Categories"},"worked_examples":{"additionalProperties":{"type":"string"},"type":"object","title":"Worked Examples"},"sources":{"additionalProperties":{"type":"string"},"type":"object","title":"Sources"},"canary":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Canary"}},"type":"object","required":["bpf_version","currency","marketplace","flat_fee","tiers","excluded_categories","worked_examples","sources"],"title":"MetaResponse"},"SellerBlock":{"properties":{"receives_item":{"type":"number","title":"Receives Item"},"receives_postage":{"type":"number","title":"Receives Postage"},"bpf_passed_to_ebay":{"type":"number","title":"Bpf Passed To Ebay"},"note":{"type":"string","title":"Note"}},"type":"object","required":["receives_item","receives_postage","bpf_passed_to_ebay","note"],"title":"SellerBlock"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}