Variants

Variants are written through POST /products, inside the product they belong to. Send a variants array on the product. Each variant is matched by its SKU within that product: a SKU that matches is updated, and a new SKU sent with options is created. This needs the products:write scope.

Update existing variants

Send the variant's SKU and only the fields that change:

• Variant SKUs are matched ignoring case and surrounding spaces.
• Only the fields you send change, and null clears a field.
• Leave price empty (or set it to null) and the variant uses the product's base price on every channel.
• Up to 500 variants per product are processed in one request. Extras are skipped and noted in unmatchedVariants.
• Send prices, weights and dimensions as a number or a string. Variant values are stored exactly as sent and aren't checked, so validate them on your side. On an existing variant, a value that's neither a number nor a string (such as true) is skipped, and the product still reports success.

The result reports how many variants were updated:

Variants that aren't updated

A variant SKU that matches nothing on the product, and has no options, isn't created. It's listed in unmatchedVariants and the rest of the product is still written. The same happens when more than one variant on the product shares the SKU you sent: Fulify refuses to guess which one you meant.

To fix a duplicated variant SKU, change one of them in the product editor.

Create variants

A variant SKU that matches nothing on the product is created when you send it with options. options maps each option type to a value:

Rules for new variants

• Option types must already exist in Settings → Variant Options. An unknown option type, such as a misspelt "Szie", fails the product rather than adding a new option type for your whole organization.
• If two option types share a name, the one already on the product is used. If that doesn't settle it, send the option type's id as the key instead of its name, for example { "12": "XXL" }.
• Option values are matched ignoring case and spaces, so "xxl" reuses an existing XXL. A value that doesn't exist yet is created under that option type and listed in createdOptionValues, for the product and in the summary.
• Every new variant must name exactly the product's options. A product with no options yet takes them from its first new variant. A product that already has variants without options can't take new ones through the API; add its options in Fulify first.
• Combinations must be unique. A combination that already exists on the product, or a SKU sent twice in the same product, fails the product.
• SKUs must be unique. A new variant's SKU can't match its own product's SKU, another product's SKU, or a variant of another product.
• New variants are active unless you send "isActive": false, and are never the default variant. Choose the default variant in Fulify.
• Price: leave it out and the variant inherits the product's base price. Send one to override it.
• You can create a product and its variants in the same request.
• If a variant SKU already exists on the product, it's treated as an update and its options are ignored.

Option values created by a request stay in place even if the product they were created for later fails. They're just unused labels, and the next request reuses them.

Variant fields

These variant fields can be written:

Stock quantities can't be written. Fulify doesn't hold stock; your OMS sends quantities to your channels directly.

Nothing is pushed to your channels when you update or create variants. The product follows the normal sync rules described in Products.