Create or re-link a variant group

POST/v1/product-groups

scope products.write

One product sold in several sizes or colours. Each variant is its own product with its own price and stock; the group links them so the storefront shows one card with a picker. Pushing the same group again re-links it (200) instead of creating a second one (201).

Request body#

Field	Type	Required	Description
`external_group_id`	string	required	Your own id for the PARENT product — the one the variants are versions of. Required and non-empty (`field_required`, 400). Calling again with the same id updates that group rather than making another.
`products`	array	required	The variants. At least two — a single product does not need a group (`too_few_variants`, 400). They must all be in the SAME category, or the storefront cannot show them behind one card (`mixed_categories`, 400).
`products[].external_id`	string	optional	Which product this variant is, by your id. Send this or `product_id`; an entry matching neither is rejected with `product_not_found` naming its position.
`products[].product_id`	integer	optional	Which product this variant is, by our id. The alternative to `external_id`.
`products[].size`	string	optional	The size axis, free text as you use it — `S`, `54`, `27.5`. Shown as the picker on the listing.
`products[].color`	string	optional	The colour axis, free text.
`products[].gender`	string	optional	The gender axis, free text. Use whichever axes apply; a group with no axis at all links the products but gives the storefront nothing to offer as a choice.

Example

{
    "external_group_id": "ERP-1001-GROUP",
    "products": [
        {
            "external_id": "ERP-1001",
            "size": "S",
            "color": "Negru"
        },
        {
            "external_id": "ERP-1001-M",
            "size": "M",
            "color": "Negru"
        }
    ]
}

Response#

Returns the same object as Read a variant group (GET /v1/product-groups/{externalGroupId}), described in full there.

Example

{
    "external_group_id": "ERP-1001-GROUP",
    "group_id": 904,
    "count": 2,
    "variants": [
        {
            "product_id": 237224,
            "external_id": "ERP-1001",
            "sku": "MTB-29-001-S",
            "title": "Bicicleta MTB Hardtail 29 inch",
            "price": {
                "amount": 249900
            },
            "stock": 4,
            "size": "S",
            "color": "Negru",
            "gender": null,
            "is_representative": true
        },
        {
            "product_id": 237225,
            "external_id": "ERP-1001-M",
            "sku": "MTB-29-001-M",
            "title": "Bicicleta MTB Hardtail 29 inch",
            "price": {
                "amount": 249900
            },
            "stock": 2,
            "size": "M",
            "color": "Negru",
            "gender": null,
            "is_representative": false
        }
    ]
}

Failures use the shared error envelope — a machine-readable code and a request_id to quote to support. Error handling.

curl -X POST "https://sandbox-api.biklo.com/v1/product-groups" \ -H "Authorization: Bearer bk_test_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{ "external_group_id": "ERP-1001-GROUP", "products": [ { "external_id": "ERP-1001", "size": "S", "color": "Negru" }, { "external_id": "ERP-1001-M", "size": "M", "color": "Negru" } ] }'

<?php $ch = curl_init('https://sandbox-api.biklo.com/v1/product-groups'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_HTTPHEADER => [ 'Authorization: Bearer bk_test_YOUR_KEY', 'Content-Type: application/json', ], CURLOPT_POSTFIELDS => json_encode([ 'external_group_id' => 'ERP-1001-GROUP', 'products' => [ 0 => [ 'external_id' => 'ERP-1001', 'size' => 'S', 'color' => 'Negru', ], 1 => [ 'external_id' => 'ERP-1001-M', 'size' => 'M', 'color' => 'Negru', ], ], ]), ]); $response = json_decode(curl_exec($ch), true); curl_close($ch);

using System.Net.Http; using System.Net.Http.Headers; var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "bk_test_YOUR_KEY"); var request = new HttpRequestMessage( new HttpMethod("POST"), "https://sandbox-api.biklo.com/v1/product-groups"); request.Content = new StringContent( @"{ ""external_group_id"": ""ERP-1001-GROUP"", ""products"": [ { ""external_id"": ""ERP-1001"", ""size"": ""S"", ""color"": ""Negru"" }, { ""external_id"": ""ERP-1001-M"", ""size"": ""M"", ""color"": ""Negru"" } ] }", System.Text.Encoding.UTF8, "application/json"); var response = await client.SendAsync(request); var json = await response.Content.ReadAsStringAsync();

import requests response = requests.post( "https://sandbox-api.biklo.com/v1/product-groups", headers={"Authorization": "Bearer bk_test_YOUR_KEY"}, json={ "external_group_id": "ERP-1001-GROUP", "products": [ { "external_id": "ERP-1001", "size": "S", "color": "Negru" }, { "external_id": "ERP-1001-M", "size": "M", "color": "Negru" } ] }, ) data = response.json()

const response = await fetch("https://sandbox-api.biklo.com/v1/product-groups", { method: "POST", headers: { Authorization: "Bearer bk_test_YOUR_KEY", "Content-Type": "application/json" }, body: JSON.stringify({ "external_group_id": "ERP-1001-GROUP", "products": [ { "external_id": "ERP-1001", "size": "S", "color": "Negru" }, { "external_id": "ERP-1001-M", "size": "M", "color": "Negru" } ] }) }); const data = await response.json();

import java.net.http.*; import java.net.URI; var client = HttpClient.newHttpClient(); var request = HttpRequest.newBuilder() .uri(URI.create("https://sandbox-api.biklo.com/v1/product-groups")) .header("Authorization", "Bearer bk_test_YOUR_KEY") .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString( "{ \"external_group_id\": \"ERP-1001-GROUP\", \"products\": [ { \"external_id\": \"ERP-1001\", \"size\": \"S\", \"color\": \"Negru\" }, { \"external_id\": \"ERP-1001-M\", \"size\": \"M\", \"color\": \"Negru\" } ] }")) .build(); var response = client.send(request, HttpResponse.BodyHandlers.ofString());