OpenAPI Specification
openapi: 3.0.0
info:
title: batches landedcosts 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: landedcosts
description: LandedCosts Module
paths:
/bills/{bill_id}/landedcosts:
x-mcp-group:
- Landed Costs
parameters:
- name: bill_id
in: path
required: true
description: Unique identifier of the bill to which the landed cost is added.
schema:
type: string
example: '4815000000045067'
- $ref: '#/components/parameters/organization_id'
post:
tags:
- landedcosts
operationId: create_landed_cost_for_bill
summary: Creates a landed cost for a bill.
description: Create a landed cost for a bill. Use this to record additional charges such as shipping, customs, or handling against a bill, and allocate those charges across the line items of the bill using the chosen allocation method.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/create-a-landed-cost-for-bill-request'
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/create-a-landed-cost-for-bill-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.bills.CREATE
/bills/{bill_id}/landedcosts/{landed_cost_id}:
x-mcp-group:
- Landed Costs
parameters:
- name: bill_id
in: path
required: true
description: Unique identifier of the bill that the landed cost belongs to.
schema:
type: string
example: '4815000000045067'
- name: landed_cost_id
in: path
required: true
description: Unique identifier of the landed cost.
schema:
type: string
example: '4815000000049011'
- $ref: '#/components/parameters/organization_id'
get:
tags:
- landedcosts
operationId: get_landed_cost_for_bill
summary: Retrieves the details of a specific landed cost
description: Retrieve the details of a specific landed cost recorded against a bill, including the cost allocations across the bill line items.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/get-a-landed-cost-for-bill-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.bills.READ
put:
tags:
- landedcosts
operationId: update_landed_cost_for_bill
summary: Updates an existing landed cost on a bill.
description: Update an existing landed cost on a bill. The full landed cost record, including its allocations across the bill line items, is replaced with the values provided in the request body.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/update-a-landed-cost-for-bill-request'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/update-a-landed-cost-for-bill-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.bills.UPDATE
delete:
tags:
- landedcosts
operationId: delete_landed_cost_for_bill
summary: Deletes a landed cost from a bill.
description: Delete a landed cost from a bill. The allocated amounts are removed from the bill line items.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/delete-a-landed-cost-for-bill-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.bills.DELETE
/bills/bulklandedcosts:
x-mcp-group:
- Landed Costs
parameters:
- $ref: '#/components/parameters/organization_id'
post:
tags:
- landedcosts
operationId: create_bulk_landed_costs
summary: Create bulk landed costs
description: Create a landed cost from a single source transaction (such as a bill, bill of entry, or self-billed invoice) and allocate it across multiple bills in one call. Use this when a single charge, for example a freight invoice, needs to be distributed across more than one downstream bill.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/create-bulk-landed-costs-request'
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/create-bulk-landed-costs-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.bills.CREATE
/landedcosts/billdetails:
x-mcp-group:
- Landed Costs
parameters:
- $ref: '#/components/parameters/organization_id'
get:
tags:
- landedcosts
operationId: get_bill_details_for_bulk_landed_cost
summary: Get bill details for bulk landed cost
description: Retrieve the bill and line item details for one or more bills. Use this before calling the bulk landed cost endpoint to fetch the bill items that the landed cost can be allocated against.
parameters:
- name: bill_ids
in: query
description: Comma-separated list of bill IDs whose details are to be fetched. A maximum of 200 bill IDs can be passed in a single call.
required: true
schema:
type: string
example: 4815000000045067,4815000000045079
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/get-bill-details-for-bulk-landed-cost-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.bills.READ
components:
schemas:
currency_code:
description: ISO code of the currency in which the landed cost is recorded.
type: string
example: USD
create-bulk-landed-costs-response:
type: object
properties:
code:
type: integer
example: 0
readOnly: true
message:
type: string
example: The landed cost has been added.
readOnly: true
line_item_rate:
description: Unit rate of the bill line item in the currency of the bill.
type: number
format: double
example: 1200
reference_entity_number:
description: Number of the source transaction (for example, the bill number) from which the landed cost is recorded.
type: string
example: BILL-00045
create-a-landed-cost-for-bill-response:
type: object
properties:
code:
type: integer
example: 0
readOnly: true
message:
type: string
example: The landed cost has been added.
readOnly: true
landed_cost:
$ref: '#/components/schemas/landed-cost-for-bill-response'
package_width:
description: Width of the item package.
type: number
format: double
example: 10
package_height:
description: Height of the item package.
type: number
format: double
example: 2
bill_line_item:
type: object
properties:
bill_id:
$ref: '#/components/schemas/bill_id'
bill_item_id:
$ref: '#/components/schemas/bill_item_id'
item_id:
type: string
description: Unique identifier of the item.
example: '4815000000044100'
name:
$ref: '#/components/schemas/line_item_name'
sku:
type: string
description: Stock keeping unit of the item. Returned only when SKU is enabled for the organization.
example: SKU-001
description:
$ref: '#/components/schemas/line_item_description'
quantity:
$ref: '#/components/schemas/line_item_quantity'
unit:
type: string
description: Unit of measure of the line item.
example: qty
item_total:
$ref: '#/components/schemas/line_item_total'
package_details:
$ref: '#/components/schemas/package_details'
allocated_amount:
description: Amount of the landed cost allocated to the bill line item, in the currency of the bill.
type: number
format: double
example: 100
line_item_total:
description: Sub-total of the bill line item in the currency of the bill.
type: number
format: double
example: 2400
reference_entity_id:
description: Unique identifier of the source transaction (for example, the bill or self-billed invoice) from which the landed cost is recorded.
type: string
example: '4815000000045067'
vendor_name:
description: Display name of the vendor associated with the landed cost.
type: string
example: Molly
bill_item_id:
description: Unique identifier of the bill line item that the landed cost is allocated to.
type: string
example: '4815000000045071'
line_item_name:
description: Name of the bill line item.
type: string
example: Laptop-white/15inch/dell
update-a-landed-cost-for-bill-request:
type: object
allOf:
- $ref: '#/components/schemas/create-a-landed-cost-for-bill-request'
landed-cost-for-bill-response:
type: object
properties:
bill_id:
$ref: '#/components/schemas/bill_id'
bill_number:
$ref: '#/components/schemas/bill_number'
landed_cost_id:
$ref: '#/components/schemas/landed_cost_id'
vendor_id:
$ref: '#/components/schemas/vendor_id'
vendor_name:
$ref: '#/components/schemas/vendor_name'
reference_entity_id:
$ref: '#/components/schemas/reference_entity_id'
reference_item_id:
$ref: '#/components/schemas/reference_item_id'
reference_entity_type:
description: Type of the source transaction. Allowed values <code>bill</code>, <code>bill_of_entry</code> and <code>self_billed_invoice</code>.
type: string
example: bill
reference_entity_number:
$ref: '#/components/schemas/reference_entity_number'
price_precision:
$ref: '#/components/schemas/price_precision'
amount:
$ref: '#/components/schemas/amount'
currency_id:
$ref: '#/components/schemas/currency_id'
currency_code:
$ref: '#/components/schemas/currency_code'
currency_symbol:
$ref: '#/components/schemas/currency_symbol'
account_id:
$ref: '#/components/schemas/account_id'
account_name:
$ref: '#/components/schemas/account_name'
description:
$ref: '#/components/schemas/description'
allocation_method:
$ref: '#/components/schemas/allocation_method'
cost_allocations:
$ref: '#/components/schemas/cost_allocations_for_bill'
package_details:
description: Package dimensions and weight of the item, used when the allocation method is <code>dimension</code> or <code>weight</code>. Returned only when Zoho Inventory is enabled.
type: object
properties:
length:
$ref: '#/components/schemas/package_length'
width:
$ref: '#/components/schemas/package_width'
height:
$ref: '#/components/schemas/package_height'
weight:
$ref: '#/components/schemas/package_weight'
weight_unit:
$ref: '#/components/schemas/weight_unit'
dimension_unit:
$ref: '#/components/schemas/dimension_unit'
account_id:
description: Unique identifier of the expense account against which the landed cost is recorded.
type: string
example: '4815000000035003'
bill_id:
description: Unique identifier of the bill that the landed cost belongs to.
type: string
example: '4815000000045067'
label_rate:
description: Updated label (MRP) rate for the bill line item after the landed cost is applied. Returned only when MRP is enabled for the organization.
type: number
format: double
example: 0
bill_number:
description: Number of the bill that the landed cost belongs to.
type: string
example: BILL-00045
weight_unit:
description: Unit of measure for the package weight.
type: string
example: kg
allocation_method:
description: Method used to distribute the landed cost across the bill line items. Allowed values <code>quantity</code>, <code>amount</code>, <code>dimension</code> and <code>weight</code>.
type: string
example: quantity
sales_rate:
description: Updated sales rate for the bill line item after the landed cost is applied.
type: number
format: double
example: 0
price_precision:
description: Number of decimal places used to store the landed cost amounts.
type: integer
example: 2
bill_details:
type: object
properties:
bill_id:
$ref: '#/components/schemas/bill_id'
bill_number:
$ref: '#/components/schemas/bill_number'
date:
type: string
description: Date of the bill in <code>yyyy-mm-dd</code> format.
example: '2015-05-28'
vendor_id:
$ref: '#/components/schemas/vendor_id'
vendor_name:
$ref: '#/components/schemas/vendor_name'
status:
type: string
description: Current status of the bill.
example: open
total:
type: number
format: double
description: Total amount of the bill in the currency of the bill.
example: 2400
currency_id:
$ref: '#/components/schemas/currency_id'
currency_code:
$ref: '#/components/schemas/currency_code'
currency_symbol:
$ref: '#/components/schemas/currency_symbol'
exchange_rate:
type: number
format: double
description: Exchange rate of the currency of the bill against the base currency of the organization.
example: 1
price_precision:
$ref: '#/components/schemas/price_precision'
line_items:
type: array
description: Line items of the bill that the landed cost can be allocated to.
items:
$ref: '#/components/schemas/bill_line_item'
update-a-landed-cost-for-bill-response:
type: object
properties:
code:
type: integer
example: 0
readOnly: true
message:
type: string
example: The landed cost has been updated.
readOnly: true
landed_cost:
$ref: '#/components/schemas/landed-cost-for-bill-response'
reference_item_id:
description: Unique identifier of the line item in the source transaction that represents the landed cost.
type: string
example: '4815000000045071'
bulk-landed-cost-bill-allocation:
type: object
properties:
bill_id:
type: string
description: Unique identifier of the bill that the landed cost is being allocated to.
example: '4815000000045067'
vendor_id:
$ref: '#/components/schemas/vendor_id'
cost_allocations:
description: Distribution of the landed cost across the line items of the bill. At least one entry is required.
type: array
items:
type: object
properties:
bill_item_id:
type: string
description: Unique identifier of the bill line item.
example: '4815000000045071'
allocated_amount:
$ref: '#/components/schemas/allocated_amount'
create-a-landed-cost-for-bill-request:
type: object
required:
- cost_allocations
properties:
vendor_id:
$ref: '#/components/schemas/vendor_id'
reference_entity_id:
$ref: '#/components/schemas/reference_entity_id'
reference_item_id:
$ref: '#/components/schemas/reference_item_id'
reference_entity_type:
description: Type of the source transaction. Allowed values <code>bill</code>, <code>bill_of_entry</code> and <code>self_billed_invoice</code>.
type: string
example: bill
account_id:
$ref: '#/components/schemas/account_id'
description:
$ref: '#/components/schemas/description'
allocation_method:
$ref: '#/components/schemas/allocation_method'
cost_allocations:
description: Distribution of the landed cost across the line items of the bill. At least one entry is required.
type: array
items:
$ref: '#/components/schemas/cost_allocation_for_bill_request'
delete-a-landed-cost-for-bill-response:
type: object
properties:
code:
type: integer
example: 0
readOnly: true
message:
type: string
example: The landed cost has been deleted.
readOnly: true
landed_cost_id:
description: Unique identifier of the landed cost generated by the server.
type: string
example: '4815000000049011'
currency_symbol:
description: Symbol of the currency in which the landed cost is recorded.
type: string
example: $
get-a-landed-cost-for-bill-response:
type: object
properties:
code:
type: integer
example: 0
readOnly: true
message:
type: string
example: success
readOnly: true
landed_cost:
$ref: '#/components/schemas/landed-cost-for-bill-response'
currency_id:
description: Unique identifier of the currency in which the landed cost is recorded.
type: string
example: '4815000000044052'
dimension_unit:
description: Unit of measure for the package dimensions.
type: string
example: cm
get-bill-details-for-bulk-landed-cost-response:
type: object
properties:
code:
type: integer
example: 0
readOnly: true
message:
type: string
example: success
readOnly: true
bills:
type: array
description: Bill details for each requested bill, including the line items the landed cost can be allocated against.
items:
$ref: '#/components/schemas/bill_details'
account_name:
description: Name of the expense account against which the landed cost is recorded.
type: string
example: Freight and Forwarding Charges
cost_allocations_for_bill:
description: Distribution of the landed cost across the line items of the bill. Each entry contains the bill line item identifier and the amount allocated to it.
type: array
items:
type: object
properties:
bill_id:
$ref: '#/components/schemas/bill_id'
bill_item_id:
$ref: '#/components/schemas/bill_item_id'
allocated_amount:
$ref: '#/components/schemas/allocated_amount'
name:
$ref: '#/components/schemas/line_item_name'
description:
$ref: '#/components/schemas/line_item_description'
quantity:
$ref: '#/components/schemas/line_item_quantity'
rate:
$ref: '#/components/schemas/line_item_rate'
item_total:
$ref: '#/components/schemas/line_item_total'
package_details:
$ref: '#/components/schemas/package_details'
sales_rate:
$ref: '#/components/schemas/sales_rate'
label_rate:
$ref: '#/components/schemas/label_rate'
create-bulk-landed-costs-request:
type: object
properties:
reference_entity_id:
$ref: '#/components/schemas/reference_entity_id'
reference_item_id:
$ref: '#/components/schemas/reference_item_id'
reference_entity_type:
description: Type of the source transaction from which the bulk landed cost is recorded. Allowed values <code>bill</code>, <code>bill_of_entry</code> and <code>self_billed_invoice</code>.
type: string
example: bill
account_id:
$ref: '#/components/schemas/account_id'
description:
description: Description of the bulk landed cost.
type: string
example: Freight charges allocated across August shipments.
allocation_method:
$ref: '#/components/schemas/allocation_method'
bills:
description: Bills that the landed cost is allocated to. A maximum of 100 bills can be passed in a single call.
type: array
items:
$ref: '#/components/schemas/bulk-landed-cost-bill-allocation'
description:
description: Description of the landed cost. Max length [100].
type: string
example: Freight charges for the August shipment.
amount:
description: Total landed cost amount in the currency of the bill.
type: number
format: double
example: 250
cost_allocation_for_bill_request:
type: object
properties:
bill_item_id:
$ref: '#/components/schemas/bill_item_id'
allocated_amount:
$ref: '#/components/schemas/allocated_amount'
sales_rate:
$ref: '#/components/schemas/sales_rate'
label_rate:
$ref: '#/components/schemas/label_rate'
package_length:
description: Length of the item package.
type: number
format: double
example: 15
line_item_description:
description: Description of the bill line item.
type: string
example: Just a sample description.
vendor_id:
description: Unique identifier of the vendor associated with the landed cost.
type: string
example: '4815000000044080'
line_item_quantity:
description: Quantity of the bill line item.
type: number
format: double
example: 2
package_weight:
description: Weight of the item package.
type: number
format: double
example: 1.5
parameters:
organization_id:
name: organization_id
description: 'ID of the organization. Note: This value is a set of numeric characters.'
in: query
required: true
schema:
type: string
example: '10234695'
securitySchemes:
Zoho_Auth:
type: oauth2
flows:
implicit:
authorizationUrl: https://accounts.zoho.com/oauth/v2/auth
scopes:
ZohoInventory.items.CREATE: Create Items
ZohoInventory.items.READ: Read Items
ZohoInventory.items.UPDATE: Update Items
ZohoInventory.items.DELETE: Delete Items