openapi: 3.0.3
x-stoplight:
  id: 89icnughyrxhn
info:
  title: Storefront API
  description: >
    REVER's Storefront Returns API is the solution to building your custom made
    returns storefront while leveraging the power of REVER's returns engine.


    **Quick Integration**

    - RESTful architecture

    - OpenAPI specification with ready-to-use examples and client library
    generation


    **Features**

    - Return initiation and validation

    - Smart exchange recommendations

    - Multiple refund options (store credit, bank transfer, gift cards)

    - Automated return logistics

    - Tracking and status updates

    - Risk Assesment


    **Technical Highlights**

    - REST-based API with JSON payloads

    - Secure authentication via API keys

    - Sandbox environment for testing

    - Rate limiting with generous quotas


    Get started quickly with our step-by-step integration guide. Our support
    team is ready to help you at every step of your integration journey.

     ## Authentication
    The REVER Admin API uses API key authentication.


    ### Authenticating via API Key

    This authentication method is primarily

    used for server-to-server (unattended) integrations. You must request an API
    key

    through your account manager.\n**The API key must be kept secure and
    confidential**, do not share

    it with anyone.



    To authenticate a request using an API key, include the header

    **x-rever-api-key**. Example: `x-rever-api-key: 87bf223499abeef`
  contact:
    name: REVER
    url: https://itsrever.com
    email: developer@itsrever.com
  version: 1.0.0
tags:
  - name: Return Request
    description: Returns are a way to return items to the store.
  - name: Exchange Options
    description: >-
      Exchange options are the steps when the user decides to return an item.
      The first step is to get the available exchange options and try to get the
      best exchange option for the user.
  - name: Return Reasons
    description: >-
      Return reasons are the reasons why the user wants to return an item
      available for the ecommerce.
  - name: Refund Options
    description: >-
      Refund options are a way to refund items. A refund is not an exchange, the
      available refund options are BANK_TRANSFER, STORE_CREDIT, GIFT_CARD,
      ORIGINAL_PAYMENT_METHOD.
  - name: Return Options
    description: Return options are a way to return items to the store.
  - name: Return Checkout
    description: >-
      Checkout is the final step when the user decides to return an item. The
      user will be redirected to the checkout page to complete the return.
  - name: Tracking and Status
    description: Tracking and status are a way to track and status of a return.
