> ## Documentation Index
> Fetch the complete documentation index at: https://pricepirate.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Create an Allegro price-lookup job

> Submit one product barcode (EAN / GTIN / UPC) with `country: pl`. Returns a `job_id` you then poll via `GET /jobs/{job_id}`. Prices are returned in Polish złoty (PLN).



## OpenAPI

````yaml /price-data/global.yaml post /allegro/search-by-gtin
openapi: 3.0.3
info:
  title: Global EAN/GTIN Price Data API
  version: 1.0.0
  description: >-
    One barcode in, every market out. This API merges five price sources —
    Klarna, PriceRunner, Idealo, Google Shopping and Allegro — behind a single
    universal endpoint and a single unified response schema. Submit an EAN /
    GTIN / UPC, choose a source and a country, and get back every merchant offer
    for that exact product: price, shipping, total, item condition,
    availability, voucher/free-return flags and per-store ratings — all in one
    JSON shape, whichever source you hit. Covers 29 countries across 47
    source-country marketplaces.


    ## Sources & coverage

    - **klarna** — `at, dk, fi, fr, de, ie, it, nl, no, es, se, us` -
    **pricerunner** — `uk, se, dk` - **idealo** — `de, at` - **google-shopping**
    — `us, nl, de, fr, uk, es, it, be, at, ch, pl, se, dk,
      no, fi, pt, ie, cz, hu, ro, gr, sk, hr, bg, au, ca, br, in, jp`
    - **allegro** — `pl`


    ## How it works (asynchronous jobs)

    1. **Create a job** — call the universal endpoint
       `POST /universal/search-by-gtin` with a `source`, a `country` and one
       barcode, or call a dedicated per-source endpoint. You receive a `job_id`.
    2. **Poll for results** — `GET /jobs/{job_id}` every 1–2 seconds until
       `status` is `completed`. Live lookups are typically ready within a few
       seconds.

    Barcodes follow the GTIN standard (8–14 digit strings) and are compatible
    with EAN, UPC and JAN. The `result` object is identical in shape across
    every source — fields a given source does not provide come back as `null`.
    Note: for Google Shopping, `price_min` / `price_avg` / `price_max` are based
    on the total price (item + shipping); for other sources they reflect the
    item price. Idealo additionally exposes `search-by-id`, `search-by-term` and
    `search-by-url`; `search-by-term` returns matching listings (with
    `price_min` and `offers_count` but an empty `offers` array) — expand one via
    `search-by-id` to get its full offer breakdown.
servers:
  - url: https://<rapidapi-host>.p.rapidapi.com
security:
  - rapidApiKey: []
tags:
  - name: Universal
    description: Single endpoint that routes a lookup to any source.
  - name: Klarna
    description: Klarna shopping-network price data.
  - name: PriceRunner
    description: PriceRunner comparison-network price data.
  - name: Idealo
    description: Idealo price-comparison data (barcode, ID, term, URL).
  - name: Google Shopping
    description: Google Shopping price data.
  - name: Allegro
    description: Allegro (Poland) marketplace price data.
  - name: Jobs
    description: Retrieve job results.
  - name: System
    description: Service health.
paths:
  /allegro/search-by-gtin:
    post:
      tags:
        - Allegro
      summary: Create an Allegro price-lookup job
      description: >-
        Submit one product barcode (EAN / GTIN / UPC) with `country: pl`.
        Returns a `job_id` you then poll via `GET /jobs/{job_id}`. Prices are
        returned in Polish złoty (PLN).
      operationId: /allegro/search-by-gtin
      parameters:
        - $ref: '#/components/parameters/RapidApiHostHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AllegroSearchRequest'
            examples:
              poland:
                summary: Single barcode in Poland
                value:
                  country: pl
                  values:
                    - '4013474101469'
      responses:
        '200':
          description: Job created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobCreatedResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalidCountry:
                  value:
                    error: true
                    message: 'Invalid country: de. Available for allegro: pl'
components:
  parameters:
    RapidApiHostHeader:
      name: x-rapidapi-host
      in: header
      required: true
      description: Your RapidAPI host.
      schema:
        type: string
        example: <rapidapi-host>
  schemas:
    AllegroSearchRequest:
      type: object
      additionalProperties: false
      required:
        - country
        - values
      properties:
        country:
          $ref: '#/components/schemas/AllegroCountry'
        values:
          $ref: '#/components/schemas/BarcodeList'
    JobCreatedResponse:
      type: object
      required:
        - error
        - job_id
      properties:
        error:
          type: boolean
          example: false
        job_id:
          type: string
          example: f3a1c2b4-5d6e-7f80-9a1b-2c3d4e5f6071
    ErrorResponse:
      type: object
      required:
        - error
        - message
      properties:
        error:
          type: boolean
          example: true
        message:
          type: string
          example: country is required
    AllegroCountry:
      type: string
      description: >-
        Two-letter Allegro country code. Allegro currently supports `pl`
        (Poland).
      enum:
        - pl
      example: pl
    BarcodeList:
      type: array
      description: >-
        Exactly one product barcode (GTIN / EAN / UPC / JAN), digits only, 8–14
        chars.
      minItems: 1
      maxItems: 1
      items:
        type: string
        pattern: ^\d{8,14}$
        example: '4013474101469'
  securitySchemes:
    rapidApiKey:
      type: apiKey
      in: header
      name: x-rapidapi-key
      description: Your RapidAPI key.

````