# Faire API

> Every Faire endpoint on Cotlet: inputs, JSON Schema, cURL, Python and Node.js examples and an example response for each call.

Source: https://cotlet.dev/docs/api/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 endpoints for Faire. Each one is a POST with a JSON body, called with your API key.

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

## Endpoints

| Endpoint | Access | Description |
|---|---|---|
| `list_orders` | read | Wholesale orders, newest first, with retailer, total, status and ship-by date. |
| `get_order` | read | One order with items, SKUs, quantities, wholesale prices, ship-to address and shipments. |
| `get_inventory` | read | Available quantity for each product variant, by SKU. |
| `list_customers` | read | Retailers on your customer list with order count and last order date. |
| `list_conversations` | read | Conversations in your Messages tab, with retailer, last message and whether a reply is needed. |
| `get_conversation` | read | Messages in one conversation with a retailer, oldest first. |
| `get_faire_direct_link` | read | Your Faire Direct link, to share with retailers you already work with. |
| `accept_order` | write | Accept a new order and set the scheduled ship date. The retailer is notified. |
| `add_shipment` | write | Add carrier, tracking number and package cost to an order. The retailer is notified. |
| `update_inventory` | write | Set the available quantity of product variants by SKU. |
| `reply_to_message` | write | Send a message as your brand in an existing conversation with a retailer. |
| `send_campaign` | write | Send an email campaign to chosen retailers through Faire Campaigns. |

## List orders

`POST https://cotlet.dev/api/v1/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. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/faire/list_orders \
  -H "Authorization: Bearer $COTLET_API_KEY"
```

**Python**

```python
result = client.call("faire", "list_orders")
```

**Node.js**

```js
const result = await cotlet.call('faire', 'list_orders');
```

**CLI**

```bash
cotlet call faire list_orders
```

### Example response

```json
{
  "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
}
```

## Get order

`POST https://cotlet.dev/api/v1/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. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/faire/get_order \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"order_id":"order_8c41d2"}'
```

**Python**

```python
result = client.call("faire", "get_order", {"order_id":"order_8c41d2"})
```

**Node.js**

```js
const result = await cotlet.call('faire', 'get_order', {"order_id":"order_8c41d2"});
```

**CLI**

```bash
cotlet call faire get_order --data '{"order_id":"order_8c41d2"}'
```

### Example response

```json
{
  "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": []
}
```

## Get inventory

`POST https://cotlet.dev/api/v1/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. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/faire/get_inventory \
  -H "Authorization: Bearer $COTLET_API_KEY"
```

**Python**

```python
result = client.call("faire", "get_inventory")
```

**Node.js**

```js
const result = await cotlet.call('faire', 'get_inventory');
```

**CLI**

```bash
cotlet call faire get_inventory
```

### Example response

```json
{
  "items": [
    {
      "sku": "CNDL-AMB-01",
      "quantity": 84
    },
    {
      "sku": "CNDL-CDR-02",
      "quantity": 0
    }
  ]
}
```

## List customers

`POST https://cotlet.dev/api/v1/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. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/faire/list_customers \
  -H "Authorization: Bearer $COTLET_API_KEY"
```

**Python**

```python
result = client.call("faire", "list_customers")
```

**Node.js**

```js
const result = await cotlet.call('faire', 'list_customers');
```

**CLI**

```bash
cotlet call faire list_customers
```

### Example response

```json
{
  "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
}
```

## List conversations

`POST https://cotlet.dev/api/v1/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. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/faire/list_conversations \
  -H "Authorization: Bearer $COTLET_API_KEY"
```

**Python**

```python
result = client.call("faire", "list_conversations")
```

**Node.js**

```js
const result = await cotlet.call('faire', 'list_conversations');
```

**CLI**

```bash
cotlet call faire list_conversations
```

### Example response

```json
{
  "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
}
```

## Get conversation

`POST https://cotlet.dev/api/v1/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. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/faire/get_conversation \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"conversation_id":"conversation_8c41d2"}'
```

**Python**

```python
result = client.call("faire", "get_conversation", {"conversation_id":"conversation_8c41d2"})
```

**Node.js**

```js
const result = await cotlet.call('faire', 'get_conversation', {"conversation_id":"conversation_8c41d2"});
```

**CLI**

```bash
cotlet call faire get_conversation --data '{"conversation_id":"conversation_8c41d2"}'
```

### Example response

```json
{
  "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"
    }
  ]
}
```

## Get Faire Direct link

