openapi: 3.0.1
info:
  title: Carriyo Returns API
  description: |-
    Manage return requests: create, approve, and reject customer return requests, and track them through to reverse shipment. Covers the lookup reference data merchants configure for the returns workflow — reasons, rejection reasons, resolutions, refund types, and item conditions.
  version: "1.0"
  contact:
    name: Carriyo Support
    url: https://help.carriyo.com
    email: support@carriyo.com
tags:
  - name: Return Requests
    description: |-
      A Carriyo return object represents a customer return request. A return is created when a customer requests to return an item for some reason, such as the item arriving damaged, the product not matching its description, or the customer simply changing their mind.

      When a return is initiated, a business user can approve the request, which may result in the creation of a reverse shipment.

      The Carriyo Returns API allows the merchant to create, approve, reject and manage return requests. It also allows the merchant to define allowed return reasons, resolutions, and other return settings.
  - name: Return Reasons
    description: |-
      The merchant can configure a custom list of return reasons based on their business requirements. These reasons are presented as options to the customer on the return portal. Common examples include "Not as described online", "Arrived damaged", "Wrong colour or size".
  - name: Rejection Reasons
    description: |-
      The merchant can also configure a custom list of rejection reasons to use when rejecting a customer's request for return. These reasons are presented to the merchant as options when rejecting a return, and are used to communicate the rejection back to the customer.
  - name: Return Resolutions
    description: |-
      Return resolutions are outcomes that the customer is expecting from the return. The options can vary based on what the merchant offers but typically include "Credit card refund", "Store credit", or "Exchange".
  - name: Return Refund Types
    description: |-
      The merchant can configure a custom list of return refund types based on their business requirements. These refund types are presented as options to the customer on the return portal.
  - name: Return Item Conditions
    description: |-
      The merchant can configure a custom list of return item conditions based on their business requirements. These item conditions are presented as options to the customer on the return portal when describing the state of the item being returned.
  - name: Return Settings
    description: |-
      The return settings hold the general configuration for returns at the merchant level.
  - name: Return Comments
    description: |-
      The merchant can configure a custom list of return comments. Comments can be scoped to specific return reasons and are presented as options on the return portal.
