{ "openapi": "3.1.0", "info": { "title": "Barcodes.GG API", "description": "Barcodes.GG is a sneaker and streetwear barcode API that resolves UPC and EAN barcodes to products and sizes, and style codes to products and barcodes. Requests are authenticated with a bearer token created in the dashboard and are counted against the monthly allowance of the plan.", "version": "2.0.0", "termsOfService": "https://barcodes.gg/legal/terms", "contact": { "name": "Barcodes.GG", "email": "mail@barcodes.gg", "url": "https://barcodes.gg" } }, "externalDocs": { "description": "Barcodes.GG API documentation", "url": "https://barcodes.gg/guide/docs/introduction" }, "servers": [ { "url": "https://barcodes.gg/api", "description": "Production" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Barcodes", "description": "Barcode to product, and style code to barcodes (v2)." }, { "name": "Products", "description": "Product search, lookup, details and release lists (v2)." }, { "name": "Account", "description": "Usage of the calling token." }, { "name": "Images", "description": "Product images. No token needed." }, { "name": "Legacy v1", "description": "Unversioned v1 endpoints that remain available. They do not add the v2 response metadata to error responses." } ], "paths": { "/v2/barcode/lookup/{barcode}": { "get": { "tags": [ "Barcodes" ], "operationId": "lookupBarcode", "summary": "Look up a product by barcode", "description": "Resolves a UPC or EAN to the product it belongs to and the size that barcode identifies. A successful call debits one request from the plan allowance; a call that finds nothing is not debited. A barcode in an invalid format returns 400 with the message `Please enter a valid barcode.`\n\nRequired token ability: `lookup-barcode`. Plans whose tokens can carry it: Free Trial, Basic, Basic Plus, Standard, Standard Plus, Pro, Pro Plus and Enterprise. A token without the ability gets a 403.", "parameters": [ { "name": "barcode", "in": "path", "required": true, "description": "UPC or EAN digits, 8 to 15 characters, no letters. One leading zero is dropped before matching, and all GTIN zero-paddings of the number are tried.", "schema": { "type": "string", "minLength": 8, "maxLength": 15, "pattern": "^[0-9]{8,15}$" }, "example": "195245980597" }, { "name": "fields", "in": "query", "required": true, "description": "Either `*` for everything, or up to four comma-separated field names. `product` and `barcode` return the whole object. Dotted names return one value as a top-level key named after the part behind the dot: `product.product_name`, `product.product_brand`, `product.product_category`, `product.product_description`, `product.product_unique_id` (v2 only), `product.product_style_code`, `product.product_colorway`, `product.product_release_date`, `product.product_retail_price`, `product.product_image`, `product.product_sizes`, `product.product_added`, `product.product_updated`, `barcode.barcode_type`, `barcode.barcode_value`, `barcode.barcode_added`, `barcode.product_size`. Unknown names are ignored.", "schema": { "type": "string", "pattern": "^[a-zA-Z*._]+(,[a-zA-Z._]+){0,3}$", "example": "*" } }, { "name": "show_data", "in": "query", "required": false, "description": "Send 1 to add `product_data` (raw source payload) and `us_sizes` to the product object.", "schema": { "type": "integer", "enum": [ 0, 1 ], "default": 0 } } ], "responses": { "200": { "description": "Lookup result. A barcode that is unknown, or known without product data, returns HTTP 200 with `error: true`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "error" ], "description": "With `fields=*` the body holds `product` and `barcode`. With named fields it holds only what was requested, flattened to top-level keys.", "properties": { "error": { "type": "boolean", "const": false }, "product": { "$ref": "#/components/schemas/Product" }, "barcode": { "$ref": "#/components/schemas/Barcode" }, "response_time": { "type": "string", "description": "Server runtime of the request, for example `41ms`." }, "request_fulfilled": { "type": "boolean", "description": "True when the HTTP status is below 400." }, "request_debited": { "type": "boolean", "description": "True only when the call was debited from the plan allowance." } }, "additionalProperties": true }, { "$ref": "#/components/schemas/Error" } ] }, "examples": { "success": { "summary": "Success", "value": { "error": false, "product": { "product_name": "Nike Dunk Low Retro White Black Panda", "product_brand": "Nike", "product_category": "sneakers", "product_unique_id": "DD1391-100_WHITE-BLACK", "product_style_code": "DD1391-100", "product_release_date": "2021-03-10", "product_description": "The Nike Dunk Low Retro White Black pairs a white leather base with black overlays and a black Swoosh.", "product_colorway": "White/Black", "product_retail_price": "100", "product_image": "https://barcodes.gg/api/image/uid/DD1391-100_WHITE-BLACK", "product_sizes": [ 6, 6.5, 7, 7.5, 8, 8.5, 9, 9.5, 10, 10.5, 11, 12, 13 ], "product_added": "2023-06-14T09:21:07.000000Z", "product_updated": "2026-08-30T02:11:45.000000Z" }, "barcode": { "barcode_type": "GTIN12", "barcode_value": "195245980597", "barcode_added": null, "product_size": { "us": "9", "uk": "8", "eu": "42.5" } }, "response_time": "41ms", "request_fulfilled": true, "request_debited": true } }, "notFound": { "summary": "Nothing found (still HTTP 200)", "value": { "error": true, "message": "Barcode could not be found.", "response_time": "23ms", "request_fulfilled": true, "request_debited": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v2/barcode/lookup/sku/{style_code}": { "get": { "tags": [ "Barcodes" ], "operationId": "lookupBarcodesBySku", "summary": "List barcodes for a style code", "description": "Reverse lookup: returns the barcodes held for a style code with the size each one identifies, 20 per page. With `sizerun` the response is one barcode per size for the whole size run, sorted by EU size, in a single page. A successful call debits one request from the plan allowance; a call that finds nothing is not debited.\n\nRequired token ability: `lookup-barcode-sku`. Plans whose tokens can carry it: Free Trial, Basic Plus, Standard Plus, Pro Plus and Enterprise. A token without the ability gets a 403.", "parameters": [ { "name": "style_code", "in": "path", "required": true, "description": "Manufacturer style code (SKU), for example DD1391-100. The value may contain slashes.", "schema": { "type": "string" }, "example": "DD1391-100" }, { "name": "sizerun", "in": "query", "required": false, "description": "Return one barcode per size, preferring verified barcodes, without pagination.", "schema": { "type": "boolean", "default": false } }, { "name": "is_verified", "in": "query", "required": false, "description": "Leave out barcodes derived by the size-run algorithm. Ignored when `sizerun` is true.", "schema": { "type": "boolean", "default": false } }, { "name": "page", "in": "query", "required": false, "description": "Page number.", "schema": { "type": "integer", "minimum": 1, "default": 1 } } ], "responses": { "200": { "description": "Barcodes for the style code. No match returns HTTP 200 with `error: true`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "error", "barcodes", "pagination" ], "properties": { "error": { "type": "boolean", "const": false }, "barcodes": { "type": "array", "items": { "$ref": "#/components/schemas/SkuBarcode" } }, "pagination": { "$ref": "#/components/schemas/NextPagePagination" }, "response_time": { "type": "string", "description": "Server runtime of the request, for example `41ms`." }, "request_fulfilled": { "type": "boolean", "description": "True when the HTTP status is below 400." }, "request_debited": { "type": "boolean", "description": "True only when the call was debited from the plan allowance." } } }, { "$ref": "#/components/schemas/Error" } ] }, "examples": { "success": { "summary": "Success", "value": { "error": false, "barcodes": [ { "product_barcode_type": "GTIN12", "product_barcode_value": "195245980597", "product_size": { "us": "9", "uk": "8", "eu": "42.5" }, "isVerified": true } ], "pagination": { "current_page": "1", "next_page": null, "has_next_page": false }, "response_time": "41ms", "request_fulfilled": true, "request_debited": true } }, "notFound": { "summary": "Nothing found (still HTTP 200)", "value": { "error": true, "message": "No barcodes could not be found for this style code.", "response_time": "23ms", "request_fulfilled": true, "request_debited": false } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v2/product/search": { "get": { "tags": [ "Products" ], "operationId": "searchProducts", "summary": "Search products", "description": "Searches products by name keywords or by style code. A query shaped like a style code is matched exactly first; otherwise products matching all keywords are returned, falling back to products matching any keyword. Results are ordered by number of matched keywords, then by release date, newest first. A successful call debits one request from the plan allowance; a call that finds nothing is not debited.\n\nRequired token ability: `search-product`. Plans whose tokens can carry it: Free Trial, Basic, Basic Plus, Standard, Standard Plus, Pro, Pro Plus and Enterprise. A token without the ability gets a 403.", "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Keywords or a style code.", "schema": { "type": "string", "minLength": 3, "example": "DD1391-100" } }, { "name": "results", "in": "query", "required": false, "description": "Results per page.", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }, { "name": "page", "in": "query", "required": false, "description": "Page number.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "show_data", "in": "query", "required": false, "description": "Send 1 to add `_id` and `product_data` (raw source payload) to each result.", "schema": { "type": "integer", "enum": [ 0, 1 ], "default": 0 } } ], "responses": { "200": { "description": "Search results. No match returns HTTP 200 with `error: true`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "error", "results", "pagination" ], "properties": { "error": { "type": "boolean", "const": false }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "response_time": { "type": "string", "description": "Server runtime of the request, for example `41ms`." }, "request_fulfilled": { "type": "boolean", "description": "True when the HTTP status is below 400." }, "request_debited": { "type": "boolean", "description": "True only when the call was debited from the plan allowance." } } }, { "$ref": "#/components/schemas/Error" } ] }, "examples": { "success": { "summary": "Success", "value": { "error": false, "results": [ { "product_name": "Nike Dunk Low Retro White Black Panda", "product_brand": "Nike", "product_category": "sneakers", "product_unique_id": "DD1391-100_WHITE-BLACK", "product_style_code": "DD1391-100", "product_release_date": "2021-03-10", "product_description": "The Nike Dunk Low Retro White Black pairs a white leather base with black overlays and a black Swoosh.", "product_colorway": "White/Black", "product_retail_price": "100", "product_image": "https://barcodes.gg/api/image/uid/DD1391-100_WHITE-BLACK", "match_count": 999 } ], "pagination": { "total": 1, "per_page": 20, "current_page": 1, "last_page": 1 }, "response_time": "41ms", "request_fulfilled": true, "request_debited": true } }, "notFound": { "summary": "Nothing found (still HTTP 200)", "value": { "error": true, "message": "No products could be found for this search query.", "response_time": "23ms", "request_fulfilled": true, "request_debited": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v2/product/search/bulk": { "post": { "tags": [ "Products" ], "operationId": "searchProductsBulk", "summary": "Look up many style codes at once", "description": "Returns the products for a list of style codes in one call, in the order the codes were sent. Matching is exact and case-sensitive. The whole call debits one request. A body without a non-empty `styleCodes` array returns HTTP 200 with `error: true` and the message `Invalid JSON Data.`\n\nRequired token ability: `search-product-bulk`. Plans whose tokens can carry it: Enterprise only. A token without the ability gets a 403.", "parameters": [ { "name": "show_data", "in": "query", "required": false, "description": "Send 1 to add the raw source payload (`product_data`) to each product.", "schema": { "type": "integer", "enum": [ 0, 1 ], "default": 0 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "styleCodes" ], "properties": { "styleCodes": { "type": "array", "minItems": 1, "items": { "type": "string" } } } }, "example": { "styleCodes": [ "DD1391-100", "DD1503-100" ] } } } }, "responses": { "200": { "description": "Products found. No match returns HTTP 200 with `error: true`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "error", "results" ], "properties": { "error": { "type": "boolean", "const": false }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "response_time": { "type": "string", "description": "Server runtime of the request, for example `41ms`." }, "request_fulfilled": { "type": "boolean", "description": "True when the HTTP status is below 400." }, "request_debited": { "type": "boolean", "description": "True only when the call was debited from the plan allowance." } } }, { "$ref": "#/components/schemas/Error" } ] }, "examples": { "success": { "summary": "Success", "value": { "error": false, "results": [ { "product_name": "Nike Dunk Low Retro White Black Panda", "product_brand": "Nike", "product_category": "sneakers", "product_unique_id": "DD1391-100_WHITE-BLACK", "product_style_code": "DD1391-100", "product_release_date": "2021-03-10", "product_description": "The Nike Dunk Low Retro White Black pairs a white leather base with black overlays and a black Swoosh.", "product_colorway": "White/Black", "product_retail_price": "100", "product_image": "https://barcodes.gg/api/image/uid/DD1391-100_WHITE-BLACK", "match_count": 1 } ], "response_time": "41ms", "request_fulfilled": true, "request_debited": true } }, "notFound": { "summary": "Nothing found (still HTTP 200)", "value": { "error": true, "message": "No products could be found for this search query.", "response_time": "23ms", "request_fulfilled": true, "request_debited": false } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v2/product/lookup/sku/{style_code}": { "get": { "tags": [ "Products" ], "operationId": "lookupProductBySku", "summary": "Get products by style code", "description": "Returns every variant stored under a style code. Several products can share one style code; use the `product_unique_id` of a result to address one of them. A successful call debits one request from the plan allowance; a call that finds nothing is not debited.\n\nRequired token ability: `lookup-product`. Plans whose tokens can carry it: Free Trial, Basic, Basic Plus, Standard, Standard Plus, Pro, Pro Plus and Enterprise. A token without the ability gets a 403.", "parameters": [ { "name": "style_code", "in": "path", "required": true, "description": "Manufacturer style code (SKU), for example DD1391-100. This route does not accept slashes in the value.", "schema": { "type": "string" }, "example": "DD1391-100" }, { "name": "show_data", "in": "query", "required": false, "description": "Send 1 to add the raw source payload (`product_data`) to each product.", "schema": { "type": "integer", "enum": [ 0, 1 ], "default": 0 } } ], "responses": { "200": { "description": "Matching variants. No match returns HTTP 200 with `error: true`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "error", "results" ], "properties": { "error": { "type": "boolean", "const": false }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "response_time": { "type": "string", "description": "Server runtime of the request, for example `41ms`." }, "request_fulfilled": { "type": "boolean", "description": "True when the HTTP status is below 400." }, "request_debited": { "type": "boolean", "description": "True only when the call was debited from the plan allowance." } } }, { "$ref": "#/components/schemas/Error" } ] }, "examples": { "success": { "summary": "Success", "value": { "error": false, "results": [ { "product_last_checked": "2026-09-30T18:42:10.000000Z", "product_name": "Nike Dunk Low Retro White Black Panda", "product_brand": "Nike", "product_category": "sneakers", "product_unique_id": "DD1391-100_WHITE-BLACK", "product_style_code": "DD1391-100", "product_release_date": "2021-03-10", "product_description": "The Nike Dunk Low Retro White Black pairs a white leather base with black overlays and a black Swoosh.", "product_colorway": "White/Black", "product_retail_price": "100", "product_image": "https://barcodes.gg/api/image/uid/DD1391-100_WHITE-BLACK" } ], "response_time": "41ms", "request_fulfilled": true, "request_debited": true } }, "notFound": { "summary": "Nothing found (still HTTP 200)", "value": { "error": true, "message": "No product could be found for this search query.", "response_time": "23ms", "request_fulfilled": true, "request_debited": false } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v2/product/lookup/uid/{product_unique_id}": { "get": { "tags": [ "Products" ], "operationId": "lookupProductByUid", "summary": "Get a product by unique ID", "description": "Returns exactly one product variant. `results` is an array with a single item. A successful call debits one request from the plan allowance; a call that finds nothing is not debited.\n\nRequired token ability: `lookup-product`. Plans whose tokens can carry it: Free Trial, Basic, Basic Plus, Standard, Standard Plus, Pro, Pro Plus and Enterprise. A token without the ability gets a 403.", "parameters": [ { "name": "product_unique_id", "in": "path", "required": true, "description": "Unique ID of one product variant, as returned in `product_unique_id`. The value may contain slashes.", "schema": { "type": "string" }, "example": "DD1391-100_WHITE-BLACK" }, { "name": "show_data", "in": "query", "required": false, "description": "Send 1 to add the raw source payload (`product_data`) to each product.", "schema": { "type": "integer", "enum": [ 0, 1 ], "default": 0 } } ], "responses": { "200": { "description": "The product. No match returns HTTP 200 with `error: true`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "error", "results" ], "properties": { "error": { "type": "boolean", "const": false }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "response_time": { "type": "string", "description": "Server runtime of the request, for example `41ms`." }, "request_fulfilled": { "type": "boolean", "description": "True when the HTTP status is below 400." }, "request_debited": { "type": "boolean", "description": "True only when the call was debited from the plan allowance." } } }, { "$ref": "#/components/schemas/Error" } ] }, "examples": { "success": { "summary": "Success", "value": { "error": false, "results": [ { "product_last_checked": "2026-09-30T18:42:10.000000Z", "product_name": "Nike Dunk Low Retro White Black Panda", "product_brand": "Nike", "product_category": "sneakers", "product_unique_id": "DD1391-100_WHITE-BLACK", "product_style_code": "DD1391-100", "product_release_date": "2021-03-10", "product_description": "The Nike Dunk Low Retro White Black pairs a white leather base with black overlays and a black Swoosh.", "product_colorway": "White/Black", "product_retail_price": "100", "product_image": "https://barcodes.gg/api/image/uid/DD1391-100_WHITE-BLACK" } ], "response_time": "41ms", "request_fulfilled": true, "request_debited": true } }, "notFound": { "summary": "Nothing found (still HTTP 200)", "value": { "error": true, "message": "No product could be found for this search query.", "response_time": "23ms", "request_fulfilled": true, "request_debited": false } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v2/product/details/{style_code}": { "get": { "tags": [ "Products" ], "operationId": "getProductDetails", "summary": "Get product details with the size run", "description": "Returns a merged product record and the full size run, with the EAN and UPC held for each size. The style code is matched in upper case. With `is_slug` the path value is a marketplace slug instead. A successful call debits one request from the plan allowance; a call that finds nothing is not debited. An `is_slug` request with a `slug_store` other than `alias` or `stockx` returns 400.\n\nRequired token ability: `product-details`. Plans whose tokens can carry it: Free Trial, Pro, Pro Plus and Enterprise. A token without the ability gets a 403.", "parameters": [ { "name": "style_code", "in": "path", "required": true, "description": "Manufacturer style code (SKU), for example DD1391-100. The value may contain slashes. A marketplace slug when `is_slug` is true.", "schema": { "type": "string" }, "example": "DD1391-100" }, { "name": "is_slug", "in": "query", "required": false, "description": "Treat the path value as a marketplace slug.", "schema": { "type": "boolean", "default": false } }, { "name": "slug_store", "in": "query", "required": false, "description": "Marketplace the slug belongs to. Required when `is_slug` is true.", "schema": { "type": "string", "enum": [ "alias", "stockx" ] } }, { "name": "show_images", "in": "query", "required": false, "description": "Send 1 to add `goat_image`, `stockx_image` and `product_images`.", "schema": { "type": "integer", "enum": [ 0, 1 ], "default": 0 } } ], "responses": { "200": { "description": "Product details. No match returns HTTP 200 with `error: true`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "error", "product" ], "properties": { "error": { "type": "boolean", "const": false }, "product": { "$ref": "#/components/schemas/ProductDetails" }, "response_time": { "type": "string", "description": "Server runtime of the request, for example `41ms`." }, "request_fulfilled": { "type": "boolean", "description": "True when the HTTP status is below 400." }, "request_debited": { "type": "boolean", "description": "True only when the call was debited from the plan allowance." } } }, { "$ref": "#/components/schemas/Error" } ] }, "examples": { "success": { "summary": "Success", "value": { "error": false, "product": { "sku": "DD1391-100", "type": "Sneakers", "colourway": "White/Black", "category": "sneakers", "title": "Nike Dunk Low Retro White Black Panda", "brand": "Nike", "nickname": "Panda", "designer": "Peter Moore", "main_color": "White", "model": "Nike Dunk Low", "product_unique_id": "DD1391-100_WHITE-BLACK", "gender": "men", "upper_material": "Leather", "release_date": "2021-03-10", "release_date_formatted": "10/03/2021", "retail_price": 10000, "retail_price_gbp": 9000, "retail_price_usd": "100", "description": "The Nike Dunk Low Retro White Black pairs a white leather base with black overlays and a black Swoosh.", "stockx_total_sold": "", "image": "https://barcodes.gg/api/image/uid/DD1391-100_WHITE-BLACK", "sizes": [ { "eu": "42", "uk": "7.5", "us": "8.5", "ean": "", "upc": "" }, { "eu": "42.5", "uk": "8", "us": "9", "ean": "", "upc": "195245980597" } ], "variants": 2, "variant_format": "UK", "size_run": "7.5 - 8", "internal_category": "Sneakers", "search_sku": "DD1391-100" }, "response_time": "41ms", "request_fulfilled": true, "request_debited": true } }, "notFound": { "summary": "Nothing found (still HTTP 200)", "value": { "error": true, "message": "No product could be found for this style code.", "response_time": "23ms", "request_fulfilled": true, "request_debited": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v2/product/upcoming": { "get": { "tags": [ "Products" ], "operationId": "listUpcomingProducts", "summary": "List upcoming releases", "description": "Lists products with a release date after today and up to the end of next year, soonest first. A successful call debits one request from the plan allowance; a call that finds nothing is not debited.\n\nRequired token ability: `upcoming-product`. Plans whose tokens can carry it: Free Trial, Basic, Basic Plus, Standard, Standard Plus, Pro, Pro Plus and Enterprise. A token without the ability gets a 403.", "parameters": [ { "name": "results", "in": "query", "required": false, "description": "Results per page.", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }, { "name": "page", "in": "query", "required": false, "description": "Page number.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "show_data", "in": "query", "required": false, "description": "Send 1 to add the raw source payload (`product_data`) to each product.", "schema": { "type": "integer", "enum": [ 0, 1 ], "default": 0 } } ], "responses": { "200": { "description": "Upcoming products. An empty list returns HTTP 200 with `error: true`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "error", "results", "pagination" ], "properties": { "error": { "type": "boolean", "const": false }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "pagination": { "$ref": "#/components/schemas/NextPagePagination" }, "response_time": { "type": "string", "description": "Server runtime of the request, for example `41ms`." }, "request_fulfilled": { "type": "boolean", "description": "True when the HTTP status is below 400." }, "request_debited": { "type": "boolean", "description": "True only when the call was debited from the plan allowance." } } }, { "$ref": "#/components/schemas/Error" } ] }, "examples": { "success": { "summary": "Success", "value": { "error": false, "results": [ { "product_name": "Nike Dunk Low Retro White Black Panda", "product_brand": "Nike", "product_category": "sneakers", "product_unique_id": "DD1391-100_WHITE-BLACK", "product_style_code": "DD1391-100", "product_release_date": "2026-11-14", "product_description": "The Nike Dunk Low Retro White Black pairs a white leather base with black overlays and a black Swoosh.", "product_colorway": "White/Black", "product_retail_price": "100", "product_image": "https://barcodes.gg/api/image/uid/DD1391-100_WHITE-BLACK" } ], "pagination": { "total": "1", "current_page": "1", "next_page": null, "has_next_page": false }, "response_time": "41ms", "request_fulfilled": true, "request_debited": true } }, "notFound": { "summary": "Nothing found (still HTTP 200)", "value": { "error": true, "message": "No products could be found for this search query.", "response_time": "23ms", "request_fulfilled": true, "request_debited": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v2/product/latest": { "get": { "tags": [ "Products" ], "operationId": "listLatestProducts", "summary": "List latest products", "description": "Returns 10 products per page. By default these are the products added to the database in the last 7 days, ordered by date added. With `release_date_search` the list holds products released between `release_date` and today, ordered by release date. A successful call debits one request from the plan allowance; a call that finds nothing is not debited.\n\nRequired token ability: `latest-product`. Plans whose tokens can carry it: Free Trial, Basic, Basic Plus, Standard, Standard Plus, Pro, Pro Plus and Enterprise. A token without the ability gets a 403.", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "sort", "in": "query", "required": false, "description": "Sort direction. Any other value falls back to desc.", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } }, { "name": "release_date_search", "in": "query", "required": false, "description": "Send `true` or `1` to list by release date instead of by date added. `release_date` is then required.", "schema": { "type": "string", "enum": [ "true", "1" ] } }, { "name": "release_date", "in": "query", "required": false, "description": "Earliest release date, YYYY-MM-DD. Must be no more than 14 days in the past. Results run from this date to today.", "schema": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } } ], "responses": { "200": { "description": "Latest products. An empty page returns HTTP 200 with `error: true`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "error", "products", "pagination" ], "properties": { "error": { "type": "boolean", "const": false }, "products": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "pagination": { "$ref": "#/components/schemas/NextPagePagination" }, "response_time": { "type": "string", "description": "Server runtime of the request, for example `41ms`." }, "request_fulfilled": { "type": "boolean", "description": "True when the HTTP status is below 400." }, "request_debited": { "type": "boolean", "description": "True only when the call was debited from the plan allowance." } } }, { "$ref": "#/components/schemas/Error" } ] }, "examples": { "success": { "summary": "Success", "value": { "error": false, "products": [ { "product_name": "Nike Dunk Low Retro White Black Panda", "product_brand": "Nike", "product_category": "sneakers", "product_unique_id": "DD1391-100_WHITE-BLACK", "product_style_code": "DD1391-100", "product_release_date": "2021-03-10", "product_description": "The Nike Dunk Low Retro White Black pairs a white leather base with black overlays and a black Swoosh.", "product_colorway": "White/Black", "product_retail_price": "100", "product_added": "2026-09-29T04:10:22.000000Z" } ], "pagination": { "current_page": "1", "next_page": null, "has_next_page": false }, "response_time": "41ms", "request_fulfilled": true, "request_debited": true } }, "notFound": { "summary": "Nothing found (still HTTP 200)", "value": { "error": true, "message": "No products could be found for your query.", "response_time": "23ms", "request_fulfilled": true, "request_debited": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v2/product/alternatives/{style_code}": { "get": { "tags": [ "Products" ], "operationId": "getProductAlternatives", "summary": "Get marketplace references for a product", "description": "Returns the StockX and GOAT slug and SKU for a product, to map one style code across marketplaces. The path value is a style code, or a StockX slug. A value made only of lower-case letters, digits and hyphens is treated as a StockX slug, so send style codes in upper case. A successful call debits one request from the plan allowance; a call that finds nothing is not debited.\n\nRequired token ability: `lookup-product-alternatives`. Plans whose tokens can carry it: Free Trial and Enterprise. A token without the ability gets a 403.", "parameters": [ { "name": "style_code", "in": "path", "required": true, "description": "Manufacturer style code (SKU), for example DD1391-100. The value may contain slashes. Or a StockX slug.", "schema": { "type": "string" }, "example": "DD1391-100" } ], "responses": { "200": { "description": "Marketplace references. No match returns HTTP 200 with `error: true`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "boolean", "const": false }, "stockx": { "$ref": "#/components/schemas/MarketplaceReference" }, "goat": { "$ref": "#/components/schemas/MarketplaceReference" }, "alternatives": { "type": "array", "items": {}, "description": "Returned, empty, when the product is known but has no marketplace reference." }, "response_time": { "type": "string", "description": "Server runtime of the request, for example `41ms`." }, "request_fulfilled": { "type": "boolean", "description": "True when the HTTP status is below 400." }, "request_debited": { "type": "boolean", "description": "True only when the call was debited from the plan allowance." } } }, { "$ref": "#/components/schemas/Error" } ] }, "examples": { "success": { "summary": "Success", "value": { "error": false, "stockx": { "slug": "nike-dunk-low-retro-white-black-2021", "sku": "DD1391-100" }, "goat": { "slug": "dunk-low-black-white-dd1391-100", "sku": "DD1391-100" }, "response_time": "41ms", "request_fulfilled": true, "request_debited": true } }, "notFound": { "summary": "Nothing found (still HTTP 200)", "value": { "error": true, "message": "No product could be found for this search query.", "response_time": "23ms", "request_fulfilled": true, "request_debited": false } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v2/token/usage": { "get": { "tags": [ "Account" ], "operationId": "getTokenUsage", "summary": "Get usage for the current token", "description": "Returns the remaining and used requests of the account, the plan limits, and the last call made with this token. This call is not debited.\n\nRequired token ability: `usage-stats`. Plans whose tokens can carry it: Free Trial, Basic, Basic Plus, Standard, Standard Plus, Pro, Pro Plus and Enterprise. A token without the ability gets a 403.", "responses": { "200": { "description": "Usage statistics.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "usage" ], "properties": { "error": { "type": "boolean", "const": false }, "usage": { "$ref": "#/components/schemas/Usage" }, "response_time": { "type": "string", "description": "Server runtime of the request, for example `41ms`." }, "request_fulfilled": { "type": "boolean", "description": "True when the HTTP status is below 400." }, "request_debited": { "type": "boolean", "description": "True only when the call was debited from the plan allowance." } } }, "examples": { "success": { "summary": "Success", "value": { "error": false, "usage": { "calls": { "remaining": 1234, "lifetime": 56789, "plan_limit": 10000, "used_this_cycle": 8766 }, "plan": { "type": "standard", "name": "Standard Plan", "expires_at": "2026-04-30T00:00:00+00:00", "rate_limit": 60, "token_limit": 5 }, "token": { "name": "My SDK Token", "last_used_at": "2026-03-29T12:34:56+00:00" }, "activity": { "last_api_call_at": "2026-03-29T12:34:56+00:00", "last_api_call_name": "Search Products", "last_api_call_status": 200 }, "estimates": { "average_daily_usage": 42.5, "estimated_days_left": 29, "basis": "lifetime_usage_since_signup" } }, "response_time": "18ms", "request_fulfilled": true, "request_debited": false } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/image/uid/{product_unique_id}": { "get": { "tags": [ "Images" ], "operationId": "getImageByUid", "summary": "Get a product image by unique ID", "description": "Returns the image of one exact product variant. No token is needed and the call is not debited. These are the URLs returned in `product_image`. The content type is that of the stored image (WebP, PNG, JPEG, GIF or AVIF).", "security": [], "parameters": [ { "name": "product_unique_id", "in": "path", "required": true, "description": "Unique ID of one product variant, as returned in `product_unique_id`. The value may contain slashes.", "schema": { "type": "string" }, "example": "DD1391-100_WHITE-BLACK" }, { "name": "resize", "in": "query", "required": false, "description": "Presence flag. When the parameter is present the image is returned as a 750 by 750 PNG.", "schema": { "type": "string" } }, { "name": "flip", "in": "query", "required": false, "description": "Presence flag. With `resize`, mirrors the image horizontally.", "schema": { "type": "string" } }, { "name": "no_reply", "in": "query", "required": false, "description": "Presence flag. When no image is available, return an empty `image/png` body with HTTP 200 instead of a JSON error.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The image as binary data. When no image is held for the product the response is HTTP 200 with a JSON error body instead.", "content": { "image/*": { "schema": { "type": "string", "format": "binary" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": true, "message": "Image could not be found." } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/ImageUnavailable" } } } }, "/image/{style_code}": { "get": { "tags": [ "Images" ], "operationId": "getImageByStyleCode", "summary": "Get a product image by style code", "description": "Returns the image stored for a style code. Prefer the unique ID route when several variants share a style code. No token is needed and the call is not debited. These are the URLs returned in `product_image`. The content type is that of the stored image (WebP, PNG, JPEG, GIF or AVIF).", "security": [], "parameters": [ { "name": "style_code", "in": "path", "required": true, "description": "Manufacturer style code (SKU). The value may contain slashes. A value starting with `uid/` is routed to the unique ID endpoint.", "schema": { "type": "string" }, "example": "DH4756-100" }, { "name": "resize", "in": "query", "required": false, "description": "Presence flag. When the parameter is present the image is returned as a 750 by 750 PNG.", "schema": { "type": "string" } }, { "name": "flip", "in": "query", "required": false, "description": "Presence flag. With `resize`, mirrors the image horizontally.", "schema": { "type": "string" } }, { "name": "no_reply", "in": "query", "required": false, "description": "Presence flag. When no image is available, return an empty `image/png` body with HTTP 200 instead of a JSON error.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The image as binary data. When no image is held for the product the response is HTTP 200 with a JSON error body instead.", "content": { "image/*": { "schema": { "type": "string", "format": "binary" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": true, "message": "Image could not be found." } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/ImageUnavailable" } } } }, "/barcode/lookup/{barcode}": { "get": { "tags": [ "Legacy v1" ], "operationId": "lookupBarcodeV1", "summary": "Look up a product by barcode (v1)", "description": "Resolves a UPC or EAN to its product and size. Legacy v1 endpoint, kept for existing integrations; new integrations should use the v2 equivalent. The description is returned as stored, without clean-up, and the product has no `product_unique_id`. Error responses carry only `error` and `message`.\n\nRequired token ability: `lookup-barcode`. Plans whose tokens can carry it: Free Trial, Basic, Basic Plus, Standard, Standard Plus, Pro, Pro Plus and Enterprise. A token without the ability gets a 403.", "parameters": [ { "name": "barcode", "in": "path", "required": true, "description": "UPC or EAN digits, 8 to 15 characters, no letters. One leading zero is dropped before matching, and all GTIN zero-paddings of the number are tried.", "schema": { "type": "string", "minLength": 8, "maxLength": 15, "pattern": "^[0-9]{8,15}$" }, "example": "195245980597" }, { "name": "fields", "in": "query", "required": true, "description": "Either `*` for everything, or up to four comma-separated field names. `product` and `barcode` return the whole object. Dotted names return one value as a top-level key named after the part behind the dot: `product.product_name`, `product.product_brand`, `product.product_category`, `product.product_description`, `product.product_unique_id` (v2 only), `product.product_style_code`, `product.product_colorway`, `product.product_release_date`, `product.product_retail_price`, `product.product_image`, `product.product_sizes`, `product.product_added`, `product.product_updated`, `barcode.barcode_type`, `barcode.barcode_value`, `barcode.barcode_added`, `barcode.product_size`. Unknown names are ignored.", "schema": { "type": "string", "pattern": "^[a-zA-Z*._]+(,[a-zA-Z._]+){0,3}$", "example": "*" } }, { "name": "show_data", "in": "query", "required": false, "description": "Send 1 to add `product_data` and `us_sizes` to the product object.", "schema": { "type": "integer", "enum": [ 0, 1 ], "default": 0 } } ], "responses": { "200": { "description": "Lookup result. An unknown barcode returns HTTP 200 with `error: true`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "error" ], "description": "With `fields=*` the body holds `product` and `barcode`. With named fields it holds only what was requested, flattened to top-level keys.", "properties": { "error": { "type": "boolean", "const": false }, "product": { "$ref": "#/components/schemas/Product" }, "barcode": { "$ref": "#/components/schemas/Barcode" }, "response_time": { "type": "string", "description": "Server runtime of the request, for example `41ms`." }, "request_fulfilled": { "type": "boolean", "description": "True when the HTTP status is below 400." }, "request_debited": { "type": "boolean", "description": "True only when the call was debited from the plan allowance." } }, "additionalProperties": true }, { "$ref": "#/components/schemas/Error" } ] }, "examples": { "success": { "summary": "Success", "value": { "error": false, "product": { "product_name": "Nike Dunk Low Retro White Black Panda", "product_brand": "Nike", "product_category": "sneakers", "product_style_code": "DD1391-100", "product_release_date": "2021-03-10", "product_description": "The Nike Dunk Low Retro White Black pairs a white leather base with black overlays and a black Swoosh.", "product_colorway": "White/Black", "product_retail_price": "100", "product_image": "https://barcodes.gg/api/image/uid/DD1391-100_WHITE-BLACK", "product_sizes": [ 6, 6.5, 7, 7.5, 8, 8.5, 9, 9.5, 10, 10.5, 11, 12, 13 ], "product_added": "2023-06-14T09:21:07.000000Z", "product_updated": "2026-08-30T02:11:45.000000Z" }, "barcode": { "barcode_type": "GTIN12", "barcode_value": "195245980597", "barcode_added": null, "product_size": { "us": "9", "uk": "8", "eu": "42.5" } }, "response_time": "41ms", "request_fulfilled": true, "request_debited": true } }, "notFound": { "summary": "Nothing found (still HTTP 200)", "value": { "error": true, "message": "Barcode could not be found." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/barcode/lookup/sku/{style_code}": { "get": { "tags": [ "Legacy v1" ], "operationId": "lookupBarcodesBySkuV1", "summary": "List barcodes for a style code (v1)", "description": "Returns the barcodes held for a style code, 20 per page. Legacy v1 endpoint, kept for existing integrations; new integrations should use the v2 equivalent. It has no `sizerun` mode. Every successful call debits one request.\n\nRequired token ability: `lookup-barcode-sku`. Plans whose tokens can carry it: Free Trial, Basic Plus, Standard Plus, Pro Plus and Enterprise. A token without the ability gets a 403.", "parameters": [ { "name": "style_code", "in": "path", "required": true, "description": "Manufacturer style code (SKU), for example DD1391-100. The value may contain slashes.", "schema": { "type": "string" }, "example": "DD1391-100" }, { "name": "is_verified", "in": "query", "required": false, "description": "Send 1 to leave out barcodes derived by the size-run algorithm.", "schema": { "type": "integer", "enum": [ 0, 1 ], "default": 0 } }, { "name": "page", "in": "query", "required": false, "description": "Page number, or `all` to get up to 1000 barcodes in one page.", "schema": { "oneOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "enum": [ "all" ] } ], "default": 1 } } ], "responses": { "200": { "description": "Barcodes for the style code. No match returns HTTP 200 with `error: true`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "error", "barcodes", "pagination" ], "properties": { "error": { "type": "boolean", "const": false }, "barcodes": { "type": "array", "items": { "$ref": "#/components/schemas/SkuBarcode" } }, "pagination": { "$ref": "#/components/schemas/NextPagePagination" }, "response_time": { "type": "string", "description": "Server runtime of the request, for example `41ms`." }, "request_fulfilled": { "type": "boolean", "description": "True when the HTTP status is below 400." }, "request_debited": { "type": "boolean", "description": "True only when the call was debited from the plan allowance." } } }, { "$ref": "#/components/schemas/Error" } ] }, "examples": { "success": { "summary": "Success", "value": { "error": false, "barcodes": [ { "product_barcode_type": "GTIN12", "product_barcode_value": "195245980597", "product_size": { "us": "9", "uk": "8", "eu": "42.5" }, "isVerified": true } ], "pagination": { "current_page": "1", "next_page": null, "has_next_page": false }, "response_time": "41ms", "request_fulfilled": true, "request_debited": true } }, "notFound": { "summary": "Nothing found (still HTTP 200)", "value": { "error": true, "message": "No barcodes could not be found for this style code." } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/product/search": { "get": { "tags": [ "Legacy v1" ], "operationId": "searchProductsV1", "summary": "Search products (v1)", "description": "Full-text search over products, ordered by text relevance. Legacy v1 endpoint, kept for existing integrations; new integrations should use the v2 equivalent. It has no pagination and returns `relevance` instead of `match_count`.\n\nRequired token ability: `search-product`. Plans whose tokens can carry it: Free Trial, Basic, Basic Plus, Standard, Standard Plus, Pro, Pro Plus and Enterprise. A token without the ability gets a 403.", "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Search text.", "schema": { "type": "string", "minLength": 3, "example": "dunk low panda" } }, { "name": "results", "in": "query", "required": false, "description": "Maximum number of results.", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 } }, { "name": "show_data", "in": "query", "required": false, "description": "Send 1 to add `_id` and `product_data` to each result.", "schema": { "type": "integer", "enum": [ 0, 1 ], "default": 0 } } ], "responses": { "200": { "description": "Search results. No match returns HTTP 200 with `error: true`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "error", "results" ], "properties": { "error": { "type": "boolean", "const": false }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } } } }, { "$ref": "#/components/schemas/Error" } ] }, "examples": { "success": { "summary": "Success", "value": { "error": false, "results": [ { "product_name": "Nike Dunk Low Retro White Black Panda", "product_brand": "Nike", "product_category": "sneakers", "product_style_code": "DD1391-100", "product_release_date": "2021-03-10", "product_description": "The Nike Dunk Low Retro White Black pairs a white leather base with black overlays and a black Swoosh.", "product_colorway": "White/Black", "product_retail_price": "100", "product_image": "https://barcodes.gg/api/image/uid/DD1391-100_WHITE-BLACK", "relevance": 2.25 } ] } }, "notFound": { "summary": "Nothing found (still HTTP 200)", "value": { "error": true, "message": "No products could be found for this search query." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/product/lookup/sku/{style_code}": { "get": { "tags": [ "Legacy v1" ], "operationId": "lookupProductBySkuV1", "summary": "Get a product by style code (v1)", "description": "Returns the first product stored under a style code, as the complete stored record. Legacy v1 endpoint, kept for existing integrations; new integrations should use the v2 equivalent. The record includes internal fields such as `_id`, `product_data`, `created_at` and `updated_at`, and has no `product_image`.\n\nRequired token ability: `lookup-product`. Plans whose tokens can carry it: Free Trial, Basic, Basic Plus, Standard, Standard Plus, Pro, Pro Plus and Enterprise. A token without the ability gets a 403.", "parameters": [ { "name": "style_code", "in": "path", "required": true, "description": "Manufacturer style code (SKU), for example DD1391-100. This route does not accept slashes in the value.", "schema": { "type": "string" }, "example": "DD1391-100" } ], "responses": { "200": { "description": "The stored product record. No match returns HTTP 200 with `error: true`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "error", "product" ], "properties": { "error": { "type": "boolean", "const": false }, "product": { "$ref": "#/components/schemas/Product" } } }, { "$ref": "#/components/schemas/Error" } ] }, "examples": { "success": { "summary": "Success", "value": { "error": false, "product": { "product_name": "Nike Dunk Low Retro White Black Panda", "product_brand": "Nike", "product_category": "sneakers", "product_unique_id": "DD1391-100_WHITE-BLACK", "product_style_code": "DD1391-100", "product_release_date": "2021-03-10", "product_description": "The Nike Dunk Low Retro White Black pairs a white leather base with black overlays and a black Swoosh.", "product_colorway": "White/Black", "product_retail_price": "100" } } }, "notFound": { "summary": "Nothing found (still HTTP 200)", "value": { "error": true, "message": "No product could be found for this search query." } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/product/latest": { "get": { "tags": [ "Legacy v1" ], "operationId": "listLatestProductsV1", "summary": "List latest products (v1)", "description": "Returns 10 products per page. By default these are the products added to the database in the last 7 days, ordered by date added. With `release_date_search` the list holds products released between `release_date` and today, ordered by release date. Legacy v1 endpoint, kept for existing integrations; new integrations should use the v2 equivalent. Products have no `product_unique_id`. Every successful call debits one request.\n\nRequired token ability: `latest-product`. Plans whose tokens can carry it: Free Trial, Basic, Basic Plus, Standard, Standard Plus, Pro, Pro Plus and Enterprise. A token without the ability gets a 403.", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "sort", "in": "query", "required": false, "description": "Sort direction. Any other value falls back to desc.", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } }, { "name": "release_date_search", "in": "query", "required": false, "description": "Send `true` or `1` to list by release date instead of by date added. `release_date` is then required.", "schema": { "type": "string", "enum": [ "true", "1" ] } }, { "name": "release_date", "in": "query", "required": false, "description": "Earliest release date, YYYY-MM-DD. Must be no more than 14 days in the past. Results run from this date to today.", "schema": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } } ], "responses": { "200": { "description": "Latest products. An empty page returns HTTP 200 with `error: true`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "error", "products", "pagination" ], "properties": { "error": { "type": "boolean", "const": false }, "products": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "pagination": { "$ref": "#/components/schemas/NextPagePagination" }, "response_time": { "type": "string", "description": "Server runtime of the request, for example `41ms`." }, "request_fulfilled": { "type": "boolean", "description": "True when the HTTP status is below 400." }, "request_debited": { "type": "boolean", "description": "True only when the call was debited from the plan allowance." } } }, { "$ref": "#/components/schemas/Error" } ] }, "examples": { "success": { "summary": "Success", "value": { "error": false, "products": [ { "product_name": "Nike Dunk Low Retro White Black Panda", "product_brand": "Nike", "product_category": "sneakers", "product_style_code": "DD1391-100", "product_release_date": "2021-03-10", "product_description": "The Nike Dunk Low Retro White Black pairs a white leather base with black overlays and a black Swoosh.", "product_colorway": "White/Black", "product_retail_price": "100", "product_added": "2026-09-29T04:10:22.000000Z" } ], "pagination": { "current_page": "1", "next_page": null, "has_next_page": false }, "response_time": "41ms", "request_fulfilled": true, "request_debited": true } }, "notFound": { "summary": "Nothing found (still HTTP 200)", "value": { "error": true, "message": "No products could be found for your query." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/product/details/{style_code}": { "get": { "tags": [ "Legacy v1" ], "operationId": "getProductDetailsV1", "summary": "Get product details with the size run (v1)", "description": "Returns a merged product record and the full size run with the EAN and UPC held for each size. Legacy v1 endpoint, kept for existing integrations; new integrations should use the v2 equivalent. It takes no query parameters, does not accept slugs, returns no `product_unique_id`, and `image` is a marketplace image URL. This call is not debited.\n\nRequired token ability: `product-details`. Plans whose tokens can carry it: Free Trial, Pro, Pro Plus and Enterprise. A token without the ability gets a 403.", "parameters": [ { "name": "style_code", "in": "path", "required": true, "description": "Manufacturer style code (SKU), for example DD1391-100. This route does not accept slashes in the value.", "schema": { "type": "string" }, "example": "DD1391-100" } ], "responses": { "200": { "description": "Product details. No match returns HTTP 200 with `error: true`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "error", "product" ], "properties": { "error": { "type": "boolean", "const": false }, "product": { "$ref": "#/components/schemas/ProductDetails" } } }, { "$ref": "#/components/schemas/Error" } ] }, "examples": { "success": { "summary": "Success", "value": { "error": false, "product": { "sku": "DD1391-100", "type": "Sneakers", "colourway": "White/Black", "category": "sneakers", "title": "Nike Dunk Low Retro White Black Panda", "brand": "Nike", "nickname": "Panda", "designer": "Peter Moore", "main_color": "White", "model": "Nike Dunk Low", "gender": "men", "upper_material": "Leather", "release_date": "2021-03-10", "release_date_formatted": "10/03/2021", "retail_price": 10000, "retail_price_gbp": 9000, "retail_price_usd": "100", "description": "The Nike Dunk Low Retro White Black pairs a white leather base with black overlays and a black Swoosh.", "stockx_total_sold": "", "image": "https://image.goat.com/750/attachments/product_template_pictures/images/example.png", "sizes": [ { "eu": "42", "uk": "7.5", "us": "8.5", "ean": "", "upc": "" }, { "eu": "42.5", "uk": "8", "us": "9", "ean": "", "upc": "195245980597" } ], "variants": 2, "variant_format": "UK", "size_run": "7.5 - 8", "internal_category": "Sneakers", "search_sku": "DD1391-100" } } }, "notFound": { "summary": "Nothing found (still HTTP 200)", "value": { "error": true, "message": "No product could be found for this style code." } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API token created in the dashboard under Tokens (Laravel Sanctum personal access token). Send it as `Authorization: Bearer `. Each token carries a set of abilities limited to those of the plan; each endpoint requires one ability. Free Trial tokens expire when the trial ends." } }, "schemas": { "Error": { "type": "object", "description": "Error envelope. Lookups that find nothing also use it, with HTTP 200. The three metadata fields are added to v2 JSON responses produced inside the v2 route group; 401 and 429 responses do not carry them.", "required": [ "error", "message" ], "properties": { "error": { "type": "boolean", "const": true }, "message": { "description": "A message string, or for validation failures an object mapping each field name to a list of messages.", "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } ] }, "response_time": { "type": "string", "description": "Server runtime of the request, for example `41ms`." }, "request_fulfilled": { "type": "boolean", "description": "True when the HTTP status is below 400." }, "request_debited": { "type": "boolean", "description": "True only when the call was debited from the plan allowance." } } }, "Size": { "type": "object", "description": "Size of the item a barcode belongs to, per sizing region. Other regional keys (for example `us w`) can be present.", "properties": { "us": { "type": [ "string", "number", "null" ] }, "uk": { "type": [ "string", "number", "null" ] }, "eu": { "type": [ "string", "number", "null" ] } }, "additionalProperties": true }, "Barcode": { "type": "object", "description": "A barcode as returned by the barcode lookup.", "properties": { "barcode_type": { "type": "string", "description": "Stored symbology, for example GTIN12 (UPC-A) or GTIN13 (EAN-13)." }, "barcode_value": { "type": "string", "description": "Barcode digits as stored." }, "barcode_added": { "type": [ "string", "null" ], "description": "When the barcode was added, if recorded." }, "product_size": { "$ref": "#/components/schemas/Size" } } }, "SkuBarcode": { "type": "object", "description": "A barcode as returned by the lookup by style code.", "properties": { "product_barcode_type": { "type": "string", "description": "GTIN12 or GTIN13." }, "product_barcode_value": { "type": "string" }, "product_size": { "$ref": "#/components/schemas/Size" }, "isVerified": { "type": "boolean", "description": "False when the barcode was derived by the size-run algorithm instead of being observed." } } }, "Product": { "type": "object", "description": "Product record. The first ten properties are returned by every product endpoint; the rest depend on the endpoint and on `show_data`. Example values in this document are illustrative.", "properties": { "product_name": { "type": [ "string", "null" ] }, "product_brand": { "type": [ "string", "null" ] }, "product_category": { "type": [ "string", "null" ] }, "product_unique_id": { "type": [ "string", "null" ], "description": "Identifier of one exact variant, built as style code, underscore, colourway. Not returned by the v1 endpoints." }, "product_style_code": { "type": [ "string", "null" ] }, "product_release_date": { "type": [ "string", "null" ], "description": "Usually YYYY-MM-DD." }, "product_description": { "type": [ "string", "null" ], "description": "Plain text." }, "product_colorway": { "type": [ "string", "null" ] }, "product_retail_price": { "type": [ "string", "number", "null" ] }, "product_image": { "type": [ "string", "null" ], "format": "uri", "description": "URL of the image endpoint for this product." }, "product_sizes": { "type": [ "array", "null" ], "items": {}, "description": "Size range of the product. Barcode lookup only." }, "product_added": { "type": [ "string", "null" ], "format": "date-time", "description": "Barcode lookup and latest products only." }, "product_updated": { "type": [ "string", "null" ], "format": "date-time", "description": "Barcode lookup only." }, "product_last_checked": { "type": [ "string", "null" ], "format": "date-time", "description": "Product lookup by style code or unique ID only." }, "match_count": { "type": "integer", "description": "Number of query tokens matched. v2 search and bulk search only." }, "relevance": { "type": "number", "description": "Text search score. v1 search only." }, "product_data": { "description": "Raw source payload. Only with show_data=1.", "type": [ "string", "array", "object", "null" ] }, "us_sizes": { "type": "array", "items": { "type": "string" }, "description": "All US sizes known for the style code. Barcode lookup with show_data=1 only." } }, "additionalProperties": true }, "Pagination": { "type": "object", "description": "Page-number pagination used by product search.", "properties": { "total": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" }, "last_page": { "type": "integer" } } }, "NextPagePagination": { "type": "object", "description": "Next-page pagination used by the barcode-by-SKU, latest and upcoming endpoints. Page numbers are strings.", "properties": { "total": { "type": "string", "description": "Total matches. Upcoming products only." }, "current_page": { "type": "string" }, "next_page": { "type": [ "string", "null" ] }, "has_next_page": { "type": "boolean" } } }, "SizeRunEntry": { "type": "object", "description": "One size of a product with its barcodes. `ean` and `upc` are empty strings when no barcode is held for the size.", "properties": { "eu": { "type": "string" }, "uk": { "type": "string" }, "us": { "type": "string" }, "ean": { "type": "string" }, "upc": { "type": "string" } } }, "ProductDetails": { "type": "object", "description": "Merged product record with the full size run.", "properties": { "sku": { "type": "string" }, "type": { "type": "string" }, "colourway": { "type": "string" }, "category": { "type": [ "string", "object", "null" ] }, "title": { "type": "string" }, "brand": { "type": "string" }, "nickname": { "type": "string" }, "designer": { "type": "string" }, "main_color": { "type": "string" }, "model": { "type": "string" }, "product_unique_id": { "type": [ "string", "null" ], "description": "v2 only." }, "gender": { "type": "string" }, "upper_material": { "type": "string" }, "release_date": { "type": "string" }, "release_date_formatted": { "type": "string", "description": "DD/MM/YYYY, or empty." }, "retail_price": { "type": [ "integer", "number", "string", "null" ] }, "retail_price_gbp": { "type": [ "integer", "number", "string", "null" ] }, "retail_price_usd": { "type": [ "integer", "number", "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "stockx_total_sold": { "type": [ "integer", "string", "null" ] }, "image": { "type": "string", "format": "uri" }, "sizes": { "type": "array", "items": { "$ref": "#/components/schemas/SizeRunEntry" } }, "variants": { "type": "integer", "description": "Number of sizes." }, "variant_format": { "type": "string", "description": "UK or N/A." }, "size_run": { "type": "string", "description": "First and last size, for example `3 - 14`." }, "internal_category": { "type": "string", "description": "Sneakers, Clothing, Accessories or Collectibles." }, "search_sku": { "type": "string" }, "goat_image": { "type": "string", "description": "v2 with show_images=1 only." }, "stockx_image": { "type": "string", "description": "v2 with show_images=1 only." }, "product_images": { "type": "array", "items": { "type": "string" }, "description": "v2 with show_images=1 only." } } }, "MarketplaceReference": { "type": "object", "properties": { "slug": { "type": "string" }, "sku": { "type": "string" } } }, "Usage": { "type": "object", "properties": { "calls": { "type": "object", "properties": { "remaining": { "type": "integer" }, "lifetime": { "type": "integer" }, "plan_limit": { "type": "integer" }, "used_this_cycle": { "type": "integer" } } }, "plan": { "type": "object", "properties": { "type": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "rate_limit": { "type": [ "integer", "null" ], "description": "Requests per minute." }, "token_limit": { "type": [ "integer", "null" ] } } }, "token": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "activity": { "type": "object", "properties": { "last_api_call_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_api_call_name": { "type": [ "string", "null" ] }, "last_api_call_status": { "type": [ "integer", "null" ] } } }, "estimates": { "type": "object", "properties": { "average_daily_usage": { "type": "number" }, "estimated_days_left": { "type": [ "integer", "null" ] }, "basis": { "type": "string" } } } } } }, "responses": { "BadRequest": { "description": "A parameter failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "validation": { "summary": "Validation errors", "value": { "error": true, "message": { "fields": [ "The fields field is required." ] }, "response_time": "12ms", "request_fulfilled": false, "request_debited": false } } } } } }, "Unauthorized": { "description": "The bearer token is missing, unknown or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalidToken": { "summary": "Invalid token", "value": { "error": true, "message": "Invalid authorization token." } } } } } }, "Forbidden": { "description": "The plan allowance is used up, or the token lacks the ability this endpoint requires.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "quota": { "summary": "No requests left", "value": { "error": true, "message": "API Token has run out of usage, please top up via the dashboard.", "response_time": "12ms", "request_fulfilled": false, "request_debited": false } }, "ability": { "summary": "Missing ability", "value": { "error": true, "message": "Invalid permissions to perform this action.", "response_time": "12ms", "request_fulfilled": false, "request_debited": false } } } } } }, "RateLimited": { "description": "The per-minute rate limit of the plan was exceeded. Unauthenticated routes are limited to 30 requests per minute per IP address.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rateLimited": { "summary": "Rate limited", "value": { "error": true, "message": "Rate limit reached, please wait and try again." } } } } } }, "ImageUnavailable": { "description": "The image exists but could not be read from storage.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unavailable": { "summary": "Storage error", "value": { "error": true, "message": "Image could not be retrieved at this time." } } } } } } } } }