> ## Documentation Index
> Fetch the complete documentation index at: https://docs.supercycle.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Tools
> Reference of the tools available in the Operators MCP for managing cycles, fulfillments, receivals, inventory, products, customers, returns, charges, pricing, availability, and tags
List tools support pagination (`page`, `per_page` max 100), sorting (`sort`, `sort_direction`), and date filtering (`created_after`, `created_before`, `updated_after`, `updated_before`) in `YYYY-MM-DD` format.
***
## Cycles
List cycles filtered by status, method, dates, and packing status.
| Parameter | Values |
| --------------------------------------- | --------------------------------------------------------------------------------------- |
| `status` | `upcoming`, `active`, `complete`, `to_fulfill`, `to_receive`, `to_restock`, `cancelled` |
| `method_type` | `calendar`, `subscription`, `membership`, `resale` |
| `packing_status` | `pending`, `printed`, `packed` |
| `rental_start_from` / `rental_start_to` | Date range for rental start |
| `customer_email` | Partial match |
| `item_title` | Partial match |
Optionally include related data with `include_customer`, `include_item`, `include_order`, `include_line_item`.
Get full details of a single cycle by ID.
| Parameter | Required | Description |
| --------- | -------- | ------------------------- |
| `id` | Yes | Cycle ID (e.g. `SC-1234`) |
Returns the complete cycle record with customer, item, order, charges, and return data.
Update a cycle's packing status, dates, or item assignment. Requires confirmation.
| Parameter | Description |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id` | Cycle ID (required) |
| `packing_status` | `pending`, `printed`, `packed` |
| `item_id` | Item ID to assign |
| `rental_start` / `rental_end` | Reschedule dates (`YYYY-MM-DD`) |
| `fulfilled_at` / `received_at` | Mark as fulfilled or received (`YYYY-MM-DD`) |
| `prepare_from` / `restock_by` | Override the preparation start or restock end date (`YYYY-MM-DD`). Pass `null` to revert to the automatic date computed from the shop's [logistics buffers](/documentation/configuration/logistics/buffers). |
***
## Outbound fulfillments
Outbound fulfillments are the packing queue: each one groups the cycles going out to a customer together, so one update moves every cycle travelling together.
List the outbound fulfillment queue with status and date filters.
| Parameter | Values |
| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `status` | `pending` (not yet fulfilled), `due` (fulfill by today or unscheduled), `overdue`, `scheduled` (fulfill date in the future), `fulfilled` |
| `delivery_method_type` | `shipping`, `pick_up` |
| `customer_email` | Partial match |
| `fulfill_by_after` / `fulfill_by_before` | Fulfill-by date range (`YYYY-MM-DD`) |
Sortable by `created_at`, `fulfill_by`, or `arrive_by`. Each fulfillment carries its schedule dates, customer, and the cycles going out together with their packing statuses.
Get full details of a single outbound fulfillment.
| Parameter | Required | Description |
| --------- | -------- | --------------------------------- |
| `id` | Yes | Outbound fulfillment ID (numeric) |
Returns schedule dates, status, delivery method, customer, order, and the cycles going out together with their items, packing statuses, pick locations, and serials.
Update an outbound fulfillment's schedule dates or mark it fulfilled. Requires confirmation.
| Parameter | Description |
| ------------------ | -------------------------------------------------------------------------------------------------------- |
| `id` | Outbound fulfillment ID (required) |
| `arrive_by` | Date the items should reach the customer (`YYYY-MM-DD`) |
| `fulfill_by` | Date the items must be sent out (`YYYY-MM-DD`) |
| `prepare_from` | Override the computed preparation start date (`YYYY-MM-DD`) |
| `expected_arrival` | Expected arrival date of a sent fulfillment (`YYYY-MM-DD`) |
| `fulfilled_at` | When the items were sent (`YYYY-MM-DD`, ISO 8601, or `now`). Setting this marks the fulfillment complete |
| `pin_dates` | Date fields to hold in place while others recompute: `arrive_by`, `fulfill_by`, `prepare_from` |
Moving a boundary date recomputes the dependent dates unless they are pinned. Pass `clear` as any date value to null it and let it recompute; `clear` on `fulfilled_at` marks the fulfillment not fulfilled after all.
***
## Inbound receivals
Inbound receivals are the receiving queue: each one groups the cycles coming back from a customer together.
List the inbound receival queue with status and date filters.
| Parameter | Values |
| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `status` | `pending` (not yet received), `due` (receive by today or unscheduled), `overdue`, `scheduled` (receive date in the future), `received` |
| `return_method_type` | `shipping`, `drop_off` |
| `customer_email` | Partial match |
| `receive_by_after` / `receive_by_before` | Receive-by date range (`YYYY-MM-DD`) |
Sortable by `created_at`, `receive_by`, or `return_by`. Each receival carries its schedule dates, customer, and the cycles coming back together.
Get full details of a single inbound receival.
| Parameter | Required | Description |
| --------- | -------- | ----------------------------- |
| `id` | Yes | Inbound receival ID (numeric) |
Returns schedule dates, status, return method, customer, order, and the cycles coming back together with their items.
Update an inbound receival's schedule dates or mark it received. Requires confirmation.
| Parameter | Description |
| ----------------- | -------------------------------------------------------------------------------------------------------------- |
| `id` | Inbound receival ID (required) |
| `return_by` | Date the customer must send or hand the items back (`YYYY-MM-DD`) |
| `receive_by` | Date the items should be back with the store (`YYYY-MM-DD`) |
| `restock_by` | Override the computed restock date (`YYYY-MM-DD`) |
| `expected_return` | Expected return date of items already on their way back (`YYYY-MM-DD`) |
| `received_at` | When the items were received back (`YYYY-MM-DD`, ISO 8601, or `now`). Setting this marks the receival complete |
| `pin_dates` | Date fields to hold in place while others recompute: `return_by`, `receive_by`, `restock_by` |
Moving a boundary date recomputes the dependent dates unless they are pinned. Pass `clear` as any date value to null it and let it recompute; `clear` on `received_at` marks the receival not received after all.
***
## Inventory
List inventory items filtered by visibility, status, condition, and availability.
| Parameter | Values |
| ------------------- | ----------------------------------------------- |
| `visibility` | `available`, `unavailable`, `sold`, `retired` |
| `processing_status` | `unprocessed`, `processed` |
| `available` | `true` (not rented), `false` (currently rented) |
| `product_title` | Partial match |
| `sku` | Partial match |
| `condition_id` | Filter by condition |
Returns item ID, product/variant title, SKU, serial, visibility, condition, and pick location.
Get full details of a single inventory item by ID.
| Parameter | Required | Description |
| --------- | -------- | ---------------------- |
| `id` | Yes | Item ID (e.g. `#1042`) |
Returns the complete item record with serial, SKU, condition, visibility, processing status, pick location, tags, custom fields, acquisition cost and lifecycle revenue, the current and upcoming cycles, and blocked dates. Blocked dates include blocks inherited from the item's variant, product, or the whole store; cycle bookings are not included.
Update an item's condition, serial, pick location, or visibility. Requires confirmation.
| Parameter | Description |
| --------------- | --------------------------------------------------------- |
| `id` | Item ID (required) |
| `condition_id` | Condition ID to assign |
| `serial` | Serial number, unique per store |
| `pick_location` | Free-text pick/storage location (e.g. `Shelf B3`) |
| `visibility` | `available`, `unavailable`, `sold`, `retired`, `expected` |
Pass `clear` as the value for `condition_id`, `serial`, or `pick_location` to remove it.
***
## Products
List catalog products filtered by title, status, and enabled cycle methods.
| Parameter | Values |
| ------------- | ------------------------------------------------------------------------------------------------------ |
| `title` | Partial match |
| `status` | `active`, `archived`, `draft`, `unlisted` |
| `method_type` | Only products with this method enabled: `subscription`, `membership`, `calendar`, `resale`, `trade_in` |
Sortable by `created_at` or `title`. Returns per-product method flags plus variant and item counts.
Get full details of a single product.
| Parameter | Required | Description |
| --------- | -------- | ------------------------------------------------------- |
| `id` | Yes | Shopify product ID, internal ID, handle, or exact title |
Returns status, vendor, tags, per-method configuration with option counts, variants with their inventory counts, inventory totals, and cycle activity counts. Products backed by a membership plan, bundle, card authorisation, or deposit are classified by `kind` and returned without inventory.
***
## Customers
List customers filtered by activity, value, and balance.
| Parameter | Description |
| ------------------------------- | --------------------------- |
| `customer_email` | Partial match |
| `name` | Partial match |
| `has_active_rentals` | `true` or `false` |
| `lifetime_value_min_cents` | Minimum lifetime value |
| `outstanding_balance_min_cents` | Minimum outstanding balance |
Sortable by `lifetime_value_cents`, `rentals_count`, `outstanding_balance_cents`.
Get full details of a single customer.
| Parameter | Required | Description |
| --------- | -------- | --------------------------------------------------- |
| `id` | Yes | Customer email, Shopify customer ID, or internal ID |
Returns contact info and default address, lifetime value, outstanding and deposit balances, cycle counts, membership status, identity verification status, and tags.
***
## Returns
List returns filtered by status, receival, and credit status.
| Parameter | Values |
| ----------------- | ---------------------------------------------------------------------------- |
| `status` | `requested`, `expected`, `received`, `in_progress`, `completed`, `cancelled` |
| `receival_status` | `unreceived`, `partially_received`, `received` |
| `credit_status` | `uncredited`, `partially_recredited`, `recredited` |
| `incomplete` | `true` to show only incomplete returns |
| `customer_email` | Partial match |
Optionally include related data with `include_customer`, `include_return_lines`.
Get full details of a single return by ID.
| Parameter | Required | Description |
| --------- | -------- | ------------------------ |
| `id` | Yes | Return ID (e.g. `#2001`) |
Returns the complete return record with customer, return lines, conditions, return method, and tags.
Create a return order for a customer. Requires confirmation.
| Parameter | Required | Description |
| -------------------- | -------- | --------------------------------------------------- |
| `customer_id` | Yes | Customer email or Shopify ID |
| `rental_ids` | Yes | Array of rental IDs (e.g. `['SC-1042', 'SC-1043']`) |
| `return_method_type` | No | `collection` or `return_label` |
Update a return order's status or return line statuses. Requires confirmation.
| Parameter | Description |
| -------------- | ------------------------------------------------------------------------------ |
| `id` | Return ID (required) |
| `status` | `requested`, `expected`, `received`, `in_progress`, `completed`, `cancelled` |
| `return_lines` | Array of `{ id, status }` where status is `awaiting`, `received`, or `missing` |
***
## Charges
List charges with optional status filtering.
| Parameter | Description |
| --------------------------------------- | -------------------------------------------- |
| `status` | `paid`, `unpaid`, `cancelled` (default: all) |
| `customer_email` | Partial match |
| `amount_min_cents` / `amount_max_cents` | Filter by amount |
| `category_type` | `Checkout`, `Generic`, `BillingCycle` |
Optionally include related data with `include_customer`, `include_dunning`.
Get full details of a single charge by ID.
| Parameter | Required | Description |
| --------- | -------- | ------------------------ |
| `id` | Yes | Charge ID (e.g. `#3001`) |
Returns the charge with amounts paid and due, each payment attempt with its line breakdown and order, the linked cycle or membership, and the payment collector's retry state.
***
## Pricing
List pricing options for a given method, filtered by product and price range.
| Parameter | Required | Description |
| ------------------------------------- | -------- | -------------------------------------------------- |
| `method_type` | Yes | `subscription`, `membership`, `calendar`, `resale` |
| `product_id` | No | Filter by product |
| `price_min_cents` / `price_max_cents` | No | Filter by price |
Returns method-specific fields (e.g. recurring price and billing interval for subscriptions, duration for calendar).
***
## Availability
Check whether a product or variant can be booked for a date range, accounting for the preparation, delivery, return, and restock time from your [logistics buffers](/documentation/configuration/logistics/buffers) around both the proposed booking and existing reservations.
| Parameter | Required | Description |
| ----------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `variant_id` / `sku` / `product_id` / `product_title` | One of | Which variants to check. SKU and product title support partial matches; product lookups check all variants |
| `start_date` | Yes | The day the customer receives the item (`YYYY-MM-DD`) |
| `end_date` | No | The day the customer hands the item back (`YYYY-MM-DD`). Omit for an open-ended booking (e.g. a subscription), which conflicts with any future block |
| `delivery_method_type` | No | `shipping` or `pick_up` (default: the shop default) |
| `return_method_type` | No | `shipping` or `drop_off` (default: the shop default) |
Returns, per variant: a bookable verdict with item counts, the contiguous available windows around the requested dates, and per-item conflicts showing each block's padded date range and the cycle causing it. When transit time is the only blocker, an alternative verdict for pick-up delivery with drop-off return is included. Checks up to 10 matching variants.
List blocked date ranges, optionally scoped to a resource or filtered to a date window. Cycle bookings are not included.
| Parameter | Description |
| --------------- | ---------------------------------------------------------------------------------- |
| `resource_type` | Only include blocks on this resource type: `item`, `variant`, `product`, or `shop` |
| `resource_id` | Resource ID to scope to. Required with `resource_type` except for `shop` |
| `from` / `to` | Only include blocks overlapping this date window (`YYYY-MM-DD`) |
Sortable by `created_at` or `from`. Dates are day-bounded in the shop timezone. Each result includes its ID, which `delete_blocked_date` takes.
Block an item, variant, or product from being booked over a date range. Requires confirmation.
| Parameter | Required | Description |
| --------------- | -------- | ------------------------------------------------------------------------------------- |
| `resource_type` | Yes | `item`, `variant`, or `product` |
| `resource_id` | Yes | Formatted or numeric ID for items; Shopify ID or numeric ID for variants and products |
| `from` | No | First blocked date (`YYYY-MM-DD`, inclusive). Omit for open-ended start. |
| `to` | No | Last blocked date (`YYYY-MM-DD`, inclusive). Omit for open-ended end. |
| `description` | No | Optional note (e.g. `Repairs`, `Reserved for photoshoot`) |
At least one of `from` or `to` must be provided. Dates are day-bounded in the shop timezone.
Delete a blocked date range so the resource can be booked again. Requires confirmation.
| Parameter | Required | Description |
| --------- | -------- | ----------------------------------------------------------------------------- |
| `id` | Yes | Blocked date ID, as returned by `list_blocked_dates` or `create_blocked_date` |
Deleting cannot be undone; recreate the block with `create_blocked_date` if needed. Cycle bookings cannot be deleted this way.
***
## Tags
List all tags on a cycle, item, or return.
| Parameter | Required | Description |
| --------------- | -------- | ---------------------------- |
| `resource_type` | Yes | `cycle`, `item`, or `return` |
| `resource_id` | Yes | Resource ID (e.g. `#1042`) |
Add a tag to a cycle, item, or return. Idempotent. Requires confirmation.
| Parameter | Required | Description |
| --------------- | -------- | ---------------------------- |
| `resource_type` | Yes | `cycle`, `item`, or `return` |
| `resource_id` | Yes | Resource ID (e.g. `#1042`) |
| `tag` | Yes | Tag title to add |
Remove a tag from a cycle, item, or return. Idempotent. Requires confirmation.
| Parameter | Required | Description |
| --------------- | -------- | ---------------------------- |
| `resource_type` | Yes | `cycle`, `item`, or `return` |
| `resource_id` | Yes | Resource ID (e.g. `#1042`) |
| `tag` | Yes | Tag title to remove |
***
## Comments
List the comments/notes on a cycle, item, customer, or return, newest first.
| Parameter | Required | Description |
| --------------- | -------- | ---------------------------------------- |
| `resource_type` | Yes | `cycle`, `item`, `customer`, or `return` |
| `resource_id` | Yes | Resource ID or email for customers |
Each comment includes its message, author, and timestamp.
Add a comment/note to a cycle, item, customer, or return. Requires confirmation.
| Parameter | Required | Description |
| --------------- | -------- | ---------------------------------------- |
| `resource_type` | Yes | `cycle`, `item`, `customer`, or `return` |
| `resource_id` | Yes | Resource ID or email for customers |
| `body` | Yes | Comment text |