Introduction

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

You can test that your Faire API access token is working correctly by running the following command.

curl 'https://www.faire.com/external-api/v2/brands/profile' -H 'X-FAIRE-ACCESS-TOKEN: {your access token}'

It should return the profile for the brand account the access token is for.

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.

This is documentation for V2 of the external API. For V1, visit External API V1

Migrating from the v1 API

This section covers the breaking changes to the API we have made that you will need to update your code to support.

Breaking changes

We feel these changes will make the API more stable and easier to use going forward. We take breaking changes seriously and do not plan to have so many breaking changes in future API releases. We want to get the most painful changes out of the way as soon as possible so future API upgrades will be simple.

Changes to terminology

Our v1 API used non-standard terminology for product variant and product variant options. We used the terms product options and variations, respectively (nearly an inverse of what is used elsewhere). We have chosen to correct the terminology in the v2 API release.

Product Changes: v1 to v2

Major API changes

• Several field changes. See below.
• Preorders are part of the API! See Products.
• Prepacks are part of the API! See Prepacks.
• The batch product creation API has been removed.
• The get all product categories API has been removed.
• Product variant option names (formerly variations) cannot be changed.
• URL paths now start with https://www.faire.com/external-api/v2 instead of https://www.faire.com/api/v1.

Product field changes

The following fields have been changed with products.

Field Name	Change Type	Details
lifecycle_state	Added	The DELETED state used to be a potential sales_state value.
sale_state	Modified	The only values are now FOR_SALE and SALES_PAUSED.
wholesale_price_cents	Removed	This field never really made sense. Product variants are the physical item and are often priced differently.
retail_price_cents	Removed	This field never really made sense. Product variants are the physical item and are often priced differently.
active	Removed	Replaced by lifecycle_state.
deleted	Removed	Replaced by lifecycle_state.
variant_option_sets	Renamed/Modified	Replaces variation_map. It now must be specified during product creation. The JSON structure is now an ordered list of variant options instead of an object acting as a map.
options	Renamed	Renamed to variants.
categories	Removed	No longer used.
preorderable	Added	New v2 API feature. See Products.
preorder_details	Added	New v2 API feature. See Products.
prepacks	Added	New v2 API feature. See Prepacks.

Variant Changes: v1 to v2

Major API changes

• Several field changes. See below.
• Product variant option values (formerly variations) cannot be changed.

Variant field changes

Field Name	Change Type	Details
lifecycle_state	Added	The DELETED state used to be a potential sale_state value.
sale_state	Modified	The only values are now FOR_SALE and SALES_PAUSED.
active	Removed	Replaced by lifecycle_state.
deleted	Removed	Replaced by lifecycle_state.
variations	Renamed/Modified	Renamed to options.

Timestamp Format Changed: v1 to v2

In the v1 API, our timestamps were in the basic format of ISO 8601. We decided to use the extended format of ISO 8601 for all timestamps in the v2 API.

For example, "20190314T000915.000Z" in the v1 API will become "2019-03-14T00:09:15.000Z" in the v2 API.

Key Definitions

Product Definition

A product is a category of similar physical items that are differentiated by their options. An example product could be a Faire-branded sweatshirt. The sweatshirt may come in different sizes and colors. The product itself represents the kind of product, but not a specific variant.

Option Definition

An option is a variable attribute that a product has. An example might be size or color. Options are defined with an option name and several option values. A "color" option could have "red", "blue", and "yellow", for example. In this example, the option name is "color" and the option values are "red", "blue", and "yellow".

Variant Definition

A variant is a specific combination of option values. For example, for a Faire-branded sweatshirt product with "size" and "color" options, a large, red Faire-branded sweatshirt would be a variant. Variants represent an actual physical item and have pricing, unique skus, and inventory.

Products

Products are the goods that brands sell on Faire. A product can have multiple variants, differentiated by options such as size, or color.

A product is structurally defined by its option names. They define the types of variants that can exist for the product. A product with a "Size" option is structurally different from a product with both "Size" and "Color". Since the option names are a defining trait, they cannot be changed on a product. If you want to add a new option name to a product, you should delete the product and create a new one.

The option values for a product's options can be changed. They do not define the structure of the product and instead only define what variants can be created.

A product's options affect the display ordering on Faire for the variants. The ordering of the option names on the product are used first for ordering and then the values are used secondarily for ordering. For example, if the available options on a t-shirt are "Color":["Red", "Blue"] and "Size":["Small", "Medium". "Large"], then a large red t-shirt would appear before a medium blue t-shirt, which would appear before a large blue t-shirt.

A sample product might look like:

{
  "id": "p_123",
  "idempotence_token": "4aytry2ust",
  "brand_id": "b_abc",
  "name": "Faire's fantastic candle",
  "sale_state" : "FOR_SALE",
  "lifecycle_state" : "PUBLISHED",
  "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.",
  "unit_multiplier": 2,
  "minimum_order_quantity": 8,
  "per_style_minimum_order_quantity": 0,
  "variant_option_sets": [
    {
      "name": "Scent",
      "values": [
        "Cinnamon",
        "Skunk",
        "Vanilla"
      ]
    }
  ],
  "variants": [
    {
      "id": "po_123",
      "idempotence_token": "rrc23negw",
      "product_id": "p_123",
      "name": "Vanilla Scent",
      "sku": "vanilla-2019",
      "available_quantity": 42,
      "backordered_until": "20190208T000915.000Z",
      "created_at": "2019-03-14T00:09:15.000Z",
      "updated_at": "2019-03-15T00:09:15.000Z",
      "images": [
        {
          "id": "i_adqaiy3htm",
          "width": 1000,
          "height": 1000,
          "sequence": 0,
          "url": "https://cdn.faire.com/374cd3041a4c4.png",
          "tags": [
            "Hero"
          ]
        }
      ],
      "options": [
        {
          "name": "Scent",
          "value": "Vanilla"
        }
      ],
      "wholesale_price_cents": 299,
      "retail_price_cents": 599,
      "tariff_code": "340600"
    }
  ],
  "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"
        ]
    }
  ],
  "taxonomy_type": {
    "id": "tt_23nl3bzl00"
  },
  "preorderable": true,
  "preorder_details": {
    "order_by_date": "2021-04-01",
    "keep_active_past_order_by_date": false,
    "expected_ship_date": "2021-05-21",
    "expected_ship_window_end_date": "2021-05-24"
  },
  "created_at": "2019-03-14T00:09:15.000Z",
  "updated_at": "2019-03-15T00:09:15.000Z"
}

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_".
name	The name of the product.
sale_state	READ-ONLY The current sellability of the product variant on Faire. See Product State Management.
lifecycle_state	The current stage in the lifecycle of a product on Faire. See Product State Management.
short_description	A short description of the product, at most 75 characters.
description	A description of the product, at most 1,000 characters.
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.
per_style_minimum_order_quantity	The minimum nuber of units of this product that can be ordered for the same "style". A "style" is defined as the set of variation values for an option, excluding the "Size" variation. A product without a "Size" variation cannot use per_style_minimum_order_quantity. This field is mutually exclusive with minimum_order_quantity and unit_multiplier. When setting per_style_minium_order_quantity to a number greater than 0, unit_multiplier must be set to 1 and minimum_order_quantity must be set to 0.
variant_option_sets	A list of the different available options used to compose variants. The names of the options on a product cannot change after creation.
variants	A list of product variants that belong to this product.
idempotence_token	The identifier used for idempotence when this product was created.
images	The list of images associated with the 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.
preorderable	Boolean that is true when the product can be preordered. If this field is true, preorder_details will be non-null.
preorder_details	An object containing all the details for a preorderable product. Null if preorderable is false.
preorder_details.order_by_date	An ISO 8601 date representing the latest date this product can be preordered.
preorder_details.keep_active_past_order_by_date	Boolean that, when true, will keep products active past their orderByDate. Products are auto deactivated at the order by date. Setting this flag to true avoids this auto deactivation and the product to be explicitly deactivated. When a product reaches the order by date and this flag is true, the product remains active and it can still be preordered before start ship date, and ordered as a regular order after the start ship date.
preorder_details.expected_ship_date	An ISO 8601 date representing the start of the shipping window for this preorder product.
preorder_details.expected_ship_window_end_date	An ISO 8601 date representing the end of the shipping window for this preorder product.
created_at	READ-ONLY An ISO 8601 timestamp of when the product was created.
updated_at	READ-ONLY An ISO 8601 timestamp of when the product was last updated.

