# Faire

> Run your Faire wholesale brand from workflows: pick up new orders, accept them, backorder items, add shipments with tracking and cancel them; keep products, variants, prices and stock in step with your other channels. Start a workflow when an order comes in, changes state, ships or is canceled, or a product changes.

App · 21 actions. Web page: https://docs.lodol.com/docs/integrations/faire

## Actions

### Accept order

Accept a new order, which moves it to Processing. Faire tells the retailer you've accepted it.

**Inputs**

- Order (`order`, text, required): The order's ID (it starts with bo_), from the trigger or another Faire step.
- Expected ship date (`expected_ship_date`, date): When you expect to ship it, which Faire shows the retailer.

**Outputs**

- `created_at` (text): When it was placed (ISO 8601)
- `currency` (text): The currency, such as USD
- `customer_name` (text): The name of the person who placed it
- `display_id` (text): The order number Faire shows
- `expected_ship_date` (text): When it's expected to ship (ISO 8601)
- `id` (text): The order's ID, such as bo_bxdmjbwxid
- `item_count` (number): How many different items it has
- `items` (list): What was ordered
- `notes` (text): The retailer's notes or special requests for you
- `purchase_order_number` (text): The retailer's purchase order number, if given
- `retailer_id` (text): The retailer's ID; 'Get retailer' gives their store
- `ship_after` (text): The retailer's earliest ship date (ISO 8601); empty if none
- `ship_to_address1` (text): The street address
- `ship_to_address2` (text): The second address line
- `ship_to_city` (text): The city
- `ship_to_company` (text): The store or company it ships to
- `ship_to_country` (text): The country's three-letter code, such as CAN
- `ship_to_name` (text): Who it ships to
- `ship_to_phone` (text): The phone number to ship to
- `ship_to_postal_code` (text): The postal code
- `ship_to_state` (text): The state or province code, such as ON
- `shipments` (list): The shipments added to it
- `state` (text): Its state: NEW, PROCESSING, PRE_TRANSIT, IN_TRANSIT, DELIVERED, PENDING_RETAILER_CONFIRMATION, BACKORDERED or CANCELED
- `state_label` (text): Its state in words, such as Processing
- `subtotal` (number): The items' wholesale value: each price times its quantity
- `total_payout` (number): What Faire pays you for it; 0 if Faire doesn't say yet
- `total_quantity` (number): How many units in all
- `updated_at` (text): When it last changed (ISO 8601)

**Example output**

```json
{
  "created_at": "2026-11-05T09:00:00.000Z",
  "currency": "USD",
  "customer_name": "John Smith",
  "display_id": "BXDMJBWXID",
  "expected_ship_date": "2026-11-12T00:00:00.000Z",
  "id": "bo_bxdmjbwxid",
  "item_count": 1,
  "items": [
    {
      "currency": "USD",
      "id": "oi_bq425ju5vh",
      "price": 49.99,
      "product_id": "p_fccaefnahr",
      "product_name": "Golden Dog",
      "quantity": 2,
      "sku": "goldenretriever",
      "state": "NEW",
      "variant_id": "po_3745tjzrpc",
      "variant_name": ""
    }
  ],
  "notes": "Please include a handwritten thank-you note",
  "purchase_order_number": "12345",
  "retailer_id": "r_c9385ldj",
  "ship_after": "",
  "ship_to_address1": "41 King Street West",
  "ship_to_address2": "3rd Floor",
  "ship_to_city": "Kitchener",
  "ship_to_company": "Faire Wholesale, Inc",
  "ship_to_country": "CAN",
  "ship_to_name": "John Smith",
  "ship_to_phone": "555-123-4567",
  "ship_to_postal_code": "N2G 1A1",
  "ship_to_state": "ON",
  "shipments": [],
  "state": "NEW",
  "state_label": "New",
  "subtotal": 99.98,
  "total_payout": 80.0,
  "total_quantity": 2,
  "updated_at": "2026-11-05T09:00:00.000Z"
}
```

### Add shipment

Add a shipment to an order with its carrier and tracking code, which marks the order as shipped. Faire sends the retailer the tracking.

**Inputs**

- Order (`order`, text, required): The order's ID (it starts with bo_), from the trigger or another Faire step.
- Carrier (`carrier`, text, required): Who is carrying it. For another carrier, add the shipment in Faire instead. One of: `UPS`, `USPS`, `FEDEX`, `DHL_EXPRESS` (DHL Express), `DHL_ECOMMERCE` (DHL eCommerce), `CANADA_POST` (Canada Post), `PUROLATOR`, `CANPAR`, `ROYAL_MAIL` (Royal Mail), `PARCELFORCE`, and 8 more.
- Tracking code (`tracking_code`, text, required): The carrier's tracking code.
- Shipping cost (`shipping_cost`, number, required): What you paid to ship it, such as 12.40. At least 0.
- Currency (`currency`, text): The shipping cost's currency. Leave blank for the one your brand sells in. One of: `USD` (US dollars (USD), for the United States), `CAD` (Canadian dollars (CAD), for Canada), `GBP` (Pounds (GBP), for the United Kingdom), `EUR` (Euros (EUR), for the European Union), `AUD` (Australian dollars (AUD), for Australia).

**Outputs**

- `created_at` (text): When it was placed (ISO 8601)
- `currency` (text): The currency, such as USD
- `customer_name` (text): The name of the person who placed it
- `display_id` (text): The order number Faire shows
- `expected_ship_date` (text): When it's expected to ship (ISO 8601)
- `id` (text): The order's ID, such as bo_bxdmjbwxid
- `item_count` (number): How many different items it has
- `items` (list): What was ordered
- `notes` (text): The retailer's notes or special requests for you
- `purchase_order_number` (text): The retailer's purchase order number, if given
- `retailer_id` (text): The retailer's ID; 'Get retailer' gives their store
- `ship_after` (text): The retailer's earliest ship date (ISO 8601); empty if none
- `ship_to_address1` (text): The street address
- `ship_to_address2` (text): The second address line
- `ship_to_city` (text): The city
- `ship_to_company` (text): The store or company it ships to
- `ship_to_country` (text): The country's three-letter code, such as CAN
- `ship_to_name` (text): Who it ships to
- `ship_to_phone` (text): The phone number to ship to
- `ship_to_postal_code` (text): The postal code
- `ship_to_state` (text): The state or province code, such as ON
- `shipments` (list): The shipments added to it
- `state` (text): Its state: NEW, PROCESSING, PRE_TRANSIT, IN_TRANSIT, DELIVERED, PENDING_RETAILER_CONFIRMATION, BACKORDERED or CANCELED
- `state_label` (text): Its state in words, such as Processing
- `subtotal` (number): The items' wholesale value: each price times its quantity
- `total_payout` (number): What Faire pays you for it; 0 if Faire doesn't say yet
- `total_quantity` (number): How many units in all
- `updated_at` (text): When it last changed (ISO 8601)

