{ "openapi": "3.1.0", "info": { "title": "WISEPIM Open Data API", "version": "1.0.0", "summary": "Free GTIN/EAN validation, HS code lookup and European marketplace fee data.", "description": "A free, keyless reference API for product data: validate GTIN, EAN, UPC and ISBN barcodes and find the GS1 prefix origin, browse the EU Combined Nomenclature and US HTS customs tariffs, and read a sourced dataset of European marketplace seller fees (Amazon, eBay, bol, OTTO, Kaufland, Allegro and more).\n\n**Terms:** free for commercial and non-commercial use. Show a visible link with the text \"Data by WISEPIM\" wherever the data appears; every response carries the exact link in `attribution`. Limit: 120 requests a minute per IP; responses may be cached for an hour. Full terms: https://wisepim.com/developers/open-data#terms", "termsOfService": "https://wisepim.com/developers/open-data#terms", "contact": { "name": "WISEPIM", "url": "https://wisepim.com/developers/open-data", "email": "support@wisepim.com" }, "x-logo": { "url": "https://wisepim.com/wisepim-logo.png" } }, "externalDocs": { "description": "Documentation and examples", "url": "https://wisepim.com/developers/open-data" }, "servers": [ { "url": "https://wisepim.com/api/open/v1" } ], "tags": [ { "name": "GTIN", "description": "Barcode validation and GS1 prefix lookup." }, { "name": "HS codes", "description": "EU Combined Nomenclature and US HTS customs tariff codes." }, { "name": "Marketplace fees", "description": "Sourced seller fees of European marketplaces." } ], "paths": { "/gtin/{code}": { "get": { "tags": [ "GTIN" ], "operationId": "validateGtin", "summary": "Validate one GTIN, EAN, UPC or ISBN-13", "description": "Checks the length and GS1 check digit, detects the format and returns the GS1 prefix origin. An invalid code is still a 200 with `valid: false`.", "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 32 }, "example": "4006381333931" } ], "responses": { "200": { "description": "The validation result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GtinResult" } } } }, "400": { "description": "Code too long", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/gtin/check-digit/{digits}": { "get": { "tags": [ "GTIN" ], "operationId": "gtinCheckDigit", "summary": "Calculate the check digit and return the complete code", "parameters": [ { "name": "digits", "in": "path", "required": true, "description": "7, 11, 12 or 13 digits without the check digit.", "schema": { "type": "string" }, "example": "400638133393" } ], "responses": { "200": { "description": "The completed code, validated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GtinResult" } } } }, "400": { "description": "Wrong number of digits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/gtin": { "get": { "tags": [ "GTIN" ], "operationId": "validateGtinBatch", "summary": "Validate up to 100 codes", "parameters": [ { "name": "codes", "in": "query", "required": true, "description": "Comma-separated codes, at most 100.", "schema": { "type": "string" }, "example": "4006381333931,036000291452" } ], "responses": { "200": { "description": "One result per code, in order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GtinBatch" } } } }, "400": { "description": "Missing or too many codes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/hs-codes/search": { "get": { "tags": [ "HS codes" ], "operationId": "searchHsCodes", "summary": "Find HS chapters and headings by keyword", "description": "Keyword match over the official chapter and 4-digit heading texts, which the EU CN and US HTS share. Follow a result's `url` for its subheadings.", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 200 }, "example": "cotton t-shirt" }, { "name": "lang", "in": "query", "description": "Language of the descriptions. The US HTS is published in English only.", "schema": { "type": "string", "enum": [ "en", "nl", "de", "fr" ], "default": "en" } } ], "responses": { "200": { "description": "Up to 10 chapters and headings, best first", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HsSearch" } } } }, "400": { "description": "Missing keywords or bad lang", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/hs-codes": { "get": { "tags": [ "HS codes" ], "operationId": "listHsChapters", "summary": "List the chapters of a nomenclature", "parameters": [ { "name": "market", "in": "query", "description": "`eu`: EU Combined Nomenclature (8-digit CN codes). `us`: US Harmonized Tariff Schedule (10-digit).", "schema": { "type": "string", "enum": [ "eu", "us" ], "default": "eu" } }, { "name": "lang", "in": "query", "description": "Language of the descriptions. The US HTS is published in English only.", "schema": { "type": "string", "enum": [ "en", "nl", "de", "fr" ], "default": "en" } } ], "responses": { "200": { "description": "The chapters (node is null)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HsBrowse" } } } }, "400": { "description": "Bad market or lang", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Nomenclature unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/hs-codes/{code}": { "get": { "tags": [ "HS codes" ], "operationId": "getHsCode", "summary": "Look up an HS, CN or HTS code with its parents and children", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "2, 4, 6, 8 or 10 digits; dots and spaces are ignored.", "schema": { "type": "string" }, "example": "8471" }, { "name": "market", "in": "query", "description": "`eu`: EU Combined Nomenclature (8-digit CN codes). `us`: US Harmonized Tariff Schedule (10-digit).", "schema": { "type": "string", "enum": [ "eu", "us" ], "default": "eu" } }, { "name": "lang", "in": "query", "description": "Language of the descriptions. The US HTS is published in English only.", "schema": { "type": "string", "enum": [ "en", "nl", "de", "fr" ], "default": "en" } } ], "responses": { "200": { "description": "The code, its path and its direct children", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HsBrowse" } } } }, "400": { "description": "Malformed code, market or lang", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Code not in the nomenclature", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Nomenclature unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/marketplace-fees": { "get": { "tags": [ "Marketplace fees" ], "operationId": "listFeeMarketplaces", "summary": "Marketplaces, fee types and dataset metadata", "responses": { "200": { "description": "The dataset index", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeeIndex" } } } } } } }, "/marketplace-fees/calculate": { "get": { "tags": [ "Marketplace fees" ], "operationId": "calculateMarketplaceFees", "summary": "Fees, payout and margin for one sale at any price", "description": "Without `calculator`, lists the calculators with their parameters and categories. With it, runs the same cent-exact math as WISEPIM's eBay, Etsy, Amazon FBA and bol calculators. Other parameters depend on the calculator; see the listing.", "parameters": [ { "name": "calculator", "in": "query", "schema": { "type": "string", "enum": [ "ebay-us", "ebay-de", "ebay-fr", "etsy", "amazon-us", "amazon-de", "bol" ] } }, { "name": "price", "in": "query", "description": "Item price in the marketplace currency.", "schema": { "type": "number", "minimum": 0 }, "example": 50 }, { "name": "category", "in": "query", "description": "Category key from the listing.", "schema": { "type": "string" } }, { "name": "shipping", "in": "query", "schema": { "type": "number", "minimum": 0, "default": 0 } }, { "name": "cost", "in": "query", "description": "Your product cost, for profit and margin.", "schema": { "type": "number", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "The fee breakdown, or the calculator listing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeeCalculation" } } } }, "400": { "description": "Unknown calculator, category or a bad number", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/marketplace-fees/compare": { "get": { "tags": [ "Marketplace fees" ], "operationId": "compareMarketplaceFees", "summary": "Fee on a 50 EUR sale by category across marketplaces", "parameters": [ { "name": "category", "in": "query", "required": false, "description": "A category id, e.g. consumer_electronics.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The comparison table", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeeComparison" } } } }, "400": { "description": "Unknown category", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/marketplace-fees/{marketplace}": { "get": { "tags": [ "Marketplace fees" ], "operationId": "getMarketplaceFees", "summary": "Every sourced fee row of one marketplace", "parameters": [ { "name": "marketplace", "in": "path", "required": true, "schema": { "type": "string" }, "example": "amazon" }, { "name": "market", "in": "query", "description": "ISO 3166-1 alpha-2 country, e.g. DE.", "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" } }, { "name": "feeType", "in": "query", "schema": { "type": "string", "enum": [ "advertising", "commission", "cross_border_fx", "fixed_fee", "logistics", "payment", "subscription", "tax_or_regulatory", "terms_and_context", "vat" ] } }, { "name": "format", "in": "query", "description": "`csv` returns the rows as CSV for spreadsheets (`=IMPORTDATA(url)`), with the attribution in the last column.", "schema": { "type": "string", "enum": [ "json", "csv" ], "default": "json" } } ], "responses": { "200": { "description": "The matching rows", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeeRows" } }, "text/csv": { "schema": { "type": "string" } } } }, "400": { "description": "Bad filter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown marketplace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "schemas": { "Attribution": { "type": "object", "description": "Credit to show wherever the data appears: a visible link with the text \"Data by WISEPIM\" to `url`.", "required": [ "required", "text", "url", "html", "markdown", "terms" ], "properties": { "required": { "type": "boolean", "const": true }, "text": { "type": "string", "example": "Data by WISEPIM" }, "url": { "type": "string", "format": "uri", "example": "https://wisepim.com/hs-codes/8471" }, "html": { "type": "string", "example": "Data by WISEPIM" }, "markdown": { "type": "string", "example": "[Data by WISEPIM](https://wisepim.com/hs-codes/8471)" }, "terms": { "type": "string", "format": "uri" } } }, "Error": { "type": "object", "required": [ "error", "docs" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_request", "not_found", "method_not_allowed", "rate_limited", "unavailable" ] }, "message": { "type": "string" } } }, "docs": { "type": "string", "format": "uri" } } }, "GtinResult": { "type": "object", "required": [ "input", "valid", "format", "checkDigit", "expectedCheckDigit", "gtin14", "gs1Prefix", "error" ], "properties": { "input": { "type": "string" }, "valid": { "type": "boolean" }, "format": { "type": [ "string", "null" ], "enum": [ "EAN-13", "EAN-8", "UPC-A", "ISBN-13", "GTIN-14", null ] }, "checkDigit": { "type": [ "integer", "null" ] }, "expectedCheckDigit": { "type": [ "integer", "null" ] }, "gtin14": { "type": [ "string", "null" ], "description": "The code zero-padded to 14 digits, when valid." }, "gs1Prefix": { "type": [ "object", "null" ], "properties": { "prefix": { "type": "string", "example": "400" }, "name": { "type": "string", "example": "Germany" }, "kind": { "type": "string", "enum": [ "country", "organization", "unassigned" ] }, "regions": { "type": "array", "items": { "type": "string" }, "description": "ISO 3166-1 alpha-2 codes." } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string", "enum": [ "empty", "nonDigit", "length", "checkDigit" ] }, "message": { "type": "string" } } }, "attribution": { "$ref": "#/components/schemas/Attribution" } } }, "GtinBatch": { "type": "object", "properties": { "count": { "type": "integer" }, "valid": { "type": "integer" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/GtinResult" } }, "attribution": { "$ref": "#/components/schemas/Attribution" } } }, "HsCode": { "type": "object", "required": [ "code", "formatted", "level", "description" ], "properties": { "code": { "type": "string", "example": "847130" }, "formatted": { "type": "string", "example": "8471 30" }, "level": { "type": "integer", "minimum": 2, "maximum": 10 }, "description": { "type": "string" } } }, "HsBrowse": { "type": "object", "properties": { "market": { "type": "string", "enum": [ "eu", "us" ] }, "language": { "type": "string" }, "nomenclature": { "type": "object", "properties": { "source": { "type": "string" }, "version": { "type": "string" }, "attribution": { "type": "string", "description": "Credit for the official source; show it with the data." } } }, "node": { "oneOf": [ { "type": "null" }, { "allOf": [ { "$ref": "#/components/schemas/HsCode" }, { "type": "object", "properties": { "note": { "type": "string" }, "path": { "type": "array", "items": { "$ref": "#/components/schemas/HsCode" } } } } ] } ] }, "children": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/HsCode" }, { "type": "object", "properties": { "hasChildren": { "type": "boolean" }, "url": { "type": [ "string", "null" ], "format": "uri" } } } ] } }, "attribution": { "$ref": "#/components/schemas/Attribution" } } }, "FeeSource": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "title": { "type": "string" } } }, "FeeMarketplace": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "markets": { "type": "array", "items": { "type": "string" } }, "feeCurrency": { "type": "string" } } }, "FeeIndex": { "type": "object", "properties": { "verifiedOn": { "type": "string", "format": "date" }, "refreshCadence": { "type": "string" }, "rowCount": { "type": "integer" }, "feeTypes": { "type": "array", "items": { "type": "string" } }, "marketplaces": { "type": "array", "items": { "$ref": "#/components/schemas/FeeMarketplace" } }, "attribution": { "$ref": "#/components/schemas/Attribution" } } }, "FeeRow": { "type": "object", "properties": { "id": { "type": "string" }, "marketplace": { "type": "string" }, "entity": { "type": "string" }, "markets": { "type": "array", "items": { "type": "string" } }, "feeType": { "type": "string" }, "obligation": { "type": "string" }, "field": { "type": "string" }, "value": { "type": "string", "description": "The fee as published, e.g. \"EUR 39 per month, excl. VAT\"." }, "scope": { "type": "string" }, "effectiveDate": { "type": [ "string", "null" ], "format": "date" }, "notes": { "type": [ "string", "null" ] }, "confidence": { "type": "string" }, "verification": { "type": "string" }, "verifiedOn": { "type": "string", "format": "date" }, "source": { "$ref": "#/components/schemas/FeeSource" } } }, "FeeRows": { "type": "object", "properties": { "marketplace": { "$ref": "#/components/schemas/FeeMarketplace" }, "count": { "type": "integer" }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/FeeRow" } }, "attribution": { "$ref": "#/components/schemas/Attribution" } } }, "HsSearch": { "type": "object", "properties": { "query": { "type": "string" }, "language": { "type": "string" }, "nomenclatureVersion": { "type": "string" }, "count": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "level": { "type": "integer" }, "kind": { "type": "string", "enum": [ "chapter", "heading" ] }, "description": { "type": "string" }, "matchedTerms": { "type": "integer" }, "allTermsMatched": { "type": "boolean" }, "url": { "type": "string", "format": "uri" }, "page": { "type": "string", "format": "uri" } } } }, "attribution": { "$ref": "#/components/schemas/Attribution" } } }, "FeeCalculation": { "type": "object", "properties": { "calculator": { "type": "string" }, "currency": { "type": "string" }, "verifiedOn": { "type": "string", "format": "date" }, "fees": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "amount": { "type": "number" }, "pct": { "type": "number" } } } }, "totalFees": { "type": "number" }, "vatOnFees": { "type": "number" }, "payout": { "type": "number" }, "netRevenue": { "type": "number" }, "profit": { "type": "number" }, "marginPct": { "type": [ "number", "null" ] }, "notes": { "type": "array", "items": { "type": "string" } }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/FeeSource" } }, "calculators": { "type": "array", "items": { "type": "object" }, "description": "Only in the listing (no calculator)." }, "attribution": { "$ref": "#/components/schemas/Attribution" } } }, "FeeComparison": { "type": "object", "properties": { "verifiedOn": { "type": "string", "format": "date" }, "referencePriceEur": { "type": "number" }, "description": { "type": "string" }, "assumptions": { "type": "array", "items": { "type": "string" } }, "columns": { "type": "array", "items": { "type": "object" } }, "categories": { "type": "array", "items": { "type": "object" } }, "attribution": { "$ref": "#/components/schemas/Attribution" } } } } } }