# Faire MCP tools

> Every Faire MCP tool on the Cotlet server: tool names, input schemas, a tools/call example and an example result for each tool.

Source: https://cotlet.dev/docs/mcp/faire

Docs sections: [Get started](https://cotlet.dev/docs.md) · [REST API](https://cotlet.dev/docs/api.md) · [MCP](https://cotlet.dev/docs/mcp.md) · [SDKs & CLI](https://cotlet.dev/docs/sdks.md) · [Integrations](https://cotlet.dev/docs/integrations.md)

12 tools for Faire on the Cotlet MCP server. Your agent picks them from tools/list.

- MCP server: `https://cotlet.dev/mcp/v1`
- Connects with: Your own Faire brand account (the brand portal)
- Integration page: https://cotlet.dev/integrations/faire-api-mcp-server

## Endpoints

| Endpoint | Access | Description |
|---|---|---|
| `faire_list_orders` | read | Wholesale orders, newest first, with retailer, total, status and ship-by date. |
| `faire_get_order` | read | One order with items, SKUs, quantities, wholesale prices, ship-to address and shipments. |
| `faire_get_inventory` | read | Available quantity for each product variant, by SKU. |
| `faire_list_customers` | read | Retailers on your customer list with order count and last order date. |
| `faire_list_conversations` | read | Conversations in your Messages tab, with retailer, last message and whether a reply is needed. |
| `faire_get_conversation` | read | Messages in one conversation with a retailer, oldest first. |
| `faire_get_faire_direct_link` | read | Your Faire Direct link, to share with retailers you already work with. |
| `faire_accept_order` | write | Accept a new order and set the scheduled ship date. The retailer is notified. |
| `faire_add_shipment` | write | Add carrier, tracking number and package cost to an order. The retailer is notified. |
| `faire_update_inventory` | write | Set the available quantity of product variants by SKU. |
| `faire_reply_to_message` | write | Send a message as your brand in an existing conversation with a retailer. |
| `faire_send_campaign` | write | Send an email campaign to chosen retailers through Faire Campaigns. |

## List orders

MCP tool: `faire_list_orders`

Access: read.

Lists your wholesale orders, newest first. Filter by status or by the date an order was placed to see what is new since your last check. Totals are wholesale prices. Pages hold up to 100 orders; pass next_cursor back as cursor for the next page.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `status` | string | no | Order status as the portal shows it, e.g. New or Processing. Default: all. |
| `since` | date | no | Only orders placed on or after this date. |
| `retailer_id` | string | no | Only orders from this retailer. |
| `limit` | integer | no | 1 to 100. Default: 50. |
| `cursor` | string | no | Next page cursor from the previous call. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "faire_list_orders",
    "arguments": {}
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "orders": [
      {
        "order_id": "bo_8x2k4m9q",
        "retailer": "Example Gift Shop",
        "retailer_id": "r_61d0c3",
        "status": "New",
        "total": 408,
        "currency": "USD",
        "placed_at": "2026-10-08T15:12:00Z",
        "ship_by": "2026-10-16"
      }
    ],
    "next_cursor": null
  },
  "isError": false
}
```

## Get order

MCP tool: `faire_get_order`

Access: read.

Returns one order in full: each item with SKU, quantity and wholesale price, the ship-to address and any shipments already added. The order total is the sum of the item lines.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `order_id` | string | yes | Order ID from list_orders, e.g. bo_8x2k4m9q. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "faire_get_order",
    "arguments": {
      "order_id": "order_8c41d2"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "order_id": "bo_8x2k4m9q",
    "status": "New",
    "retailer": "Example Gift Shop",
    "items": [
      {
        "sku": "CNDL-AMB-01",
        "name": "Amber candle",
        "quantity": 12,
        "unit_price": 14,
        "line_total": 168
      },
      {
        "sku": "CNDL-CDR-02",
        "name": "Cedar candle",
        "quantity": 12,
        "unit_price": 14,
        "line_total": 168
      },
      {
        "sku": "MTCH-BOX-01",
        "name": "Match box",
        "quantity": 12,
        "unit_price": 6,
        "line_total": 72
      }
    ],
    "total": 408,
    "currency": "USD",
    "ship_to": {
      "city": "Portland",
      "region": "OR",
      "country": "US"
    },
    "shipments": []
  },
  "isError": false
}
```