**Example output**

```json
{
  "created_at": "2026-11-05T09:00:00.000Z",
  "currency": "USD",
  "customer_name": "John Smith",
  "display_id": "BXDMJBWXID",
  "expected_ship_date": "2026-11-12T00:00:00.000Z",
  "id": "bo_bxdmjbwxid",
  "item_count": 1,
  "items": [
    {
      "currency": "USD",
      "id": "oi_bq425ju5vh",
      "price": 49.99,
      "product_id": "p_fccaefnahr",
      "product_name": "Golden Dog",
      "quantity": 2,
      "sku": "goldenretriever",
      "state": "NEW",
      "variant_id": "po_3745tjzrpc",
      "variant_name": ""
    }
  ],
  "notes": "Please include a handwritten thank-you note",
  "purchase_order_number": "12345",
  "retailer_id": "r_c9385ldj",
  "ship_after": "",
  "ship_to_address1": "41 King Street West",
  "ship_to_address2": "3rd Floor",
  "ship_to_city": "Kitchener",
  "ship_to_company": "Faire Wholesale, Inc",
  "ship_to_country": "CAN",
  "ship_to_name": "John Smith",
  "ship_to_phone": "555-123-4567",
  "ship_to_postal_code": "N2G 1A1",
  "ship_to_state": "ON",
  "shipments": [],
  "state": "NEW",
  "state_label": "New",
  "subtotal": 99.98,
  "total_payout": 80.0,
  "total_quantity": 2,
  "updated_at": "2026-11-05T09:00:00.000Z"
}
```

### Backorder item

Tell Faire you can't ship all of an item on an order now: how many you can ship, and the day the rest will be ready, or that it's discontinued. Faire asks the retailer whether to wait.

**Inputs**

- Order (`order`, text, required): The order's ID (it starts with bo_), from the trigger or another Faire step.
- Item (`item`, text, required): The order item's ID (it starts with oi_), or its SKU on this order.
- Can ship now (`available_quantity`, number): How many of the item you can ship now. Leave blank for none. At least 0.
- Ready on (`backordered_until`, date): The day the rest will be ready to ship. Needed unless the item is discontinued.
- Discontinued (`discontinued`, true/false): Turn on if you'll never have the rest.

**Outputs**

- `created_at` (text): When it was placed (ISO 8601)
- `currency` (text): The currency, such as USD
- `customer_name` (text): The name of the person who placed it
- `display_id` (text): The order number Faire shows
- `expected_ship_date` (text): When it's expected to ship (ISO 8601)
- `id` (text): The order's ID, such as bo_bxdmjbwxid
- `item_count` (number): How many different items it has
- `items` (list): What was ordered
- `notes` (text): The retailer's notes or special requests for you
- `purchase_order_number` (text): The retailer's purchase order number, if given
- `retailer_id` (text): The retailer's ID; 'Get retailer' gives their store
- `ship_after` (text): The retailer's earliest ship date (ISO 8601); empty if none
- `ship_to_address1` (text): The street address
- `ship_to_address2` (text): The second address line
- `ship_to_city` (text): The city
- `ship_to_company` (text): The store or company it ships to
- `ship_to_country` (text): The country's three-letter code, such as CAN
- `ship_to_name` (text): Who it ships to
- `ship_to_phone` (text): The phone number to ship to
- `ship_to_postal_code` (text): The postal code
- `ship_to_state` (text): The state or province code, such as ON
- `shipments` (list): The shipments added to it
- `state` (text): Its state: NEW, PROCESSING, PRE_TRANSIT, IN_TRANSIT, DELIVERED, PENDING_RETAILER_CONFIRMATION, BACKORDERED or CANCELED
- `state_label` (text): Its state in words, such as Processing
- `subtotal` (number): The items' wholesale value: each price times its quantity
- `total_payout` (number): What Faire pays you for it; 0 if Faire doesn't say yet
- `total_quantity` (number): How many units in all
- `updated_at` (text): When it last changed (ISO 8601)

**Example output**

```json
{
  "created_at": "2026-11-05T09:00:00.000Z",
  "currency": "USD",
  "customer_name": "John Smith",
  "display_id": "BXDMJBWXID",
  "expected_ship_date": "2026-11-12T00:00:00.000Z",
  "id": "bo_bxdmjbwxid",
  "item_count": 1,
  "items": [
    {
      "currency": "USD",
      "id": "oi_bq425ju5vh",
      "price": 49.99,
      "product_id": "p_fccaefnahr",
      "product_name": "Golden Dog",
      "quantity": 2,
      "sku": "goldenretriever",
      "state": "NEW",
      "variant_id": "po_3745tjzrpc",
      "variant_name": ""
    }
  ],
  "notes": "Please include a handwritten thank-you note",
  "purchase_order_number": "12345",
  "retailer_id": "r_c9385ldj",
  "ship_after": "",
  "ship_to_address1": "41 King Street West",
  "ship_to_address2": "3rd Floor",
  "ship_to_city": "Kitchener",
  "ship_to_company": "Faire Wholesale, Inc",
  "ship_to_country": "CAN",
  "ship_to_name": "John Smith",
  "ship_to_phone": "555-123-4567",
  "ship_to_postal_code": "N2G 1A1",
  "ship_to_state": "ON",
  "shipments": [],
  "state": "NEW",
  "state_label": "New",
  "subtotal": 99.98,
  "total_payout": 80.0,
  "total_quantity": 2,
  "updated_at": "2026-11-05T09:00:00.000Z"
}
```

