openapi: 3.2.0
info:
  version: 0.1.1
  title: Back Market - API Guidelines Buy Back 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: Buy Back
paths:
  /ws/buyback/v1/orders:
    get:
      x-tier: 2
      summary: List of BuyBack orders
      tags:
      - Buy Back
      operationId: get-ws-buyback-v1-orders
      description: 'List of paginated buyback orders.

        Caller must be an authenticated merchant.'
      security:
      - ApiKeyAuth: []
      - BasicAuth: []
      parameters:
      - $ref: '#/components/parameters/status'
      - $ref: '#/components/parameters/productId'
      - $ref: '#/components/parameters/creationDate'
      - $ref: '#/components/parameters/modificationDate'
      - $ref: '#/components/parameters/shippingDate'
      - $ref: '#/components/parameters/receivedDate'
      - $ref: '#/components/parameters/suspendedDate'
      - $ref: '#/components/parameters/paymentDate'
      - $ref: '#/components/parameters/page'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                allOf:
                - $ref: '#/components/schemas/buyback-base-paginated'
                - type: object
                  properties:
                    results:
                      type: array
                      uniqueItems: true
                      items:
                        $ref: '#/components/schemas/buyback-order'
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponseV3'
        '403':
          description: Permission denied
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponseV3'
  /ws/buyback/v1/orders/pending-reply:
    get:
      x-tier: 2
      summary: List of BuyBack orders pending reply
      tags:
      - Buy Back
      operationId: get-ws-buyback-v1-orders-pending-reply
      description: 'List of paginated BuyBack orders that are pending a reply from the refurbisher.

        Caller must be an authenticated refurbisher.'
      parameters:
      - $ref: '#/components/parameters/page'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                allOf:
                - $ref: '#/components/schemas/buyback-base-paginated'
                - type: object
                  properties:
                    results:
                      type: array
                      uniqueItems: true
                      items:
                        $ref: '#/components/schemas/buyback-order'
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponseV3'
        '403':
          description: Permission denied
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponseV3'
  /ws/buyback/v1/orders/suspend-reasons:
    get:
      x-tier: 2
      summary: List of suspend reasons
      tags:
      - Buy Back
      operationId: get-ws-buyback-v1-orders-suspend-reasons
      description: 'List of suspend reasons that could be used to put a BuyBack order in SUSPENDED state.

        Caller must be an authenticated merchant.'
      security:
      - ApiKeyAuth: []
      - BasicAuth: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                minItems: 0
                items:
                  $ref: '#/components/schemas/buyback-reason'
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponseV3'
        '403':
          description: Permission denied
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponseV3'
  /ws/buyback/v1/orders/{buybackOrderId}:
    get:
      x-tier: 2
      summary: Retrieve a BuyBack order
      tags:
      - Buy Back
      operationId: get-ws-buyback-v1-order
      description: 'Retrieve a single BuyBack order.

        Caller must be an authenticated merchant.'
      security:
      - ApiKeyAuth: []
      - BasicAuth: []
      parameters:
      - $ref: '#/components/parameters/buybackOrderId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/buyback-order'
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponseV3'
        '403':
          description: Permission denied
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponseV3'
        '404':
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponseV3'
        5XX:
          description: Internal Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponseV3'
  /ws/buyback/v1/orders/{buybackOrderId}/messages:
    get:
      x-tier: 2
      summary: List of a BuyBack order messages
      tags:
      - Buy Back
      operationId: get-ws-buyback-v1-orders-messages
      description: 'List of paginated BuyBack order messages.

        Caller must be an authenticated refurbisher, owner of the provided buyback order.'
      parameters:
      - $ref: '#/components/parameters/buybackOrderId'
      - $ref: '#/components/parameters/page'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                allOf:
                - $ref: '#/components/schemas/buyback-base-paginated'
                - type: object
                  properties:
                    results:
                      type: array
                      uniqueItems: true
                      items:
                        $ref: '#/components/schemas/buyback-message'
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponseV3'
        '403':
          description: Permission denied
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponseV3'
        '404':
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponseV3'
        5XX:
          description: Internal Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponseV3'
    post:
      x-tier: 2
      summary: Post a message on a BuyBack order
      tags:
      - Buy Back
      operationId: post-ws-buyback-v1-orders-messages
      description: 'Create BuyBack order messages.

        Caller must be an authenticated refurbisher, owner of the provided buyback order.'
      parameters:
      - $ref: '#/components/parameters/buybackOrderId'
      requestBody:
        description: A payload containing the message and supporting photos if any.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/buyback-message-payload'
        required: true
      responses:
        '201':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/buyback-message'
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponseV3'
        '403':
          description: Permission denied
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponseV3'
        '404':
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponseV3'
        '422':
          description: Unprocessable Entity
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponseV3'
        5XX:
          description: Internal Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponseV3'
  /ws/buyback/v1/orders/{buybackOrderId}/suspend:
    put:
      x-tier: 2
      summary: Suspend a BuyBack order
      tags:
      - Buy Back
      operationId: put-ws-buyback-v1-orders-suspend
      description: 'Suspend a BuyBack order with the provided reasons.

        Caller must be an authenticated refurbisher, owner of the provided buyback order.'
      parameters:
      - $ref: '#/components/parameters/buybackOrderId'
      requestBody:
        description: A list of suspend reasons identifiers to put an order in SUSPENDED state.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/buyback-order-suspension-payload'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/buyback-order'
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponseV3'
        '403':
          description: Permission denied
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponseV3'
        '404':
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponseV3'
        '422':
          description: Unprocessable Entity
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponseV3'
        5XX:
          description: Internal Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponseV3'
  /ws/buyback/v1/orders/{buybackOrderId}/validate:
    put:
      x-tier: 2
      summary: Validate BuyBack order
      tags:
      - Buy Back
      operationId: put-ws-buyback-v1-orders-validate
      description: Validate a BuyBack order by setting the state to VALIDATED. Caller must be an authenticated merchant, owner of the provided buyback order.
      parameters:
      - $ref: '#/components/parameters/buybackOrderId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/buyback-order'
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponseV3'
        '403':
          description: Permission denied
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponseV3'
        '422':
          description: Unprocessable Entity
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponseV3'
        5XX:
          description: Internal Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponseV3'
  /ws/buyback/v1/orders/{buybackOrderId}/counter-offers/reasons:
    get:
      x-tier: 3
      summary: Retrieve counter offer reasons
      tags:
      - Buy Back
      operationId: get-ws-counter-offer-reason
      description: 'Get eligible reasons counter offer reasons for a given buyback order.

        Caller must be an authenticated refurbisher, owner of the provided buyback order.'
      parameters:
      - $ref: '#/components/parameters/buybackOrderId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/buyback-counter-offer-reasons'
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponseV3'
        '403':
          description: Permission denied
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponseV3'
        '404':
          description: Order not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponseV3'
        5XX:
          description: Internal Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponseV3'
  /ws/buyback/v2/orders/{buybackOrderId}/counter-offers:
    put:
      x-tier: 2
      summary: Make a counteroffer
      tags:
      - Buy Back
      operationId: put-ws-refurbisher-counter-offer
      description: 'Make a counter offer on an order.

        Caller must be an authenticated refurbisher, owner of the provided buyback order.'
      parameters:
      - $ref: '#/components/parameters/buybackOrderId'
      requestBody:
        description: A payload containing the counter offer data.
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/buyback-counter-offer-payload'
        required: true
      responses:
        '204':
          description: No content
        '400':
          description: Invalid request payload
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponseV3'
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponseV3'
        '403':
          description: Permission denied
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponseV3'
        '404':
          description: Order id not found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponseV3'
        '422':
          description: Unprocessable request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponseV3'
        '429':
          description: Too Many Requests
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponseV3'
        5XX:
          description: Internal Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponseV3'
  /ws/buyback/v1/listings:
    get:
      x-tier: 2
      summary: List of BuyBack listings
      tags:
      - Buy Back
      operationId: get-ws-buyback-v1-listings
      description: This endpoint returns a list of buyback listings based on a set of parameters.
      security:
      - ApiKeyAuth: []
      - BasicAuth: []
      parameters:
      - name: productId
        in: query
        required: false
        description: Product ID
        example: 1f9be4c7-19e6-4ebb-a8e2-1995130339f7
        schema:
          type:
          - string
          - 'null'
          format: uuid
          title: ProductId
      - name: cursor
        in: query
        required: false
        description: Cursor for the pagination
        example: bfc3e105-7209-4da2-9c25-1dc392e8d68c
        schema:
          type:
          - string
          - 'null'
          format: uuid
          title: Cursor
      - name: pageSize
        in: query
        required: false
        description: Page size
        example: 6
        schema:
          type: integer
          maximum: 100
          default: 100
          title: Pagesize
          exclusiveMinimum: 0
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/buyback-paginated-listing-response'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemValidation'
              example:
                type: /errors/validation-error
                title: Validation error
                status: 400
                errors:
                - type: /errors/missing
                  title: Missing
                  detail: Field required
                  target: header.Bm-User-Id
            text/plain:
              schema:
                type: string
              example: Invalid HTTP request received.
          description: Bad Request
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemValidation'
              example:
                type: /errors/validation-error
                title: Validation error
                status: 422
                errors:
                - type: /errors/missing
                  title: Missing
                  detail: Field required
                  target: header.Bm-User-Id
            text/plain:
              schema:
                type: string
              example: Invalid HTTP request received.
          description: Unprocessable Entity
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: /errors//errors/internal-error
                title: Internal server error
                status: 500
                detail: An internal error happened.
                instance: https://example.org/error/condition
          description: Internal Server Error
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: /errors//errors/service-unavailable
                title: Service unavailable
                status: 503
                detail: The server was not ready to handle your request.
                instance: https://example.org/error/condition
          description: Service Unavailable
  /ws/buyback/v1/listings/{buybackListingId}:
    get:
      x-tier: 2
      summary: Retrieve a Buyback listing
      tags:
      - Buy Back
      operationId: get-ws-buyback-v1-listing
      description: This endpoint returns a single BuyBack listing based on its public id.
      security:
      - ApiKeyAuth: []
      - BasicAuth: []
      parameters:
      - $ref: '#/components/parameters/buybackListingId'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/buyback-listing'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemValidation'
              example:
                type: /errors/validation-error
                title: Validation error
                status: 400
                errors:
                - type: /errors/missing
                  title: Missing
                  detail: Field required
                  target: header.Bm-User-Id
            text/plain:
              schema:
                type: string
              example: Invalid HTTP request received.
          description: Bad Request
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemValidation'
              example:
                type: /errors/validation-error
                title: Validation error
                status: 422
                errors:
                - type: /errors/missing
                  title: Missing
                  detail: Field required
                  target: header.Bm-User-Id
            text/plain:
              schema:
                type: string
              example: Invalid HTTP request received.
          description: Unprocessable Entity
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: /errors//errors/internal-error
                title: Internal server error
                status: 500
                detail: An internal error happened.
                instance: https://example.org/error/condition
          description: Internal Server Error
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: /errors//errors/service-unavailable
                title: Service unavailable
                status: 503
                detail: The server was not ready to handle your request.
                instance: https://example.org/error/condition
          description: Service Unavailable
    put:
      x-tier: 2
      summary: Update a Buyback listing
      tags:
      - Buy Back
      operationId: put-ws-buyback-v1-listing
      description: 'This endpoint updates a single BuyBack listing based on its public id. Only price updates are supported as of now.

        Note that, if you want to deactivate a buyback listing, you can simply update the listing price to zero (0) :

        It will automatically turn the listing offline.'
      security:
      - ApiKeyAuth: []
      - BasicAuth: []
      parameters:
      - $ref: '#/components/parameters/buybackListingId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                prices:
                  type: object
                  additionalProperties:
                    $ref: '#/components/schemas/Price'
              title: Payload
              example:
                prices:
                  FR:
                    amount: '34.50'
                    currency: EUR
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                example: {}
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemValidation'
              example:
                type: /errors/validation-error
                title: Validation error
                status: 400
                errors:
                - type: /errors/missing
                  title: Missing
                  detail: Field required
                  target: header.Bm-User-Id
            text/plain:
              schema:
                type: string
              example: Invalid HTTP request received.
          description: Bad Request
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemValidation'
              example:
                type: /errors/validation-error
                title: Validation error
                status: 422
                errors:
                - type: /errors/missing
                  title: Missing
                  detail: Field required
                  target: header.Bm-User-Id
            text/plain:
              schema:
                type: string
              example: Invalid HTTP request received.
          description: Unprocessable Entity
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: /errors//errors/internal-error
                title: Internal server error
                status: 500
                detail: An internal error happened.
                instance: https://example.org/error/condition
          description: Internal Server Error
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: /errors//errors/service-unavailable
                title: Service unavailable
                status: 503
                detail: The server was not ready to handle your request.
                instance: https://example.org/error/condition
          description: Service Unavailable
  /ws/buyback/v1/competitors/{listingId}:
    get:
      description: Get the buyback Backbox data related to your competitors, i.e. your online listings competing in a Backbox.
      parameters:
      - in: path
        name: listingId
        required: true
        schema:
          format: uuid
          title: Buyback listing Id
          type: string
        example: 7e1f4a8d-b1bb-47aa-9f77-2cca759eb41b
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/buybackCompetitor'
                type: array
                description: Each item is a competitor, ie. a `listing x market`, competing for a single buyback Backbox.
          description: Successful Response
        '401':
          description: Unauthorized
        '404':
          description: Not Found
        '422':
          description: Unprocessable Entity
      security:
      - ApiKeyAuth: []
      - BasicAuth: []
      summary: Get buyback competitors
      tags:
      - Buy Back
      x-category: domain
      x-tier: 2
      operationId: getWsBuybackV1CompetitorsByListingId
      x-operation-id-source: derived
