--- title: "PATCH /products/{product_id}" method: PATCH path: "/products/{product_id}" tags: ["Products"] --- # PATCH /products/{product_id} `PATCH /products/{product_id}` This updates a single product. Variants can be updated/created with this endpoint, but prepacks must use the prepack APIs. ## Path parameters - `product_id` string, required ## Request body - ExternalProductV2 - `id` string — Read-only. The unique identifier of the product, beginning with "p_". - `created_at` string — Read-only. An ISO 8601 extended timestamp of when the product was created. - `updated_at` string — Read-only. An ISO 8601 extended timestamp of when the product was last updated. - `brand_id` string — Read-only. A unique identifier of the brand that owns the product, beginning with "b_". - `name` string — The name of the product. - `description` string — A description of the product, at most 65,535 characters. - `short_description` string — A short description of the product, at most 255 characters. - `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. - `variants` ExternalProductVariantV2[] — A list of product variants that belong to this 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. - `idempotence_token` string — TODO (bad docs): The identifier used when this product was created. - `unit_multiplier` integer — Also known as 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` integer — The minimum number of units required to purchase this product. Must be a multiple of the unit_multiplier. - `per_style_minimum_order_quantity` integer — The minimum number of units of this product that can be ordered for the same "style". "Style" is defined as the set of variation values excluding the value for the "Size" variation. A product without a "Size" variation cannot use perStyleMinimumOrderQuantity. This field is mutually exclusive with unitMultiplier and minimumOrderQuantity. When using perStyleMinimumOrderQuantity, unitMultiplier should be set to 1, and minimumOrderQuantity to 0. - `allow_sales_when_out_of_stock` boolean — determines if the state of the options can be `SALES_PAUSED` for stock reasons - `images` ExternalImageV2[] — The list of [images] associated with the product. - `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? - `variant_option_sets` ExternalProductVariantOptionDefinitionV2[] — A list of the different available options (attributes) used to compose variants. Products can only have the available option names defined on creation. If you want to redefine a product to have an additional option dimension, you must delete this product and create a new one. Option values are ordered (ex. Small, Medium, Large) and affect how they are displayed. TODO (add more details): New option values can be added to a product. See prepacks for details about altering the values for a "Size" option. - `name` string — The name of the option (e.g., "Size", "Color"). - `values` string[] — The available values for this option (e.g., ["Small", "Medium", "Large"]). - `taxonomy_type` ExternalTaxonomyTypeV2 - `id` string — The unique identifier of the taxonomy type. - `name` string — The human-readable name of the taxonomy type. - `preorderable` boolean — True when the product can be preordered. If this field is true, preorder_details will be non-null. - `preorder_details` ExternalProductV2PreorderDetails — An object containing all the details for a preorderable product. - `order_by_date` string — An ISO 8601 extended timestamp representing the latest date this product can be preordered. - `keep_active_past_order_by_date` boolean — 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. - `expected_ship_date` string — An ISO 8601 extended timestamp representing the start of the shipping window for this preorder product. - `expected_ship_window_end_date` string — An ISO 8601 extended timestamp representing the end of the shipping window for this preorder product. - `product_attributes` ExternalProductTaxonomyAttributeV2[] — Object containing list of taxonomy attributes for the product * - `name` string — The name of the taxonomy attribute. - `value` string — The value of the taxonomy attribute. - `made_in_country` string — Country of origin for the product * - `publication_warnings` ExternalPublicationValidationErrorV2[] — Read-only. Publication warnings returned when a create attempt auto-publish fails validation. Empty when the product published successfully. - `error_code` string — Machine-readable error code (e.g. "UNIT_MULTIPLIER_REQUIRED"). - `field_path` string — The dot-path of the field that caused the error (e.g. "unitMultiplier"). - `message` string — Human-readable description of the validation error. ## Response `200` Successful response - ExternalProductV2 - `id` string — Read-only. The unique identifier of the product, beginning with "p_". - `created_at` string — Read-only. An ISO 8601 extended timestamp of when the product was created. - `updated_at` string — Read-only. An ISO 8601 extended timestamp of when the product was last updated. - `brand_id` string — Read-only. A unique identifier of the brand that owns the product, beginning with "b_". - `name` string — The name of the product. - `description` string — A description of the product, at most 65,535 characters. - `short_description` string — A short description of the product, at most 255 characters. - `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. - `variants` ExternalProductVariantV2[] — A list of product variants that belong to this 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. - `idempotence_token` string — TODO (bad docs): The identifier used when this product was created. - `unit_multiplier` integer — Also known as 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` integer — The minimum number of units required to purchase this product. Must be a multiple of the unit_multiplier. - `per_style_minimum_order_quantity` integer — The minimum number of units of this product that can be ordered for the same "style". "Style" is defined as the set of variation values excluding the value for the "Size" variation. A product without a "Size" variation cannot use perStyleMinimumOrderQuantity. This field is mutually exclusive with unitMultiplier and minimumOrderQuantity. When using perStyleMinimumOrderQuantity, unitMultiplier should be set to 1, and minimumOrderQuantity to 0. - `allow_sales_when_out_of_stock` boolean — determines if the state of the options can be `SALES_PAUSED` for stock reasons - `images` ExternalImageV2[] — The list of [images] associated with the product. - `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? - `variant_option_sets` ExternalProductVariantOptionDefinitionV2[] — A list of the different available options (attributes) used to compose variants. Products can only have the available option names defined on creation. If you want to redefine a product to have an additional option dimension, you must delete this product and create a new one. Option values are ordered (ex. Small, Medium, Large) and affect how they are displayed. TODO (add more details): New option values can be added to a product. See prepacks for details about altering the values for a "Size" option. - `name` string — The name of the option (e.g., "Size", "Color"). - `values` string[] — The available values for this option (e.g., ["Small", "Medium", "Large"]). - `taxonomy_type` ExternalTaxonomyTypeV2 - `id` string — The unique identifier of the taxonomy type. - `name` string — The human-readable name of the taxonomy type. - `preorderable` boolean — True when the product can be preordered. If this field is true, preorder_details will be non-null. - `preorder_details` ExternalProductV2PreorderDetails — An object containing all the details for a preorderable product. - `order_by_date` string — An ISO 8601 extended timestamp representing the latest date this product can be preordered. - `keep_active_past_order_by_date` boolean — 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. - `expected_ship_date` string — An ISO 8601 extended timestamp representing the start of the shipping window for this preorder product. - `expected_ship_window_end_date` string — An ISO 8601 extended timestamp representing the end of the shipping window for this preorder product. - `product_attributes` ExternalProductTaxonomyAttributeV2[] — Object containing list of taxonomy attributes for the product * - `name` string — The name of the taxonomy attribute. - `value` string — The value of the taxonomy attribute. - `made_in_country` string — Country of origin for the product * - `publication_warnings` ExternalPublicationValidationErrorV2[] — Read-only. Publication warnings returned when a create attempt auto-publish fails validation. Empty when the product published successfully. - `error_code` string — Machine-readable error code (e.g. "UNIT_MULTIPLIER_REQUIRED"). - `field_path` string — The dot-path of the field that caused the error (e.g. "unitMultiplier"). - `message` string — Human-readable description of the validation error. ## 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)