openapi: 3.0.2
servers:
  - description: Development Server
    url: https://api.dev.ifreturns.com/integration/v1
  - description: Staging Server
    url: https://api.stg.ifreturns.com/integration/v1
  - description: Production Server
    url: https://api.ifreturns.com/integration/v1
info:
  description: API to allow the integration with merchants
  version: 1.4.2
  title: iF returns - Logistic API
  contact:
    email: dev@ifreturns.com
tags:
  - name: iFreturns REST API
    description: integration with merchants
paths:
  /returns:
    get:
      operationId: getReturns
      tags:
        - Returns
      summary: List all return requests
      description: >-
        Allows to get the list of return requested through the iF returns
        channels (e.g. returns portal). Each return request contains the list of
        returned items, origin address, and associated transport data. In case
        any parameter is sent, the last 100 returns created will be returned
      parameters:
        - in: query
          name: shop_code
          description: >-
            iF returns code assigned to the merchant. In case this parameter is
            not sent, the shop codes associated to the token will be used
          required: false
          schema:
            type: string
            example: marchelacolombine
        - in: query
          name: name
          description: Request merchant authorization (RMA) name
          required: false
          schema:
            type: string
            example: R1-2944
        - in: query
          name: status
          description: Status of the return
          required: false
          schema:
            $ref: '#/components/schemas/ReturnStatus'
        - in: query
          name: ecommerce_order
          description: Ecommerce order from where the return was requested
          required: false
          schema:
            type: string
            example: '2944'
        - in: query
          name: created_from
          description: Date from which the returns will be searched by creation date
          required: false
          schema:
            type: string
            example: '2023-04-01T12:00:00'
        - in: query
          name: created_to
          description: Date up to which the returns will be searched by creation date
          required: false
          schema:
            type: string
            example: '2023-04-01T13:00:00'
        - in: query
          name: updated_from
          description: Date from which the returns will be searched by update date
          required: false
          schema:
            type: string
            example: '2023-04-01T12:00:00'
        - in: query
          name: updated_to
          description: Date up to which the returns is to be searched by update date
          required: false
          schema:
            type: string
            example: '2023-04-01T13:00:00'
        - in: query
          name: refunded_from
          description: Date from which the returns will be searched by refund date
          required: false
          schema:
            type: string
            example: '2023-04-01T12:00:00'
        - in: query
          name: refunded_to
          description: Date up to which the returns is to be searched by refund date
          required: false
          schema:
            type: string
            example: '2023-04-01T13:00:00'
        - in: query
          name: limit
          description: Number of records to obtain. Maximum value 500.
          required: false
          schema:
            type: integer
            example: 100
        - in: query
          name: page
          description: Page number from which the records are obtained.
          required: false
          schema:
            type: integer
            example: 20
        - in: query
          name: time_zone
          description: >-
            Time zone used to search by date range (date_from and date_to). All
            date fields in the response will be formatted in this timezone. List
            of available values
            https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
          required: false
          schema:
            type: string
            example: Europe/Madrid
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReturnResponse'
        '400':
          description: Bad request.
        '401':
          description: The token is not authorized for this call.
        '404':
          description: Not found.
        '500':
          description: Unexpected error.
  /returns/{return_id}:
    get:
      operationId: getReturn
      tags:
        - Returns
      summary: Get a specific return request
      description: Get detailed information of a single return based on its ID
      parameters:
        - name: return_id
          in: path
          description: ID of the return request
          required: true
          schema:
            type: string
            example: 8e1b8c92-37a9-44c6-952a-b86bce1d8cfb
            format: uuid
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Return'
        '400':
          description: Bad request
        '401':
          description: The token is not authorized for this call
        '404':
          description: Not found
        '500':
          description: Unexpected error
  /returns/{return_id}/transportations:
    get:
      operationId: getTransportations
      tags:
        - Returns
      summary: List all return transportations
      description: >-
        Get information of a transportations scheduled to receive the return
        items of an exchange/return request
      parameters:
        - name: return_id
          in: path
          description: ID of the return request
          required: true
          schema:
            type: string
            example: 8e1b8c92-37a9-44c6-952a-b86bce1d8cfb
            format: uuid
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransportationResponse'
        '400':
          description: Bad request
        '401':
          description: The token is not authorized for this call
        '404':
          description: Not found
        '500':
          description: Unexpected error
  /returns/{return_id}/transportations/{transportation_id}:
    get:
      operationId: getTransporation
      tags:
        - Returns
      summary: Get a specific return transportation
      description: Get detailed information of a scheduled transportation based on its ID
      parameters:
        - name: return_id
          in: path
          description: ID of the return request
          required: true
          schema:
            type: string
            example: 8e1b8c92-37a9-44c6-952a-b86bce1d8cfb
            format: uuid
        - name: transportation_id
          in: path
          description: ID of the scheduled transportation
          required: true
          schema:
            type: string
            example: 38885822-8d44-4819-8358-345b4d83be70
            format: uuid
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                description: Transportation
                allOf:
                  - $ref: '#/components/schemas/TransportationScheduled'
                  - type: object
                    required:
                      - transportations
                    properties:
                      statusHistory:
                        type: array
                        description: List of transportation tracking statuses
                        items:
                          $ref: '#/components/schemas/TransportationStatusHistory'
        '400':
          description: Bad request
        '401':
          description: The token is not authorized for this call
        '404':
          description: Not found
        '500':
          description: Unexpected error
  /returns/{return_id}/refunds:
    get:
      operationId: getRefunds
      tags:
        - Returns
      summary: List all the refunds of a return request
      description: >-
        Get information of the different refunds/resolutions executed for a
        return request
      parameters:
        - name: return_id
          in: path
          description: ID of the return request
          required: true
          schema:
            type: string
            example: 8e1b8c92-37a9-44c6-952a-b86bce1d8cfb
            format: uuid
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefundResponse'
        '400':
          description: Bad request
        '401':
          description: The token is not authorized for this call
        '404':
          description: Not found
        '500':
          description: Unexpected error
  /order_cancellation_returns:
    post:
      operationId: createReturnAndCancelOrder
      tags:
        - Order Cancellation Returns
      summary: Create a return and cancel the order
      description: >-
        Create an return over an order that never was picked up by the customer.
        The return will cancel the order in the ecommerce platform regardless it
        was fulfilled or not
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderCancellationReturnRequest'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: string
                    example: '200'
                  description:
                    type: string
                    example: Your return have been registered correctly
                  return:
                    type: object
                    properties:
                      id:
                        type: string
                        example: eaea3209-68c9-4493-9df5-415f1b52003a
                        format: uuid
                        description: Internal ID of the return
                      name:
                        type: string
                        example: R1-7848
                        format: uuid
                        description: Internal ID of the return
                      shopCode:
                        type: string
                        example: marchelacolombine
                        description: Shop code which belongs the return
        '400':
          description: Bad request
        '401':
          description: The token is not authorized for this call
        '404':
          description: Shop Not found
        '405':
          description: Method not allowed
        '500':
          description: Unexpected error
  /line_items_cancellation_returns:
    post:
      operationId: createReturnAndRemoveItems
      tags:
        - Order Cancellation Returns
      summary: Create a return and remove items
      description: >-
        Create an return for those items that can not be fulfilled (e.g.
        out-of-stock of the item). In case all the items are reported, the
        ecommerce order will be cancelled
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LineItemsCancellationReturnRequest'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: string
                    example: '200'
                  description:
                    type: string
                    example: Your return have been registered correctly
                  return:
                    type: object
                    properties:
                      id:
                        type: string
                        example: eaea3209-68c9-4493-9df5-415f1b52003a
                        format: uuid
                        description: Internal ID of the return
                      name:
                        type: string
                        example: R1-7848
                        format: uuid
                        description: Internal ID of the return
                      shopCode:
                        type: string
                        example: marchelacolombine
                        description: Shop code which belongs the return
        '400':
          description: Bad request
        '401':
          description: The token is not authorized for this call
        '404':
          description: Shop Not found
        '405':
          description: Method not allowed
        '500':
          description: Unexpected error
  /store_returns:
    post:
      operationId: createInStoreReturn
      tags:
        - Store Returns
      summary: Register an in-store return
      description: >-
        Registering a new return made by the customer in a physical store of the
        merchant
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StoreReturn'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: string
                    example: '200'
                  description:
                    type: string
                    example: Your return have been registered correctly
                  return:
                    type: object
                    properties:
                      id:
                        type: string
                        example: eaea3209-68c9-4493-9df5-415f1b52003a
                        format: uuid
                        description: Internal ID of the return
                      name:
                        type: string
                        example: R1-7848
                        format: uuid
                        description: Internal ID of the return
                      shopCode:
                        type: string
                        example: marchelacolombine
                        description: Shop code which belongs the return
        '400':
          description: Bad request
        '401':
          description: The token is not authorized for this call
        '404':
          description: Shop Not found
        '405':
          description: Method not allowed
        '500':
          description: Unexpected error
  /gradings:
    post:
      operationId: createGrading
      tags:
        - Gradings of Return
      summary: Register validation of the returned items
      description: Allows to notify the result of validation process for returned items
      requestBody:
        content:
          application/only-registered+json:
            schema:
              type: object
              required:
                - shipmentId
                - shipmentIdType
                - status
              properties:
                shopCode:
                  type: string
                  description: >-
                    Shop code which belongs the return request or RMA. This
                    field is mandatory if the authorization token will be used
                    by more than one shop. In case this field is not informed,
                    it will be obtained from security context. In case it is
                    informed, it will be validated against the security context
                  example: marchelacolombine
                shipmentId:
                  type: string
                  description: >-
                    ID of the shipment. The ID must exist in the platform. API
                    will use this value to search the shipment whose status will
                    be updated.
                  example: R1-64231
                shipmentIdType:
                  type: string
                  description: >
                    Type of ID that is being reported  * `RETURN_ID` - ID of the
                    return. The last active shipment/transport will be searched.
                    This value is generated by iF at the moment the return
                    request is created. It has the GUID format
                    (f1844145-28a8-48d5-97b4-b00505e98cdc) * `RETURN_NAME` -
                    Name of the return. The last active shipment/transport will
                    be searched. This value is generated by iF at the moment the
                    return request is created. It has the format R#-{ORDER_NAME}
                    (R1-64231)
                  example: RETURN_NAME
                  enum:
                    - RETURN_ID
                    - RETURN_NAME
                status:
                  $ref: '#/components/schemas/GradingReturnStatus'
                itemsWithIncidents:
                  type: array
                  items:
                    $ref: '#/components/schemas/GradedLineItemWithIncident'
          application/new-items+json:
            schema:
              type: object
              required:
                - orderName
                - returnLineItems
              properties:
                shopCode:
                  type: string
                  example: marchelacolombine
                  description: >-
                    Shop code which belongs the return request or RMA. This
                    field is mandatory if the authorization token will be used
                    by more than one shop. In case this field is not informed,
                    it will be obtained from security context. In case it is
                    informed, it will be validated against the security context
                returnName:
                  type: string
                  example: R1-64231
                  description: Name of the return that has been validated
                orderName:
                  type: string
                  example: '64231'
                  description: >
                    Name of the ecommerce order. The API will use this field to 

                    * Search the order in the ecommerce platform and get details
                    about line items

                    * Search the returns requests registered at iF returns
                returnLineItems:
                  type: array
                  description: List of items that have been graded
                  items:
                    $ref: '#/components/schemas/GradedLineItem'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: string
                    example: '200'
                  description:
                    type: string
                    example: Your grading have been received correctly
        '400':
          description: Bad request
        '401':
          description: The token is not authorized for this call
        '404':
          description: Not found
        '405':
          description: Method not allowed
        '500':
          description: Unexpected error
  /orders/{order_name}/return_gradings:
    post:
      operationId: createGradingForOrderReturn
      tags:
        - Gradings of Return
      summary: Register validation of returns for an ecommere order
      description: >-
        Allows to notify the result of validation process of the returns
        received by the merchant operational teams
      parameters:
        - name: order_name
          in: path
          description: Name of ecommerce order
          required: true
          schema:
            type: string
            example: '64231'
      requestBody:
        content:
          application/new-items+json:
            schema:
              type: object
              required:
                - returnLineItems
              properties:
                shopCode:
                  type: string
                  example: marchelacolombine
                  description: >-
                    Shop code which belongs the return request or RMA. This
                    field is mandatory if the authorization token will be used
                    by more than one shop. In case this field is not informed,
                    it will be obtained from security context. In case it is
                    informed, it will be validated against the security context
                returnName:
                  type: string
                  example: R1-64231
                  description: Name of the return that has been validated
                customerEmail:
                  type: string
                  example: customer@if.com
                  description: Email associated to the customer
                returnLineItems:
                  type: array
                  description: List of items that have been graded
                  items:
                    $ref: '#/components/schemas/GradedLineItem'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: string
                    example: '200'
                  description:
                    type: string
                    example: Your grading have been received correctly
        '400':
          description: Bad request
        '401':
          description: The token is not authorized for this call
        '404':
          description: Not found
        '405':
          description: Method not allowed
        '500':
          description: Unexpected error
  /shipping_trackings:
    post:
      operationId: createShippingTracking
      tags:
        - Transportations
      summary: Register tracking status
      description: It allows to update the tracking status of an active tranportation
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - shipmentId
                - shipmentIdType
                - trackingStatus
              properties:
                shopCode:
                  type: string
                  description: >-
                    Shop code which belongs the shipment. In case this field is
                    not informed, it will be obtained from security context. In
                    case it is informed, it will be validated against the
                    security context. This field is mandatory in case the token
                    is associated with two or more merchants
                  example: marchelacolombine
                shipmentId:
                  type: string
                  description: >-
                    ID of the shipment. The ID must exist in the platform. API
                    will use this value to search the shipment whose status will
                    be updated.
                  example: R1-64231
                shipmentIdType:
                  type: string
                  description: >
                    Type of ID that is being reported  * `RETURN_NAME` - Name of
                    the return. The last active shipment/transport will be
                    searched. This value is generated by iF at the moment the
                    return request is created. It has the format R#-{ORDER_NAME}
                    (R1-64231)
                  example: RETURN_NAME
                  enum:
                    - RETURN_NAME
                carrierName:
                  type: string
                  description: Carrier responsible for the shipment
                  example: UPS
                trackingNumber:
                  type: string
                  description: Tracking number for the shipping
                  example: 1Z4E61W19106005862
                trackingUrl:
                  type: string
                  description: Tracking URL for the shipping
                  example: https://www.ups.com/tracknum=1Z4E61W19106005862
                trackingStatus:
                  $ref: '#/components/schemas/TransportationStatus'
                trackingStatusDescription:
                  type: string
                  description: Description of the status description
                  example: Package assigned to the driver
                trackingDate:
                  type: string
                  format: date
                  description: >-
                    Date of the tracking event. In case is not present, the
                    current date will be used
                  example: '2011-08-12T20:17:46Z'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: string
                    example: '200'
                  description:
                    type: string
                    example: Your tracking have been registered correctly
        '400':
          description: Bad request
        '401':
          description: The token is not authorized for this call
        '404':
          description: Shop Not found
        '405':
          description: Method not allowed
        '500':
          description: Unexpected error
  /return_methods:
    post:
      operationId: calculateReturnMethodsForReturn
      tags:
        - Return Methods
      summary: Calculate the available return methods
      description: >-
        Calculate the return methods the customer can use to ship the returned
        items. The available return methods are calculated based on the data of
        the ecoommerce order and the list of the returned items selected by the
        customer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CalculateReturnMethodsRequest'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  returnMethods:
                    type: array
                    description: List of available return methods
                    items:
                      $ref: '#/components/schemas/CalculatedReturnMethod'
        '400':
          description: >-
            Bad request. It will include all the errors comming from carrier
            integration
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorRespose'
        '401':
          description: The token is not authorized for this call
        '405':
          description: Method not allowed
        '500':
          description: Unexpected error
  /shipping_labels:
    post:
      operationId: createShippingLabel
      tags:
        - Transportations
      summary: Create shipping label
      description: Create a shipping label for the transportation of the items
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateShippingLabelRequest'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShippingLabel'
        '400':
          description: >-
            Bad request. It will include all the errors comming from carrier
            integration
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      allOf:
                        - $ref: '#/components/schemas/ErrorRespose'
                        - properties:
                            carrierErrors:
                              type: array
                              items:
                                $ref: '#/components/schemas/CarrierErrorResponse'
        '401':
          description: The token is not authorized for this call
        '405':
          description: Method not allowed
        '500':
          description: Unexpected error
    get:
      operationId: getShippingLabel
      tags:
        - Transportations
      summary: Get a shipping label
      description: Get an existing shipping label
      parameters:
        - in: query
          name: client_shipment_id
          description: ID of the shipment assigned by the merchant
          required: true
          schema:
            type: string
            example: SHP123
        - in: query
          name: shopCode
          description: >-
            Shop code which belongs the shipping label. In case this field is
            not informed, it will be obtained from security context. In case it
            is informed, it will be validated against the security context
          required: false
          schema:
            type: string
            example: marchelacolombine
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ShippingLabel'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorRespose'
        '401':
          description: The token is not authorized for this call
        '404':
          description: Not found
        '405':
          description: Method not allowed
        '500':
          description: Unexpected error
    put:
      operationId: updateShippingLabel
      tags:
        - Transportations
      summary: Update the shipping label
      description: >-
        It allows to update the shipping label of an existing transportation in
        the platform
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - shipmentId
                - shipmentIdType
                - shippingLabels
              properties:
                shopCode:
                  type: string
                  description: >-
                    Shop code which belongs the shipment. In case this field is
                    not informed, it will be obtained from security context. In
                    case it is informed, it will be validated against the
                    security context. This field is mandatory in case the token
                    is associated with two or more merchants
                  example: marchelacolombine
                shipmentId:
                  type: string
                  description: >-
                    ID of the shipment. The ID must exist in the platform.
                    Platform will use this value to search the shipment whose
                    status will be updated.
                  example: 64231-R1
                shipmentIdType:
                  type: string
                  description: >
                    Type of ID that is being reported  * `RETURN_NAME` - Name of
                    the return. The last active shipment/transport will be
                    searched. This value is generated by iF at the moment the
                    return request is created. It has the format R#-{ORDER_NAME}
                    (R1-64231) * `CLIENT_REFERENCE` - Shipping reference
                    assigned for the shipment/transport. This value is generated
                    by iF at the moment the transport is created. It has the
                    format P#R#{MERCHANT-SHORT-CODE}{ORDER_NAME} (P1R1maco64231)
                    * `MERCHANT_RETURN_NAME` - Name of the return in the
                    ecommerce platform. The last active shipment/transport will
                    be searched. This value is generated by the merchant system
                    when the return is registered. The format is defined by the
                    merchant (e.g. in Shopify the return name is 64231-R1)
                  example: MERCHANT_RETURN_NAME
                  enum:
                    - RETURN_NAME
                    - CLIENT_REFERENCE
                    - MERCHANT_RETURN_NAME
                shippingLabels:
                  type: array
                  description: List of shipping labels
                  items:
                    type: object
                    required:
                      - carrierTrackingCode
                      - carrierTrackingUrl
                      - format
                      - url
                    properties:
                      carrierTrackingCode:
                        type: string
                        description: Reference assigned by the carrier to the shipment
                        example: PARC0001
                      additionalTrackingCodes:
                        type: array
                        items:
                          type: string
                          description: >-
                            Additional code generated by the carrier when the
                            shipping label was created
                          example: S4848554544545
                      carrierTrackingUrl:
                        type: string
                        description: URL for shipment tracking
                        example: https://carrier.com/tracking/S4848554544545
                      format:
                        $ref: '#/components/schemas/LabelFormat'
                      url:
                        description: URL for getting the shipping label
                        type: string
                        example: https://if.com/shippping_label.pdf
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: string
                    example: '200'
                  description:
                    type: string
                    example: Your shipping label have been updated correctly
        '400':
          description: Bad request
        '401':
          description: The token is not authorized for this call
        '404':
          description: Shop Not found
        '405':
          description: Method not allowed
        '500':
          description: Unexpected error
  /pudos:
    post:
      operationId: calculatePudosForReturn
      tags:
        - Transportations
      summary: Calculate available PUDOs
      description: >-
        Calculate the PUDOs can be used to ship the items. The PUDOs are
        calculated based on a reference address. Before call this endpoint, the
        list of avaiable return methods should be calculated in order to obtain
        the carrier data. It is mandatory to inform either the address or the
        geolocation data
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CalculatePudosRequest'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                description: List of available PUDOs
                items:
                  properties:
                    carrierCode:
                      description: Carrier code associated with the PUDOs
                      type: string
                      example: ups
                    carrierExternalCode:
                      description: Carrier code associated with the PUDOs
                      type: string
                      example: '20000008'
                    pudoPoints:
                      description: List of available PUDOs for the carrier
                      type: array
                      items:
                        $ref: '#/components/schemas/CalculatedPudo'
        '400':
          description: >-
            Bad request. It will include all the errors comming from carrier
            integration
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      allOf:
                        - $ref: '#/components/schemas/ErrorRespose'
                        - properties:
                            carrierErrors:
                              type: array
                              items:
                                $ref: '#/components/schemas/CarrierErrorResponse'
        '401':
          description: The token is not authorized for this call
        '405':
          description: Method not allowed
        '500':
          description: Unexpected error
