Samples

Ready-to-use request body samples for the most common write operations of the be.open API. Each sample shows the endpoint (the call) it belongs to, followed by the example request body. Path parameters in {curly braces} and the Authorization: Bearer <jwt-token> header must be filled in by the caller.

1. Product import — create or update a product

Endpoint: POST /api/products

Auth: Bearer JWT (any authenticated API client)

Source file: 01_product_import.json

Creates or updates a product including its attributes, options and combinations. The request is processed asynchronously (HTTP 200 confirms acceptance only). Keep each uploaded import file at or below 10 MB; split larger combination datasets into chunks via POST /api/products/combinations. The category_id is optional — if it does not match an existing category, the product is assigned to the default category. default_combination_options is a list of plain option ids (not attribute:option pairs).

Request body:

{
  "key": "ext-product-001",
  "category_id": "524a63eb-9276-4021-bdf0-b81ac79d7886",
  "currency": "EUR",
  "country_code": "DE",
  "name": "Broschüre Softcover",
  "characteristics": "Klebegebundene Broschüre mit Softcover-Umschlag, individuell konfigurierbar nach Seitenzahl (Sorten) und Bandierung.",
  "info": "Lieferzeit gemäß Combination-Quantity.",
  "product_number": "BR-SC-001",
  "product_period": 5,
  "product_type": "standard",
  "fix_price": 0,
  "seo_url": "broschuere-softcover",
  "shipping_packing_info": "Versand in stabiler Kartonage.",
  "canonical_url": "https://example.com/shop/broschuere-softcover",
  "browser_title": "Broschüre Softcover online drucken",
  "meta_key_words": "broschüre, softcover, klebebindung, drucken",
  "meta_description": "Broschüre Softcover online bestellen - individuell konfigurierbar, schnelle Lieferung.",

  "default_combination_options": [
    "31a01984-a294-4232-a5ad-726dab86f04e",
    "8bc1c0ac-e8ff-46f2-8f68-0d0bdcf5aaa6"
  ],

  "dependable_attributes": [
    {
      "attribute_id": "c1c3928e-7dc3-4301-bc9a-7dab73d5d520",
      "external_id": "umschlag",
      "options": [
        { "option_id": "3eece221-bcc2-48d6-b95e-acc6e4d08f1d", "external_id": "umschlag" },
        { "option_id": "1fdcc732-a555-4dda-8a9d-b6d531801103", "external_id": "zusatz" }
      ]
    }
  ],

  "independent_options": [
    {
      "option_id": "7faf89ba-c84d-4759-bae7-7af2c0617b58",
      "price": 0.00,
      "external_attribute_id": "bandieren",
      "external_option_id": "zweck"
    },
    {
      "option_id": "bf028a59-0ac6-483a-8f88-c5a26754f001",
      "price": 2.50,
      "external_attribute_id": "bandieren",
      "external_option_id": "50"
    },
    {
      "option_id": "13b644d5-e26a-4e9a-a85f-2604768f07cc",
      "price": 4.90,
      "external_attribute_id": "bandieren",
      "external_option_id": "100"
    }
  ],

  "product_variants": [
    {
      "product_data_sheet": "https://example.com/datasheets/br-sc-001.pdf",
      "current_version": "sha1-of-variant-attributes",
      "attributes": [
        { "attribute_key": "product_type", "option_key": "softcover" },
        { "attribute_key": "sorten", "option_key": "2" }
      ],
      "quantities": [
        {
          "quantity_id": "31a01984-a294-4232-a5ad-726dab86f04e",
          "quantity_value": "100",
          "delivery": {
            "de": {
              "1aba2af1-6ba0-4c69-911c-4f8c1bb0361e": {
                "price": 7.90,
                "shipping_price": 4.90,
                "delivery_days": 3
              },
              "5ad9ce9d-d77a-4125-b0cc-7f8dcfeacaa2": {
                "price": 7.90,
                "shipping_price": 9.90,
                "delivery_days": 1
              },
              "5ceb103a-2a98-4e62-b183-8e442e43abdd": {
                "price": 7.90,
                "shipping_price": 14.90,
                "delivery_days": 1
              }
            },
            "at": {
              "1aba2af1-6ba0-4c69-911c-4f8c1bb0361e": {
                "price": 7.90,
                "shipping_price": 6.90,
                "delivery_days": 4
              }
            }
          }
        },
        {
          "quantity_id": "e1468d50-0a4e-451c-bb7e-496632ef2424",
          "quantity_value": "250",
          "delivery": {
            "de": {
              "1aba2af1-6ba0-4c69-911c-4f8c1bb0361e": {
                "price": 12.90,
                "shipping_price": 4.90,
                "delivery_days": 3
              }
            }
          }
        }
      ]
    }
  ],

  "product_image": "https://example.com/images/br-sc-001.jpg",
  "product_icon": "https://example.com/icons/br-sc-001.png",
  "product_upload": "https://example.com/uploads/br-sc-001-template.pdf"
}

