Faire API and MCP server

• POST

  list_orders

  Wholesale orders, newest first, with retailer, total, status and ship-by date.

  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.

  POST /api/v1/faire/list_orders

  Input

  Input: list_orders

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

  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

  get_order

  One order with items, SKUs, quantities, wholesale prices, ship-to address and shipments.

  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.

  POST /api/v1/faire/get_order

  Input

  Input: get_order

  Parameter	Type	Description
  order_id required	string	Order ID from list_orders, e.g. bo_8x2k4m9q.

  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

  get_inventory

  Available quantity for each product variant, by SKU.

  read

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

  POST /api/v1/faire/get_inventory

  Input

  Input: get_inventory

  Parameter	Type	Description
  skus	string[]	SKUs to check. Default: all variants.

  Example response

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

• POST

  list_customers

  Retailers on your customer list with order count and last order date.

  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.

  POST /api/v1/faire/list_customers

  Input

  Input: list_customers

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

  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

  list_conversations

  Conversations in your Messages tab, with retailer, last message and whether a reply is needed.

  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.

  POST /api/v1/faire/list_conversations

  Input

  Input: list_conversations

  Parameter	Type	Description
  needs_reply	boolean	Only conversations waiting for your reply.
  limit	integer	1 to 50. Default: 20.
  cursor	string	Next page cursor from the previous call.

  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

  get_conversation

  Messages in one conversation with a retailer, oldest first.

  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.

  POST /api/v1/faire/get_conversation

  Input

  Input: get_conversation

  Parameter	Type	Description
  conversation_id required	string	Conversation ID from list_conversations.

  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

  get_faire_direct_link

  Your Faire Direct link, to share with retailers you already work with.

  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.

  POST /api/v1/faire/get_faire_direct_link

  Input

  No parameters.

  Example response

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

• POST

  accept_order

  Accept a new order and set the scheduled ship date. The retailer is notified.

  asks first write

  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.

  POST /api/v1/faire/accept_order

  Input

  Input: accept_order

  Parameter	Type	Description
  order_id required	string	Order ID from list_orders, e.g. bo_8x2k4m9q.
  ship_by required	date	Scheduled ship date.

  Example response

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

• POST

  add_shipment

  Add carrier, tracking number and package cost to an order. The retailer is notified.

  asks first write

  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.

  POST /api/v1/faire/add_shipment

  Input

  Input: add_shipment

  Parameter	Type	Description
  order_id required	string	Order ID from list_orders, e.g. bo_8x2k4m9q.
  carrier required	string	Carrier name, e.g. UPS or USPS.
  tracking_code required	string	Tracking number.
  package_cost required	number	Cost of the package.

  Example response

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

• POST

  update_inventory

  Set the available quantity of product variants by SKU.

  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.

  POST /api/v1/faire/update_inventory

  Input

  Input: update_inventory

  Parameter	Type	Description
  items required	object[]	List of { sku, quantity }.

  Example response

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

• POST

  reply_to_message

  Send a message as your brand in an existing conversation with a retailer.

  asks first write

  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.

  POST /api/v1/faire/reply_to_message

  Input

  Input: reply_to_message

  Parameter	Type	Description
  conversation_id required	string	Conversation ID from list_conversations.
  body required	string	Message text.

  Example response

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

• POST

  send_campaign

  Send an email campaign to chosen retailers through Faire Campaigns.

  asks first write

  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.

  POST /api/v1/faire/send_campaign

  Input

  Input: send_campaign

  Parameter	Type	Description
  subject required	string	Email subject line.
  body_markdown required	string	Campaign text. Images by URL.
  retailer_ids required	string[]	Recipients from list_customers.
  include_faire_direct_link	boolean	Add your Faire Direct link. Default: false.

  Example response

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

Each successful call uses credits for the work it takes; failed calls and timeouts cost nothing. A hard spend cap is on by default. Authenticate with the Authorization: Bearer header.