paths:
  /returns:
    get:
      summary: Get active returns
      description: Get all active returns for a user
      tags:
        - Return Request
      parameters:
        - name: order_ids
          in: query
          required: true
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  returns:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        status:
                          type: string
                        created_at:
                          type: string
                        updated_at:
                          type: string
                        order_id:
                          type: string
                        order_number:
                          type: string
                        order_date:
                          type: string
                        line_items:
                          type: array
                          items:
                            type: object
                            properties:
                              id:
                                type: string
                              name:
                                type: string
                              product_id:
                                type: string
                              variant_id:
                                type: string
                              quantity:
                                type: integer
  /returns/intent/start:
    post:
      operationId: StartReturnIntent
      summary: Start a return intent for a user
      description: Start a return intent for a user
      tags:
        - Return Request
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                order_number:
                  type: string
      responses:
        '200':
          description: Order details to show in the portal
          content:
            application/json:
              schema:
                type: object
                properties:
                  order:
                    type: object
                    properties:
                      id:
                        type: string
                      currency:
                        type: string
                      line_items:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                            name:
                              type: string
                            variant_name:
                              type: string
                            quantity:
                              type: integer
                            quantity_in_progress:
                              type: integer
                            quantity_returned:
                              type: integer
                            quantity_not_returnable:
                              type: integer
                            available_return_reasons:
                              type: array
                              items:
                                type: object
                                properties:
                                  id:
                                    type: string
                                    description: The ID of the return reason
                                    default: TOO_SMALL
                            total:
                              type: integer
                            product:
                              type: object
                              properties:
                                id:
                                  type: string
                                images:
                                  type: array
                                  items:
                                    type: object
                                    properties:
                                      src:
                                        type: string
                                      alt:
                                        type: string
                      return_id:
                        type: string
                        description: The ID of the return process to be started
                      customer_token:
                        type: string
                        description: The token of the customer
  /returns/{return_id}/items/{line_item_id}/exchange_options:
    get:
      tags:
        - Exchange Options
      summary: Get available exchange options
      description: >-
        Retrieves available exchange options based on return reason, product
        category, stock levels, and country.
      parameters:
        - name: return_id
          in: path
          required: true
          schema:
            type: string
        - name: line_item_id
          in: path
          required: true
          schema:
            type: string
        - name: return_reason
          in: query
          required: false
          schema:
            type: string
        - name: country
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: List of exchange options
          content:
            application/json:
              schema:
                type: object
                properties:
                  exchange_options:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        exchange_type:
                          type: string
                          enum:
                            - OPEN_CATALOG
                            - SIZE_EXCHANGE
                            - COLOR_EXCHANGE
                            - NO_EXCHANGE
                        exchange_reason:
                          type: string
      x-stoplight:
        id: 6d8evvs1dz44b
  /returns/{return_id}/exchange_incentive:
    description: Get incentives for exchange
    get:
      summary: Get incentives for exchange
      tags:
        - Exchange Options
      description: Retrieves extra amounts and preferred exchange types.
      parameters:
        - name: return_id
          in: path
          required: true
          schema:
            type: string
        - name: line_item_id
          in: query
          required: true
          schema:
            type: string
        - name: return_reason
          in: query
          required: true
          schema:
            type: string
        - name: order_id
          in: query
          required: true
          schema:
            type: string
        - name: exchange_country
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Incentive details for exchange
          content:
            application/json:
              schema:
                type: object
                properties:
                  incentives:
                    type: array
                    items:
                      type: object
                      properties:
                        extra_credit:
                          type: integer
                          description: The extra credit amount for exchange
                        preferred_exchange_type:
                          type: string
                          description: The preferred exchange type for exchange
                          enum:
                            - OPEN_CATALOG
                            - SIZE_EXCHANGE
      x-stoplight:
        id: 34ctesk7nee34
  /returns/{return_id}/items/{line_item_id}/recommended_products:
    get:
      summary: Get recommended products for an item
      description: Retrieves recommended products for a specific line item.
      tags:
        - Exchange Options
      x-stoplight:
        id: 1i7x396gt7d3z
      parameters:
        - name: return_id
          in: path
          required: true
          schema:
            type: string
        - name: line_item_id
          in: path
          required: true
          schema:
            type: string
        - name: page
          in: query
          required: false
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 10
        - name: text_search
          in: query
          required: false
          schema:
            type: string
            default: ''
      responses:
        '200':
          description: List of recommended products
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                    name:
                      type: string
                    image:
                      type: string
                    variants:
                      type: array
                      items:
                        type: object
                        properties:
                          id:
                            type: string
                          available_for_sale:
                            type: boolean
                          sku:
                            type: string
                          title:
                            type: string
                          total_price:
                            type: integer
                          currency:
                            type: string
                          price_after_return_discount:
                            type: integer
                          options:
                            type: array
                            items:
                              type: object
                              properties:
                                id:
                                  type: string
                                name:
                                  type: string
  /v1/public/configs/return-reasons/find:
    get:
      tags:
        - Return Reasons
      x-stoplight:
        id: 1i7x396gt7d3z
      summary: Get Return Reasons
      description: >-
        Fetches the list of available return reasons for a given ecommerce
        store. This is the first step in the return process.
      operationId: GetReturnReasons
      parameters:
        - name: ecommerce_id
          in: query
          description: ID of the ecommerce store.
          required: true
          schema:
            type: string
            example: acme
      responses:
        '200':
          description: A list of available return reasons.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    parent_reason:
                      type: object
                      properties:
                        name:
                          type: string
                          description: The identifier for the return reason.
              example:
                - parent_reason:
                    name: NOT_AS_EXPECTED
                - parent_reason:
                    name: TOO_BIG
  /returns/{return_id}/items/refund_options:
    get:
      summary: Get refund options
      description: Retrieves refund options for a specific line item.
      tags:
        - Refund Options
      x-stoplight:
        id: 1i7x396gt7d3z
      parameters:
        - name: return_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: List of refund options
          content:
            application/json:
              schema:
                type: object
                properties:
                  refund_options:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: The ID of the refund option
                          enum:
                            - BANK_TRANSFER
                            - STORE_CREDIT
                            - GIFT_CARD
                            - ORIGINAL_PAYMENT_METHOD
                        timing:
                          type: string
                          description: The timing of the refund
                          enum:
                            - ON_START
                            - ON_ITEM_VERIFIED
                            - ON_RETURN_COMPLETED
  /returns/{return_id}/giftcard_incentive/:
    get:
      summary: Get gift card incentive
      description: Retrieves gift card incentive for a specific return.
      tags:
        - Refund Options
      parameters:
        - name: return_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Gift card incentive details
          content:
            application/json:
              schema:
                type: object
                properties:
                  incentive:
                    type: integer
                    description: The gift card incentive amount
  /returns/{return_id}/refund_options/return_fees:
    get:
      summary: Get return fees
      description: Retrieves return fees for a specific return.
      tags:
        - Return Options
      parameters:
        - name: return_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Return fees details
          content:
            application/json:
              schema:
                type: object
                properties:
                  fees:
                    type: array
                    items:
                      type: object
                      description: >-
                        To get available return reasons, call GET
                        /v1/public/configs/return-reasons/find
                      properties:
                        estimated_fee:
                          type: integer
                        currency:
                          type: string
                        fee_type:
                          type: string
                          enum:
                            - RETURN_FEE
                            - SHIPPING_FEE
                            - RESTOCK_FEE
  /returns/{return_id}/refund_options/timings:
    get:
      summary: Get refund timings
      description: Retrieves refund timings for a specific return.
      tags:
        - Return Options
      parameters:
        - name: return_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Refund timings details
          content:
            application/json:
              schema:
                type: object
                properties:
                  timings:
                    type: array
                    items:
                      type: object
                      properties:
                        timing:
                          type: string
                          enum:
                            - ON_START
                            - ON_ITEM_VERIFIED
                            - ON_RETURN_COMPLETED
                        refund_option:
                          type: string
                          enum:
                            - BANK_TRANSFER
                            - STORE_CREDIT
                            - GIFT_CARD
                            - ORIGINAL_PAYMENT_METHOD
  /returns/{return_id}/return_options/:
    get:
      summary: Get available return options
      description: >-
        Retrieve available return options based on return ID. Country, user
        info, and product weights are inferred from the return ID.
      tags:
        - Return Options
      parameters:
        - name: return_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  country:
                    type: string
                    example: ES
                  weights:
                    type: number
                    example: 2.5
                  return_options:
                    type: array
                    items:
                      type: object
                      properties:
                        method:
                          type: string
                          enum:
                            - HOME_PICKUP
                            - DROP_OFF
                            - IN_STORE
                          example: DROP_OFF
                        carrier:
                          type: string
                          example: UPS
                        dropoff_link:
                          type: string
                          nullable: true
                          example: https://dropoff.example.com
                        dropoff_locations:
                          type: array
                          nullable: true
                          items:
                            type: object
                            properties:
                              latitude:
                                type: number
                                example: 40.4168
                              longitude:
                                type: number
                                example: -3.7038
                        pickup_ranges:
                          type: array
                          nullable: true
                          items:
                            type: string
                          example:
                            - '2025-03-06T08:00:00+01:00'
                            - '2025-03-06T12:00:00+01:00'
                        in_store_locations:
                          type: array
                          nullable: true
                          items:
                            type: string
        '400':
          description: Invalid request
        '404':
          description: Return not found
        '422':
          description: No available return methods
  /returns/{return_id}/return_stores/:
    get:
      summary: Get closest available store for return
      description: >-
        Check if in-store return is available for the given return ID and
        provide the closest store location.
      tags:
        - Return Options
      parameters:
        - name: return_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  closest_store:
                    type: object
                    properties:
                      name:
                        type: string
                        example: Bershka Madrid Gran Via
                      address:
                        type: string
                        example: Gran Via 32, 28013 Madrid, Spain
                      latitude:
                        type: number
                        example: 40.42
                      longitude:
                        type: number
                        example: -3.7058
        '400':
          description: Invalid request
        '404':
          description: Return not found
        '422':
          description: No available in-store return locations
  /returns/{return_id}/return_options/return_fees:
    post:
      summary: Calculate logistics fees
      description: Get details on return fees based on the selected return method.
      tags:
        - Return Options
      parameters:
        - name: return_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                return_method:
                  type: string
                  enum:
                    - HOME_PICKUP
                    - DROP_OFF
                    - IN_STORE
                  example: DROP_OFF
                weight:
                  type: number
                  example: 2.5
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  fee:
                    type: integer
                    example: 200
                  currency:
                    type: string
                    example: EUR
        '400':
          description: Invalid request
        '404':
          description: Return not found
  /returns/{return_id}/save_client_preferences:
    post:
      summary: Add an item to a return
      description: Add an item to a return
      tags:
        - Return Request
      parameters:
        - name: return_id
          in: path
          required: true
          schema:
            type: string
        - name: line_item_id
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  return_id:
                    type: string
                  pending_credit_to_use:
                    type: integer
                    example: 200
                  currency:
                    type: string
                    example: EUR
        '400':
          description: Invalid request
        '404':
          description: Return not found
  /returns/{return_id}/checkout:
    post:
      summary: Calculates the finantial information before completing the return
      description: >-
        Checkout a return, this will calculate all finantial data before
        completing the return
      tags:
        - Return Checkout
      parameters:
        - name: return_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  return_id:
                    type: string
                  returned_items:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        name:
                          type: string
                        image:
                          type: string
                        return_reason:
                          type: string
                        quantity_returned:
                          type: integer
                        compensation:
                          type: object
                          properties:
                            original_payment_method:
                              type: object
                              properties:
                                amount:
                                  type: integer
                                currency:
                                  type: string
                            store_credit:
                              type: object
                              properties:
                                amount:
                                  type: integer
                                currency:
                                  type: string
                            bank_transfer:
                              type: object
                              properties:
                                amount:
                                  type: integer
                                currency:
                                  type: string
                            new_items_to_ship:
                              type: array
                              items:
                                type: object
                                properties:
                                  id:
                                    type: string
                                  name:
                                    type: string
                                  image:
                                    type: string
                  costs:
                    type: object
                    properties:
                      total:
                        type: integer
                        example: 200
                      fee_type:
                        type: string
                        enum:
                          - RETURN_FEE
                          - SHIPPING_FEE
                          - RESTOCK_FEE
                        example: RETURN_FEE
                      currency:
                        type: string
                        example: EUR
                  subtotal:
                    type: integer
                    example: 200
                  total:
                    type: integer
                    example: 200
        '400':
          description: Invalid request
  /returns/{return_id}/complete:
    post:
      summary: Complete a return
      description: Complete a return
      tags:
        - Return Checkout
      parameters:
        - name: return_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
  /returns/{return_id}/:
    get:
      summary: Get a return
      description: Get a return
      tags:
        - Tracking and Status
      parameters:
        - name: return_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  return_id:
                    type: string
                  status:
                    type: string
                    enum:
                      - IN_PROGRESS
                      - COMPLETED
                      - CANCELLED
                    example: IN_PROGRESS
                  logistics_info:
                    type: object
                    properties:
                      return_method:
                        type: string
                        enum:
                          - HOME_PICKUP
                          - DROP_OFF
                          - IN_STORE
                        example: DROP_OFF
                      tracking_number:
                        type: string
                        example: '1234567890'
                      carrier:
                        type: string
                        example: UPS
                      shipping_status:
                        type: string
                        enum:
                          - PENDING
                          - SHIPPED
                          - DELIVERED
                          - CANCELLED
                        example: PENDING
                      shipping_cost:
                        type: integer
                        example: 200
                  compensations_info:
                    type: object
                    properties:
                      compensations:
                        type: array
                        items:
                          type: object
                          properties:
                            type:
                              type: string
                              enum:
                                - STORE_CREDIT
                                - BANK_TRANSFER
                                - GIFT_CARD
                                - EXCHANGE
                            status:
                              type: string
                              enum:
                                - PENDING
                                - COMPLETED
                                - CANCELLED
                            amount:
                              type: integer
                            currency:
                              type: string
components:
  securitySchemes:
    X-REVER-API-KEY:
      type: apiKey
      in: query
      name: X-REVER-API-KEY
