Create a product variant

post

https://api.twoboxes.io/api/v1/product-variants

Creates a new product variant for the given merchant. If a product-variant
already exists for the provided variant_id, the existing product-variant
is returned without modification. If a variant_id is not provided and a
product-variant already exists for the same SKU & barcode combination
provided, the existing product-variant is returned without modification.
Otherwise, a new product-variant will be created. Metadata is persisted
in the same database transaction as the variant. If a source image URL
is provided, CDN image processing is scheduled asynchronously after creation.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

Product variant fields

Request body for creating or upserting a product variant. Optional fields will be set to null unless a default value is otherwise given.

barcode

string

Barcode (e.g. UPC/EAN) assigned to this variant by the merchant. Required if sku not provided.

capture_expiration_date

boolean

Whether an expiration date must be recorded when receiving or grading. Default: false. Optional.

capture_lot_code

boolean

Whether a lot code must be recorded when receiving or grading. Default: false. Optional.

currency

string

Currency used for MSRP pricing, as an ISO 4217 code (e.g. "usd"). Optional.

merchant

object

required

Prevents automated storefront syncs from overwriting this variant's data. Default: false.

metadata

object

Arbitrary key-value pairs attached to this variant. Optional.

msrp

number

Manufacturer's suggested retail price in the variant's local Currency. Optional.

name

string

required

Variant-level display name (e.g. "Blue / Large"). Required.

shelf_life_days

integer

Days this variant is sellable after being received. Zero means no restriction. Default: 0. Optional.

sku

string

Stock-keeping unit identifier assigned by the merchant. Required if barcode not provided.

source_image_url

string

Source image URL for this variant; the system processes it and serves it via CDN. Optional.

status

string

enum

Lifecycle state. Accepted values: active, archived, do_not_use. Default: active. Optional but recommended.

Allowed:

storefront_product_category

string

Product category as defined by the originating storefront. Must map to a Two Boxes product category. Optional but recommended.

storefront_product_type

string

Product type as defined by the originating storefront. Can be any value, where a Two Boxes product alias
should be created to map this value to a known entry in the Two Boxes product type taxonomy. Optional but recommended if storefront_product_category not provided.

title

string

Parent product title from the originating storefront (e.g. "Vintage Denim Jacket"). Optional.

valid_lot_codes

array of strings

Accepted lot codes during receiving. An empty or nil slice means all lot codes are accepted. Optional.

valid_lot_codes

variant_id

string

Variant-specific identifier from the originating storefront (e.g. Shopify variant ID). Optional.

weight_oz

number

Weight of this variant in ounces. Optional.

Responses

201Created

400Missing required fields, invalid status, or duplicate identifier

500Database or internal service failure