Get All Products

This endpoint retrieves a list of products, ordered ascending by updated_at. By default, it only returns products that are not deleted.

HTTP Request

GET https://www.faire.com/external-api/v2/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 timestamp. If specified, only return products that have been modified since.
sku	null	The SKU of the product variants to search by, if supplied.
include_deleted	null	True to include deleted products in the response, false or unspecified to omit them.

Response

This endpoint returns JSON structured like:

{
  "page": 1,
  "limit": 50,
  "products": [
    {
      "id": "p_123",
      "idempotence_token": "4aytry2ust",
      "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": "NOT_FOR_SALE",
      "lifecycle_state": "DRAFT",
      "name": "Faire's fantastic candle",
      "unit_multiplier": 2,
      "minimum_order_quantity": 8,
      "per_style_minimum_order_quantity": 0,
      "variant_option_sets": [
        {
          "name": "Scent",
          "values": [
            "Cinnamon",
            "Skunk",
            "Vanilla"
          ]
        }
      ],
      "taxonomy_type": {
        "id": "tt_23nl3bzl00",
        "name": "Votive Candle"
      },
      "variants": [
        {
          "id": "po_123",
          "idempotence_token": "rrc23negw",
          "name": "Vanilla Scent",
          "sku": "vanilla-2019",
          "images": [
            {
              "url": "https://cdn.faire.com/374cd3041a4c4.png"
            }
          ],
          "options": [
            {
              "name": "Scent",
              "value": "Vanilla"
            }
          ],
          "wholesale_price_cents": 299,
          "retail_price_cents": 599
        }
      ],
      "created_at": "2019-03-14T00:09:15.000Z",
      "updated_at": "2019-03-15T00:09:15.000Z"
    }
  ]
}

Get A Product By ID

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

HTTP Request

GET https://www.faire.com/external-api/v2/products/<ID>

Path Parameters

Parameter	Description
ID	The ID of the product to retrieve.

Response

This endpoint returns JSON structured like:

{
  "id": "p_123",
  "idempotence_token": "4aytry2ust",
  "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": "NOT_FOR_SALE",
  "lifecycle_state": "DRAFT",
  "name": "Faire's fantastic candle",
  "unit_multiplier": 2,
  "minimum_order_quantity": 8,
  "per_style_minimum_order_quantity": 0,
  "variant_option_sets": [
    {
      "name": "Scent",
      "values": [
        "Cinnamon",
        "Skunk",
        "Vanilla"
      ]
    }
  ],
  "taxonomy_type": {
    "id": "tt_23nl3bzl00",
    "name": "Votive Candle"
  },
  "variants": [
    { 
      "id": "po_123",
      "idempotence_token": "rrc23negw",
      "name": "Vanilla Scent",
      "sku": "vanilla-2019",
      "images": [
        {
          "url": "https://cdn.faire.com/374cd3041a4c4.png"
        }
      ],
      "options": [
        {
          "name": "Scent",
          "value": "Vanilla"
        }
      ],
      "wholesale_price_cents": 299,
      "retail_price_cents": 599
    }
  ],
  "created_at": "2019-03-14T00:09:15.000Z",
  "updated_at": "2019-03-15T00:09:15.000Z"
}

Create A Product

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

