Back Market Backbox API

openapi: 3.2.0
info:
  version: 0.1.1
  title: Back Market - API Guidelines Backbox API
  description: '## Table of contents


    1.'
  contact:
    name: Seller Support Center
    url: https://merchant-support.backmarket.com/hc/en-us
    x-slack: NA
    email: NA@NA.com
servers:
- url: https://preprod.backmarket.co.jp
  description: Preprod - AP
- url: https://www.backmarket.co.jp
  description: Prod - AP
- url: https://preprod.backmarket.fr
  description: Preprod - EU
- url: https://www.backmarket.fr
  description: Prod - EU
- url: https://preprod.backmarket.com
  description: Preprod - NA
- url: https://www.backmarket.com
  description: Prod - NA
tags:
- name: Backbox
paths:
  /ws/listings_bi:
    get:
      description: 'Get the Backbox data related to your competitors, i.e. your online listings competing in a Backbox. You can call this endpoint twice every hour for each country.


        Backbox (previously named Buybox) is the listing displayed at a given time on the website when it has the best ratio quality score per price.


        This endpoint is being deprecated in favor of the /ws/backbox/v1/competitors endpoint.'
      operationId: GetBackboxData
      parameters:
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  count:
                    description: Total number of backbox data per listing
                    example: 42
                    type: integer
                  next:
                    description: URL to get the next paginated backbox data per listing list. Null if no next page
                    example: https://www.backmarket.fr/ws/listings_bi/?page=2
                    type:
                    - string
                    - 'null'
                  previous:
                    description: URL to get the previous paginated backbox data per listing list. Null if no previous page
                    example: https://www.backmarket.fr/ws/listings_bi/?page=1
                    type:
                    - string
                    - 'null'
                  results:
                    description: List of backbox data per listing
                    items:
                      $ref: '#/components/schemas/Backbox'
                    type: array
                required:
                - count
                - next
                - previous
                - results
                type: object
          description: List of backbox data per listing
        '403':
          description: Permission denied
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponseV3'
        '404':
          description: Webservices unavailable
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponseV3'
        '429':
          description: Too many calls
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponseV3'
      summary: Return backbox data per listing list
      tags:
      - Backbox
      x-category: domain
      x-tier: 2
  /ws/backbox/v1/competitors/{listingId}:
    get:
      description: 'Get the Backbox data related to your competitors, i.e. your online listings competing in a Backbox.


        You can call this endpoint twice per second per API token.


        Here is an example of how you can use the Listings and the BackBox APIs together, in order to adjust your listings'' prices in case there are some good opportunities. This can allow you to win more BackBoxes automatically with small prices reductions.'
      parameters:
      - in: path
        name: listingId
        required: true
        schema:
          format: uuid
          title: Listing Id
          type: string
        example: 7e1f4a8d-b1bb-47aa-9f77-2cca759eb41b
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/Competitor'
                type: array
                description: Each item is a competitor, ie. a `listing x market`, competing for a single Backbox.
          description: Successful Response
        '401':
          description: Unauthorized
        '404':
          description: Not Found
        '422':
          description: Unprocessable Entity
      security:
      - ApiKeyAuth: []
      - BasicAuth: []
      summary: Get competitors
      tags:
      - Backbox
      x-category: domain
      x-tier: 2
      operationId: getWsBackboxV1CompetitorsByListingId
      x-operation-id-source: derived
