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.

Using OAuth

OAuth is the recommended authorization process for accessing Faire's External API. However, if you are a single brand seeking access to Faire's APIs, we suggest generating the access token yourself in the Brand Portal. For integration partners with multiple brands, we recommend utilizing OAuth for authorization.

OAuth

OAuth (in this case OAuth 2.0) which stands for “Open Authorization”, is a standard designed to allow a website or application to access resources hosted by other web apps on behalf of a user.
The Faire OAuth API lets applications request and obtain permissions from a Faire account to make API calls on behalf of that account. By using OAuth, applications are able to receive an access token without relying on the Faire user to provide it to them.

Authorization Code

Faire uses an "Authorization Code Grant" flow where external partner applications obtain an authorization code that is then redeemed to get an access token. This token can then be used for authorization when calling Faire APIs.

To start the flow, navigate the Faire user to the OAuth authorization page. On this page, the user is able to view a list of permissions that your application is trying to obtain. If the user decides to authorize the application, an authorization code is returned. If the user does not authorize the application, the user is redirected back to your website.

OAuth permission URL

To access the authorization page, the user needs to be redirected to a URL of the following format: https://faire.com/oauth2/authorize?applicationId={YOUR_APP_ID}&scope=SPECIFIC_PERMISSION&state=82201dd8d83d23cc8a48caf52&redirectUrl=https://example.com.

Query String Parameters

All the required parameters are provided in the form of a query string. Below, you can find a detailed description of all the parameters that you need to build the OAuth permission URL:

Field	Description	Required
applicationId string	The identifier that is assigned to your application. You can find it in the Developer Portal.	Yes
scope string[]	A list of the permissions that your application requests. For more information on permissions, refer to the section below.	Yes
state string	This parameter serves as a CSRF protection mechanism. When the user gets redirected back, you can verify that the state value matches what it was set originally.	Yes
redirectUrl string	This is the URL to which the Faire user will be redirected to after the authorization is complete.	Yes

Permissions

Applications must provide a list of specific permissions that they want to access from Faire user. Below you can find the list of different permissions that you can specify:

State	Description
READ_PRODUCTS	Fetch product information.
WRITE_PRODUCTS	Add, update, or delete product information.
READ_ORDERS	Fetch order information.
WRITE_ORDERS	Add, update, or delete order information.
READ_BRAND	Fetch brand information.
READ_RETAILER	Fetch retailer information.
READ_INVENTORIES	Fetch inventory information.
WRITE_INVENTORIES	Add, update, or delete inventory information.
READ_SHIPMENTS	Fetch shipments information.

Response

Once the Faire user authorizes the application, the authorizationCode and state are passed in as query parameters in the provided redirectUrl.

**Keep in mind that the *authorization code expires within 10 minutes. If you do not exchange it for the token within the allotted time, you will need to start the flow over again.*

Access Token

As mentioned above, once you receive an authorization code you can exchange it for an OAuth access token. Use the access token to make authorized requests on behalf of the Faire user.

Sample request:

{
  "application_token": "YOUR_APP_ID",
  "application_secret": "YOUR_APP_SECRET",
  "redirect_url": "YOUR_REDIRECT_URL",
  "scope": ["PERMISSION_1", "PERMISSION_2"],
  "grant_type": "AUTHORIZATION_CODE",
  "authorization_code": "YOUR_CODE"
}

HTTP Request

POST https://www.faire.com/api/external-api-oauth2/token

Request Parameters

Field	Description	Required
applicationId	The identifier that is assigned to your application. You can access it in the Developer Portal.	Yes
applicationSecret	The secret identifier that is assigned to your application. You can access it in the Developer Portal. Please make sure to keep this data private and do not share it with other parties.	Yes
scope	A list of the permissions that your application requests. This list must match the previously provided scope parameter.	Yes
grantType	The grant identifier. In this iteration of OAuth, you would need to set it to AUTHORIZATION_CODE.	Yes
redirectUrl	This is the URL which you provided earlier. This url must match the previously provided redirect url.	Yes
authorizationCode	This is the authorization code which you were able to receive earlier.	Yes

Response

Sample response

{
  "accessToken": "OAUTH_ACCESS_TOKEN",
  "tokenType": "BEARER"
}

Using OAuth Access Token

