Faire API

POST https://cotlet.dev/api/v1/faire/list_orders

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

Request

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

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

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

cotlet call faire list_orders

Example response

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

POST https://cotlet.dev/api/v1/faire/get_order

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

Request

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"}'

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

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

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

Example response

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

POST https://cotlet.dev/api/v1/faire/get_inventory

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

Parameters

Request

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

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

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

cotlet call faire get_inventory

Example response

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

POST https://cotlet.dev/api/v1/faire/list_customers

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

Request

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

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

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

cotlet call faire list_customers

Example response

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

POST https://cotlet.dev/api/v1/faire/list_conversations

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

Request

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

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

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

cotlet call faire list_conversations

Example response

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

POST https://cotlet.dev/api/v1/faire/get_conversation

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

Request

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"}'

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

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

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

Example response

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

POST https://cotlet.dev/api/v1/faire/get_faire_direct_link

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 -X POST https://cotlet.dev/api/v1/faire/get_faire_direct_link \
  -H "Authorization: Bearer $COTLET_API_KEY"

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

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

cotlet call faire get_faire_direct_link

Example response

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

POST https://cotlet.dev/api/v1/faire/accept_order

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

Request

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"}'

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

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

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

Example response

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

POST https://cotlet.dev/api/v1/faire/add_shipment

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

Request

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}'

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

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

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

Example response

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

POST https://cotlet.dev/api/v1/faire/update_inventory

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

Request

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"]}'

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

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

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

Example response

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

POST https://cotlet.dev/api/v1/faire/reply_to_message

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

Request

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."}'

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."})

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."});

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

{
  "conversation_id": "cv_4f7a21",
  "message_id": "msg_9d20",
  "status": "sent"
}

POST https://cotlet.dev/api/v1/faire/send_campaign

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

Request

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"]}'

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"]})

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"]});

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

{
  "campaign_id": "cp_30b9",
  "status": "sent",
  "recipients": 3,
  "subject": "Your fall restock is ready"
}