### Cancel order

Cancel an order that is new, processing, backordered or waiting for the retailer. Faire tells the retailer why, with your note. This can't be undone.

**Inputs**

- Order (`order`, text, required): The order's ID (it starts with bo_), from the trigger or another Faire step.
- Reason (`reason`, text, required): Why you're canceling. One of: `ITEM_OUT_OF_STOCK` (Items are out of stock), `REQUESTED_BY_RETAILER` (The retailer asked to cancel), `CHANGE_REPLACE_ORDER` (The retailer wants to change or replace the order), `RETAILER_NOT_GOOD_FIT` (The retailer isn't a good fit), `INCORRECT_PRICING` (Items are priced wrongly), `ORDER_TOO_SMALL` (The order is too small), `REJECT_INTERNATIONAL_ORDER` (You don't sell in the retailer's country), `OTHER` (Another reason).
- Note to the retailer (`note`, text, required): Why you're canceling, in your words: 30 to 1,000 characters. Faire shows it to the retailer.

**Outputs**

- `created_at` (text): When it was placed (ISO 8601)
- `currency` (text): The currency, such as USD
- `customer_name` (text): The name of the person who placed it
- `display_id` (text): The order number Faire shows
- `expected_ship_date` (text): When it's expected to ship (ISO 8601)
- `id` (text): The order's ID, such as bo_bxdmjbwxid
- `item_count` (number): How many different items it has
- `items` (list): What was ordered
- `notes` (text): The retailer's notes or special requests for you
- `purchase_order_number` (text): The retailer's purchase order number, if given
- `retailer_id` (text): The retailer's ID; 'Get retailer' gives their store
- `ship_after` (text): The retailer's earliest ship date (ISO 8601); empty if none
- `ship_to_address1` (text): The street address
- `ship_to_address2` (text): The second address line
- `ship_to_city` (text): The city
- `ship_to_company` (text): The store or company it ships to
- `ship_to_country` (text): The country's three-letter code, such as CAN
- `ship_to_name` (text): Who it ships to
- `ship_to_phone` (text): The phone number to ship to
- `ship_to_postal_code` (text): The postal code
- `ship_to_state` (text): The state or province code, such as ON
- `shipments` (list): The shipments added to it
- `state` (text): Its state: NEW, PROCESSING, PRE_TRANSIT, IN_TRANSIT, DELIVERED, PENDING_RETAILER_CONFIRMATION, BACKORDERED or CANCELED
- `state_label` (text): Its state in words, such as Processing
- `subtotal` (number): The items' wholesale value: each price times its quantity
- `total_payout` (number): What Faire pays you for it; 0 if Faire doesn't say yet
- `total_quantity` (number): How many units in all
- `updated_at` (text): When it last changed (ISO 8601)

**Example output**

```json
{
  "created_at": "2026-11-05T09:00:00.000Z",
  "currency": "USD",
  "customer_name": "John Smith",
  "display_id": "BXDMJBWXID",
  "expected_ship_date": "2026-11-12T00:00:00.000Z",
  "id": "bo_bxdmjbwxid",
  "item_count": 1,
  "items": [
    {
      "currency": "USD",
      "id": "oi_bq425ju5vh",
      "price": 49.99,
      "product_id": "p_fccaefnahr",
      "product_name": "Golden Dog",
      "quantity": 2,
      "sku": "goldenretriever",
      "state": "NEW",
      "variant_id": "po_3745tjzrpc",
      "variant_name": ""
    }
  ],
  "notes": "Please include a handwritten thank-you note",
  "purchase_order_number": "12345",
  "retailer_id": "r_c9385ldj",
  "ship_after": "",
  "ship_to_address1": "41 King Street West",
  "ship_to_address2": "3rd Floor",
  "ship_to_city": "Kitchener",
  "ship_to_company": "Faire Wholesale, Inc",
  "ship_to_country": "CAN",
  "ship_to_name": "John Smith",
  "ship_to_phone": "555-123-4567",
  "ship_to_postal_code": "N2G 1A1",
  "ship_to_state": "ON",
  "shipments": [],
  "state": "NEW",
  "state_label": "New",
  "subtotal": 99.98,
  "total_payout": 80.0,
  "total_quantity": 2,
  "updated_at": "2026-11-05T09:00:00.000Z"
}
```

### Create product

Add a product with one variant: its SKU, wholesale and retail prices and stock. It starts as a draft unless you publish it. Add more variants with 'Create variant'.

**Inputs**

- Name (`name`, text, required): What the product is called.
- Product type (`product_type`, text, required): The kind of product, such as Votive Candle.
- SKU (`sku`, text, required): The product's SKU.
- Wholesale price (`wholesale_price`, number, required): What retailers pay for one, such as 12.50. At least 0.
- Retail price (`retail_price`, number, required): The price you suggest retailers sell one at, such as 25. At least 0.
- Currency (`currency`, text): The prices' currency. Leave blank for the one your brand sells in. One of: `USD` (US dollars (USD), for the United States), `CAD` (Canadian dollars (CAD), for Canada), `GBP` (Pounds (GBP), for the United Kingdom), `EUR` (Euros (EUR), for the European Union), `AUD` (Australian dollars (AUD), for Australia).
- State (`state`, text): Whether retailers can see it yet. A published product needs an image. One of: `DRAFT` (Draft: not shown to retailers), `PUBLISHED` (Published: retailers can order it). Default: `DRAFT`.
- Description (`description`, text): What retailers read about it.
- Short description (`short_description`, text): A line about it, up to 255 characters.
- Stock (`available_quantity`, number): How many you have to sell. At least 0.
- Image addresses (`image_urls`, list): Web addresses of its images, starting with https://.
- Sold in packs of (`unit_multiplier`, number): How many units retailers buy at a time, such as 6. Leave blank for one. At least 1.
- Minimum order (`minimum_order_quantity`, number): The fewest units a retailer can order, a whole number of packs. Leave blank for one pack. At least 0.
- Option (`option_name`, text): What its variants differ by, such as Scent or Size. It can't be added later, so give it if you'll add variants.
- This variant's option (`option_value`, text): This first variant's value of that option, such as Vanilla.

