openapi: 3.0.0
info:
  title: Sales Returns
  description: A Return Material Authorization (RMA) or Sales Return is the process of a seller accepting a purchased item back from the consumer. In turn, the customer receives credit, cash refund or a replacement.
  contact: {}
  version: 1.0.0
servers:
  - url: https://www.zohoapis.in/erp/v3
    description: API Endpoint
tags:
  - name: salesreturns
    description: SalesReturns Module
paths:
  /salesreturns:
    x-mcp-group:
      - Sales Returns
    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:
            - ERP.salesreturns.CREATE
    get:
      tags:
        - salesreturns
      operationId: list_sales_returns
      summary: List all Sales Returns
      description: Lists all the Sales Returns present in Zoho ERP.
      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:
            - ERP.salesreturns.READ
    parameters:
      - $ref: '#/components/parameters/organization_id'
  /salesreturns/{salesreturn_id}:
    x-mcp-group:
      - Sales Returns
    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:
            - ERP.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:
            - ERP.salesreturns.READ
    delete:
      tags:
        - salesreturns
      operationId: delete_sales_return
      summary: Delete a Sales Return
      description: Deletes a Sales Return from Zoho ERP.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/delete-a-sales-return-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ERP.salesreturns.DELETE
    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'
  /salesreturnreceives:
    x-mcp-group:
      - Sales Returns
    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:
            - ERP.salesreturnreceives.CREATE
    parameters:
      - $ref: '#/components/parameters/organization_id'
  /salesreturnreceives/{salesreturnreceive_id}:
    x-mcp-group:
      - Sales Returns
    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:
            - ERP.salesreturnreceives.DELETE
    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'
components:
  parameters:
    organization_id:
      name: organization_id
      description: ID of the organization
      in: query
      required: true
      schema:
        type: string
      example: '10234695'
  schemas:
    gendoc-attributes-schema:
      $ref: '#/components/schemas/salesreturn-response'
    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'
    salesreturn_id:
      description: Unique ID generated by the server for the Sales Return.
      type: string
      example: 4815000000044972
    salesreturn_number:
      description: Return Merchandise Authorization (RMA) number of the Sales Return.
      type: string
      example: RMA-00001
    reason:
      description: The reason for raising a Sales Return.
      type: string
      example: Sample Note
    customfield_id:
      type: string
      description: Unique identifier of the custom field.
      example: '46000000012845'
    value:
      description: Value of the Custom Field.
      type: string
      example: Normal
    custom_fields:
      description: Custom fields for a salesreturn.
      type: array
      items:
        type: object
        properties:
          customfield_id:
            $ref: '#/components/schemas/customfield_id'
          value:
            $ref: '#/components/schemas/value'
    date:
      description: Date on which the entity was created.
      type: string
      example: '2015-05-28'
    line_item_id:
      description: Unique ID generated by the server for each line item. This is used as an identifier.
      type: string
      example: 4815000000044897
    item_id:
      description: Unique ID generated by the server for the item. This is used as an identifier.
      type: string
      example: 4815000000044100
    name:
      description: Name of the line item.
      type: string
      example: Laptop-white/15inch/dell
    description:
      description: Description of the line item.
      type: string
      example: Just a sample description.
    unit:
      description: Measurement unit of the line item.
      type: string
      example: qty
    rate:
      description: Price of the line item in an entity.
      type: number
      format: double
      example: 122
    salesorder_item_id:
      description: Unique ID generated by the server for each line item in a sales order.
      type: string
      example: 4815000000044892
    quantity:
      description: The quantity that can be received for the line item.
      type: number
      format: double
      example: 3
    non_receive_quantity:
      description: The quantity that cannot be received for the line item.
      type: number
      format: double
      example: 2
    location_id:
      description: Location ID.
      type: string
      example: '460000000038080'
    location_name:
      description: Name of the location.
      type: string
      example: Head Office
    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'
          rate:
            $ref: '#/components/schemas/rate'
          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'
          location_name:
            $ref: '#/components/schemas/location_name'
    comment_id:
      description: Unique ID generated by the server for the comment(history). This is used as an identifier.
      type: string
      example: 16115000000097016
    commented_by:
      description: Indicates the user who performed the action on the purchase order.
      type: string
      example: John
    comment_type:
      description: Indicates the type of the action.
      type: string
    date_description:
      description: Indicates the time duration since the action was performed.
      type: string
      example: few seconds ago
    time:
      description: Indicates the time when the action was performed.
      type: string
      example: 2:18 PM
    operation_type:
      description: Type of operation performed on the transaction.
      type: string
      example: Updated
    transaction_id:
      description: Unique ID generated by the server for the transaction. This is used as an identifier.
      type: string
      example: 1232423434
    transaction_type:
      description: Indicates the type of transaction.
      type: string
      example: salesreturn
    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'
    salesreturn_status:
      description: Status of the Sales Return.
      type: string
      example: approved
    receive_status:
      description: Receive status of the Sales Return.
      type: string
      example: received
    refund_status:
      description: Refund status of the Sales Return.
      type: string
      example: refunded
    salesorder_id:
      description: Unique ID generated by the server for the Sales Order from which the Sales Return is created.
      type: string
      example: 4815000000044936
    salesorder_number:
      description: Unique sales order number for each sales order.
      type: string
      example: SO-00032
    customer_id:
      description: Unique ID generated by the server for the customer.
      type: string
      example: 4815000000044080
    customer_name:
      description: Name of the customer.
      type: string
      example: Molly
    refunded_amount:
      description: Total amount refunded to the customer.
      type: number
      format: double
      example: 2670
    receive_id:
      description: Unique ID generated by the server for the Sales Return Receive. This is used as an identifier.
      type: string
      example: 4815000000045035
    receive_number:
      description: Unique Sales Return Receive Number.
      type: string
      example: PR-00002
    notes:
      description: Notes for the current entity.
      type: string
      example: Sample Note
    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'
    creditnote_id:
      description: Unique ID of the credit note generated by the server.
      type: string
      example: 90300000072369
    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
    total:
      description: Total amount on the credit note.
      type: number
      format: double
      example: 2670
    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'
    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'
    create-a-sales-return-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: Return created successfully
          readOnly: true
        salesreturn:
          $ref: '#/components/schemas/salesreturn-response'
    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'
    update-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:
              line_item_id:
                $ref: '#/components/schemas/line_item_id'
              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'
    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'
            creditnotes:
              $ref: '#/components/schemas/creditnotes'
    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'
            creditnotes:
              $ref: '#/components/schemas/creditnotes'
    delete-a-sales-return-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: The Sales Return has been deleted.
          readOnly: true
    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'
        notes:
          $ref: '#/components/schemas/notes'
    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'
            notes:
              $ref: '#/components/schemas/notes'
    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
  securitySchemes:
    Zoho_Auth:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: https://accounts.zoho.in/oauth/v2/auth
          scopes:
            ERP.salesreturns.CREATE: Create Salesreturns
            ERP.salesreturns.UPDATE: Update Salesreturns
            ERP.salesreturns.READ: Read Salesreturns
            ERP.salesreturns.DELETE: Delete Salesreturns
            ERP.salesreturnreceives.CREATE: Create Salesreturnreceives
            ERP.salesreturnreceives.DELETE: Delete Salesreturnreceives
