OTO Global Return Shipments API

openapi: 3.0.3
info:
  title: OTO API V2 Account Return Shipments API
  version: 2.0.0
  description: 'Introduction OTO REST API provides seamless integration for managing shipments, tracking deliveries, and handling logistics operations. With powerful endpoints for creating, updating, and querying shipments, it ensures efficient and reliable communication between your systems and OTO''s platform. Overview We continuously analyze the e-commerce and logistics industries to enhance shipping and fulfillment processes, making them easier for vendors. OTO APIs are designed to automate and simplify key logistics operations, including: 🚀 Order Management – Process, update, and sync orders seamlessly. 🚀 Shipment Management – Create, manage, and track shipments effortlessly. 🚀 Return Management – Handle return requests and reverse logistics smoothly. 🚀 Stock Inventory Management – Keep inventory levels updated in real-time. 🚀 Product Management – Organize, update, and synchronize products efficiently. 🚀 Warehouse Management – Add, update, organize pickup locations. You can find guidance to assist you throughout the integration process here . Base URL: All API requests must be made over HTTPS to the following base endpoint: https://api.tryoto.com Meet our new OTO AI Assistant 🤖— a smart AI agent designed to help you navigate and use our REST API with ease. Whether you''re integrating for the first time or need help troubleshooting a request, our assistant is here to provide instant answers, example json responses, guide you through endpoints, and help you build faster.'
  contact:
    name: OTO Support
    url: https://help.tryoto.com/en/support/home
  x-source: derived from published OTO API V2 Postman collection (apis.tryoto.com)
servers:
- url: https://api.tryoto.com/rest/v2
  description: Production
- url: https://staging-api.tryoto.com/rest/v2
  description: Staging / sandbox
security:
- bearerAuth: []
tags:
- name: Return Shipments
  description: ''
paths:
  /rest/v2/createReturnShipment:
    post:
      operationId: createReturnShipment
      summary: Create Return Shipment
      tags:
      - Return Shipments
      description: 'This API endpoint creates a new return order for delivered forward orders. A new return order ID is generated by appending a suffix (e.g. -R1, -R2) to the original order ID and is returned in the response for return tracking and related operations. Return processing is handled on an item basis, meaning only the specified items are included in the return order and used for all return-related calculations. Example: Original order ID: ORD-1234 Order status: delivered Result: A new return order is c'
      requestBody:
        content:
          application/json:
            example:
              orderId: '202111080914'
              deliveryOptionId: '156'
              pickupLocationCode: wh1
              items:
              - quantity: '1'
                sku: SKU045857
            schema:
              type: object
      responses:
        '200':
          description: '200'
          content:
            application/json:
              example:
                success: true
                returnOrderId: 2204749035-R1
                message: A new return order is created for return shipment
  /rest/v2/getReturnLink:
    post:
      operationId: getReturnLink
      summary: Get Return Link
      tags:
      - Return Shipments
      description: 'This API endpoint generates a link that serves as a return request portal for end customers. The portal allows customers to initiate return requests seamlessly. Additionally, the portal''s details and settings can be customized in the OTO Dashboard to align with your specific requirements. Request Parameters: Name Required Type Description orderId yes string The order for which a return request is requested.'
      requestBody:
        content:
          application/json:
            example:
              orderId: '123'
            schema:
              type: object
      responses:
        '200':
          description: '200'
          content:
            application/json:
              example:
                success: true
                returnLink: https://app.tryoto.com/sms/return-request?key=Y3RnL0MwMTJiTFYwOVo5UnhGS0lOcU0xcnhBclRVMGwzTENGcjd4bEZCST0=
        '404':
          description: '404'
          content:
            application/json:
              example:
                success: false
                otoErrorCode: OTO1002
                otoErrorMessage: Order is not exist
        '400':
          description: '400'
          content:
            application/json:
              example:
                success: false
                otoErrorCode: OTO1001
                otoErrorMessage: Invalid or missing order Id
  /rest/v2/getReturnDetails:
    post:
      operationId: getReturnDetails
      summary: Get Return Details
      tags:
      - Return Shipments
      description: 'This API endpoint allows you to retrieve detailed information about the reverse shipment associated with a specific order. Reverse shipments are typically created when an order is returned or exchanged. This endpoint provides comprehensive insights into the reverse shipment process, including: return reason, returned items etc. Request Parameters: Name Required Type Description orderId yes string Id of the order Response Parameters: returnedItems: An array showing information about items to be r'
      requestBody:
        content:
          application/json:
            example:
              orderId: OID-9616-1008
            schema:
              type: object
      responses:
        '200':
          description: 200 OK
          content:
            application/json:
              example:
                returnLocationCode: Riyadh
                orderId: OID-9616-1008
                returnReason: Damaged
                items:
                - sku: '123456'
                  quantityOrdered: 1
                status: returned
        '401':
          description: 401 Unauthorized
          content:
            application/json:
              example:
                message: Jwt is expired
                code: 401
  /rest/v2/triggerReturnSms:
    post:
      operationId: triggerReturnSms
      summary: Trigger Return SMS
      tags:
      - Return Shipments
      description: 'This API endpoint will trigger an SMS for a successful return request, If your SMS settings are configured correctly. Please note that, since the SMS service operates asynchronously, the response does not confirm that the SMS has been delivered to the end customer. For a more detailed investigation of any SMS delivery issues, we recommend checking the SMS Logs under the Logs section in the OTO UI. Request Parameters: Name Required Type Description orderId yes string The orderId you want to trigg'
      requestBody:
        content:
          application/json:
            example:
              orderId: '523939'
            schema:
              type: object
      responses:
        '200':
          description: '200'
          content:
            application/json:
              example:
                success: true
                otoId: 3077435
        '400':
          description: '400'
          content:
            application/json:
              example:
                success: false
                otoErrorCode: OTO1002
                otoErrorMessage: Order is not exist
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Obtain an access_token by POSTing your refresh_token to /refreshToken, then send Authorization: Bearer <access_token>.'