NAV

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

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

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

{
  "access_token": "OAUTH_ACCESS_TOKEN",
  "token_type": "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",
  "gtin": "12345670",
  "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.
gtin A Global Trade Item Number (GTIN) that identifies the product variant. GTINs are issued by the global trade organization GS1 and must pass three validation checks: 1) they must be either 8, 12, 13, or 14 digits long, 2) they must be composed of only numeric digits, and 3) the last digit must match a computed check digit. For more information, see the Faire Help Center.
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 Deprecated. The number of units available to sell, calculated by (on hand - committed). To fetch all inventory types and update on hand inventory, see product variant inventory
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",
  "gtin": "12345670",
  "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
gtin A Global Trade Item Number (GTIN) that identifies the product variant. GTINs are issued by the global trade organization GS1 and must pass three validation checks: 1) they must be either 8, 12, 13, or 14 digits long, 2) they must be composed of only numeric digits, and 3) the last digit must match a computed check digit. For more information, see the Faire Help Center. 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",
  "gtin": "12345670",
  "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
gtin A Global Trade Item Number (GTIN) that identifies the product variant. GTINs are issued by the global trade organization GS1 and must pass three validation checks: 1) they must be either 8, 12, 13, or 14 digits long, 2) they must be composed of only numeric digits, and 3) the last digit must match a computed check digit. For more information, see the Faire Help Center. 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 (deprecated)

This endpoint is deprecated. Please use the endpoints in the product variant inventory section to update inventory instead.

This endpoint updates variant available 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. available_quantity is a read-only value, calculated as (on hand - committed). This request sets the available_quantity by performing an update to on-hand inventory. The new on-hand inventory is calculated using the current committed inventory and new available_quantity. 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 (deprecated)

This endpoint is deprecated. Please use the endpoints in the product variant inventory section to update inventory instead.

This endpoint updates variant available 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. available_quantity is a read-only value, calculated as (on hand - committed). This request sets the available_quantity by performing an update to on-hand inventory. The new on-hand inventory is calculated using the current committed inventory and new available_quantity. 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 Inventory

Every product variant on Faire has three types of inventory.

Field Description Brand updated Faire updated Read-only
On hand The total number of units that are in stock. Yes Yes No
Committed The number of units that are already allocated to orders No Yes Yes
Available The number of units that are available to sell. This field is calculated by (on hand - committed). No No Yes

Inventory for a variant may be tracked or untracked.

If the on-hand units are set as a whole number, inventory is tracked and available units will be calculated as (on hand - committed). 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).

If the on-hand units are not set, inventory is untracked. In this case, the available units are also untracked and the variant will be purchasable regardless of the number of committed units.

For more information about managing inventory from the Faire brand portal, refer to this help center article.

Sample product variant inventory levels might look like:

{
  "on_hand_quantity": {
    "type": "QUANTITY",
    "quantity": 17
  },
  "committed_quantity": {
    "type": "QUANTITY",
    "quantity": 11
  },
  "available_quantity": {
    "type": "QUANTITY",
    "quantity": 6
  }
}

Get inventory by variant IDs

This endpoint fetches inventory levels by given product variant IDs. A sample request might look like:

https://www.faire.com/external-api/v2/product-inventory/by-product-variant-ids?ids=po_123&ids=po_567

HTTP Request

GET https://www.faire.com/external-api/v2/product-inventory/by-product-variant-ids

Query Parameters

Field Description
ids A list of ids for the product variants to fetch. The id is a unique identifier starting with "po_".

Response

This endpoint returns JSON structured like:

{
  "po_123": {
    "on_hand_quantity": {
      "type": "QUANTITY",
      "quantity": 22
    },
    "committed_quantity": {
      "type": "QUANTITY",
      "quantity": 4
    },
    "available_quantity": {
      "type": "QUANTITY",
      "quantity": 18
    }
  },
  "po_456": {
    "on_hand_quantity": {
      "type": "UNTRACKED",
      "quantity": null
    },
    "committed_quantity": {
      "type": "QUANTITY",
      "quantity": 1
    },
    "available_quantity": {
      "type": "UNTRACKED",
      "quantity": null
    }
  }
}

