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.
This is documentation for V2 of the external API. For V1, visit External API V1
Migrating from the v1 API
This section covers the breaking changes to the API we have made that you will need to update your code to support.
Breaking changes
We feel these changes will make the API more stable and easier to use going forward. We take breaking changes seriously and do not plan to have so many breaking changes in future API releases. We want to get the most painful changes out of the way as soon as possible so future API upgrades will be simple.
Changes to terminology
Our v1 API used non-standard terminology for product variant and product variant options. We used the terms product options and variations, respectively (nearly an inverse of what is used elsewhere). We have chosen to correct the terminology in the v2 API release.
Product Changes: v1 to v2
Major API changes
- Several field changes. See below.
- Preorders are part of the API! See Products.
- Prepacks are part of the API! See Prepacks.
- The batch product creation API has been removed.
- The get all product categories API has been removed.
- Product variant option names (formerly variations) cannot be changed.
- URL paths now start with
https://www.faire.com/external-api/v2
instead ofhttps://www.faire.com/api/v1
.
Product field changes
The following fields have been changed with products.
Field Name | Change Type | Details |
---|---|---|
lifecycle_state | Added | The DELETED state used to be a potential sales_state value. |
sale_state | Modified | The only values are now FOR_SALE and SALES_PAUSED . |
wholesale_price_cents | Removed | This field never really made sense. Product variants are the physical item and are often priced differently. |
retail_price_cents | Removed | This field never really made sense. Product variants are the physical item and are often priced differently. |
active | Removed | Replaced by lifecycle_state . |
deleted | Removed | Replaced by lifecycle_state . |
variant_option_sets | Renamed/Modified | Replaces variation_map . It now must be specified during product creation. The JSON structure is now an ordered list of variant options instead of an object acting as a map. |
options | Renamed | Renamed to variants . |
categories | Removed | No longer used. |
preorderable | Added | New v2 API feature. See Products. |
preorder_details | Added | New v2 API feature. See Products. |
prepacks | Added | New v2 API feature. See Prepacks. |
Variant Changes: v1 to v2
Major API changes
- Several field changes. See below.
- Product variant option values (formerly variations) cannot be changed.
Variant field changes
Field Name | Change Type | Details |
---|---|---|
lifecycle_state | Added | The DELETED state used to be a potential sale_state value. |
sale_state | Modified | The only values are now FOR_SALE and SALES_PAUSED . |
active | Removed | Replaced by lifecycle_state . |
deleted | Removed | Replaced by lifecycle_state . |
variations | Renamed/Modified | Renamed to options . |
Timestamp Format Changed: v1 to v2
In the v1 API, our timestamps were in the basic format of ISO 8601. We decided to use the extended format of ISO 8601 for all timestamps in the v2 API.
For example, "20190314T000915.000Z" in the v1 API will become "2019-03-14T00:09:15.000Z" in the v2 API.
Key Definitions
Product Definition
A product is a category of similar physical items that are differentiated by their options. An example product could be a Faire-branded sweatshirt. The sweatshirt may come in different sizes and colors. The product itself represents the kind of product, but not a specific variant.
Option Definition
An option is a variable attribute that a product has. An example might be size or color. Options are defined with an option name and several option values. A "color" option could have "red", "blue", and "yellow", for example. In this example, the option name is "color" and the option values are "red", "blue", and "yellow".
Variant Definition
A variant is a specific combination of option values. For example, for a Faire-branded sweatshirt product with "size" and "color" options, a large, red Faire-branded sweatshirt would be a variant. Variants represent an actual physical item and have pricing, unique skus, and inventory.
Products
Products are the goods that brands sell on Faire. A product can have multiple variants, differentiated by options such as size, or color.
A product is structurally defined by its option names. They define the types of variants that can exist for the product. A product with a "Size" option is structurally different from a product with both "Size" and "Color". Since the option names are a defining trait, they cannot be changed on a product. If you want to add a new option name to a product, you should delete the product and create a new one.
The option values for a product's options can be changed. They do not define the structure of the product and instead only define what variants can be created.
A product's options affect the display ordering on Faire for the variants. The ordering of the option names on the
product are used first for ordering and then the values are used secondarily for ordering. For example, if the available
options on a t-shirt are "Color":["Red", "Blue"]
and "Size":["Small", "Medium". "Large"]
, then a
large red t-shirt would appear before a medium blue t-shirt, which would appear before a
large blue t-shirt.
A sample product might look like:
{
"id": "p_123",
"idempotence_token": "4aytry2ust",
"brand_id": "b_abc",
"name": "Faire's fantastic candle",
"sale_state" : "FOR_SALE",
"lifecycle_state" : "PUBLISHED",
"short_description": "Our candles smell fantastic. Want to know how good? Read our description!",
"description": "Glad you decided to read our description! We have significantly more characters to describe to you just how good our candles smell.",
"unit_multiplier": 2,
"minimum_order_quantity": 8,
"per_style_minimum_order_quantity": 0,
"variant_option_sets": [
{
"name": "Scent",
"values": [
"Cinnamon",
"Skunk",
"Vanilla"
]
}
],
"variants": [
{
"id": "po_123",
"idempotence_token": "rrc23negw",
"product_id": "p_123",
"name": "Vanilla Scent",
"sku": "vanilla-2019",
"available_quantity": 42,
"backordered_until": "20190208T000915.000Z",
"created_at": "2019-03-14T00:09:15.000Z",
"updated_at": "2019-03-15T00:09:15.000Z",
"images": [
{
"id": "i_adqaiy3htm",
"width": 1000,
"height": 1000,
"sequence": 0,
"url": "https://cdn.faire.com/374cd3041a4c4.png",
"tags": [
"Hero"
]
}
],
"options": [
{
"name": "Scent",
"value": "Vanilla"
}
],
"wholesale_price_cents": 299,
"retail_price_cents": 599,
"tariff_code": "340600"
}
],
"images": [
{
"id": "i_7oey1vb9bm",
"width": 1000,
"height": 1000,
"sequence": 0,
"url": "https://cdn.faire.com/53105976.png",
"tags": [
"Hero"
]
},
{
"id": "i_1i8ui542vi",
"width": 1200,
"height": 1200,
"sequence": 1,
"url": "https://cdn.faire.com/554156553.png",
"tags": [
"Product"
]
}
],
"taxonomy_type": {
"id": "tt_23nl3bzl00"
},
"preorderable": true,
"preorder_details": {
"order_by_date": "2021-04-01",
"keep_active_past_order_by_date": false,
"expected_ship_date": "2021-05-21",
"expected_ship_window_end_date": "2021-05-24"
},
"created_at": "2019-03-14T00:09:15.000Z",
"updated_at": "2019-03-15T00:09:15.000Z"
}
Field | Description |
---|---|
id | A unique identifier of the product, beginning with "p_". |
brand_id | A unique identifier of the brand that owns the product, beginning with "b_". |
name | The name of the product. |
sale_state | READ-ONLY The current sellability of the product variant on Faire. See Product State Management. |
lifecycle_state | The current stage in the lifecycle of a product on Faire. See Product State Management. |
short_description | A short description of the product, at most 75 characters. |
description | A description of the product, at most 1,000 characters. |
unit_multiplier | Also called case size or case quantity, this is the unit size that this product ships in. The product must be purchased in increments of this number. |
minimum_order_quantity | The minimum number of units required to purchase this product. Must be a multiple of the unit_multiplier . |
per_style_minimum_order_quantity | The minimum nuber of units of this product that can be ordered for the same "style". A "style" is defined as the set of variation values for an option, excluding the "Size" variation. A product without a "Size" variation cannot use per_style_minimum_order_quantity . This field is mutually exclusive with minimum_order_quantity and unit_multiplier . When setting per_style_minium_order_quantity to a number greater than 0, unit_multiplier must be set to 1 and minimum_order_quantity must be set to 0. |
variant_option_sets | A list of the different available options used to compose variants. The names of the options on a product cannot change after creation. |
variants | A list of product variants that belong to this product. |
idempotence_token | The identifier used for idempotence when this product was created. |
images | The list of images associated with the product. |
taxonomy_type | The taxonomy type of this product. |
allow_sales_when_out_of_stock | Boolean that determines whether this product should automatically go out of stock when it has insufficient inventory. |
preorderable | Boolean that is true when the product can be preordered. If this field is true, preorder_details will be non-null. |
preorder_details | An object containing all the details for a preorderable product. Null if preorderable is false. |
preorder_details.order_by_date | An ISO 8601 date representing the latest date this product can be preordered. |
preorder_details.keep_active_past_order_by_date | Boolean that, when true, will keep products active past their orderByDate. Products are auto deactivated at the order by date. Setting this flag to true avoids this auto deactivation and the product to be explicitly deactivated. When a product reaches the order by date and this flag is true, the product remains active and it can still be preordered before start ship date, and ordered as a regular order after the start ship date. |
preorder_details.expected_ship_date | An ISO 8601 date representing the start of the shipping window for this preorder product. |
preorder_details.expected_ship_window_end_date | An ISO 8601 date representing the end of the shipping window for this preorder product. |
created_at | READ-ONLY An ISO 8601 timestamp of when the product was created. |
updated_at | READ-ONLY An ISO 8601 timestamp of when the product was last updated. |
Get All Products
This endpoint retrieves a list of products, ordered ascending by updated_at. By default, it only returns products that are not deleted.
HTTP Request
GET https://www.faire.com/external-api/v2/products
Query Parameters
Parameter | Default | Description |
---|---|---|
limit | 50 | The max number of products to return in a response. Must be between 50-250. |
page | 1 | The page of products to return. The first result will be (page - 1) * limit. |
updated_at_min | null | ISO 8601 timestamp. If specified, only return products that have been modified since. |
sku | null | The SKU of the product variants to search by, if supplied. |
include_deleted | null | True to include deleted products in the response, false or unspecified to omit them. |
Response
This endpoint returns JSON structured like:
{
"page": 1,
"limit": 50,
"products": [
{
"id": "p_123",
"idempotence_token": "4aytry2ust",
"brand_id": "b_abc",
"short_description": "Our candles smell fantastic. Want to know how good? Read our description!",
"description": "Glad you decided to read our description! We have significantly more characters to describe to you just how good our candles smell.",
"wholesale_price_cents": 500,
"retail_price_cents": 1000,
"sale_state": "NOT_FOR_SALE",
"lifecycle_state": "DRAFT",
"name": "Faire's fantastic candle",
"unit_multiplier": 2,
"minimum_order_quantity": 8,
"per_style_minimum_order_quantity": 0,
"variant_option_sets": [
{
"name": "Scent",
"values": [
"Cinnamon",
"Skunk",
"Vanilla"
]
}
],
"taxonomy_type": {
"id": "tt_23nl3bzl00",
"name": "Votive Candle"
},
"variants": [
{
"id": "po_123",
"idempotence_token": "rrc23negw",
"name": "Vanilla Scent",
"sku": "vanilla-2019",
"images": [
{
"url": "https://cdn.faire.com/374cd3041a4c4.png"
}
],
"options": [
{
"name": "Scent",
"value": "Vanilla"
}
],
"wholesale_price_cents": 299,
"retail_price_cents": 599
}
],
"created_at": "2019-03-14T00:09:15.000Z",
"updated_at": "2019-03-15T00:09:15.000Z"
}
]
}
Get A Product By ID
This endpoint retrieves a single product given an ID, regardless of state (active or deleted).
HTTP Request
GET https://www.faire.com/external-api/v2/products/<ID>
Path Parameters
Parameter | Description |
---|---|
ID | The ID of the product to retrieve. |
Response
This endpoint returns JSON structured like:
{
"id": "p_123",
"idempotence_token": "4aytry2ust",
"brand_id": "b_abc",
"short_description": "Our candles smell fantastic. Want to know how good? Read our description!",
"description": "Glad you decided to read our description! We have significantly more characters to describe to you just how good our candles smell.",
"wholesale_price_cents": 500,
"retail_price_cents": 1000,
"sale_state": "NOT_FOR_SALE",
"lifecycle_state": "DRAFT",
"name": "Faire's fantastic candle",
"unit_multiplier": 2,
"minimum_order_quantity": 8,
"per_style_minimum_order_quantity": 0,
"variant_option_sets": [
{
"name": "Scent",
"values": [
"Cinnamon",
"Skunk",
"Vanilla"
]
}
],
"taxonomy_type": {
"id": "tt_23nl3bzl00",
"name": "Votive Candle"
},
"variants": [
{
"id": "po_123",
"idempotence_token": "rrc23negw",
"name": "Vanilla Scent",
"sku": "vanilla-2019",
"images": [
{
"url": "https://cdn.faire.com/374cd3041a4c4.png"
}
],
"options": [
{
"name": "Scent",
"value": "Vanilla"
}
],
"wholesale_price_cents": 299,
"retail_price_cents": 599
}
],
"created_at": "2019-03-14T00:09:15.000Z",
"updated_at": "2019-03-15T00:09:15.000Z"
}
Create A Product
This endpoint accepts a product with only the fields populated that are to be used in creation:
{
"idempotence_token": "4aytry2ust",
"name": "Faire's fantastic candle",
"short_description": "Our candles smell fantastic. Want to know how good? Read our description!",
"description": "Glad you decided to read our description! We have significantly more characters to describe to you just how good our candles smell.",
"lifecycle_state": "PUBLISHED",
"unit_multiplier": 2,
"minimum_order_quantity": 8,
"variant_option_sets": [
{
"name": "Scent",
"values": [
"Cinnamon",
"Skunk",
"Vanilla"
]
}
],
"variants": [
{
"idempotence_token": "rrc23negw",
"name": "Vanilla Scent",
"sku": "vanilla-2019",
"images": [
{
"url": "https://cdn.faire.com/374cd3041a4c4.png"
}
],
"options": [
{
"name": "Scent",
"value": "Vanilla"
}
],
"wholesale_price_cents": 299,
"retail_price_cents": 599
}
],
"images": [
{
"url": "https://cdn.faire.com/53105976.png"
},
{
"url": "https://cdn.faire.com/554156553.png"
}
],
"preorderable": true,
"preorder_details": {
"order_by_date": "2021-04-01",
"keep_active_past_order_by_date": false,
"expected_ship_date": "2021-05-21",
"expected_ship_window_end_date": "2021-05-24"
},
"taxonomy_type": {
"id": "tt_23nl3bzl00"
}
}
This creates a single product in the specified lifecycle_state
, with a sale_state
of FOR_SALE
that is preorderable.
HTTP Request
POST https://www.faire.com/external-api/v2/products
Request Parameters
Parameter | Description | Required |
---|---|---|
idempotence_token | The identifier to use for idempotence when creating this product. This must be specified and be unique per product when creating. | Required |
name | The name of the product. | Required |
short_description | A short description of the product, at most 75 characters. | Optional |
description | A description of the product, at most 1,000 characters. | Optional |
lifecycle_state | The current stage in the lifecycle of a product on Faire. See Product State Management | Optional |
unit_multiplier | Also called case size or case quantity, this is the unit size that this product ships in. The product must be purchased in increments of this number. | Required |
minimum_order_quantity | The minimum number of units required to purchase this product. Must be a multiple of the unit_multiplier . |
Required |
per_style_minimum_order_quantity | The minimum nuber of units of this product that can be ordered for the same "style". A "style" is defined as the set of variation values for an option, excluding the "Size" variation. A product without a "Size" variation cannot use per_style_minimum_order_quantity . This field is mutually exclusive with minimum_order_quantity and unit_multiplier . When setting per_style_minium_order_quantity to a number greater than 0, unit_multiplier must be set to 1 and minimum_order_quantity must be set to 0. |
Optional |
variant_option_sets | A list of the different available options used to compose variants. See Product Variant Options. | Required |
variants | A list of product variants that belong to this product. | Required |
images | The list of images associated with the product. | Optional |
taxonomy_type | The taxonomy type of this product. | Optional |
allow_sales_when_out_of_stock | Boolean that determines whether this product should automatically go out of stock when it has insufficient inventory. | Optional |
preorderable | Boolean that is true when the product can be preordered. If this field is true, preorder_details will be non-null. | Optional |
preorder_details | An object containing all the details for a preorderable product. Null if preorderable is false. | Optional |
preorder_details.order_by_date | An ISO 8601 date representing the latest date this product can be preordered. | Optional |
preorder_details.keep_active_past_order_by_date | Boolean that, when true, will keep products active past their orderByDate. Products are auto deactivated at the order by date. Setting this flag to true avoids this auto deactivation and the product to be explicitly deactivated. When a product reaches the order by date and this flag is true, the product remains active and it can still be preordered before start ship date, and ordered as a regular order after the start ship date. | Optional |
preorder_details.expected_ship_date | An ISO 8601 date representing the start of the shipping window for this preorder product. | Optional |
preorder_details.expected_ship_window_end_date | An ISO 8601 date representing the end of the shipping window for this preorder product. | Optional |
Response
This endpoint returns JSON structured like:
{
"id": "p_123",
"idempotence_token": "4aytry2ust",
"name": "Faire's fantastic candle",
"short_description": "Our candles smell fantastic. Want to know how good? Read our description!",
"description": "Glad you decided to read our description! We have significantly more characters to describe to you just how good our candles smell.",
"lifecycle_state": "PUBLISHED",
"unit_multiplier": 2,
"minimum_order_quantity": 8,
"per_style_minimum_order_quantity": 0,
"variant_option_sets": [
{
"name": "Scent",
"values": [
"Cinnamon",
"Skunk",
"Vanilla"
]
}
],
"variants": [
{
"id": "po_123",
"name": "Vanilla Scent",
"idempotence_token": "rrc23negw",
"sku": "vanilla-2019",
"images": [
{
"url": "https://cdn.faire.com/374cd3041a4c4.png"
}
],
"options": [
{
"name": "Scent",
"value": "Vanilla"
}
],
"wholesale_price_cents": 299,
"retail_price_cents": 599
}
],
"images": [
{
"url": "https://cdn.faire.com/53105976.png"
},
{
"url": "https://cdn.faire.com/554156553.png"
}
],
"preorderable": true,
"preorder_details": {
"order_by_date": "2021-04-01",
"keep_active_past_order_by_date": false,
"expected_ship_date": "2021-05-21",
"expected_ship_window_end_date": "2021-05-24"
},
"taxonomy_type": {
"id": "tt_23nl3bzl00",
"name": "Votive Candle"
}
}
Update A Product
This endpoint accepts a product with only the fields populated that are to be modified:
{
"name": "Faire's fantastic candle",
"short_description": "Our candles smell fantastic. Want to know how good? Read our description!",
"description": "Glad you decided to read our description! We have significantly more characters to describe to you just how good our candles smell.",
"lifecycle_state": "PUBLISHED",
"unit_multiplier": 2,
"minimum_order_quantity": 8,
"variants": [
{
"id": "po_123",
"name": "Updated Vanilla Scent"
},
{
"name": "New Cinnamon Scent",
"sku": "Cinnamon-2019",
"images": [
{
"url": "https://cdn.faire.com/374cd3041a4c5.png"
}
],
"options": [
{
"name": "Scent",
"value": "Cinnamon"
}
],
"wholesale_price_cents": 299,
"retail_price_cents": 599
}
],
"images": [
{
"url": "https://cdn.faire.com/53105976.png"
},
{
"url": "https://cdn.faire.com/554156553.png"
}
],
"taxonomy_type": {
"id": "tt_23nl3bzl00"
},
"preorderable": true,
"preorder_details": {
"order_by_date": "2021-04-01",
"keep_active_past_order_by_date": false,
"expected_ship_date": "2021-05-21",
"expected_ship_window_end_date": "2021-05-24"
}
}
This updates a single product. Variants can be updated/created with this endpoint, but prepacks must use the prepack APIs.
HTTP Request
PATCH https://www.faire.com/external-api/v2/products/<ID>
Path Parameters
Parameter | Description |
---|---|
ID | The ID of the product to modify. |
Request Parameters
Parameter | Description | Required |
---|---|---|
name | The name of the product. | Optional |
short_description | A short description of the product, at most 75 characters. | Optional |
description | A description of the product, at most 1,000 characters. | Optional |
lifecycle_state | The current stage in the lifecycle of a product on Faire. See Product State Management | Optional |
unit_multiplier | Also called case size or case quantity, this is the unit size that this product ships in. The product must be purchased in increments of this number. | Optional |
minimum_order_quantity | The minimum number of units required to purchase this product. Must be a multiple of the unit_multiplier . |
Optional |
variants | A list of product variants that belong to this product. To update an existing variant, the variant ID must be provided. | Optional |
images | The list of images associated with the product. Images in this list will be added to the existing images. This list will not replace the existing | Optional |
images. Faire will download a copy of the image at the specified url . |
Optional | |
taxonomy_type | The taxonomy type of this product. | Optional |
variant_option_sets | A list of the different available options used to compose variants. Option names cannot be edited, but the option values can be updated. | Optional |
allow_sales_when_out_of_stock | Boolean that determines whether this product should automatically go out of stock when it has insufficient inventory. | Optional |
preorderable | Boolean that is true when the product can be preordered. If this field is true, preorder_details will be non-null. | Optional |
preorder_details | An object containing all the details for a preorderable product. Null if preorderable is false. | Optional |
preorder_details.order_by_date | An ISO 8601 date representing the latest date this product can be preordered. | Optional |
preorder_details.keep_active_past_order_by_date | Boolean that, when true, will keep products active past their orderByDate. Products are auto deactivated at the order by date. Setting this flag to true avoids this auto deactivation and the product to be explicitly deactivated. When a product reaches the order by date and this flag is true, the product remains active and it can still be preordered before start ship date, and ordered as a regular order after the start ship date. | Optional |
preorder_details.expected_ship_date | An ISO 8601 date representing the start of the shipping window for this preorder product. | Optional |
preorder_details.expected_ship_window_end_date | An ISO 8601 date representing the end of the shipping window for this preorder product. | Optional |
Response
This endpoint returns JSON structured like:
{
"id": "p_123",
"name": "Faire's fantastic candle",
"short_description": "Our candles smell fantastic. Want to know how good? Read our description!",
"description": "Glad you decided to read our description! We have significantly more characters to describe to you just how good our candles smell.",
"lifecycle_state": "PUBLISHED",
"unit_multiplier": 2,
"minimum_order_quantity": 8,
"idempotence_token": "4aytry2ust",
"variant_option_sets": [
{
"name": "Scent",
"values": [
"Cinnamon",
"Skunk",
"Vanilla"
]
}
],
"variants": [
{
"id": "po_123",
"name": "Updated Vanilla Scent",
"sku": "vanilla-2019",
"images": [
{
"url": "https://cdn.faire.com/374cd3041a4c4.png"
}
],
"idempotence_token": "rrc23negw",
"options": [
{
"name": "Scent",
"value": "Vanilla"
}
],
"wholesale_price_cents": 299,
"retail_price_cents": 599
},
{
"id": "po_456",
"name": "New Cinnamon Scent",
"sku": "Cinnamon-2019",
"images": [
{
"url": "https://cdn.faire.com/374cd3041a4c5.png"
}
],
"idempotence_token": "rrc45negw",
"options": [
{
"name": "Scent",
"value": "Cinnamon"
}
],
"wholesale_price_cents": 299,
"retail_price_cents": 599
}
],
"images": [
{
"url": "https://cdn.faire.com/53105976.png"
},
{
"url": "https://cdn.faire.com/554156553.png"
}
],
"preorderable": true,
"preorder_details": {
"order_by_date": "2021-04-01",
"keep_active_past_order_by_date": false,
"expected_ship_date": "2021-05-21",
"expected_ship_window_end_date": "2021-05-24"
},
"taxonomy_type": {
"id": "tt_23nl3bzl00",
"name": "Votive Candle"
}
}
Delete A Product
This endpoint deletes a single product given an ID.
This means that the product will have its lifecycle_state
set to DELETED
and will no longer be visible on Faire.
HTTP Request
DELETE https://www.faire.com/external-api/v2/products/<ID>
Path Parameters
Parameter | Description |
---|---|
ID | The ID of the product to delete. |
Response
204 NO_CONTENT
Update product's variation option sets
This endpoint replaces the current variation option sets of a product by the given new variation option sets. Options applied in the current variants cannot be removed.
If the product is sold in prepacks, size options cannot be reorganized and new values cannot be inserted to the middle of size options. (e.g current size options: ["S", "M", "L"], then new size options ["S", "M", "L", "XL"] or ["XS", "S", "M", "L"] is acceptable, but ["M", "S", "L"] or ["S", "M", "XL", "L"] is invalid.)
{
"variant_option_sets": [
{
"name": "Scent",
"values": [
"Cinnamon",
"Skunk",
"Vanilla"
]
},
{
"name": "Color",
"values": [
"Red",
"Blue",
"Yellow"
]
}
]
}
HTTP Request
PATCH https://www.faire.com/external-api/v2/products/<ID>/variant-option-sets
Path Parameters
Parameter | Description |
---|---|
ID | The ID of the product to update variant option sets |
Request Parameters
Parameter | Description | Required |
---|---|---|
variant_option_sets | A list of the different available options used to compose variants. Option names cannot be edited, but the option values can be updated. | Required |
Response
This endpoint returns JSON structured like:
{
"variant_option_sets": [
{
"name": "Scent",
"values": [
"Cinnamon",
"Skunk",
"Vanilla"
]
},
{
"name": "Color",
"values": [
"Red",
"Blue",
"Yellow"
]
}
]
}
Get All Taxonomy Types
This endpoint retrieves all the Faire taxonomy types. Taxonomy types are often referred to as "product types" in our user-facing terminology. The two terms can be used interchangeably
Faire will use taxonomy type information to determine the categories in which brands and products are surfaced in our marketplace.
You only need to provide the ID when creating or updating a product. When you retrieve a product, both the ID and name will be returned.
HTTP Request
GET https://www.faire.com/external-api/v2/products/types
Response
This endpoint returns JSON structured like:
{
"taxonomy_types": [
{
"id": "tt_6hk4mf1xig",
"name": "Tea Bags"
},
{
"id": "tt_b0oaeo6ixo",
"name": "Tea Cup"
},
{
"id": "tt_beh3u2i3o0",
"name": "Tea Light Candles"
}
]
}
Product Variants
Product variants are a unique variant of a product. All variants belong to a single product, with a product having at least one variant. Variants can be differentiated by SKU, have their own inventory levels, and be backordered or deactivated independently of other variants.
A variant has a single option values for each type of option. For example, a variant could have "Red" and "Large" for its product's "Color" and "Size" options, respectively. Variants are defined by their option values, so the values cannot be changed once the variant is created.
A product does not need to exhaustively have a variant for each possible combination of options.
A sample product variant might look like:
{
"id": "po_123",
"idempotence_token": "4aytry2ust",
"product_id": "p_abc",
"name": "Vanilla",
"sale_state" : "FOR_SALE",
"lifecycle_state" : "PUBLISHED",
"sku": "vanilla-2019",
"tariff_code": "123123",
"prices": [
{
"geo_constraint": {
"country": "CAN"
},
"wholesale_price": {
"amount_minor": 1299,
"currency": "CAD"
},
"retail_price": {
"amount_minor": 2201,
"currency": "CAD"
}
},
{
"geo_constraint": {
"country": "USA"
},
"wholesale_price": {
"amount_minor": 899,
"currency": "USD"
},
"retail_price": {
"amount_minor": 1801,
"currency": "USD"
}
}
],
"available_quantity": 42,
"backordered_until": "2019-02-08T00:09:15.000Z",
"created_at": "2019-03-14T00:09:15.000Z",
"updated_at": "2019-03-15T00:09:15.000Z",
"options": [
{
"name": "Scent",
"value": "Vanilla"
}
],
"images": [
{
"id": "i_adqaiy3htm",
"width": 1000,
"height": 1000,
"sequence": 0,
"url": "https://cdn.faire.com/374cd3041a4c4.png",
"tags": [
"Hero"
]
}
]
}
Field | Description |
---|---|
id | A unique identifier of the product variant, beginning with "po_". |
idempotence_token | The identifier used for idempotence when this variant was created. |
product_id | A unique identifier of the product the variant belongs to, beginning with "p_". |
name | READ-ONLY The name of the product variant, auto-generated by option values. |
sale_state | READ-ONLY The current sellability of the product variant on Faire. See Product State Management |
lifecycle_state | The current stage in the lifecycle of a product on Faire. See Product State Management |
sku | An identifier that should be unique amongst product variants. It is up to the client to keep SKUs unique. SKUs are case-sensitive. |
retail_price_cents | Deprecated. The current recommended retailer price of a single unit of this variant in cents (US dollars). |
wholesale_price_cents | Deprecated. The current wholesale price of a single unit of this variant in cents (US dollars). |
prices | The prices for this product variant based on geographic region and currency. |
available_quantity | If set, the number of units available for sale. If not set in the response, the brand has not set their inventory levels in Faire. |
backordered_until | If set, Faire will not allow the product variant to be FOR_SALE until this date. |
created_at | READ-ONLY An ISO 8601 timestamp of when the product variant was created. |
updated_at | READ-ONLY An ISO 8601 timestamp of when the product variant was last updated. |
options | A set of options (attributes) that define this product variant. e.g. If the variant is a large red shirt, the options might include Color:Red and Size:Large. The options are immutable and must be valid values from the product's variant_option_sets . |
images | A list of images for this variant. If supplied on creation of the variant, Faire will download a copy of the image at the specified url . |
Create Product Variant
This endpoint accepts a variant with only the fields populated that are to be used in creation:
{
"idempotence_token": "4aytry2ust",
"name": "Vanilla",
"lifecycle_state" : "PUBLISHED",
"sku": "vanilla-2019",
"tariff_code": "123123",
"prices": [
{
"geo_constraint": {
"country": "CAN"
},
"wholesale_price": {
"amount_minor": 1299,
"currency": "CAD"
},
"retail_price": {
"amount_minor": 2201,
"currency": "CAD"
}
},
{
"geo_constraint": {
"country": "USA"
},
"wholesale_price": {
"amount_minor": 899,
"currency": "USD"
},
"retail_price": {
"amount_minor": 1801,
"currency": "USD"
}
}
],
"available_quantity": 42,
"options": [
{
"name": "Scent",
"value": "Vanilla"
}
],
"images": [
{
"width": 1000,
"height": 1000,
"sequence": 0,
"url": "https://cdn.faire.com/374cd3041a4c4.png",
"tags": [
"Hero"
]
}
]
}
HTTP Request
POST https://www.faire.com/external-api/v2/products/<PRODUCT_ID>/variants
Path Parameters
Parameter | Description |
---|---|
PRODUCT_ID | The ID of the product corresponding with the product variant |
Request Parameters
Field | Description | Required |
---|---|---|
idempotence_token | The identifier used for idempotence when this variant was created. | Required |
lifecycle_state | The current stage in the lifecycle of a product on Faire. See Product State Management | Optional |
sku | An identifier that should be unique amongst product variants. It is up to the client to keep SKUs unique. SKUs are case-sensitive. | Optional |
tariff_code | The tariff code of the variant, must be a valid HS6 Tariff Code. | Optional |
retail_price_cents | Deprecated. The current recommended retailer price of a single unit of this variant in cents (US dollars). | Optional |
wholesale_price_cents | Deprecated. The current wholesale price of a single unit of this variant in cents (US dollars). | Optional |
prices | The prices for this product variant based on geographic region and currency. | Required |
available_quantity | If set, the number of units available for sale. If not set in the response, the brand has not set their inventory levels in Faire. | Optional |
backordered_until | ISO 8601 timestamp that indicates when the variant will be back in stock. If set, Faire will not allow the product variant to be FOR_SALE until this date. |
Optional |
options | A set of options (attributes) that define this product variant. e.g. If the variant is a large red shirt, the options might include Color:Red and Size:Large. The options must be valid values from the product's variant_option_sets . |
Optional |
images | A list of images for this variant. If supplied on creation of the variant, Faire will download a copy of the image at the specified url . |
Optional |
Response
This endpoint returns JSON structured like:
{
"id": "po_123",
"idempotence_token": "4aytry2ust",
"product_id": "p_abc",
"name": "Vanilla Scent",
"sale_state" : "FOR_SALE",
"lifecycle_state" : "PUBLISHED",
"sku": "vanilla-2019",
"tariff_code": "123123",
"prices": [
{
"geo_constraint": {
"country": "CAN"
},
"wholesale_price": {
"amount_minor": 1299,
"currency": "CAD"
},
"retail_price": {
"amount_minor": 2201,
"currency": "CAD"
}
},
{
"geo_constraint": {
"country": "USA"
},
"wholesale_price": {
"amount_minor": 899,
"currency": "USD"
},
"retail_price": {
"amount_minor": 1801,
"currency": "USD"
}
}
],
"available_quantity": 42,
"created_at": "2019-03-14T00:09:15.000Z",
"updated_at": "2019-03-15T00:09:15.000Z",
"options": [
{
"name": "Scent",
"value": "Vanilla"
}
],
"images": [
{
"id": "i_adqaiy3htm",
"width": 1000,
"height": 1000,
"sequence": 0,
"url": "https://cdn.faire.com/374cd3041a4c4.png",
"tags": [
"Hero"
]
}
]
}
Update Product Variant
This endpoint accepts a variant with only the fields populated that you want to modify. A variant's options cannot be updated. If you want to change the options, delete the existing variant and create a new variant with new options.
{
"lifecycle_state" : "PUBLISHED",
"sku": "vanilla-2019",
"tariff_code": "123123",
"prices": [
{
"geo_constraint": {
"country": "USA"
},
"wholesale_price": {
"amount_minor": 1099,
"currency": "USD"
},
"retail_price": {
"amount_minor": 2001,
"currency": "USD"
}
}
],
"available_quantity": 42,
"images": [
{
"width": 1000,
"height": 1000,
"sequence": 0,
"url": "https://cdn.faire.com/374cd3041a4c4.png",
"tags": [
"Hero"
]
}
]
}
HTTP Request
PATCH https://www.faire.com/external-api/v2/products/<PRODUCT_ID>/variants/<VARIANT_ID>
Path Parameters
Parameter | Description |
---|---|
PRODUCT_ID | The ID of the product corresponding with the product variant |
VARIANT_ID | The ID of the product variant to update |
Request Parameters
Field | Description | Required |
---|---|---|
lifecycle_state | The current stage in the lifecycle of a product on Faire. See Product State Management | Optional |
sku | An identifier that should be unique amongst product variants. It is up to the client to keep SKUs unique. SKUs are case-sensitive. | Optional |
tariff_code | The tariff code of the variant, must be a valid HS6 Tariff Code. | Optional |
retail_price_cents | Deprecated. The current recommended retailer price of a single unit of this variant in cents (US dollars). | Optional |
wholesale_price_cents | Deprecated. The current wholesale price of a single unit of this variant in cents (US dollars). | Optional |
prices | The prices for this product variant based on geographic region and currency. | Optional |
available_quantity | If set, the number of units available for sale. If not set in the response, the brand has not set their inventory levels in Faire. | Optional |
backordered_until | ISO 8601 timestamp that indicates when the variant will be back in stock. If set, Faire will not allow the product variant to be FOR_SALE until this date. |
Optional |
images | A list of images for this variant. Images in this list will be added to the existing images. This list will not replace the existing images. Faire will download a copy of the image at the specified url . |
Optional |
Response
This endpoint returns JSON structured like:
{
"id": "po_123",
"idempotence_token": "4aytry2ust",
"product_id": "p_abc",
"name": "Vanilla Scent",
"sale_state" : "FOR_SALE",
"lifecycle_state" : "PUBLISHED",
"sku": "vanilla-2019",
"tariff_code": "123123",
"prices": [
{
"geo_constraint": {
"country": "USA"
},
"wholesale_price": {
"amount_minor": 1099,
"currency": "USD"
},
"retail_price": {
"amount_minor": 2001,
"currency": "USD"
}
}
],
"available_quantity": 42,
"created_at": "2019-03-14T00:09:15.000Z",
"updated_at": "2019-03-15T00:09:15.000Z",
"options": [
{
"name": "Scent",
"value": "Vanilla"
}
],
"images": [
{
"id": "i_adqaiy3htm",
"width": 1000,
"height": 1000,
"sequence": 0,
"url": "https://cdn.faire.com/374cd3041a4c4.png",
"tags": [
"Hero"
]
}
]
}
Delete A Product Variant
This endpoint deletes a single variant given a product ID and a variant ID.
This means that the product variant will have its lifecycle_state
set to DELETED
and will no longer be visible on Faire.
A product must have at least one non-deleted variant. To delete the last variant of product, need to delete the product instead.
HTTP Request
DELETE https://www.faire.com/external-api/v2/products/<PRODUCT_ID>/variants/<VARIANT_ID>
Path Parameters
Parameter | Description |
---|---|
PRODUCT_ID | The ID of the product corresponding with the product variant |
VARIANT_ID | The ID of the product variant to delete |
Response
204 NO_CONTENT
Update inventory levels by variant IDs
This endpoint updates variant inventory levels by given variant IDs.
{
"inventories": [
{
"product_variant_id": "po_123",
"current_quantity": 10,
"discontinued": false
},
{
"product_variant_id": "po_456",
"current_quantity": 20,
"discontinued": false,
"backordered_until": "2019-02-08T00:09:15.000Z"
}
]
}
HTTP Request
PATCH https://www.faire.com/external-api/v2/products/variants/inventory-levels-by-product-variant-ids
Request Parameters
Field | Description | Required |
---|---|---|
inventories.product_variant_id | The ID of the product variant to update. This is a unique identifier starting with "po_". | Required |
inventories.current_quantity | The quantity to set available_quantity to, must be null or a whole number. If the value is null, this will remove inventory tracking and disable inventory tracking features. If the number of available units is less than the unit_multiplier or minimum_order_quantity of the product, the variant will be deactivated. If there are no active variants for the product, the product will also be deactivated (see: Product State Management). |
Optional |
inventories.discontinued | Boolean indicating if the variant has been discontinued, and Faire should no longer activate this variant based on inventory levels. | Optional |
inventories.backordered_until | ISO 8601 timestamp that indicates when the variant will be back in stock. Faire will not allow the product variant to be FOR_SALE until this date and will deactivate all prepacks containing the variant. |
Optional |
Response
This endpoint returns JSON structured like:
{
"variants": [
{
"id": "po_123",
"idempotence_token": "4aytry2ust",
"product_id": "p_abc",
"name": "Vanilla",
"sale_state" : "FOR_SALE",
"lifecycle_state" : "PUBLISHED",
"sku": "vanilla-2019",
"tariff_code": "123123",
"prices": [
{
"geo_constraint": {
"country": "USA"
},
"wholesale_price": {
"amount_minor": 1099,
"currency": "USD"
},
"retail_price": {
"amount_minor": 2001,
"currency": "USD"
}
}
],
"available_quantity": 10,
"created_at": "2019-03-14T00:09:15.000Z",
"updated_at": "2019-03-15T00:09:15.000Z",
"options": [
{
"name": "Scent",
"value": "Vanilla"
}
]
},
{
"id": "po_456",
"idempotence_token": "3wegt4erg",
"product_id": "p_abc",
"name": "Cinnamon",
"sale_state" : "SALE_PAUSED",
"lifecycle_state" : "PUBLISHED",
"sku": "cinnamon-2019",
"tariff_code": "123123",
"retail_price_cents": 1099,
"wholesale_price_cents": 600,
"available_quantity": 20,
"backordered_until": "2019-02-08T00:09:15.000Z",
"created_at": "2019-03-14T00:09:15.000Z",
"updated_at": "2019-03-15T00:09:15.000Z",
"options": [
{
"name": "Scent",
"value": "Cinnamon"
}
]
}
]
}
Update inventory levels by variant SKUs
This endpoint updates variant inventory levels by given variant SKUs.
{
"inventories": [
{
"sku": "vanilla-2019",
"current_quantity": 10,
"discontinued": false
},
{
"sku": "cinnamon-2019",
"current_quantity": 20,
"discontinued": false,
"backordered_until": "2019-02-08T00:09:15.000Z"
}
]
}
HTTP Request
PATCH https://www.faire.com/external-api/v2/products/variants/inventory-levels-by-skus
Request Parameters
Field | Description | Required |
---|---|---|
inventories.sku | Matches the most recently created product variant with that SKU. | Required |
inventories.current_quantity | The quantity to set available_quantity to, must be null or a whole number. If the value is null, this will remove inventory tracking and disable inventory tracking features. If the number of available units is less than the unit_multiplier or minimum_order_quantity of the product, the variant will be deactivated. If there are no active variants for the product, the product will also be deactivated (see: Product State Management). |
Optional |
inventories.discontinued | Boolean indicating if the variant has been discontinued, and Faire should no longer activate this variant based on inventory levels. | Optional |
inventories.backordered_until | ISO 8601 timestamp that indicates when the variant will be back in stock. Faire will not allow the product variant to be FOR_SALE until this date and will deactivate all prepacks containing the variant. |
Optional |
Response
This endpoint returns JSON structured like:
{
"variants": [
{
"id": "po_123",
"idempotence_token": "4aytry2ust",
"product_id": "p_abc",
"name": "Vanilla",
"sale_state" : "FOR_SALE",
"lifecycle_state" : "PUBLISHED",
"sku": "vanilla-2019",
"tariff_code": "123123",
"prices": [
{
"geo_constraint": {
"country": "USA"
},
"wholesale_price": {
"amount_minor": 1099,
"currency": "USD"
},
"retail_price": {
"amount_minor": 2001,
"currency": "USD"
}
}
],
"available_quantity": 10,
"created_at": "2019-03-14T00:09:15.000Z",
"updated_at": "2019-03-15T00:09:15.000Z",
"options": [
{
"name": "Scent",
"value": "Vanilla"
}
]
},
{
"id": "po_456",
"idempotence_token": "3wegt4erg",
"product_id": "p_abc",
"name": "Cinnamon",
"sale_state" : "SALE_PAUSED",
"lifecycle_state" : "PUBLISHED",
"sku": "vanilla-2019",
"tariff_code": "123123",
"prices": [
{
"geo_constraint": {
"country": "USA"
},
"wholesale_price": {
"amount_minor": 1199,
"currency": "USD"
},
"retail_price": {
"amount_minor": 2101,
"currency": "USD"
}
}
],
"available_quantity": 20,
"backordered_until": "2019-02-08T00:09:15.000Z",
"created_at": "2019-03-14T00:09:15.000Z",
"updated_at": "2019-03-15T00:09:15.000Z",
"options": [
{
"name": "Scent",
"value": "Cinnamon"
}
]
}
]
}
Product Variant Prices
A product variant can be sold in different countries on the Faire platform and have different pricing in each country. To specify the currency, set exactly one of geo_constraint.country
or geo_constraint.country_group
.
A sample price might look like:
{
"geo_constraint": {
"country": "USA"
},
"wholesale_price": {
"amount_minor": 999,
"currency": "USD"
},
"retail_price": {
"amount_minor": 1901,
"currency": "USD"
}
}
Field | Description |
---|---|
geo_constraint.country | An ISO-3166-Alpha3 country code that the price applies to. Accepted values include:
country or country_group fields may be set. |
geo_constraint.country_group | A country group that the price applies to. Accepted values include:
country or country_group fields may be set. |
wholesale_price.amount_minor | The amount of money for the wholesale price in the smallest unit of the applicable currency. For example, 1000 cents for $10.00. |
wholesale_price.currency | The type of currency for the wholesale price in ISO 4217 format. For example, US dollars is USD. |
retail_price.amount_minor | The amount of money for the retail price in the smallest unit of the applicable currency. For example, 1000 cents for $10.00. |
retail_price.currency | The type of currency for the retail price in ISO 4217 format. For example, US dollars is USD. |
Prepacks
A product can have variants assembled into a prepack. This prepack is meant to be used with apparel items and is composed of several sizes of the apparel item, at specified quantities, listed from smallest to largest.
The following rules apply when adding a prepack to a product.
- Only products that have an option with the name "Size" can have prepacks.
- Prepacks must have all the sizes between the smallest and largest sizes included. For example, if a prepack has a Small and Large product option, it must also have a Medium product option.
- Prepack items are ordered in ascending order of size.
The description of the prepack is automatically generated based on its sizes and quantities and it follows apparel industry conventions. An example prepack with 2 Small, 1 Medium, and 3 Large product options included would have the description "2-1-3; S-L".
A sample prepack might look like:
{
"id": "pc_123",
"idempotence_token": "df41f1dfa",
"name": "My Red Shirt Prepack",
"description": "2-1-2; S-L",
"items": [
{
"id": "pci_234",
"variant_id": "po_d2d1",
"quantity": 2
},
{
"id": "pci_567",
"variant_id": "po_4r5e",
"quantity": 1
},
{
"id": "pci_890",
"variant_id": "po_8ash",
"quantity": 2
}
],
"created_at": "2019-03-14T00:09:15.000Z"
}
Field | Description |
---|---|
id | A unique identifier of the prepack, beginning with "pc_". |
idempotence_token | The identifier used when this prepack was created. |
name | The name of the prepack. |
description | A description of the prepack. The description is determined by the quantities and sizes of prepack items. |
items | A list of prepack items that belong to this prepack. |
created_at | An ISO 8601 timestamp of when the prepack was created. |
Prepack Items
Prepack items are a pairing of product variants to the quantity in the prepack.
Field | Description |
---|---|
id | A unique identifier of the prepack item, beginning with "pci_". |
variant_id | The identifier of the variant for this prepack item. |
quantity | The number of prepack items included in the prepack. |
Add a prepack to a product
This endpoint adds a prepack to an existing product:
{
"idempotence_token": "df41f1dfa",
"name": "My Red Shirt Prepack",
"items": [
{
"variant_id": "po_d2d1",
"quantity": 2
},
{
"variant_id": "po_4r5e",
"quantity": 1
},
{
"variant_id": "po_8ash",
"quantity": 2
}
]
}
HTTP Request
POST https://www.faire.com/external-api/v2/products/{product_id}/prepacks
Path Parameters
Parameter | Description |
---|---|
product_id | The identifier of the product to add the prepack to. |
Prepack Request Parameters
Parameter | Description | Required |
---|---|---|
idempotence_token | The identifier to use for idempotence when creating this prepack. This must be specified and be unique per prepack when creating. | Required |
name | The name of the prepack. | Required |
items | A list of prepack items that belong to this prepack. | Required |
Prepack Item Request Parameters
Parameter | Description | Required |
---|---|---|
variant_id | The identifier of the product variant for this prepack item. | Required |
quantity | The number of prepack items included in the prepack. | Required |
Response
This endpoint returns JSON structured like:
{
"id": "pc_123",
"idempotence_token": "df41f1dfa",
"name": "My Red Shirt Prepack",
"description": "2-1-2; S-L",
"items": [
{
"id": "pci_123",
"variant_id": "po_d2d1",
"quantity": 2
},
{
"id": "pci_456",
"variant_id": "po_4r5e",
"quantity": 1
},
{
"id": "pci_789",
"variant_id": "po_8ash",
"quantity": 2
}
]
}
Get a Prepack for a Product
This endpoint gets a single prepack specified in the URL path.
HTTP Request
GET https://www.faire.com/external-api/v2/products/{product_id}/prepacks/{prepack_id}
Path Parameters
Parameter | Description |
---|---|
product_id | The identifier of the product which owns the prepack. |
prepack_id | The identifier of the prepack. |
Response
This endpoint returns JSON structured like:
{
"id": "pc_123",
"idempotence_token": "df41f1dfa",
"name": "My Red Shirt Prepack",
"description": "2-1-2; S-L",
"items": [
{
"id": "pci_123",
"variant_id": "po_d2d1",
"quantity": 2
},
{
"id": "pci_456",
"variant_id": "po_4r5e",
"quantity": 1
},
{
"id": "pci_789",
"variant_id": "po_8ash",
"quantity": 2
}
]
}
Get all Prepacks for a Product
This endpoint gets all active prepacks of the product specified in the URL path.
HTTP Request
GET https://www.faire.com/external-api/v2/products/{product_id}/prepacks
Path Parameters
Parameter | Description |
---|---|
product_id | The identifier of the product which owns the prepacks. |
Response
This endpoint returns JSON structured like:
{
"prepacks": [
{
"id": "pc_123",
"idempotence_token": "df41f1dfa",
"name": "My Red Shirt Prepack",
"description": "2-1-2; S-L",
"items": [
{
"id": "pci_123",
"variant_id": "po_d2d1",
"quantity": 2
},
{
"id": "pci_456",
"variant_id": "po_4r5e",
"quantity": 1
},
{
"id": "pci_789",
"variant_id": "po_8ash",
"quantity": 2
}
]
},
{
"id": "pc_456",
"idempotence_token": "df4werwef",
"name": "My Red Shirt Prepack",
"description": "2-2-2; S-L",
"items": [
{
"id": "pci_135",
"variant_id": "po_d2d1",
"quantity": 2
},
{
"id": "pci_357",
"variant_id": "po_4r5e",
"quantity": 2
},
{
"id": "pci_579",
"variant_id": "po_8ash",
"quantity": 2
}
]
}
]
}
Delete A Prepack
This endpoint deletes a specified prepack. Deleted prepacks cannot be re-activated.
HTTP Request
DELETE https://www.faire.com/external-api/v2/products/{product_id}/prepacks/{prepack_id}
Path Parameters
Parameter | Description |
---|---|
product_id | The identifier of the product which contains the prepack. |
prepack_id | The identifier of the prepack to delete. |
Response
204 NO_CONTENT
Orders
Orders are placed from a retailer to a brand on Faire. Faire supports scheduling orders, where a retailer can place an order and request a ship date up to 6 months in the future. Orders should not be shipped before the scheduled ship date.
A sample order might look like:
{
"id": "bo_bxdmjbwxid",
"display_id": "BXDMJBWXID",
"created_at": "2019-03-15T00:09:15.000Z",
"updated_at": "2019-03-15T00:10:00.000Z",
"state": "PRE_TRANSIT",
"items": [
{
"id": "oi_bq425ju5vh",
"created_at": "2019-03-15T00:09:15.000Z",
"updated_at": "2019-03-15T00:09:15.000Z",
"order_id": "bo_bxdmjbwxid",
"product_id": "p_fccaefnahr",
"variant_id": "po_3745tjzrpc",
"quantity": 1,
"sku": "goldenretriever",
"price_cents": 10500,
"product_name": "Golden Dog",
"variant_name": "retriever",
"includes_tester": false,
"discounts": []
}
],
"shipments": [
{
"id": "s_bq425ju5vh",
"order_id": "bo_bxdmjbwxid",
"maker_cost_cents": 2300,
"carrier": "fedex",
"tracking_code": "94029300101029282",
"created_at": "2019-03-15T00:09:15.000Z",
"updated_at": "2019-03-15T00:09:15.000Z"
}
],
"address": {
"name": "John Smith",
"address1": "41 King Street West",
"address2": "3rd Floor",
"postal_code": "N2G 1A1",
"city": "Kitchener",
"state": "Ontario",
"state_code": "ON",
"phone_number": "555-123-4567",
"country": "Canada",
"country_code": "CAN",
"company_name": "Faire Wholesale, Inc"
},
"retailer_id": "r_c9385ldj",
"ship_after": "2019-03-15T00:09:15.000Z",
"payout_costs": {
"payout_fee_cents": 0,
"payout_fee_bps": 0,
"commission_cents": 2625,
"commission_bps": 2500
},
"source": "MARKETPLACE",
"payment_initiated_at": "2019-03-16T00:10:34.000Z",
"original_order_id": "bo_bg5ude6pmd",
"brand_discounts": [
{
"id": "bpc_k3w2kb97tp",
"code": "SUMMER10",
"includes_free_shipping": false,
"discount_percentage": 10,
"discount_type": "PERCENTAGE",
}
]
}
Field | Description |
---|---|
id | A unique identifier of the order, beginning with "bo_". NOTE: When shown on the Faire website, the "bo_" will be stripped and the order ID will be upper-case. e.g. "bo_bxdmjbwxid" appears as "#BXDMJBWXID" (See display_id). |
display_id | The order identifier as displayed on the Faire website, emails, etc. |
state | The current state of the order |
ship_after | An ISO 8601 timestamp of the earliest the order should ship |
items | A list of order items associated with the order |
shipments | A list of shipments associated with the order |
address | The address the order should be shipped to |
retailer_id | A unique identifier that represents the retailer who placed the order. See retailers for more information. |
payout_costs | The payout costs associated with the order. NOTE: this may change until the order has been paid out (payment_initiated_at is set), for example if items are removed from the order. |
source | How this order was initiated (may be MARKETPLACE, FAIRE_DIRECT, TRADESHOW, etc). |
payment_initiated_at | An ISO 8601 timestamp of when the brand was paid for this order. Null/absent if the order has not been paid yet. |
original_order_id | If this order has a parent, for example due to a backorder, this contains the ID of the original order. Null/absent otherwise. |
created_at | An ISO 8601 timestamp of when the order was created |
updated_at | An ISO 8601 timestamp of when the order was last updated |
brand_discounts | A list of any shop-wide promotions that were applied to this order. Does not include product-specific discounts, which can be found under the discounts field of the relevant order item. |
Order States
State | Description |
---|---|
NEW | The order has not yet been accepted by the brand. |
PROCESSING | The brand has accepted the order, and is in the process of fulfilling it. |
PRE_TRANSIT | The order has at least one shipment, but no shipments are in transit. |
IN_TRANSIT | At least one of the shipments is in transit. |
DELIVERED | At least one of the shipments has been delivered. |
BACKORDERED | The brand did not have sufficient quantity to fulfill the order and will ship it when items are back in stock. |
CANCELED | The order was canceled by the brand or the retailer. Can only happen if the order is NEW or PROCESSING. |
Get all Orders
This endpoint retrieves a list of orders, ordered ascending by updated_at.
A sample response might look like:
{
"page": 1,
"limit": 10,
"orders": [
{
"id": "bo_bxdmjbwxid",
"created_at": "2019-03-15T00:09:15.000Z",
"updated_at": "2019-03-15T00:10:00.000Z",
"state": "NEW",
"items": [
{
"id": "oi_bq425ju5vh",
"created_at": "2019-03-15T00:09:15.000Z",
"updated_at": "2019-03-15T00:09:15.000Z",
"order_id": "bo_bxdmjbwxid",
"product_id": "p_fccaefnahr",
"variant_id": "po_3745tjzrpc",
"quantity": 1,
"sku": "goldenretriever",
"price_cents": 10000,
"product_name": "Golden Dog",
"variant_name": "retriever",
"includes_tester": false
}
],
"address": {
"name": "John Smith",
"address1": "41 King Street West",
"address2": "3rd Floor",
"postal_code": "N2G 1A1",
"city": "Kitchener",
"state": "Ontario",
"state_code": "ON",
"phone_number": "555-123-4567",
"country": "Canada",
"country_code": "CAN",
"company_name": "Faire Wholesale, Inc"
},
"retailer_id": "r_c9385ldj",
"payout_costs": {
"payout_fee_cents": 0,
"payout_fee_bps": 0,
"commission_cents": 2625,
"commission_bps": 2500
},
"source": "MARKETPLACE"
}
]
}
HTTP Request
GET https://www.faire.com/external-api/v2/orders
Query Parameters
Parameter | Default | Description |
---|---|---|
limit | 50 | The max number of orders to return in a response. Must be between 10-50. |
page | 1 | The page of products to return. The first result will be (page - 1) * limit. |
updated_at_min | null | ISO 8601 timestamp, if specified only show orders that have been modified since. |
created_at_min | null | ISO 8601 timestamp, if specified only show orders that were created since. |
excluded_states | null | A comma separated list of states to exclude from the response (e.g. "DELIVERED,BACKORDERED,CANCELED"). |
ship_after_max | null | ISO 8601 timestamp, if specified only show orders that are due to be shipped at or before this time. |
Get a single order by ID
This endpoint retrieves a single order given an order ID.
A sample response might look like:
{
"id": "bo_bxdmjbwxid",
"created_at": "2019-03-15T00:09:15.000Z",
"updated_at": "2019-03-15T00:10:00.000Z",
"state": "NEW",
"items": [
{
"id": "oi_bq425ju5vh",
"created_at": "2019-03-15T00:09:15.000Z",
"updated_at": "2019-03-15T00:09:15.000Z",
"order_id": "bo_bxdmjbwxid",
"product_id": "p_fccaefnahr",
"variant_id": "po_3745tjzrpc",
"quantity": 1,
"sku": "goldenretriever",
"price_cents": 10000,
"product_name": "Golden Dog",
"variant_name": "retriever",
"includes_tester": false
}
],
"address": {
"name": "John Smith",
"address1": "41 King Street West",
"address2": "3rd Floor",
"postal_code": "N2G 1A1",
"city": "Kitchener",
"state": "Ontario",
"state_code": "ON",
"phone_number": "555-123-4567",
"country": "Canada",
"country_code": "CAN",
"company_name": "Faire Wholesale, Inc"
},
"retailer_id": "r_c9385ldj",
"payout_costs": {
"payout_fee_cents": 0,
"payout_fee_bps": 0,
"commission_cents": 2625,
"commission_bps": 2500
},
"source": "MARKETPLACE"
}
HTTP Request
GET https://www.faire.com/external-api/v2/orders/<ID>
Path Parameters
Parameter | Description |
---|---|
ID | The ID of the order to fetch. |
Accept an Order
This endpoint accepts an order and moves it to PROCESSING.
A sample request might look like:
{
"expected_ship_date": "2019-07-15T00:09:15.000Z"
}
HTTP Request
PUT https://www.faire.com/external-api/v2/orders/<ID>/processing
Path Parameters
Parameter | Description |
---|---|
ID | The ID of the order to accept |
Request Body Fields
Field | Description |
---|---|
expected_ship_date | Optional. If specified, an ISO 8601 timestamp of when the order is expected to be shipped. |
Add Shipments to an Order
This endpoint adds shipments to an order and moves the state to PRE_TRANSIT. When one of the shipments is accepted by the carrier, the state will move to IN_TRANSIT.
A sample request might look like:
{
"shipments": [
{
"order_id": "bo_bxdmjbwxid",
"maker_cost_cents": 2300,
"carrier": "fedex",
"tracking_code": "94029300101029282"
}
]
}
HTTP Request
POST https://www.faire.com/external-api/v2/orders/<ID>/shipments
Path Parameters
Parameter | Description |
---|---|
ID | The ID of the order to add shipments to |
Request Body Fields
Field | Description |
---|---|
shipments | A list of shipments to add to the order. |
Order Items
A sample order item might look like:
{
"id": "oi_bq425ju5vh",
"created_at": "2019-03-15T00:09:15.000Z",
"updated_at": "2019-03-15T00:09:15.000Z",
"order_id": "bo_bxdmjbwxid",
"product_id": "p_fccaefnahr",
"variant_id": "po_3745tjzrpc",
"quantity": 1,
"sku": "goldenretriever",
"price": {
"amount_minor": 10000,
"currency": "USD"
},
"product_name": "Golden Dog",
"variant_name": "retriever",
"includes_tester": true,
"tester_price": {
"amount_minor": 500,
"currency": "USD"
},
"discounts": [
{
"id": "bpc_cjpyaf56ts",
"code": "STOCK_UP",
"includes_free_shipping": false,
"discount_amount": {
"amount_minor": 2000,
"currency": "USD"
},
"discount_type": "FLAT_AMOUNT"
}
]
}
Field | Description |
---|---|
id | A unique identifier of the order item, beginning with "oi_". |
order_id | The ID of the order the item belongs to. |
product_id | The ID of the product the retailer bought. |
variant_id | The ID of the variant the retailer bought. |
quantity | The number of physical items the retailer purchased. |
sku | The SKU of the variant when the order was created. This may not match the current SKU of the variant. |
price.amount_minor | The amount of money for the wholesale price in the smallest unit of the applicable currency. For example, 1000 cents for $10.00. |
price.currency | The type of currency for the wholesale price in ISO 4217 format. For example, US dollars is USD. |
product_name | The name of the product when it was purchased. |
variant_name | The name of the variant when it was purchased. |
includes_tester | A boolean indicating whether or not a tester for the variant was purchased. |
tester_price.amount_minor | If includes_tester is true, The amount of money for the wholesale price in the smallest unit of the applicable currency. For example, 1000 cents for $10.00. |
tester_price.currency | If includes_tester is true, the type of currency for the tester price in ISO 4217 format. For example, US dollars is USD. |
created_at | An ISO 8601 timestamp of when the order was created. |
updated_at | An ISO 8601 timestamp of when the order was last updated. |
discounts | A list of any product-specific promotions that were applied to this item. Does not include shop-wide promotions, which can be found under the order's brand_discounts field. |
price_cents | Deprecated - use price instead. The wholesale price of the product at the time it was purchased, in USD cents. |
tester_price_cents | Deprecated - use tester_price instead. If includes_tester is true, the price of the tester in USD cents. |
Backordering Items
When backordering items, a new order will be created with the backordered items to be confirmed by the retailer. This is not intended for updating item inventory, only for backordering or discontinuing items that are not available for a specific order.
A sample request might look like:
{
"availabilities": {
"oi_abc": {
"available_quantity": 0,
"discontinued": true
},
"oi_def": {
"available_quantity": 4,
"discontinued": false,
"backordered_until": "2019-03-15T00:10:00.000Z"
}
}
}
HTTP Request
POST https://www.faire.com/external-api/v2/orders/<ID>/items/availability
Path Parameters
Parameter | Description |
---|---|
ID | The ID of the order for which to backorder items. |
Request Body Fields
The request body is a map of order item availabilities, keyed by the order item ID.
NOTE: This is the ID of the order item (starting with "oi_") and can be retrieved from the
order object. It is not the ID of the ordered variant.
Field | Description |
---|---|
available_quantity | The current available quantity for the item. The valid range is [0, orderedQuantity). |
discontinued | If true, the item was discontinued and cannot be ordered again in the future. |
backordered_until | An ISO 8601 timestamp of when the item will be back in stock. |
NOTE: Each availability body must have either discontinued set to true or backordered_until set to a valid date.
Shipments
Shipments are added to an order by a brand when fulfilling an order.
A sample shipment might look like:
{
"id": "s_bq425ju5vh",
"order_id": "bo_bxdmjbwxid",
"maker_cost_cents": 2300,
"carrier": "fedex",
"tracking_code": "94029300101029282",
"created_at": "2019-03-15T00:09:15.000Z",
"updated_at": "2019-03-15T00:09:15.000Z"
}
Field | Description |
---|---|
id | A unique identifier of the shipments, beginning with "s_". |
order_id | The ID of the order the shipment is attached to. |
maker_cost_cents | The cost the brand paid to ship the order, in USD cents. |
carrier | The carrier the brand used to ship the order. Accepted values are CANADA_POST , DHL_ECOMMERCE , DHL_EXPRESS , FEDEX , PUROLATOR , UPS , USPS , POSTNL , CANPAR . |
tracking_code | The tracking code for the shipment, format varies based on the carrier. |
created_at | An ISO 8601 timestamp of when the order was created. |
updated_at | An ISO 8601 timestamp of when the order was last updated. |
Discounts
Contains information about a promotion that's been applied to an order or order item.
A percentage discount might look like this:
{
"id": "bpc_k3w2kb97tp",
"code": "SUMMER10",
"includes_free_shipping": false,
"discount_percentage": 10,
"discount_type": "PERCENTAGE"
}
A flat discount might look like this:
{
"id": "bpc_cjpyaf56ts",
"code": "STOCK_UP",
"includes_free_shipping": false,
"discount_amount": {
"amount_minor": 2000,
"currency": "USD"
},
"discount_type": "FLAT_AMOUNT"
}
A free shipping promotion might look like this:
{
"id": "bpc_bj6sgz7yzu",
"code": "FREE_SHIP",
"includes_free_shipping": true,
"discount_type": "NONE"
}
Field | Description |
---|---|
id | A unique identifier for the order, beginning with "bpc_". |
code | The name of the promotion as it appears to retailers at checkout. |
discount_type | This is PERCENTAGE, FLAT_AMOUNT, or NONE depending on how the discount is calculated. A discount of type NONE means that this discount affected something other than the purchase price, such as free shipping or duties. |
includes_free_shipping | Whether this promotion is for free shipping. |
discount_amount.amount_minor | The amount of money for the discount in the smallest unit of the applicable currency. For example, 1000 cents for $10.00. This value is present only when the discount_type is FLAT_AMOUNT. |
discount_amount.currency | The type of currency for the discount in ISO 4217 format. For example, US dollars is USD. This value is present only when the discount_type is FLAT_AMOUNT. |
discount_percentage | The discount amount as a percent of the total. This value is present only when the discount_type is PERCENTAGE. |
Brands
Get Brand Profile
This endpoint retrieves information about the brand associated with the current session.
A sample response might look like:
{
"brand_id": "b_60ae65c4",
"name": "Jeff's Warm Toques"
}
HTTP Request
GET https://www.faire.com/external-api/v2/brands/profile
Retailers
Get Retailer Public Profile
This endpoint retrieves information about a retailer given their ID.
A sample response might look like:
{
"retailer_id": "r_c9385ldj",
"name": "Tom's Toque Emporium"
}
HTTP Request
GET https://www.faire.com/external-api/v2/retailers/public/<retailer_id>
Path Parameters
Parameter | Description |
---|---|
retailer_id | The ID of the retailer to get information for. |
Addresses
Contains information about the location of a person or business. Typically used to describe where to ship an order.
A sample address might look like:
{
"name": "John Smith",
"address1": "41 King Street West",
"address2": "3rd Floor",
"postal_code": "N2G 1A1",
"city": "Kitchener",
"state": "Ontario",
"state_code": "ON",
"phone_number": "555-123-4567",
"country": "Canada",
"country_code": "CAN",
"company_name": "Faire Wholesale, Inc"
}
Field | Description |
---|---|
name | The name of the individual (recipient) to contact at the address. |
address1 | The first line of street address information. |
address2 | Optional. The second line of street address information. |
postal_code | The ZIP/postal code. |
city | The city. |
state | The full name of the state or province. |
state_code | The ISO 3166-2 subdivision code. This is typically 2 letters to represent the state or province. |
phone_number | The E.164 formatted phone number used to contact the recipient. |
country | The full name of the country. |
country_code | The ISO 3166 alpha-3 country code. |
company_name | The name of the company at this address. |
Payout Costs
Contains information about how the payout amount for an order was calculated.
A sample payout costs object might look like:
{
"payout_fee_cents": 2100,
"payout_fee_bps": 300,
"commission_cents": 10500,
"commission_bps": 1500,
"payout_fee": {
"amount_minor" : 2100,
"currency": "USD"
},
"commission": {
"amount_minor" : 10500,
"currency": "USD"
},
"payout_protection_fee": {
"amount_minor" : 1050,
"currency": "USD"
},
"damaged_and_missing_items" : {
"amount_minor" : 0,
"currency": "USD"
},
"net_tax": {
"amount_minor" : 0,
"currency": "USD"
},
"total_payout": {
"amount_minor" : 56350,
"currency": "USD"
}
}
Field | Description |
---|---|
payout_fee | The amount charged to the brand to pay out the order (e.g. for next-day ACH transfers). |
payout_fee_cents | Deprecated. This is the same as payout_fee but is only for USD. Prefer that field. |
payout_fee_bps | The payout fee basis points used to calculate the payout fee (e.g. 300 is 3%). |
commission | The amount of commission charged to the brand for the order. |
commission_cents | Deprecated. This is the same as commission but is only for USD. Prefer that field. |
commission_bps | The commission basis points used to calculate the commission (e.g. 1500 is 15%). |
payout_protection_fee | The amount charged to the brand for the Faire shipping protection program, if the brand is a participant. |
damaged_and_missing_items | The amount deducted for any items reported missing or damaged in shipping. |
shipping_subsidy | The amount charged to the brand for the free shipping partnership program, if the brand is a participant. |
net_tax | The amount of tax charged to the retailer and included in the payout. |
total_payout | The amount paid out to the brand after all fees and deductions. |
Images
Contains information about the image. Typically used in products/variants.
A sample image might look like:
{
"id": "i_7oey1vb9bm",
"width": 1000,
"height": 1000,
"sequence": 0,
"url": "https://cdn.faire.com/53105976.png",
"tags": [
"Hero"
]
}
Field | Description |
---|---|
id | READ-ONLY The unique identifier of the image, beginning with "i_". |
width | READ-ONLY The width of the image in pixels. |
height | READ-ONLY The height of the image in pixels. |
sequence | The ordering to display the image when it is part of a collection of images. |
url | The URL for the image file. When provided as an input, Faire will attempt to download the image and host it on the Faire CDN. If it fails to download, Faire will attempt to serve the original image URL. |
tags | A distinct list of tags associated with this image |
Product State Management
Sale State
We have a read-only field on products and variants called sale_state
. It represents the current sellability of a
product on Faire. When a variant tracks inventory, or is backordered, it can change the sale_state
of the variant and
product.
sale_state
can be one of 2 values:
FOR_SALE
SALES_PAUSED
Comparison of sale states:
sale_state |
Visible to Makers | Visible to Retailers | Purchasable |
---|---|---|---|
FOR_SALE |
Yes | Yes | Yes |
SALES_PAUSED |
Yes | Yes | No |
Faire systems automatically move products and variants between the sale states.
Lifecycle State
This field represents the current lifecycle stage of a product or variant on Faire.
lifecycle_state
can be one of 4 values:
DRAFT
PUBLISHED
UNPUBLISHED
DELETED
Draft products do not need to have required fields (e.g. prices, case size) populated or validated, and are not visible
to retailers. While UNPUBLISHED
products are also not visible to retailers, they have all fields validated.
When changing the state of a product or variant to PUBLISHED
, it must have all its required fields populated including
having at least one image.
Comparison of lifecycle states:
lifecycle_state |
Enforces validation | Visible to Makers | Visible to Retailers |
---|---|---|---|
DRAFT |
No | Yes | No |
PUBLISHED |
Yes | Yes | Yes |
UNPUBLISHED |
Yes | Yes | No |
DELETED |
No | No | No |
Detailed Technical Explanation
For the purposes of this explanation, we will assume DELETED
products and variants do not exist. They are only
visible via certain API endpoints to help you track when products/variants are deleted.
Faire UI
Via Faire’s UI, brands can create DRAFT
products, and save the product without validating fields. If all the required
fields are populated and valid, the brand can then publish the draft product, which sets the lifecycle_state
to
PUBLISHED
. At this point, products can no longer be set to DRAFT
with the Faire UI. However, brands can now toggle
the lifecycle_state
between PUBLISHED
or UNPUBLISHED
at any time.
Faire Automated Systems
Product Variants
Faire will automatically determine whether a FOR_SALE
variant should instead be SALES_PAUSED
while one of the
following conditions are met:
- The variant has
backordered_until
set.- (we are aware this is not the typical usage of the term “Backorder”)
- The product has
allow_sales_when_out_of_stock = false
and the variant’savailable_quantity
is less than either:- the product’s
minimum_order_quantity
- the product’s
unit_multiplier
- the product’s
The variant is reverted to FOR_SALE
if an update causes all the conditions to no longer be met.
Products
- Faire will automatically determine whether a
FOR_SALE
product should instead beSALES_PAUSED
if:- All the variants under the product are either
SALES_PAUSED
- All the variants under the product are either
- If any option is
FOR_SALE
, the product will remainFOR_SALE
. - Faire will automatically set a
PUBLISHED
product toUNPUBLISHED
if at any point all the variants areUNPUBLISHED
.- This is not an automatically reversible change.
- Faire will never set a
UNPUBLISHED
product or variant toPUBLISHED
.
Preorders
When a preorder product reaches the "Order by Date" or "Expected Ship Date", it will move to UNPUBLISHED
.
Idempotency
An idempotent operation can be applied multiple times without changing the result. Many of Faire's APIs have a mechanism to allow for idempotent operations.
Imagine you are trying to create a product and then the network connection fails after we create the product in Faire, but before we can return the results to you. You see it as a failure and might try to create the product again. Without idempotent operations, there are now 2 duplicate products in Faire!
The Faire APIs require an idempotency_token
when creating new objects in our system. This token can be any string of
characters and should be unique to the object you are creating. With the idempotency token, you can retry failed
requests without risk of duplicating data in our system.
Errors
The Faire API uses the following error codes:
Error Code | Meaning |
---|---|
400 | Bad Request -- Your request is invalid. |
401 | Unauthorized -- Your API key is wrong. |
404 | Not Found -- The requested resource could not be found. |
405 | Method Not Allowed -- You tried to access an entity with an invalid method. |
418 | I'm a teapot. |
429 | Too Many Requests. |
500 | Internal Server Error -- We had a problem with our server. Try again later. |
503 | Service Unavailable -- We're temporarily offline for maintenance. Please try again later. |
Changelog
2023-01
- Added several fields to payout costs
2022-11
- Added
brand_discounts
field to orders anddiscounts
to order items
2022-10-14
- Update product variant pricing geo constraint
country
andcountry_group
restraints
2021-04-26
- Added support for open pack products via
per_style_minimum_order_quantity
2021-04-14
- Added support for geographic pricing for product variations.
- Deprecated
retailer_price_cents
andwholesale_price_cents
2021-04-07
- Adjusted the maximum length of product short_description and description to match with brand portal
2021-03-17
- Fixed incorrect
unit_multiplier
andminimum_order_quantity
values in sample requests and responses under product endpoints - Added missing request parameter
minimum_order_quantity
to create and patch product endpoints
2021-03-15
- added preorder details in create and patch product endpoints
2021-03-10
- We noticed prepacks shouldn't have any images, and we removed the field
image
from all requests and responses under that section.
2021-03-01
- External API V2 was released