Introduction

Note: This API documentation is for V1 of Faire's API, which is not supported anymore. Please refer to the documentation for V2 instead.

To authenticate calls to the API, pass your Faire API access token as an HTTP request header named "X-FAIRE-ACCESS-TOKEN".

Note that for staging access, you need to set the host name to www.faire-stage.com.

Please always check the HTTP status code returned from any API request. This API will return a status code between 200 and 299 when a request is successful. In any event that the request was not completed, an error code between 400 and 599 will be returned.

What's new.

Products

Products are the goods that brands sell on Faire. A product can have multiple options, differentiated by attributes such as size, or color. It is important to note that the price is on the product instead of the option. As a result, all options for a given product must have the same price. If this is not the case, the options must be split out into multiple products.

A sample product might look like:

{
  "id": "p_123",
  "brand_id": "b_abc",
  "short_description": "Our candles smell fantastic. Want to know how good? Read our description!",
  "description": "Glad you decided to read our description! We have significantly more characters to describe to you just how good our candles smell.",
  "wholesale_price_cents": 500,
  "retail_price_cents": 1000,
  "sale_state" : "FOR_SALE",
  "active": true,
  "name": "Faire's fantastic candle",
  "unit_multiplier": 8,
  "minimum_order_quantity": 8,
  "deleted": false,
  "options": [
    {
      "id": "po_123",
      "product_id": "p_123",
      "active": true,
      "deleted": false,
      "name": "Vanilla Scent",
      "sku": "vanilla-2019",
      "available_quantity": 42,
      "backordered_until": "20190208T000915.000Z",
      "created_at": "20190314T000915.000Z",
      "updated_at": "20190315T000915.000Z",
      "images": [
        {
          "id": "i_adqaiy3htm",
          "width": 1000,
          "height": 1000,
          "sequence": 0,
          "url": "https://cdn.faire.com/374cd3041a4c4.png",
          "tags": [
            "Hero"
          ]
        }
      ],
      "idempotence_token": "rrc23negw",
      "variations": [
        {
          "name": "Scent",
          "value": "Vanilla"
        }
      ],
      "wholesale_price_cents": 299,
      "retail_price_cents": 599,
      "tariff_code": "340600"
    }
  ],
  "created_at": "20190314T000915.000Z",
  "updated_at": "20190315T000915.000Z",
  "images": [
    {
        "id": "i_7oey1vb9bm",
        "width": 1000,
        "height": 1000,
        "sequence": 0,
        "url": "https://cdn.faire.com/53105976.png",
        "tags": [
            "Hero"
        ]
    },
    {
        "id": "i_1i8ui542vi",
        "width": 1200,
        "height": 1200,
        "sequence": 1,
        "url": "https://cdn.faire.com/554156553.png",
        "tags": [
            "Product"
        ]
    }
  ],
  "idempotence_token": "4aytry2ust",
  "taxonomy_type": {
    "id": "tt_23nl3bzl00"
  }
}

Field	Description
id	A unique identifier of the product, beginning with "p_".
brand_id	A unique identifier of the brand that owns the product, beginning with "b_".
short_description	A short description of the product, at most 255 characters.
description	A description of the product, at most 65,535 characters.
wholesale_price_cents	The current wholesale price of a single unit in cents (US dollars).
retail_price_cents	The current recommended retailer price of a single unit in cents (US dollars).
active	Whether or not the product is currently active, and being shown to retailers. Inactive products can be thought of as drafts.
deleted	Whether or not the product has been deleted.
sale_state	`READ-ONLY` The current sellability of the product option on Faire. See Product State Management
name	The name of the product.
unit_multiplier	Also called case size or case quantity, this is the unit size that this product ships in. The product must be purchased in increments of this number.
minimum_order_quantity	The minimum number of units required to purchase this product. Must be a multiple of the `unit_multiplier`
options	A list of product options that belong to this product.
created_at	An ISO 8601 basic timestamp of when the product was created.
updated_at	An ISO 8601 basic timestamp of when the product was last updated.
idempotence_token	The identifier used when this product was created.
images	The list of images associated with the product.
categories	`DEPRECATED` The search categories associated with this product.
taxonomy_type	The taxonomy type of this product.
allow_sales_when_out_of_stock	Boolean that determines whether this product should automatically go out of stock when it has insufficient inventory.

Get All Products

This endpoint retrieves a list of products, ordered ascending by updated_at. By default, it only returns non-deleted products.

This endpoint returns JSON structured like:

{
  "page": 1,
  "limit": 50,
  "products": [
    {
      "id": "p_123",
      "brand_id": "b_abc",
      "short_description": "Our candles smell fantastic. Want to know how good? Read our description!",
      "description": "Glad you decided to read our description! We have significantly more characters to describe to you just how good our candles smell.",
      "wholesale_price_cents": 500,
      "retail_price_cents": 1000,
      "sale_state": "FOR_SALE",
      "active": true,
      "deleted": false,
      "name": "Faire's fantastic candle",
      "unit_multiplier": 8,
      "taxonomy_type": {
        "id": "tt_23nl3bzl00",
        "name": "Votive Candle"
      },
      "options": [],
      "created_at": "20190314T000915.000Z",
      "updated_at": "20190315T000915.000Z"
    }
  ]
}

HTTP Request

GET https://www.faire.com/api/v1/products

Query Parameters

Parameter	Default	Description
limit	50	The max number of products to return in a response. Must be between 50-250.
page	1	The page of products to return. The first result will be (page - 1) * limit.
updated_at_min	null	ISO 8601 basic timestamp. If specified, only return products that have been modified since.
sku	null	The SKU of the product options to search by, if supplied.
include_deleted	null	True to include deleted products in the response, false or unspecified to omit them.

Get A Product By ID

This endpoint returns JSON structured like:

