zaepho.zohobooks.zohobooks_item module – Manage ZohoBooks items

Note

This module is part of the zaepho.zohobooks collection (version 0.3.0).

It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install zaepho.zohobooks.

To use it in a playbook, specify: zaepho.zohobooks.zohobooks_item.

New in zaepho.zohobooks 0.2.0

Synopsis

  • Create, update, or delete items in ZohoBooks

  • Idempotent operations based on item name, or on SKU when the sku option is provided

Parameters

Parameter

Comments

access_token

string

ZohoBooks API access token

Can also be set via ZOHO_ACCESS_TOKEN environment variable

account_id

string

Income/Sales account ID

api_domain

string

ZohoBooks API domain

Can also be set via ZOHO_API_DOMAIN environment variable

Default: "https://www.zohoapis.com"

description

string

Description of the item

initial_stock

float

Initial stock quantity

initial_stock_rate

float

Rate of initial stock

inventory_account_id

string

Inventory account ID

is_taxable

boolean

Whether the item is taxable

Choices:

  • false

  • true

item_type

string

Type of item (inventory or non-inventory)

Choices:

  • "inventory"

  • "non_inventory"

name

string / required

Name of the item

organization_id

string

ZohoBooks organization ID

Can also be set via ZOHO_ORGANIZATION_ID environment variable

product_type

string

Type of product

Choices:

  • "goods"

  • "service"

  • "digital_service"

purchase_account_id

string

Account ID for purchases

purchase_rate

float

Purchase rate of the item

rate

float

Rate/price of the item

reorder_level

float

Reorder level for inventory

sku

string

Stock Keeping Unit (SKU) - must be unique

When provided, this is also used to look up the existing item instead of name

state

string

Desired state of the item

Choices:

  • "present" ← (default)

  • "absent"

  • "active"

  • "inactive"

tax_exemption_id

string

Tax exemption ID to apply when the item is not taxable

tax_id

string

Tax ID to apply to the item

tax_percentage

float

Tax percentage to apply

track_inventory

boolean

Whether to track inventory for this item

Choices:

  • false ← (default)

  • true

unit

string

Unit of measurement

Examples

- name: Create a goods item (using explicit parameters)
  zohobooks_item:
    organization_id: "123456789"
    access_token: "{{ zoho_access_token }}"
    name: "Hard Drive"
    rate: 120.00
    description: "500GB Hard Drive"
    sku: "HD-500GB-001"
    product_type: "goods"
    unit: "unit"
    state: present

- name: Create item using environment variables
  zohobooks_item:
    name: "Software License"
    rate: 99.99
    description: "Annual software license"
    product_type: "service"
    state: present
  environment:
    ZOHO_ORGANIZATION_ID: "123456789"
    ZOHO_ACCESS_TOKEN: "your_access_token"
    ZOHO_API_DOMAIN: "https://www.zohoapis.com"

- name: Create inventory item with initial stock
  zohobooks_item:
    organization_id: "123456789"
    access_token: "{{ zoho_access_token }}"
    name: "Widget A"
    rate: 25.00
    sku: "WGT-A-001"
    product_type: "goods"
    item_type: "inventory"
    track_inventory: true
    initial_stock: 100
    initial_stock_rate: 20.00
    reorder_level: 25
    state: present

- name: Update an existing item
  zohobooks_item:
    organization_id: "123456789"
    access_token: "{{ zoho_access_token }}"
    name: "Hard Drive"
    description: "Updated description - 1TB Hard Drive"
    rate: 150.00
    state: present

- name: Create/update a non-taxable item, looked up and upserted by SKU
  zohobooks_item:
    organization_id: "123456789"
    access_token: "{{ zoho_access_token }}"
    name: "Widget A - Digital"
    sku: "WGT-A-DIGITAL"
    rate: 9.99
    product_type: "digital_service"
    is_taxable: false
    tax_exemption_id: "123456789"
    account_id: "{{ sales_account_id }}"
    state: present

- name: Mark item as inactive
  zohobooks_item:
    organization_id: "123456789"
    access_token: "{{ zoho_access_token }}"
    name: "Old Product"
    state: inactive

- name: Mark item as active
  zohobooks_item:
    organization_id: "123456789"
    access_token: "{{ zoho_access_token }}"
    name: "Seasonal Product"
    state: active

- name: Delete an item
  zohobooks_item:
    organization_id: "123456789"
    access_token: "{{ zoho_access_token }}"
    name: "Discontinued Item"
    state: absent

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key

Description

changed

boolean

Whether the item was changed

Returned: always

item

dictionary

Item details

Returned: when state is present, active, or inactive

Sample: {"description": "500GB Hard Drive", "item_id": "123456789", "name": "Hard Drive", "product_type": "goods", "rate": 120.0, "sku": "HD-500GB-001", "status": "active"}

msg

string

Information about the operation

Returned: always

Authors

  • Kevin Colby (@zaepho)