KiotViet MCP by usefulapi

List products (code, barcode, name, category, base price, units, attributes). Optionally include stock per branch (include_inventory) and price-book prices. Filter by name, category, branch, active flag or last change. GET /products.

{
  "type": "object",
  "properties": {
    "name": {
      "description": "Filter by product name.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "category_id": {
      "description": "Only products in this category (see kiotviet_list_categories).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "branch_ids": {
      "description": "Only these branches (see kiotviet_list_branches).",
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "integer",
        "exclusiveMinimum": 0,
        "maximum": 9007199254740991
      }
    },
    "is_active": {
      "description": "Only active (true) or inactive (false) products.",
      "type": "boolean"
    },
    "include_inventory": {
      "description": "Include the stock on hand per branch.",
      "type": "boolean"
    },
    "include_pricebook": {
      "description": "Include the price-book prices.",
      "type": "boolean"
    },
    "last_modified_from": {
      "description": "Only records changed at or after this date-time (shop local time).",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,7})?)?(Z|[+-]\\d{2}:\\d{2})?)?$"
    },
    "order_by": {
      "description": "Sort field.",
      "type": "string",
      "enum": [
        "name",
        "code",
        "createdDate",
        "modifiedDate"
      ]
    },
    "order_direction": {
      "description": "Sort direction.",
      "type": "string",
      "enum": [
        "Asc",
        "Desc"
      ]
    },
    "current_item": {
      "description": "Record offset to start from (0 = first record). Pass the previous reply's next_item.",
      "type": "integer",
      "minimum": 0,
      "maximum": 10000000
    },
    "page_size": {
      "description": "Records per page, 1-100 (default 20).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One product by id: code, barcode, name, category, base price, units, attributes, images, stock per branch and price books. GET /products/{id}.

{
  "type": "object",
  "properties": {
    "product_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "KiotViet product id."
    }
  },
  "required": [
    "product_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One product by its product code (SKU). GET /products/code/{code}.

{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "KiotViet product code."
    }
  },
  "required": [
    "code"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List product categories (id, name, parent, whether it has children). Set hierarchical to get the category tree. GET /categories.

{
  "type": "object",
  "properties": {
    "hierarchical": {
      "description": "Return the nested tree (ignores last_modified_from).",
      "type": "boolean"
    },
    "last_modified_from": {
      "description": "Only records changed at or after this date-time (shop local time).",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,7})?)?(Z|[+-]\\d{2}:\\d{2})?)?$"
    },
    "order_by": {
      "description": "Sort field.",
      "type": "string",
      "enum": [
        "categoryName",
        "createdDate",
        "modifiedDate"
      ]
    },
    "order_direction": {
      "description": "Sort direction.",
      "type": "string",
      "enum": [
        "Asc",
        "Desc"
      ]
    },
    "current_item": {
      "description": "Record offset to start from (0 = first record). Pass the previous reply's next_item.",
      "type": "integer",
      "minimum": 0,
      "maximum": 10000000
    },
    "page_size": {
      "description": "Records per page, 1-100 (default 20).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One product category by id (name, parent, children). GET /categories/{id}.

{
  "type": "object",
  "properties": {
    "category_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "KiotViet category id."
    }
  },
  "required": [
    "category_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List customers (code, name, phone, email, address, debt, total invoiced, reward points, groups). Contains personal data of the shop's customers. Filter by code, name, phone, group or last change. GET /customers.

{
  "type": "object",
  "properties": {
    "code": {
      "description": "Customer code.",
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "name": {
      "description": "Filter by customer name.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "contact_number": {
      "description": "Filter by phone number.",
      "type": "string",
      "minLength": 1,
      "maxLength": 30
    },
    "group_id": {
      "description": "Only customers in this customer group.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "include_customer_group": {
      "description": "Include each customer's groups.",
      "type": "boolean"
    },
    "include_total": {
      "description": "Include financial totals (debt, total invoiced, points).",
      "type": "boolean"
    },
    "last_modified_from": {
      "description": "Only records changed at or after this date-time (shop local time).",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,7})?)?(Z|[+-]\\d{2}:\\d{2})?)?$"
    },
    "order_by": {
      "description": "Sort field.",
      "type": "string",
      "enum": [
        "name",
        "code",
        "createdDate",
        "modifiedDate"
      ]
    },
    "order_direction": {
      "description": "Sort direction.",
      "type": "string",
      "enum": [
        "Asc",
        "Desc"
      ]
    },
    "current_item": {
      "description": "Record offset to start from (0 = first record). Pass the previous reply's next_item.",
      "type": "integer",
      "minimum": 0,
      "maximum": 10000000
    },
    "page_size": {
      "description": "Records per page, 1-100 (default 20).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One customer by id: contact data, debt, total invoiced, reward points, groups. GET /customers/{id}.

{
  "type": "object",
  "properties": {
    "customer_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "KiotViet customer id."
    }
  },
  "required": [
    "customer_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One customer by customer code. GET /customers/code/{code}.

{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "KiotViet customer code."
    }
  },
  "required": [
    "code"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: create a new customer in the shop (name required; code is generated by KiotViet if omitted). Always check with the user first, and look the customer up by phone before creating a duplicate. POST /customers.

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255,
      "description": "Customer name."
    },
    "code": {
      "description": "Customer code (optional; KiotViet generates one).",
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "contact_number": {
      "description": "Phone number.",
      "type": "string",
      "minLength": 1,
      "maxLength": 30
    },
    "email": {
      "description": "Email address.",
      "type": "string",
      "minLength": 1,
      "maxLength": 255
    },
    "address": {
      "description": "Street address.",
      "type": "string",
      "minLength": 1,
      "maxLength": 500
    },
    "birth_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,7})?)?(Z|[+-]\\d{2}:\\d{2})?)?$",
      "description": "Date 2026-10-01 or date-time 2026-10-01T08:00:00 (shop local time)."
    },
    "comments": {
      "description": "Note on the customer.",
      "type": "string",
      "minLength": 1,
      "maxLength": 1000
    },
    "group_ids": {
      "description": "Customer group ids.",
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "integer",
        "exclusiveMinimum": 0,
        "maximum": 9007199254740991
      }
    },
    "organization": {
      "description": "Company name.",
      "type": "string",
      "minLength": 1,
      "maxLength": 255
    },
    "tax_code": {
      "description": "Tax code (ma so thue).",
      "type": "string",
      "minLength": 1,
      "maxLength": 50
    }
  },
  "required": [
    "name"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List sales invoices (code, date, branch, customer, total, amount paid, status, lines). Filter by branch, customer, status, order, purchase-date range or last change. GET /invoices.

{
  "type": "object",
  "properties": {
    "branch_ids": {
      "description": "Only these branches (see kiotviet_list_branches).",
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "integer",
        "exclusiveMinimum": 0,
        "maximum": 9007199254740991
      }
    },
    "customer_ids": {
      "description": "Only invoices of these customers.",
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "integer",
        "exclusiveMinimum": 0,
        "maximum": 9007199254740991
      }
    },
    "customer_code": {
      "description": "Only invoices of the customer with this code.",
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "status": {
      "description": "KiotViet status code(s) to include.",
      "maxItems": 10,
      "type": "array",
      "items": {
        "type": "integer",
        "minimum": 0,
        "maximum": 100
      }
    },
    "order_id": {
      "description": "Only the invoice created from this sales order.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "from_purchase_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,7})?)?(Z|[+-]\\d{2}:\\d{2})?)?$",
      "description": "Date 2026-10-01 or date-time 2026-10-01T08:00:00 (shop local time)."
    },
    "to_purchase_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,7})?)?(Z|[+-]\\d{2}:\\d{2})?)?$",
      "description": "Date 2026-10-01 or date-time 2026-10-01T08:00:00 (shop local time)."
    },
    "include_payment": {
      "description": "Include the payments.",
      "type": "boolean"
    },
    "last_modified_from": {
      "description": "Only records changed at or after this date-time (shop local time).",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,7})?)?(Z|[+-]\\d{2}:\\d{2})?)?$"
    },
    "order_by": {
      "description": "Sort field.",
      "type": "string",
      "enum": [
        "createdDate",
        "modifiedDate",
        "purchaseDate",
        "code"
      ]
    },
    "order_direction": {
      "description": "Sort direction.",
      "type": "string",
      "enum": [
        "Asc",
        "Desc"
      ]
    },
    "current_item": {
      "description": "Record offset to start from (0 = first record). Pass the previous reply's next_item.",
      "type": "integer",
      "minimum": 0,
      "maximum": 10000000
    },
    "page_size": {
      "description": "Records per page, 1-100 (default 20).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One invoice by id with its lines, payments and delivery. GET /invoices/{id}.

{
  "type": "object",
  "properties": {
    "invoice_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "KiotViet invoice id."
    }
  },
  "required": [
    "invoice_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One invoice by invoice code (for example HD000123). GET /invoices/code/{code}.

{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "KiotViet invoice code."
    }
  },
  "required": [
    "code"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List sales orders (code, date, branch, customer, total, status, lines, delivery). Filter by branch, customer, status, creation date (from) or last change (from/to). GET /orders.

{
  "type": "object",
  "properties": {
    "branch_ids": {
      "description": "Only these branches (see kiotviet_list_branches).",
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "integer",
        "exclusiveMinimum": 0,
        "maximum": 9007199254740991
      }
    },
    "customer_ids": {
      "description": "Only orders of these customers.",
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "integer",
        "exclusiveMinimum": 0,
        "maximum": 9007199254740991
      }
    },
    "customer_code": {
      "description": "Only orders of the customer with this code.",
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "status": {
      "description": "KiotViet status code(s) to include.",
      "maxItems": 10,
      "type": "array",
      "items": {
        "type": "integer",
        "minimum": 0,
        "maximum": 100
      }
    },
    "sale_channel_id": {
      "description": "Only orders from this sales channel.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "created_date": {
      "description": "Only orders created at or after this date.",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,7})?)?(Z|[+-]\\d{2}:\\d{2})?)?$"
    },
    "last_modified_to": {
      "description": "Only orders last changed up to this date-time (KiotViet toDate is a bound on the modification time, not the creation time). Use with last_modified_from.",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,7})?)?(Z|[+-]\\d{2}:\\d{2})?)?$"
    },
    "include_payment": {
      "description": "Include the payments.",
      "type": "boolean"
    },
    "include_order_delivery": {
      "description": "Include the delivery details.",
      "type": "boolean"
    },
    "last_modified_from": {
      "description": "Only records changed at or after this date-time (shop local time).",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,7})?)?(Z|[+-]\\d{2}:\\d{2})?)?$"
    },
    "order_by": {
      "description": "Sort field.",
      "type": "string",
      "enum": [
        "createdDate",
        "modifiedDate",
        "purchaseDate",
        "code"
      ]
    },
    "order_direction": {
      "description": "Sort direction.",
      "type": "string",
      "enum": [
        "Asc",
        "Desc"
      ]
    },
    "current_item": {
      "description": "Record offset to start from (0 = first record). Pass the previous reply's next_item.",
      "type": "integer",
      "minimum": 0,
      "maximum": 10000000
    },
    "page_size": {
      "description": "Records per page, 1-100 (default 20).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One sales order by id with its lines, payments and delivery. GET /orders/{id}.

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "KiotViet order id."
    }
  },
  "required": [
    "order_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One sales order by order code (for example DH000123). GET /orders/code/{code}.

{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "KiotViet order code."
    }
  },
  "required": [
    "code"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: create a sales order (an order, not an invoice: no invoice is made and no payment is recorded) with lines of existing products in a branch, for an existing customer or none. Always confirm the products, quantities and prices with the user first. POST /orders.

{
  "type": "object",
  "properties": {
    "branch_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Branch the order is for (see kiotviet_list_branches)."
    },
    "customer_id": {
      "description": "Existing customer id (see kiotviet_list_customers).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "description": {
      "description": "Note on the order.",
      "type": "string",
      "minLength": 1,
      "maxLength": 1000
    },
    "discount": {
      "description": "Order discount amount.",
      "type": "number",
      "minimum": 0,
      "maximum": 1000000000000
    },
    "sold_by_id": {
      "description": "Salesperson user id (see kiotviet_list_users).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "sale_channel_id": {
      "description": "Sales channel id.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "items": {
      "minItems": 1,
      "maxItems": 100,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "product_id": {
            "type": "integer",
            "exclusiveMinimum": 0,
            "maximum": 9007199254740991,
            "description": "Product id."
          },
          "quantity": {
            "type": "number",
            "exclusiveMinimum": 0,
            "maximum": 1000000,
            "description": "Quantity."
          },
          "price": {
            "type": "number",
            "minimum": 0,
            "maximum": 1000000000000,
            "description": "Unit price."
          },
          "discount": {
            "description": "Line discount amount.",
            "type": "number",
            "minimum": 0,
            "maximum": 1000000000000
          },
          "note": {
            "description": "Line note.",
            "type": "string",
            "minLength": 1,
            "maxLength": 500
          }
        },
        "required": [
          "product_id",
          "quantity",
          "price"
        ]
      },
      "description": "The order lines."
    }
  },
  "required": [
    "branch_id",
    "items"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List the shop's branches (id, name, code, phone, address). Use the ids to filter other tools. GET /branches.

{
  "type": "object",
  "properties": {
    "current_item": {
      "description": "Record offset to start from (0 = first record). Pass the previous reply's next_item.",
      "type": "integer",
      "minimum": 0,
      "maximum": 10000000
    },
    "page_size": {
      "description": "Records per page, 1-100 (default 20).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Stock on hand and reserved quantity per product and branch. Filter by branch or last change. GET /productOnHands.

{
  "type": "object",
  "properties": {
    "branch_ids": {
      "description": "Only these branches (see kiotviet_list_branches).",
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "integer",
        "exclusiveMinimum": 0,
        "maximum": 9007199254740991
      }
    },
    "last_modified_from": {
      "description": "Only records changed at or after this date-time (shop local time).",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,7})?)?(Z|[+-]\\d{2}:\\d{2})?)?$"
    },
    "order_by": {
      "description": "Sort field.",
      "type": "string",
      "enum": [
        "code",
        "createdDate",
        "modifiedDate"
      ]
    },
    "order_direction": {
      "description": "Sort direction.",
      "type": "string",
      "enum": [
        "Asc",
        "Desc"
      ]
    },
    "current_item": {
      "description": "Record offset to start from (0 = first record). Pass the previous reply's next_item.",
      "type": "integer",
      "minimum": 0,
      "maximum": 10000000
    },
    "page_size": {
      "description": "Records per page, 1-100 (default 20).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List suppliers (code, name, phone, email, address, debt, total invoiced). Filter by code, name, phone or last change. GET /suppliers.

{
  "type": "object",
  "properties": {
    "code": {
      "description": "Supplier code.",
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "name": {
      "description": "Filter by supplier name.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "contact_number": {
      "description": "Filter by phone number.",
      "type": "string",
      "minLength": 1,
      "maxLength": 30
    },
    "include_total": {
      "description": "Include financial totals (debt, total invoiced).",
      "type": "boolean"
    },
    "last_modified_from": {
      "description": "Only records changed at or after this date-time (shop local time).",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,7})?)?(Z|[+-]\\d{2}:\\d{2})?)?$"
    },
    "order_direction": {
      "description": "Sort direction.",
      "type": "string",
      "enum": [
        "Asc",
        "Desc"
      ]
    },
    "current_item": {
      "description": "Record offset to start from (0 = first record). Pass the previous reply's next_item.",
      "type": "integer",
      "minimum": 0,
      "maximum": 10000000
    },
    "page_size": {
      "description": "Records per page, 1-100 (default 20).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One supplier by id. GET /suppliers/{id}.

{
  "type": "object",
  "properties": {
    "supplier_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "KiotViet supplier id."
    }
  },
  "required": [
    "supplier_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List goods receipts from suppliers (nhap hang: code, date, branch, supplier, total, lines). Filter by branch, status or purchase-date range. GET /purchaseorders.

{
  "type": "object",
  "properties": {
    "branch_ids": {
      "description": "Only these branches (see kiotviet_list_branches).",
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "integer",
        "exclusiveMinimum": 0,
        "maximum": 9007199254740991
      }
    },
    "status": {
      "description": "KiotViet status code(s) to include.",
      "maxItems": 10,
      "type": "array",
      "items": {
        "type": "integer",
        "minimum": 0,
        "maximum": 100
      }
    },
    "from_purchase_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,7})?)?(Z|[+-]\\d{2}:\\d{2})?)?$",
      "description": "Date 2026-10-01 or date-time 2026-10-01T08:00:00 (shop local time)."
    },
    "to_purchase_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,7})?)?(Z|[+-]\\d{2}:\\d{2})?)?$",
      "description": "Date 2026-10-01 or date-time 2026-10-01T08:00:00 (shop local time)."
    },
    "include_payment": {
      "description": "Include the payments.",
      "type": "boolean"
    },
    "current_item": {
      "description": "Record offset to start from (0 = first record). Pass the previous reply's next_item.",
      "type": "integer",
      "minimum": 0,
      "maximum": 10000000
    },
    "page_size": {
      "description": "Records per page, 1-100 (default 20).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One goods receipt (nhap hang) by id with its lines. GET /purchaseorders/{id}.

{
  "type": "object",
  "properties": {
    "purchase_order_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "KiotViet goods receipt id."
    }
  },
  "required": [
    "purchase_order_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List orders placed with suppliers (dat hang nhap: code, date, branch, supplier, status, lines, amount paid). Filter by branch, status, supplier or product text. GET /ordersuppliers.

{
  "type": "object",
  "properties": {
    "branch_id": {
      "description": "Only this branch.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "status": {
      "description": "KiotViet status code.",
      "type": "integer",
      "minimum": 0,
      "maximum": 100
    },
    "supplier_key": {
      "description": "Supplier code, name or phone.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "product_key": {
      "description": "Product code or name.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "code_key": {
      "description": "Order code.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "current_item": {
      "description": "Record offset to start from (0 = first record). Pass the previous reply's next_item.",
      "type": "integer",
      "minimum": 0,
      "maximum": 10000000
    },
    "page_size": {
      "description": "Records per page, 1-100 (default 20).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List customer returns (code, date, branch, customer, invoice, return total, lines). GET /returns.

{
  "type": "object",
  "properties": {
    "include_payment": {
      "description": "Include the payments.",
      "type": "boolean"
    },
    "last_modified_from": {
      "description": "Only records changed at or after this date-time (shop local time).",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,7})?)?(Z|[+-]\\d{2}:\\d{2})?)?$"
    },
    "order_by": {
      "description": "Sort field.",
      "type": "string",
      "enum": [
        "createdDate",
        "modifiedDate",
        "code"
      ]
    },
    "order_direction": {
      "description": "Sort direction.",
      "type": "string",
      "enum": [
        "Asc",
        "Desc"
      ]
    },
    "current_item": {
      "description": "Record offset to start from (0 = first record). Pass the previous reply's next_item.",
      "type": "integer",
      "minimum": 0,
      "maximum": 10000000
    },
    "page_size": {
      "description": "Records per page, 1-100 (default 20).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One customer return by id with its lines. GET /returns/{id}.

{
  "type": "object",
  "properties": {
    "return_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "KiotViet return id."
    }
  },
  "required": [
    "return_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List cash-book entries (receipts and payments: code, branch, method, partner, amount, date, status). Filter by branch, direction or date range. GET /cashflow.

{
  "type": "object",
  "properties": {
    "branch_ids": {
      "description": "Only these branches (see kiotviet_list_branches).",
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "integer",
        "exclusiveMinimum": 0,
        "maximum": 9007199254740991
      }
    },
    "is_receipt": {
      "description": "true = receipts (money in), false = payments (money out).",
      "type": "boolean"
    },
    "start_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,7})?)?(Z|[+-]\\d{2}:\\d{2})?)?$",
      "description": "Date 2026-10-01 or date-time 2026-10-01T08:00:00 (shop local time)."
    },
    "end_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,7})?)?(Z|[+-]\\d{2}:\\d{2})?)?$",
      "description": "Date 2026-10-01 or date-time 2026-10-01T08:00:00 (shop local time)."
    },
    "code": {
      "description": "Voucher code.",
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "partner_name": {
      "description": "Customer, supplier or other partner name.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "current_item": {
      "description": "Record offset to start from (0 = first record). Pass the previous reply's next_item.",
      "type": "integer",
      "minimum": 0,
      "maximum": 10000000
    },
    "page_size": {
      "description": "Records per page, 1-100 (default 20).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List the shop's staff users (id, username, name, phone, email). GET /users.

{
  "type": "object",
  "properties": {
    "current_item": {
      "description": "Record offset to start from (0 = first record). Pass the previous reply's next_item.",
      "type": "integer",
      "minimum": 0,
      "maximum": 10000000
    },
    "page_size": {
      "description": "Records per page, 1-100 (default 20).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List price books (bang gia: name, active flag, validity dates, branches, customer groups). GET /pricebooks.

{
  "type": "object",
  "properties": {
    "include_branches": {
      "description": "Include the branches each price book applies to.",
      "type": "boolean"
    },
    "include_customer_groups": {
      "description": "Include the customer groups each price book applies to.",
      "type": "boolean"
    },
    "current_item": {
      "description": "Record offset to start from (0 = first record). Pass the previous reply's next_item.",
      "type": "integer",
      "minimum": 0,
      "maximum": 10000000
    },
    "page_size": {
      "description": "Records per page, 1-100 (default 20).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

The product prices of one price book (product id, code, price), paged. GET /pricebooks/{id}.

{
  "type": "object",
  "properties": {
    "price_book_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "KiotViet price book id."
    },
    "current_item": {
      "description": "Record offset to start from (0 = first record). Pass the previous reply's next_item.",
      "type": "integer",
      "minimum": 0,
      "maximum": 10000000
    },
    "page_size": {
      "description": "Records per page, 1-100 (default 20).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100
    }
  },
  "required": [
    "price_book_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}