## Get inventory

MCP tool: `faire_get_inventory`

Access: read.

Returns the on-hand quantity Faire shows for each variant, keyed by SKU. Pass skus to check only some variants.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `skus` | string[] | no | SKUs to check. Default: all variants. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "faire_get_inventory",
    "arguments": {}
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "items": [
      {
        "sku": "CNDL-AMB-01",
        "quantity": 84
      },
      {
        "sku": "CNDL-CDR-02",
        "quantity": 0
      }
    ]
  },
  "isError": false
}
```

## List customers

MCP tool: `faire_list_customers`

Access: read.

Lists retailers on your customer list, with how many orders each placed and the date of the last one. Use last_order_before to find retailers who stopped ordering. Pass retailer_id values to send_campaign.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `last_order_before` | date | no | Only retailers whose last order is older than this date. |
| `limit` | integer | no | 1 to 100. Default: 50. |
| `cursor` | string | no | Next page cursor from the previous call. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "faire_list_customers",
    "arguments": {}
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "customers": [
      {
        "retailer_id": "r_61d0c3",
        "name": "Example Gift Shop",
        "orders": 3,
        "last_order_at": "2026-04-12"
      },
      {
        "retailer_id": "r_9a3e77",
        "name": "Harbor Home Store",
        "orders": 1,
        "last_order_at": "2026-03-02"
      }
    ],
    "next_cursor": null
  },
  "isError": false
}
```

## List conversations

MCP tool: `faire_list_conversations`

Access: read.

Lists your conversations with retailers, most recent first. Set needs_reply to see only the threads waiting for you, the ones the portal groups under Needs Reply.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `needs_reply` | boolean | no | Only conversations waiting for your reply. |
| `limit` | integer | no | 1 to 50. Default: 20. |
| `cursor` | string | no | Next page cursor from the previous call. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "faire_list_conversations",
    "arguments": {}
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "conversations": [
      {
        "conversation_id": "cv_4f7a21",
        "retailer": "Example Gift Shop",
        "last_message": "When will the candles ship?",
        "needs_reply": true,
        "updated_at": "2026-10-09T10:41:00Z"
      }
    ],
    "next_cursor": null
  },
  "isError": false
}
```

## Get conversation

MCP tool: `faire_get_conversation`

Access: read.

Returns the messages of one conversation, oldest first, so your agent reads the thread in order before answering. Attachments are listed by file name only.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `conversation_id` | string | yes | Conversation ID from list_conversations. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "faire_get_conversation",
    "arguments": {
      "conversation_id": "conversation_8c41d2"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "conversation_id": "cv_4f7a21",
    "retailer": "Example Gift Shop",
    "messages": [
      {
        "from": "retailer",
        "body": "Hi! When will the candles ship?",
        "sent_at": "2026-10-09T10:41:00Z"
      }
    ]
  },
  "isError": false
}
```

## Get Faire Direct link

MCP tool: `faire_get_faire_direct_link`

Access: read.

Returns the Faire Direct link from your brand portal. A retailer who signs up for Faire through this link can qualify for 0% commission on orders with you. Use it in campaigns and messages.

### Parameters

No parameters.

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "faire_get_faire_direct_link",
    "arguments": {}
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "url": "https://www.faire.com/direct/example-candle-co"
  },
  "isError": false
}
```

## Accept order

MCP tool: `faire_accept_order`

Access: write. Confirm: waits for the user's OK before it runs.

Accepts one new order with a scheduled ship date. Faire emails the retailer that the order is processing. Replacement orders are not covered by Faire's auto-accept, so use this tool for them. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `order_id` | string | yes | Order ID from list_orders, e.g. bo_8x2k4m9q. |
| `ship_by` | date | yes | Scheduled ship date. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "faire_accept_order",
    "arguments": {
      "order_id": "order_8c41d2",
      "ship_by": "2026-10-01"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "order_id": "bo_8x2k4m9q",
    "status": "Processing",
    "ship_by": "2026-10-16"
  },
  "isError": false
}
```

