> ## Documentation Index
> Fetch the complete documentation index at: https://docs.armin.cx/llms.txt
> Use this file to discover all available pages before exploring further.

# Hive

> Show Hive fulfillment orders in the inbox and let AI Agents look up, hold, cancel, and update orders.

The Hive integration connects Chatarmin CX to your Hive warehouse so agents and AI Agents can see fulfillment status, pause orders before picking, and handle WISMO and address-change tickets without leaving the inbox.

## When to use it

Use Hive in Chatarmin CX when:

* you fulfill through Hive and customers ask where their order is, to cancel, or to fix a shipping address
* agents need Hive order status, tracking, and hold controls beside the ticket conversation
* you want AI Agents to look up orders by email, check shipments, and propose hold, cancel, or address updates with human approval

<Note>
  Hive orders in the inbox are resolved through **Shopify**. Connect [Shopify](/integrations/shopify) on the same workspace so cx can match customer orders to Hive via the Shopify merchant order id.
</Note>

## Set it up

You need a Hive API key from your Hive account. Shopify must be connected on the same organization for inbox order display and for the **Get orders for customer** action.

<Steps>
  <Step title="Connect Shopify">
    [Connect Shopify](https://armin.cx/app/_/settings/integrations) on the same workspace. See [Shopify](/integrations/shopify). Hive ties orders to Shopify via `merchant_order_id`.
  </Step>

  <Step title="Open integrations">
    Go to [Integrations](https://armin.cx/app/_/settings/integrations) and select **Hive**.
  </Step>

  <Step title="Connect Hive">
    Click **Connect**, enter a display **Name** for the account, and paste your **API Key** from Hive. Save the connection.
  </Step>

  <Step title="Enable AI Agent actions">
    In [AI Agents](https://armin.cx/app/_/ai/agents-v2), open the agents that handle order tickets and enable the Hive actions they need. Require approval on write actions until test runs look safe.
  </Step>
</Steps>

<Tip>
  You can connect multiple Hive accounts per workspace. Use a clear display name when you have more than one store or brand.
</Tip>

## Use Hive in the inbox

When a ticket contact matches a customer with Shopify orders linked to Hive, the customer panel shows Hive orders with fulfillment status, store, and line items.

<Steps>
  <Step title="Open a ticket">
    Open the ticket for the customer who wrote about their order.
  </Step>

  <Step title="Review Hive orders">
    In the integrations panel, expand the Hive section. Each order shows the order number, status badge, store, total, and shipping address.
  </Step>

  <Step title="Hold or release">
    When the order is **waiting for picking**, use **Put on Hold** to pause fulfillment. When the order is on hold, use **Release Hold** to resume. Hold and release tag the linked Shopify order with `cx-on-hold` — they do not call a separate Hive hold API from the inbox button.
  </Step>

  <Step title="Edit the shipping address">
    Use **Edit address** while the order is not in a terminal state (not shipped, cancelled, or ignored). Changes go to Hive through the connected integration.
  </Step>

  <Step title="Open in Hive">
    Click the order number to open the order in the Hive merchant portal when a portal link is available.
  </Step>
</Steps>

### Fulfillment states agents should know

| Status                                  | What it means for agents                                     |
| --------------------------------------- | ------------------------------------------------------------ |
| **waiting for picking**                 | Order can still be put on hold from the inbox                |
| **on hold** / tag `cx-on-hold`          | Fulfillment is paused — release when the customer confirms   |
| **shipped**, **cancelled**, **ignored** | Terminal — hold, release, and address edit are not available |

## AI Agent actions

Give order-handling AI Agents Hive actions so they can work inside the ticket. Prefer **AI Agents** for new automation; legacy **Workflows** can still call the same Hive nodes for fixed flows.

### Read actions

| Action                           | Purpose                                                                                  |
| -------------------------------- | ---------------------------------------------------------------------------------------- |
| **Get Hive order**               | Look up one order by id                                                                  |
| **Get Hive orders for customer** | Find recent orders by customer email or phone (WISMO) — requires Shopify on the same org |
| **Get Hive shipments**           | List shipments with tracking, delivery status, and items for an order                    |

### Write actions (approval recommended)

| Action                                                | Purpose                                                                                |
| ----------------------------------------------------- | -------------------------------------------------------------------------------------- |
| **Hold / release Hive order** (`hive_set_order_hold`) | Set `hold: true` to pause picking, or `hold: false` to release. Preferred hold action. |
| **Cancel Hive order**                                 | Cancel an order that has not shipped                                                   |
| **Update Hive shipping address**                      | Correct delivery details before shipment                                               |

<Warning>
  For **Hold / release order** and **Update shipping address**, pass the Shopify **legacyResourceId** from **Get Shopify order** — not the Hive internal id or the Shopify order name. Hold actions tag Shopify; a connected Shopify integration is required.
</Warning>

### Order id formats

For **Get order**, **Cancel order**, and **Get shipments**, cx accepts any of these formats:

* Hive internal id (for example `4829103`)
* Shopify `legacyResourceId` (for example `11592011448585`)
* Shopify GID (for example `gid://shopify/Order/11592011448585`)
* Shopify order name (for example `DE13778080`)

### Deprecated hold actions

`hive_hold_order` and `hive_release_order` still exist for older workflows. Use **`hive_set_order_hold`** with `hold: true` or `hold: false` instead — one action covers both directions.

<Steps>
  <Step title="Connect Hive and Shopify">
    Complete the setup above on the same workspace.
  </Step>

  <Step title="Enable actions on the agent">
    In [AI Agents](https://armin.cx/app/_/ai/agents-v2), enable read actions for lookup and write actions for cancel, hold, and address changes. Select which connected Hive account(s) the agent may use.
  </Step>

  <Step title="Set approvals">
    Keep **Cancel Hive order**, **Hold / release Hive order**, and **Update Hive shipping address** on **Always require approval** until you trust production runs.
  </Step>

  <Step title="Add instructions">
    Tell the agent to call **Get Hive orders for customer** or **Get Shopify order** first, use **Get Hive shipments** for tracking questions, and explain when an order is already shipped or cancelled. For holds, use the Shopify legacy id from **Get Shopify order**.
  </Step>
</Steps>

## Best practices

* Connect Shopify before Hive so inbox orders and WISMO lookups resolve correctly
* Put write actions on approval until test tickets look safe
* Use **Hold / release order** (`hive_set_order_hold`) instead of the deprecated hold and release actions
* Pause orders only while the customer confirms a change — release when they are done
* Tell agents and AI to hand off when the order is already shipped, cancelled, or ignored
* Watch for Hive API rate limits on busy stores; retry or escalate if lookups fail repeatedly
* For multi-store setups, use clear Hive account display names so the right integration is selected

## FAQ

**Do I need Shopify if I only use Hive?**\
Yes, for inbox order display and **Get orders for customer**. Hive orders are matched through Shopify merchant order ids on the same organization.

**Why does hold in the inbox tag Shopify?**\
The inbox hold button tags the linked Shopify order with `cx-on-hold`. That is how cx pauses fulfillment for agents in the UI. AI Agent hold actions follow the same Shopify-backed path.

**When can agents put an order on hold?**\
When fulfillment status is **waiting for picking** and the order is not already shipped, cancelled, or ignored.

**Which order id should AI Agents use for hold and address updates?**\
The numeric Shopify **legacyResourceId** from **Get Shopify order**. Do not use the Hive internal id field from a Hive response for those writes.

**What if Hive returns a rate limit error?**\
Wait and retry, or have a human complete the action in Hive. Heavy automation on one store can hit Hive API limits.

**Can I still use Workflows?**\
Yes. Legacy workflows can call Hive nodes for fixed flows. For new automation, use AI Agents and the actions above.