OpenAPI Specification
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