**Outputs**

- `created_at` (text): When it was added (ISO 8601)
- `description` (text): Its description
- `id` (text): The product's ID, such as p_fccaefnahr
- `image_urls` (list): Its images' addresses
- `lifecycle_state` (text): PUBLISHED, DRAFT, UNPUBLISHED or DELETED
- `minimum_order_quantity` (number): The fewest a retailer can order
- `name` (text): Its name
- `product_type` (text): Its product type, such as Votive Candle
- `product_type_id` (text): Its product type's ID, such as tt_23nl3bzl00
- `sale_state` (text): Whether it's for sale, such as FOR_SALE
- `short_description` (text): Its short description
- `unit_multiplier` (number): How many units it's sold in at a time
- `updated_at` (text): When it last changed (ISO 8601)
- `variant_count` (number): How many variants it has
- `variants` (list): Its variants

**Example output**

```json
{
  "created_at": "2026-11-05T09:00:00.000Z",
  "description": "Glad you decided to read our description!",
  "id": "p_fccaefnahr",
  "image_urls": [
    "https://cdn.example.com/candle.jpg"
  ],
  "lifecycle_state": "PUBLISHED",
  "minimum_order_quantity": 8,
  "name": "Faire's fantastic candle",
  "product_type": "Votive Candle",
  "product_type_id": "tt_23nl3bzl00",
  "sale_state": "FOR_SALE",
  "short_description": "Our candles smell fantastic.",
  "unit_multiplier": 8,
  "updated_at": "2026-11-05T09:00:00.000Z",
  "variant_count": 1,
  "variants": [
    {
      "available_quantity": 24,
      "backordered_until": "",
      "created_at": "2026-11-05T09:00:00.000Z",
      "currency": "USD",
      "id": "po_3745tjzrpc",
      "lifecycle_state": "PUBLISHED",
      "name": "Vanilla",
      "options": {
        "Scent": "Vanilla"
      },
      "prices": [
        {
          "country": "USA",
          "country_group": "",
          "currency": "USD",
          "retail_price": 10.0,
          "wholesale_price": 5.0
        }
      ],
      "product_id": "p_fccaefnahr",
      "retail_price": 10.0,
      "sale_state": "FOR_SALE",
      "sku": "vanilla-candle",
      "tariff_code": "",
      "updated_at": "2026-11-05T09:00:00.000Z",
      "wholesale_price": 5.0
    }
  ]
}
```

### Create variant

Add a variant, such as another size or colour, to a product, with its SKU, prices and stock.

**Inputs**

- Product (`product`, text, required): The product. Pick one, or give its ID (it starts with p_).
- SKU (`sku`, text, required): The variant's SKU.
- Name (`name`, text): The variant's name, such as Large.
- Options (`options`, object): Its options by name, such as {"Size": "Large"}, using the product's own option names. A new value is added to the product for you.
- Wholesale price (`wholesale_price`, number, required): What retailers pay for one, such as 12.50. At least 0.
- Retail price (`retail_price`, number, required): The price you suggest retailers sell one at, such as 25. At least 0.
- Currency (`currency`, text): The prices' currency. Leave blank for the one your brand sells in. One of: `USD` (US dollars (USD), for the United States), `CAD` (Canadian dollars (CAD), for Canada), `GBP` (Pounds (GBP), for the United Kingdom), `EUR` (Euros (EUR), for the European Union), `AUD` (Australian dollars (AUD), for Australia).
- Stock (`available_quantity`, number): How many you have to sell. At least 0.
- Image addresses (`image_urls`, list): Web addresses of its images, starting with https://.

**Outputs**

- `available_quantity` (number): How many Faire shows as available
- `backordered_until` (text): When it's back in stock (ISO 8601); empty if not
- `created_at` (text): When it was added (ISO 8601)
- `currency` (text): Those prices' currency
- `id` (text): The variant's ID, such as po_3745tjzrpc
- `lifecycle_state` (text): PUBLISHED, DRAFT, UNPUBLISHED or DELETED
- `name` (text): Its name, if it has one
- `options` (object): Its options by name, such as {"Scent": "Vanilla"}
- `prices` (list): Its prices for each country or group of countries
- `product_id` (text): Its product's ID
- `retail_price` (number): Its suggested retail price, from its first price
- `sale_state` (text): Whether it's for sale, such as FOR_SALE
- `sku` (text): Its SKU
- `tariff_code` (text): Its tariff (HS) code
- `updated_at` (text): When it last changed (ISO 8601)
- `wholesale_price` (number): Its wholesale price, from its first price

**Example output**

```json
{
  "available_quantity": 24,
  "backordered_until": "",
  "created_at": "2026-11-05T09:00:00.000Z",
  "currency": "USD",
  "id": "po_3745tjzrpc",
  "lifecycle_state": "PUBLISHED",
  "name": "Vanilla",
  "options": {
    "Scent": "Vanilla"
  },
  "prices": [
    {
      "country": "USA",
      "country_group": "",
      "currency": "USD",
      "retail_price": 10.0,
      "wholesale_price": 5.0
    }
  ],
  "product_id": "p_fccaefnahr",
  "retail_price": 10.0,
  "sale_state": "FOR_SALE",
  "sku": "vanilla-candle",
  "tariff_code": "",
  "updated_at": "2026-11-05T09:00:00.000Z",
  "wholesale_price": 5.0
}
```

### Delete product

Delete a product. Faire marks it deleted and retailers no longer see it; this can't be undone here.

**Inputs**

- Product (`product`, text, required): The product. Pick one, or give its ID (it starts with p_).

**Outputs**

- `deleted` (true/false): True once deleted
- `id` (text): The ID of what was deleted

**Example output**

```json
{
  "deleted": true,
  "id": "p_fccaefnahr"
}
```

### Delete variant

Delete one of a product's variants. A product keeps at least one: to remove the last, delete the product.

**Inputs**

- Product (`product`, text, required): The product. Pick one, or give its ID (it starts with p_).
- Variant (`variant`, text, required): The variant to delete. Pick one, or give its ID or SKU.

