Zoho Inventory salesreturns API

openapi: 3.0.0
info:
  title: batches salesreturns API
  description: Batches help you track inventory items by batch numbers, manufacturing dates, and expiration dates.
  contact: {}
  version: 1.0.0
servers:
- url: https://www.zohoapis.com/inventory/v1
  description: API Endpoint
tags:
- name: salesreturns
  description: SalesReturns Module
paths:
  /salesreturns:
    x-mcp-group:
    - Sales Returns
    parameters:
    - $ref: '#/components/parameters/organization_id'
    post:
      tags:
      - salesreturns
      operationId: create_sales_return
      summary: Create a Sales Return
      description: Creation of Sales Return. Sales return can be created for all the shipped units of the items in a sales order.
      parameters:
      - name: salesorder_id
        in: query
        description: Unique ID generated by the server for the Sales Order from which the Sales Return is created.
        required: false
        schema:
          type: string
        example: 4815000000044936
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create-a-sales-return-request'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/create-a-sales-return-response'
      deprecated: false
      security:
      - Zoho_Auth:
        - ZohoInventory.salesreturns.CREATE
    get:
      tags:
      - salesreturns
      operationId: list_sales_returns
      summary: List all Sales Returns
      description: Lists all the Sales Returns present in Zoho Inventory.
      parameters:
      - name: page
        in: query
        description: Page number to be fetched. Default value is 1.
        required: false
        schema:
          type: integer
          default: 1
        example: 1
      - name: per_page
        in: query
        description: Number of records to be fetched per page. Default value is 200.
        required: false
        schema:
          type: integer
          default: 200
        example: 200
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/list-all-sales-returns-response'
      deprecated: false
      security:
      - Zoho_Auth:
        - ZohoInventory.salesreturns.READ
  /salesreturns/{salesreturn_id}:
    x-mcp-group:
    - Sales Returns
    parameters:
    - name: salesreturn_id
      in: path
      required: true
      description: Unique identifier of the sales return.
      schema:
        type: string
      example: 4815000000044972
    - $ref: '#/components/parameters/organization_id'
    put:
      tags:
      - salesreturns
      operationId: update_sales_return
      summary: Update a Sales Return
      description: Updation of Sales Return.
      parameters:
      - name: salesorder_id
        in: query
        description: Unique ID generated by the server for the Sales Order from which the Sales Return is created.
        required: false
        schema:
          type: string
        example: 4815000000044936
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/update-a-sales-return-request'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/update-a-sales-return-response'
      deprecated: false
      security:
      - Zoho_Auth:
        - ZohoInventory.salesreturns.UPDATE
    get:
      tags:
      - salesreturns
      operationId: get_sales_return
      summary: Retrieve a Sales Return
      description: Retrieves the details for an existing Sales Return.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retrieve-a-sales-return-response'
      deprecated: false
      security:
      - Zoho_Auth:
        - ZohoInventory.salesreturns.READ
    delete:
      tags:
      - salesreturns
      operationId: delete_sales_return
      summary: Delete a Sales Return
      description: Deletes a Sales Return from Zoho Inventory.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/delete-a-sales-return-response'
      deprecated: false
      security:
      - Zoho_Auth:
        - ZohoInventory.salesreturns.DELETE
  /salesreturnreceives:
    x-mcp-group:
    - Sales Returns
    parameters:
    - $ref: '#/components/parameters/organization_id'
    post:
      tags:
      - salesreturns
      operationId: create_sales_return_receive
      summary: Create a Sales Return Receive
      description: Creating a sales return receive to mark the receivable goods as received.
      parameters:
      - name: salesreturn_id
        in: query
        description: Unique ID generated by the server for the Sales Return.
        required: false
        schema:
          type: string
        example: 4815000000044972
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create-a-sales-return-receive-request'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/create-a-sales-return-receive-response'
      deprecated: false
      security:
      - Zoho_Auth:
        - ZohoInventory.salesreturnreceives.CREATE
  /salesreturnreceives/{salesreturnreceive_id}:
    x-mcp-group:
    - Sales Returns
    parameters:
    - name: salesreturnreceive_id
      in: path
      required: true
      description: Unique identifier of the sales return receive.
      schema:
        type: string
      example: '4815000000044972'
    - $ref: '#/components/parameters/organization_id'
    delete:
      tags:
      - salesreturns
      operationId: delete_sales_return_receive
      summary: Delete a Sales Return Receive
      description: Deletes the sales return receive of a sales return.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/delete-a-sales-return-receive-response'
      deprecated: false
      security:
      - Zoho_Auth:
        - ZohoInventory.salesreturnreceives.DELETE
