swagger: '2.0'
info:
  title: Carriyo Returns API
  version: ''
  contact:
    name: Carriyo Support
    url: 'htttps://help.carriyo.com'
    email: support@carriyo.com
  description:
    $ref: ../../api/returns/index.md
host: api.carriyo.com
paths:
  /returns/requests:
    post:
      responses:
        '200':
          description: ''
          schema:
            $ref: '#/definitions/return-request'
        '400':
          description: |-
            Returns 400 when
            * duplicated SKU found in request
            * the requested quantity is missing for some SKU
      operationId: create-return-request
      tags:
        - Return Requests
      consumes:
        - application/json
      produces:
        - application/json
      summary: Create Return Request
      parameters:
        - in: body
          name: body
          schema:
            $ref: '#/definitions/create-return-request'
        - in: header
          name: tenant-id
          type: string
      description: Creates new Return Request. Pickup location is mandatory in the request in order to successfully create reverse shipment on Return Request approval.
      security:
        - Oauth2.0: [ ]
  '/returns/requests/{return_request_id}':
    get:
      responses:
        '200':
          description: ''
          schema:
            $ref: '#/definitions/return-request'
      summary: Get Return Request
      operationId: get-return-request
      tags:
        - Return Requests
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: header
          name: tenant-id
          type: string
        - name: return_request_id
          in: path
          type: string
          required: true
      description: Return information about specific Return Request by its ID.
    patch:
      responses:
        '200':
          description: ''
          schema:
            $ref: '#/definitions/return-request'
        '400':
          description: |-
            Returns 400 when
            * RMA is not in `PENDING` status.
      summary: Update Return Request
      operationId: update-return-request
      tags:
        - Return Requests
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: body
          schema:
            $ref: '#/definitions/edit-return-request'
        - in: header
          name: tenant-id
          type: string
        - name: return_request_id
          in: path
          type: string
          required: true
      description: 'Update Return Request properties. This can be done only when RMA is in `PENDING` status. Once Return Request is approved, it cannot be modified.'
  '/returns/requests/{return_request_id}/approve':
    patch:
      responses:
        '200':
          description: ''
          schema:
            $ref: '#/definitions/return-request'
        '400':
          description: |-
            Returns 400 when:
            * dropoff location is missing in the resulted RMA object.
            * RMA is not in `PENDING` status.
      summary: Approve Return Request
      description: 'Sets Return Request to `APPROVED` status and creates reverse shipment according to Return Request properties. At this point Return Request is required to have pickup and dropoff details. Payment, if not specified, is calculated based on the shipment items present in request.'
      operationId: approve-return-request
      tags:
        - Return Requests
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: header
          name: tenant-id
          type: string
        - in: body
          name: body
          schema:
            $ref: '#/definitions/approve-return-request'
        - name: return_request_id
          in: path
          type: string
          required: true
  '/returns/requests/{return_request_id}/additional-references':
    patch:
      responses:
        '200':
          description: ''
          schema:
            $ref: '#/definitions/return-request'
        '400':
          description: |-
            Returns 400 when:
            * Tenant Id in the header is missing.
            * Return Request Id provided in the request path is missing.
            * Return Reference Edit Request is not provided in the request.
        '404':
          description: |-
            Returns 404 when:
            * Didn't find existing return request with the provided return request id and tenant id.
      summary: Update Additional References.
      description: 'This endpoint will override the additional reference provide in the existing return request.'
      operationId: edit-additional-references
      tags:
        - Return Requests
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: header
          name: tenant-id
          type: string
        - in: body
          name: body
          schema:
            $ref: '#/definitions/return-references-edit-request'
        - name: return_request_id
          in: path
          type: string
          required: true
  '/returns/requests/{return_request_id}/cancel':
    patch:
      responses:
        '200':
          description: ''
          schema:
            $ref: '#/definitions/return-request'
      summary: Cancel Return Request
      description: Sets Return Request status to `CANCELLED` and cancels associated reverse shipment.
      operationId: cancel-return-request
      tags:
        - Return Requests
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: header
          name: tenant-id
          type: string
        - name: return_request_id
          in: path
          type: string
          required: true
  '/returns/requests/{return_request_id}/reject':
    patch:
      responses:
        '200':
          description: ''
          schema:
            $ref: '#/definitions/return-request'
      summary: Reject Return Request
      description: Reject Return Request with a reason.
      operationId: reject-return-request
      tags:
        - Return Requests
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: header
          name: tenant-id
          type: string
        - in: body
          name: body
          schema:
            type: object
            properties:
              items:
                type: array
                items:
                  type: object
                  properties:
                    sku:
                      type: string
                    rejection_reason:
                      type: string
        - name: return_request_id
          in: path
          type: string
          required: true
  '/returns/requests/{return_request_id}/receive':
    patch:
      responses:
        '200':
          description: ''
          schema:
            $ref: '#/definitions/return-request'
      summary: Receive Return Request
      description: Receive Return Request with item quantities.
      operationId: receive-return-request
      tags:
        - Return Requests
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: header
          name: tenant-id
          type: string
        - in: body
          name: body
          schema:
            type: object
            properties:
              items:
                type: array
                items:
                  type: object
                  properties:
                    sku:
                      type: string
                    received_quantity:
                      type: integer
        - name: return_request_id
          in: path
          type: string
          required: true
  '/returns/requests/{return_request_id}/complete':
    patch:
      responses:
        '200':
          description: ''
          schema:
            $ref: '#/definitions/return-request'
      summary: Complete Return Request
      operationId: complete-return-request
      tags:
        - Return Requests
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: header
          name: tenant-id
          type: string
        - name: return_request_id
          in: path
          type: string
          required: true
      description: Marks Return Request as completed.
  '/returns/requests/{return_request_id}/notes':
    post:
      responses:
        '200':
          description: ''
          schema:
            $ref: '#/definitions/return-request'
      summary: Add Note
      description: Add Return Request Note.
      operationId: return-request-add-note
      tags:
        - Return Requests
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: header
          name: tenant-id
          type: string
          required: true
        - in: header
          name: x-user
          type: string
          required: true
        - in: body
          name: body
          schema:
            type: object
            properties:
              text:
                type: string
            required:
              - text
        - name: return_request_id
          in: path
          type: string
          required: true
  '/returns/requests/{return_request_id}/notes/{note_id}':
    delete:
      responses:
        '200':
          description: ''
          schema:
            $ref: '#/definitions/return-request'
      summary: Delete Note
      description: Delete Return Request note by ID.
      operationId: return-request-delete-note
      tags:
        - Return Requests
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: header
          name: tenant-id
          type: string
          required: true
        - name: return_request_id
          in: path
          type: string
          required: true
        - name: note_id
          in: path
          type: string
          required: true
  /returns/available-items:
    get:
      responses:
        '200':
          description: ''
          schema:
            type: array
            items:
              $ref: '#/definitions/return-request-remaining-item'
      summary: Get Remaining Items
      operationId: get-return-remaining-items
      tags:
        - Return Requests
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: header
          name: tenant-id
          type: string
        - in: query
          name: merchant
          type: string
          required: true
        - in: query
          name: email_or_phone
          type: string
          required: true
        - in: query
          name: partner_order_ref
          type: string
          required: true
      description: Returns the list of remaining items for return.
      security:
        - Oauth2.0: [ ]
  /returns/available-locations:
    get:
      responses:
        '200':
          description: ''
          schema:
            type: array
            items:
              $ref: '#/definitions/dropoff-object'
      summary: Get Available Locations
      operationId: get-return-available-locations
      tags:
        - Return Requests
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: query
          name: merchant
          type: string
          required: true
        - in: query
          name: email_or_phone
          type: string
          required: true
        - in: query
          name: partner_order_ref
          type: string
          required: true
        - in: header
          name: tenant-id
          type: string
          required: true
      description: Get the list of customer's available locations based on the delivered shipments.
  /returns/reasons:
    get:
      responses:
        '200':
          description: ''
          schema:
            type: array
            items:
              $ref: '#/definitions/return-reason'
      summary: Get Return Reasons
      tags:
        - Return Reasons
      operationId: list-return-reasons
      consumes:
        - application/json
      produces:
        - application/json
      description: Returns the list of available return reasons for a merhant.
      parameters:
        - in: query
          name: merchant
          type: string
          required: true
        - in: header
          name: tenant-id
          type: string
        - in: query
          name: language
          type: string
    post:
      responses:
        '200':
          description: ''
          schema:
            $ref: '#/definitions/return-reason'
      operationId: create-return-reason
      tags:
        - Return Reasons
      consumes:
        - application/json
      produces:
        - application/json
      summary: Create Return Reason
      parameters:
        - in: body
          name: body
          schema:
            $ref: '#/definitions/return-reason'
      description: Creates new reason for return.
  '/returns/reasons/{reason_code}':
    delete:
      responses:
        '200':
          description: ''
          schema:
            type: object
            properties: { }
      summary: 'Delete Return Reason '
      description: Delete return reason by code.
      operationId: delete-return-reason
      tags:
        - Return Reasons
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: query
          name: merchant
          type: string
          required: true
        - in: path
          name: reason_code
          type: string
          required: true
    put:
      responses:
        '200':
          description: ''
          schema:
            $ref: '#/definitions/return-reason'
      summary: Update Return Reason
      description: Update Return Reason properties.
      operationId: update-return-reason
      tags:
        - Return Reasons
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: body
          schema:
            $ref: '#/definitions/return-reason'
        - in: path
          name: reason_code
          type: string
          required: true
  /returns/resolutions:
    get:
      responses:
        '200':
          description: ''
          schema:
            type: array
            items:
              $ref: '#/definitions/return-resolution'
      summary: List Return Resolutions
      operationId: list-return-resolutions
      tags:
        - Return Resolutions
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: query
          name: merchant
          type: string
          required: true
        - in: header
          name: tenant-id
          type: string
        - in: query
          name: language
          type: string
      description: Returns the list of available resolutions for a merchant.
    post:
      responses:
        '200':
          description: ''
          schema:
            $ref: '#/definitions/return-resolution'
      summary: Create Return Resolution
      description: Creates new resolution.
      operationId: create-return-resolution
      tags:
        - Return Resolutions
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: body
          schema:
            $ref: '#/definitions/return-resolution'
  '/returns/resolutions/{resolution_code}':
    delete:
      responses:
        '200':
          description: ''
          schema:
            type: object
            properties: { }
      summary: Delete Return Resolution
      description: Deletes resolution by code.
      operationId: delete-return-resolution
      tags:
        - Return Resolutions
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: query
          name: merchant
          type: string
          required: true
        - name: resolution_code
          in: path
          type: string
          required: true
    put:
      responses:
        '200':
          description: ''
          schema:
            $ref: '#/definitions/return-resolution'
      summary: Update Return Resolution
      description: Updates resolution name.
      operationId: update-return-resolution
      tags:
        - Return Resolutions
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: body
          schema:
            $ref: '#/definitions/return-resolution'
        - name: resolution_code
          in: path
          type: string
          required: true
  /returns/rejection-reasons:
    get:
      responses:
        '200':
          description: ''
          schema:
            type: array
            items:
              $ref: '#/definitions/rejection-reason'
      summary: List Rejection Reasons
      description: Returns the list of available rejection reasons for a merhant.
      parameters:
        - in: query
          name: merchant
          type: string
        - in: header
          name: tenant-id
          type: string
      operationId: list-return-rejection-reasons
      tags:
        - Rejection Reasons
      consumes:
        - application/json
      produces:
        - application/json
    post:
      responses:
        '200':
          description: ''
          schema:
            $ref: '#/definitions/rejection-reason'
      summary: Create Rejection Reason
      parameters:
        - in: body
          name: body
          schema:
            $ref: '#/definitions/rejection-reason'
      description: Creates new rejection reason.
      operationId: create-return-rejection-reason
      tags:
        - Rejection Reasons
      consumes:
        - application/json
      produces:
        - application/json
  '/returns/rejection-reasons/{reason_code}':
    delete:
      responses:
        '200':
          description: ''
          schema:
            type: object
            properties: { }
      summary: Delete Rejection Reason
      description: Deletes rejection reason by code.
      operationId: delete-return-rejection-reason
      tags:
        - Rejection Reasons
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: query
          name: merchant
          type: string
          required: true
        - name: reason_code
          in: path
          type: string
          required: true
    put:
      responses:
        '200':
          description: ''
          schema:
            $ref: '#/definitions/rejection-reason'
      summary: Update  Rejection Reason
      description: Updates rejection reason name.
      operationId: update-return-rejection-reason
      tags:
        - Rejection Reasons
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: body
          schema:
            $ref: '#/definitions/rejection-reason'
        - name: reason_code
          in: path
          type: string
          required: true
  /returns/refund-types:
    get:
      responses:
        '200':
          description: ''
          schema:
            type: array
            items:
              $ref: '#/definitions/return-refund-type'
      summary: List Return Refund Types
      description: Returns the list of available refund types reasons for a merchant.
      parameters:
        - in: query
          name: merchant
          type: string
        - in: header
          name: tenant-id
          type: string
      operationId: get-return-refund-types
      tags:
        - Return Refund Types
      consumes:
        - application/json
      produces:
        - application/json
    post:
      responses:
        '200':
          description: ''
          schema:
            $ref: '#/definitions/return-refund-type'
      summary: Create Return Refund Type
      parameters:
        - in: body
          name: body
          schema:
            $ref: '#/definitions/return-refund-type'
      description: Creates new return refund type.
      operationId: create-return-refund-type
      tags:
        - Return Refund Types
      consumes:
        - application/json
      produces:
        - application/json
  '/returns/refund-types/{refund_type_code}':
    delete:
      responses:
        '200':
          description: ''
          schema:
            type: object
            properties: { }
      summary: Delete Return Refund Type
      description: Deletes return refund type by code.
      operationId: delete-return-refund-type
      tags:
        - Return Refund Types
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: query
          name: merchant
          type: string
          required: true
        - name: refund_type_code
          in: path
          type: string
          required: true
    put:
      responses:
        '200':
          description: ''
          schema:
            $ref: '#/definitions/return-refund-type'
      summary: Update Return Refund Type
      description: Updates return refund type.
      operationId: update-return-refund-type
      tags:
        - Return Refund Types
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: body
          schema:
            $ref: '#/definitions/return-refund-type'
        - name: refund_type_code
          in: path
          type: string
          required: true
  /returns/item-conditions:
    get:
      responses:
        '200':
          description: ''
          schema:
            type: array
            items:
              $ref: '#/definitions/return-item-condition'
      summary: List Return Refund Types
      description: Returns the list of available refund item conditions for a merchant.
      parameters:
        - in: query
          name: merchant
          type: string
        - in: header
          name: tenant-id
          type: string
      operationId: get-return-item-conditions
      tags:
        - Return Item Condition
      consumes:
        - application/json
      produces:
        - application/json
    post:
      responses:
        '200':
          description: ''
          schema:
            $ref: '#/definitions/return-item-condition'
      summary: Create Return Item Condition
      parameters:
        - in: body
          name: body
          schema:
            $ref: '#/definitions/return-item-condition'
      description: Creates new return item condition
      operationId: create-return-item-condition
      tags:
        - Return Item Condition
      consumes:
        - application/json
      produces:
        - application/json
  '/returns/item-conditions/{item_condition_code}':
    delete:
      responses:
        '200':
          description: ''
          schema:
            type: object
            properties: { }
      summary: Delete Return Item Condition
      description: Deletes return item condition by code.
      operationId: delete-return-item-condition
      tags:
        - Return Item Condition
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: query
          name: merchant
          type: string
          required: true
        - name: item_condition_code
          in: path
          type: string
          required: true
    put:
      responses:
        '200':
          description: ''
          schema:
            $ref: '#/definitions/return-item-condition'
      summary: Update Return Item Condition
      description: Updates Return Item Condition
      operationId: update-return-item-condition
      tags:
        - Return Refund Types
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: body
          schema:
            $ref: '#/definitions/return-item-condition'
        - name: item_condition_code
          in: path
          type: string
          required: true
  /returns/settings:
    get:
      responses:
        '200':
          description: ''
          schema:
            $ref: '#/definitions/return-request-settings'
      summary: Get Return Settings
      operationId: get-return-settings
      tags:
        - Return Settings
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: query
          name: merchant
          type: string
          required: true
        - in: query
          name: notification_user_scope
          type: string
        - in: query
          name: shopify_connector_id
          type: string
        - in: query
          name: notification_user_id
          type: string
        - in: header
          name: tenant-id
          type: string
          required: true
      description: Return settings object.
    post:
      responses:
        '200':
          description: ''
          schema:
            $ref: '#/definitions/return-request-settings'
      operationId: create-return-settings
      tags:
        - Return Settings
      consumes:
        - application/json
      produces:
        - application/json
      summary: Create Return Settings
      parameters:
        - in: header
          name: tenant-id
          type: string
          required: true
        - in: body
          name: body
          schema:
            $ref: '#/definitions/return-request-settings'
      description: Creates Return Settings for merchant.
    put:
      responses:
        '200':
          description: ''
          schema:
            $ref: '#/definitions/return-request-settings'
      summary: Update Return Settings
      description: Updates existing Return Settings.
      operationId: update-return-settings
      tags:
        - Return Settings
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: header
          name: tenant-id
          type: string
          required: true
        - in: body
          name: body
          schema:
            $ref: '#/definitions/return-request-settings'
    delete:
      responses:
        '200':
          description: ''
          schema:
            type: object
            properties: { }
      summary: Delete Return Settings
      description: Deletes Return Settings.
      operationId: delete-return-settings
      tags:
        - Return Settings
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: query
          name: merchant
          type: string
          required: true
        - in: header
          name: tenant-id
          type: string
          required: true