{
    "id": "p_123",
    "brand_id": "b_abc",
    "short_description": "Our candles smell fantastic. Want to know how good? Read our description!",
    "description": "Glad you decided to read our description! We have significantly more characters to describe to you just how good our candles smell.",
    "wholesale_price_cents": 500,
    "retail_price_cents": 1000,
    "sale_state" : "FOR_SALE",
    "active": true,
    "deleted": false,
    "name": "Faire's fantastic candle",
    "unit_multiplier": 8,
    "options": [],
    "variation_map": {
        "entries": []
    },
    "created_at": "20190314T000915.000Z",
    "updated_at": "20190315T000915.000Z"
}

This endpoint retrieves a single product given an ID, regardless of state (active or deleted).

HTTP Request

GET https://www.faire.com/api/v1/products/<ID>

Path Parameters

Parameter	Description
ID	The ID of the product to retrieve.

Create A Product

This endpoint accepts a product with only the fields populated that are to be used in creation:

{
  "short_description": "Our candles smell fantastic. Want to know how good? Read our description!",
  "description": "Glad you decided to read our description! We have significantly more characters to describe to you just how good our candles smell.",
  "name": "Faire's fantastic candle",
  "unit_multiplier": 8,
  "idempotence_token": "4aytry2ust",
  "options": [
    {
      "name": "Vanilla Scent",
      "sku": "vanilla-2019",
      "images": [
        {
          "url": "https://cdn.faire.com/374cd3041a4c4.png"
        }
      ],
      "idempotence_token": "rrc23negw",
      "variations": [
        {
          "name": "Scent",
          "value": "Vanilla"
        }
      ],
      "wholesale_price_cents": 299,
      "retail_price_cents": 599
    }
  ],
  "images": [
    {
      "url": "https://cdn.faire.com/53105976.png"
    },
    {
      "url": "https://cdn.faire.com/554156553.png"
    }
  ],
  "taxonomy_type": {
    "id": "tt_23nl3bzl00"
  }
}

This creates a single, inactive product.

HTTP Request

POST https://www.faire.com/api/v1/products

Request Parameters

Parameter	Description
idempotence_token	The identifier to use for idempotence when creating this product. This must be specified and be unique per product when creating.
short_description	A short description of the product, at most 255 characters.
description	A description of the product, at most 65,535 characters.
name	The name of the product.
unit_multiplier	Also called case size or case quantity, this is the unit size that this product ships in. The product must be purchased in increments of this number.options
images	The list of images associated with the product.
categories	`DEPRECATED` The search categories associated with this product.
taxonomy_type	The taxonomy type of this product.
allow_sales_when_out_of_stock	Boolean that determines whether this product should automatically go out of stock when it has insufficient inventory.

Create A Batch of Products

This endpoint accepts a list of products with only the fields populated that are to be used in creation:

{
  "products": [
    {
      "short_description": "Our candles smell fantastic. Want to know how good? Read our description!",
      "description": "Glad you decided to read our description! We have significantly more characters to describe to you just how good our candles smell.",
      "name": "Faire's fantastic candle",
      "unit_multiplier": 8,
      "idempotence_token": "4aytry2ust",
      "options": [
        {
          "name": "Vanilla Scent",
          "sku": "vanilla-2019",
          "images": [
            {
              "url": "https://cdn.faire.com/374cd3041a4c4.png"
            }
          ],
          "idempotence_token": "rrc23negw",
          "variations": [
            {
              "name": "Scent",
              "value": "Vanilla"
            }
          ],
          "wholesale_price_cents": 299,
          "retail_price_cents": 599
        }
      ],
      "images": [
        {
          "url": "https://cdn.faire.com/53105976.png"
        },
        {
          "url": "https://cdn.faire.com/554156553.png"
        }
      ],
      "taxonomy_type": {
        "id": "tt_23nl3bzl00"
      }
    },
    {
      "short_description": "Our candles smell fantastic. Want to know how good? Read our description!",
      "description": "Glad you decided to read our description! We have significantly more characters to describe to you just how good our candles smell.",
      "name": "Faire's other fantastic candle",
      "unit_multiplier": 8,
      "idempotence_token": "4aytry5f4fg",
      "options": [
        {
          "name": "Chocolate Scent",
          "sku": "chocolate-2020",
          "images": [
            {
              "url": "https://cdn.faire.com/374cd3041a5e3.png"
            }
          ],
          "idempotence_token": "rrc23wegd",
          "variations": [
            {
              "name": "Scent",
              "value": "Chocolate"
            }
          ],
          "wholesale_price_cents": 299,
          "retail_price_cents": 599
        }
      ],
      "images": [
        {
          "url": "https://cdn.faire.com/53105454.png"
        },
        {
          "url": "https://cdn.faire.com/554156345.png"
        }
      ],
      "taxonomy_type": {
        "id": "tt_23nl3bzl00"
      }
    }
  ]
}

This creates a list of inactive products.

HTTP Request

POST https://www.faire.com/api/v1/products/batch

Request Parameters

Parameter	Description
products	The list of products to create. Each must be a valid product with required fields and idempotence tokens.

Update A Product

This endpoint accepts a product with only the fields populated that are to be modified:

{
  "short_description": "Our candles smell fantastic. Want to know how good? Read our description!",
  "description": "Glad you decided to read our description! We have significantly more characters to describe to you just how good our candles smell.",
  "name": "Faire's fantastic candle",
  "active": true,
  "unit_multiplier": 8,
  "images": [
    {
      "url": "https://cdn.faire.com/53105976.png"
    },
    {
      "url": "https://cdn.faire.com/554156553.png"
    }
  ],
  "taxonomy_type": {
    "id": "tt_23nl3bzl00"
  }
}

This updates a single product.
NOTE: This endpoint cannot be used for updating options. Options must be updated via the update option method.

HTTP Request

PATCH https://www.faire.com/api/v1/products/<ID>

Path Parameters

Parameter	Description
ID	The ID of the product to modify.

Request Parameters