**Outputs**

- `deleted` (true/false): True once deleted
- `id` (text): The ID of what was deleted

**Example output**

```json
{
  "deleted": true,
  "id": "po_3745tjzrpc"
}
```

### Get brand profile

Get your brand's name, ID, the currency you sell in and your locale.

**Inputs**: None.

**Outputs**

- `brand_id` (text): Your brand's ID
- `currency` (text): The currency you sell in, such as USD
- `locale` (text): Your brand's locale, such as en-US
- `name` (text): Your brand's name

**Example output**

```json
{
  "brand_id": "b_60ae65c4",
  "currency": "USD",
  "locale": "en-US",
  "name": "Jeff's Warm Toques"
}
```

### Get order

Get an order with its items, the address it ships to, its payout and its shipments.

**Inputs**

- Order (`order`, text, required): The order's ID (it starts with bo_), from the trigger or another Faire step.

**Outputs**

- `created_at` (text): When it was placed (ISO 8601)
- `currency` (text): The currency, such as USD
- `customer_name` (text): The name of the person who placed it
- `display_id` (text): The order number Faire shows
- `expected_ship_date` (text): When it's expected to ship (ISO 8601)
- `id` (text): The order's ID, such as bo_bxdmjbwxid
- `item_count` (number): How many different items it has
- `items` (list): What was ordered
- `notes` (text): The retailer's notes or special requests for you
- `purchase_order_number` (text): The retailer's purchase order number, if given
- `retailer_id` (text): The retailer's ID; 'Get retailer' gives their store
- `ship_after` (text): The retailer's earliest ship date (ISO 8601); empty if none
- `ship_to_address1` (text): The street address
- `ship_to_address2` (text): The second address line
- `ship_to_city` (text): The city
- `ship_to_company` (text): The store or company it ships to
- `ship_to_country` (text): The country's three-letter code, such as CAN
- `ship_to_name` (text): Who it ships to
- `ship_to_phone` (text): The phone number to ship to
- `ship_to_postal_code` (text): The postal code
- `ship_to_state` (text): The state or province code, such as ON
- `shipments` (list): The shipments added to it
- `state` (text): Its state: NEW, PROCESSING, PRE_TRANSIT, IN_TRANSIT, DELIVERED, PENDING_RETAILER_CONFIRMATION, BACKORDERED or CANCELED
- `state_label` (text): Its state in words, such as Processing
- `subtotal` (number): The items' wholesale value: each price times its quantity
- `total_payout` (number): What Faire pays you for it; 0 if Faire doesn't say yet
- `total_quantity` (number): How many units in all
- `updated_at` (text): When it last changed (ISO 8601)

**Example output**

```json
{
  "created_at": "2026-11-05T09:00:00.000Z",
  "currency": "USD",
  "customer_name": "John Smith",
  "display_id": "BXDMJBWXID",
  "expected_ship_date": "2026-11-12T00:00:00.000Z",
  "id": "bo_bxdmjbwxid",
  "item_count": 1,
  "items": [
    {
      "currency": "USD",
      "id": "oi_bq425ju5vh",
      "price": 49.99,
      "product_id": "p_fccaefnahr",
      "product_name": "Golden Dog",
      "quantity": 2,
      "sku": "goldenretriever",
      "state": "NEW",
      "variant_id": "po_3745tjzrpc",
      "variant_name": ""
    }
  ],
  "notes": "Please include a handwritten thank-you note",
  "purchase_order_number": "12345",
  "retailer_id": "r_c9385ldj",
  "ship_after": "",
  "ship_to_address1": "41 King Street West",
  "ship_to_address2": "3rd Floor",
  "ship_to_city": "Kitchener",
  "ship_to_company": "Faire Wholesale, Inc",
  "ship_to_country": "CAN",
  "ship_to_name": "John Smith",
  "ship_to_phone": "555-123-4567",
  "ship_to_postal_code": "N2G 1A1",
  "ship_to_state": "ON",
  "shipments": [],
  "state": "NEW",
  "state_label": "New",
  "subtotal": 99.98,
  "total_payout": 80.0,
  "total_quantity": 2,
  "updated_at": "2026-11-05T09:00:00.000Z"
}
```

### Get product

Get a product with its type, images and every variant's SKU, prices and stock, even if it was deleted.

**Inputs**

- Product (`product`, text, required): The product. Pick one, or give its ID (it starts with p_).

**Outputs**

- `created_at` (text): When it was added (ISO 8601)
- `description` (text): Its description
- `id` (text): The product's ID, such as p_fccaefnahr
- `image_urls` (list): Its images' addresses
- `lifecycle_state` (text): PUBLISHED, DRAFT, UNPUBLISHED or DELETED
- `minimum_order_quantity` (number): The fewest a retailer can order
- `name` (text): Its name
- `product_type` (text): Its product type, such as Votive Candle
- `product_type_id` (text): Its product type's ID, such as tt_23nl3bzl00
- `sale_state` (text): Whether it's for sale, such as FOR_SALE
- `short_description` (text): Its short description
- `unit_multiplier` (number): How many units it's sold in at a time
- `updated_at` (text): When it last changed (ISO 8601)
- `variant_count` (number): How many variants it has
- `variants` (list): Its variants

**Example output**

```json
{
  "created_at": "2026-11-05T09:00:00.000Z",
  "description": "Glad you decided to read our description!",
  "id": "p_fccaefnahr",
  "image_urls": [
    "https://cdn.example.com/candle.jpg"
  ],
  "lifecycle_state": "PUBLISHED",
  "minimum_order_quantity": 8,
  "name": "Faire's fantastic candle",
  "product_type": "Votive Candle",
  "product_type_id": "tt_23nl3bzl00",
  "sale_state": "FOR_SALE",
  "short_description": "Our candles smell fantastic.",
  "unit_multiplier": 8,
  "updated_at": "2026-11-05T09:00:00.000Z",
  "variant_count": 1,
  "variants": [
    {
      "available_quantity": 24,
      "backordered_until": "",
      "created_at": "2026-11-05T09:00:00.000Z",
      "currency": "USD",
      "id": "po_3745tjzrpc",
      "lifecycle_state": "PUBLISHED",
      "name": "Vanilla",
      "options": {
        "Scent": "Vanilla"
      },
      "prices": [
        {
          "country": "USA",
          "country_group": "",
          "currency": "USD",
          "retail_price": 10.0,
          "wholesale_price": 5.0
        }
      ],
      "product_id": "p_fccaefnahr",
      "retail_price": 10.0,
      "sale_state": "FOR_SALE",
      "sku": "vanilla-candle",
      "tariff_code": "",
      "updated_at": "2026-11-05T09:00:00.000Z",
      "wholesale_price": 5.0
    }
  ]
}
```