A major difference between OAuth tokens and the access tokens used for V1 and V2 of the Faire External Api is that OAuth access tokens are used only for authorization, not authentication. In order to make requests you would need to use the following headers: Header | Description | Required ----- | ----------- | ----------- X-FAIRE-APP-CREDENTIALS| The applicationId:applicationSecret encoded in the Base64 format. | Yes X-FAIRE-OAUTH-ACCESS-TOKEN | The OAuth access token. | Yes

Only by using these two headers together, you are able to make requests and access resources at Faire.

Please note that OAuth is only enabled for External Api V2+ - you cannot send External V1 requests using OAuth access tokens.

Revoking OAuth Access Token

If by any chance you lose any confidential information about the application, you can easily revoke the OAuth access token to prevent it from being used by some other party. To do this you can make the POST request to the following endpoint \revoke

Sample request:

{
  "application_token": "YOUR_APP_ID",
  "application_secret": "YOUR_APP_SECRET",
  "access_token_o_auth": "YOUR_TOKEN"
}

HTTP Request

POST https://www.faire.com/api/external-api-oauth2/revoke

Request Parameters

Field	Description	Required
applicationToken	The identifier that is assigned to your application. You can access it in the Developer Portal.	Yes
applicationSecret	The secret identifier that is assigned to your application. You can access it in the Developer Portal. Please make sure to keep this data private and do not share it with other parties.	Yes
accessTokenOAuth	This is the OAuth token that you want to get revoked.	Yes

Response

Sample response

{
  "success": "true"
}

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 number of units of this product that can be ordered for the same "style". A "style" is defined as the set of option values for a variant, excluding the "Size" option. A product without a "Size" option cannot use per_style_minimum_order_quantity. When setting per_style_minimum_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 10-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.
cursor	null	A value used to paginate through products, which is an alternative to pagination using page. The value to be passed for this is returned in a previous response. When cursor is passed, updated_at_min, sku, and include_deleted must not be passed. When there are no more products to paginate, a response will not contain a value for cursor.

Pagination

This endpoint provides two pagination options: offset pagination using page, and cursor pagination using cursor.

For offset pagination, clients can request a specific page by passing in the page query parameter.

For cursor pagination, clients can pass the value returned for cursor in a previous response for the query parameter cursor in subsequent requests.

When requesting the first set of products, a cursor is always returned if there are products left to paginate. However, if offset pagination is used for future requests by specifying a page greater than 1, a cursor will not be returned.

Response

This endpoint returns JSON structured like:

{
  "page": 1,
  "limit": 50,
  "cursor": "eyJxdWVyeV9wYXJhbXMiOnsiaW5jbHVkZV9kZWxldGVkIjpmYWxzZX0sInVwZGF0ZWRfYXRfbWluIjoiMjAyMy0wNC0xOVQyMTowMTo1NS4wMDBaIiwidXBkYXRlZF9hdF9taW5fdG9rZW4iOnsidG9rZW5fdHlwZSI6IlBST0RVQ1QiLCJpZCI6InBfenNiOWZwejg5cCJ9fQ==",
  "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",
      "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 number of units of this product that can be ordered for the same "style". A "style" is defined as the set of option values for a variant, excluding the "Size" option. A product without a "Size" option cannot use per_style_minimum_order_quantity. When setting per_style_minimum_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 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

Delete image from product

Removes an image from a product. To remove images from a variant, see Delete image from variant

Published products need at least one image. If you try to remove the last image, this endpoint returns 400 Bad Request.

HTTP Request

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

Path Parameters

Parameter	Description
PRODUCT_ID	The ID of the product to be updated.
IMAGE_ID	The ID of the image to be removed.

Response

204 NO_CONTENT

Update product's variant option sets

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

If the product is sold in prepacks, size options cannot be reorganized and new values cannot be inserted into the middle of the 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"]
    }
  ],
  "measurements": {
    "mass_unit": "GRAMS",
    "weight": 85.4,
    "distance_unit": "CENTIMETERS",
    "length": 8.5,
    "width": 8.0,
    "height": 10.0
  }
}

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.
tariff_code	The HS6 Tariff Code for the variant. If no tariff code is provided when the variant is created, Faire may automatically pick one.
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.
measurements	Contains information about the product variant's weight and dimensions. See Measurements for more information.

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"]
    }
  ],
  "measurements": {
    "mass_unit": "GRAMS",
    "weight": 85.4,
    "distance_unit": "CENTIMETERS",
    "length": 8.5,
    "width": 8.0,
    "height": 10.0
  }
}

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
measurements	Contains information about the product variant's weight and dimensions. See Measurements for more information.	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"]
    }
  ],
  "measurements": {
    "mass_unit": "GRAMS",
    "weight": 85.4,
    "distance_unit": "CENTIMETERS",
    "length": 8.5,
    "width": 8.0,
    "height": 10.0
  }
}

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"]
    }
  ],
  "measurements": {
    "mass_unit": "GRAMS",
    "weight": 85.4
  }
}

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
measurements	Contains information about the product variant's weight and dimensions. If measurements is non-null, it will overwrite all previous measurements. For example, if a variant has length and distance_unit set, and you update this variant with a measurements object containing only weight and mass_unit, the length and distance_unit fields will be set to null. See Measurements for more information.	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"]
    }
  ],
  "measurements": {
    "mass_unit": "GRAMS",
    "weight": 85.4
  }
}

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