paths:
  /returns/requests:
    post:
      responses:
        "200":
          description: Return request created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/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
      summary: Create return request
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/create-return-request"
      description: Creates a new return request. A pickup location is required so the reverse shipment can be created when the return request is approved.
      security:
        - OAuth2-Production: []
          ApiKey: []
          TenantId: []
        - OAuth2-Demo: []
          ApiKey: []
          TenantId: []
  /returns/available-items:
    get:
      responses:
        "200":
          description: Items still eligible for return on the order.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/return-request-remaining-item"
      summary: Get remaining items
      operationId: get-return-remaining-items
      tags:
        - Return Requests
      parameters:
        - in: query
          name: merchant
          required: true
          schema:
            type: string
        - in: query
          name: email_or_phone
          required: true
          schema:
            type: string
        - in: query
          name: partner_order_ref
          required: true
          schema:
            type: string
      description: Returns the items on the order that are still eligible for return.
      security:
        - OAuth2-Production: []
          ApiKey: []
          TenantId: []
        - OAuth2-Demo: []
          ApiKey: []
          TenantId: []
  /returns/available-locations:
    get:
      responses:
        "200":
          description: Drop-off locations available for the return.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/dropoff-object"
      summary: Get available locations
      operationId: get-return-available-locations
      tags:
        - Return Requests
      parameters:
        - in: query
          name: merchant
          required: true
          schema:
            type: string
        - in: query
          name: email_or_phone
          required: true
          schema:
            type: string
        - in: query
          name: partner_order_ref
          required: true
          schema:
            type: string
      description: Returns the customer's available collection locations, derived from delivered shipments.
  "/returns/requests/{return_request_id}":
    get:
      responses:
        "200":
          description: Returns the requested return request.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/return-request"
      summary: Get return request
      operationId: get-return-request
      tags:
        - Return Requests
      parameters:
        - name: return_request_id
          in: path
          required: true
          schema:
            type: string
      description: Returns the specified return request.
    patch:
      responses:
        "200":
          description: Return request updated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/return-request"
        "400":
          description: |-
            Returns 400 when
            * RMA is not in `PENDING` status.
      summary: Update return request
      operationId: update-return-request
      tags:
        - Return Requests
      parameters:
        - name: return_request_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/edit-return-request"
      description: Update properties of an existing return request. Allowed only while the request is in `PENDING` status; once approved, it cannot be modified.
  "/returns/requests/{return_request_id}/approve":
    patch:
      responses:
        "200":
          description: Return request approved.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/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: Approves the return request, sets its status to `APPROVED`, and creates the associated reverse shipment. The return request must have pickup and dropoff details at this point. Payment, if not supplied, is computed from the shipment items in the request.
      operationId: approve-return-request
      tags:
        - Return Requests
      parameters:
        - name: return_request_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/approve-return-request"
  "/returns/requests/{return_request_id}/cancel":
    patch:
      responses:
        "200":
          description: Return request cancelled.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/return-request"
      summary: Cancel return request
      description: Cancels the return request, sets its status to `CANCELLED`, and cancels the associated reverse shipment.
      operationId: cancel-return-request
      tags:
        - Return Requests
      parameters:
        - name: return_request_id
          in: path
          required: true
          schema:
            type: string
  "/returns/requests/{return_request_id}/reject":
    patch:
      responses:
        "200":
          description: Return request rejected.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/return-request"
      summary: Reject return request
      description: Rejects the return request with a reason.
      operationId: reject-return-request
      tags:
        - Return Requests
      parameters:
        - name: return_request_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                items:
                  type: array
                  items:
                    type: object
                    properties:
                      sku:
                        type: string
                      rejection_reason:
                        type: string
  "/returns/requests/{return_request_id}/receive":
    patch:
      responses:
        "200":
          description: Return request marked as received.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/return-request"
      summary: Receive return request
      description: Records receipt of the return request with the specified item quantities.
      operationId: receive-return-request
      tags:
        - Return Requests
      parameters:
        - name: return_request_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                items:
                  type: array
                  items:
                    type: object
                    properties:
                      sku:
                        type: string
                      received_quantity:
                        type: integer
  "/returns/requests/{return_request_id}/complete":
    patch:
      responses:
        "200":
          description: Return request completed.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/return-request"
      summary: Complete return request
      operationId: complete-return-request
      tags:
        - Return Requests
      parameters:
        - name: return_request_id
          in: path
          required: true
          schema:
            type: string
      description: Marks the return request as completed.
  "/returns/requests/{return_request_id}/notes":
    post:
      responses:
        "200":
          description: Note added to the return request.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/return-request"
      summary: Add note
      description: Adds a note to the return request.
      operationId: return-request-add-note
      tags:
        - Return Requests
      parameters:
        - in: header
          name: x-user
          required: true
          schema:
            type: string
        - name: return_request_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                text:
                  type: string
              required:
                - text
  "/returns/requests/{return_request_id}/notes/{note_id}":
    delete:
      responses:
        "200":
          description: Note deleted from the return request.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/return-request"
      summary: Delete note
      description: Deletes a note from the return request by ID.
      operationId: return-request-delete-note
      tags:
        - Return Requests
      parameters:
        - name: return_request_id
          in: path
          required: true
          schema:
            type: string
        - name: note_id
          in: path
          required: true
          schema:
            type: string
  /returns/reasons:
    post:
      responses:
        "200":
          description: Return reason created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/return-reason"
      operationId: create-return-reason
      tags:
        - Return Reasons
      summary: Create return reason
      requestBody:
        $ref: "#/components/requestBodies/return-reason"
      description: Creates a new return reason.
    get:
      responses:
        "200":
          description: Return reasons configured for the merchant.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/return-reason"
      summary: List return reasons
      tags:
        - Return Reasons
      operationId: list-return-reasons
      description: Returns the available return reasons for the merchant.
      parameters:
        - in: query
          name: merchant
          required: true
          schema:
            type: string
        - in: query
          name: language
          schema:
            type: string
  "/returns/reasons/{reason_code}":
    put:
      responses:
        "200":
          description: Return reason updated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/return-reason"
      summary: Update return reason
      description: Updates an existing return reason.
      operationId: update-return-reason
      tags:
        - Return Reasons
      parameters:
        - in: path
          name: reason_code
          required: true
          schema:
            type: string
      requestBody:
        $ref: "#/components/requestBodies/return-reason"
    delete:
      responses:
        "200":
          description: Return reason deleted.
          content:
            application/json:
              schema:
                type: object
                properties: {}
      summary: Delete return reason
      description: Deletes a return reason by code.
      operationId: delete-return-reason
      tags:
        - Return Reasons
      parameters:
        - in: query
          name: merchant
          required: true
          schema:
            type: string
        - in: path
          name: reason_code
          required: true
          schema:
            type: string
  /returns/rejection-reasons:
    post:
      responses:
        "200":
          description: Rejection reason created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/rejection-reason"
      summary: Create rejection reason
      requestBody:
        $ref: "#/components/requestBodies/rejection-reason"
      description: Creates a new rejection reason.
      operationId: create-return-rejection-reason
      tags:
        - Rejection Reasons
    get:
      responses:
        "200":
          description: Rejection reasons configured for the merchant.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/rejection-reason"
      summary: List rejection reasons
      description: Returns the available rejection reasons for the merchant.
      parameters:
        - in: query
          name: merchant
          schema:
            type: string
      operationId: list-return-rejection-reasons
      tags:
        - Rejection Reasons
  "/returns/rejection-reasons/{reason_code}":
    put:
      responses:
        "200":
          description: Rejection reason updated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/rejection-reason"
      summary: Update rejection reason
      description: Updates a rejection reason.
      operationId: update-return-rejection-reason
      tags:
        - Rejection Reasons
      parameters:
        - name: reason_code
          in: path
          required: true
          schema:
            type: string
      requestBody:
        $ref: "#/components/requestBodies/rejection-reason"
    delete:
      responses:
        "200":
          description: Rejection reason deleted.
          content:
            application/json:
              schema:
                type: object
                properties: {}
      summary: Delete rejection reason
      description: Deletes a rejection reason by code.
      operationId: delete-return-rejection-reason
      tags:
        - Rejection Reasons
      parameters:
        - in: query
          name: merchant
          required: true
          schema:
            type: string
        - name: reason_code
          in: path
          required: true
          schema:
            type: string
  /returns/resolutions:
    post:
      responses:
        "200":
          description: Return resolution created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/return-resolution"
      summary: Create return resolution
      description: Creates a new return resolution.
      operationId: create-return-resolution
      tags:
        - Return Resolutions
      requestBody:
        $ref: "#/components/requestBodies/return-resolution"
    get:
      responses:
        "200":
          description: Return resolutions configured for the merchant.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/return-resolution"
      summary: List return resolutions
      operationId: list-return-resolutions
      tags:
        - Return Resolutions
      parameters:
        - in: query
          name: merchant
          required: true
          schema:
            type: string
        - in: query
          name: language
          schema:
            type: string
      description: Returns the available return resolutions for the merchant.
  "/returns/resolutions/{resolution_code}":
    put:
      responses:
        "200":
          description: Return resolution updated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/return-resolution"
      summary: Update return resolution
      description: Updates a return resolution.
      operationId: update-return-resolution
      tags:
        - Return Resolutions
      parameters:
        - name: resolution_code
          in: path
          required: true
          schema:
            type: string
      requestBody:
        $ref: "#/components/requestBodies/return-resolution"
    delete:
      responses:
        "200":
          description: Return resolution deleted.
          content:
            application/json:
              schema:
                type: object
                properties: {}
      summary: Delete return resolution
      description: Deletes a return resolution by code.
      operationId: delete-return-resolution
      tags:
        - Return Resolutions
      parameters:
        - in: query
          name: merchant
          required: true
          schema:
            type: string
        - name: resolution_code
          in: path
          required: true
          schema:
            type: string
  /returns/refund-types:
    post:
      responses:
        "200":
          description: Refund type created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/return-refund-type"
      summary: Create return refund type
      requestBody:
        $ref: "#/components/requestBodies/return-refund-type"
      description: Creates a new return refund type.
      operationId: create-return-refund-type
      tags:
        - Return Refund Types
    get:
      responses:
        "200":
          description: Refund types configured for the merchant.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/return-refund-type"
      summary: List return refund types
      description: Returns the available return refund types for the merchant.
      parameters:
        - in: query
          name: merchant
          schema:
            type: string
      operationId: get-return-refund-types
      tags:
        - Return Refund Types
  "/returns/refund-types/{refund_type_code}":
    put:
      responses:
        "200":
          description: Refund type updated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/return-refund-type"
      summary: Update return refund type
      description: Updates a return refund type.
      operationId: update-return-refund-type
      tags:
        - Return Refund Types
      parameters:
        - name: refund_type_code
          in: path
          required: true
          schema:
            type: string
      requestBody:
        $ref: "#/components/requestBodies/return-refund-type"
    delete:
      responses:
        "200":
          description: Refund type deleted.
          content:
            application/json:
              schema:
                type: object
                properties: {}
      summary: Delete return refund type
      description: Deletes a return refund type by code.
      operationId: delete-return-refund-type
      tags:
        - Return Refund Types
      parameters:
        - in: query
          name: merchant
          required: true
          schema:
            type: string
        - name: refund_type_code
          in: path
          required: true
          schema:
            type: string
  "/returns/item-conditions/{item_condition_code}":
    put:
      responses:
        "200":
          description: Return item condition updated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/return-item-condition"
      summary: Update return item condition
      description: Updates a return item condition.
      operationId: update-return-item-condition
      tags:
        - Return Item Conditions
      parameters:
        - name: item_condition_code
          in: path
          required: true
          schema:
            type: string
      requestBody:
        $ref: "#/components/requestBodies/return-item-condition"
    delete:
      responses:
        "200":
          description: Return item condition deleted.
          content:
            application/json:
              schema:
                type: object
                properties: {}
      summary: Delete return item condition
      description: Deletes a return item condition by code.
      operationId: delete-return-item-condition
      tags:
        - Return Item Conditions
      parameters:
        - in: query
          name: merchant
          required: true
          schema:
            type: string
        - name: item_condition_code
          in: path
          required: true
          schema:
            type: string
  /returns/item-conditions:
    post:
      responses:
        "200":
          description: Return item condition created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/return-item-condition"
      summary: Create return item condition
      requestBody:
        $ref: "#/components/requestBodies/return-item-condition"
      description: Creates a new return item condition.
      operationId: create-return-item-condition
      tags:
        - Return Item Conditions
    get:
      responses:
        "200":
          description: Return item conditions configured for the merchant.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/return-item-condition"
      summary: List return item conditions
      description: Returns the available return item conditions for the merchant.
      parameters:
        - in: query
          name: merchant
          schema:
            type: string
      operationId: get-return-item-conditions
      tags:
        - Return Item Conditions
  /returns/settings:
    post:
      responses:
        "200":
          description: Return settings created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/return-request-settings"
      operationId: create-return-settings
      tags:
        - Return Settings
      summary: Create return settings
      requestBody:
        $ref: "#/components/requestBodies/return-request-settings"
      description: Creates the return settings for the merchant.
    get:
      responses:
        "200":
          description: Return settings for the merchant.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/return-request-settings"
      summary: Get return settings
      operationId: get-return-settings
      tags:
        - Return Settings
      parameters:
        - in: query
          name: merchant
          required: true
          schema:
            type: string
        - in: query
          name: notification_user_scope
          schema:
            type: string
        - in: query
          name: shopify_connector_id
          schema:
            type: string
        - in: query
          name: notification_user_id
          schema:
            type: string
      description: Returns the merchant's return settings.
    put:
      responses:
        "200":
          description: Return settings updated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/return-request-settings"
      summary: Update return settings
      description: Updates the merchant's return settings.
      operationId: update-return-settings
      tags:
        - Return Settings
      requestBody:
        $ref: "#/components/requestBodies/return-request-settings"
    delete:
      responses:
        "200":
          description: Return settings deleted.
          content:
            application/json:
              schema:
                type: object
                properties: {}
      summary: Delete return settings
      description: Deletes the merchant's return settings.
      operationId: delete-return-settings
      tags:
        - Return Settings
      parameters:
        - in: query
          name: merchant
          required: true
          schema:
            type: string
  /returns/requests/{return_request_id}/assign-to-user:
    patch:
      responses:
        '200':
          description: Return request assignment updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/return-request'
        '404':
          description: Return request not found for the supplied `return_request_id` and `tenant-id`.
      summary: Assign return request to a user
      operationId: assign-return-request
      description: Assigns the return request to a Carriyo dashboard user. The user identifier is typically an email.
      tags:
        - Return Requests
      parameters:
        - name: return_request_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/return-assign-to-user-request'
        required: true
      security:
        - OAuth2-Production: []
          ApiKey: []
          TenantId: []
        - OAuth2-Demo: []
          ApiKey: []
          TenantId: []
  "/returns/requests/{return_request_id}/split":
    patch:
      responses:
        "200":
          description: Items split into a new return request.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/return-request"
      summary: Split return request items
      description: Splits selected items out of the return request into a new return request, optionally assigning a pickup location.
      operationId: split-return-request-items
      tags:
        - Return Requests
      parameters:
        - name: return_request_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/split-return-request-items-request"
  "/returns/requests/{return_request_id}/status":
    patch:
      responses:
        "200":
          description: Return request status updated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/return-request"
        "400":
          description: Returns 400 when the supplied status is not a recognised return status.
      summary: Set return request status
      description: Directly sets the status of the return request to the value supplied in the `status` query parameter.
      operationId: change-return-request-status
      tags:
        - Return Requests
      parameters:
        - name: return_request_id
          in: path
          required: true
          schema:
            type: string
        - name: status
          in: query
          required: true
          description: The target return status.
          schema:
            type: string
            enum:
              - pending
              - on_hold
              - approved
              - completed
              - rejected
              - cancelled
              - returned
              - received
  "/returns/requests/{return_request_id}/refunds":
    post:
      responses:
        "200":
          description: Refund recorded against the return request.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/return-refund-info"
      summary: Add return refund
      description: Records a refund against the return request.
      operationId: add-return-refund
      tags:
        - Return Requests
      parameters:
        - name: return_request_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/refund-add-request"
  "/returns/requests/{return_request_id}/refunds/{refund_id}":
    delete:
      responses:
        "200":
          description: Refund removed from the return request.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/return-refund-info"
      summary: Delete return refund
      description: Removes a previously recorded refund from the return request.
      operationId: delete-return-refund
      tags:
        - Return Requests
      parameters:
        - name: return_request_id
          in: path
          required: true
          schema:
            type: string
        - name: refund_id
          in: path
          required: true
          schema:
            type: string
  /returns/comments:
    post:
      responses:
        "200":
          description: Return comment created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/return-comment"
      summary: Create return comment
      operationId: create-return-comment
      tags:
        - Return Comments
      description: Creates a new return comment.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/return-comment"
    get:
      responses:
        "200":
          description: Return comments configured for the merchant.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/return-comment"
      summary: List return comments
      operationId: list-return-comments
      tags:
        - Return Comments
      description: Returns the available return comments for the merchant.
      parameters:
        - in: query
          name: merchant
          required: true
          schema:
            type: string
        - in: query
          name: language
          schema:
            type: string
  "/returns/comments/{comment_code}":
    put:
      responses:
        "200":
          description: Return comment updated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/return-comment"
      summary: Update return comment
      description: Updates an existing return comment.
      operationId: update-return-comment
      tags:
        - Return Comments
      parameters:
        - in: path
          name: comment_code
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/return-comment"
    delete:
      responses:
        "200":
          description: Return comment deleted.
          content:
            application/json:
              schema:
                type: object
                properties: {}
      summary: Delete return comment
      description: Deletes a return comment by code.
      operationId: delete-return-comment
      tags:
        - Return Comments
      parameters:
        - in: query
          name: merchant
          required: true
          schema:
            type: string
        - in: path
          name: comment_code
          required: true
          schema:
            type: string