### Get retailer

Get the store behind an order: its name, and whether it's a Faire Insider.

**Inputs**

- Retailer (`retailer`, text, required): The retailer's ID (it starts with r_), such as an order's retailer ID.

**Outputs**

- `is_insider` (true/false): True if the retailer has an active Faire Insider membership
- `name` (text): Their store's name
- `retailer_id` (text): The retailer's ID

**Example output**

```json
{
  "is_insider": true,
  "name": "Faire Wholesale, Inc",
  "retailer_id": "r_c9385ldj"
}
```

### Get stock

Get how many of each SKU you have on hand, how many are promised to orders, and how many retailers can still order.

**Inputs**

- SKUs (`skus`, list, required): The SKUs to look up. Pick them, or type them.

**Outputs**

- `count` (number): How many SKUs are listed
- `inventories` (list): Each SKU's stock

**Example output**

```json
{
  "count": 1,
  "inventories": [
    {
      "available_quantity": 20,
      "committed_quantity": 4,
      "on_hand_quantity": 24,
      "sku": "vanilla-candle",
      "tracked": true
    }
  ]
}
```

### Get variant

Get one of a product's variants by its ID or SKU, with its options, prices and stock.

**Inputs**

- Product (`product`, text, required): The product. Pick one, or give its ID (it starts with p_).
- Variant (`variant`, text, required): The variant. Pick one, or give its ID or SKU.

**Outputs**

- `available_quantity` (number): How many Faire shows as available
- `backordered_until` (text): When it's back in stock (ISO 8601); empty if not
- `created_at` (text): When it was added (ISO 8601)
- `currency` (text): Those prices' currency
- `id` (text): The variant's ID, such as po_3745tjzrpc
- `lifecycle_state` (text): PUBLISHED, DRAFT, UNPUBLISHED or DELETED
- `name` (text): Its name, if it has one
- `options` (object): Its options by name, such as {"Scent": "Vanilla"}
- `prices` (list): Its prices for each country or group of countries
- `product_id` (text): Its product's ID
- `retail_price` (number): Its suggested retail price, from its first price
- `sale_state` (text): Whether it's for sale, such as FOR_SALE
- `sku` (text): Its SKU
- `tariff_code` (text): Its tariff (HS) code
- `updated_at` (text): When it last changed (ISO 8601)
- `wholesale_price` (number): Its wholesale price, from its first price

**Example output**

```json
{
  "available_quantity": 24,
  "backordered_until": "",
  "created_at": "2026-11-05T09:00:00.000Z",
  "currency": "USD",
  "id": "po_3745tjzrpc",
  "lifecycle_state": "PUBLISHED",
  "name": "Vanilla",
  "options": {
    "Scent": "Vanilla"
  },
  "prices": [
    {
      "country": "USA",
      "country_group": "",
      "currency": "USD",
      "retail_price": 10.0,
      "wholesale_price": 5.0
    }
  ],
  "product_id": "p_fccaefnahr",
  "retail_price": 10.0,
  "sale_state": "FOR_SALE",
  "sku": "vanilla-candle",
  "tariff_code": "",
  "updated_at": "2026-11-05T09:00:00.000Z",
  "wholesale_price": 5.0
}
```

### List orders

List your Faire orders, oldest change first, by state and date. Gets one page; to see more, run it again with the next page.

**Inputs**

- States (`states`, list): Only orders in these states. Leave blank for every state. One or more of: `NEW`, `PROCESSING`, `PRE_TRANSIT` (Pre-transit), `IN_TRANSIT` (In transit), `DELIVERED`, `PENDING_RETAILER_CONFIRMATION` (Waiting for the retailer to confirm), `BACKORDERED`, `CANCELED`.
- Placed after (`created_after`, date and time): Only orders placed at or after this time.
- Changed after (`updated_after`, date and time): Only orders that changed at or after this time.
- Can ship by (`ship_after_before`, date and time): Only orders the retailer lets you ship by this time: their earliest ship date is no later.
- Sort by (`sort_by`, text): List them by when they last changed or when they were placed, oldest first. One of: `UPDATED_AT` (Last change), `CREATED_AT` (When placed). Default: `UPDATED_AT`.
- How many (`limit`, number): How many to list on this page, from 10 to 50. Defaults to 50. From 10 to 50.
- Page (`page`, number): Which page to list, starting at 1. Use the next number when the last answer said there may be more. At least 1.

**Outputs**

- `count` (number): How many are listed
- `has_more` (true/false): True when there may be another page
- `orders` (list): The orders found, oldest change first
- `page` (number): The page these are

**Example output**

```json
{
  "count": 1,
  "has_more": false,
  "orders": [
    {
      "created_at": "2026-11-05T09:00:00.000Z",
      "currency": "USD",
      "customer_name": "John Smith",
      "display_id": "BXDMJBWXID",
      "expected_ship_date": "2026-11-12T00:00:00.000Z",
      "id": "bo_bxdmjbwxid",
      "item_count": 1,
      "items": [
        {
          "currency": "USD",
          "id": "oi_bq425ju5vh",
          "price": 49.99,
          "product_id": "p_fccaefnahr",
          "product_name": "Golden Dog",
          "quantity": 2,
          "sku": "goldenretriever",
          "state": "NEW",
          "variant_id": "po_3745tjzrpc",
          "variant_name": ""
        }
      ],
      "notes": "Please include a handwritten thank-you note",
      "purchase_order_number": "12345",
      "retailer_id": "r_c9385ldj",
      "ship_after": "",
      "ship_to_address1": "41 King Street West",
      "ship_to_address2": "3rd Floor",
      "ship_to_city": "Kitchener",
      "ship_to_company": "Faire Wholesale, Inc",
      "ship_to_country": "CAN",
      "ship_to_name": "John Smith",
      "ship_to_phone": "555-123-4567",
      "ship_to_postal_code": "N2G 1A1",
      "ship_to_state": "ON",
      "shipments": [],
      "state": "NEW",
      "state_label": "New",
      "subtotal": 99.98,
      "total_payout": 80.0,
      "total_quantity": 2,
      "updated_at": "2026-11-05T09:00:00.000Z"
    }
  ],
  "page": 1
}
```