Delete image from variant

Removes an image from a variant.

HTTP Request

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

Path Parameters

Parameter	Description
PRODUCT_ID	The ID of the product to be updated.
VARIANT_ID	The ID of the variant to be updated.
IMAGE_ID	The ID of the image to be removed.

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"
        }
      ],
      "measurements": {
        "mass_unit": "GRAMS",
        "weight": 85.4,
        "distance_unit": "CENTIMETERS",
        "length": 8.5,
        "width": 8.0,
        "height": 10.0
      }
    },
    {
      "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"
        }
      ],
      "measurements": {
        "mass_unit": "GRAMS",
        "weight": 90.2,
        "distance_unit": "CENTIMETERS",
        "length": 9.0,
        "width": 8.0,
        "height": 10.0
      }
    }
  ]
}

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"
        }
      ],
      "measurements": {
        "mass_unit": "GRAMS",
        "weight": 85.4,
        "distance_unit": "CENTIMETERS",
        "length": 8.5,
        "width": 8.0,
        "height": 10.0
      }
    },
    {
      "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"
        }
      ],
      "measurements": {
        "mass_unit": "GRAMS",
        "weight": 90.2,
        "distance_unit": "CENTIMETERS",
        "length": 9.0,
        "width": 8.0,
        "height": 10.0
      }
    }
  ]
}

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,
      "created_at": "2019-03-14T00:09:15.000Z",
      "updated_at": "2020-02-13T00:09:16.000Z"
    },
    {
      "id": "pci_567",
      "variant_id": "po_4r5e",
      "quantity": 1,
      "created_at": "2019-03-14T00:09:15.000Z",
      "updated_at": "2020-02-13T00:09:16.000Z"
    },  
    {
      "id": "pci_890",
      "variant_id": "po_8ash",
      "quantity": 2,
      "created_at": "2019-03-14T00:09:15.000Z",
      "updated_at": "2020-02-13T00:09:16.000Z"
    }    
  ],
  "created_at": "2019-03-14T00:09:15.000Z",
  "updated_at": "2020-02-13T00:09:16.000Z"
}

Field	Description
id	READ-ONLY 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	READ-ONLY An ISO 8601 timestamp of when the prepack was created.
updated_at	READ-ONLY An ISO 8601 timestamp of when the prepack was most recently updated.

Prepack Items

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

Field	Description
id	READ-ONLY 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.
created_at	READ-ONLY An ISO 8601 timestamp of when the item was created.
updated_at	READ-ONLY An ISO 8601 timestamp of when the item was most recently updated.

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

Add Multiple Prepacks to a Product

This endpoint adds multiple prepacks to an existing product:

{
  "prepacks": [
    {
      "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
        }    
      ]
    },
    {
      "idempotence_token": "df4werwef",
      "name": "My Red Shirt Prepack",
      "items": [
        {
          "variant_id": "po_d2d1",
          "quantity": 2
        },
        {
          "variant_id": "po_4r5e",
          "quantity": 2
        },  
        {
          "variant_id": "po_8ash",
          "quantity": 2
        }
      ]
    }
  ]
}

HTTP Request

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

Path Parameters

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

Prepacks Batch Request Parameters

Parameter	Description	Required
prepacks	A list of prepacks to create for the product. The maximum number of prepacks that can be created in a single request is 20.	Required

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

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.
PENDING_RETAILER_CONFIRMATION	The brand did not have sufficient quantity to fulfill the order; the retailer needs to decide whether they want to wait till the items are back in stock, or cancel.
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.

Cancel Reasons