components:
  schemas:
    TransportationResponse:
      type: object
      properties:
        transportations:
          type: array
          items:
            $ref: '#/components/schemas/TransportationScheduled'
    RefundResponse:
      type: object
      properties:
        refunds:
          type: array
          items:
            $ref: '#/components/schemas/Refund'
    Refund:
      properties:
        id:
          type: number
          description: ID of the refund
          example: '2025-03-06T14:27:11.481Z'
        createdAt:
          type: string
          format: date
          description: Date when the Refund was created
          example: '2025-03-06T14:27:11Z'
        amount:
          type: number
          format: float
          description: Amount refunded to the customer in ORIGINAL_PAYMENT_METHOD
          example: 120
        currency:
          type: string
          description: Currency in which the refund is made
          example: EUR
        baseAmount:
          type: number
          description: >-
            Amount refunded to the customer in ORIGINAL_PAYMENT_METHOD in the
            shop base currency
          example: 120
          format: float
        baseCurrency:
          type: string
          description: Shop base currency
          example: EUR
        approvedBy:
          type: string
          description: User who approved the refund
          example: operator@ifeturns.com
        exchangeAmountPaid:
          type: number
          description: Amount paid by the customer for the exchange
          example: 0
          format: float
        baseExchangeAmountPaid:
          type: number
          description: >-
            Amount paid by the customer for the exchange in the shop base
            currency
          example: 0
          format: float
        ecommerceDiscountCouponCode:
          type: string
          description: >-
            Code of the discount (masked) created in the ecommerce platform when
            the refund type is STORE_CREDIT
          example: null
        ecommerceDiscountCouponId:
          type: string
          description: >-
            ID of the discount created in the ecommerce platform when the refund
            type is STORE_CREDIT
          example: null
        ecommerceGiftCardCode:
          type: string
          description: >-
            Code of the gift card (masked) created in the ecommerce platform
            when the refund type is GIFT_CARD
          example: null
        ecommerceGiftCardId:
          type: string
          description: >-
            ID of the gift card (masked) created in the ecommerce platform when
            the refund type is GIFT_CARD
          example: ''
        ecommerceExchangeOrderName:
          type: string
          description: ' Name of the new order created created in the ecommerce platform when the refund type is EXCHANGE'
          example: null
        ecommerceExchangeOrderId:
          type: string
          description: >-
            ID of the new order created created in the ecommerce platform when
            the refund type is EXCHANGE
          example: null
        ecommerceRefundId:
          type: string
          description: ID of the refund created in the ecommerce platform
          example: '1041273454923'
        mode:
          example: POST_VALIDATION
          $ref: '#/components/schemas/RefundMode'
        type:
          example: ORIGINAL_PAYMENT_METHOD
          $ref: '#/components/schemas/RefundType'
        subType:
          $ref: '#/components/schemas/RefundSubType'
          example: ''
        refundLineItems:
          type: array
          description: List of line items included in the refund
          items:
            $ref: '#/components/schemas/ReturnLineItem'
    ReturnResponse:
      type: object
      properties:
        returns:
          type: array
          items:
            $ref: '#/components/schemas/Return'
        pageInfo:
          $ref: '#/components/schemas/PageInfo'
    Return:
      type: object
      required:
        - shopCode
        - name
        - totalReturnFee
        - totalReturnAmount
        - currency
        - origin
        - destination
        - customer
        - ecommerceOrder
        - returnLineItems
      description: Return request object
      properties:
        id:
          type: string
          description: Internal ID of the return order
          example: 8e1b8c92-37a9-44c6-952a-b86bce1d8cfb
          format: uuid
        shopCode:
          type: string
          example: marchelacolombine
          description: >-
            Shop code which belongs the return. In case this field is not
            informed, it will be obtained from security context. In case it is
            informed, it will be validated against the security context
        name:
          type: string
          description: Return Merchant Authorization (RMA) name
          example: R1-7848
        createdAt:
          type: string
          description: Date when the return order was created
          format: date-time
          example: '2022-11-17 12:01:00Z'
        updatedAt:
          type: string
          description: Date when the return order was updated
          format: date-time
          example: '2022-11-17 12:01:00Z'
        cancelledAt:
          type: string
          description: Date when the return order was updated
          format: date-time
          example: '2022-11-17 12:01:00Z'
        status:
          $ref: '#/components/schemas/ReturnStatus'
        totalReturnFee:
          type: number
          description: Fee associated with the method of return
          format: float
          example: 5
        totalReturnAmount:
          type: number
          description: Total amount of the all returned items
          format: float
          example: 121
        totalTax:
          type: number
          description: Total tax of the all returned items
          format: float
          example: 21
        totalRefund:
          type: number
          description: Total amount to be refund (totalReturnAmount - totalReturnFee)
          format: float
          example: 116
        currency:
          type: string
          description: Transaction currency
          example: EUR
        baseTotalReturnFee:
          type: number
          description: Fee associated with the method of return in shop base currency
          format: float
          example: 5
        baseTotalReturnAmount:
          type: number
          description: Total amount of the all returned items in shop base currency
          format: float
          example: 121
        baseTotalTax:
          type: number
          description: Total tax of the all returned items in shop base currency
          format: float
          example: 21
        baseTotalRefund:
          type: number
          description: >-
            Total amount to be refund in shop base currency
            (baseTotalReturnAmount - baseTotalReturnFee)
          format: float
          example: 116
        baseCurrency:
          type: string
          description: Shop base currency
          example: EUR
        customer:
          $ref: '#/components/schemas/Customer'
        ecommerceOrder:
          $ref: '#/components/schemas/Order'
        origin:
          type: object
          description: Origin address for the transportation
          properties:
            fullName:
              type: string
              description: Full name associated to the origin
              example: Juan Perez
            email:
              type: string
              description: Email associated to the origin
              example: customer@if.com
            phone:
              type: string
              description: Phone associated to the origin
              example: '+34666666666'
            address:
              $ref: '#/components/schemas/Address'
        destination:
          description: Destination address for the transportation
          properties:
            fullName:
              type: string
              description: Full name of the destination
              example: iF warehouse
            email:
              type: string
              description: Email associated to the destination
              example: warehouse@if.com
            phone:
              type: string
              description: Phone associated to the destination
              example: '+34666666666'
            address:
              $ref: '#/components/schemas/Address'
        returnLineItems:
          type: array
          description: List of returned items
          items:
            $ref: '#/components/schemas/ReturnLineItem'
        activeTransportation:
          $ref: '#/components/schemas/ActiveTransportationScheduled'
    StoreReturn:
      type: object
      required:
        - orderName
        - customerEmail
        - returnLineItems
      description: >-
        Return request input object. It Only supports returns (not exchanges)
        and EUR as currency
      properties:
        shopCode:
          type: string
          example: marchelacolombine
          description: >-
            Shop code which belongs the return. In case this field is not
            informed, it will be obtained from security context. In case it is
            informed, it will be validated against the security context
        orderName:
          type: string
          description: Ecommerce order name
          example: '7848'
        customerEmail:
          type: string
          description: Email associated to the customer
          example: customer@if.com
        customerPhone:
          type: string
          description: Phone associated to the customer
          example: '+34666666666'
        returnLineItems:
          type: array
          description: List of returned items
          items:
            $ref: '#/components/schemas/StoreReturnLineItem'
    StoreReturnLineItem:
      type: object
      required:
        - barcode
        - refundType
        - refundMode
      properties:
        barcode:
          type: string
          description: Barcode of the returned item
          example: '8893892'
        quantity:
          type: number
          description: Items units returned
          format: int
          example: 1
        refundType:
          $ref: '#/components/schemas/RefundType'
        refundMode:
          $ref: '#/components/schemas/RefundMode'
    Customer:
      type: object
      required:
        - fullName
        - email
      description: Customer who is requesting the return
      properties:
        fullName:
          type: string
          description: Full name associated to the address
          example: Juan Perez
        email:
          type: string
          description: Email associated to the address
          example: customer@if.com
        phone:
          type: string
          description: Phone associated to the address
          example: '+34666666666'
        address:
          $ref: '#/components/schemas/Address'
    Order:
      type: object
      required:
        - id
      description: Ecommerce order from where the return was requested
      properties:
        id:
          type: string
          description: ID of the original order in the ecommerce platform
          example: '4243234'
        name:
          type: string
          description: Name of the original order in the ecommerce platform
          example: '7848'
        customerId:
          type: string
          description: >-
            Customer ID associated to the original order in the ecommerce
            platform
          example: '23423'
    ReturnLineItem:
      type: object
      required:
        - sku
        - barcode
        - quantity
        - price
        - refundType
        - refundMode
      properties:
        id:
          type: string
          description: Internal ID of returned item
          example: 54048ad6-af97-417c-a8a6-7b19a154c135
          format: uuid
        productName:
          type: string
          description: Name of returned item
          example: Camisa
        variantName:
          type: string
          description: Specific variant of the returned item
          example: XL Roja
        sku:
          type: string
          description: SKU of the returned item
          example: '1234567'
        barcode:
          type: string
          description: Barcode of the returned item
          example: '8893892'
        vendor:
          type: string
          description: Vendor name associated to returned item
          example: iFreturns
        price:
          type: number
          description: Price of the returned item including taxes
          format: float
          example: 141
        discount:
          type: number
          description: Discount over the original price of the returned item
          format: float
          example: 20
        paid:
          type: number
          description: Amount paid by the customer for the returned item (price - discount)
          format: float
          example: 121
        tax:
          type: number
          description: Tax of the returned item
          format: float
          example: 21
        returnAmount:
          type: number
          description: Amount to be returned to the customer
          format: float
          example: 121
        currency:
          type: string
          description: Transaction currency
          example: EUR
        basePrice:
          type: number
          description: Price of the returned item including taxes in shop base currency
          format: float
          example: 141
        baseDiscount:
          type: number
          description: >-
            Discount over the original price of the returned item in shop base
            currency
          format: float
          example: 20
        basePaid:
          type: number
          description: >-
            Amount paid by the customer for the returned item (basePrice -
            baseDiscount)
          format: float
          example: 121
        baseTax:
          type: number
          description: Tax of the returned item in shop base currency
          format: float
          example: 21
        baseReturnAmount:
          type: number
          description: Amount to be returned to the customer in shop base currency
          format: float
          example: 121
        baseCurrency:
          type: string
          description: Shop base currency
          example: EUR
        quantity:
          type: number
          description: Items units returned
          format: int
          example: 1
        imageUrl:
          type: string
          description: Url for the image of the returned item
          example: https://ifreturns.com/imagen/producto.jpg
        ecommerceLineItem:
          $ref: '#/components/schemas/OrderLineItem'
        returnReason:
          $ref: '#/components/schemas/ReturnReason'
        refundType:
          $ref: '#/components/schemas/RefundType'
        refundMode:
          $ref: '#/components/schemas/RefundMode'
        exchangeLineItems:
          type: array
          description: Information about the new product in case of exchange
          items:
            $ref: '#/components/schemas/ExchangeLineItem'
    OrderLineItem:
      type: object
      description: Ecommerce order line item that is returned
      required:
        - lineItemId
        - productId
        - variantId
      properties:
        lineItemId:
          type: string
          description: ID of returned line item in the original order
          example: 8e1b8c92
        productId:
          type: string
          description: Product ID in the ecommerce platform
          example: '1234'
        variantId:
          type: string
          description: Variant ID in the ecommerce platform
          example: XS1234
    ExchangeLineItem:
      type: object
      required:
        - productName
        - variantName
        - price
        - quantity
        - ecommerceProductId
        - ecommerceVariantId
      properties:
        id:
          type: string
          description: Internal ID of new item
          example: 8e1b8c92-37a9-44c6-952a-b86bce1d8cfb
          format: uuid
        productName:
          type: string
          description: Product ID of the new item
          example: Product/12345
        variantName:
          type: string
          description: Specific variant of the new item
          example: Blue Sweater XL Size
        sku:
          type: string
          description: SKU of the new item
          example: '1234557'
        price:
          type: number
          description: Price of the new item
          format: float
          example: 120
        quantity:
          type: number
          format: int
          description: Items units to be processed
          example: 1
        vendor:
          type: string
          description: Vendor name of the new item
          example: iFreturns
        ecommerceProductId:
          type: string
          description: Product ID in the ecommerce platform
          example: '1234'
        ecommerceVariantId:
          type: string
          description: Variant ID in the ecommerce platform
          example: XL1234
    ReturnReason:
      type: object
      required:
        - additionalInfo
      properties:
        code:
          type: string
          description: Reason code why the customer returns the item
          example: dont-like
        reason:
          type: string
          description: Reason description why the customer returns the item"
          example: No me gusta
        additionalInfo:
          type: string
          description: Additional info about why the customer returns the item
          example: Presenta un fallo en la cremallera
    Address:
      type: object
      required:
        - line1
        - city
        - postalCode
        - countryCode
      properties:
        line1:
          type: string
          description: Line 1 of the Address
          example: Calle de Fortunata y Jacinta 12
        line2:
          type: string
          description: Line 2 data of the address
          example: ''
        city:
          type: string
          description: City name of the address
          example: Madrid
        postalCode:
          type: string
          description: Postal code of the address
          example: '28020'
        region:
          type: string
          description: Region name of the address
          example: Madrid
        countryCode:
          type: string
          description: Country ISO code of the address
          example: ES
    ActiveTransportationScheduled:
      type: object
      description: Transport currently active to receive the returned items
      properties:
        id:
          type: string
          description: Internal ID of new item
          example: 38885822-8d44-4819-8358-345b4d83be70
          format: uuid
        createdAt:
          type: string
          format: date-time
          description: Date when the Transport was created
          example: '2022-11-17 12:05:00Z'
        status:
          example: REQUESTED
          $ref: '#/components/schemas/TransportationStatus'
        serviceMessage:
          type: string
          description: Name of the transport chosed by customer
          example: Recogida programada
        serviceType:
          type: string
          description: Type of transport chosed by customer
          example: pickup
        carrierCode:
          type: string
          description: Carrier responsible for the transport
          example: CORREOS-EXPRESS
        carrierServiceCode:
          type: string
          description: Carrier service used for the transport
          example: correos-epaq-24
        carrierLabel:
          type: string
          description: URL to donwload the carrier label
          example: https://if.com/P1R1mlc7848.pdf
        carrierTrackingUrl:
          type: string
          description: URL for tracking the shipment
          example: https://if.com/tracking/3230006199506927
        carrierPickupReference:
          type: string
          description: Pickup code generated by the carrier
          example: '125172899'
        carrierReference:
          type: string
          description: Transport code generated by the carrier
          example: '3230006199506927'
        clientReference:
          type: string
          description: Internal code generated for the transport
          example: P1R1mlc7848
        pickupDate:
          type: string
          description: >-
            Date when the return order will be picked up. Only available in case
            of pickup return method
          example: '2022-11-22'
    TransportationScheduled:
      type: object
      description: Transport scheduled to receive the returned items
      properties:
        id:
          type: string
          description: Internal ID of new item
          example: 38885822-8d44-4819-8358-345b4d83be70
          format: uuid
        returnId:
          type: string
          description: Return ID associated to the transportation
          example: 38885822-8d44-4819-8358-345b4d83be70
          format: uuid
        createdAt:
          type: string
          format: date-time
          description: Date when the Transport was created
          example: '2022-11-17 12:05:00Z'
        status:
          example: REQUESTED
          $ref: '#/components/schemas/TransportationStatus'
        currentActive:
          type: boolean
          description: >-
            Flag to indicate which transport is active, in case a pickup has
            failed
          example: true
        serviceMessage:
          type: string
          description: Name of the transport chosed by customer
          example: Recogida programada
        serviceType:
          type: string
          description: Type of transport chosed by customer
          example: pickup
        carrierCode:
          type: string
          description: Carrier responsible for the transport
          example: CORREOS-EXPRESS
        carrierServiceCode:
          type: string
          description: Carrier service used for the transport
          example: correos-epaq-24
        carrierLabel:
          type: string
          description: URL to donwload the carrier label
          example: https://if.com/P1R1mlc7848.pdf
        carrierTrackingUrl:
          type: string
          description: URL for tracking the shipment
          example: https://if.com/tracking/3230006199506927
        carrierPickupReference:
          type: string
          description: Pickup code generated by the carrier
          example: '125172899'
        carrierReference:
          type: string
          description: Transport code generated by the carrier
          example: '3230006199506927'
        clientReference:
          type: string
          description: Internal code generated for the transport
          example: P1R1mlc7848
        pickupDate:
          type: string
          description: >-
            Date when the return order will be picked up. Only available in case
            of pickup return method
          example: '2022-11-22'
        origin:
          type: object
          description: Origin address for the transportation
          properties:
            fullName:
              type: string
              description: Full name associated to the origin
              example: Juan Perez
            email:
              type: string
              description: Email associated to the origin
              example: customer@if.com
            phone:
              type: string
              description: Phone associated to the origin
              example: '+34666666666'
            address:
              $ref: '#/components/schemas/Address'
        destination:
          description: Destination address for the transportation
          properties:
            fullName:
              type: string
              description: Full name of the destination
              example: iF warehouse
            email:
              type: string
              description: Email associated to the destination
              example: warehouse@if.com
            phone:
              type: string
              description: Phone associated to the destination
              example: 34666666666
            address:
              $ref: '#/components/schemas/Address'
    TransportationStatusHistory:
      type: object
      description: Detailed status of the transportation
      properties:
        id:
          type: string
          description: Internal ID of the status history
          example: 38885822-8d44-4819-8358-345b4d83be70
          format: uuid
        status:
          $ref: '#/components/schemas/TransportationStatus'
        createdAt:
          type: string
          description: Date when the carrier status was registered at iF
          example: '2022-11-17 12:15:00Z'
        carrierStatusDate:
          type: string
          format: date-time
          description: Date when the status was registered by the carrier
          example: '2022-11-17 12:05:00Z'
        carrierStatusCode:
          type: string
          description: Status code registered by the carrier
          example: '01'
        carrierStatusDescription:
          type: string
          description: Status description registered by the carrier
          example: RECEIVED AT THE OFFICE
        carrierIncidentDescription:
          type: string
          description: Additional info in case of an issue with the transportation
          example: CUSTOMER DOES NOT HAVE READY THE PARCEL
    GradedLineItemWithIncident:
      type: object
      required:
        - status
        - sku
      properties:
        sku:
          type: string
          description: SKU of the returned item
          example: '1234567'
        barcode:
          type: string
          description: Barcode of the returned item
          example: '8893892'
        status:
          $ref: '#/components/schemas/GradingIncidentStatus'
        note:
          type: string
          example: picking error
          description: Additional notes reported for the grading
        validatedAt:
          type: string
          format: date-time
          example: '2022-11-17 12:01:00'
          description: Date when the validation was performed (UTC)'
    GradedLineItem:
      type: object
      required:
        - sku
        - status
      properties:
        sku:
          type: string
          description: SKU of the graded item
        status:
          $ref: '#/components/schemas/GradingValidationStatus'
        note:
          type: string
          description: Additional notes for the validation of the item
        validatedAt:
          type: string
          format: date-time
          example: '2022-11-17 12:01:00'
          description: Date when the validation was performed (UTC)
        refundType:
          $ref: '#/components/schemas/RefundType'
    OrderCancellationReturnRequest:
      type: object
      required:
        - orderName
        - customerEmail
      description: Information about the order to be returned and cancelled.
      properties:
        shopCode:
          type: string
          example: marchelacolombine
          description: >-
            Shop code which belongs the return. In case this field is not
            informed, it will be obtained from security context. In case it is
            informed, it will be validated against the security context
        orderName:
          type: string
          description: Ecommerce order name
          example: '7848'
        customerEmail:
          type: string
          description: Email associated to the customer
          example: customer@if.com
        customerPhone:
          type: string
          description: Phone associated to the customer
          example: '+34666666666'
        dropOffPointCode:
          type: string
          description: >-
            Internal code of the drop-off location where the customer was going
            to pick up the order
          example: STORE-TEST-1
        language:
          type: string
          description: Language code on ISO-639 to localize the return request
          example: es
    LineItemsCancellationReturnRequest:
      type: object
      required:
        - orderName
        - customerEmail
        - removeLineItems
      description: Information about the line items that will be removed from the order.
      properties:
        shopCode:
          type: string
          example: marchelacolombine
          description: >-
            Shop code which belongs the return. In case this field is not
            informed, it will be obtained from security context. In case it is
            informed, it will be validated against the security context
        orderName:
          type: string
          description: Ecommerce order name
          example: '7848'
        customerEmail:
          type: string
          description: Email associated to the customer
          example: customer@if.com
        customerPhone:
          type: string
          description: Phone associated to the customer
          example: '+34666666666'
        language:
          type: string
          description: Language code on ISO-639 to localize the return request
          example: es
        removeLineItems:
          type: array
          minItems: 1
          description: List of items to be removed from the order
          items:
            type: object
            properties:
              sku:
                type: string
                description: SKU of the item
                example: '1234567'
    PageInfo:
      type: object
      properties:
        totalRecords:
          type: integer
          description: Total number of records meet search criteria
          example: 351
        totalPages:
          type: integer
          description: >-
            Number of pages comprising all available records. It is calculated
            based on the limit value
          example: 4
    RefundType:
      type: string
      description: Refund method the customer can select for the returned item
      enum:
        - ORIGINAL_PAYMENT_METHOD
        - STORE_CREDIT
        - EXCHANGE
        - GIFT_CARD
    RefundSubType:
      type: string
      description: Refund sub type selected by customer for the returned item
      enum:
        - OTHER_PRODUCT_SAME
        - OTHER_PRODUCT_HIGHER
        - OTHER_PRODUCT_LOWER
        - OTHER_VARIANT
      example: ''
    RefundMode:
      type: string
      description: Mode in which the returned item will be refunded
      enum:
        - PRE_VALIDATION
        - SHIPPING_COMPLETED
        - SHIPPING_IN_PROGRESS
        - POST_VALIDATION
        - MANUAL
        - INSTANT
        - DROP_OFF
    ReturnStatus:
      type: string
      description: Status of the return order
      enum:
        - PENDING
        - RECEPTION_IN_PROGRESS
        - RECEPTION_COMPLETED
        - RECEIVED
        - CHECKED
        - CLOSED
        - DISCARDED
        - EXPIRED
        - NEEDS_VALIDATION
      example: RECEIVED
    TransportationStatus:
      type: string
      description: Status of the shipment/transport
      example: SHIPPING_IN_PROGRESS
      enum:
        - REQUESTED
        - PICK_UP_IN_PROGRESS
        - PICK_UP_COMPLETED
        - SHIPPING_IN_PROGRESS
        - SHIPPING_COMPLETED
        - PICK_UP_FAILED
        - PICK_UP_CANCELLED
        - SHIPPING_FAILED
        - SHIPPING_CANCELLED
    GradingIncidentStatus:
      type: string
      example: DEFECT-ODOURS-OR-DIRTY
      description: Grading status assigned after the validation
      enum:
        - DEFECT-ODOURS-OR-DIRTY
        - DEFECT-BROKEN-PRODUCT
        - ISSUE-INCORRECT-PRODUCT-OR-SKU
        - ISSUE-MISSING-PRODUCT-OR-SKU
        - ISSUE-INCOMPLETE-PRODUCT-OR-SKU
        - ISSUE-UNKNOWN-PRODUCT-OR-SKU
        - ISSUE-FALSIFICATION
        - ISSUE-OTHER
    GradingReturnStatus:
      type: string
      example: INCIDENT
      description: Grading status of the return assigned after the validation
      enum:
        - OK
        - INCIDENT
    GradingValidationStatus:
      type: string
      description: Validation status assigned to the graded item
      example: APPROVED
      enum:
        - APPROVED
        - REJECTED
    CalculateReturnMethodsRequest:
      type: object
      required:
        - currencyCode
        - originAddress
        - returnLineItems
        - client
      properties:
        shopCode:
          type: string
          description: >-
            Shop code which belongs the retrurn request or rma. In case this
            field is not informed, it will be obtained from security context. In
            case it is informed, it will be validated against the security
            context
          example: marchelacolombine
        currencyCode:
          description: >-
            Currency in which the order is being returned was placed. All
            amounts reported must be in this currency
          type: string
          example: EUR
        ecommerceOrder:
          type: object
          description: Ecommerce order from which the returns is being generated
          required:
            - id
          properties:
            id:
              description: ID of the ecommerce order
              type: string
              example: 123
            orderType:
              description: Type of the ecommerce order
              type: string
              example: DTC
            salesChannel:
              description: Channel from which the order was created
              type: string
              example: web
            status:
              description: Ecommerce order status
              type: string
              example: COMPLETED
            totalPaid:
              description: Total amount paid for the order
              type: number
              format: float
              example: 254
            totalDiscount:
              description: Total discount applied to the order
              type: number
              format: float
              example: 0
            totalShippingCost:
              description: Cost of shipping method
              type: number
              format: float
              example: 5
            paymentMethods:
              description: methods used to pay the order
              type: array
              items:
                type: object
                properties:
                  method:
                    description: name of the payment method
                    type: string
                    example: credit_card
                  amount:
                    description: amount paid with the paymenet method
                    type: number
                    format: float
                    example: 254
            tags:
              description: Tags assigned to the order
              type: array
              items:
                type: string
              example:
                - WEB
                - SUMMER
            discountCodes:
              description: Discount codes used in the order
              type: array
              items:
                type: string
              example:
                - WELCOME10
                - FREESHIPPING
            lineItems:
              description: Items included in the order
              type: array
              items:
                type: object
                properties:
                  id:
                    description: ID of the line item
                    type: string
                  name:
                    description: Name of the item
                    type: string
                  sku:
                    description: SKU of the item
                    type: string
                  variantOptions:
                    description: Options that define the product variant
                    type: array
                    items:
                      type: object
                      properties:
                        key:
                          type: string
                          description: Key of the option
                          example: color
                        value:
                          type: string
                          description: Value of the option
                          example: blue
                  quantity:
                    description: Number of items ordered
                    type: number
                  originalUnitPrice:
                    type: number
                    description: original unit price of items ordered
                    format: float
                  lineTotalPrice:
                    type: number
                    description: Total price of the line item
                    format: float
                  lineTotalDiscount:
                    type: number
                    description: Total discount of the line item
                    format: float
                  lineTotalPaid:
                    description: Total paid for the line item
                    type: number
                    format: float
                  productTags:
                    type: array
                    description: >-
                      Tags assigned to the item. Any additional product
                      attribute could be reported using this field
                    items:
                      type: string
                  primaryProductCategory:
                    type: string
                    description: Primary product category which the item belongs
                  productVendor:
                    type: string
                    description: Vendor name associated to the item
              example:
                - id: '456456'
                  name: Oxford shirt M
                  sku: OSM123
                  variantOptions:
                    - key: color
                      value: blue
                    - key: size
                      value: M
                  quantity: 1
                  originalUnitPrice: 100
                  lineTotalPrice: 100
                  lineTotalDiscount: 0
                  lineTotalPaid: 100
                  productTags:
                    - new
                    - color:blue
                    - collection:summer
                  primaryProductCategory: shirts
                  productVendor: ifreturns
                - id: '456488'
                  name: Black trouser 38
                  sku: BT038
                  variantOptions:
                    - key: color
                      value: black
                    - key: size
                      value: '38'
                  quantity: 2
                  originalUnitPrice: 149
                  lineTotalPrice: 298
                  lineTotalDiscount: 10
                  lineTotalPaid: 198
                  productTags:
                    - outlet
                  primaryProductCategory: trousers
                  productVendor: ifreturns
            fulfillments:
              description: List of shipments for the order
              type: array
              items:
                type: object
                properties:
                  id:
                    description: Fulfillment ID
                    type: string
                    example: '2454552154'
                  fulfilledAt:
                    description: Date when the order was fulfilled
                    type: string
                    example: '2024-07-02'
                    format: date
                  deliverAt:
                    description: Date when the order was delivered
                    type: string
                    example: '2024-07-04'
                    format: date
                  fulfillmentCenter:
                    description: Name of the fulfillment center
                    type: string
                    example: MAIN_WAREHOUSE
                  fulfillmentCenterCountryCode:
                    description: Country code where the fulfillment center is located
                    type: string
                    example: ES
                  shipmentCarrier:
                    description: Carrier name for the shipment
                    type: string
                    example: CORREOS
                  shipmentServiceName:
                    description: Type of the shipment service
                    type: string
                    example: Express Delivery
                  fulfillmentLineItems:
                    type: array
                    items:
                      type: object
                      properties:
                        lineItemid:
                          description: ID of the line item associated to the fulfillment
                          type: string
                        quantity:
                          description: Number of line items in the fulfillment.
                          type: number
                    example:
                      - lineItemid: '456456'
                        quantity: 1
                      - lineItemid: '456488'
                        quantity: 1
                required:
                  - fulfillmentCenter
        originAddress:
          description: Origin address for the return
          type: object
          required:
            - countryCode
            - postalCode
          properties:
            firstName:
              description: First Name of the origin address
              type: string
              example: Paul
            lastName:
              description: Last Name of the origin address
              type: string
              example: Doe
            line1:
              description: Origin address information
              type: number
              example: C. Juan de Mena 8
            line2:
              description: Additional information for the origin address
              type: string
              example: sótano
            city:
              description: City of the origin address
              type: string
              example: Madrid
            postalCode:
              description: Postal code of the origin address
              type: string
              example: '28010'
            regionCode:
              description: Region code of the origin address
              type: string
              example: M
            countryCode:
              description: Country code of the origin address
              type: string
              example: ES
        returnLineItems:
          description: List of items included in the return
          type: object
          required:
            - sku
            - quantity
            - lineTotalPaid
          properties:
            id:
              description: ID of the returned item
              type: string
              example: 456456
            name:
              type: string
              description: Name of returned item
              example: Oxford shirt M
            sku:
              type: string
              description: SKU of the returned item
              example: OSM123
            variantOptions:
              description: Options that define the product variant
              type: array
              items:
                type: object
                properties:
                  key:
                    type: string
                    description: Key of the option
                    example: color
                  value:
                    type: string
                    description: Value of the option
                    example: blue
            quantity:
              type: number
              description: Items units returned
              format: int
              example: 1
            originalUnitPrice:
              type: number
              description: original unit price of items ordered
              format: float
              example: 100
            lineTotalPrice:
              type: number
              description: Total price of the line item
              format: float
              example: 100
            lineTotalDiscount:
              type: number
              description: Total discount of the line item
              format: float
              example: 0
            lineTotalPaid:
              description: Total paid for the line item
              type: number
              format: float
              example: 100
            returnReasonCode:
              type: string
              example: size-bigger
            refundTypeCode:
              type: string
              example: ORIGINAL_PAYMENT_METHOD
            productTags:
              type: array
              items:
                type: string
              example:
                - new
                - color:blue
                - collection:summer
            primaryProductCategory:
              type: string
              example: shirts
            productVendor:
              type: string
              description: Vendor name associated to returned item
              example: iFreturns
        client:
          type: object
          required:
            - id
            - tier
          properties:
            id:
              description: Customer ID associated with the returned order
              type: string
              example: '2352123'
            totalAmountSpent:
              description: Amount spent by the customer in the merchant
              type: number
              format: float
              example: 1000,
            totalAmountReturned:
              description: Amount returned by the customer in the merchant
              type: number
              format: float
              example: 100,
            quantityPlacedOrders:
              description: Number of orders placed by the customer in the merchant
              type: number
              example: 1
            quantityReturns:
              description: Number of returns made by the customer in the merchant
              type: number
              example: 1
            tier:
              description: Customer classification tier
              type: string
              example: GOLD
    CalculatedReturnMethod:
      type: object
      properties:
        code:
          description: Code of the return method
          type: string
          example: marchelacolombinev2-drop-off-es
        serviceType:
          description: Service type for the return method
          type: string
          enum:
            - drop-off
            - pick-up
            - direct
            - do-it-yourself
            - drop-off-store
          example: drop-off
        currencyCode:
          description: >-
            Currency code of the return method. All amounts reported will be in
            this currency
          type: string
          example: EUR
        isLabelFree:
          description: >-
            Flag to indicate if the printing of shipping is required to deliver
            the return
          type: boolean
          example: false
        returnFee:
          description: Fee of the return method
          type: number
          format: float
          example: 4.99
        priority:
          description: Priority for the return method free
          type: number
          example: 1
        visible:
          description: Flag to state the return method should be displayed or hidden
          type: boolean
          example: true
        carrierService:
          description: Carrier service to create the shipping label
          type: object
          properties:
            code:
              description: Code of the carrier service connection
              type: number
              example: IF-UPS-EXPRESS-SAVER
            carrierDisplayName:
              description: carrier name configured for the connection
              type: string
              example: UPS
            carrierExternalCode:
              description: carrier name configured for the connection
              type: string
              example: '20000008'
        destinationLocation:
          type: object
          properties:
            code:
              description: Code of the destination
              type: string
              example: C40
            fullName:
              description: Name of the destination
              type: string
              example: MAIN_WAREHOUSE
            line1:
              type: string
              description: Destination address
              example: C. Juan de Mena 8
            line2:
              description: Additional information for the destination address
              type: string
              example: sótano
            city:
              description: City of the destination address
              type: string
              example: Madrid
            postalCode:
              description: Postal code of the destination address
              type: string
              example: '28010'
            regionCode:
              description: Region code of the destination address
              type: string
              example: M
            countryCode:
              description: Country code of the destination address
              type: string
              example: ES
            latitude:
              description: Latitude of the destination address
              type: string
              example: 40.3232434
            longitude:
              description: Longitude of the destination address
              type: string
              example: -3.3232434
            phone:
              description: Phone of the destination address
              type: string
              example: 34666666666
            email:
              description: Email of the destination address
              type: string
              example: warehouse@email.com
        promotions:
          type: array
          description: List of promotions activated for the return method
          items:
            type: object
            properties:
              promoType:
                type: string
                description: Type of the promotion applied
                enum:
                  - DISCOUNT_COUPON_FIXED
                  - DISCOUNT_COUPON_PERCENTAGE
                  - PRIORITY_REFUND
                example: DISCOUNT_COUPON_FIXED
              promoAmount:
                type: number
                description: >-
                  Amount of promotion applied. It will be informend for the type
                  DISCOUNT_COUPON_XYZ
                format: float
                example: 5.99
        refundMode:
          $ref: '#/components/schemas/RefundMode'
    CreateShippingLabelRequest:
      type: object
      required:
        - shipmentType
        - clientShipmentId
        - carrierServiceCode
        - origin
        - destination
        - labelFormat
      properties:
        shopCode:
          type: string
          description: >-
            Shop code which belongs the shipment. In case this field is not
            informed, it will be obtained from security context. In case it is
            informed, it will be validated against the security context
          example: marchelacolombine
        shipmentType:
          description: Shiptment type
          type: string
          enum:
            - DELIVERY
            - RETURN
          example: RETURN
        clientShipmentId:
          description: >-
            ID of the shipment assigned by the merchant. It will be communicated
            to the carrier in order to be printed in the label
          type: string
          example: SHP123
        clientShipmentName:
          description: Name of the shipment assigned by the merchant
          type: string
          example: S123
        carrierServiceCode:
          description: Code of the carrier connection
          type: string
          example: IF-UPS-EXPRESS-SAVER
        carrierOptions:
          type: object
          properties:
            customsOptions:
              type: object
              properties:
                exportTrackingNumber:
                  description: >-
                    In case of return, the tracking number of the exportation
                    shipment
                  type: string
                  example: 1ZW699A59506626197
            pudoOptions:
              type: object
              properties:
                pudoEnabled:
                  type: boolean
                  description: Flag to indicate if a PUDO location will be used
                  example: true
                pudoCode:
                  type: string
                  example: '2778782'
                  description: Code of the PUDO location
                pudoName:
                  type: string
                  example: New Bookstore
                  description: Name of the PUDO location
        labelFormat:
          $ref: '#/components/schemas/LabelFormatInput'
        tags:
          description: Tags assigned to the shipping label
          type: array
          items:
            type: string
          example:
            - salesChannel:retail
            - type:premium
        shipper:
          type: object
          description: Shipper for the transportation
          properties:
            fullName:
              type: string
              description: Full name of the shipper
              example: iF warehouse
            email:
              type: string
              description: Email associated to the shipper
              example: warehouse@if.com
            phone:
              type: string
              description: Phone associated to the shipper
              example: 34666666666
            address:
              $ref: '#/components/schemas/Address'
        origin:
          type: object
          description: Origin address for the transportation
          properties:
            fullName:
              type: string
              description: Full name associated to the origin
              example: Juan Perez
            code:
              type: string
              description: Code associated to the origin
              example: Juan Perez
            email:
              type: string
              description: Email associated to the origin
              example: customer@if.com
            phone:
              type: string
              description: Phone associated to the origin
              example: 34666666666
            address:
              $ref: '#/components/schemas/Address'
          required:
            - fullName
            - email
            - phone
        destination:
          description: Destination address for the transportation
          properties:
            fullName:
              type: string
              description: Full name of the destination
              example: iF warehouse
            code:
              type: string
              description: Code associated to the destination
            email:
              type: string
              description: Email associated to the destination
              example: warehouse@if.com
            phone:
              type: string
              description: Phone associated to the destination
              example: 34666666666
            address:
              $ref: '#/components/schemas/Address'
          required:
            - fullName
            - email
            - phone
        parcels:
          type: array
          items:
            $ref: '#/components/schemas/Parcel'
    CalculatePudosRequest:
      type: object
      required:
        - carrierServices
      properties:
        shopCode:
          type: string
          description: >-
            Shop code which belongs the shipment. In case this field is not
            informed, it will be obtained from security context. In case it is
            informed, it will be validated against the security context
          example: marchelacolombine
        carrierServices:
          description: >-
            List of carrier service connections from which the PUDOs will be
            obtained
          type: array
          items:
            type: object
            required:
              - code
            properties:
              code:
                type: string
                description: Code of the carrier service connection
          example:
            - code: IF-UPS-EXPRESS-SAVER
            - code: IF-SEUR-HOME2SHOP
        limit:
          description: Number of PUDOs to be listed
          type: number
          example: 10
        address:
          description: Reference address information
          type: string
          example: C. Juan de Mena 8
        city:
          description: City of the reference address
          type: string
          example: Madrid
        postalCode:
          description: Postal code of the reference address
          type: string
          example: '28010'
        countryCode:
          description: Country code of the reference address
          type: string
          example: ES
        latitude:
          description: >-
            Latitude of the reference address. If this field is informed will
            have more priority than address
          type: number
          format: float
          example: 40.323132
        longitude:
          description: >-
            Longitude of the reference address. If this field is informed will
            have more priority than address
          type: number
          format: float
          example: -3.434343
        range:
          description: Range search area in km. Min 1 and Max 20
          type: number
          example: 10
        locationType:
          $ref: '#/components/schemas/LocationType'
    CalculatedPudo:
      type: object
      properties:
        id:
          description: ID of the PUDO
          type: string
          example: P232
        name:
          type: string
          description: Name of the PUDO
          example: ABC Book Store
        email:
          type: string
          description: Email associated to the PUDO
          example: pudo@email.com
        phone:
          type: string
          description: Phone associated to the PUDO
          example: 34666666666
        address:
          type: string
          description: Address of the PUDO
          example: C. Ibiza 200
        city:
          type: string
          description: City name of the PUDO address
          example: Madrid
        postalCode:
          type: string
          description: Postal code of the PUDO address
          example: '28020'
        region:
          type: string
          description: Region name of the PUDO address
          example: Madrid
        countryCode:
          type: string
          description: Country ISO code of PUDO address
          example: ES
        latitude:
          description: Latitude for the PUDO address
          type: string
          example: 40.393132
        longitude:
          description: Longitude for the PUDO address address
          type: string
          example: -3.723233
        image:
          description: Image associated to the PUDO
          type: string
          example: https://pudo.com/image.jpeg
        openingHours:
          description: Opening hours of the PUDO
          type: array
          items:
            type: object
            properties:
              dayOfWeek:
                description: Day of the week. Start at 1-Monday
                type: number
                example: 1
              hours:
                type: array
                items:
                  description: Opening hours in the specific day
                  type: string
                  example: 9:30-13:00
    ErrorRespose:
      type: object
      properties:
        code:
          description: Error code
          type: string
          example: VA001
        message:
          type: string
          description: Error message
          example: The origin address is not valid
    CarrierErrorResponse:
      type: object
      properties:
        carrierName:
          type: string
          example: SEUR
        carrierService:
          type: string
          example: RETHOME
        code:
          type: string
          example: ER001
        message:
          type: string
          example: Zip code for sender address has an incorrect format
    Parcel:
      type: object
      required:
        - clientParcelId
        - description
      properties:
        clientParcelId:
          type: string
          description: Client reference for the parcel
          example: P001
        description:
          type: number
          description: Description of the parcel content
          example: Goods
        weight:
          type: number
          description: Weight of the parcel in grams
          example: 1000
        height:
          type: number
          description: Height of the parcel in centimeters
          example: 10
        length:
          type: number
          description: Height of the parcel in centimeters
          example: 10
        width:
          type: number
          description: Width of the parcel in centimeters
          example: 10
        items:
          type: array
          items:
            $ref: '#/components/schemas/ParcelItem'
    ParcelItem:
      type: object
      required:
        - hsCode
        - description
        - quantity
        - price
        - unitPrice
      properties:
        sku:
          type: string
          description: SKU of the declared items
          example: P9991
        barcode:
          type: string
          description: Barcode of the declared items
          example: 40159000
        description:
          type: string
          description: Description of the shipment content
          example: T-shirt blue XL
        hsCode:
          type: string
          description: Description of the shipment content
          example: 40159000
        weight:
          description: Weight of the content in kg
          type: number
          example: 1000
        quantity:
          description: Quantity of the declared items
          type: number
          example: 1
        unitPrice:
          description: Unit price of the declared items
          type: number
          format: float
          example: 120
        currencyCode:
          description: Unit price of the declared items
          type: string
          example: EUR
        originCountryCode:
          description: Country code of origin of the Goods
          type: string
          example: ES
    ShippingLabel:
      type: object
      properties:
        carrierCode:
          type: string
          description: Carrier code associated to the shipment
          example: ups
        carrierExternalCode:
          type: string
          description: External carrier code associated to the shipment
          example: 20000008
        carrierServiceCode:
          type: string
          description: Carrier service associated to the shipment
          example: IF-UPS-EXPRESS-SAVER
        clientShipmentId:
          type: string
          description: ID of the shipment assigned by the merchant
          example: SHP123
        shippingLabels:
          type: array
          description: List of shipping labels
          items:
            type: object
            properties:
              carrierTrackingCode:
                type: string
                description: Reference assigned by the carrier to the shipment
                example: PARC0001
              carrierTrackingUrl:
                type: string
                description: URL for shipment tracking
                example: https://carrier.com/tracking/S4848554544545
              isLabelFree:
                description: Flag to indicate the shipment is label free
                type: boolean
                example: true
              labelFreeCode:
                type: object
                description: >-
                  Code to be used for the delivery of the package to the carrier
                  in the case of label-free shipments
                properties:
                  format:
                    $ref: '#/components/schemas/LabelFormat'
                  base64:
                    description: Label-free code in base64
                    type: string
                    example: AFJJJKJLDHKFJDLLKJKL...
                  url:
                    description: URL for getting the label-free code
                    type: string
                    example: https://if.com/image.png
              format:
                $ref: '#/components/schemas/LabelFormat'
              base64:
                description: Shipping label in base64
                type: string
                example: R0lGODlhLAGCAPcAAAAA...
              url:
                description: URL for getting the shipping label
                type: string
                example: https://if.com/shippping_label.pdf
    LabelFormatInput:
      type: string
      description: >-
        Allow to request a specific label format. In case is not informed, the
        default format for the carrier will be used. In case the carrier does
        not support the requested format, the default format for the carrier
        will be used. The final format will be included in the response
      enum:
        - PDF
        - ZPL
    LocationType:
      type: string
      description: >-
        Optional parameter used to filter PUDOs by location type. By default all
        location types are listed.
      enum:
        - ALL
        - STORE_POINT
        - LOCKER_POINT
    LabelFormat:
      type: string
      description: Format of the label or free-label code
      enum:
        - PDF
        - ZPL
        - PNG
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
security:
  - bearerAuth: []