components:
  schemas:
    notes:
      description: Notes for the current entity.
      type: string
      example: Sample Note
    transaction_id:
      description: Unique ID generated by the server for the transaction. This is used as an identifier.
      type: string
      example: 1232423434
    create-a-sales-return-request:
      required:
      - line_items
      type: object
      properties:
        salesreturn_number:
          $ref: '#/components/schemas/salesreturn_number'
        date:
          $ref: '#/components/schemas/date'
        reason:
          $ref: '#/components/schemas/reason'
        custom_fields:
          $ref: '#/components/schemas/custom_fields'
        location_id:
          $ref: '#/components/schemas/location_id'
        line_items:
          description: The underlying items in a Sales Return
          type: array
          items:
            type: object
            properties:
              item_id:
                $ref: '#/components/schemas/item_id'
              salesorder_item_id:
                $ref: '#/components/schemas/salesorder_item_id'
              quantity:
                $ref: '#/components/schemas/quantity'
              non_receive_quantity:
                $ref: '#/components/schemas/non_receive_quantity'
              location_id:
                $ref: '#/components/schemas/location_id'
              mapped_items:
                $ref: '#/components/schemas/mapped_items_create'
    creditnote_id:
      description: Unique ID of the credit note generated by the server.
      type: string
      example: 90300000072369
    salesreturn-response:
      type: object
      properties:
        salesreturn_id:
          $ref: '#/components/schemas/salesreturn_id'
        salesreturn_number:
          $ref: '#/components/schemas/salesreturn_number'
        date:
          $ref: '#/components/schemas/date'
        reason:
          $ref: '#/components/schemas/reason'
        custom_fields:
          $ref: '#/components/schemas/custom_fields'
        line_items:
          $ref: '#/components/schemas/line_items'
        location_id:
          $ref: '#/components/schemas/location_id'
        location_name:
          $ref: '#/components/schemas/location_name'
        comments:
          $ref: '#/components/schemas/comments'
        salesreturn_status:
          $ref: '#/components/schemas/salesreturn_status'
        salesorder_id:
          $ref: '#/components/schemas/salesorder_id'
        salesorder_number:
          $ref: '#/components/schemas/salesorder_number'
    status:
      description: Status of the credit note.
      type: string
      example: closed
    creditnotes:
      description: List of credit notes associated with a sales return.
      type: array
      items:
        type: object
        properties:
          creditnote_id:
            $ref: '#/components/schemas/creditnote_id'
          creditnote_number:
            $ref: '#/components/schemas/creditnote_number'
          status:
            $ref: '#/components/schemas/status'
          date:
            $ref: '#/components/schemas/date'
          total:
            $ref: '#/components/schemas/total'
    label:
      description: Label of the Custom Field
      type: string
    transaction_type:
      description: Indicates the type of transaction.
      type: string
      example: salesreturn
    salesreturn_number:
      description: Return Merchandise Authorisation (RMA) number of the Sales Return.
      type: string
      example: RMA-00001
    commented_by:
      description: Indicates the user who performed the action on the purchase order.
      type: string
      example: John
    mapped_items_receive:
      description: Items that are associated with the composite item (kit) in the line item. Applicable only when the line item is a kit type composite item.
      type: array
      items:
        type: object
        properties:
          line_item_id:
            $ref: '#/components/schemas/line_item_id'
          item_id:
            $ref: '#/components/schemas/item_id'
          name:
            $ref: '#/components/schemas/name'
          description:
            $ref: '#/components/schemas/description'
          unit:
            $ref: '#/components/schemas/unit'
          quantity:
            $ref: '#/components/schemas/quantity'
          combo_type:
            $ref: '#/components/schemas/combo_type'
          mapped_items:
            description: Nested mapped items for kit within kit scenarios.
            type: array
            items:
              type: object
              properties:
                line_item_id:
                  $ref: '#/components/schemas/line_item_id'
                item_id:
                  $ref: '#/components/schemas/item_id'
                name:
                  $ref: '#/components/schemas/name'
                description:
                  $ref: '#/components/schemas/description'
                unit:
                  $ref: '#/components/schemas/unit'
                quantity:
                  $ref: '#/components/schemas/quantity'
                combo_type:
                  $ref: '#/components/schemas/combo_type'
    create-a-sales-return-receive-request:
      required:
      - line_items
      type: object
      properties:
        date:
          $ref: '#/components/schemas/date'
        line_items:
          description: The underlying items in a Sales Return
          type: array
          items:
            type: object
            properties:
              line_item_id:
                description: Unique ID generated by the server for each line item. This is used as an identifier.
                type: string
                example: 4815000000044897
              quantity:
                $ref: '#/components/schemas/quantity'
              mapped_items:
                description: Items that are associated with the composite item (kit) in the line item. Applicable only when the line item is a kit type composite item.
                type: array
                items:
                  type: object
                  properties:
                    line_item_id:
                      $ref: '#/components/schemas/line_item_id'
                    quantity:
                      $ref: '#/components/schemas/quantity'
                    mapped_items:
                      description: Nested mapped items for kit within kit scenarios.
                      type: array
                      items:
                        type: object
                        properties:
                          line_item_id:
                            $ref: '#/components/schemas/line_item_id'
                          quantity:
                            $ref: '#/components/schemas/quantity'
              serial_numbers:
                $ref: '#/components/schemas/serial_numbers'
              batches:
                $ref: '#/components/schemas/batches'
              storages:
                $ref: '#/components/schemas/storages'
        notes:
          $ref: '#/components/schemas/notes'
    salesreturn_status:
      description: Status of the Sales Return.
      type: string
      example: approved
    location_name:
      description: Name of the location
      type: string
      example: Head Office
    rate:
      description: Price of the line item in an entity.
      type: number
      format: double
      example: 122
    batches:
      description: Batches for the line item. Create a new batch using <code>batch_number</code> or reference an existing batch using <code>batch_id</code>. Applicable only for items with batch tracking enabled.
      type: array
      items:
        type: object
        required:
        - in_quantity
        properties:
          batch_id:
            description: Unique identifier of a batch. Use when adding inward quantity to an existing batch or updating a batch.
            type: string
            example: '6780203000001066789'
          batch_number:
            description: Batch number. Required when creating a new batch.
            type: string
            example: BTC-TL-890
          external_batch_number:
            description: External batch number from the manufacturer. Applicable when creating a new batch.
            type: string
            example: MFR-TL-890
          manufacturer_date:
            description: Manufacturing date of the batch. Applicable when creating a new batch.
            type: string
            example: '2026-05-12'
          expiry_date:
            description: Expiration date of the batch. Applicable when creating a new batch.
            type: string
            example: '2026-12-24'
          in_quantity:
            description: Inward quantity for the batch.
            type: number
            format: float
            example: 2
          storages:
            description: Bin/storage locations allocated for stock received against this batch.
            type: array
            x-node_available_in:
            - Batch with Bin tracked items
            items:
              type: object
              required:
              - storage_id
              - in_quantity
              properties:
                storage_id:
                  description: Unique identifier of the bin/storage location.
                  type: string
                  example: '6780203000001066003'
                in_quantity:
                  description: Inward quantity into the bin.
                  type: number
                  format: float
                  example: 2
    quantity:
      description: The quantity that can be received for the line item.
      type: number
      format: double
      example: 3
    storages-response:
      description: Bin/storage locations tracked for the line item. Returned for items with bin tracking enabled.
      type: array
      items:
        type: object
        properties:
          storage_id:
            description: Unique identifier of the bin/storage location.
            type: string
            example: '6780203000000093226'
          storage_name:
            description: Display name of the bin/storage location.
            type: string
            example: Bin A2
          in_quantity:
            description: Inward quantity recorded against the bin.
            type: number
            format: float
            example: 2
          storage_in_id:
            description: Unique identifier of the storage entry on the line item.
            type: string
            example: '6780203000001066795'
          serial_numbers:
            description: Serial numbers allocated to this bin.
            type: array
            x-node_available_in:
            - Serial with Bin tracked items
            items:
              type: string
              example: TC-IO-09
    receive_status:
      description: Receive status of the Sales Return
      type: string
      example: received
    item_id:
      description: Unique ID generated by the server for the item. This is used as an identifier.
      type: string
      example: 4815000000044100
    update-a-sales-return-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: Return updated successfully
          readOnly: true
        salesreturn:
          type: object
          properties:
            salesreturn_id:
              $ref: '#/components/schemas/salesreturn_id'
            salesreturn_number:
              $ref: '#/components/schemas/salesreturn_number'
            date:
              $ref: '#/components/schemas/date'
            reason:
              $ref: '#/components/schemas/reason'
            custom_fields:
              $ref: '#/components/schemas/custom_fields'
            location_id:
              $ref: '#/components/schemas/location_id'
            location_name:
              $ref: '#/components/schemas/location_name'
            line_items:
              $ref: '#/components/schemas/line_items'
            comments:
              $ref: '#/components/schemas/comments'
            salesreturn_status:
              $ref: '#/components/schemas/salesreturn_status'
            receive_status:
              $ref: '#/components/schemas/receive_status'
            refund_status:
              $ref: '#/components/schemas/refund_status'
            salesorder_id:
              $ref: '#/components/schemas/salesorder_id'
            salesorder_number:
              $ref: '#/components/schemas/salesorder_number'
            salesreturnreceives:
              description: List of sales return receives for the sales return
              type: array
              items:
                type: object
                properties:
                  receive_id:
                    $ref: '#/components/schemas/receive_id'
                  receive_number:
                    $ref: '#/components/schemas/receive_number'
                  date:
                    $ref: '#/components/schemas/date'
                  notes:
                    $ref: '#/components/schemas/notes'
                  line_items:
                    description: The underlying items in the sales return receive
                    type: array
                    items:
                      type: object
                      properties:
                        line_item_id:
                          $ref: '#/components/schemas/line_item_id'
                        item_id:
                          $ref: '#/components/schemas/item_id'
                        name:
                          $ref: '#/components/schemas/name'
                        description:
                          $ref: '#/components/schemas/description'
                        unit:
                          $ref: '#/components/schemas/unit'
                        quantity:
                          $ref: '#/components/schemas/quantity'
                        is_combo_product:
                          $ref: '#/components/schemas/is_combo_product'
                        combo_type:
                          $ref: '#/components/schemas/combo_type'
                        mapped_items:
                          $ref: '#/components/schemas/mapped_items_receive'
            creditnotes:
              $ref: '#/components/schemas/creditnotes'
    mapped_items_create:
      description: Items that are associated with the composite item (kit) in the line item. Applicable only when the line item is a kit type composite item.
      type: array
      items:
        type: object
        properties:
          item_id:
            $ref: '#/components/schemas/item_id'
          salesorder_item_id:
            $ref: '#/components/schemas/salesorder_item_id'
          quantity:
            $ref: '#/components/schemas/quantity'
          non_receive_quantity:
            $ref: '#/components/schemas/non_receive_quantity'
          location_id:
            $ref: '#/components/schemas/location_id'
          mapped_items:
            description: Nested mapped items for kit within kit scenarios.
            type: array
            items:
              type: object
              properties:
                item_id:
                  $ref: '#/components/schemas/item_id'
                salesorder_item_id:
                  $ref: '#/components/schemas/salesorder_item_id'
                quantity:
                  $ref: '#/components/schemas/quantity'
                non_receive_quantity:
                  $ref: '#/components/schemas/non_receive_quantity'
                location_id:
                  $ref: '#/components/schemas/location_id'
    comments:
      description: History related to the Sales Return.
      type: array
      items:
        type: object
        properties:
          comment_id:
            $ref: '#/components/schemas/comment_id'
          salesreturn_id:
            $ref: '#/components/schemas/salesreturn_id'
          commented_by:
            $ref: '#/components/schemas/commented_by'
          comment_type:
            $ref: '#/components/schemas/comment_type'
          date:
            $ref: '#/components/schemas/date'
          date_description:
            $ref: '#/components/schemas/date_description'
          time:
            $ref: '#/components/schemas/time'
          operation_type:
            $ref: '#/components/schemas/operation_type'
          transaction_id:
            $ref: '#/components/schemas/transaction_id'
          transaction_type:
            $ref: '#/components/schemas/transaction_type'
    combo_type:
      description: Type of the composite item. Allowed values are <code>assembly</code> and <code>kit</code>.
      type: string
      example: kit
    customer_id:
      description: Unique ID generated by the server for the customer.
      type: string
      example: 4815000000044080
    name:
      description: Name of the line item.
      type: string
      example: Laptop-white/15inch/dell
    retrieve-a-sales-return-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: success
          readOnly: true
        salesreturn:
          type: object
          properties:
            salesreturn_id:
              $ref: '#/components/schemas/salesreturn_id'
            salesreturn_number:
              $ref: '#/components/schemas/salesreturn_number'
            date:
              $ref: '#/components/schemas/date'
            reason:
              $ref: '#/components/schemas/reason'
            custom_fields:
              $ref: '#/components/schemas/custom_fields'
            location_id:
              $ref: '#/components/schemas/location_id'
            location_name:
              $ref: '#/components/schemas/location_name'
            line_items:
              $ref: '#/components/schemas/line_items'
            comments:
              $ref: '#/components/schemas/comments'
            salesreturn_status:
              $ref: '#/components/schemas/salesreturn_status'
            receive_status:
              $ref: '#/components/schemas/receive_status'
            refund_status:
              $ref: '#/components/schemas/refund_status'
            salesorder_id:
              $ref: '#/components/schemas/salesorder_id'
            salesorder_number:
              $ref: '#/components/schemas/salesorder_number'
            salesreturnreceives:
              description: List of sales return receives for the sales return
              type: array
              items:
                type: object
                properties:
                  receive_id:
                    $ref: '#/components/schemas/receive_id'
                  receive_number:
                    $ref: '#/components/schemas/receive_number'
                  date:
                    $ref: '#/components/schemas/date'
                  notes:
                    $ref: '#/components/schemas/notes'
                  line_items:
                    description: The underlying items in the sales return receive
                    type: array
                    items:
                      type: object
                      properties:
                        line_item_id:
                          $ref: '#/components/schemas/line_item_id'
                        item_id:
                          $ref: '#/components/schemas/item_id'
                        name:
                          $ref: '#/components/schemas/name'
                        description:
                          $ref: '#/components/schemas/description'
                        unit:
                          $ref: '#/components/schemas/unit'
                        quantity:
                          $ref: '#/components/schemas/quantity'
                        is_combo_product:
                          $ref: '#/components/schemas/is_combo_product'
                        combo_type:
                          $ref: '#/components/schemas/combo_type'
                        mapped_items:
                          $ref: '#/components/schemas/mapped_items_receive'
            creditnotes:
              $ref: '#/components/schemas/creditnotes'
    delete-a-sales-return-receive-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: Sales Return Receive Deleted Successfully.
          readOnly: true
    serial_numbers:
      description: Serial numbers for the line item. Applicable only for items with serial tracking enabled.
      type: array
      items:
        type: string
        example: TC-IO-09
    date:
      description: Date on which the entity was created.
      type: string
      example: '2015-05-28'
    customer_name:
      description: Name of the customer.
      type: string
      example: Molly
    receive_id:
      description: Unique ID generated by the server for the Sales Return Receive. This is used as an identifier.
      type: string
      example: 4815000000045035
    is_combo_product:
      description: Indicates whether the line item is a composite product.
      type: boolean
      example: true
    salesreturn_id:
      description: Unique ID generated by the server for the Sales Return.
      type: string
      example: 4815000000044972
    custom_fields:
      description: Custom fields for a salesreturn.
      type: array
      items:
        type: object
        properties:
          customfield_id:
            $ref: '#/components/schemas/customfield_id'
          label:
            $ref: '#/components/schemas/label'
          value:
            $ref: '#/components/schemas/value'
    customfield_id:
      type: string
      description: Unique ID of the custom field.
    creditnote_number:
      description: Unique number generated (starts with CN) which will be displayed in the interface and credit notes. Max-Length [100]
      type: string
      example: CN-0029
    time:
      description: Indicates the time when the action was performed
      type: string
      example: 2:18 PM
    total:
      description: Total amount on the credit note.
      type: number
      format: double
      example: 2670
    comment_type:
      description: Indicates the type of the action
      type: string
    non_receive_quantity:
      description: The quantity that cannot be received for the line item.
      type: number
      format: double
      example: 2
    line_item_id:
      description: Unique ID generated by the server for each line item. This is used as an identifier.
      type: string
      example: 4815000000044897
    value:
      description: Value of the Custom Field
      type: string
      example: Normal
    list-all-sales-returns-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: success
          readOnly: true
        salesreturns:
          type: object
          properties:
            salesreturn_id:
              $ref: '#/components/schemas/salesreturn_id'
            salesreturn_number:
              $ref: '#/components/schemas/salesreturn_number'
            date:
              $ref: '#/components/schemas/date'
            salesorder_id:
              $ref: '#/components/schemas/salesorder_id'
            salesorder_number:
              $ref: '#/components/schemas/salesorder_number'
            custom_fields:
              $ref: '#/components/schemas/custom_fields'
            customer_id:
              $ref: '#/components/schemas/customer_id'
            customer_name:
              $ref: '#/components/schemas/customer_name'
            salesreturn_status:
              $ref: '#/components/schemas/salesreturn_status'
            receive_status:
              $ref: '#/components/schemas/receive_status'
            refund_status:
              $ref: '#/components/schemas/refund_status'
            quantity:
              description: Total quantity of all the items in the sales return
              type: number
              format: double
              example: 5
            refunded_amount:
              $ref: '#/components/schemas/refunded_amount'
    refunded_amount:
      description: Total amount refunded to the customer.
      type: number
      format: double
      example: 2670
    create-a-sales-return-receive-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: Sales Return Receive Created Successfully
          readOnly: true
        salesreturn:
          type: object
          properties:
            receive_id:
              $ref: '#/components/schemas/receive_id'
            receive_number:
              $ref: '#/components/schemas/receive_number'
            salesreturn_id:
              $ref: '#/components/schemas/salesreturn_id'
            salesreturn_number:
              $ref: '#/components/schemas/salesreturn_number'
            date:
              $ref: '#/components/schemas/date'
            line_items:
              description: The underlying items in a Sales Return
              type: array
              items:
                type: object
                properties:
                  line_item_id:
                    $ref: '#/components/schemas/line_item_id'
                  item_id:
                    $ref: '#/components/schemas/item_id'
                  name:
                    $ref: '#/components/schemas/name'
                  description:
                    $ref: '#/components/schemas/description'
                  unit:
                    $ref: '#/components/schemas/unit'
                  quantity:
                    $ref: '#/components/schemas/quantity'
                  is_combo_product:
                    $ref: '#/components/schemas/is_combo_product'
   

# --- truncated at 32 KB (44 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/zoho-inventory/refs/heads/main/openapi/zoho-inventory-salesreturns-api-openapi.yml