Hivebuy API

Documentation of all available endpoints for Hivebuy customers

## Sections
• [Hivebuy API - BETA](https://app.theneo.io/hivebuy/hivebuy-api/api.md): This section of the API allows users to interact with Hivebuy from external sources using an access token provided by Hivebuy. With this API, you can seamlessly communicate with Hivebuy and access essential data and functionalities for your projects. Please note that this API documentation is in beta status and may not cover every detail. We are continuously improving it, so if you have any questions, feel free to reach out to us at support@hivebuy.de. To create and manage your API Keys, go to the Hivebuy App and navigate to the API Key page . General Information RESTful Architecture – Designed for simplicity and scalability JSON Responses – Standardized and easy-to-parse responses Authentication & Security – Secure API calls with a Bearer Token specificly for your company Rate Limits – Fair usage policies to ensure reliability Please not that Hivebuy does not allow more than 100 requests per minute. To use this API, you will need to: Get an API key – Go to the Hivebuy App and navigate to Company Management / Api Keys . Create a key for a specific user and copy it. Authenticate – Include your API key in each request as a Bearer Token Make a Request – Use our endpoints to interact with the API
• [Catalogues](https://app.theneo.io/hivebuy/hivebuy-api/catalogues.md): GET / CREATE / PATCH Catalogues inside Hivebuy Internal catalog master data in Hivebuy is essential for streamlining procurement by providing predefined product selections for users. These catalogs are created by the procurement team and contain items that employees can directly order. Key functionalities: Standardized product selection for efficient and controlled purchasing Assignment of catalogs to specific legal entities and departments Simplified ordering process for users with predefined products and suppliers Use cases include: Providing office supplies, IT equipment, or frequently used materials in a structured catalog Ensuring compliance with preferred suppliers and negotiated conditions Restricting catalog availability to specific entities or departments for better cost control Field Update: Transition from “name” to “names” (Multi-language Support) New Replaced “ name ” field with a " names " object to support multi-language localization. Example: Old: “name” : “Official Supplies” New: "names": {"en": "Official Supplies"} All new implementations should use the “names” object instead. Action Required Update your payloads and consumers to use “names” instead of “name”.
  • [Get Catalogues](https://app.theneo.io/hivebuy/hivebuy-api/catalogues/get-catalogues.md): The Get Catalogues section allows users to retrieve detailed information about catalogues stored in the system. Users can access essential data such as catalogue IDs, names, descriptions, creation dates, and associated departments and legal entities. This section enables users to efficiently manage and view catalogue information for better organization and accessibility within the application.
  • [Get Single Catalogue](https://app.theneo.io/hivebuy/hivebuy-api/catalogues/get-single-catalogue.md)
  • [PATCH Catalogue](https://app.theneo.io/hivebuy/hivebuy-api/catalogues/patch-catalogue.md)
  • [Create Catalogue](https://app.theneo.io/hivebuy/hivebuy-api/catalogues/create-catalogue.md)
  • [DELETE Catalogue](https://app.theneo.io/hivebuy/hivebuy-api/catalogues/delete-catalogue.md)
• [Catalogue Items](https://app.theneo.io/hivebuy/hivebuy-api/catalogue-items.md): GET / CREATE / PATCH Catalogue Items inside Hivebuy Catalog item master data in Hivebuy is essential for ensuring a structured and efficient procurement process. Catalog items are predefined products or services that users can order directly from internal catalogs managed by the procurement team. Field Update: Transition from “name” to “names” (Multi-language Support) New Replaced “ name ” field with a " names " object to support multi-language localization. Example: Old: “name” : “Official Supplies” New: "names": {"en": "Official Supplies"} All new implementations should use the “names” object instead. Action Required Update your payloads and consumers to use “names” instead of “name”.
  • [Get Catalogue Items](https://app.theneo.io/hivebuy/hivebuy-api/catalogue-items/get-catalogue-items.md): This section enables users to retrieve a comprehensive list of catalogue items available from suppliers. It provides detailed information about each item and its variants, supporting tasks such as browsing inventory, integrating product data, or building custom catalog displays. Note: Only a limited number of items are returned per request due to default pagination.
  • [Get Catalogue Items (pagination)](https://app.theneo.io/hivebuy/hivebuy-api/catalogue-items/get-catalogue-items-copy-1.md)
  • [Get Single Catalogue Item](https://app.theneo.io/hivebuy/hivebuy-api/catalogue-items/get-single-catalogue-item.md)
  • [CREATE Catalogue Item](https://app.theneo.io/hivebuy/hivebuy-api/catalogue-items/create-catalogue-item.md)
  • [PATCH Catalogue Item](https://app.theneo.io/hivebuy/hivebuy-api/catalogue-items/patch-catalogue-item.md)
  • [DEACTIVATE Catalogue Item](https://app.theneo.io/hivebuy/hivebuy-api/catalogue-items/deactivate-catalogue-item.md)
  • [DELETE Catalogue Item](https://app.theneo.io/hivebuy/hivebuy-api/catalogue-items/delete-catalogue-item.md)
  • [BULK UPSERT Catalogue Items](https://app.theneo.io/hivebuy/hivebuy-api/catalogue-items/bulk-upsert-catalogue-items.md): The Bulk Upsert operation enables inserting or updating multiple catalogue item records in a single request. If a catalogue item already exists, it will be updated with the new data. If the catalogue item does not exist, it will be inserted as a new record.
• [Categories](https://app.theneo.io/hivebuy/hivebuy-api/categories.md): Product category master data in Hivebuy is essential for structuring procurement processes and enhancing reporting. Product categories serve as an additional classification method alongside cost centers and projects, enabling better spend analysis and control. Key functionalities: Grouping of similar products and services for streamlined purchasing Improved spend visibility and reporting across different categories Better supplier management by aligning purchases with relevant product groups Use cases include: Categorizing office supplies, IT equipment, or production materials Analyzing spend by product category for cost optimization Defining procurement strategies based on category-specific insights By utilizing product category master data, organizations can gain a clearer overview of procurement activities and make more informed purchasing decisions. The Categories section allows users to manage and organize different categories within the Hivebuy platform. Users can create, update, and view various categories to streamline their products and services effectively. This section is essential for maintaining a structured and organized system within the platform. Field Update: Transition from “name” to “names” (Multi-language Support) New Replaced “ name ” field with a " names " object to support multi-language localization. Example: Old: “name” : “Official Supplies” New: "names": {"en": "Official Supplies"} The "name" field is still accepted for backward compatibility but will be removed in a future release . All new implementations should use the “names” object instead. Action Required Update your payloads and consumers to use “names” instead of “name”. Support for “name” will be removed in an upcoming version.
  • [GET Categories](https://app.theneo.io/hivebuy/hivebuy-api/categories/get-categories.md): The GET Categories section allows users to retrieve a comprehensive list of categories associated with their company. By leveraging this section, users can easily access and display the various categories available within the system, including detailed information such as unique identifiers, parent categories, default budget levels, and more. This functionality enables users to efficiently manage and categorize their data within the API. The GET Categories section allows users to retrieve a list of categories associated with your company company. By utilizing this section, users can easily access and display the various categories available within the system.
  • [GET Category](https://app.theneo.io/hivebuy/hivebuy-api/categories/get-category.md): The GET Category section allows users to retrieve information about a specific category within the company.
  • [CREATE Category](https://app.theneo.io/hivebuy/hivebuy-api/categories/create-category.md): The CREATE Category section allows users to create new categories within the system, specifying details such as the category name, budget level, notes, emoji, and more.
  • [PATCH Category](https://app.theneo.io/hivebuy/hivebuy-api/categories/patch-category.md): The PATCH Category section allows users to update the details of a specific category within their company's account. By making changes to the category information, users can ensure that their company's data remains accurate and up-to-date.
  • [BULK UPSERT Categories](https://app.theneo.io/hivebuy/hivebuy-api/categories/bulk-upsert-categories.md): Bulk Upsert for categories allows inserting or updating multiple category records in a single operation. If a category already exists, it will be updated with the new data. If the category does not exist, it will be inserted as a new record.
  • [DELETE Category](https://app.theneo.io/hivebuy/hivebuy-api/categories/delete-category.md): Objects are never permanently deleted. This is a soft-delete system: The object remains in the database. It will be excluded from normal list/query responses. It can still be queried directly using its Unique Identifier.
• [Company Addresses](https://app.theneo.io/hivebuy/hivebuy-api/company-addresses.md): This endpoint allows you to manage and retrieve all relevant company delivery and invoice addresses . You can configure default addresses for both types, ensuring consistency across purchasing and invoicing operations. Additionally, the API supports assigning personal addresses to individual users , which are automatically used as the default delivery address in their Purchase Requests . Key Features: Define and update company-level delivery and invoice addresses Set default addresses per type (Delivery / Invoice) Assign user-specific addresses for personalized Purchase Request defaults Use Cases: Streamlining purchase workflows by predefining delivery destinations Ensuring accurate invoice routing by associating proper billing addresses Supporting distributed teams with per-user delivery defaults
  • [GET Company Addresses](https://app.theneo.io/hivebuy/hivebuy-api/company-addresses/get-company-addresses.md): This section allows users to retrieve detailed information about company addresses
  • [GET Company Addresses(Pagination)](https://app.theneo.io/hivebuy/hivebuy-api/company-addresses/get-company-addresses-pagination.md): This section allows users to retrieve a paginated list of company addresses
  • [GET Company Address](https://app.theneo.io/hivebuy/hivebuy-api/company-addresses/get-company-address.md): This section allows users to retrieve the address details of a company based on its unique identifier.
  • [PATCH Company Address](https://app.theneo.io/hivebuy/hivebuy-api/company-addresses/patch-company-address.md): This API section allows users to update the details of a company address, such as the street name, house number, postal code, and city etc.
  • [CREATE Company Address](https://app.theneo.io/hivebuy/hivebuy-api/company-addresses/create-company-address.md): The CREATE Company Address section allows users to add a new company address to their account, specifying details such as the address type, street, city, and country
  • [DELETE Company Address](https://app.theneo.io/hivebuy/hivebuy-api/company-addresses/delete-company-address.md): This section enables users to delete a company address associated with a specific ID.
• [Contracts](https://app.theneo.io/hivebuy/hivebuy-api/contract.md): The Contracts section allows users to manage the agreements and legal contracts associated with their accounts or transactions. This section enables users to view, create, update, and delete contracts as needed, providing a centralized hub for all legal documentation related to their interactions on the platform. Users can easily access and maintain their contracts through this section, ensuring compliance and clarity in their business dealings. Key Features Create, retrieve, and update company contract records Attach multiple documents (PDFs etc.) to a contract Track net, gross, and license-related amounts with currency support Set approval requirements for controlled procurement
  • [GET Contracts](https://app.theneo.io/hivebuy/hivebuy-api/contract/get-contracts.md): This section allows users to retrieve list of contracts
  • [GET Contract](https://app.theneo.io/hivebuy/hivebuy-api/contract/get-contract.md): The "GET Contract" section allows users to retrieve detailed information about a specific contract
  • [GET Contracts(Pagination)](https://app.theneo.io/hivebuy/hivebuy-api/contract/get-contracts-pagination.md)
  • [CREATE Contract](https://app.theneo.io/hivebuy/hivebuy-api/contract/create-contract.md): The CREATE Contract section allows users to create a new contract within the system
  • [PATCH Contract](https://app.theneo.io/hivebuy/hivebuy-api/contract/patch-contract.md): The PATCH Contract section allows users to update and modify existing contract information within the system.
  • [DELETE Contract](https://app.theneo.io/hivebuy/hivebuy-api/contract/delete-contract.md): The DELETE Contract section allows users to remove a specific contract.
• [Departments](https://app.theneo.io/hivebuy/hivebuy-api/departments.md): GET / CREATE / PATCH Departments inside Hivebuy Department master data in Hivebuy is essential for organizing procurement processes and aligning purchases with financial structures. Each department is linked to a corresponding cost center, ensuring accurate cost allocation and reporting. Key functionalities: Assignment of purchases to specific departments for better cost tracking Clear mapping to cost centers for financial transparency Improved reporting and budget control across departments Use cases include: Structuring procurement activities by department, such as Marketing, IT, or Finance Monitoring departmental budgets and expenses efficiently Ensuring approvals and purchasing workflows are aligned with department responsibilities By using department master data, organizations can optimize financial tracking, improve procurement efficiency, and maintain a structured overview of expenses.
  • [Get Departments](https://app.theneo.io/hivebuy/hivebuy-api/departments/get-departments.md): Will return all departments for this company, depending on the permissions of the token user
  • [Get Single Department](https://app.theneo.io/hivebuy/hivebuy-api/departments/get-single-department.md): Returns a single department
  • [Get Departments(pagination)](https://app.theneo.io/hivebuy/hivebuy-api/departments/get-departments-pagination.md)
  • [Create Department](https://app.theneo.io/hivebuy/hivebuy-api/departments/create-department.md): Will create one single department. Only the name is mandatory, the other fields are optional. legalEntity, members and approvers are UUIDs for the respective users/legalEntity
  • [PATCH Department](https://app.theneo.io/hivebuy/hivebuy-api/departments/patch-department.md): Returns a single department
  • [BULK UPSERT Departments](https://app.theneo.io/hivebuy/hivebuy-api/departments/bulk-upsert-department.md): Bulk Upsert allows inserting or updating multiple department records in a single operation. If a department already exists, it updates the existing record. If the department does not exist, it inserts it as a new record.
  • [DELETE Department](https://app.theneo.io/hivebuy/hivebuy-api/departments/delete-departments.md): Deletes a department by its unique identifier.
• [Legal Entities](https://app.theneo.io/hivebuy/hivebuy-api/legal-entities.md): Legal entity master data in Hivebuy is crucial for structuring procurement processes across different company entities. Legal entities represent the various companies within an organization, ensuring accurate financial reporting and compliance. Key functionalities: Clear assignment of purchases to specific legal entities Improved financial reporting and transparency across multiple entities Compliance with tax and regulatory requirements Use cases include: Managing procurement for subsidiaries, branches, or international entities Ensuring correct invoicing and tax handling per legal entity Structuring approvals and budget tracking based on legal entity assignment By leveraging legal entity master data, organizations can maintain financial accuracy, streamline procurement operations, and ensure compliance across all company entities.
  • [GET Legal Entities](https://app.theneo.io/hivebuy/hivebuy-api/legal-entities/get-legal-entities.md): Retrieves a list of all legal entities available.
  • [GET Legal Entity](https://app.theneo.io/hivebuy/hivebuy-api/legal-entities/get-legal-entity.md): Get detailed information about a single legal entity by using its unique identifier.
  • [CREATE Legal Entity](https://app.theneo.io/hivebuy/hivebuy-api/legal-entities/create-legal-entity.md): Creates a new legal entity in the system.
  • [PATCH Legal Entitiy](https://app.theneo.io/hivebuy/hivebuy-api/legal-entities/patch-legal-entitiy.md): Updates one or more fields of a legal entity using its unique identifier.
  • [BULK UPSERT Legal Entities](https://app.theneo.io/hivebuy/hivebuy-api/legal-entities/bulk-legal-entities.md): Allows bulk creation or update of legal entities within a company. If a legal entity with the same unique identifier (e.g., name) exists, it will be updated; otherwise, a new entity is created.
  • [DELETE Legal Entity](https://app.theneo.io/hivebuy/hivebuy-api/legal-entities/delete-legal-entity.md): Deletes a specific legal entity from the system by its unique identifier.
• [Projects](https://app.theneo.io/hivebuy/hivebuy-api/projects.md): GET / CREATE / PATCH Projects inside Hivebuy Project master data in Hivebuy is used as an additional reporting option alongside cost centers. It allows individual projects and orders to be represented as cost carriers. Projects can be assigned to multiple departments (cost centers), enabling flexible cost allocation. Use cases include: Customer projects Individual company events Internal projects, such as software implementation projects By leveraging project master data, organizations can improve financial tracking and gain better insights into project-related expenses.
  • [GET Projects](https://app.theneo.io/hivebuy/hivebuy-api/projects/get-projects.md): Retrieves a list of projects
  • [GET Project](https://app.theneo.io/hivebuy/hivebuy-api/projects/get-project.md): Retrieves detailed information about a specific project using its unique identifier.
  • [GET Project(pagination)](https://app.theneo.io/hivebuy/hivebuy-api/projects/get-project-filtering.md)
  • [CREATE Project](https://app.theneo.io/hivebuy/hivebuy-api/projects/create-project.md): The "CREATE Project" section allows users to add a new project to the system by submitting relevant details such as project name, description, budget allocated, and participating departments.
  • [PATCH Project](https://app.theneo.io/hivebuy/hivebuy-api/projects/patch-project.md): The PATCH Project section allows users to update and modify project details such as project name, team members, approvers, budget allocation, and project description.
  • [BULK UPSERT Projects](https://app.theneo.io/hivebuy/hivebuy-api/projects/patch-project-copy.md): Use this section to efficiently create or update multiple projects in a single request by providing an array of project objects. The system matches each project against existing records using a defined hierarchy of unique identifiers, ensuring accurate updates or the creation of new entries when no match is found. This enables streamlined bulk management of project data while maintaining data integrity and consistency. Endpoint POST /api/company/bulk-upsert/projects/ Body: JSON array of project objects. Max 50 items per request. Payloads exceeding the limit are rejected with 400 . Matching order For each item, the API attempts to match an existing project using the following fields in order . The first unique match wins. If no step matches, a new project is created. Title Description Title # Field(s) Notes 1 id UUID. Must belong to a project in your company. Does not fall through on no match. 2 externalId The externalId of the project. This field is usually used for the UUID of the external system 3 projectNumber + parent parent is the parent project's projectNumber . 4 projectNumber Only evaluated when step 2 yields no match. 5 costCenter 6 name If any step finds multiple matching projects, the item is rejected with ambiguous_match (see Errors). The item is not saved, and matching does not continue to the next step. Field resolution Title Description Title Field Accepted value Behavior if not resolvable parent projectNumber of an existing project, or null parent_not_found legalEntity Name of an existing legal entity, or null legal_entity_not_found approvers , budgetOwners List of email addresses (users in your company) users_not_found participatingDepartments List of department names departments_not_found Partial updates Fields omitted from the payload are not modified on the matched project. To clear a list field, send an empty list explicitly. To clear a scalar reference, send null . Response 200 OK on every request that passes top-level validation. Per-item outcomes: { " upserted ": [ { " id ": "<uuid>" , " action ": "created" | "updated" , ...item } ], " errors ": [ { " data ": { ...original item... }, " errorCode ": "<code>" , " errorField ": "<field>" , " message ": "<human-readable>" , " details ": { ...code-specific... } } ]} action distinguishes newly created projects from updates to existing ones. Always inspect errors — a 200 response does not imply all items were processed. Error codes Title Description Title errorCode Meaning details ambiguous_match Multiple existing projects match the lookup step. value , candidateIds unknown_id id does not exist in your company. value invalid_id id is not a valid UUID. value parent_not_found parent projectNumber does not exist in your company. value legal_entity_not_found legalEntity name does not exist in your company. value users_not_found One or more emails in approvers / budgetOwners are unknown. unresolved (list of emails) departments_not_found One or more participatingDepartments names are unknown. unresolved (list of names) validation_error Serializer validation failed. Field-keyed error dict. unexpected Unhandled server-side error. details (string). Integration guidelines Prefer sending id for updates. It is the only unambiguous identifier. When omitting id , ensure the combination of projectNumber + parent , costCenter , or name is unique within your tenant. Treat any non-empty errors array as a partial failure and reconcile on your side. Per-item saves are atomic: a failed item leaves no partial state.
  • [DELETE Project](https://app.theneo.io/hivebuy/hivebuy-api/projects/delete-project.md)
• [Purchase Orders](https://app.theneo.io/hivebuy/hivebuy-api/purchase-order.md): The Hivebuy Purchase Order API has a default result length of 10 entries. You can increase this to a maximum of 30 entries by using the parameter pageSize
  • [POST Upload document](https://app.theneo.io/hivebuy/hivebuy-api/purchase-order/get-purchase-orders-copy.md): Upload documents related to purchase orders to securely associate files with your transactions.
  • [GET Purchase Orders](https://app.theneo.io/hivebuy/hivebuy-api/purchase-order/get-purchase-order.md): This endpoint allows you to fetch purchase orders, either as a paginated list or by specific parameters. It’s useful for tracking orders, viewing details, and managing them efficiently. How it works Custom pages: You can adjust the page number and page size (maximum 30; larger values return an error; defaults to 10). Specific order: Retrieve a single order by its ID. Returns an error if not found. By creator: Retrieve orders created by a specific user. Returns an error if none exist. Combine filters: Filters can be combined with pagination for more precise queries.
• [Suppliers](https://app.theneo.io/hivebuy/hivebuy-api/suppliers.md): Supplier master data in Hivebuy is essential for ensuring seamless procurement processes. These data records can be regularly transferred from ERP and accounting systems to Hivebuy, but only suppliers relevant to the Hivebuy scope should be included. Supplier master data consists of address and payment details , as well as information on whether purchase orders should be sent directly to the supplier via email. Additionally, Hivebuy provides a change log that tracks modifications to master data , allowing users to see when and what changes were made.
  • [GET Suppliers](https://app.theneo.io/hivebuy/hivebuy-api/suppliers/get-suppliers.md): Get all suppliers in your account
  • [GET Suppliers (pagination)](https://app.theneo.io/hivebuy/hivebuy-api/suppliers/get-suppliers-pagination.md)
  • [GET Supplier](https://app.theneo.io/hivebuy/hivebuy-api/suppliers/get-supplier.md): Retrieves information about a single supplier by using its unique identifier.
  • [CREATE Supplier](https://app.theneo.io/hivebuy/hivebuy-api/suppliers/create-supplier.md): Adds a new supplier to the system by submitting relevant details
  • [PATCH Supplier](https://app.theneo.io/hivebuy/hivebuy-api/suppliers/patch-supplier.md): Updates one or more details of an existing supplier using its unique identifier. Only the provided fields will be modified.
  • [BULK UPSERT Suppliers](https://app.theneo.io/hivebuy/hivebuy-api/suppliers/bulk-upsert-supplier.md): The BULK UPSERT Suppliers section enables users to efficiently insert new supplier records or update existing ones in a single operation. It streamlines data management by ensuring supplier information remains current and consistent across your system, reducing the need for multiple individual requests. The BULK UPSERT operation allows for the mass insertion or update of supplier records in a database or system. It ensures that: New suppliers are inserted. Existing suppliers (matched by a unique key) are updated.
  • [DELETE Supplier](https://app.theneo.io/hivebuy/hivebuy-api/suppliers/delete-supplier.md): This section allows users to soft-delete a supplier object, which means the object remains in the database but is excluded from normal list/query responses. Users can still query the deleted supplier directly using its Unique Identifier. Objects are never permanently deleted. This is a soft-delete system: The object remains in the database. It will be excluded from normal list/query responses. It can still be queried directly using its Unique Identifier.
• [User Sync](https://app.theneo.io/hivebuy/hivebuy-api/user-sync.md): The User Sync section enables seamless synchronization of external user data with Hivebuy. Users can create invitations, manage user properties, and access a full list of all users within their system. This functionality streamlines the integration process and enhances user management capabilities.
  • [CREATE + UPDATE User](https://app.theneo.io/hivebuy/hivebuy-api/user-sync/create-update-user.md): Bulk create and update users (up to 50 per request). One request can mix creations, updates and email changes; each array item is processed independently. For every item, the user is matched by email (case-insensitive): An existing user is updated (only the provided keys are applied) An existing, not yet accepted invite is updated Otherwise the user is created , controlled by createUser : createUser = true ⇒ the user is created directly without an invitation email. Best practice when your users log in with Microsoft or Google. createUser = false (default) ⇒ the user receives an invitation email and sets up the account personally. Changing a login email. Send an item containing email (the current address) and newEmail . The login email is changed in Hivebuy and in the identity backend; all other keys in that item are ignored. Identity provider linking. idpName ( microsoft , the default, or google ), idpUserId and idpUsername link the user to your IdP. An idpUserId or idpUsername already linked to a different user rejects that item. This bulk endpoint accepts a maximum of 50 users at once. Everything after the first 50 items is silently ignored, so send larger syncs in chunks. The endpoint returns HTTP 200 even when individual items fail. An empty response body means every item was processed; otherwise the body is an array of per-item error objects. Always inspect the response body.
  • [GET User](https://app.theneo.io/hivebuy/hivebuy-api/user-sync/get-user.md): Get a single user of your company by their Hivebuy UUID (the `id` returned by the list endpoint or by a sync).
  • [GET Users](https://app.theneo.io/hivebuy/hivebuy-api/user-sync/get-users.md): Get a paginated list of all users in your company. Use the `page` and `pageSize` query parameters to page through the results. For API (external) callers the default page size is 10.
• [POST Order Status](https://app.theneo.io/hivebuy/hivebuy-api/update-order-status/post-order-status.md): You can set an order status within Hivebuy with this endpoint. The purchase order is identified by either its Hivebuy UUID or the readable ID from your system. You can use either one of those fields; if both are provided, the UUID takes precedence. * Purchase Order UUID - Example: `59fd47a3-3941-40e2-9878-27295b1501b8` * Purchase Order ID - Example: `000173` **Item-level updates.** Add `position` to update only the item at that position within the order (1-based line number). Without `position`, the status applies to the whole order and all of its items. When a single-item change warrants it, the order status is recalculated automatically; for example, delivering the last open item marks the whole order as delivered. `finalDelivered` / `finalInvoiced` are order-level flags and cannot be combined with `position`. **Repeated statuses.** Sending a status the order (or the addressed item) already has never creates a duplicate status entry. If the request contains nothing else, it is rejected with `400`. If it also carries `syncStatus`, `syncText` or `orderNumber`, that metadata is saved and the request succeeds with `200`, so a retrying integration does not lose its sync bookkeeping. **Validation.** All field problems are collected and returned together in a single `400` response of the shape `{"type": "validationError", "errors": [{"code", "detail", "attr"}]}`, so one request tells you everything that needs fixing.