Parameter	Description
short_description	A short description of the product, at most 255 characters.
description	A description of the product, at most 65,535 characters.
name	The name of the product.
active	Whether or not the product is currently active, and being shown to retailers.
unit_multiplier	Also called case size or case quantity, this is the unit size that this product ships in. The product must be purchased in increments of this number.options
images	The list of images associated with the product.
categories	`DEPRECATED` The search categories associated with this product.
taxonomy_type	The taxonomy type of this product.
variation_map	A structure for ordering the display of the product options by their variations. See Arranging Product Options
allow_sales_when_out_of_stock	Boolean that determines whether this product should automatically go out of stock when it has insufficient inventory.

Arranging Product Options

HTTP Request

This is part of the Update A Product request.

PATCH https://www.faire.com/api/v1/products/<ID>

Details

A variation_map is an ordered map of key/value pairs where the key is the variation name and the values are a list of variation values. Since JSON has no ordered maps, the map is represented as an Array.

The variation_map is automatically generated on product creation.
Product option variations are validated against the available variations in the variation_map.
You can add new values and remove unused values. A value is unused if no options have a variation with that value.
You can order values and entries to control the order in which they are displayed:
- The order of the entries will determine the order of the variation selection dropdowns that retailers see on the product page, top-down. (With some exceptions for colour and size.)
- The order of the values will determine the order of the variation values in the selection dropdowns, top-down or left-to-right.
At this time, you cannot add or remove variation_map entries.

Example:

{
    "token": "p_test",
    "name": "Fun Ball",
    "variation_map": {
        "entries": [
            {
                "name": "Size",
                "values": [
                    "1\"",
                    "2\"",
                    "3\""
                ]
            },
            {
                "name": "Texture",
                "values": [
                    "Smooth",
                    "Criss-cross",
                    "Hexagons"
                ]
            }
        ]
    }
}

fun ball on product page

Note how the ordering of the textures in this list determines the order of items in the dropdown and how the order of the sizes controls the order of the selection boxes.

`DEPRECATED` Get All Product Categories

This endpoint returns JSON structured like:

{
  "categories": [
    {
      "name": "Accessories",
      "sub_categories": [
        {
          "name": "Bags & Purses",
          "sub_categories": []
        },
        {
          "name": "Other",
          "sub_categories": []
        }
      ]
    },
    {
      "name": "Home Decor",
      "sub_categories": [
        {
          "name": "Pillows & Blankets",
          "sub_categories": []
        },
        {
          "name": "Candles",
          "sub_categories": []
        }
      ]
    }
  ]
}

This endpoint retrieves the product category tree.

HTTP Request

GET https://www.faire.com/api/v1/products/categories

Get All Taxonomy Types

GET https://www.faire.com/api/v1/products/types

This endpoint returns JSON structured like:

{
  "taxonomy_types": [
    {
      "id": "tt_6hk4mf1xig",
      "name": "Tea Bags"
    },
    {
      "id": "tt_b0oaeo6ixo",
      "name": "Tea Cup"
    },
    {
      "id": "tt_beh3u2i3o0",
      "name": "Tea Light Candles"
    }
  ]
}

This endpoint retrieves all taxonomy types. Taxonomy types are often referred to as "product types" in our user-facing terminology. The two terms can be used interchangeably.

After 1 June 2020, each product must be tagged with a taxonomy type.

Faire will use taxonomy type information to determine the categories in which brands and products are surfaced.

You only need to provide the ID when creating or updating a product. When you retrieve a product, both the ID and name will be returned.

Product Options

Product options are a unique variant of a product. All options belong to a single product, with a product having at least one option. Options can be differentiated by SKU, have their own inventory levels, and be backordered or deactivated independently of other options.

A sample product option might look like:

{
  "id": "po_123",
  "product_id": "p_abc",
  "sale_state" : "FOR_SALE",
  "active": true,
  "deleted": false,
  "name": "Vanilla Scent",
  "sku": "vanilla-2019",
  "retail_price_cents": 1099,
  "wholesale_price_cents": 600,
  "available_quantity": 42,
  "backordered_until": "20190208T000915.000Z",
  "created_at": "20190314T000915.000Z",
  "updated_at": "20190315T000915.000Z",
  "variations": [
    {
      "name": "Scent",
      "value": "Vanilla"
    }
  ],
  "images": [
    {
      "id": "i_adqaiy3htm",
      "width": 1000,
      "height": 1000,
      "sequence": 0,
      "url": "https://cdn.faire.com/374cd3041a4c4.png",
      "tags": [
        "Hero"
      ]
    }
  ]
}

A product's options can be different choices along one dimension, such as size options that are small, medium, or large. More complex products may have choices spanning two or more dimensions. The arrangement of the dimensions and choices can be configured with the variation map.

Field	Description
id	A unique identifier of the product option, beginning with "po_".
product_id	A unique identifier of the product the option belongs to, beginning with "p_".
active	Whether or not the product option is currently active and being shown to retailers. Inactive product options can be thought of as drafts.
deleted	Whether or not the product option has been deleted.
sale_state	`READ-ONLY` The current sellability of the product option on Faire. See Product State Management
name	The name of the product option.
sku	An identifier that should be unique amongst product options. It is up to the client to keep SKUs unique. SKUs are case-sensitive.
retail_price_cents	The current recommended retailer price of a single unit of this option in cents (US dollars).
wholesale_price_cents	The current wholesale price of a single unit of this option in cents (US dollars).
available_quantity	If set, the number of units available for sale. If not set in the response, the brand has not set their inventory levels in Faire.
backordered_until	If set, Faire will not allow the product option to be `FOR_SALE` until this date.
created_at	An ISO 8601 basic timestamp of when the product option was created.
updated_at	An ISO 8601 basic timestamp of when the product option was last updated.
variations	A set of variations (attributes) that define this product option. e.g. If the option is a large red shirt, the variations might include Color:Red and Size:Large. The variations must be valid values from the product's `variation_map`.

Create a Product Option

This endpoint accepts a product option with only the fields populated that are to be used for creation:

{
  "name": "Vanilla Scent",
  "sku": "vanilla-2019",
  "active": true,
  "variations": [
    {
      "name": "Scent",
      "value": "Vanilla"
    }
  ],
  "images": [
    {
      "url": "https://cdn.faire.com/374cd3041a4c4.png"
    }
  ],
  "retail_price_cents": 1099,
  "wholesale_price_cents": 600,
  "idempotence_token": "c5nh9vd5ee"
}

This endpoint returns the created product option.

{
  "id": "po_123",
  "product_id": "p_abc",
  "active": true,
  "deleted": false,
  "name": "Vanilla Scent",
  "sku": "vanilla-2019",
  "backordered_until": "20190208T000915.000Z",
  "created_at": "20190314T000915.000Z",
  "updated_at": "20190315T000915.000Z",
  "variations": [
    {
      "name": "Scent",
      "value": "Vanilla"
    }
  ],
  "images": [
    {
      "id": "i_adqaiy3htm",
      "width": 1000,
      "height": 1000,
      "sequence": 0,
      "url": "https://cdn.faire.com/374cd3041a4c4.png",
      "tags": [
        "Hero"
      ]
    }
  ],
  "retail_price_cents": 1099,
  "wholesale_price_cents": 600,
  "idempotence_token": "c5nh9vd5ee"
}

HTTP Request

POST https://www.faire.com/api/v1/products/<ID>/options

This endpoint is used to add a new product option to an existing product.

Path Parameters

Parameter	Description
ID	The ID of the product to add the option to

Request Fields

Name	Description
name	The name of the product option.
active	Whether or not the product option is currently active, and being shown to retailers. Inactive products can be thought of as drafts.
sku	An identifier that should be unique amongst product options. It is up to the client to keep SKUs unique. SKUs are case-sensitive.
retail_price_cents	The current recommended retailer price of a single unit of this option in cents (US dollars).
wholesale_price_cents	The current wholesale price of a single unit of this option in cents (US dollars).
backordered_until	An ISO 8601 basic timestamp that specifies when the product option will be back in stock.
available_quantity	Must be a whole number. If the number is less than the unit_multiplier of the product, the option will be deactivated. If there are no active options for the product, the product will also be deactivated.
idempotence_token	The identifier to use for idempotence when creating this product option. This must be specified and be unique per product option when creating.
variations	A set of variations (attributes) that define this product option. e.g. If the option is a large red shirt, the variations might include Color:Red and Size:Large. The variations must be valid values from the product's `variation_map`.

Update a Product Option

This endpoint accepts a product option with only the fields populated that are to be modified:

{
  "name": "Vanilla Scent",
  "sku": "vanilla-2019",
  "active": true,
  "available_quantity": 42,
  "backordered_until": "20190208T000915.000Z",
  "variations": [
    {
      "name": "Scent",
      "value": "Vanilla"
    }
  ],
  "retail_price_cents": 1099,
  "wholesale_price_cents": 600
}

This endpoint returns an updated product option.

{
  "id": "po_123",
  "product_id": "p_abc",
  "active": true,
  "deleted": false,
  "name": "Vanilla Scent",
  "sku": "vanilla-2019",
  "available_quantity": 42,
  "backordered_until": "20190208T000915.000Z",
  "created_at": "20190314T000915.000Z",
  "updated_at": "20190315T000915.000Z",
  "variations": [
    {
      "name": "Scent",
      "value": "Vanilla"
    }
  ],
  "retail_price_cents": 1099,
  "wholesale_price_cents": 600
}

HTTP Request

PATCH https://www.faire.com/api/v1/products/options/<ID>

This endpoint is used to modify the available quantity of a product option.

Path Parameters

Parameter	Description
ID	The ID of the product option to update

Updatable Fields

Name	Description
name	The name of the product option.
active	Whether or not the product option is currently active, and being shown to retailers. Inactive products can be thought of as drafts.
sku	An identifier that should be unique amongst product options. It is up to the client to keep SKUs unique. SKUs are case-sensitive.
retail_price_cents	The current recommended retailer price of a single unit of this option in cents (US dollars).
wholesale_price_cents	The current wholesale price of a single unit of this option in cents (US dollars).
backordered_until	An ISO 8601 basic timestamp that specifies when the product option will be back in stock.
available_quantity	Must be a whole number. If the number is less than the unit_multiplier of the product, the option will be deactivated. If there are no active options for the product, the product will also be deactivated.
variations	A set of variations (attributes) that define this product option. e.g. If the option is a large red shirt, the variations might include Color:Red and Size:Large. The variations must be valid values from the product's `variation_map`.

Update Inventory Levels

This endpoint is used to update the inventory levels for multiple product options in one request.

A product option can be referenced by its ID or SKU value. Update by SKU may be more convenient in many situations, but since some systems may have duplicate SKUs in their catalog, we support using the unique ID of the product option. All requests should specify either product_option_id or sku. There cannot be duplicates and there cannot be a mix.

This endpoint accepts requests like:

{
  "inventories": [
    {
      "sku": "vanilla-candle",
      "current_quantity": 24,
      "discontinued": false,
      "backordered_until": null
    },
    {
      "sku": "cinnamon-candle",
      "current_quantity": 0,
      "discontinued": false,
      "backordered_until": "20190314T000915.000Z"
    },
    {
      "sku": "fall-candle",
      "current_quantity": 0,
      "discontinued": true,
      "backordered_until": null
    },
    {
      "sku": "fall-candle",
      "current_quantity": null,
      "discontinued": false,
      "backordered_until": null
    }
  ]
}

{
  "inventories": [
    {
      "product_option_id": "po_456",
      "current_quantity": 24,
      "discontinued": false,
      "backordered_until": null
    },
    {
      "product_option_id": "po_789",
      "current_quantity": 0,
      "discontinued": false,
      "backordered_until": "20190314T000915.000Z"
    },
    {
      "product_option_id": "po_012",
      "current_quantity": 0,
      "discontinued": true,
      "backordered_until": null
    },
    {
      "product_option_id": "po_123",
      "current_quantity": null,
      "discontinued": false,
      "backordered_until": null
    }
  ]
}

