---
title: "POST /products/{product_id}/variants"
method: POST
path: "/products/{product_id}/variants"
tags: ["Products", "Product Variants"]
---

# POST /products/{product_id}/variants

`POST /products/{product_id}/variants`

Creates a new variant for a product.

## Path parameters

- `product_id` string, required

## Request body

- ExternalProductVariantV2 — All products have one or more variants, which represent an combination of options defining that product. Variants can be differentiated by SKU, have their own inventory levels, and be backordered or deactivated independently of other variants. A product's variants can be different choices along one dimension, such as size variants that are small, medium, or large. More complex products may have choices spanning two or more dimensions. The arrangement of the dimensions and choices can be configured with the `option_definitions` of the product.
  - `id` string — Read-only. The unique identifier of the variant, beginning with "po_".
  - `created_at` string — Read-only. An ISO 8601 extended timestamp of when the variant was created.
  - `updated_at` string — Read-only. An ISO 8601 extended timestamp of when the variant was last updated.
  - `product_id` string — Read-only. The unique identifier of the product the variant belongs to, beginning with "p_".
  - `name` string — The name of the variant.
  - `sale_state` 'FOR_SALE' | 'SALES_PAUSED' — Read-only. The current sellability of the product option on Faire.
  - `lifecycle_state` 'DRAFT' | 'PUBLISHED' | 'UNPUBLISHED' | 'DELETED' — The current stage in the lifecycle of a product on Faire.
  - `idempotence_token` string — TODO (bad docs): The identifier used when this variant was created.
  - `sku` string — An identifier that should be unique amongst variants. It is up to the client to keep SKUs unique. SKUs are case-sensitive.
  - `available_quantity` integer — 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` string — If set, Faire will not allow the product option to be `FOR_SALE` until this date.
  - `wholesale_price_cents` integer — The current wholesale price of a single unit of this variant in cents (US dollars). Deprecated - use prices instead.
  - `retail_price_cents` integer — The current recommended retailer price of a single unit of this option in cents (US dollars). Deprecated - use prices instead.
  - `tariff_code` string — The tariff code (HS code) for this product variant.
  - `images` ExternalImageV2[] — The list of images associated with the variant.
    - `id` string — Read-only. The unique identifier of the image, beginning with "i_".
    - `width` integer — Read-only. The width of the image in pixels.
    - `height` integer — Read-only. The height of the image in pixels.
    - `sequence` integer — The ordering to display the image when it is part of a collection of images.
    - `url` string — 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.
    - `original_url` string — [READ-ONLY] The original url passed in for this image.
    - `tags` string[] — TODO: Document. What are tags? Are they an input?
  - `options` ExternalProductVariantOptionV2[] — A set of options (attributes) that define this variant. For example, if the variant is a large red shirt, the options might include Color:Red and Size:Large. The options must be valid name/value pairs from the product's `option_definitions`.
    - `name` string — The name of the option (e.g., "Size", "Color").
    - `value` string — The value of the option for this variant (e.g., "Large", "Red").
  - `prices` ExternalProductVariantV2Price[] — All the available prices with currency for this variant, by geographic region.
    - `geo_constraint` ExternalProductVariantV2PricePriceGeoConstraint
      - `country` string — The ISO alpha-3 country code. The only accepted values are: - "USA" for the United States - "CAN" for Canada - "GBR" for the United Kingdom - "AUS" for Australia
      - `country_group` string — The only accepted value is "EUROPEAN_UNION"
    - `wholesale_price` ExternalMoneyV2 — Represents a monetary amount with currency. All monetary values in the API use this structure. The amount is stored in the smallest unit (e.g., cents for USD) to avoid floating point precision issues.
      - `amount_minor` integer — The amount of money in the smallest unit of the applicable currency. For example, US dollars is in cents.
      - `currency` string — The type of currency involved in the current payment in ISO 4217 format. For example, US dollars is USD.
    - `retail_price` ExternalMoneyV2 — Represents a monetary amount with currency. All monetary values in the API use this structure. The amount is stored in the smallest unit (e.g., cents for USD) to avoid floating point precision issues.
      - `amount_minor` integer — The amount of money in the smallest unit of the applicable currency. For example, US dollars is in cents.
      - `currency` string — The type of currency involved in the current payment in ISO 4217 format. For example, US dollars is USD.
  - `variant_preorder_details` ExternalProductVariantV2VariantPreorderDetails
    - `expected_ship_date` string — An ISO 8601 extended timestamp representing the start of the shipping window for this preorder Option.
    - `expected_ship_window_end_date` string — An ISO 8601 extended timestamp representing the end of the shipping window for this preorder Option.
    - `stop_selling_at` integer — The date past which this Option will cease to be sold (gets de-listed).
  - `measurements` ExternalMeasurementsV2 — Contains information about weight and dimensions.
    - `mass_unit` 'GRAMS' | 'KILOGRAMS' | 'OUNCES' | 'POUNDS' — Mass units.
    - `weight` number — Weight, with unit specified by massUnit.
    - `distance_unit` 'CENTIMETERS' | 'INCHES' | 'FEET' | 'MILLIMETERS' | 'METERS' | 'YARDS' — Distance units.
    - `length` number — Length, with unit specified by distanceUnit.
    - `width` number — Width, with unit specified by distanceUnit.
    - `height` number — Height, with unit specified by distanceUnit.
  - `gtin` string — A Global Trade Item Number (GTIN) for the product variant. These are standardized codes issues by GS1 and include barcodes like UPC, ISBN, and EAN. GTINs must consist of only numbers, be 8, 12, 13, or 14 digits long, and have a valid check digit.
  - `orderability_type` 'IMMEDIATE' | 'PREORDER' — Indicates whether a product variant is available for immediate purchase or requires preorder.
  - `case_measurements` ExternalMeasurementsV2 — Contains information about weight and dimensions.
    - `mass_unit` 'GRAMS' | 'KILOGRAMS' | 'OUNCES' | 'POUNDS' — Mass units.
    - `weight` number — Weight, with unit specified by massUnit.
    - `distance_unit` 'CENTIMETERS' | 'INCHES' | 'FEET' | 'MILLIMETERS' | 'METERS' | 'YARDS' — Distance units.
    - `length` number — Length, with unit specified by distanceUnit.
    - `width` number — Width, with unit specified by distanceUnit.
    - `height` number — Height, with unit specified by distanceUnit.

## Response `200`

Successful response

- ExternalProductVariantV2 — All products have one or more variants, which represent an combination of options defining that product. Variants can be differentiated by SKU, have their own inventory levels, and be backordered or deactivated independently of other variants. A product's variants can be different choices along one dimension, such as size variants that are small, medium, or large. More complex products may have choices spanning two or more dimensions. The arrangement of the dimensions and choices can be configured with the `option_definitions` of the product.
  - `id` string — Read-only. The unique identifier of the variant, beginning with "po_".
  - `created_at` string — Read-only. An ISO 8601 extended timestamp of when the variant was created.
  - `updated_at` string — Read-only. An ISO 8601 extended timestamp of when the variant was last updated.
  - `product_id` string — Read-only. The unique identifier of the product the variant belongs to, beginning with "p_".
  - `name` string — The name of the variant.
  - `sale_state` 'FOR_SALE' | 'SALES_PAUSED' — Read-only. The current sellability of the product option on Faire.
  - `lifecycle_state` 'DRAFT' | 'PUBLISHED' | 'UNPUBLISHED' | 'DELETED' — The current stage in the lifecycle of a product on Faire.
  - `idempotence_token` string — TODO (bad docs): The identifier used when this variant was created.
  - `sku` string — An identifier that should be unique amongst variants. It is up to the client to keep SKUs unique. SKUs are case-sensitive.
  - `available_quantity` integer — 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` string — If set, Faire will not allow the product option to be `FOR_SALE` until this date.
  - `wholesale_price_cents` integer — The current wholesale price of a single unit of this variant in cents (US dollars). Deprecated - use prices instead.
  - `retail_price_cents` integer — The current recommended retailer price of a single unit of this option in cents (US dollars). Deprecated - use prices instead.
  - `tariff_code` string — The tariff code (HS code) for this product variant.
  - `images` ExternalImageV2[] — The list of images associated with the variant.
    - `id` string — Read-only. The unique identifier of the image, beginning with "i_".
    - `width` integer — Read-only. The width of the image in pixels.
    - `height` integer — Read-only. The height of the image in pixels.
    - `sequence` integer — The ordering to display the image when it is part of a collection of images.
    - `url` string — 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.
    - `original_url` string — [READ-ONLY] The original url passed in for this image.
    - `tags` string[] — TODO: Document. What are tags? Are they an input?
  - `options` ExternalProductVariantOptionV2[] — A set of options (attributes) that define this variant. For example, if the variant is a large red shirt, the options might include Color:Red and Size:Large. The options must be valid name/value pairs from the product's `option_definitions`.
    - `name` string — The name of the option (e.g., "Size", "Color").
    - `value` string — The value of the option for this variant (e.g., "Large", "Red").
  - `prices` ExternalProductVariantV2Price[] — All the available prices with currency for this variant, by geographic region.
    - `geo_constraint` ExternalProductVariantV2PricePriceGeoConstraint
      - `country` string — The ISO alpha-3 country code. The only accepted values are: - "USA" for the United States - "CAN" for Canada - "GBR" for the United Kingdom - "AUS" for Australia
      - `country_group` string — The only accepted value is "EUROPEAN_UNION"
    - `wholesale_price` ExternalMoneyV2 — Represents a monetary amount with currency. All monetary values in the API use this structure. The amount is stored in the smallest unit (e.g., cents for USD) to avoid floating point precision issues.
      - `amount_minor` integer — The amount of money in the smallest unit of the applicable currency. For example, US dollars is in cents.
      - `currency` string — The type of currency involved in the current payment in ISO 4217 format. For example, US dollars is USD.
    - `retail_price` ExternalMoneyV2 — Represents a monetary amount with currency. All monetary values in the API use this structure. The amount is stored in the smallest unit (e.g., cents for USD) to avoid floating point precision issues.
      - `amount_minor` integer — The amount of money in the smallest unit of the applicable currency. For example, US dollars is in cents.
      - `currency` string — The type of currency involved in the current payment in ISO 4217 format. For example, US dollars is USD.
  - `variant_preorder_details` ExternalProductVariantV2VariantPreorderDetails
    - `expected_ship_date` string — An ISO 8601 extended timestamp representing the start of the shipping window for this preorder Option.
    - `expected_ship_window_end_date` string — An ISO 8601 extended timestamp representing the end of the shipping window for this preorder Option.
    - `stop_selling_at` integer — The date past which this Option will cease to be sold (gets de-listed).
  - `measurements` ExternalMeasurementsV2 — Contains information about weight and dimensions.
    - `mass_unit` 'GRAMS' | 'KILOGRAMS' | 'OUNCES' | 'POUNDS' — Mass units.
    - `weight` number — Weight, with unit specified by massUnit.
    - `distance_unit` 'CENTIMETERS' | 'INCHES' | 'FEET' | 'MILLIMETERS' | 'METERS' | 'YARDS' — Distance units.
    - `length` number — Length, with unit specified by distanceUnit.
    - `width` number — Width, with unit specified by distanceUnit.
    - `height` number — Height, with unit specified by distanceUnit.
  - `gtin` string — A Global Trade Item Number (GTIN) for the product variant. These are standardized codes issues by GS1 and include barcodes like UPC, ISBN, and EAN. GTINs must consist of only numbers, be 8, 12, 13, or 14 digits long, and have a valid check digit.
  - `orderability_type` 'IMMEDIATE' | 'PREORDER' — Indicates whether a product variant is available for immediate purchase or requires preorder.
  - `case_measurements` ExternalMeasurementsV2 — Contains information about weight and dimensions.
    - `mass_unit` 'GRAMS' | 'KILOGRAMS' | 'OUNCES' | 'POUNDS' — Mass units.
    - `weight` number — Weight, with unit specified by massUnit.
    - `distance_unit` 'CENTIMETERS' | 'INCHES' | 'FEET' | 'MILLIMETERS' | 'METERS' | 'YARDS' — Distance units.
    - `length` number — Length, with unit specified by distanceUnit.
    - `width` number — Width, with unit specified by distanceUnit.
    - `height` number — Height, with unit specified by distanceUnit.

## Other responses

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

---

[API](https://skmtc.net/faire/apis/faire-external-api.md) · [All operations](https://skmtc.net/faire/apis/faire-external-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/faire/faire-external-api/revisions/19558399745c/schema)