security:
  - OAuth2-Production: []
    ApiKey: []
    TenantId: []
  - OAuth2-Demo: []
    ApiKey: []
    TenantId: []
servers:
  - url: https://api.carriyo.com
    description: Production Server
  - url: https://demo-api.carriyo.com
    description: Demo Server
components:
  schemas:
    split-return-request-items-request:
      type: object
      title: Split return request items request
      description: Body for splitting items out of a return request into a new request.
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/return-split-item"
        partner_location_id:
          type: string
          description: Pickup location to assign to the new (split) return request.
    return-split-item:
      type: object
      title: Return split item
      properties:
        id:
          type: string
          description: The return request item id to split.
        split_quantity:
          type: integer
          description: Quantity of the item to move into the new return request.
        return_reason:
          type: string
        resolution:
          type: string
        return_item_condition:
          type: string
    refund-add-request:
      type: object
      title: Refund add request
      description: Body for recording a refund against a return request.
      properties:
        reference:
          type: string
        type:
          type: string
        amount:
          type: number
        currency:
          type: string
        note:
          type: string
        refund_date:
          type: string
          format: date-time
    return-comment:
      type: object
      title: Return comment
      properties:
        code:
          type: string
        name:
          type: string
        merchant:
          type: string
        allowed_return_reasons:
          type: array
          items:
            type: string
          description: Return reason codes this comment applies to.
        translations:
          $ref: "#/components/schemas/translation"
    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
        merchant:
          type: string
        status:
          type: string
          description: "[Click here for the list of Return Request Status Codes](https://carriyo.com/docs/api/returns/return-status-codes/)"
        pickup:
          $ref: "#/components/schemas/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: "#/components/schemas/return-request-item"
        refund_method:
          type: string
        refund_info:
          $ref: "#/components/schemas/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: "#/components/schemas/return-items-update"
        collection:
          allOf:
            - $ref: '#/components/schemas/return-collection'
          description: Scheduled collection window. Set when the return is collected from the customer.
        assigned_to_user:
          type: string
          description: Email or user identifier of the dashboard user the return request is assigned to.
        auto_closed:
          type: boolean
          description: True when the return request was automatically closed by the auto-close job (no progress within the configured window).
        auto_closed_date:
          type: string
          format: date-time
          description: Timestamp when the return request was auto-closed.
        creation_source:
          allOf:
            - $ref: '#/components/schemas/request-source'
          description: Identifies the system or actor that created the return request.
        update_source:
          allOf:
            - $ref: '#/components/schemas/request-source'
          description: Identifies the system or actor that last updated the return request.
        updated_by_user:
          type: string
          description: Email or user identifier of the dashboard user who last updated the return request.
    return-refund-info:
      type: object
      title: Return refund information
      properties:
        refunds:
          type: array
          items:
            $ref: "#/components/schemas/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: "#/components/schemas/pickup-request"
        channel:
          type: string
        partner_order_reference:
          type: string
        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: "#/components/schemas/pickup-request"
        items:
          type: array
          items:
            type: object
            properties:
              sku:
                type: string
              return_reason:
                type: string
              dropoff:
                $ref: "#/components/schemas/dropoff-request"
        resolution:
          type: string
    return-request-item:
      type: object
      title: Return request item
      properties:
        sku:
          type: string
        return_reason:
          type: string
        rejection_reason:
          type: string
        resolution:
          type: string
        description:
          type: string
        price:
          $ref: "#/components/schemas/return-request-item-price"
        dropoff:
          $ref: "#/components/schemas/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
        product_ref:
          type: string
          description: Merchant's product reference for the returned item.
        image_link:
          type: string
          description: Catalog image URL for the product.
        pre_defined_return_comments:
          type: array
          items:
            type: string
          description: Pre-defined comment codes selected by the customer for this item (from the comments configured against the return reason).
        reverse_shipments:
          type: array
          items:
            type: string
          description: IDs of the reverse shipments created for this returned item. Most returns have a single reverse shipment, but splits can produce multiple.
    return-request-item-price:
      type: object
      title: Return request item
      properties:
        amount:
          type: number
        currency:
          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: "#/components/schemas/translation"
    rejection-reason:
      type: object
      title: Rejection reason
      properties:
        code:
          type: string
        name:
          type: string
        merchant:
          type: string
        translations:
          $ref: "#/components/schemas/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: "#/components/schemas/translation"
    return-resolution:
      type: object
      title: Return resolution
      properties:
        code:
          type: string
        name:
          type: string
        merchant:
          type: string
        translations:
          $ref: "#/components/schemas/translation"
    return-item-condition:
      type: object
      title: Return item condition
      properties:
        code:
          type: string
        name:
          type: string
        merchant:
          type: string
        translations:
          $ref: "#/components/schemas/translation"
    return-request-remaining-item:
      type: object
      title: Return request remaining 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: "#/components/schemas/dropoff-object"
            UK:
              $ref: "#/components/schemas/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: "#/components/schemas/personal_id"
        street:
          type: string
        building:
          type: string
        floor:
          type: string
        flat:
          type: string
        po_box:
          type: string
        custom_fields:
          $ref: "#/components/schemas/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: "#/components/schemas/personal_id"
        building:
          type: string
        floor:
          type: string
        flat:
          type: string
        po_box:
          type: string
        custom_fields:
          $ref: "#/components/schemas/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. e.g., +442071234567
        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. e.g., +442071234567
        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 Geo List for more information.](https://carriyo.com/docs/guides/carriyo-geo-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: "#/components/schemas/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: "#/components/schemas/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. e.g., +442071234567
        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. e.g., +442071234567
        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 Geo List for more information.](https://carriyo.com/docs/guides/carriyo-geo-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: "#/components/schemas/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: "#/components/schemas/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
    request-source:
      title: Request Source
      type: object
      description: Identifies the system or actor that originated a return-request create or update.
      properties:
        source_type:
          type: string
          description: Originating system type (e.g. `api`, `dashboard`, `returns_service`).
        source_id:
          type: string
          description: Identifier of the originator (user id, system component).
        api_pattern:
          type: string
          description: For API-originated requests, the matched route pattern.
        request_type:
          type: string
          description: Logical operation name (e.g. `CREATE_RETURN_REQUEST`).
        system_log_identifier:
          type: string
          description: Correlation identifier for the system log entry.
    return-collection:
      title: Return collection
      type: object
      description: Scheduled collection window for the return shipment (when collection is required).
      properties:
        scheduled_from:
          type: string
          format: date-time
          description: Start of the collection window.
        scheduled_to:
          type: string
          format: date-time
          description: End of the collection window.
    return-assign-to-user-request:
      title: Return assign-to-user request
      type: object
      description: Body for `PATCH /returns/requests/{return_request_id}/assign-to-user`. Sets the dashboard user the return request is assigned to.
      required:
        - assigned_to_user
      properties:
        assigned_to_user:
          type: string
          description: Email or user identifier of the dashboard user to assign the return request to.
  requestBodies:
    rejection-reason:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/rejection-reason"
    return-reason:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/return-reason"
    return-resolution:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/return-resolution"
    return-refund-type:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/return-refund-type"
    return-item-condition:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/return-item-condition"
    return-request-settings:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/return-request-settings"
  securitySchemes:
    OAuth2-Production:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.carriyo.com/oauth/token
          scopes: {}
    OAuth2-Demo:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://demo-api.carriyo.com/oauth/token
          scopes: {}
    ApiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: "Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`."
    TenantId:
      type: apiKey
      in: header
      name: tenant-id
      description: "Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`."