This endpoint returns a list of product options in response:

{
  "options": [
    {
      "id": "po_012",
      "product_id": "p_ghi",
      "active": false,
      "deleted": false,
      "name": "Fall Scent",
      "sku": "fall-candle",
      "available_quantity": 0,
      "created_at": "20190313T000915.000Z",
      "updated_at": "20190315T000915.000Z",
      "variations": [
        {
          "name": "Scent",
          "value": "Fall"
        }
      ],
      "retail_price_cents": 599,
      "wholesale_price_cents": 300
    },
    {
      "id": "po_789",
      "product_id": "p_def",
      "active": false,
      "deleted": false,
      "name": "Cinnamon Scent",
      "sku": "cinnamon-candle",
      "available_quantity": 0,
      "created_at": "20190312T000915.000Z",
      "updated_at": "20190315T000915.000Z",
      "backordered_until": "20190314T000915.000Z",
      "variations": [
        {
          "name": "Scent",
          "value": "Cinnamon"
        }
      ],
      "retail_price_cents": 599,
      "wholesale_price_cents": 300
    },
    {
      "id": "po_456",
      "product_id": "p_abc",
      "active": true,
      "deleted": false,
      "name": "Vanilla Scent",
      "sku": "vanilla-candle",
      "available_quantity": 24,
      "created_at": "20190314T000915.000Z",
      "updated_at": "20190315T000915.000Z",
      "variations": [
        {
          "name": "Scent",
          "value": "Vanilla"
        }
      ],
      "retail_price_cents": 599,
      "wholesale_price_cents": 300
    }
  ]
}

HTTP Request

PATCH https://www.faire.com/api/v1/products/options/inventory-levels

This endpoint allows updating inventory levels of multiple options at once.

Request Parameters

Name	Description
inventories.sku	Matches the most recently created product option with that SKU.
inventories.product_option_id	The ID of the product option to update. This is a unique identifier starting with "po_".
inventories.current_quantity	The quantity to set `available_quantity` to, must be `null` or a whole number. If the value is `null`, this will remove inventory tracking and disable inventory tracking features. If the number of available units is less than the `unit_multiplier` or `minimum_order_quantity` of the product, the option will be deactivated. If there are no active options for the product, the product will also be deactivated (see: Product State Management).
inventories.discontinued	Boolean indicating if the option has been discontinued, and Faire should no longer activate this option based on inventory levels.
inventories.backordered_until	ISO 8601 datetime that indicates when the option will be back in stock.

Product State Management

Sale State

We have a read-only field on Products and Options called sale_state. It represents the current visibility/sellability of a product on Faire. When a product tracks inventory, or is backordered, it can change the sale_state of the product.

sale_state can be one of 4 values:

FOR_SALE
SALES_PAUSED
NOT_FOR_SALE
DELETED

Summary of what the different states represent in various contexts:

Does the maker want to sell the Product/Option on Faire?	`sale_state`	Visible to Makers	Visible to Retailers	Purchasable
Yes	`FOR_SALE`	Yes	Yes	Yes
Yes	`SALES_PAUSED`	Yes	Yes	No
No	`NOT_FOR_SALE`	Yes	No	No
N/A	`DELETED`	No	No	No

Faire systems automatically move products and options between FOR_SALE and SALES_PAUSED, while makers can only select between FOR_SALE or NOT_FOR_SALE.

DELETED is a special state reserved to DELETED products/options.

Detailed Technical Explanation

For the purposes of explanation, we will assume DELETED products and product options do not exist. They are only visible via certain API endpoints to help track when products/options are deleted.

A product can have a sale_state of NOT_FOR_SALE, while it’s options have a sale_state of FOR_SALE. The product sale_state is effectively a filter, meaning the options do not appear to retailers, similarly to if they were NOT_FOR_SALE.

Faire UI

Via Faire’s UI makers can select whether an item is FOR_SALE or NOT_FOR_SALE.

Faire Automated Systems

Product Options

Faire will automatically determine whether a FOR_SALE Option should instead be SALES_PAUSED while one of the following conditions are met:

The option has a backordered_until
- (we are aware this is not the typical usage of the term “Backorder”)
The product has allow_sales_when_out_of_stock = false and the option’s available_quantity is less than either:
- the product’s minimum_order_quantity
- the product’s unit_multiplier

The Option is reverted to FOR_SALE if an update causes all the conditions to no longer be met.

Products

Faire will automatically determine whether a FOR_SALE Product should instead be SALES_PAUSED if:
- All the options under the product are either SALES_PAUSED or NOT_FOR_SALE
If any option is FOR_SALE, the product will remain FOR_SALE.
Faire will automatically set a FOR_SALE Product to NOT_FOR_SALE if at any point all the options are NOT_FOR_SALE.
- This is not an automatically reversible change.
Faire will never set a NOT_FOR_SALE product or option to FOR_SALE.

Note: Pre-orders

Faire's implementation of pre-orders is not currently supported via our API.

You should note however, that pre-orders will move a product to NOT_FOR_SALE on:

the "Order by Date"
the "Expected Ship Date"

Faire Public API

Affected Product/Option endpoints:

Create A Batch of Products
Update A Product
Create A Product Option
Update A Product Option

Affected Inventory endpoints:

Update Inventory Levels

On Input to Faire’s Public API:

When a Product/Option API request sets a product to active = true, we interpret that as a request for the product to be FOR_SALE
- Faire will automatically toggle between FOR_SALE and SALES_PAUSED
When a Product/Option API request sets a product to active = false, OR an inventory update request sets discontinued=true, we interpret that as a request for the product to be NOT_FOR_SALE
- Faire will never automatically change the sale_state from NOT_FOR_SALE.