### List product types

List Faire's product types, which every product is filed under, with their IDs.

**Inputs**

- Name contains (`search`, text): Only types whose name has these words, such as candle.

**Outputs**

- `count` (number): How many are listed
- `product_types` (list): Faire's product types

**Example output**

```json
{
  "count": 1,
  "product_types": [
    {
      "id": "tt_23nl3bzl00",
      "name": "Votive Candle"
    }
  ]
}
```

### List products

List your Faire products with their variants, oldest change first. Gets one page; to see more, run it again with the next page.

**Inputs**

- SKU (`sku`, text): Only the product with a variant of this SKU.
- Changed after (`updated_after`, date and time): Only products that changed at or after this time.
- Include deleted (`include_deleted`, true/false): Turn on to list deleted products too.
- How many (`limit`, number): How many to list on this page, from 10 to 250. Defaults to 50. From 10 to 250.
- Page (`page`, number): Which page to list, starting at 1. Use the next number when the last answer said there may be more. At least 1.

**Outputs**

- `count` (number): How many are listed
- `has_more` (true/false): True when there may be another page
- `page` (number): The page these are
- `products` (list): The products found, oldest change first

**Example output**

```json
{
  "count": 1,
  "has_more": false,
  "page": 1,
  "products": [
    {
      "created_at": "2026-11-05T09:00:00.000Z",
      "description": "Glad you decided to read our description!",
      "id": "p_fccaefnahr",
      "image_urls": [
        "https://cdn.example.com/candle.jpg"
      ],
      "lifecycle_state": "PUBLISHED",
      "minimum_order_quantity": 8,
      "name": "Faire's fantastic candle",
      "product_type": "Votive Candle",
      "product_type_id": "tt_23nl3bzl00",
      "sale_state": "FOR_SALE",
      "short_description": "Our candles smell fantastic.",
      "unit_multiplier": 8,
      "updated_at": "2026-11-05T09:00:00.000Z",
      "variant_count": 1,
      "variants": [
        {
          "available_quantity": 24,
          "backordered_until": "",
          "created_at": "2026-11-05T09:00:00.000Z",
          "currency": "USD",
          "id": "po_3745tjzrpc",
          "lifecycle_state": "PUBLISHED",
          "name": "Vanilla",
          "options": {
            "Scent": "Vanilla"
          },
          "prices": [
            {
              "country": "USA",
              "country_group": "",
              "currency": "USD",
              "retail_price": 10.0,
              "wholesale_price": 5.0
            }
          ],
          "product_id": "p_fccaefnahr",
          "retail_price": 10.0,
          "sale_state": "FOR_SALE",
          "sku": "vanilla-candle",
          "tariff_code": "",
          "updated_at": "2026-11-05T09:00:00.000Z",
          "wholesale_price": 5.0
        }
      ]
    }
  ]
}
```

### List variants

List a product's variants with their SKUs, options, prices and stock.

**Inputs**

- Product (`product`, text, required): The product. Pick one, or give its ID (it starts with p_).

**Outputs**

- `count` (number): How many it has
- `product_id` (text): The product's ID
- `product_name` (text): The product's name
- `variants` (list): Its variants

**Example output**

```json
{
  "count": 1,
  "product_id": "p_fccaefnahr",
  "product_name": "Faire's fantastic candle",
  "variants": [
    {
      "available_quantity": 24,
      "backordered_until": "",
      "created_at": "2026-11-05T09:00:00.000Z",
      "currency": "USD",
      "id": "po_3745tjzrpc",
      "lifecycle_state": "PUBLISHED",
      "name": "Vanilla",
      "options": {
        "Scent": "Vanilla"
      },
      "prices": [
        {
          "country": "USA",
          "country_group": "",
          "currency": "USD",
          "retail_price": 10.0,
          "wholesale_price": 5.0
        }
      ],
      "product_id": "p_fccaefnahr",
      "retail_price": 10.0,
      "sale_state": "FOR_SALE",
      "sku": "vanilla-candle",
      "tariff_code": "",
      "updated_at": "2026-11-05T09:00:00.000Z",
      "wholesale_price": 5.0
    }
  ]
}
```

### Set stock

Set how many of a SKU you have on hand, such as after a stock count or a sale elsewhere. Faire works out what retailers can order.

**Inputs**

- SKU (`sku`, text, required): The SKU. Pick one, or type it.
- On hand (`on_hand_quantity`, number, required): How many you have. At least 0.

**Outputs**

- `available_quantity` (number): How many retailers can still order (on hand less committed); empty when untracked
- `committed_quantity` (number): How many are promised to orders
- `on_hand_quantity` (number): How many you have; empty when untracked
- `sku` (text): The SKU
- `tracked` (true/false): False when Faire doesn't count this SKU's stock

**Example output**

```json
{
  "available_quantity": 20,
  "committed_quantity": 4,
  "on_hand_quantity": 24,
  "sku": "vanilla-candle",
  "tracked": true
}
```

### Update product

Change a product's name, descriptions, type, state or how it's sold. Fields left blank keep what it has.

**Inputs**