2. Create or update an attribute

Endpoint: POST /api/attributes

Auth: ROLE_INTERNAL_ADMIN

Source file: 02_create_attribute.json

The combination of key + service_provider_id identifies the attribute (update if it exists, otherwise create). Required: service_provider_id, key, name, category_id.

Request body:

{
  "service_provider_id": "sp1111111-1111-1111-1111-111111111111",
  "key": "color",
  "name": "Farbe",
  "description": "Hauptfarbvariante des Produkts",
  "sort": 10,
  "category": "none",
  "category_id": "cbcfedc9-3435-4c36-a078-0d02d3c144b3",
  "attribute_style": "normal",
  "attribute_type": "other"
}

3. Add or update an option

Endpoint: POST /api/attributes/options

Auth: ROLE_INTERNAL_ADMIN

Source file: 03_create_option.json

The parent attribute is referenced by its string attribute_key (not the UUID). Required: service_provider_id, attribute_key, key, name. For quantity options send meta: {"quantity": <int>}.

Request body:

{
  "service_provider_id": "sp1111111-1111-1111-1111-111111111111",
  "attribute_key": "color",
  "key": "red",
  "name": "Rot",
  "description": "Leuchtendes Rot, Pantone 485 C",
  "sort": 20,
  "icon_name": "swatch_red",
  "meta": {
    "hex": "#ED1C24"
  }
}

4. Update the service-provider metadata of an attribute

Endpoint: PATCH /api/serviceproviders/{serviceproviderId}/attributes/{attributeId}

Auth: ROLE_MANUFACTURER_ADMIN

Source file: 04_sp_patch_attribute.json

Sets the service-provider-specific metadata of an existing attribute. All body fields are optional — only the fields actually present are applied. Send only what you want to change.

Request body:

{
  "name": "Versand",
  "sort": 9999,
  "sort_type": 1,
  "category_id": "27e34d25-7982-47a6-8d54-f785056d843b",
  "attribute_style": "list",
  "external_id": "shipping",
  "external_id2": "legacy_shipping_15"
}

5. Update the service-provider metadata of an option

Endpoint: PATCH /api/serviceproviders/{serviceproviderId}/options/{optionId}

Auth: ROLE_MANUFACTURER_ADMIN

Source file: 05_sp_patch_option.json

Sets the service-provider-specific metadata of an existing option. All body fields are optional — only the fields actually present are applied.

Request body:

{
  "name": "Standard",
  "sort": 40,
  "icon_name": "",
  "is_highlight": false,
  "external_id": "standard",
  "external_id2": "legacy_shipping_std"
}

6. Update the service-provider metadata of an attribute category

Endpoint: PATCH /api/serviceproviders/{serviceproviderId}/attributecategories/{attributeCategoryId}

Auth: ROLE_MANUFACTURER_ADMIN

Source file: 06_sp_patch_attributecategory.json

Sets the service-provider-specific metadata of an existing attribute category. All body fields are optional.

Request body:

{
  "name": "Versand",
  "sort": 40
}

1. Product import — create or update a product#

2. Create or update an attribute#

3. Add or update an option#

4. Update the service-provider metadata of an attribute#

5. Update the service-provider metadata of an option#

6. Update the service-provider metadata of an attribute category#

1. Product import — create or update a product

2. Create or update an attribute

3. Add or update an option

4. Update the service-provider metadata of an attribute

5. Update the service-provider metadata of an option

6. Update the service-provider metadata of an attribute category