On Output from Faire’s Public API, the active and deleted fields are computed from the sale_state. For backwards compatibility, here is what they are computed to be, based on the sale_state:

`sale_state`	active	deleted
`FOR_SALE`	true	false
`SALES_PAUSED`	false	false
`NOT_FOR_SALE`	false	false
`DELETED`	false	true

WARNING

If you read a SALES_PAUSED product, it will be active = false, but sending that back to Faire will put the product into a NOT_FOR_SALE sale_state.

This is inconsistent, and future versions of the API will not permit active, and will instead require sale_state.

Orders

Orders are placed from a retailer to a brand on Faire. Faire supports scheduling orders, where a retailer can place an order and request a ship date up to 6 months in the future. Orders should not be shipped before the scheduled ship date.

A sample order might look like:

{
  "id": "bo_bxdmjbwxid",
  "display_id": "BXDMJBWXID",
  "created_at": "20190315T000915.000Z",
  "updated_at": "20190315T001000.000Z",
  "state": "PRE_TRANSIT",
  "items": [
    {
      "id": "oi_bq425ju5vh",
      "created_at": "20190315T000915.000Z",
      "updated_at": "20190315T000915.000Z",
      "order_id": "bo_bxdmjbwxid",
      "product_id": "p_fccaefnahr",
      "product_option_id": "po_3745tjzrpc",
      "quantity": 1,
      "sku": "goldenretriever",
      "price_cents": 10500,
      "product_name": "Golden Dog",
      "product_option_name": "retriever",
      "includes_tester": false
    }
  ],
  "shipments": [
    {
      "id": "s_bq425ju5vh",
      "order_id": "bo_bxdmjbwxid",
      "maker_cost_cents": 2300,
      "carrier": "fedex",
      "tracking_code": "94029300101029282",
      "created_at": "20190315T000915.000Z",
      "updated_at": "20190315T000915.000Z"
    }
  ],
  "address": {
      "name": "John Smith",
      "address1": "41 King Street West",
      "address2": "3rd Floor",
      "postal_code": "N2G 1A1",
      "city": "Kitchener",
      "state": "Ontario",
      "state_code": "ON",
      "phone_number": "555-123-4567",
      "country": "Canada",
      "country_code": "CAN",
      "company_name": "Faire Wholesale, Inc"
  },
  "retailer_id": "r_c9385ldj",
  "ship_after": "20190315T000915.000Z",
  "payout_costs": {
      "payout_fee_cents": 0,
      "payout_fee_bps": 0,
      "commission_cents": 2625,
      "commission_bps": 2500
  },
  "source": "MARKETPLACE",
  "payment_initiated_at": "20190316T001034.000Z",
  "original_order_id": "bo_bg5ude6pmd"
}

Field	Description
id	A unique identifier of the order, beginning with "bo_". NOTE: When shown on the Faire website, the "bo_" will be stripped and the order ID will be upper-case. e.g. "bo_bxdmjbwxid" appears as "#BXDMJBWXID" (See display_id).
display_id	The order identifier as displayed on the Faire website, emails, etc.
state	The current state of the order
ship_after	An ISO 8601 basic timestamp of the earliest the order should ship
items	A list of order items associated with the order
shipments	A list of shipments associated with the order
address	The address the order should be shipped to
retailer_id	A unique identifier that represents the retailer who placed the order. See retailers for more information.l
payout_costs	The payout costs associated with the order. NOTE: this may change until the order has been paid out (payment_initiated_at is set), for example if items are removed from the order.
source	How this order was initiated (may be MARKETPLACE, FAIRE_DIRECT, TRADESHOW, etc).
payment_initiated_at	An ISO 8601 basic timestamp of when the brand was paid for this order. Null/absent if the order has not been paid yet.
original_order_id	If this order has a parent, for example due to a backorder, this contains the ID of the original order. Null/absent otherwise.
created_at	An ISO 8601 basic timestamp of when the order was created
updated_at	An ISO 8601 basic timestamp of when the order was last updated

Order States

State	Description
NEW	The order has not yet been accepted by the brand.
PROCESSING	The brand has accepted the order, and is in the process of fulfilling it.
PRE_TRANSIT	The order has at least one shipment, but no shipments are in transit.
IN_TRANSIT	At least one of the shipments is in transit.
DELIVERED	At least one of the shipments has been delivered.
BACKORDERED	The brand did not have sufficient quantity to fulfill the order and will ship it when items are back in stock.
CANCELED	The order was canceled by the brand or the retailer. Can only happen if the order is NEW or PROCESSING.

Get all Orders

This endpoint retrieves a list of orders, ordered ascending by updated_at.

A sample response might look like:

{
  "page": 1,
  "limit": 10,
  "orders": [
    {
        "id": "bo_bxdmjbwxid",
        "created_at": "20190315T000915.000Z",
        "updated_at": "20190315T001000.000Z",
        "state": "NEW",
        "items": [
          {
            "id": "oi_bq425ju5vh",
            "created_at": "20190315T000915.000Z",
            "updated_at": "20190315T000915.000Z",
            "order_id": "bo_bxdmjbwxid",
            "product_id": "p_fccaefnahr",
            "product_option_id": "po_3745tjzrpc",
            "quantity": 1,
            "sku": "goldenretriever",
            "price_cents": 10000,
            "product_name": "Golden Dog",
            "product_option_name": "retriever",
            "includes_tester": false
          }
        ],
        "address": {
            "name": "John Smith",
            "address1": "41 King Street West",
            "address2": "3rd Floor",
            "postal_code": "N2G 1A1",
            "city": "Kitchener",
            "state": "Ontario",
            "state_code": "ON",
            "phone_number": "555-123-4567",
            "country": "Canada",
            "country_code": "CAN",
            "company_name": "Faire Wholesale, Inc"
        },
        "retailer_id": "r_c9385ldj",
        "payout_costs": {
            "payout_fee_cents": 0,
            "payout_fee_bps": 0,
            "commission_cents": 2625,
            "commission_bps": 2500
        },
        "source": "MARKETPLACE"
      }
  ]
}

