NAV Navbar

Introduction

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.

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.

Delete A Product

This endpoint soft deletes a single product given an ID. This means that the product will have the deleted flag set to true and will no longer be visible on Faire.

HTTP Request

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

Path Parameters

Parameter Description
ID The ID of the product to delete.

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.

Delete A Product Option

HTTP Request

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

This endpoint is used to soft delete a product option from an existing product. This will set the product option's deleted flag to true and the option will no longer be visible on Faire.

Path Parameters

Parameter Description
ID The ID of the product option to delete.

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:

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 is reverted to FOR_SALE if an update causes all the conditions to no longer be met.

Products

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:

Faire Public API

Affected Product/Option endpoints:

Affected Inventory endpoints:

On Input to Faire’s Public API:

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.
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

2020-07-01

2020-05-01

2020-04-29

2020-04-14

2020-04-13

2020-03-18

2020-02-24