latestOpenAPI 3.0.32026-08-083681145.6 KB

19558399745c

Products

Product Variants

POST /products/{product_id}/variants

Creates a new variant for a product.

post/products/{product_id}/variants

Path parameters

product_idstring required

Request body

idstring

Read-only. The unique identifier of the variant, beginning with "po_".

created_atstring

Read-only. An ISO 8601 extended timestamp of when the variant was created.

updated_atstring

Read-only. An ISO 8601 extended timestamp of when the variant was last updated.

product_idstring

Read-only. The unique identifier of the product the variant belongs to, beginning with "p_".

namestring

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_tokenstring

TODO (bad docs): The identifier used when this variant was created.

skustring

An identifier that should be unique amongst variants. It is up to the client to keep SKUs unique. SKUs are case-sensitive.

available_quantityinteger

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_untilstring

If set, Faire will not allow the product option to be FOR_SALE until this date.

wholesale_price_centsinteger

The current wholesale price of a single unit of this variant in cents (US dollars). Deprecated - use prices instead.

retail_price_centsinteger

The current recommended retailer price of a single unit of this option in cents (US dollars). Deprecated - use prices instead.

tariff_codestring

The tariff code (HS code) for this product variant.

gtinstring

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.

Example request

{
  "id": "po_abc123",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-20T14:45:00Z",
  "name": "Vanilla Scent",
  "idempotence_token": "rrc23negw",
  "sku": "vanilla-2019",
  "available_quantity": 42,
  "backordered_until": "20190208T000915.000Z",
  "tariff_code": "340600",
  "images": [
    {
      "id": "i_adqaiy3htm",
      "width": 1000,
      "height": 1000,
      "url": "https://cdn.faire.com/374cd3041a4c4.png",
      "original_url": "https://example.com/original-image.png"
    }
  ],
  "options": [
    {
      "name": "Scent",
      "value": "Vanilla"
    }
  ],
  "prices": [
    {
      "geo_constraint": {
        "country": "USA",
        "country_group": "EUROPEAN_UNION"
      },
      "wholesale_price": {
        "amount_minor": 4999,
        "currency": "USD"
      },
      "retail_price": {
        "amount_minor": 4999,
        "currency": "USD"
      }
    }
  ],
  "variant_preorder_details": {
    "expected_ship_date": "2021-05-21",
    "expected_ship_window_end_date": "2021-05-24",
    "stop_selling_at": 1619827200000
  },
  "measurements": {
    "weight": 1.5,
    "length": 10.5,
    "width": 8,
    "height": 3.2
  },
  "gtin": "012345678905",
  "case_measurements": {
    "weight": 1.5,
    "length": 10.5,
    "width": 8,
    "height": 3.2
  }
}

Response

Successful response