State	Description
REQUESTED_BY_RETAILER	The retailer asked to cancel the order.
RETAILER_NOT_GOOD_FIT	The retailer isn’t a good fit for the brand.
CHANGE_REPLACE_ORDER	The retailer wants to modify or replace the order.
ITEM_OUT_OF_STOCK	Item(s) in the order are out of stock.
INCORRECT_PRICING	Item(s) in the order are incorrectly priced.
ORDER_TOO_SMALL	The order is too small.
REJECT_INTERNATIONAL_ORDER	The brand doesn't sell in retailer's country.
OTHER	Any other reason.

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,
  "cursor": "eyJxdWVyeV9wYXJhbXMiOnsiZXhjbHVkZWRfc3RhdGVzIjpbXX0sInVwZGF0ZWRfYXRfbWluIjoiMjAyMi0xMS0wN1QxODowOTo0Mi4wMDBaIiwidXBkYXRlZF9hdF9taW5fdG9rZW4iOnsidG9rZW5fdHlwZSI6IkJSQU5EX09SREVSIiwiaWQiOiJib18xZDB6ZjNmamhkIn19",
  "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.
cursor	null	A value used to paginate through orders, which is an alternative to pagination using page. The value to be passed for this is returned in a previous response. When cursor is passed, updated_at_min, created_at_min, excluded_states and ship_after_max must not be passed. When there are no more orders to paginate, a response will not contain a value for cursor.

Pagination

This endpoint provides two pagination options: offset pagination using page, and cursor pagination using cursor.

For offset pagination, clients can request a specific page by passing in the page query parameter.

For cursor pagination, clients can pass the value returned for cursor in a previous response for the query parameter cursor in subsequent requests.

When requesting the first set of orders, a cursor is always returned if there are orders left to paginate. However, if offset pagination is used for future requests by specifying a page greater than 1, a cursor will not be returned.

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.

Cancel an Order

This endpoint cancels an order and places it in the state CANCELED. The order can be canceled only if it has a state of NEW, PROCESSING, PENDING_RETAILER_CONFIRMATION or BACKORDERED.

A sample request might look like:

{
  "reason": "ITEM_OUT_OF_STOCK",
  "note": "I had to cancel your order because an item in your order is out of stock."
}

HTTP Request

PUT https://www.faire.com/external-api/v2/orders/<ID>/cancel

Path Parameters

Parameter	Description
ID	The ID of the order to cancel.

Request Body Fields

Parameter	Description	Required
reason	The reason for canceling the order.	Required
note	A note explaining to the retailer why their order was canceled. The note must be between 30 and 1000 characters long.	Required

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",
  "state": "DELIVERED",
  "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.
state	The current state of the order item.
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.

Order Item States

More states may be added in the future.

State	Description
PROCESSING	The order has been placed.
PRE_TRANSIT	A shipment has been created for this item's order.
IN_TRANSIT	This item has been shipped. The state may be IN_TRANSIT even if this particular item hasn't been shipped yet, if another item from the same order has been.
DELIVERED	This item has been delivered.
RETURNED	The item was delivered but the retailer decided to return it.
PENDING_RETAILER_CONFIRMATION	The brand did not have sufficient quantity to fulfill the order; the retailer needs to decide whether they want to wait till the items are back in stock, or cancel.
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.
DAMAGED_OR_MISSING	The item was reported as damaged upon delivery or missing from the shipment.

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. Currently, the accepted values are CANADA_POST, DHL_ECOMMERCE, DHL_EXPRESS, FEDEX, PUROLATOR, UPS, USPS, POSTNL, CANPAR, INTERLINK_EXPRESS, GSO, ROYAL_MAIL, DPD, DPDUK, PARCELFORCE, AUSTRALIA_POST, EVRI, and LA_POSTE. These values are case insensitive. If another string is entered for this field, Faire will do its best to produce tracking information for that carrier, but may not succeed. Any string up to 255 characters long is considered valid in a request, but strings not matching the accepted values above will not be included in any response.
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:

{
        "id": "a_sd0f9sid0f",
        "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
id	READ-ONLY A unique identifier for the address, beginning with "a_".
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,
  "payout_flat_fee": {
    "amount_minor" : 30,
    "currency": "USD"
  },
  "commission_cents": 10500,
  "commission_bps": 1500,
  "commission_flat_fee": {
    "amount_minor" : 1000,
    "currency": "USD"
  },

  "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"
  },
  "taxes": [],
  "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). (item subtotal x payout_fee_bps + payout_flat_fee)
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%).
payout_flat_fee	The payout flat fee amount charged in addition to payout_fee_bps
commission	The amount of commission charged to the brand for the order. (item subtotal x commission_bps + commission_flat_fee)
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%).
commission_flat_fee	The commission flat fee amount (showing up as "New customer fee" in Faire brand portal) charged in addition to commission_bps
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.
taxes	A list of the individual taxes that make up net_tax.
total_payout	The amount paid out to the brand after all fees and deductions.