`POST https://cotlet.dev/api/v1/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.

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/faire/get_faire_direct_link \
  -H "Authorization: Bearer $COTLET_API_KEY"
```

**Python**

```python
result = client.call("faire", "get_faire_direct_link")
```

**Node.js**

```js
const result = await cotlet.call('faire', 'get_faire_direct_link');
```

**CLI**

```bash
cotlet call faire get_faire_direct_link
```

### Example response

```json
{
  "url": "https://www.faire.com/direct/example-candle-co"
}
```

## Accept order

`POST https://cotlet.dev/api/v1/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. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/faire/accept_order \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"order_id":"order_8c41d2","ship_by":"2026-10-01"}'
```

**Python**

```python
result = client.call("faire", "accept_order", {"order_id":"order_8c41d2","ship_by":"2026-10-01"})
```

**Node.js**

```js
const result = await cotlet.call('faire', 'accept_order', {"order_id":"order_8c41d2","ship_by":"2026-10-01"});
```

**CLI**

```bash
cotlet call faire accept_order --data '{"order_id":"order_8c41d2","ship_by":"2026-10-01"}'
```

### Example response

```json
{
  "order_id": "bo_8x2k4m9q",
  "status": "Processing",
  "ship_by": "2026-10-16"
}
```

## Add shipment

`POST https://cotlet.dev/api/v1/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. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/faire/add_shipment \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"order_id":"bo_8x2k4m9q","carrier":"UPS","tracking_code":"1Z999AA10123456784","package_cost":12.4}'
```

**Python**

```python
result = client.call("faire", "add_shipment", {"order_id":"bo_8x2k4m9q","carrier":"UPS","tracking_code":"1Z999AA10123456784","package_cost":12.4})
```

**Node.js**

```js
const result = await cotlet.call('faire', 'add_shipment', {"order_id":"bo_8x2k4m9q","carrier":"UPS","tracking_code":"1Z999AA10123456784","package_cost":12.4});
```

**CLI**

```bash
cotlet call faire add_shipment --data '{"order_id":"bo_8x2k4m9q","carrier":"UPS","tracking_code":"1Z999AA10123456784","package_cost":12.4}'
```

### Example response

```json
{
  "order_id": "bo_8x2k4m9q",
  "status": "Shipped",
  "shipment": {
    "carrier": "UPS",
    "tracking_code": "1Z999AA10123456784",
    "package_cost": 12.4
  }
}
```

## Update inventory

`POST https://cotlet.dev/api/v1/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 }. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/faire/update_inventory \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"items":["items"]}'
```

**Python**

```python
result = client.call("faire", "update_inventory", {"items":["items"]})
```

**Node.js**

```js
const result = await cotlet.call('faire', 'update_inventory', {"items":["items"]});
```

**CLI**

```bash
cotlet call faire update_inventory --data '{"items":["items"]}'
```

### Example response

```json
{
  "updated": [
    {
      "sku": "CNDL-AMB-01",
      "quantity": 120
    },
    {
      "sku": "CNDL-CDR-02",
      "quantity": 48
    }
  ]
}
```

## Reply to message

`POST https://cotlet.dev/api/v1/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. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/faire/reply_to_message \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"conversation_id":"cv_4f7a21","body":"Thanks for asking! Your candles ship on Friday 16 Oct and the tracking link follows by email."}'
```

**Python**

```python
result = client.call("faire", "reply_to_message", {"conversation_id":"cv_4f7a21","body":"Thanks for asking! Your candles ship on Friday 16 Oct and the tracking link follows by email."})
```

**Node.js**

```js
const result = await cotlet.call('faire', 'reply_to_message', {"conversation_id":"cv_4f7a21","body":"Thanks for asking! Your candles ship on Friday 16 Oct and the tracking link follows by email."});
```

**CLI**

```bash
cotlet call faire reply_to_message --data '{"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
{
  "conversation_id": "cv_4f7a21",
  "message_id": "msg_9d20",
  "status": "sent"
}
```

## Send campaign

`POST https://cotlet.dev/api/v1/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. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/faire/send_campaign \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"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"]}'
```

**Python**

```python
result = client.call("faire", "send_campaign", {"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"]})
```

**Node.js**

```js
const result = await cotlet.call('faire', 'send_campaign', {"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"]});
```

**CLI**

```bash
cotlet call faire send_campaign --data '{"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
{
  "campaign_id": "cp_30b9",
  "status": "sent",
  "recipients": 3,
  "subject": "Your fall restock is ready"
}
```