HTTP Request

GET https://www.faire.com/api/v1/orders

Query Parameters

Parameter	Default	Description
limit	50	The max number of orders to return in a response. Must be between 10-50.
page	1	The page of products to return. The first result will be (page - 1) * limit.
updated_at_min	null	ISO 8601 basic timestamp, if specified only show orders that have been modified since.
created_at_min	null	ISO 8601 basic timestamp, if specified only show orders that were created since.
excluded_states	null	A comma separated list of states to exclude from the response (e.g. "DELIVERED,BACKORDERED,CANCELED").
ship_after_max	null	ISO 8601 basic timestamp, if specified only show orders that are due to be shipped at or before this time.

Get a single order by ID

This endpoint retrieves a single order given an order ID.

A sample response might look like:

{
  "id": "bo_bxdmjbwxid",
  "created_at": "20190315T000915.000Z",
  "updated_at": "20190315T001000.000Z",
  "state": "NEW",
  "items": [
    {
      "id": "oi_bq425ju5vh",
      "created_at": "20190315T000915.000Z",
      "updated_at": "20190315T000915.000Z",
      "order_id": "bo_bxdmjbwxid",
      "product_id": "p_fccaefnahr",
      "product_option_id": "po_3745tjzrpc",
      "quantity": 1,
      "sku": "goldenretriever",
      "price_cents": 10000,
      "product_name": "Golden Dog",
      "product_option_name": "retriever",
      "includes_tester": false
    }
  ],
  "address": {
      "name": "John Smith",
      "address1": "41 King Street West",
      "address2": "3rd Floor",
      "postal_code": "N2G 1A1",
      "city": "Kitchener",
      "state": "Ontario",
      "state_code": "ON",
      "phone_number": "555-123-4567",
      "country": "Canada",
      "country_code": "CAN",
      "company_name": "Faire Wholesale, Inc"
  },
  "retailer_id": "r_c9385ldj",
  "payout_costs": {
      "payout_fee_cents": 0,
      "payout_fee_bps": 0,
      "commission_cents": 2625,
      "commission_bps": 2500
  },
  "source": "MARKETPLACE"
}

HTTP Request

GET https://www.faire.com/api/v1/orders/<ID>

Path Parameters

Parameter	Description
ID	The ID of the order to fetch.

Accept an Order

This endpoint accepts an order and moves it to PROCESSING.

A sample request might look like:

{
  "expected_ship_date": "20190715T000915.000Z"
}

HTTP Request

PUT https://www.faire.com/api/v1/orders/<ID>/processing

Path Parameters

Parameter	Description
ID	The ID of the order to accept

Request Body Fields

Field	Description
expected_ship_date	Optional. If specified, an ISO 8601 basic timestamp of when the order is expected to be shipped.

Add Shipments to an Order

This endpoint adds shipments to an order and moves the state to PRE_TRANSIT. When one of the shipments is accepted by the carrier, the state will move to IN_TRANSIT.

A sample request might look like:

{
  "shipments": [
    {
      "order_id": "bo_bxdmjbwxid",
      "maker_cost_cents": 2300,
      "carrier": "fedex",
      "tracking_code": "94029300101029282"
    }
  ]
}

HTTP Request

POST https://www.faire.com/api/v1/orders/<ID>/shipments

Path Parameters

Parameter	Description
ID	The ID of the order to add shipments to

Request Body Fields

Field	Description
shipments	A list of shipments to add to the order.

Order Items

A sample order item might look like:

{
  "id": "oi_bq425ju5vh",
  "created_at": "20190315T000915.000Z",
  "updated_at": "20190315T000915.000Z",
  "order_id": "bo_bxdmjbwxid",
  "product_id": "p_fccaefnahr",
  "product_option_id": "po_3745tjzrpc",
  "quantity": 1,
  "sku": "goldenretriever",
  "price_cents": 10000,
  "product_name": "Golden Dog",
  "product_option_name": "retriever",
  "includes_tester": false
}

Field	Description
id	A unique identifier of the order item, beginning with "oi_".
order_id	The ID of the order the item belongs to.
product_id	The ID of the product the retailer bought.
product_option_id	The ID of the product option the retailer bought.
quantity	The number of physical items the retailer purchased.
sku	The SKU of the option when the order was created. This may not match the current SKU of the option.
price_cents	The wholesale price of the product at the time it was purchased, in USD cents.
product_name	The name of the product when it was purchased.
product_option_name	The name of the product option when it was purchased.
includes_tester	A boolean indicating whether or not a tester for the product option was purchased.
tester_price_cents	If includes_tester is true, the price of the tester in USD cents.
created_at	An ISO 8601 basic timestamp of when the order was created.
updated_at	An ISO 8601 basic timestamp of when the order was last updated.

Backordering Items

When backordering items, a new order will be created with the backordered items to be confirmed by the retailer. This is not intended for updating item inventory, only for backordering or discontinuing items that are not available for a specific order.

A sample request might look like:

{
  "availabilities": {
    "oi_abc": {
      "available_quantity": 0,
      "discontinued": true
    },
    "oi_def": {
      "available_quantity": 4,
      "discontinued": false,
      "backordered_until": "20190315T001000.000Z"
    }
  }
}

HTTP Request

POST https://www.faire.com/api/v1/orders/<ID>/items/availability

Path Parameters

Parameter	Description
ID	The ID of the order for which to backorder items.

Request Body Fields

The request body is a map of order item availabilities, keyed by the order item ID.
NOTE: This is the ID of the order item (starting with "oi_") and can be retrieved from the order object. It is not the ID of the ordered product option.

Field	Description
available_quantity	The current available quantity for the item. The valid range is [0, orderedQuantity).
discontinued	If true, the item was discontinued and cannot be ordered again in the future.
backordered_until	An ISO 8601 basic timestamp of when the item will be back in stock.

NOTE: Each availability body must have either discontinued set to true or backordered_until set to a valid date.