Get inventory by SKU

This endpoint fetches inventory levels by given product variant SKUs. A sample request might look like:

https://www.faire.com/external-api/v2/product-inventory/by-skus?skus=SKU1&skus=SKU2

HTTP Request

GET https://www.faire.com/external-api/v2/product-inventory/by-skus

Query Parameters

Field Description
skus A list of SKUs for the product variants to fetch.

Response

This endpoint returns JSON structured like:

{
  "vanilla-2019": {
    "on_hand_quantity": {
      "type": "QUANTITY",
      "quantity": 22
    },
    "committed_quantity": {
      "type": "QUANTITY",
      "quantity": 4
    },
    "available_quantity": {
      "type": "QUANTITY",
      "quantity": 18
    }
  },
  "cinnamon-2019": {
    "on_hand_quantity": {
      "type": "UNTRACKED",
      "quantity": null
    },
    "committed_quantity": {
      "type": "QUANTITY",
      "quantity": 1
    },
    "available_quantity": {
      "type": "UNTRACKED",
      "quantity": null
    }
  }
}

Update inventory by variant IDs

This endpoint updates on hand inventory levels by given product variant IDs.

{
  "inventories": [
    {
      "product_variant_id": "po_123",
      "on_hand_quantity": 10
    },
    {
      "product_variant_id": "po_456",
      "on_hand_quantity": 20
    },
    {
      "product_variant_id": "po_789",
      "on_hand_quantity": null
    }
  ]
}

HTTP Request

PATCH https://www.faire.com/external-api/v2/product-inventory/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.on_hand_quantity The quantity to set on_hand_quantity to, must be null or a whole number. If the value is null, this will remove inventory tracking and disable inventory tracking features. Optional

Response

This endpoint returns JSON structured like:

{
  "po_123": {
    "on_hand_quantity": {
      "type": "QUANTITY",
      "quantity": 10
    },
    "committed_quantity": {
      "type": "QUANTITY",
      "quantity": 2
    },
    "available_quantity": {
      "type": "QUANTITY",
      "quantity": 8
    }
  },
  "po_456": {
    "on_hand_quantity": {
      "type": "QUANTITY",
      "quantity": 20
    },
    "committed_quantity": {
      "type": "QUANTITY",
      "quantity": 5
    },
    "available_quantity": {
      "type": "QUANTITY",
      "quantity": 15
    }
  },
  "po_789": {
    "on_hand_quantity": {
      "type": "UNTRACKED",
      "quantity": null
    },
    "committed_quantity": {
      "type": "QUANTITY",
      "quantity": 10
    },
    "available_quantity": {
      "type": "UNTRACKED",
      "quantity": null
    }
  }
}

Update inventory by SKUs

This endpoint updates variant inventory levels by given variant SKUs.

{
  "inventories": [
    {
      "sku": "vanilla-2019",
      "on_hand_quantity": 10
    },
    {
      "sku": "cinnamon-2019",
      "on_hand_quantity": 20
    },
    {
      "sku": "chocolate-2019",
      "on_hand_quantity": 20
    }
  ]
}

HTTP Request

PATCH https://www.faire.com/external-api/v2/product-inventory/by-skus

Request Parameters

Field Description Required
inventories.sku Matches the most recently created product variant with that SKU. Required
inventories.on_hand_quantity The quantity to set on_hand_quantity to, must be null or a whole number. If the value is null, this will remove inventory tracking and disable inventory tracking features. Optional

Response

This endpoint returns JSON structured like:

{
  "vanilla-2019": {
    "on_hand_quantity": {
      "type": "QUANTITY",
      "quantity": 10
    },
    "committed_quantity": {
      "type": "QUANTITY",
      "quantity": 2
    },
    "available_quantity": {
      "type": "QUANTITY",
      "quantity": 8
    }
  },
  "cinnamon-2019": {
    "on_hand_quantity": {
      "type": "QUANTITY",
      "quantity": 20
    },
    "committed_quantity": {
      "type": "QUANTITY",
      "quantity": 5
    },
    "available_quantity": {
      "type": "QUANTITY",
      "quantity": 15
    }
  },
  "chocolate-2019": {
    "on_hand_quantity": {
      "type": "UNTRACKED",
      "quantity": null
    },
    "committed_quantity": {
      "type": "QUANTITY",
      "quantity": 10
    },
    "available_quantity": {
      "type": "UNTRACKED",
      "quantity": null
    }
  }
}

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.

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:

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

Products

Preorders

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

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.

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.

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",
  "is_free_shipping": true,
  "free_shipping_reason": "INSIDER_FREE_SHIPPING",
  "faire_covered_shipping_cost": 2300,
  "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",
      "shipping_type": "SHIP_ON_YOUR_OWN",
    }
  ],
  "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,
    "subtotal_after_brand_discounts": {
      "amount_minor": 9450,
      "currency": "USD"
    },
    "total_brand_discounts": {
      "amount_minor": 1050,
      "currency": "USD"
    }
  },
  "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",
    }
  ],
  "estimated_payout_at": "2019-03-16T00:00:00.000Z"
}
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
is_free_shipping True if the order has free shipping, false otherwise
free_shipping_reason The reason the order has free shipping, if any. See free shipping reason for more information.
faire_covered_shipping_cost The amount of the total shipping cost Faire is paying for, if applicable.
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.
estimated_payout_at An ISO 8601 timestamp of when Faire expects to pay the brand for the order. Note that this is not a guarantee of when the order will be paid out.

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.

Free Shipping Reasons

Reason Description
INSIDER_FREE_SHIPPING The order has Insider free shipping.
FAIRE_DIRECT The free shipping is due to a Faire Direct relationship.
BRAND_DISCOUNT The free shipping is due to a brand discount.
FIRST_ORDER The free shipping is due to this order being eligible for the first order promo for the retailer.
PROMO_CODE The free shipping is due to a Promo Code being used.
FREE_SHIPPING_THRESHOLD The free shipping is due to the order meeting the brand-set Free Shipping threshold.

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",
  "shipping_type": "SHIP_WITH_FAIRE"
}
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.
shipping_type The type of shipping selected for this shipment. Currently this can be either SHIP_ON_YOUR_OWN or SHIP_WITH_FAIRE.

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",
        "address_type": "RESIDENTIAL"
}
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.
address_type READ-ONLY The type of address. Values include: RESIDENTIAL, COMMERCIAL and MIXED. This is populated in a best-effort manner. It could be null if we were not able to catagorize the 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"
  },
  "subtotal_after_brand_discounts": {
    "amount_minor": 9450,
    "currency": "USD"
  },
  "total_brand_discounts": {
    "amount_minor": 1050,
    "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.
subtotal_after_brand_discounts.amount_minor The order subtotal after applying shop-wide discounts and product-specific discounts relevant to this order in the smallest unit of the applicable currency. For example, 1000 cents for $10.00.
subtotal_after_brand_discounts.currency The type of currency for the subtotal in ISO 4217 format. For example, US dollars is USD.
total_brand_discounts.amount_minor The sum of all the shop-wide and product-specific discounts applied to this order in the smallest unit of the applicable currency. For example, 1000 cents for $10.00.
total_brand_discounts.currency The type of currency for the total discounts in ISO 4217 format. For example, US dollars is USD.

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.

  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:

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

2025-06

2024-11

2024-09

2024-05

2024-03

2023-06

2023-05

2023-04

2023-03

2023-02

2023-01

2022-11

2022-10-14

2021-04-26

2021-04-14

2021-04-07

2021-03-17

2021-03-15

2021-03-10

2021-03-01