latestOpenAPI 3.0.32026-08-083681145.6 KB

19558399745c

Products

POST /products

This creates a single product in the specified lifecycle_state, with a sale_state of FOR_SALE that is preorderable. If lifecycle_state is omitted, the product is published when it meets Faire's publication requirements, and saved as a draft with publicationWarnings when it does not.

post/products

Request body

idstring

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

created_atstring

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

updated_atstring

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

brand_idstring

Read-only. A unique identifier of the brand that owns the product, beginning with "b_".

namestring

The name of the product.

descriptionstring

A description of the product, at most 65,535 characters.

short_descriptionstring

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.

idempotence_tokenstring

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

unit_multiplierinteger

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_quantityinteger

The minimum number of units required to purchase this product. Must be a multiple of the unit_multiplier.

per_style_minimum_order_quantityinteger

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_stockboolean

determines if the state of the options can be SALES_PAUSED for stock reasons

preorderableboolean

True when the product can be preordered. If this field is true, preorder_details will be non-null.

made_in_countrystring

Country of origin for the product *

Example request

{
  "id": "p_123",
  "created_at": "2019-03-14T00:09:15.000Z",
  "updated_at": "2019-03-15T00:09:15.000Z",
  "brand_id": "b_abc",
  "name": "Faire's fantastic candle",
  "description": "Glad you decided to read our description! We have significantly more characters to describe to you just how good our candles smell.",
  "short_description": "Our candles smell fantastic. Want to know how good? Read our description!",
  "variants": [
    {
      "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
      }
    }
  ],
  "idempotence_token": "4aytry2ust",
  "unit_multiplier": 2,
  "minimum_order_quantity": 8,
  "images": [
    {
      "id": "i_adqaiy3htm",
      "width": 1000,
      "height": 1000,
      "url": "https://cdn.faire.com/374cd3041a4c4.png",
      "original_url": "https://example.com/original-image.png"
    }
  ],
  "variant_option_sets": [
    {
      "name": "Scent"
    }
  ],
  "preorder_details": {
    "order_by_date": "2021-04-01",
    "expected_ship_date": "2021-05-21",
    "expected_ship_window_end_date": "2021-05-24"
  },
  "product_attributes": [
    {
      "name": "Material",
      "value": "Cotton"
    }
  ]
}

Response

Successful response