Barcodes.GG Account API

openapi: 3.2.0
info:
  title: Barcodes.gg Account 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: Account
  description: Usage of the calling token.
paths:
  /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.


        Required 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'
components:
  schemas:
    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
    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.
  responses:
    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.
  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