tags:
  - name: Return Requests
    description:
      $ref: ../../api/returns/return-requests.md
  - name: Return Reasons
    description:
      $ref: ../../api/returns/return-reasons.md
  - name: Rejection Reasons
    description:
      $ref: ../../api/returns/rejection-reasons.md
  - name: Return Resolutions
    description:
      $ref: ../../api/returns/return-resolutions.md
  - name: Return Refund Types
    description:
      $ref: ../../api/returns/return-refund-types.md
  - name: Return Item Conditions
    description:
      $ref: ../../api/returns/return-item-conditions.md
  - name: Return Settings
    description:
      $ref: ../../api/returns/return-settings.md
definitions:
  return-request:
    type: object
    title: Return Request
    description: 'Return Request object. '
    properties:
      return_request_id:
        type: string
        example: RMA_843X7O267D7T
      shipments:
        type: array
        items:
          type: string
        description: List of shipment ids associated with this return request.
      partner_order_reference:
        type: string
      additional_references:
        type: array
        items:
          $ref: '#/definitions/return-request-additional-reference'
        description: List of additional references associated with this return request.
      merchant:
        type: string
      status:
        type: string
        description: |-
          [Click here for the list of Return Request Status Codes](/docs/api/returns/return-status-codes/)
      pickup:
        $ref: '#/definitions/pickup-object'
      customer_comment:
        type: string
      channel:
        type: string
      notes:
        type: array
        items:
          type: object
          properties:
            email:
              type: string
            text:
              type: string
            date:
              type: string
            id:
              type: string
      items:
        type: array
        items:
          $ref: '#/definitions/return-request-item'
      refund_method:
        type: string
      refund_info:
        $ref: '#/definitions/return-refund-info'
      creation_date:
        type: string
      update_date:
        type: string
      approval_date:
        type: string
      cancellation_date:
        type: string
      rejection_date:
        type: string
      completion_date:
        type: string
      return_items_updates:
        type: array
        items:
          $ref: '#/definitions/return-items-update'
  return-refund-info:
    type: object
    title: Return Refund Information
    properties:
      refunds:
        type: array
        items:
          $ref: '#/definitions/return-refund'
  return-refund:
    type: object
    title: Return Refund
    properties:
      id:
        type: string
      reference:
        type: string
      type:
        type: string
      currency:
        type: string
      amount:
        type: number
      note:
        type: string
      creation_date:
        type: string
      refund_date:
        type: string
  create-return-request:
    type: object
    title: Return Request Create
    properties:
      merchant:
        type: string
      pickup:
        $ref: '#/definitions/pickup-request'
      channel:
        type: string
      partner_order_reference:
        type: string
      additional_references:
        type: array
        items:
          $ref: '#/definitions/return-request-additional-reference'
        description: List of additional references associated with this return request.
      items:
        type: array
        items:
          type: object
          properties:
            sku:
              type: string
            return_reason:
              type: string
            return_comments:
              type: string
            return_image_names:
              type: array
              items:
                type: string
            quantity:
              type: number
      comments:
        type: array
        items:
          type: object
          properties:
            email:
              type: string
            text:
              type: string
            date:
              type: string
      resolution:
        type: string
    required:
      - merchant
      - partner_order_reference
      - items
      - resolution
  edit-return-request:
    type: object
    title: Return Request Edit
    properties:
      pickup:
        $ref: '#/definitions/pickup-request'
      items:
        type: array
        items:
          type: object
          properties:
            sku:
              type: string
            return_reason:
              type: string
            dropoff:
              $ref: '#/definitions/dropoff-request'
      resolution:
        type: string
  return-references-edit-request:
    type: object
    title: Return Additional Reference Edit Request
    properties:
      additional_references:
        type: array
        items:
          $ref: '#/definitions/return-request-additional-reference'
  return-request-item:
    type: object
    title: Return Request Item
    properties:
      sku:
        type: string
      quantity:
        type: integer
      return_reason:
        type: string
      rejection_reason:
        type: string
      resolution:
        type: string
      reverse_shipment_id:
        type: string
      description:
        type: string
      price:
        $ref: '#/definitions/return-request-item-price'
      dropoff:
        $ref: '#/definitions/dropoff-object'
      return_comments:
        type: string
        description: User comments on the returning item based on the return reason code.
      return_images:
        type: array
        items:
          type: string
        description: Return item image urls uploaded by the end customer. These images are subjected to return reason.
      return_item_condition:
        type: string
        description: User selects one of the return item conditions defined by the merchant.
      requested_quantity:
        type: integer
      approved_quantity:
        type: integer
      returned_quantity:
        type: integer
      received_quantity:
        type: integer
  return-request-item-price:
    type: object
    title: Return Request Item
    properties:
      amount:
        type: number
      currency:
        type: string
  return-request-additional-reference:
    type: object
    title: Return Request Additional Reference
    properties:
      name:
        type: string
      value:
        type: string
  approve-return-request:
    type: object
    title: Return Request Approve
    properties:
      items:
        type: array
        items:
          type: object
          properties:
            sku:
              type: string
            return_reason:
              type: string
            approved_quantity:
              type: number
  return-reason:
    type: object
    title: Return Reason
    properties:
      code:
        type: string
      name:
        type: string
      merchant:
        type: string
      require_comments:
        type: boolean
        description: If this is enabled and user selects this return reason while creating the return request then they have to provide the comments.
      require_images:
        type: boolean
        description: If this is enabled and user selects this return reason while creating the return request then they have to upload the images of the product.
      require_item_condition:
        type: boolean
        description: If this is enabled and user selects this return reason while creating the return request then user has to choose one of the return item conditions.
      reverse_shipment_create_enabled:
        type: boolean
        description: If this is enabled and user selects this return reason while creating the return request then Carriyo will create a reverse shipment after the return request is approved.
      translations:
        $ref: '#/definitions/translation'
  rejection-reason:
    type: object
    title: Rejection Reason
    properties:
      code:
        type: string
      name:
        type: string
      merchant:
        type: string
      translations:
        $ref: '#/definitions/translation'
  return-refund-type:
    type: object
    title: Return Refund Type
    properties:
      code:
        type: string
      name:
        type: string
      merchant:
        type: string
      allowed_return_reasons:
        type: array
        items:
          type: string
      translations:
        $ref: '#/definitions/translation'
  return-resolution:
    type: object
    title: Return Resolution
    properties:
      code:
        type: string
      name:
        type: string
      merchant:
        type: string
      translations:
        $ref: '#/definitions/translation'
  return-item-condition:
    type: object
    title: Return Item Condition
    properties:
      code:
        type: string
      name:
        type: string
      merchant:
        type: string
      translations:
        $ref: '#/definitions/translation'
  return-request-remaining-item:
    type: object
    title: Return Request Remaning Item
    properties:
      sku:
        type: string
      quantity:
        type: integer
      description:
        type: string
      delivery_date:
        type: string
  translation:
    type: object
    title: Translation
    description: 'Key-value map, where key is a language (en, ru, uk etc.) and value is tranlsation.'
    properties:
      en:
        type: string
      ar:
        type: string
      uk:
        type: string
      ru:
        type: string
  return-request-settings:
    type: object
    title: Return Settings
    properties:
      merchant:
        type: string
      allowed_days_for_return:
        type: integer
      default_dropoff_locations:
        type: object
        description: 'Key-value map, where key is a country code and value is default dropoff location for this country code'
        properties:
          AE:
            $ref: '#/definitions/dropoff-object'
          UK:
            $ref: '#/definitions/dropoff-object'
      allow_undelivered_items:
        type: boolean
      allow_pickup_location_selection:
        type: boolean
      notification_users:
        type: array
        items:
          type: object
          properties:
            scope:
              type: string
            user_id:
              type: string
            active:
              type: boolean
      order_lookup_methods:
        type: array
        items:
          type: string
          enum:
            - email
            - phone
      shopify_integration_enabled:
        type: string
      shopify_connector_id:
        type: string
  return-items-update:
    type: object
    title: Return Request Items Update
    properties:
      shipment_id:
        type: string
      sku:
        type: string
      delta:
        type: string
      description:
        type: string
      origin_country:
        type: string
      notes:
        type: string
      price:
        type: object
        properties:
          amount:
            type: string
          currency:
            type: string
      weight:
        type: object
        properties:
          value:
            type: string
          unit:
            type: string
      hs_code:
        type: string
      dangerous_goods:
        type: boolean
  pickup-request:
    type: object
    title: Pickup Request
    description: 'Pickup request must contain all the neccessary information about the sender: their name, phone number, email, address, city and country. These properties will be given from the corresponding partner location, if either of following fields are specified instead: `partner_location_id`, `partner_location_name`, `partner_location_code`.'
    properties:
      partner_location_id:
        type: string
        description: only used to pass Carriyo internal location ID
      partner_location_name:
        type: string
        description: pass either partner_location_name or partner_location_code
      partner_location_code:
        type: string
        description: pass either partner_location_name or partner_location_code
      contact_name:
        type: string
      contact_phone:
        type: string
        format: E164 Format (with +<country-code> prefix)
      contact_email:
        type: string
        format: RFC 5322
      alternate_phone:
        type: string
        format: E164 Format (with +<country-code> prefix)
      address1:
        type: string
      address2:
        type: string
      area:
        type: string
      city:
        type: string
      state:
        type: string
      postcode:
        type: string
      country:
        type: string
      coords:
        type: array
        items:
          type: number
      type:
        type: string
      notes:
        type: string
      personal_id:
        $ref: '#/definitions/personal_id'
      street:
        type: string
      building:
        type: string
      floor:
        type: string
      flat:
        type: string
      po_box:
        type: string
      custom_fields:
        $ref: '#/definitions/custom-fields'
    required:
      - address1
  dropoff-request:
    type: object
    description: 'Dropoff request must contain all the neccessary information about the receiver: their name, phone number, email, address, city and country. These properties will be given from the corresponding partner location, if either of following fields are specified instead: `partner_location_id`, `partner_location_name`, `partner_location_code`.'
    title: Dropoff Request
    properties:
      partner_location_id:
        type: string
        description: only used to pass Carriyo internal location ID
      partner_location_name:
        type: string
        description: pass either partner_location_name or partner_location_code
      partner_location_code:
        type: string
        description: pass either partner_location_name or partner_location_code
      contact_name:
        type: string
      contact_phone:
        type: string
        format: E164 Format (with +<country-code> prefix)
      alternate_phone:
        type: string
        format: E164 Format (with +<country-code> prefix)
      contact_email:
        type: string
        format: RFC 5322
      address1:
        type: string
      address2:
        type: string
        format: Mandatory for SMSA
      area:
        type: string
      city:
        type: string
      state:
        type: string
      postcode:
        type: string
        format: Mandatory for SMSA
      country:
        type: string
      coords:
        type: array
        items:
          type: number
      type:
        type: string
      notes:
        type: string
      what3words:
        type: string
        format: ///three.word.address
      personal_id:
        $ref: '#/definitions/personal_id'
      building:
        type: string
      floor:
        type: string
      flat:
        type: string
      po_box:
        type: string
      custom_fields:
        $ref: '#/definitions/custom-fields'
  pickup-object:
    title: Pickup Object
    type: object
    properties:
      partner_location_id:
        type: string
        description: ID of the pickup location if it's provided by the merchant
      contact_name:
        type: string
        description: Name of the contact person
      contact_phone:
        type: string
        description: Phone number of the contact person in <E164 Format (with +<country-code> prefix)>
      contact_email:
        type: string
        description: Email address of the contact person
      alternate_phone:
        type: string
        description: Alternate phone number of the contact person in E164 Format (with +<country-code> prefix)
      address1:
        type: string
        description: Line 1 of the adddress
        example: 1 Bishopgate
      address2:
        type: string
        description: Line 2 of the adddress
      area:
        type: string
        description: |-
          District, suburb or neighbourhood, represented by the Carriyo Area Code if known. If not, it's a free text.

          [Please refer to the Carriyo Master List for more information.](/shipping/carriyo-master-list)
        example: DOWNTOWN-DUBAI
      input_area:
        type: string
        description: |-
          (Ready-only) Preserves the original input provided for "area". It is useful when Carriyo is instructed to automatically recognise the Carriyo area code.
        example: Downtown Dubai
      area_coords:
        type: array
        description: |-
          (Read-only) Approximate latitude and longitude for the area, if found in Carriyo's database. e.g., [25.1949849, 55.2784141]
        items:
          type: number
      input_city:
        type: string
        description: Original input city name from the client which get resolved into Carriyo city code.
        example: London
      city:
        type: string
        description: City part of the adddress - usually a Carriyo city code
        example: LONDON
      city_coords:
        type: array
        description: |-
          (Read-only) Approximate latitude and longitude for the city, if found in Carriyo's database. e.g., [25.1949849, 55.2784141]
        items:
          type: number
      state:
        type: string
        description: State part of the adddress
      input_state:
        type: string
        description: |-
          (Ready-only) Preserves the original input provided for "state". It is useful when Carriyo is instructed to automatically recognise the Carriyo state code.
        example: Dubai
      postcode:
        type: string
        description: Postal code part of the adddress
        example: E1 6AN
      country:
        type: string
        description: Country of the adddress represented as a 2-letter ISO code
        example: UK
      coords:
        type: array
        description: Latitude and longitude of the address represented in decimal degrees
        items:
          type: number
          example: 41.40338
      what3words:
        type: string
        format: ///three.word.address
      type:
        type: string
        description: Type of address
        enum:
          - residential
          - business
      notes:
        type: string
        description: Any additional notes
      personal_id:
        $ref: '#/definitions/personal_id'
      street:
        type: string
        description: Street number or name
      building:
        type: string
        description: Building number or name
      floor:
        type: string
        description: Floor number
      flat:
        type: string
        description: Flat number
      po_box:
        type: string
        description: Box number if the address is a PO Box
      custom_fields:
        $ref: '#/definitions/custom-fields'
  dropoff-object:
    title: Dropoff Object
    type: object
    properties:
      partner_location_id:
        type: string
        description: ID of the dropoff location if it's provided by the merchant
      collection_point_id:
        type: string
        description: ID of the carrier collection point
      contact_name:
        type: string
        description: Name of the contact person
      contact_phone:
        type: string
        description: Phone number of the contact person in <E164 Format (with +<country-code> prefix)>
      contact_email:
        type: string
        description: Email address of the contact person
      alternate_phone:
        type: string
        description: Alternate phone number of the contact person in E164 Format (with +<country-code> prefix)
      address1:
        type: string
        description: Line 1 of the adddress
        example: 1 Bishopgate
      address2:
        type: string
        description: Line 2 of the adddress
      area:
        type: string
        description: |-
          District, suburb or neighbourhood, represented by the Carriyo Area Code if known. If not, it's a free text.

          [Please refer to the Carriyo Master List for more information.](/shipping/carriyo-master-list)
        example: DOWNTOWN-DUBAI
      input_area:
        type: string
        description: |-
          (Ready-only) Preserves the original input provided for "area". It is useful when Carriyo is instructed to automatically recognise the Carriyo area code.
        example: Downtown Dubai
      area_coords:
        type: array
        description: |-
          (Read-only) Approximate latitude and longitude for the area, if found in Carriyo's database. e.g., [25.1949849, 55.2784141]
        items:
          type: number
      input_city:
        type: string
        description: Original input city name from the client which get resolved into Carriyo city code.
        example: London
      city:
        type: string
        description: City part of the adddress - usually a Carriyo city code
        example: LONDON
      city_coords:
        type: array
        description: |-
          (Read-only) Approximate latitude and longitude for the city, if found in Carriyo's database. e.g., [25.1949849, 55.2784141]
        items:
          type: number
      state:
        type: string
        description: State part of the adddress
      input_state:
        type: string
        description: |-
          (Ready-only) Preserves the original input provided for "state". It is useful when Carriyo is instructed to automatically recognise the Carriyo state code.
        example: Dubai
      postcode:
        type: string
        description: Postal code part of the adddress
        example: E1 6AN
      country:
        type: string
        description: Country of the adddress represented as a 2-letter ISO code
        example: UK
      coords:
        type: array
        description: Latitude and longitude of the address represented in decimal degrees
        items:
          type: number
          example: 41.40338
      type:
        type: string
        description: Type of address
        enum:
          - residential
          - business
      notes:
        type: string
        description: Any additional notes
      what3words:
        type: string
        format: ///three.word.address
      personal_id:
        $ref: '#/definitions/personal_id'
      street:
        type: string
        description: Street number or name
      building:
        type: string
        description: Building number or name
      floor:
        type: string
        description: Floor number
      flat:
        type: string
        description: Flat number
      po_box:
        type: string
        description: Box number if the address is a PO Box
      custom_fields:
        $ref: '#/definitions/custom-fields'
  personal_id:
    type: object
    title: Personal ID
    properties:
      id:
        type: string
      type:
        type: string
  custom-fields:
    type: object
    description: |-
      Custom address fields in the form of a map:
      ```
      {"field1" : ["value1", "value2"], "field2" : ["value1", "value2"]}
      ```
    additionalProperties:
      type: array
      items:
        type: string
    title: Custom Fields
parameters: { }
responses: { }
schemes:
  - https
securityDefinitions:
  Oauth2.0:
    type: oauth2
    flow: application
    tokenUrl: 'https://api.carriyo.com/oauth/token'
    scopes: { }
security:
  - Oauth2.0: [ ]