Shipments

Shipments are added to an order by a brand when fulfilling an order.

A sample shipment might look like:

{
  "id": "s_bq425ju5vh",
  "order_id": "bo_bxdmjbwxid",
  "maker_cost_cents": 2300,
  "carrier": "fedex",
  "tracking_code": "94029300101029282",
  "created_at": "20190315T000915.000Z",
  "updated_at": "20190315T000915.000Z"
}

Field	Description
id	A unique identifier of the shipments, beginning with "s_".
order_id	The ID of the order the shipment is attached to.
maker_cost_cents	The cost the brand paid to ship the order, in USD cents.
carrier	The carrier the brand used to ship the order. Accepted values are `CANADA_POST`, `DHL_ECOMMERCE`, `DHL_EXPRESS`, `FEDEX`, `PUROLATOR`, `UPS`, `USPS`, `POSTNL`, `CANPAR`.
tracking_code	The tracking code for the shipment, format varies based on the carrier.
created_at	An ISO 8601 basic timestamp of when the order was created.
updated_at	An ISO 8601 basic timestamp of when the order was last updated.

Brands

Get Brand Profile

This endpoint retrieves information about the brand associated with the current session.

A sample response might look like:

{
  "brand_id": "b_60ae65c4",
  "name": "Jeff's Warm Toques"
}

HTTP Request

GET https://www.faire.com/api/v1/brands/profile

Retailers

Get Retailer Public Profile

This endpoint retrieves information about a retailer given their ID.

A sample response might look like:

{
  "retailer_id": "r_c9385ldj",
  "name": "Tom's Toque Emporium"
}

HTTP Request

GET https://www.faire.com/api/v1/retailers/public/<retailer_id>

Path Parameters

Parameter	Description
retailer_id	The ID of the retailer to get information for.

Addresses

Contains information about the location of a person or business. Typically used to describe where to ship an order.

A sample address might look like:

{
        "name": "John Smith",
        "address1": "41 King Street West",
        "address2": "3rd Floor",
        "postal_code": "N2G 1A1",
        "city": "Kitchener",
        "state": "Ontario",
        "state_code": "ON",
        "phone_number": "555-123-4567",
        "country": "Canada",
        "country_code": "CAN",
        "company_name": "Faire Wholesale, Inc"
}

Field	Description
name	The name of the individual (recipient) to contact at the address.
address1	The first line of street address information.
address2	Optional. The second line of street address information.
postal_code	The ZIP/postal code.
city	The city.
state	The full name of the state or province.
state_code	The ISO 3166 two-letter code for the state or province.
phone_number	The phone number used to contact the recipient.
country	The full name of the country.
country_code	The ISO alpha-3 country code.
company_name	The name of the company at this address.

Payout Costs

Contains information about the costs associated with an order.

A sample payout costs object might look like:

{
  "payout_fee_cents": 2100,
  "payout_fee_bps": 300,
  "commission_cents": 10500,
  "commission_bps": 1500
}

Field	Description
payout_fee_cents	The amount charged to the brand to pay out the order (e.g. for next-day ACH transfers).
payout_fee_bps	The payout fee basis points used to calculate the payout fee (e.g. 300 is 3%).
commission_cents	The amount of commission charged to the brand for the order.
commission_bps	The commission basis points used to calculate the commission (e.g. 1500 is 15%).

Errors

The Faire API uses the following error codes:

Error Code	Meaning
400	Bad Request -- Your request is invalid.
401	Unauthorized -- Your API key is wrong.
404	Not Found -- The requested resource could not be found.
405	Method Not Allowed -- You tried to access an entity with an invalid method.
418	I'm a teapot.
429	Too Many Requests.
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

Changelog

2023-11-28

Removed DELETE https://www.faire.com/api/v1/products/options/<ID>

2020-07-01

The Product field: minimum_order_quantity is now writable

2020-05-01

Added documentation for a new Product field: allow_sales_when_out_of_stock

2020-04-29

Deprecated Product Categories
Added Taxonomy Types
Added explanation of how to stop inventory tracking to Update Inventory Levels

2020-04-14

Renamed "Modify A Product" to Update A Product
Improved instructions for how to arrange product options.

2020-04-13

Added a Read-Only field sale_state to products and product options
Added a Read-Only field minimum_order_quantity to products
Added documentation about how Product State Management works.

2020-03-18

Added instructions for how to arrange product options.

2020-02-24

Added this "What's New" page!
Added a batched create products endpoint.

Introduction

Products

Get All Products

HTTP Request

Query Parameters

Get A Product By ID

HTTP Request

Path Parameters

Create A Product

HTTP Request

Request Parameters

Create A Batch of Products

HTTP Request

Request Parameters

Update A Product

HTTP Request

Path Parameters

Request Parameters

Arranging Product Options

HTTP Request

Details

DEPRECATED Get All Product Categories

HTTP Request

Get All Taxonomy Types

Product Options

Create a Product Option

HTTP Request

Path Parameters

Request Fields

Update a Product Option

HTTP Request

Path Parameters

Updatable Fields

Update Inventory Levels

HTTP Request

Request Parameters

Product State Management

Sale State

Summary of what the different states represent in various contexts:

Detailed Technical Explanation

Faire UI

Faire Automated Systems

Product Options

Products

Note: Pre-orders

Faire Public API

WARNING

Orders

Order States

Get all Orders

HTTP Request

Query Parameters

Get a single order by ID

HTTP Request

Path Parameters

Accept an Order

HTTP Request

Path Parameters

Request Body Fields

Add Shipments to an Order

HTTP Request

Path Parameters

Request Body Fields

Order Items

Backordering Items

HTTP Request

Path Parameters

Request Body Fields

Shipments

Brands

Get Brand Profile

HTTP Request

Retailers

Get Retailer Public Profile

HTTP Request

Path Parameters

Addresses

Payout Costs

Errors

Changelog

`DEPRECATED` Get All Product Categories