components:
  schemas:
    buyback-listing:
      description: Buyback listing
      type: object
      title: Buyback listing
      properties:
        id:
          type: string
          format: uuid
          title: Id
          example: d80340a5-6460-4a9c-a8a6-c1c6d56b11c7
        productId:
          type: string
          format: uuid
          title: Productid
          example: 263b4873-3b6b-413e-815e-c3451117893c
        prices:
          type: object
          title: Prices
          additionalProperties:
            $ref: '#/components/schemas/Price'
          example:
            FR:
              amount: '34.50'
              currency: EUR
        aestheticGradeCode:
          $ref: '#/components/schemas/buyback-aesthetic-grade-code'
        sku:
          type:
          - string
          - 'null'
          title: Sku
          description: SKU defined by the seller. In case of a trade-in listing, it can be null.
          example: seller-sku
        markets:
          items:
            type: string
            pattern: ^[A-Z]{2}$
            description: 'List of markets in which the listing is online. Market Code MUST be represented as a two-letter code following the ISO 3166-1 alpha-2 standard: "FR" for France, "GB" for Great Britain, etc.'
            example: FR
          type: array
          title: Markets
      required:
      - id
      - productId
      - prices
      - aestheticGradeCode
      - sku
      - markets
    buybackCounterOfferReasonCategory:
      type: string
      description: identifier of the counter offer reason category
      enum:
      - functional
      - esthetics
      - other
      example: functional
    ProblemValidation:
      title: ProblemValidation
      type: object
      allOf:
      - $ref: '#/components/schemas/Problem'
      - type: object
        properties:
          errors:
            type: array
            items:
              $ref: '#/components/schemas/ProblemValidationErrorMember'
      example:
        type: /errors/bad-request
        title: Your request parameters didn't validate.
        instance: /user/signup
        status: 400
        errors:
        - type: /errors/validation-error
          title: Email conflict error
          detail: This email is already taken
          target: email
          context:
            suggestedEmails:
            - john.doe.123@gmail.com
            - john.doe.456@gmail.com
            ageLimit: 18
        - type: /errors/validation-error
          title: Password not accepted
          detail: Password is not accepted due to reason....
          target: password
          context:
            minimumTotal: 8
            minimumNumber: 2
            minimumUppercase: 3
            minimumSpecialCharacter: 2
      description: ''
      x-internal: false
    buyback-paginated-listing-response:
      title: BuyBack paginated listing response
      type: object
      properties:
        next:
          type:
          - string
          - 'null'
          title: Next page
          example: https://www.backmarket.fr/ws/buyback/v1/listings?cursor=87eeccf7-7b1a-4897-8f71-09899b337a97
        results:
          items:
            $ref: '#/components/schemas/buyback-listing'
          type: array
          title: Results
      required:
      - next
      - results
    buyback-order:
      description: Buyback order sent back by 'ws/buyback/' endpoints
      type: object
      properties:
        orderPublicId:
          type: string
          description: buyback order public identifier
          example: US-24527-ABCDE
        creationDate:
          type: string
          description: Buyback Order creation date
          example: '2019-03-21T14:28:30+01:00'
        modificationDate:
          type: string
          description: Buyback Order last modification date
          example: '2019-03-26T08:00:53+01:00'
        shippingDate:
          type: string
          description: Buyback Order shipping date
          example: '2019-03-21T14:37:54+01:00'
        suspensionDate:
          type: string
          description: Buyback Order suspension date
          example: '2019-03-21T14:37:54+01:00'
        receivalDate:
          type: string
          description: Buyback Order reception date
          example: '2019-03-21T14:37:54+01:00'
        paymentDate:
          type: string
          description: Buyback Order payment date
          example: '2019-03-21T14:38:11+01:00'
        counterProposalDate:
          type: string
          description: Last counter proposal date
          example: '2019-03-21T14:37:54+01:00'
        status:
          $ref: '#/components/schemas/buybackOrderState'
        market:
          type: string
          description: Idenfitication code of the market in which the buyback order was placed
          example: FR
        transferCertificateLink:
          type: string
          description: URL where the transfer certificate can be downloaded
          example: https://tranfer-certificate.com
        listing:
          type: object
          required:
          - productId
          - title
          - grade
          properties:
            sku:
              type: string
              example: '21000021'
              description: (Stock-keeping unit) Identification number of the product
            productId:
              type: number
              example: 2311
              description: Identification number of the product bought back by the merchant
            title:
              type: string
              description: Name of the product bought back by the merchant
              example: Apple iPhone XS 64 Go
            grade:
              $ref: '#/components/schemas/buybackListingGrade'
        customer:
          type: object
          properties:
            firstName:
              type: string
              description: First name of the customer who wants to sell a device
              example: John
            lastName:
              type: string
              description: Last name of the customer who wants to sell a device
              example: Doe
            phone:
              type: string
              description: Phone number of the customer
              example: '+33699887766'
            dateOfBirth:
              type: string
              description: Birthdate of the customer
              example: '1970-03-21'
            documents:
              type: array
              items:
                type: object
                properties:
                  type:
                    $ref: '#/components/schemas/buybackKycDocuments'
                  url:
                    type: string
                    description: URL where the document can be downloaded
                    example: https://bucket.com/user_document/passport.jpeg
                required:
                - type
                - url
        returnAddress:
          type: object
          description: Address where the parcel can be returned
          required:
          - country
          properties:
            address1:
              type: string
              description: Main address description
              example: 10, Downing street
            address2:
              type: string
              example: 3rd floor
              description: Details on the address
            city:
              type: string
              example: London
              description: City of the address
            zipcode:
              type: string
              example: '93100'
              description: Zipcode of the address
            country:
              type: string
              example: United Kingdom
              description: Country of the address
        originalPrice:
          type: object
          description: Initial offer price
          required:
          - value
          - currency
          properties:
            value:
              type: number
              description: Initial offer amount
              example: 1000
            currency:
              type: string
              description: Initial price currency
              example: EUR
        counterOfferPrice:
          type: object
          description: Counter offer price set by the merchant
          properties:
            value:
              type: number
              description: Amount set by the merchant
              example: 900
            currency:
              type: string
              description: Currency of the counter offer price set by the merchant
              example: EUR
          required:
          - value
          - currency
        trackingNumber:
          type: string
          description: Tracking number of the parcel
          example: 8R41352499203
        shipper:
          type: string
          description: Shipper of the parcel
          example: DHL
        suspendReasons:
          type: array
          description: List of reasons set by the merchant when putting the buyback order on hold
          items:
            $ref: '#/components/schemas/buyback-reason'
        counterOfferReasons:
          type: array
          description: List of reasons set by the merchant when making a counter offer on the buyback order
          items:
            $ref: '#/components/schemas/buyback-reason'
      required:
      - orderPublicId
      - creationDate
      - modificationDate
      - shippingDate
      - status
      - market
      - listing
      - customer
      - returnAddress
      - originalPrice
      - transferCertificateLink
    buyback-aesthetic-grade-code:
      title: Buyback aesthetic grade code
      type: string
      example: FUNCTIONAL_FLAWLESS
      enum:
      - FUNCTIONAL_FLAWLESS
      - FUNCTIONAL_GOOD
      - FUNCTIONAL_USED
      - FUNCTIONAL_CRACKED
      - NOT_FUNCTIONAL_USED
      - NOT_FUNCTIONAL_CRACKED
    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
    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
    Price:
      title: Price
      description: Back Market common Price model
      oneOf:
      - $ref: '#/components/schemas/MonetaryAmount'
      x-internal: false
    buybackOrderState:
      type: string
      description: Buyback order state
      enum:
      - NEW
      - PENDING
      - TO_SEND
      - SENT
      - RECEIVED
      - COUNTER_PROPOSAL
      - VALIDATED
      - PAID
      - MONEY_TRANSFERED
      - SUSPENDED
      example: TO_SEND
    buyback-counter-offer-reasons:
      type: array
      description: List of eligible counter offer reasons for a given buyback order
      items:
        type: object
        properties:
          id:
            $ref: '#/components/schemas/buybackCounterOfferReasonCategory'
          label:
            type: string
            example: Aesthetics
            description: Translated description of the category of counteroffer reasons
          reasons:
            type: array
            description: possible counter offer reasons
            items:
              type: object
              properties:
                id:
                  type: string
                  description: Identifier of the counter offer reason to be declared, this identifier should be sent
                  example: broken_screen
                label:
                  type: string
                  description: Translated description of the counter offer
                  example: Broken screen
            required:
            - id
            - label
        required:
        - id
        - label
        - reasons
    buybackMessageAuthor:
      type: string
      description: Message author
      enum:
      - Merchant
      - Client
      - BackMarket
      - Unknown
      example: Merchant
    buyback-message:
      description: Buyback order message sent back by 'ws/buyback/' endpoints
      type: object
      properties:
        body:
          type: string
          description: Message content
          example: Hello world!
        date:
          type: string
          description: Message creation date
          example: '2019-04-04T14:10:00+02:00'
        attachments:
          type: array
          items:
            type: string
            description: Url of the attachments
            example: https://storage-server/sourcing_pj/my_attachement.txt
        author:
          $ref: '#/components/schemas/buybackMessageAuthor'
      required:
      - date
      - author
    Problem:
      title: Problem Details for HTTP APIs
      description: Definition of [RFC7807](https://tools.ietf.org/html/rfc7807) problem detail
      type: object
      properties:
        type:
          type: string
          description: 'Unique problem identifier.

            The RFC says that it should be an URI but we prefere not to use that as it''s not scalable and user friendly.

            Only readable format are accepted follwoing this pattern "[a-z-/]*", eg (`/errors/authorization-failed`).

            '
          default: /errors/unknown
          example: /errors/authorization-failed
        title:
          type: string
          description: 'A short, human-readable summary of the problem type.

            It should not change from occurrence to occurrence of the problem except for purposes of localization.

            '
          example: Unable to process payment
        status:
          type: integer
          format: int32
          description: 'The HTTP status code generated by the origin server for this occurrence

            of the problem.

            '
          minimum: 100
          maximum: 599
          example: 503
        detail:
          type: string
          description: 'A human readable explanation specific to this occurrence of the

            problem.

            '
          example: Payment authorization failed because your card is expired
        instance:
          type: string
          description: 'An absolute URI that identifies the specific occurrence of the problem.

            It may or may not yield further information if dereferenced.

            '
          example: https://example.org/error/condition
      required:
      - type
      - title
      - status
      x-internal: false
    ValidationErrorResponseV3:
      type: object
      allOf:
      - $ref: '#/components/schemas/ErrorResponseV3'
      - type: object
        properties:
          errors:
            type: array
            items:
              type: object
              properties:
                type:
                  type: string
                  minLength: 1
                  example: /errors/email-conflict
                title:
                  type: string
                  minLength: 1
                  example: Email conflict error
                detail:
                  type: string
                  minLength: 1
                  example: This email is already taken
                target:
                  type: string
                  minLength: 1
                  example: email
                context:
                  type: object
                  example: {}
              required:
              - type
              - title
              - target
    buybackListingGrade:
      type: string
      description: Quality grade of the buyback order
      enum:
      - DIAMOND
      - PLATINUM
      - GOLD
      - SILVER
      - BRONZE
      - STALLONE
      example: DIAMOND
    buyback-message-payload:
      type: object
      properties:
        message:
          type: string
          minLength: 1
          description: Counter offer explanation message
          example: Scratched screen
        files:
          type: array
          uniqueItems: true
          description: Photos supporting the message. If there is no photo, an empty array should be passed.
          items:
            type: object
            properties:
              name:
                type: string
                minLength: 1
                description: Name of the photo
                example: photo_1.jpg
              content:
                type: string
                minLength: 1
                description: Content of the photo
                example: binary-content
            required:
            - name
            - content
      required:
      - files
      - message
    buyback-order-suspension-payload:
      type: object
      properties:
        reasons:
          type: array
          description: List of suspension reasons identifiers
          example:
          - parcel_damaged
          - broken_device
          items:
            type: string
            example: parcel_damaged
      required:
      - reasons
    buybackKycDocuments:
      type: string
      description: Type of the KYC document
      enum:
      - PASSPORT
      - ID
      - ID_CARD_FRONT
      - ID_CARD_BACK
      - BANK_STATEMENT
      - DRIVING_LICENCE_FRONT
      - DRIVING_LICENCE_BACK
      example: PASSPORT
    buybackCompetitor:
      properties:
        listing_id:
          description: The listing public id of this competitor.
          format: uuid
          title: Listing Id
          type: string
        product_id:
          description: The product public id of this competitor.
          format: uuid
          title: Product Id
          type: string
        market:
          anyOf:
          - $ref: '#/components/schemas/MarketCode'
          description: Two-letter country code of the market. Format ISO_3166-2.
        price:
          allOf:
          - $ref: '#/components/schemas/MonetaryAmount'
          description: The buyback price set for this competitor.
        price_to_win:
          allOf:
          - $ref: '#/components/schemas/MonetaryAmount'
          description: The price that the competitor must set to win the buyback backbox.
        is_winning:
          description: Whether or not this competitor is winning the buyback backbox.
          title: Is Winning
          type: boolean
      required:
      - listing_id
      - product_id
      - market
      - price_to_win
      - winner_price
      - is_winning
      title: BuybackCompetitor
      type: object
    buyback-reason:
      title: Suspend or counter offer reason
      description: Reason used to suspend a buyback order or make a counter offer on it
      type: object
      properties:
        message:
          type: string
          description: Details of the reason
          example: Empty parcel
        identifier:
          type: string
          description: Identifier of the reason
          example: parcel_empty
        category:
          type: string
          description: Category of the reason
          example: Transport issue
      required:
      - message
      - identifier
    Error:
      description: ''
      properties:
        code:
          type: string
        data:
          type: object
        docLink:
          type: string
        message:
          type: string
        target:
          type: string
      required:
      - code
      - message
      type: object
    ProblemValidationErrorMember:
      description: ''
      type: object
      example:
        type: /errors/email-conflict
        title: Email conflict error
        detail: This email is already taken
        target: email
        context:
          suggestedEmails:
          - john.doe.123@gmail.com
          - john.doe.456@gmail.com
          ageLimit: 18
      properties:
        type:
          type: string
          minLength: 1
          example: /errors/email-conflict
        title:
          type: string
          minLength: 1
          example: Email conflict error
        detail:
          type: string
          minLength: 1
          example: This email is already taken
        target:
          type: string
          minLength: 1
          example: email
        context:
          type: object
          example: {}
      required:
      - type
      - title
      - target
      x-internal: false
    buyback-base-paginated:
      title: base_paginated
      type: object
      properties:
        count:
          type: number
          description: Total number of objects or items
          example: 133
        next:
          type:
          - string
          - 'null'
          description: URL pointing to the next page
          example: https://www.backmarket.fr/ws/buyback/v1/orders?page=3
        previous:
          type:
          - string
          - 'null'
          description: URL pointing to the previous page
          example: https://www.backmarket.fr/ws/buyback/v1/orders?page=1
      required:
      - count
      - next
      - previous
    buyback-counter-offer-payload:
      type: object
      properties:
        price:
          type: number
          description: counteroffer price
        comment:
          type:
          - string
          - 'null'
          maxLength: 200
          description: Counteroffer explanation message
          example: The screen is too scratched.
        reasons:
          type: array
          description: List of counteroffer reasons identifiers. Must come from the /counter-offers/reasons endpoint.
          items:
            type: string
            example: parcel_damaged
        files:
          type: array
          uniqueItems: true
          description: Files that prove the counteroffer is legitimate (.jp(e)g, .png, .pdf)
          items:
            type: string
            format: binary
      required:
      - price
      - reasons
      - files
    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
  parameters:
    paymentDate:
      schema:
        type: string
        format: datetime
      in: query
      name: paymentDate
      description: BuyBack order minimum payment date
      example: '2020-12-02'
    creationDate:
      schema:
        type: string
        format: datetime
      in: query
      name: creationDate
      description: BuyBack order minimum creation date
      example: '2020-12-02'
    receivedDate:
      schema:
        type: string
        format: datetime
      in: query
      name: receivedDate
      description: BuyBack order minimum received date
      example: '2020-12-02'
    status:
      schema:
        $ref: '#/components/schemas/buybackOrderState'
      in: query
      name: status
      description: Buyback Order status
      example: PAID
    buybackOrderId:
      schema:
        type: string
      example: US-24527-ABCDE
      name: buybackOrderId
      in: path
      description: BuyBack order id
      required: true
    modificationDate:
      schema:
        type: string
        format: datetime
      in: query
      name: modificationDate
      description: BuyBack order minimum modification date
      example: '2020-12-02'
    productId:
      schema:
        type: integer
      in: query
      name: productId
      description: BuyBack product ID
      example: 123
    buybackListingId:
      schema:
        type: string
        format: uuid
      example: 3b99e96d-9db7-480f-a32f-2e05edbff30c
      name: buybackListingId
      in: path
      description: BuyBack listing id
      required: true
    page:
      schema:
        type: integer
      in: query
      name: page
      example: 1
      description: Page number
    suspendedDate:
      schema:
        type: string
        format: datetime
      in: query
      name: suspendedDate
      description: BuyBack order minimum suspended date
      example: '2020-12-02'
    shippingDate:
      schema:
        type: string
        format: datetime
      in: query
      name: shippingDate
      description: BuyBack order minimum shipping date
      example: '2020-12-02'
  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