---
updatedAt: 2025-10-02T22:25:33.000Z
agentTools:
  projectIndex: https://developer.bill.com/v2/llms.txt
---

# Update an item

Update a new item object.

In your request, set `type` as an item category, such as service, inventory, or payment. See the parameters for the complete list of categories.

### What is an item?
An item object is useful for vendor bills and customer invoices. For customers, an item object describes what your organization provides. For vendors, the item object describes what is provided to your organization.

You can sync your items with your choice of account software or import using a CSV file.

### Display item in the BILL web app
You can display item numbers with the BILL web app.
1. In the BILL web app, click **SETTINGS** at the top-right.
2. Click **Preferences** under **Accounting**.
3. Click the edit icon at the top-right.
4. Set **Use Items in Payables** as **Yes** and then click **SAVE**.

# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "info": {
    "title": "Organization | Accounts tracking",
    "version": "2.0",
    "description": "BILL is a cloud-based cash flow management system for an organization's Accounts Payable (AP) and Accounts Receivable (AR) automation.\n * **AP**: Automate workflows to pay vendors bills at scale for the goods and services they provide. Pay vendors with a wide range of payment methods. Generate vendor credits, bill credits, and payment disbursement reports.\n * **AR**: Automate workflows to get paid by customers at scale for the goods and services you provide. Generate and send invoices on a schedule, generate customer and invoice credits, and seamlessly charge authorized customers.\n * **Organization**: Manage your bank accounts (for sending and receiving payments), users (with user roles), and sync with your choice of accounting software.\n\nIntegrate with the BILL API to send and receive payments for your business. See [Support Center](https://help.bill.com/hc/en-us) for resources about using the BILL web app.",
    "contact": {
      "email": "developerprogram@hq.bill.com"
    }
  },
  "servers": [
    {
      "url": "https://api-stage.bill.com/api/v2",
      "description": "Sandbox base URL"
    }
  ],
  "x-readme": {
    "samples-languages": [
      "curl",
      "java",
      "javascript",
      "python",
      "ruby"
    ],
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "paths": {
    "/Crud/Update/Item.json": {
      "post": {
        "summary": "Update an item",
        "operationId": "org-accounts-updateitem",
        "description": "Update a new item object.\n\nIn your request, set `type` as an item category, such as service, inventory, or payment. See the parameters for the complete list of categories.\n\n### What is an item?\nAn item object is useful for vendor bills and customer invoices. For customers, an item object describes what your organization provides. For vendors, the item object describes what is provided to your organization.\n\nYou can sync your items with your choice of account software or import using a CSV file.\n\n### Display item in the BILL web app\nYou can display item numbers with the BILL web app.\n1. In the BILL web app, click **SETTINGS** at the top-right.\n2. Click **Preferences** under **Accounting**.\n3. Click the edit icon at the top-right.\n4. Set **Use Items in Payables** as **Yes** and then click **SAVE**.",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateItemResponse"
                }
              }
            }
          }
        },
        "requestBody": {
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "required": [
                  "devKey",
                  "sessionId",
                  "data"
                ],
                "properties": {
                  "devKey": {
                    "type": "string",
                    "description": "Developer key generated with your BILL developer account"
                  },
                  "sessionId": {
                    "type": "string",
                    "description": "API session ID generated with [`/v2/Login.json`](ref:auth-login)"
                  },
                  "data": {
                    "$ref": "#/components/schemas/UpdateItemRequest"
                  }
                }
              }
            }
          }
        },
        "tags": [
          "Items"
        ]
      },
      "parameters": []
    }
  },
  "components": {
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error_code": {
            "type": "string",
            "description": "Error code (only when `response_status` is `1`)"
          },
          "error_message": {
            "type": "string",
            "description": "Error message (only when `response_status` is `1`)"
          }
        }
      },
      "CreateItemResponse": {
        "type": "object",
        "properties": {
          "response_status": {
            "type": "integer",
            "description": "Response status.\n* `0`: Success response\n* `1`: Error response. Only `error_code` and `error_message` is returned in `response_data`."
          },
          "response_message": {
            "type": "string",
            "description": "Response status.\n* `Success`: Success response\n* `Error`: Error response. Only `error_code` and `error_message` is returned in `response_data`."
          },
          "response_data": {
            "type": "object",
            "allOf": [
              {
                "$ref": "#/components/schemas/ErrorResponse"
              }
            ],
            "properties": {
              "entity": {
                "type": "string",
                "description": "Object type. Set as `Item`."
              },
              "id": {
                "type": "string",
                "description": "BILL-generated item ID. The value begins with `0ii`."
              },
              "isActive": {
                "type": "string",
                "description": "Object visibility status. Inactive objects are hidden by default in the BILL web app.\n* `1`: Active\n* `2`: Inactive"
              },
              "createdTime": {
                "type": "string",
                "description": "Created date and time"
              },
              "updatedTime": {
                "type": "string",
                "description": "Updated date and time"
              },
              "name": {
                "type": "string",
                "description": "Unique item name"
              },
              "type": {
                "type": "string",
                "description": "Item type.\n* `0`: Service\n* `1`: Unknown\n* `2`: Inventory\n* `3`: Non-inventory\n* `4`: Payment\n* `5`: Discount\n* `6`: Sales tax\n* `7`: Sub-total\n* `8`: Other charge\n* `9`: Inventory assembly\n* `10`: Group\n* `11`: Sales tax group\n* `12`: Fixed asset\n* `13`: Category"
              },
              "description": {
                "type": "string",
                "description": "Item description"
              },
              "price": {
                "type": "number",
                "description": "Item price"
              },
              "percentage": {
                "type": "number",
                "description": "Percentage used for discount or tax based on the item `price`"
              },
              "parentItemId": {
                "type": "string",
                "description": "Parent item ID. Set this value if the item ID is a child object."
              },
              "hasPurInfo": {
                "type": "boolean",
                "description": "Set as `true` if the item is associated with a chart of accounts ID. This value is useful in your choice of accounting software."
              },
              "expenseAccount": {
                "type": "string",
                "description": "Chart of accounts ID associated with the item in a bill or purchase. This value is useful in your choice of accounting software."
              },
              "purDescription": {
                "type": "string",
                "description": "Description associated with the item in a bill or purchase. This value is useful in your choice of accounting software."
              },
              "purCost": {
                "type": "number",
                "description": "Cost associated with the item in a bill or purchase. This value is useful in your choice of accounting software."
              },
              "chartOfAccountId": {
                "type": "string",
                "description": "BILL-generated chart of accounts ID associated with the item in a bill or purchase"
              },
              "taxable": {
                "type": "boolean",
                "description": "Set as `true` if the item is taxable by default"
              },
              "shortName": {
                "type": "string",
                "description": "Name for identifying the item in BILL and in your choice of accounting software."
              },
              "mergedIntoId": {
                "type": "string",
                "description": "Parent item ID that the current ID is merged into"
              }
            }
          }
        }
      },
      "UpdateItemRequest": {
        "type": "object",
        "required": [
          "obj"
        ],
        "properties": {
          "obj": {
            "type": "object",
            "required": [
              "entity",
              "id"
            ],
            "properties": {
              "entity": {
                "type": "string",
                "default": "Item",
                "description": "Object type. Set as `Item`."
              },
              "id": {
                "type": "string",
                "description": "BILL-generated item ID. The value begins with `0ii`."
              },
              "name": {
                "type": "string",
                "description": "Unique item name"
              },
              "isActive": {
                "type": "string",
                "description": "Object visibility status. Inactive objects are hidden by default in the BILL web app.\n* `1`: Active\n* `2`: Inactive"
              },
              "type": {
                "type": "string",
                "description": "Item type.\n* `0`: Service\n* `1`: Unknown\n* `2`: Inventory\n* `3`: Non-inventory\n* `4`: Payment\n* `5`: Discount\n* `6`: Sales tax\n* `7`: Sub-total\n* `8`: Other charge\n* `9`: Inventory assembly\n* `10`: Group\n* `11`: Sales tax group\n* `12`: Fixed asset\n* `13`: Category"
              },
              "description": {
                "type": "string",
                "description": "Item description"
              },
              "price": {
                "type": "number",
                "description": "Item price"
              },
              "percentage": {
                "type": "number",
                "description": "Percentage used for discount or tax based on the item `price`"
              },
              "parentItemId": {
                "type": "string",
                "description": "Parent item ID. Set this value if the item ID is a child object."
              },
              "hasPurInfo": {
                "type": "boolean",
                "description": "Set as `true` if the item is associated with a chart of accounts ID. This value is useful in your choice of accounting software."
              },
              "expenseAccount": {
                "type": "string",
                "description": "Chart of accounts ID associated with the item in a bill or purchase. This value is useful in your choice of accounting software."
              },
              "purDescription": {
                "type": "string",
                "description": "Description associated with the item in a bill or purchase. This value is useful in your choice of accounting software."
              },
              "purCost": {
                "type": "number",
                "description": "Cost associated with the item in a bill or purchase. This value is useful in your choice of accounting software."
              },
              "chartOfAccountId": {
                "type": "string",
                "description": "BILL-generated chart of accounts ID associated with the item in a bill or purchase"
              },
              "taxable": {
                "type": "boolean",
                "description": "Set as `true` if the item is taxable by default"
              },
              "shortName": {
                "type": "string",
                "description": "Name for identifying the accounting class in BILL and in your choice of accounting software."
              },
              "mergedIntoId": {
                "type": "string",
                "description": "Parent accounting class ID that the current ID is merged into"
              }
            }
          }
        }
      }
    }
  }
}
```