Barcodes.GG Barcodes API

openapi: 3.2.0
info:
  title: .gg Barcodes 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
servers:
- url: https://barcodes.gg/api
  description: Production
security:
- bearerAuth: []
tags:
- name: Barcodes
  description: Barcode to product, and style code to barcodes (v2).
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.`


        Required 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.


        Required 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'
components:
  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
    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.
    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
    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.
  schemas:
    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
    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.
    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'
    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
    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
    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.
  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 <token>`. 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.'
externalDocs:
  description: Barcodes.gg API documentation
  url: https://barcodes.gg/guide/docs/introduction