{
  "idempotence_token": "4aytry2ust",
  "name": "Faire's fantastic candle",
  "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.",
  "lifecycle_state": "PUBLISHED",
  "unit_multiplier": 2,
  "minimum_order_quantity": 8,
  "variant_option_sets": [
    {
      "name": "Scent",
      "values": [
        "Cinnamon",
        "Skunk",
        "Vanilla"
      ]
    }
  ],  
  "variants": [
    {
      "idempotence_token": "rrc23negw",
      "name": "Vanilla Scent",
      "sku": "vanilla-2019",
      "images": [
        {
          "url": "https://cdn.faire.com/374cd3041a4c4.png"
        }
      ],
      "options": [
        {
          "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"
    }
  ],
  "preorderable": true,
  "preorder_details": {
    "order_by_date": "2021-04-01",
    "keep_active_past_order_by_date": false,
    "expected_ship_date": "2021-05-21",
    "expected_ship_window_end_date": "2021-05-24"
  },  
  "taxonomy_type": {
    "id": "tt_23nl3bzl00"
  }
}

This creates a single product in the specified lifecycle_state, with a sale_state of FOR_SALE that is preorderable.

HTTP Request

POST https://www.faire.com/external-api/v2/products

Request Parameters

Parameter	Description	Required
idempotence_token	The identifier to use for idempotence when creating this product. This must be specified and be unique per product when creating.	Required
name	The name of the product.	Required
short_description	A short description of the product, at most 75 characters.	Optional
description	A description of the product, at most 1,000 characters.	Optional
lifecycle_state	The current stage in the lifecycle of a product on Faire. See Product State Management	Optional
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.	Required
minimum_order_quantity	The minimum number of units required to purchase this product. Must be a multiple of the unit_multiplier.	Required
per_style_minimum_order_quantity	The minimum nuber of units of this product that can be ordered for the same "style". A "style" is defined as the set of variation values for an option, excluding the "Size" variation. A product without a "Size" variation cannot use per_style_minimum_order_quantity. This field is mutually exclusive with minimum_order_quantity and unit_multiplier. When setting per_style_minium_order_quantity to a number greater than 0, unit_multiplier must be set to 1 and minimum_order_quantity must be set to 0.	Optional
variant_option_sets	A list of the different available options used to compose variants. See Product Variant Options.	Required
variants	A list of product variants that belong to this product.	Required
images	The list of images associated with the product.	Optional
taxonomy_type	The taxonomy type of this product.	Optional
allow_sales_when_out_of_stock	Boolean that determines whether this product should automatically go out of stock when it has insufficient inventory.	Optional
preorderable	Boolean that is true when the product can be preordered. If this field is true, preorder_details will be non-null.	Optional
preorder_details	An object containing all the details for a preorderable product. Null if preorderable is false.	Optional
preorder_details.order_by_date	An ISO 8601 date representing the latest date this product can be preordered.	Optional
preorder_details.keep_active_past_order_by_date	Boolean that, when true, will keep products active past their orderByDate. Products are auto deactivated at the order by date. Setting this flag to true avoids this auto deactivation and the product to be explicitly deactivated. When a product reaches the order by date and this flag is true, the product remains active and it can still be preordered before start ship date, and ordered as a regular order after the start ship date.	Optional
preorder_details.expected_ship_date	An ISO 8601 date representing the start of the shipping window for this preorder product.	Optional
preorder_details.expected_ship_window_end_date	An ISO 8601 date representing the end of the shipping window for this preorder product.	Optional

Response

This endpoint returns JSON structured like:

{
  "id": "p_123",
  "idempotence_token": "4aytry2ust",
  "name": "Faire's fantastic candle",
  "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.",
  "lifecycle_state": "PUBLISHED",
  "unit_multiplier": 2,
  "minimum_order_quantity": 8,
  "per_style_minimum_order_quantity": 0,
  "variant_option_sets": [
    {
      "name": "Scent",
      "values": [
        "Cinnamon",
        "Skunk",
        "Vanilla"
      ]
    }
  ],  
  "variants": [
    {
      "id": "po_123",
      "name": "Vanilla Scent",
      "idempotence_token": "rrc23negw",
      "sku": "vanilla-2019",
      "images": [
        {
          "url": "https://cdn.faire.com/374cd3041a4c4.png"
        }
      ],
      "options": [
        {
          "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"
    }
  ],
  "preorderable": true,
  "preorder_details": {
    "order_by_date": "2021-04-01",
    "keep_active_past_order_by_date": false,
    "expected_ship_date": "2021-05-21",
    "expected_ship_window_end_date": "2021-05-24"
  },  
  "taxonomy_type": {
    "id": "tt_23nl3bzl00",
    "name": "Votive Candle"
  }
}

Update A Product

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

{
  "name": "Faire's fantastic candle",
  "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.",
  "lifecycle_state": "PUBLISHED",
  "unit_multiplier": 2,
  "minimum_order_quantity": 8,
  "variants": [
    {
      "id": "po_123",
      "name": "Updated Vanilla Scent"
    },
    {
      "name": "New Cinnamon Scent",
      "sku": "Cinnamon-2019",
      "images": [
        {
          "url": "https://cdn.faire.com/374cd3041a4c5.png"
        }
      ],
      "options": [
        {
          "name": "Scent",
          "value": "Cinnamon"
        }
      ],
      "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"
  },
  "preorderable": true,
  "preorder_details": {
    "order_by_date": "2021-04-01",
    "keep_active_past_order_by_date": false,
    "expected_ship_date": "2021-05-21",
    "expected_ship_window_end_date": "2021-05-24"
  }
}

This updates a single product. Variants can be updated/created with this endpoint, but prepacks must use the prepack APIs.

HTTP Request

PATCH https://www.faire.com/external-api/v2/products/<ID>

Path Parameters

Parameter	Description
ID	The ID of the product to modify.

Request Parameters

Parameter	Description	Required
name	The name of the product.	Optional
short_description	A short description of the product, at most 75 characters.	Optional
description	A description of the product, at most 1,000 characters.	Optional
lifecycle_state	The current stage in the lifecycle of a product on Faire. See Product State Management	Optional
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.	Optional
minimum_order_quantity	The minimum number of units required to purchase this product. Must be a multiple of the unit_multiplier.	Optional
variants	A list of product variants that belong to this product. To update an existing variant, the variant ID must be provided.	Optional
images	The list of images associated with the product. Images in this list will be added to the existing images. This list will not replace the existing	Optional
images. Faire will download a copy of the image at the specified url.	Optional
taxonomy_type	The taxonomy type of this product.	Optional
variant_option_sets	A list of the different available options used to compose variants. Option names cannot be edited, but the option values can be updated.	Optional
allow_sales_when_out_of_stock	Boolean that determines whether this product should automatically go out of stock when it has insufficient inventory.	Optional
preorderable	Boolean that is true when the product can be preordered. If this field is true, preorder_details will be non-null.	Optional
preorder_details	An object containing all the details for a preorderable product. Null if preorderable is false.	Optional
preorder_details.order_by_date	An ISO 8601 date representing the latest date this product can be preordered.	Optional
preorder_details.keep_active_past_order_by_date	Boolean that, when true, will keep products active past their orderByDate. Products are auto deactivated at the order by date. Setting this flag to true avoids this auto deactivation and the product to be explicitly deactivated. When a product reaches the order by date and this flag is true, the product remains active and it can still be preordered before start ship date, and ordered as a regular order after the start ship date.	Optional
preorder_details.expected_ship_date	An ISO 8601 date representing the start of the shipping window for this preorder product.	Optional
preorder_details.expected_ship_window_end_date	An ISO 8601 date representing the end of the shipping window for this preorder product.	Optional

Response

This endpoint returns JSON structured like:

{
  "id": "p_123",
  "name": "Faire's fantastic candle",
  "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.",
  "lifecycle_state": "PUBLISHED",
  "unit_multiplier": 2,
  "minimum_order_quantity": 8,
  "idempotence_token": "4aytry2ust",
  "variant_option_sets": [
    {
      "name": "Scent",
      "values": [
        "Cinnamon",
        "Skunk",
        "Vanilla"
      ]
    }
  ],  
  "variants": [
    {
      "id": "po_123",
      "name": "Updated Vanilla Scent",
      "sku": "vanilla-2019",
      "images": [
        {
          "url": "https://cdn.faire.com/374cd3041a4c4.png"
        }
      ],
      "idempotence_token": "rrc23negw",
      "options": [
        {
          "name": "Scent",
          "value": "Vanilla"
        }
      ],
      "wholesale_price_cents": 299,
      "retail_price_cents": 599
    },
    {
      "id": "po_456",
      "name": "New Cinnamon Scent",
      "sku": "Cinnamon-2019",
      "images": [
        {
          "url": "https://cdn.faire.com/374cd3041a4c5.png"
        }
      ],
      "idempotence_token": "rrc45negw",
      "options": [
        {
          "name": "Scent",
          "value": "Cinnamon"
        }
      ],
      "wholesale_price_cents": 299,
      "retail_price_cents": 599
    }
  ],
  "images": [
    {
      "url": "https://cdn.faire.com/53105976.png"
    },
    {
      "url": "https://cdn.faire.com/554156553.png"
    }
  ],
  "preorderable": true,
  "preorder_details": {
    "order_by_date": "2021-04-01",
    "keep_active_past_order_by_date": false,
    "expected_ship_date": "2021-05-21",
    "expected_ship_window_end_date": "2021-05-24"
  },  
  "taxonomy_type": {
    "id": "tt_23nl3bzl00",
    "name": "Votive Candle"
  }
}

Delete A Product

This endpoint deletes a single product given an ID. This means that the product will have its lifecycle_state set to DELETED and will no longer be visible on Faire.

HTTP Request

DELETE https://www.faire.com/external-api/v2/products/<ID>

Path Parameters

Parameter	Description
ID	The ID of the product to delete.

Response

204 NO_CONTENT

Update product's variation option sets

This endpoint replaces the current variation option sets of a product by the given new variation option sets. Options applied in the current variants cannot be removed.

If the product is sold in prepacks, size options cannot be reorganized and new values cannot be inserted to the middle of size options. (e.g current size options: ["S", "M", "L"], then new size options ["S", "M", "L", "XL"] or ["XS", "S", "M", "L"] is acceptable, but ["M", "S", "L"] or ["S", "M", "XL", "L"] is invalid.)

{
  "variant_option_sets": [
    {
      "name": "Scent",
      "values": [
        "Cinnamon", 
        "Skunk", 
        "Vanilla"
      ]
    },
    {
      "name": "Color",
      "values": [
        "Red", 
        "Blue", 
        "Yellow"
      ]
    }
  ]
}

HTTP Request

PATCH https://www.faire.com/external-api/v2/products/<ID>/variant-option-sets

Path Parameters

Parameter	Description
ID	The ID of the product to update variant option sets

Request Parameters

Parameter	Description	Required
variant_option_sets	A list of the different available options used to compose variants. Option names cannot be edited, but the option values can be updated.	Required

Response

This endpoint returns JSON structured like:

{
  "variant_option_sets": [
    {
      "name": "Scent",
      "values": [
        "Cinnamon", 
        "Skunk", 
        "Vanilla"
      ]
    },
    {
      "name": "Color",
      "values": [
        "Red", 
        "Blue", 
        "Yellow"
      ]
    }
  ]
}

Get All Taxonomy Types

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

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

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.

HTTP Request

GET https://www.faire.com/external-api/v2/products/types

Response

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

Product Variants

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

A variant has a single option values for each type of option. For example, a variant could have "Red" and "Large" for its product's "Color" and "Size" options, respectively. Variants are defined by their option values, so the values cannot be changed once the variant is created.

A product does not need to exhaustively have a variant for each possible combination of options.

A sample product variant might look like:

{
  "id": "po_123",
  "idempotence_token": "4aytry2ust",
  "product_id": "p_abc",
  "name": "Vanilla",
  "sale_state" : "FOR_SALE",
  "lifecycle_state" : "PUBLISHED",
  "sku": "vanilla-2019",
  "tariff_code": "123123",
  "prices": [
    {
      "geo_constraint": {
        "country": "CAN"
      },
      "wholesale_price": {
        "amount_minor": 1299,
        "currency": "CAD"
      },
      "retail_price": {
        "amount_minor": 2201,
        "currency": "CAD"
      }
    },
    {
      "geo_constraint": {
        "country": "USA"
      },
      "wholesale_price": {
        "amount_minor": 899,
        "currency": "USD"
      },
      "retail_price": {
        "amount_minor": 1801,
        "currency": "USD"
      }
    }
  ],
  "available_quantity": 42,
  "backordered_until": "2019-02-08T00:09:15.000Z",
  "created_at": "2019-03-14T00:09:15.000Z",
  "updated_at": "2019-03-15T00:09:15.000Z",
  "options": [
    {
      "name": "Scent",
      "value": "Vanilla"
    }
  ],
  "images": [
    {
      "id": "i_adqaiy3htm",
      "width": 1000,
      "height": 1000,
      "sequence": 0,
      "url": "https://cdn.faire.com/374cd3041a4c4.png",
      "tags": [
        "Hero"
      ]
    }
  ]
}

Field	Description
id	A unique identifier of the product variant, beginning with "po_".
idempotence_token	The identifier used for idempotence when this variant was created.
product_id	A unique identifier of the product the variant belongs to, beginning with "p_".
name	READ-ONLY The name of the product variant, auto-generated by option values.
sale_state	READ-ONLY The current sellability of the product variant on Faire. See Product State Management
lifecycle_state	The current stage in the lifecycle of a product on Faire. See Product State Management
sku	An identifier that should be unique amongst product variants. It is up to the client to keep SKUs unique. SKUs are case-sensitive.
retail_price_cents	Deprecated. The current recommended retailer price of a single unit of this variant in cents (US dollars).
wholesale_price_cents	Deprecated. The current wholesale price of a single unit of this variant in cents (US dollars).
prices	The prices for this product variant based on geographic region and currency.
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 variant to be FOR_SALE until this date.
created_at	READ-ONLY An ISO 8601 timestamp of when the product variant was created.
updated_at	READ-ONLY An ISO 8601 timestamp of when the product variant was last updated.
options	A set of options (attributes) that define this product variant. e.g. If the variant is a large red shirt, the options might include Color:Red and Size:Large. The options are immutable and must be valid values from the product's variant_option_sets.
images	A list of images for this variant. If supplied on creation of the variant, Faire will download a copy of the image at the specified url.

Create Product Variant

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

{
  "idempotence_token": "4aytry2ust",
  "name": "Vanilla",
  "lifecycle_state" : "PUBLISHED",
  "sku": "vanilla-2019",
  "tariff_code": "123123",
  "prices": [
    {
      "geo_constraint": {
        "country": "CAN"
      },
      "wholesale_price": {
        "amount_minor": 1299,
        "currency": "CAD"
      },
      "retail_price": {
        "amount_minor": 2201,
        "currency": "CAD"
      }
    },
    {
      "geo_constraint": {
        "country": "USA"
      },
      "wholesale_price": {
        "amount_minor": 899,
        "currency": "USD"
      },
      "retail_price": {
        "amount_minor": 1801,
        "currency": "USD"
      }
    }
  ],
  "available_quantity": 42,
  "options": [
    {
      "name": "Scent",
      "value": "Vanilla"
    }
  ],
  "images": [
    {
      "width": 1000,
      "height": 1000,
      "sequence": 0,
      "url": "https://cdn.faire.com/374cd3041a4c4.png",
      "tags": [
        "Hero"
      ]
    }
  ]
}

HTTP Request

POST https://www.faire.com/external-api/v2/products/<PRODUCT_ID>/variants

Path Parameters

Parameter	Description
PRODUCT_ID	The ID of the product corresponding with the product variant

Request Parameters

Field	Description	Required
idempotence_token	The identifier used for idempotence when this variant was created.	Required
lifecycle_state	The current stage in the lifecycle of a product on Faire. See Product State Management	Optional
sku	An identifier that should be unique amongst product variants. It is up to the client to keep SKUs unique. SKUs are case-sensitive.	Optional
tariff_code	The tariff code of the variant, must be a valid HS6 Tariff Code.	Optional
retail_price_cents	Deprecated. The current recommended retailer price of a single unit of this variant in cents (US dollars).	Optional
wholesale_price_cents	Deprecated. The current wholesale price of a single unit of this variant in cents (US dollars).	Optional
prices	The prices for this product variant based on geographic region and currency.	Required
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.	Optional
backordered_until	ISO 8601 timestamp that indicates when the variant will be back in stock. If set, Faire will not allow the product variant to be FOR_SALE until this date.	Optional
options	A set of options (attributes) that define this product variant. e.g. If the variant is a large red shirt, the options might include Color:Red and Size:Large. The options must be valid values from the product's variant_option_sets.	Optional
images	A list of images for this variant. If supplied on creation of the variant, Faire will download a copy of the image at the specified url.	Optional

Response

This endpoint returns JSON structured like:

{
  "id": "po_123",
  "idempotence_token": "4aytry2ust",
  "product_id": "p_abc",
  "name": "Vanilla Scent",
  "sale_state" : "FOR_SALE",
  "lifecycle_state" : "PUBLISHED",
  "sku": "vanilla-2019",
  "tariff_code": "123123",
  "prices": [
    {
      "geo_constraint": {
        "country": "CAN"
      },
      "wholesale_price": {
        "amount_minor": 1299,
        "currency": "CAD"
      },
      "retail_price": {
        "amount_minor": 2201,
        "currency": "CAD"
      }
    },
    {
      "geo_constraint": {
        "country": "USA"
      },
      "wholesale_price": {
        "amount_minor": 899,
        "currency": "USD"
      },
      "retail_price": {
        "amount_minor": 1801,
        "currency": "USD"
      }
    }
  ],
  "available_quantity": 42,
  "created_at": "2019-03-14T00:09:15.000Z",
  "updated_at": "2019-03-15T00:09:15.000Z",
  "options": [
    {
      "name": "Scent",
      "value": "Vanilla"
    }
  ],
  "images": [
    {
      "id": "i_adqaiy3htm",
      "width": 1000,
      "height": 1000,
      "sequence": 0,
      "url": "https://cdn.faire.com/374cd3041a4c4.png",
      "tags": [
        "Hero"
      ]
    }
  ]
}

Update Product Variant

This endpoint accepts a variant with only the fields populated that you want to modify. A variant's options cannot be updated. If you want to change the options, delete the existing variant and create a new variant with new options.

{
  "lifecycle_state" : "PUBLISHED",
  "sku": "vanilla-2019",
  "tariff_code": "123123",
  "prices": [
    {
      "geo_constraint": {
        "country": "USA"
      },      
      "wholesale_price": {
        "amount_minor": 1099,
        "currency": "USD"
      },
      "retail_price": {
        "amount_minor": 2001,
        "currency": "USD"
      }
    }
  ],
  "available_quantity": 42,
  "images": [
    {
      "width": 1000,
      "height": 1000,
      "sequence": 0,
      "url": "https://cdn.faire.com/374cd3041a4c4.png",
      "tags": [
        "Hero"
      ]
    }
  ]
}

HTTP Request

PATCH https://www.faire.com/external-api/v2/products/<PRODUCT_ID>/variants/<VARIANT_ID>

Path Parameters

Parameter	Description
PRODUCT_ID	The ID of the product corresponding with the product variant
VARIANT_ID	The ID of the product variant to update

Request Parameters

Field	Description	Required
lifecycle_state	The current stage in the lifecycle of a product on Faire. See Product State Management	Optional
sku	An identifier that should be unique amongst product variants. It is up to the client to keep SKUs unique. SKUs are case-sensitive.	Optional
tariff_code	The tariff code of the variant, must be a valid HS6 Tariff Code.	Optional
retail_price_cents	Deprecated. The current recommended retailer price of a single unit of this variant in cents (US dollars).	Optional
wholesale_price_cents	Deprecated. The current wholesale price of a single unit of this variant in cents (US dollars).	Optional
prices	The prices for this product variant based on geographic region and currency.	Optional
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.	Optional
backordered_until	ISO 8601 timestamp that indicates when the variant will be back in stock. If set, Faire will not allow the product variant to be FOR_SALE until this date.	Optional
images	A list of images for this variant. Images in this list will be added to the existing images. This list will not replace the existing images. Faire will download a copy of the image at the specified url.	Optional

Response

This endpoint returns JSON structured like:

{
  "id": "po_123",
  "idempotence_token": "4aytry2ust",
  "product_id": "p_abc",
  "name": "Vanilla Scent",
  "sale_state" : "FOR_SALE",
  "lifecycle_state" : "PUBLISHED",
  "sku": "vanilla-2019",
  "tariff_code": "123123",
  "prices": [
    {
      "geo_constraint": {
        "country": "USA"
      },
      "wholesale_price": {
        "amount_minor": 1099,
        "currency": "USD"
      },
      "retail_price": {
        "amount_minor": 2001,
        "currency": "USD"
      }
    }
  ],
  "available_quantity": 42,
  "created_at": "2019-03-14T00:09:15.000Z",
  "updated_at": "2019-03-15T00:09:15.000Z",
  "options": [
    {
      "name": "Scent",
      "value": "Vanilla"
    }
  ],
  "images": [
    {
      "id": "i_adqaiy3htm",
      "width": 1000,
      "height": 1000,
      "sequence": 0,
      "url": "https://cdn.faire.com/374cd3041a4c4.png",
      "tags": [
        "Hero"
      ]
    }
  ]
}

Delete A Product Variant

This endpoint deletes a single variant given a product ID and a variant ID. This means that the product variant will have its lifecycle_state set to DELETED and will no longer be visible on Faire. A product must have at least one non-deleted variant. To delete the last variant of product, need to delete the product instead.

HTTP Request

DELETE https://www.faire.com/external-api/v2/products/<PRODUCT_ID>/variants/<VARIANT_ID>

Path Parameters

Parameter	Description
PRODUCT_ID	The ID of the product corresponding with the product variant
VARIANT_ID	The ID of the product variant to delete

Response

204 NO_CONTENT

Update inventory levels by variant IDs

This endpoint updates variant inventory levels by given variant IDs.

{
  "inventories": [
    {
      "product_variant_id": "po_123",
      "current_quantity": 10,
      "discontinued": false
    },
    {
      "product_variant_id": "po_456",
      "current_quantity": 20,
      "discontinued": false,
      "backordered_until": "2019-02-08T00:09:15.000Z"
    }
  ]
}

HTTP Request

PATCH https://www.faire.com/external-api/v2/products/variants/inventory-levels-by-product-variant-ids

Request Parameters

Field	Description	Required
inventories.product_variant_id	The ID of the product variant to update. This is a unique identifier starting with "po_".	Required
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 variant will be deactivated. If there are no active variants for the product, the product will also be deactivated (see: Product State Management).	Optional
inventories.discontinued	Boolean indicating if the variant has been discontinued, and Faire should no longer activate this variant based on inventory levels.	Optional
inventories.backordered_until	ISO 8601 timestamp that indicates when the variant will be back in stock. Faire will not allow the product variant to be FOR_SALE until this date and will deactivate all prepacks containing the variant.	Optional

Response

This endpoint returns JSON structured like:

{
  "variants": [
    {
      "id": "po_123",
      "idempotence_token": "4aytry2ust",
      "product_id": "p_abc",
      "name": "Vanilla",
      "sale_state" : "FOR_SALE",
      "lifecycle_state" : "PUBLISHED",
      "sku": "vanilla-2019",
      "tariff_code": "123123",
      "prices": [
        {
          "geo_constraint": {
            "country": "USA"
          },
          "wholesale_price": {
            "amount_minor": 1099,
            "currency": "USD"
          },
          "retail_price": {
            "amount_minor": 2001,
            "currency": "USD"
          }
        }
      ],
      "available_quantity": 10,
      "created_at": "2019-03-14T00:09:15.000Z",
      "updated_at": "2019-03-15T00:09:15.000Z",
      "options": [
        {
          "name": "Scent",
          "value": "Vanilla"
        }
      ]
    },
    {
      "id": "po_456",
      "idempotence_token": "3wegt4erg",
      "product_id": "p_abc",
      "name": "Cinnamon",
      "sale_state" : "SALE_PAUSED",
      "lifecycle_state" : "PUBLISHED",
      "sku": "cinnamon-2019",
      "tariff_code": "123123",
      "retail_price_cents": 1099,
      "wholesale_price_cents": 600,
      "available_quantity": 20,
      "backordered_until": "2019-02-08T00:09:15.000Z",
      "created_at": "2019-03-14T00:09:15.000Z",
      "updated_at": "2019-03-15T00:09:15.000Z",
      "options": [
        {
          "name": "Scent",
          "value": "Cinnamon"
        }
      ]
    }
  ]
}

Update inventory levels by variant SKUs

This endpoint updates variant inventory levels by given variant SKUs.

{
  "inventories": [
    {
      "sku": "vanilla-2019",
      "current_quantity": 10,
      "discontinued": false
    },
    {
      "sku": "cinnamon-2019",
      "current_quantity": 20,
      "discontinued": false,
      "backordered_until": "2019-02-08T00:09:15.000Z"
    }
  ]
}

HTTP Request

PATCH https://www.faire.com/external-api/v2/products/variants/inventory-levels-by-skus

Request Parameters

Field	Description	Required
inventories.sku	Matches the most recently created product variant with that SKU.	Required
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 variant will be deactivated. If there are no active variants for the product, the product will also be deactivated (see: Product State Management).	Optional
inventories.discontinued	Boolean indicating if the variant has been discontinued, and Faire should no longer activate this variant based on inventory levels.	Optional
inventories.backordered_until	ISO 8601 timestamp that indicates when the variant will be back in stock. Faire will not allow the product variant to be FOR_SALE until this date and will deactivate all prepacks containing the variant.	Optional

Response

This endpoint returns JSON structured like:

{
  "variants": [
    {
      "id": "po_123",
      "idempotence_token": "4aytry2ust",
      "product_id": "p_abc",
      "name": "Vanilla",
      "sale_state" : "FOR_SALE",
      "lifecycle_state" : "PUBLISHED",
      "sku": "vanilla-2019",
      "tariff_code": "123123",
      "prices": [
        {
          "geo_constraint": {
            "country": "USA"
          },
          "wholesale_price": {
            "amount_minor": 1099,
            "currency": "USD"
          },
          "retail_price": {
            "amount_minor": 2001,
            "currency": "USD"
          }
        }
      ],
      "available_quantity": 10,
      "created_at": "2019-03-14T00:09:15.000Z",
      "updated_at": "2019-03-15T00:09:15.000Z",
      "options": [
        {
          "name": "Scent",
          "value": "Vanilla"
        }
      ]
    },
    {
      "id": "po_456",
      "idempotence_token": "3wegt4erg",
      "product_id": "p_abc",
      "name": "Cinnamon",
      "sale_state" : "SALE_PAUSED",
      "lifecycle_state" : "PUBLISHED",
      "sku": "vanilla-2019",
      "tariff_code": "123123",
      "prices": [
        {
          "geo_constraint": {
            "country": "USA"
          },
          "wholesale_price": {
            "amount_minor": 1199,
            "currency": "USD"
          },
          "retail_price": {
            "amount_minor": 2101,
            "currency": "USD"
          }
        }
      ],
      "available_quantity": 20,
      "backordered_until": "2019-02-08T00:09:15.000Z",
      "created_at": "2019-03-14T00:09:15.000Z",
      "updated_at": "2019-03-15T00:09:15.000Z",
      "options": [
        {
          "name": "Scent",
          "value": "Cinnamon"
        }
      ]
    }
  ]
}

Product Variant Prices

A product variant can be sold in different countries on the Faire platform and have different pricing in each country. To specify the currency, set exactly one of geo_constraint.country or geo_constraint.country_group.

A sample price might look like:

{
  "geo_constraint": {
    "country": "USA"
  },
  "wholesale_price": {
    "amount_minor": 999,
    "currency": "USD"
  },
  "retail_price": {
    "amount_minor": 1901,
    "currency": "USD"
  }
}

Field	Description
geo_constraint.country	An ISO-3166-Alpha3 country code that the price applies to. Accepted values include: "USA": United States "CAN": Canada "GBR": United Kingdom. "AUS": Australia Only one of the country or country_group fields may be set.
geo_constraint.country_group	A country group that the price applies to. Accepted values include: "EUROPEAN_UNION": All E.U. member countries Only one of the country or country_group fields may be set.
wholesale_price.amount_minor	The amount of money for the wholesale price in the smallest unit of the applicable currency. For example, 1000 cents for $10.00.
wholesale_price.currency	The type of currency for the wholesale price in ISO 4217 format. For example, US dollars is USD.
retail_price.amount_minor	The amount of money for the retail price in the smallest unit of the applicable currency. For example, 1000 cents for $10.00.
retail_price.currency	The type of currency for the retail price in ISO 4217 format. For example, US dollars is USD.

Prepacks

A product can have variants assembled into a prepack. This prepack is meant to be used with apparel items and is composed of several sizes of the apparel item, at specified quantities, listed from smallest to largest.

The following rules apply when adding a prepack to a product.

• Only products that have an option with the name "Size" can have prepacks.
• Prepacks must have all the sizes between the smallest and largest sizes included. For example, if a prepack has a Small and Large product option, it must also have a Medium product option.
• Prepack items are ordered in ascending order of size.

The description of the prepack is automatically generated based on its sizes and quantities and it follows apparel industry conventions. An example prepack with 2 Small, 1 Medium, and 3 Large product options included would have the description "2-1-3; S-L".

A sample prepack might look like:

{
  "id": "pc_123",
  "idempotence_token": "df41f1dfa",
  "name": "My Red Shirt Prepack",
  "description": "2-1-2; S-L",
  "items": [
    {
      "id": "pci_234",
      "variant_id": "po_d2d1",
      "quantity": 2
    },
    {
      "id": "pci_567",
      "variant_id": "po_4r5e",
      "quantity": 1
    },  
    {
      "id": "pci_890",
      "variant_id": "po_8ash",
      "quantity": 2
    }    
  ],
  "created_at": "2019-03-14T00:09:15.000Z"
}

Field	Description
id	A unique identifier of the prepack, beginning with "pc_".
idempotence_token	The identifier used when this prepack was created.
name	The name of the prepack.
description	A description of the prepack. The description is determined by the quantities and sizes of prepack items.
items	A list of prepack items that belong to this prepack.
created_at	An ISO 8601 timestamp of when the prepack was created.

Prepack Items

Prepack items are a pairing of product variants to the quantity in the prepack.

Field	Description
id	A unique identifier of the prepack item, beginning with "pci_".
variant_id	The identifier of the variant for this prepack item.
quantity	The number of prepack items included in the prepack.

Add a prepack to a product

This endpoint adds a prepack to an existing product:

{
  "idempotence_token": "df41f1dfa",
  "name": "My Red Shirt Prepack",
  "items": [
    {
      "variant_id": "po_d2d1",
      "quantity": 2
    },
    {
      "variant_id": "po_4r5e",
      "quantity": 1
    },  
    {
      "variant_id": "po_8ash",
      "quantity": 2
    }    
  ]
}

HTTP Request

POST https://www.faire.com/external-api/v2/products/{product_id}/prepacks

Path Parameters

Parameter	Description
product_id	The identifier of the product to add the prepack to.

Prepack Request Parameters

Parameter	Description	Required
idempotence_token	The identifier to use for idempotence when creating this prepack. This must be specified and be unique per prepack when creating.	Required
name	The name of the prepack.	Required
items	A list of prepack items that belong to this prepack.	Required

Prepack Item Request Parameters

Parameter	Description	Required
variant_id	The identifier of the product variant for this prepack item.	Required
quantity	The number of prepack items included in the prepack.	Required

Response

This endpoint returns JSON structured like:

{
  "id": "pc_123",
  "idempotence_token": "df41f1dfa",
  "name": "My Red Shirt Prepack",
  "description": "2-1-2; S-L",
  "items": [
    {
      "id": "pci_123",
      "variant_id": "po_d2d1",
      "quantity": 2
    },
    {
      "id": "pci_456",
      "variant_id": "po_4r5e",
      "quantity": 1
    },  
    {
      "id": "pci_789",
      "variant_id": "po_8ash",
      "quantity": 2
    }    
  ]
}

Get a Prepack for a Product

This endpoint gets a single prepack specified in the URL path.

HTTP Request

GET https://www.faire.com/external-api/v2/products/{product_id}/prepacks/{prepack_id}

Path Parameters

Parameter	Description
product_id	The identifier of the product which owns the prepack.
prepack_id	The identifier of the prepack.

Response

This endpoint returns JSON structured like:

{
  "id": "pc_123",
  "idempotence_token": "df41f1dfa",
  "name": "My Red Shirt Prepack",
  "description": "2-1-2; S-L",
  "items": [
    {
      "id": "pci_123",
      "variant_id": "po_d2d1",
      "quantity": 2
    },
    {
      "id": "pci_456",
      "variant_id": "po_4r5e",
      "quantity": 1
    },  
    {
      "id": "pci_789",
      "variant_id": "po_8ash",
      "quantity": 2
    }    
  ]
}

Get all Prepacks for a Product

This endpoint gets all active prepacks of the product specified in the URL path.

HTTP Request

GET https://www.faire.com/external-api/v2/products/{product_id}/prepacks

Path Parameters

Parameter	Description
product_id	The identifier of the product which owns the prepacks.

Response

This endpoint returns JSON structured like:

{
  "prepacks": [
    {
      "id": "pc_123",
      "idempotence_token": "df41f1dfa",
      "name": "My Red Shirt Prepack",
      "description": "2-1-2; S-L",
      "items": [
        {
          "id": "pci_123",
          "variant_id": "po_d2d1",
          "quantity": 2
        },
        {
          "id": "pci_456",
          "variant_id": "po_4r5e",
          "quantity": 1
        },  
        {
          "id": "pci_789",
          "variant_id": "po_8ash",
          "quantity": 2
        }    
      ]
    },
    {
      "id": "pc_456",
      "idempotence_token": "df4werwef",
      "name": "My Red Shirt Prepack",
      "description": "2-2-2; S-L",
      "items": [
        {
          "id": "pci_135",
          "variant_id": "po_d2d1",
          "quantity": 2
        },
        {
          "id": "pci_357",
          "variant_id": "po_4r5e",
          "quantity": 2
        },  
        {
          "id": "pci_579",
          "variant_id": "po_8ash",
          "quantity": 2
        }    
      ]
    }
  ]
}

Delete A Prepack

This endpoint deletes a specified prepack. Deleted prepacks cannot be re-activated.

HTTP Request

DELETE https://www.faire.com/external-api/v2/products/{product_id}/prepacks/{prepack_id}

Path Parameters

Parameter	Description
product_id	The identifier of the product which contains the prepack.
prepack_id	The identifier of the prepack to delete.

Response

204 NO_CONTENT

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": "2019-03-15T00:09:15.000Z",
  "updated_at": "2019-03-15T00:10:00.000Z",
  "state": "PRE_TRANSIT",
  "items": [
    {
      "id": "oi_bq425ju5vh",
      "created_at": "2019-03-15T00:09:15.000Z",
      "updated_at": "2019-03-15T00:09:15.000Z",
      "order_id": "bo_bxdmjbwxid",
      "product_id": "p_fccaefnahr",
      "variant_id": "po_3745tjzrpc",
      "quantity": 1,
      "sku": "goldenretriever",
      "price_cents": 10500,
      "product_name": "Golden Dog",
      "variant_name": "retriever",
      "includes_tester": false,
      "discounts": []
    }
  ],
  "shipments": [
    {
      "id": "s_bq425ju5vh",
      "order_id": "bo_bxdmjbwxid",
      "maker_cost_cents": 2300,
      "carrier": "fedex",
      "tracking_code": "94029300101029282",
      "created_at": "2019-03-15T00:09:15.000Z",
      "updated_at": "2019-03-15T00:09:15.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": "2019-03-15T00:09:15.000Z",
  "payout_costs": {
    "payout_fee_cents": 0,
    "payout_fee_bps": 0,
    "commission_cents": 2625,
    "commission_bps": 2500
  },
  "source": "MARKETPLACE",
  "payment_initiated_at": "2019-03-16T00:10:34.000Z",
  "original_order_id": "bo_bg5ude6pmd",
  "brand_discounts": [
    {
      "id": "bpc_k3w2kb97tp",
      "code": "SUMMER10",
      "includes_free_shipping": false,
      "discount_percentage": 10,
      "discount_type": "PERCENTAGE",
    }
  ]
}

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 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.
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 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 timestamp of when the order was created
updated_at	An ISO 8601 timestamp of when the order was last updated
brand_discounts	A list of any shop-wide promotions that were applied to this order. Does not include product-specific discounts, which can be found under the discounts field of the relevant order item.

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": "2019-03-15T00:09:15.000Z",
        "updated_at": "2019-03-15T00:10:00.000Z",
        "state": "NEW",
        "items": [
          {
            "id": "oi_bq425ju5vh",
            "created_at": "2019-03-15T00:09:15.000Z",
            "updated_at": "2019-03-15T00:09:15.000Z",
            "order_id": "bo_bxdmjbwxid",
            "product_id": "p_fccaefnahr",
            "variant_id": "po_3745tjzrpc",
            "quantity": 1,
            "sku": "goldenretriever",
            "price_cents": 10000,
            "product_name": "Golden Dog",
            "variant_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/external-api/v2/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 timestamp, if specified only show orders that have been modified since.
created_at_min	null	ISO 8601 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 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": "2019-03-15T00:09:15.000Z",
  "updated_at": "2019-03-15T00:10:00.000Z",
  "state": "NEW",
  "items": [
    {
      "id": "oi_bq425ju5vh",
      "created_at": "2019-03-15T00:09:15.000Z",
      "updated_at": "2019-03-15T00:09:15.000Z",
      "order_id": "bo_bxdmjbwxid",
      "product_id": "p_fccaefnahr",
      "variant_id": "po_3745tjzrpc",
      "quantity": 1,
      "sku": "goldenretriever",
      "price_cents": 10000,
      "product_name": "Golden Dog",
      "variant_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/external-api/v2/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": "2019-07-15T00:09:15.000Z"
}

HTTP Request

PUT https://www.faire.com/external-api/v2/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 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/external-api/v2/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": "2019-03-15T00:09:15.000Z",
  "updated_at": "2019-03-15T00:09:15.000Z",
  "order_id": "bo_bxdmjbwxid",
  "product_id": "p_fccaefnahr",
  "variant_id": "po_3745tjzrpc",
  "quantity": 1,
  "sku": "goldenretriever",
  "price": {
    "amount_minor": 10000,
    "currency": "USD"
  },
  "product_name": "Golden Dog",
  "variant_name": "retriever",
  "includes_tester": true,
  "tester_price": {
    "amount_minor": 500,
    "currency": "USD"
  },
  "discounts": [
    {
      "id": "bpc_cjpyaf56ts",
      "code": "STOCK_UP",
      "includes_free_shipping": false,
      "discount_amount": {
        "amount_minor": 2000,
        "currency": "USD"
      },
      "discount_type": "FLAT_AMOUNT"
    }
  ]
}

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.
variant_id	The ID of the variant the retailer bought.
quantity	The number of physical items the retailer purchased.
sku	The SKU of the variant when the order was created. This may not match the current SKU of the variant.
price.amount_minor	The amount of money for the wholesale price in the smallest unit of the applicable currency. For example, 1000 cents for $10.00.
price.currency	The type of currency for the wholesale price in ISO 4217 format. For example, US dollars is USD.
product_name	The name of the product when it was purchased.
variant_name	The name of the variant when it was purchased.
includes_tester	A boolean indicating whether or not a tester for the variant was purchased.
tester_price.amount_minor	If includes_tester is true, The amount of money for the wholesale price in the smallest unit of the applicable currency. For example, 1000 cents for $10.00.
tester_price.currency	If includes_tester is true, the type of currency for the tester price in ISO 4217 format. For example, US dollars is USD.
created_at	An ISO 8601 timestamp of when the order was created.
updated_at	An ISO 8601 timestamp of when the order was last updated.
discounts	A list of any product-specific promotions that were applied to this item. Does not include shop-wide promotions, which can be found under the order's brand_discounts field.
price_cents	Deprecated - use price instead. The wholesale price of the product at the time it was purchased, in USD cents.
tester_price_cents	Deprecated - use tester_price instead. If includes_tester is true, the price of the tester in USD cents.

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": "2019-03-15T00:10:00.000Z"
    }
  }
}

HTTP Request

POST https://www.faire.com/external-api/v2/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 variant.

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 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": "2019-03-15T00:09:15.000Z",
  "updated_at": "2019-03-15T00:09:15.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 timestamp of when the order was created.
updated_at	An ISO 8601 timestamp of when the order was last updated.

Discounts

Contains information about a promotion that's been applied to an order or order item.

A percentage discount might look like this:

{
  "id": "bpc_k3w2kb97tp",
  "code": "SUMMER10",
  "includes_free_shipping": false,
  "discount_percentage": 10,
  "discount_type": "PERCENTAGE"
}

A flat discount might look like this:

{
  "id": "bpc_cjpyaf56ts",
  "code": "STOCK_UP",
  "includes_free_shipping": false,
  "discount_amount": {
    "amount_minor": 2000,
    "currency": "USD"
  },
  "discount_type": "FLAT_AMOUNT"
}

A free shipping promotion might look like this:

{
  "id": "bpc_bj6sgz7yzu",
  "code": "FREE_SHIP",
  "includes_free_shipping": true,
  "discount_type": "NONE"
}

Field	Description
id	A unique identifier for the order, beginning with "bpc_".
code	The name of the promotion as it appears to retailers at checkout.
discount_type	This is PERCENTAGE, FLAT_AMOUNT, or NONE depending on how the discount is calculated. A discount of type NONE means that this discount affected something other than the purchase price, such as free shipping or duties.
includes_free_shipping	Whether this promotion is for free shipping.
discount_amount.amount_minor	The amount of money for the discount in the smallest unit of the applicable currency. For example, 1000 cents for $10.00. This value is present only when the discount_type is FLAT_AMOUNT.
discount_amount.currency	The type of currency for the discount in ISO 4217 format. For example, US dollars is USD. This value is present only when the discount_type is FLAT_AMOUNT.
discount_percentage	The discount amount as a percent of the total. This value is present only when the discount_type is PERCENTAGE.

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/external-api/v2/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/external-api/v2/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-2 subdivision code. This is typically 2 letters to represent the state or province.
phone_number	The E.164 formatted phone number used to contact the recipient.
country	The full name of the country.
country_code	The ISO 3166 alpha-3 country code.
company_name	The name of the company at this address.

Payout Costs

Contains information about how the payout amount for an order was calculated.

A sample payout costs object might look like:

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

  "payout_fee": {
    "amount_minor" : 2100,
    "currency": "USD"
  },
  "commission": {
    "amount_minor" : 10500,
    "currency": "USD"
  },
  "payout_protection_fee": {
    "amount_minor" : 1050,
    "currency": "USD"
  },
  "damaged_and_missing_items" : {
    "amount_minor" : 0,
    "currency": "USD"
  },
  "net_tax": {
    "amount_minor" : 0,
    "currency": "USD"
  },
  "total_payout": {
    "amount_minor" : 56350,
    "currency": "USD"
  }
}

Field	Description
payout_fee	The amount charged to the brand to pay out the order (e.g. for next-day ACH transfers).
payout_fee_cents	Deprecated. This is the same as payout_fee but is only for USD. Prefer that field.
payout_fee_bps	The payout fee basis points used to calculate the payout fee (e.g. 300 is 3%).
commission	The amount of commission charged to the brand for the order.
commission_cents	Deprecated. This is the same as commission but is only for USD. Prefer that field.
commission_bps	The commission basis points used to calculate the commission (e.g. 1500 is 15%).
payout_protection_fee	The amount charged to the brand for the Faire shipping protection program, if the brand is a participant.
damaged_and_missing_items	The amount deducted for any items reported missing or damaged in shipping.
shipping_subsidy	The amount charged to the brand for the free shipping partnership program, if the brand is a participant.
net_tax	The amount of tax charged to the retailer and included in the payout.
total_payout	The amount paid out to the brand after all fees and deductions.

Images

Contains information about the image. Typically used in products/variants.

A sample image might look like:

{
        "id": "i_7oey1vb9bm",
        "width": 1000,
        "height": 1000,
        "sequence": 0,
        "url": "https://cdn.faire.com/53105976.png",
        "tags": [
            "Hero"
        ]
}

Field	Description
id	READ-ONLY The unique identifier of the image, beginning with "i_".
width	READ-ONLY The width of the image in pixels.
height	READ-ONLY The height of the image in pixels.
sequence	The ordering to display the image when it is part of a collection of images.
url	The URL for the image file. When provided as an input, Faire will attempt to download the image and host it on the Faire CDN. If it fails to download, Faire will attempt to serve the original image URL.
tags	A distinct list of tags associated with this image

Product State Management

Sale State

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

sale_state can be one of 2 values:

• FOR_SALE
• SALES_PAUSED

Comparison of sale states:

sale_state	Visible to Makers	Visible to Retailers	Purchasable
FOR_SALE	Yes	Yes	Yes
SALES_PAUSED	Yes	Yes	No

Faire systems automatically move products and variants between the sale states.

Lifecycle State

This field represents the current lifecycle stage of a product or variant on Faire.

lifecycle_state can be one of 4 values:

• DRAFT
• PUBLISHED
• UNPUBLISHED
• DELETED

Draft products do not need to have required fields (e.g. prices, case size) populated or validated, and are not visible to retailers. While UNPUBLISHED products are also not visible to retailers, they have all fields validated.

When changing the state of a product or variant to PUBLISHED, it must have all its required fields populated including having at least one image.

Comparison of lifecycle states:

lifecycle_state	Enforces validation	Visible to Makers	Visible to Retailers
DRAFT	No	Yes	No
PUBLISHED	Yes	Yes	Yes
UNPUBLISHED	Yes	Yes	No
DELETED	No	No	No

Detailed Technical Explanation

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

Faire UI

Via Faire’s UI, brands can create DRAFT products, and save the product without validating fields. If all the required fields are populated and valid, the brand can then publish the draft product, which sets the lifecycle_state to PUBLISHED. At this point, products can no longer be set to DRAFT with the Faire UI. However, brands can now toggle the lifecycle_state between PUBLISHED or UNPUBLISHED at any time.

Faire Automated Systems

Product Variants

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

• The variant has backordered_until set.
  • (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 variant’s available_quantity is less than either:
  • the product’s minimum_order_quantity
  • the product’s unit_multiplier

The variant 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 variants under the product are either SALES_PAUSED
• If any option is FOR_SALE, the product will remain FOR_SALE.
• Faire will automatically set a PUBLISHED product to UNPUBLISHED if at any point all the variants are UNPUBLISHED.
  • This is not an automatically reversible change.
• Faire will never set a UNPUBLISHED product or variant to PUBLISHED.

Preorders

When a preorder product reaches the "Order by Date" or "Expected Ship Date", it will move to UNPUBLISHED.

Idempotency

An idempotent operation can be applied multiple times without changing the result. Many of Faire's APIs have a mechanism to allow for idempotent operations.

Imagine you are trying to create a product and then the network connection fails after we create the product in Faire, but before we can return the results to you. You see it as a failure and might try to create the product again. Without idempotent operations, there are now 2 duplicate products in Faire!

The Faire APIs require an idempotency_token when creating new objects in our system. This token can be any string of characters and should be unique to the object you are creating. With the idempotency token, you can retry failed requests without risk of duplicating data in our system.

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

• Added several fields to payout costs

2022-11

• Added brand_discounts field to orders and discounts to order items

2022-10-14

• Update product variant pricing geo constraint country and country_group restraints

2021-04-26

• Added support for open pack products via per_style_minimum_order_quantity

2021-04-14

• Added support for geographic pricing for product variations.
• Deprecated retailer_price_cents and wholesale_price_cents

2021-04-07

• Adjusted the maximum length of product short_description and description to match with brand portal

2021-03-17

• Fixed incorrect unit_multiplier and minimum_order_quantity values in sample requests and responses under product endpoints
• Added missing request parameter minimum_order_quantity to create and patch product endpoints

2021-03-15

• added preorder details in create and patch product endpoints

2021-03-10

• We noticed prepacks shouldn't have any images, and we removed the field image from all requests and responses under that section.

2021-03-01

• External API V2 was released