components:
  schemas:
    Competitor:
      properties:
        is_winning:
          description: Whether or not this competitor is winning the backbox.
          title: Is Winning
          type: boolean
        listing_id:
          description: The listing public id of this competitor.
          format: uuid
          title: Listing Id
          type: string
        min_price:
          anyOf:
          - $ref: '#/components/schemas/MonetaryAmount'
          description: The mimimum price set by the competitor.
        price:
          allOf:
          - $ref: '#/components/schemas/MonetaryAmount'
          description: The target price set by the competitor.
        price_to_win:
          allOf:
          - $ref: '#/components/schemas/MonetaryAmount'
          description: The price that the competitor must set to win the backbox.
        product_id:
          description: The product public id of this competitor.
          format: uuid
          title: Product Id
          type: string
        winner_price:
          anyOf:
          - $ref: '#/components/schemas/MonetaryAmount'
          description: The price of the backbox i.e. the selling price of the winner.
        market:
          anyOf:
          - $ref: '#/components/schemas/MarketCode'
          description: The market of the backbox.
      required:
      - listing_id
      - product_id
      - price
      - min_price
      - price_to_win
      - winner_price
      - is_winning
      - market
      title: Competitor
      type: object
    MonetaryAmount:
      title: MonetaryAmount
      type: object
      example:
        amount: '42'
        currency: EUR
      properties:
        amount:
          type: string
          pattern: ^\d*(\.\d*)?$
          description: 'Amount is a human representation of a decimal, without any localization.


            Trailing zero in decimal places MAY be passed (eg: "13.0")


            Values with more decimal places than the minor unit of the currency MUST NOT be considered as valid.

            The trailing zero guideline has priority over it.

            ```

            {"amount": "13.000", "currency": "EUR"} is also valid, but {"amount": "13.123", "currency": "EUR"} is not.

            ```


            Leading zero SHOULD be in the amount if the value is between 0 and 1.


            Decimal separator MAY be supplied without decimal places.'
          example: '42'
        currency:
          type: string
          pattern: ^[A-Z]{3}$
          description: 'The currency MUST be represented as a code following the ISO 4217 standard:

            "EUR" for euro, "USD" for U.S. dollar, etc.

            '
          example: EUR
      required:
      - amount
      - currency
      description: 'Back Market common monetary amount model.



        Empty monetary amount (ie amount equals 0) property SHOULD be exposed according to the following rules:

        - `{ amount: ''0.00'', currency: ''EUR|USD|...'' }`

        When a monetary amount is 0, and is intended to be displayed. Ex: free warranty, etc.

        - `null` when a monetary amount is 0, and is intended to be hidden.

        Ex: discount: `null`, when a user has no discount.

        - omitted, when a monetary amount is non-existent.

        Ex, when a feature is disabled: backlabel: `null` means BackLabel feature is enabled but not on one particular item,

        while not having backlabel field at all means BackLabel feature is disabled.'
      x-internal: false
    Error:
      description: ''
      properties:
        code:
          type: string
        data:
          type: object
        docLink:
          type: string
        message:
          type: string
        target:
          type: string
      required:
      - code
      - message
      type: object
    ErrorResponseV3:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/Error'
        status:
          description: HTTP status code
          type: integer
        title:
          description: summary of the problem type
          type:
          - string
          - 'null'
        type:
          description: unique problem identifier
          type:
          - string
          - 'null'
        requestId:
          description: ID of the request
          type: string
      required:
      - error
      - status
      - title
      - type
    ProductCondition:
      type: integer
      enum:
      - 9
      - 10
      - 11
      - 12
      description: 'Condition of the product.


        | Value | Description         |

        |-------|---------------------|

        | 9     | Premium condition   |

        | 1O    | Excellent condition |

        | 11    | Good condition      |

        | 12    | Fair condition      |

        '
      example: 10
    MarketCode:
      type: string
      description: Two-letter country code of the market. Format ISO_3166-2
      enum:
      - FR
      - BE
      - DE
      - IT
      - ES
      - GB
      - AT
      - NL
      - US
      - FI
      - PT
      - IE
      - GR
      - SK
      - SE
      - JP
      example: FR
    Backbox:
      title: Backbox
      type: object
      required:
      - product
      - sku
      - price
      - quantity
      - buybox
      - price_for_buybox
      - current
      - condition
      - same_merchant_winner
      properties:
        product:
          type: integer
          description: Product ID
          example: 42
        sku:
          type: string
          description: 'SKU used to match to an existing listing (also a listing''s unique Id)

            '
          example: SuperSKU
        price:
          type: number
          description: Listing price
          example: 70
        quantity:
          type: integer
          description: Stock available
          example: 10
        buybox:
          type: boolean
          description: Does this listing have Backbox
          example: false
        price_for_buybox:
          type: number
          description: If your listing does not have Backbox, the price you will have to set to have it (aka red price)
          example: 60
        currency:
          type: string
          description: Currency of the listing, it will depend on the market ("GBP" for UK for instance)
          example: EUR
        condition:
          $ref: '#/components/schemas/ProductCondition'
        same_merchant_winner:
          type: boolean
          description: Does one of your listing have Backbox
          example: false
  parameters:
    Page:
      description: The page number for pagination
      example: 2
      in: query
      name: page
      required: false
      schema:
        default: 1
        type: integer
    PageSize:
      description: The page size for pagination
      example: 20
      in: query
      name: page-size
      required: false
      schema:
        default: 10
        type: integer
        maximum: 50
  securitySchemes:
    ApiKeyAuth:
      in: header
      name: Authorization
      type: apiKey
      description: 'Token authentication is done with Basic authentication.

        Prefix the value with \"Basic\" and use the token you created in the backoffice in the Integrations option page.'
    BasicAuth:
      type: http
      scheme: basic
x-provenance:
  method: harvested
  publisher: Back Market
  source: https://api.backmarket.dev/bundled_openapi.yaml
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)