Taxes

These are the individual taxes that make up net_tax.

A sample tax object might look like:

{ 
  "value": {
    "amount_minor": 999,
    "currency": "EUR"
  },
  "taxable_item_type": "ORDER_ITEM",
  "tax_type": "VAT",
  "effect": "INCREASES_PAYOUT"
}

Field	Description
value	The amount of money.
taxable_item_type	The item to which this tax applies. The possible values are currently ORDER_ITEM and SHIPPING. *
tax_type	The type of tax being applied. The possible values are currently VAT, GST, HST, PST, IMPORT_VAT, AUSTRALIA_GST, and RECARGO. *
effect	Whether the value of this tax increases or decreases the payout. The possible values are currently INCREASES_PAYOUT and DEDUCTED_FROM_PAYOUT. *

* Other values may be added in the future, so make sure the implementation of your integration follows best practices when handling these fields.

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

Upload an image

We recommend uploading images to Faire before attempting to use them for a product or variant. This provides you with immediate feedback on whether the image is valid and accessible.

Recommended flow

1. POST an image to this endpoint.
2. Verify that the response had a status code of 200 and included a url.
3. Store that url in your system.
4. Include the url in a subsequent request to a Create Product, Update Product, Create Variant, or Update Variant endpoint to attach the image to a product or variant. If an uploaded image spends more than one day unattached to a product or variant, it may be deleted.

A sample request might look like:

{
  "attachment": "R0lGODlhAQABAAD/ACwAAAAAAQABAAACADs="
}

HTTP Request

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

Request Parameters

Parameter	Description	Required
attachment	The image file, encoded in Base64.	Required

Response

If the request is processed successfully, this endpoint returns JSON structured like:

{
    "url": "https://cdn.faire.com/53105976.png"
}

If the response's status code is 400, there was a problem with the request; the response will include a message indicating what the problem is. These are the most likely problems:

• The request's attachment field may be missing, empty, or invalid Base64. Fix the code and try again.

• The file format may not be supported. File formats are currently limited to jpeg, png, and webp. Convert the image to one of those formats and try again.

• The image may be too tall or too wide. The current limit is 12000 pixels in each dimension. Resize the image and try again.

• The image may be too large. The current limit is 50 MiB. Compress or resize the image, or convert it to a more efficient file format.

Measurements

Contains information about a product variant's measurements, including weight and dimensions. When setting weight, fields mass_unit and weight are both required. When setting dimensions, fields distance_unit and at least one of length, width or height are required.

Sample measurements might look like:

{
  "mass_unit": "KILOGRAMS",
  "weight": 2.4,
  "distance_unit": "METERS",
  "length": 2.0,
  "width": 1.5,
  "height": 4.25
}

Field	Description
mass_unit	The unit used for weight. Accepted values include: GRAMS, KILOGRAMS, OUNCES and POUNDS.
weight	The weight of the product variant, with units specified by mass_unit.
distance_unit	The unit used for length, width and height. Accepted values include: CENTIMETERS, INCHES, FEET, MILLIMETERS, METERS and YARDS.
length	The length of the product variant, with units specified by distance_unit.
width	The width of the product variant, with units specified by distance_unit.
height	The height of the product variant, with units specified by distance_unit.

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

• Added payout_flat_fee and commission_flat_fee, updated payout_fee and commission to payout costs

2023-05

• Added OAuth flow documentation including how to create authorization codes, create access tokens and revoke access tokens.
• Added support for cursor pagination on get all orders and get all products endpoints

2023-04

• Added endpoints for removing an image from a product and removing an image from a variant.

2023-03

• Documented the PENDING_RETAILER_CONFIRMATION state for orders and order items. Orders in this state are now returned from the Get all Orders endpoint.
• Added support for creating prepacks in batches using the Add Multiple Prepacks to a Product endpoint.
• Added documentation for canceling an order using the Cancel an Order endpoint.
• Added support for uploading images to be used by products/variants.

2023-02

• Added state field to order items and documented the possible states.
• Added support for measurements for product variants.

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