## Add shipment

MCP tool: `faire_add_shipment`

Access: write. Confirm: waits for the user's OK before it runs.

Adds a shipment to an order, the same as Ship on your own in the portal: carrier, tracking number and package cost. Faire emails the retailer a tracking link when the order ships. If Faire does not support the carrier, it marks the order shipped on its own 72 hours after the date you added the tracking. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `order_id` | string | yes | Order ID from list_orders, e.g. bo_8x2k4m9q. |
| `carrier` | string | yes | Carrier name, e.g. UPS or USPS. |
| `tracking_code` | string | yes | Tracking number. |
| `package_cost` | number | yes | Cost of the package. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "faire_add_shipment",
    "arguments": {
      "order_id": "bo_8x2k4m9q",
      "carrier": "UPS",
      "tracking_code": "1Z999AA10123456784",
      "package_cost": 12.4
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "order_id": "bo_8x2k4m9q",
    "status": "Shipped",
    "shipment": {
      "carrier": "UPS",
      "tracking_code": "1Z999AA10123456784",
      "package_cost": 12.4
    }
  },
  "isError": false
}
```

## Update inventory

MCP tool: `faire_update_inventory`

Access: write.

Sets the available quantity for one or more variants by SKU, so Faire matches your warehouse. It reaches no one directly and one more call restores the old numbers, so update_inventory runs without asking first.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `items` | object[] | yes | List of { sku, quantity }. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "faire_update_inventory",
    "arguments": {
      "items": [
        "items"
      ]
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "updated": [
      {
        "sku": "CNDL-AMB-01",
        "quantity": 120
      },
      {
        "sku": "CNDL-CDR-02",
        "quantity": 48
      }
    ]
  },
  "isError": false
}
```

## Reply to message

MCP tool: `faire_reply_to_message`

Access: write. Confirm: waits for the user's OK before it runs.

Sends a text message in an existing conversation, under your brand name. It cannot start a conversation and cannot attach files; use the portal on desktop for attachments. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `conversation_id` | string | yes | Conversation ID from list_conversations. |
| `body` | string | yes | Message text. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "faire_reply_to_message",
    "arguments": {
      "conversation_id": "cv_4f7a21",
      "body": "Thanks for asking! Your candles ship on Friday 16 Oct and the tracking link follows by email."
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "conversation_id": "cv_4f7a21",
    "message_id": "msg_9d20",
    "status": "sent"
  },
  "isError": false
}
```

## Send campaign

MCP tool: `faire_send_campaign`

Access: write. Confirm: waits for the user's OK before it runs.

Sends an email through Faire's Campaigns tool to the retailers you choose. Sending is free, but Faire limits it: 1 email a week to retailers who have not ordered from you, 2 a week to existing customers, and 1 campaign per retailer per day. Keep the bounce rate under 10% and the spam rate under 0.1% per campaign. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `subject` | string | yes | Email subject line. |
| `body_markdown` | string | yes | Campaign text. Images by URL. |
| `retailer_ids` | string[] | yes | Recipients from list_customers. |
| `include_faire_direct_link` | boolean | no | Add your Faire Direct link. Default: false. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "faire_send_campaign",
    "arguments": {
      "subject": "Your fall candle restock",
      "body_markdown": "Hi! Our fall candles are in stock, including Amber. Your last order was in July, so here is what is new before the holidays.",
      "retailer_ids": [
        "r_9a3e77",
        "r_61d0c3"
      ]
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "campaign_id": "cp_30b9",
    "status": "sent",
    "recipients": 3,
    "subject": "Your fall restock is ready"
  },
  "isError": false
}
```