- Product (`product`, text, required): The product. Pick one, or give its ID (it starts with p_).
- Name (`name`, text): A new name. Leave blank to keep it.
- Description (`description`, text): A new description. Leave blank to keep it.
- Short description (`short_description`, text): A new line about it, up to 255 characters. Leave blank to keep it.
- State (`state`, text): Publish it, hide it or make it a draft. Leave blank to keep it. One of: `DRAFT` (Draft: not shown to retailers), `PUBLISHED` (Published: retailers can order it), `UNPUBLISHED` (Unpublished: hidden from retailers).
- Product type (`product_type`, text): A new product type. Leave blank to keep it.
- Sold in packs of (`unit_multiplier`, number): How many units retailers buy at a time. Leave blank to keep it. At least 1.
- Minimum order (`minimum_order_quantity`, number): The fewest units a retailer can order. Leave blank to keep it. At least 0.

**Outputs**

- `created_at` (text): When it was added (ISO 8601)
- `description` (text): Its description
- `id` (text): The product's ID, such as p_fccaefnahr
- `image_urls` (list): Its images' addresses
- `lifecycle_state` (text): PUBLISHED, DRAFT, UNPUBLISHED or DELETED
- `minimum_order_quantity` (number): The fewest a retailer can order
- `name` (text): Its name
- `product_type` (text): Its product type, such as Votive Candle
- `product_type_id` (text): Its product type's ID, such as tt_23nl3bzl00
- `sale_state` (text): Whether it's for sale, such as FOR_SALE
- `short_description` (text): Its short description
- `unit_multiplier` (number): How many units it's sold in at a time
- `updated_at` (text): When it last changed (ISO 8601)
- `variant_count` (number): How many variants it has
- `variants` (list): Its variants

**Example output**

```json
{
  "created_at": "2026-11-05T09:00:00.000Z",
  "description": "Glad you decided to read our description!",
  "id": "p_fccaefnahr",
  "image_urls": [
    "https://cdn.example.com/candle.jpg"
  ],
  "lifecycle_state": "PUBLISHED",
  "minimum_order_quantity": 8,
  "name": "Faire's fantastic candle",
  "product_type": "Votive Candle",
  "product_type_id": "tt_23nl3bzl00",
  "sale_state": "FOR_SALE",
  "short_description": "Our candles smell fantastic.",
  "unit_multiplier": 8,
  "updated_at": "2026-11-05T09:00:00.000Z",
  "variant_count": 1,
  "variants": [
    {
      "available_quantity": 24,
      "backordered_until": "",
      "created_at": "2026-11-05T09:00:00.000Z",
      "currency": "USD",
      "id": "po_3745tjzrpc",
      "lifecycle_state": "PUBLISHED",
      "name": "Vanilla",
      "options": {
        "Scent": "Vanilla"
      },
      "prices": [
        {
          "country": "USA",
          "country_group": "",
          "currency": "USD",
          "retail_price": 10.0,
          "wholesale_price": 5.0
        }
      ],
      "product_id": "p_fccaefnahr",
      "retail_price": 10.0,
      "sale_state": "FOR_SALE",
      "sku": "vanilla-candle",
      "tariff_code": "",
      "updated_at": "2026-11-05T09:00:00.000Z",
      "wholesale_price": 5.0
    }
  ]
}
```

### Update variant

Change a variant's SKU, prices, state or the day it's back in stock. Prices in other currencies are kept. Fields left blank keep what it has.

**Inputs**

- Product (`product`, text, required): The product. Pick one, or give its ID (it starts with p_).
- Variant (`variant`, text, required): The variant to change. Pick one, or give its ID or SKU.
- SKU (`sku`, text): A new SKU. Leave blank to keep it.
- Wholesale price (`wholesale_price`, number): What retailers pay for one, such as 12.50. Leave blank to keep it. At least 0.
- Retail price (`retail_price`, number): The price you suggest retailers sell one at, such as 25. Leave blank to keep it. At least 0.
- Currency (`currency`, text): Which prices to change. Leave blank for the currency your brand sells in. One of: `USD` (US dollars (USD), for the United States), `CAD` (Canadian dollars (CAD), for Canada), `GBP` (Pounds (GBP), for the United Kingdom), `EUR` (Euros (EUR), for the European Union), `AUD` (Australian dollars (AUD), for Australia).
- State (`state`, text): Publish it, hide it or make it a draft. Leave blank to keep it. One of: `DRAFT` (Draft: not shown to retailers), `PUBLISHED` (Published: retailers can order it), `UNPUBLISHED` (Unpublished: hidden from retailers).
- Back in stock on (`backordered_until`, date): The day it will be back in stock, while it's out.
- Tariff code (`tariff_code`, text): Its customs tariff (HS) code, such as 3406.00.

**Outputs**

- `available_quantity` (number): How many Faire shows as available
- `backordered_until` (text): When it's back in stock (ISO 8601); empty if not
- `created_at` (text): When it was added (ISO 8601)
- `currency` (text): Those prices' currency
- `id` (text): The variant's ID, such as po_3745tjzrpc
- `lifecycle_state` (text): PUBLISHED, DRAFT, UNPUBLISHED or DELETED
- `name` (text): Its name, if it has one
- `options` (object): Its options by name, such as {"Scent": "Vanilla"}
- `prices` (list): Its prices for each country or group of countries
- `product_id` (text): Its product's ID
- `retail_price` (number): Its suggested retail price, from its first price
- `sale_state` (text): Whether it's for sale, such as FOR_SALE
- `sku` (text): Its SKU
- `tariff_code` (text): Its tariff (HS) code
- `updated_at` (text): When it last changed (ISO 8601)
- `wholesale_price` (number): Its wholesale price, from its first price

**Example output**

```json
{
  "available_quantity": 24,
  "backordered_until": "",
  "created_at": "2026-11-05T09:00:00.000Z",
  "currency": "USD",
  "id": "po_3745tjzrpc",
  "lifecycle_state": "PUBLISHED",
  "name": "Vanilla",
  "options": {
    "Scent": "Vanilla"
  },
  "prices": [
    {
      "country": "USA",
      "country_group": "",
      "currency": "USD",
      "retail_price": 10.0,
      "wholesale_price": 5.0
    }
  ],
  "product_id": "p_fccaefnahr",
  "retail_price": 10.0,
  "sale_state": "FOR_SALE",
  "sku": "vanilla-candle",
  "tariff_code": "",
  "updated_at": "2026-11-05T09:00:00.000Z",
  "wholesale_price": 5.0
}
```
