ConnectCloud Developers

Create an article (tenant:masterdata:write)

POST /api/masterdata/products

Module: Master data · operationId: createProduct · Tag: Articles · Auth: access token (Authorization: Bearer <accessToken>)

Stores a new article with its sales price and suppliers. An empty articleNumber is assigned from the PRODUCT number range, an empty searchTerm is derived from the short name, an empty articleType is GOODS, a priceQuantity of 0 is 1. shortName is required; GOODS, SERVICE and FEE also need productGroupId, unitCode, taxKeyCode and salesPrice (0 is allowed; unit and tax key may come from the product group), SUBSCRIPTION in addition svcBilling (not NONE), svcBillingCycleMonths and svcTermMonths. TEXT articles need nothing; their group, tax key and prices are cleared. A missing field answers 400 naming it. The first supplier becomes the default supplier. Emits masterdata.product.created.

Request body

application/json (required)

  • shortName (string, required): Kurzbezeichnung: required, one line (no line breaks); the name in lists, pickers and trade records (max length 80)
  • accounting (object, read-only): Resolved revenue account and cost center (only on the single article, not in lists)
  • articleNumber (string): Unique per tenant; assigned from the PRODUCT range when empty (max length 64)
  • articleType (string): Article type; decides the required fields (one of GOODS, SERVICE, SUBSCRIPTION, TEXT, FEE; default "GOODS")
  • basePriceUnit (string): Unit of the base price
  • blockReason (string): Reason of the block (max length 255)
  • blockedFrom (string (date), nullable): First day of the block (YYYY-MM-DD)
  • blockedUntil (string (date), nullable): After blockedFrom
  • commissionRate (number, nullable): Commission in percent
  • contentQuantity (number, nullable): Content quantity (for the base price)
  • contentUnit (string): Unit of the content quantity
  • createdAt (string (date-time), read-only): Creation time
  • createdBy (string, read-only): Who created the article (subject of the token)
  • customerNo (string, read-only): Tenant customer number (from the token)
  • customsTariffNo (string): Customs tariff number
  • defaultSupplierId (string (uuid), read-only): Id of the default supplier link
  • defaultWarehouseCode (string): Default warehouse
  • description (string): Beschreibung: long text without limit
  • dimensionUnit (string): Unit of length, width and height (one of MM, CM, M)
  • ean (string): EAN/GTIN with 8, 12, 13 or 14 digits and check digit
  • height (number, nullable): Height in dimensionUnit
  • id (string (uuid), read-only): Id of the article
  • isBatchTracked (boolean): Only for GOODS
  • isBlocked (boolean): Blocked article
  • isCommissionEligible (boolean): Commission is paid
  • isDiscountEligible (boolean): Discounts may be granted
  • isSerialTracked (boolean): Only for GOODS
  • isSkontoEligible (boolean): Cash discount (Skonto) may be granted
  • isStockItem (boolean): Only for GOODS
  • length (number, nullable): Length in dimensionUnit
  • manufacturerAddressId (string (uuid), nullable): Manufacturer address
  • manufacturerName (string): Manufacturer name (max length 255)
  • manufacturerPartNumber (string): Manufacturer part number (MPN) (max length 64)
  • memo (string): Internal memo
  • minPrice (number, nullable): Lowest net price the article may be sold for; not above salesPrice
  • name (string): Bezeichnung: optional, may span several lines; documents use shortName when empty (max length 2000)
  • originCountryCode (string): Country of origin (ISO 3166-1 alpha-2)
  • priceQuantity (number): Quantity the sales price refers to (default 1)
  • productGroupId (string (uuid), nullable): Required except for TEXT (cleared there)
  • productGroupName (string, read-only): Name of the product group
  • purchasePrice (number, read-only): Purchase price of the default supplier
  • salesPrice (number, nullable): Net sales price per priceQuantity; required (0 is allowed) except for TEXT (cleared there)
  • searchTerm (string): Upper-cased short name (first 255 characters) when empty (max length 255)
  • specialPrice (number, nullable): Net special price; not below minPrice and not above salesPrice
  • specialValidFrom (string (date), nullable): First day of the special price (dropped without specialPrice)
  • specialValidTo (string (date), nullable): Last day of the special price; not before specialValidFrom
  • suppliers (array of ProductSupplier): Suppliers with one purchase price each
    • purchasePrice (number, required): Net purchase price
    • supplierAddressId (string (uuid), required): Supplier address; once per article
    • currencyCode (string): Currency of the purchase price (ISO 4217)
    • deliveryDays (integer, nullable): Delivery time in days
    • id (string (uuid)): Id of the supplier link
    • isDefault (boolean): At most one; the first supplier is the default when none is set
    • lastPurchaseAt (string (date), nullable): Date of the last purchase (YYYY-MM-DD)
    • minOrderQty (number, nullable): Minimum order quantity
    • orderUnitCode (string): Order unit (code of units)
    • supplierArticleNumber (string): The supplier's article number (max length 64)
    • supplierName (string, read-only): Display name of the supplier address
  • svcAutoRenew (boolean): Subscription renews automatically
  • svcBilling (string): Must not be NONE for SUBSCRIPTION (one of NONE, ADVANCE, ARREARS; default "NONE")
  • svcBillingCycleMonths (integer, nullable): Billing cycle; required for SUBSCRIPTION (max 120)
  • svcNoticePeriodMonths (integer, nullable): Notice period of the subscription in months
  • svcTermMonths (integer, nullable): Subscription term; required for SUBSCRIPTION
  • syncStatus (string, read-only): Reserved for an ERP synchronisation; STANDALONE for records of this API (one of STANDALONE, PENDING_CREATION, PENDING_UPDATE, SYNCED, CONFLICT, ERROR)
  • taxKeyCode (string): Code of tax-keys; empty takes the product group's default tax key; required except for TEXT (cleared there)
  • tenantName (string, read-only): Tenant name (from the token)
  • unitCode (string): Code of units; empty takes the product group's default unit; required except for TEXT
  • updatedAt (string (date-time), read-only): Time of the last change
  • updatedBy (string, read-only): Who changed the article last (subject of the token)
  • version (integer): Optimistic locking version (ignored on create)
  • weightKg (number, nullable): Weight in kg
  • width (number, nullable): Width in dimensionUnit

Example:

{
  "articleType": "GOODS",
  "ean": "5397184440988",
  "isStockItem": true,
  "manufacturerName": "Dell",
  "manufacturerPartNumber": "P2422H",
  "name": "Monitor 24\" Full HD\nIPS, 75 Hz, HDMI und DisplayPort",
  "productGroupId": "8d0b6f3e-2c4a-4e7b-9a1d-5f3c2e1b0a97",
  "salesPrice": 189,
  "shortName": "Monitor 24\" Full HD",
  "suppliers": [
    {
      "currencyCode": "EUR",
      "isDefault": true,
      "purchasePrice": 142.5,
      "supplierAddressId": "3f6c1a52-7b1e-4d2a-9c8e-2b5f0d6a91e4",
      "supplierArticleNumber": "700-P2422H"
    }
  ],
  "taxKeyCode": "STANDARD",
  "unitCode": "STK"
}

Responses

  • 201 Created (application/json)
  • 400 Malformed body or query parameter (application/json)
  • 401 Missing, invalid or expired token (empty body)
  • 403 The token lacks the permission or carries no tenant (application/json)
  • 409 Stale version or conflict with existing data (application/json)
  • 413 The body is over the limit (2 MiB; AI drafts 4 MiB) (application/json)

Fields of the 201 answer:

  • shortName (string, required): Kurzbezeichnung: required, one line (no line breaks); the name in lists, pickers and trade records (max length 80)
  • accounting (object, read-only): Resolved revenue account and cost center (only on the single article, not in lists)
  • articleNumber (string): Unique per tenant; assigned from the PRODUCT range when empty (max length 64)
  • articleType (string): Article type; decides the required fields (one of GOODS, SERVICE, SUBSCRIPTION, TEXT, FEE; default "GOODS")
  • basePriceUnit (string): Unit of the base price
  • blockReason (string): Reason of the block (max length 255)
  • blockedFrom (string (date), nullable): First day of the block (YYYY-MM-DD)
  • blockedUntil (string (date), nullable): After blockedFrom
  • commissionRate (number, nullable): Commission in percent
  • contentQuantity (number, nullable): Content quantity (for the base price)
  • contentUnit (string): Unit of the content quantity
  • createdAt (string (date-time), read-only): Creation time
  • createdBy (string, read-only): Who created the article (subject of the token)
  • customerNo (string, read-only): Tenant customer number (from the token)
  • customsTariffNo (string): Customs tariff number
  • defaultSupplierId (string (uuid), read-only): Id of the default supplier link
  • defaultWarehouseCode (string): Default warehouse
  • description (string): Beschreibung: long text without limit
  • dimensionUnit (string): Unit of length, width and height (one of MM, CM, M)
  • ean (string): EAN/GTIN with 8, 12, 13 or 14 digits and check digit
  • height (number, nullable): Height in dimensionUnit
  • id (string (uuid), read-only): Id of the article
  • isBatchTracked (boolean): Only for GOODS
  • isBlocked (boolean): Blocked article
  • isCommissionEligible (boolean): Commission is paid
  • isDiscountEligible (boolean): Discounts may be granted
  • isSerialTracked (boolean): Only for GOODS
  • isSkontoEligible (boolean): Cash discount (Skonto) may be granted
  • isStockItem (boolean): Only for GOODS
  • length (number, nullable): Length in dimensionUnit
  • manufacturerAddressId (string (uuid), nullable): Manufacturer address
  • manufacturerName (string): Manufacturer name (max length 255)
  • manufacturerPartNumber (string): Manufacturer part number (MPN) (max length 64)
  • memo (string): Internal memo
  • minPrice (number, nullable): Lowest net price the article may be sold for; not above salesPrice
  • name (string): Bezeichnung: optional, may span several lines; documents use shortName when empty (max length 2000)
  • originCountryCode (string): Country of origin (ISO 3166-1 alpha-2)
  • priceQuantity (number): Quantity the sales price refers to (default 1)
  • productGroupId (string (uuid), nullable): Required except for TEXT (cleared there)
  • productGroupName (string, read-only): Name of the product group
  • purchasePrice (number, read-only): Purchase price of the default supplier
  • salesPrice (number, nullable): Net sales price per priceQuantity; required (0 is allowed) except for TEXT (cleared there)
  • searchTerm (string): Upper-cased short name (first 255 characters) when empty (max length 255)
  • specialPrice (number, nullable): Net special price; not below minPrice and not above salesPrice
  • specialValidFrom (string (date), nullable): First day of the special price (dropped without specialPrice)
  • specialValidTo (string (date), nullable): Last day of the special price; not before specialValidFrom
  • suppliers (array of ProductSupplier): Suppliers with one purchase price each
    • purchasePrice (number, required): Net purchase price
    • supplierAddressId (string (uuid), required): Supplier address; once per article
    • currencyCode (string): Currency of the purchase price (ISO 4217)
    • deliveryDays (integer, nullable): Delivery time in days
    • id (string (uuid)): Id of the supplier link
    • isDefault (boolean): At most one; the first supplier is the default when none is set
    • lastPurchaseAt (string (date), nullable): Date of the last purchase (YYYY-MM-DD)
    • minOrderQty (number, nullable): Minimum order quantity
    • orderUnitCode (string): Order unit (code of units)
    • supplierArticleNumber (string): The supplier's article number (max length 64)
    • supplierName (string, read-only): Display name of the supplier address
  • svcAutoRenew (boolean): Subscription renews automatically
  • svcBilling (string): Must not be NONE for SUBSCRIPTION (one of NONE, ADVANCE, ARREARS; default "NONE")
  • svcBillingCycleMonths (integer, nullable): Billing cycle; required for SUBSCRIPTION (max 120)
  • svcNoticePeriodMonths (integer, nullable): Notice period of the subscription in months
  • svcTermMonths (integer, nullable): Subscription term; required for SUBSCRIPTION
  • syncStatus (string, read-only): Reserved for an ERP synchronisation; STANDALONE for records of this API (one of STANDALONE, PENDING_CREATION, PENDING_UPDATE, SYNCED, CONFLICT, ERROR)
  • taxKeyCode (string): Code of tax-keys; empty takes the product group's default tax key; required except for TEXT (cleared there)
  • tenantName (string, read-only): Tenant name (from the token)
  • unitCode (string): Code of units; empty takes the product group's default unit; required except for TEXT
  • updatedAt (string (date-time), read-only): Time of the last change
  • updatedBy (string, read-only): Who changed the article last (subject of the token)
  • version (integer): Optimistic locking version (ignored on create)
  • weightKg (number, nullable): Weight in kg
  • width (number, nullable): Width in dimensionUnit

Example 201 answer:

{
  "accounting": {
    "costCenter": "4200",
    "costCenterSource": "GROUP",
    "revenueAccount": "4400",
    "source": "GROUP",
    "sourceGroupCode": "HARDWARE",
    "taxKeyCode": "STANDARD"
  },
  "articleNumber": "HW-1004",
  "articleType": "GOODS",
  "createdAt": "2026-01-02T08:00:00Z",
  "createdBy": "laura.kaestner@muster-it.example",
  "customerNo": "99999",
  "defaultSupplierId": "7a9c1e3a-5b7d-4f9a-8c1e-3a5b7d9f1a3c",
  "ean": "4061234500045",
  "id": "6e8a0c2e-4f6a-4b8c-8d0e-2f4a6c8e0a2c",
  "isBatchTracked": false,
  "isBlocked": false,
  "isCommissionEligible": false,
  "isDiscountEligible": true,
  "isSerialTracked": false,
  "isSkontoEligible": true,
  "isStockItem": true,
  "manufacturerName": "Nordlicht IT-Distribution",
  "manufacturerPartNumber": "NL-DOCKC100",
  "name": "USB-C Dockingstation 100 W\n2 × DisplayPort, HDMI, 4 × USB-A, Gigabit-LAN",
  "priceQuantity": 1,
  "productGroupId": "8d0b6f3e-2c4a-4e7b-9a1d-5f3c2e1b0a97",
  "productGroupName": "Hardware",
  "purchasePrice": 139,
  "salesPrice": 189,
  "searchTerm": "DOCKINGSTATION USB-C",
  "shortName": "USB-C Dockingstation 100 W",
  "suppliers": [
    {
      "currencyCode": "EUR",
      "deliveryDays": 2,
      "id": "9c1e3a5c-7d9f-4b1c-8e3a-5c7d9f1b3c5e",
      "isDefault": true,
      "lastPurchaseAt": "2026-09-23",
      "minOrderQty": 1,
      "orderUnitCode": "STK",
      "purchasePrice": 139,
      "supplierAddressId": "7a9c1e3a-5b7d-4f9a-8c1e-3a5b7d9f1a3c",
      "supplierArticleNumber": "NL-DOCKC100",
      "supplierName": "Nordlicht IT-Distribution GmbH"
    }
  ],
  "svcBilling": "NONE",
  "syncStatus": "STANDALONE",
  "taxKeyCode": "STANDARD",
  "tenantName": "DEMO",
  "unitCode": "STK",
  "updatedAt": "2026-10-07T13:12:00Z",
  "updatedBy": "laura.kaestner@muster-it.example",
  "version": 4,
  "weightKg": 0.48
}

Example request

curl -X POST 'https://api.mbcom.cloud/api/masterdata/products' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"articleType":"GOODS","ean":"5397184440988","isStockItem":true,"manufacturerName":"Dell","manufacturerPartNumber":"P2422H","name":"Monitor 24\" Full HD\nIPS, 75 Hz, HDMI und DisplayPort","productGroupId":"8d0b6f3e-2c4a-4e7b-9a1d-5f3c2e1b0a97","salesPrice":189,"shortName":"Monitor 24\" Full HD","suppliers":[{"currencyCode":"EUR","isDefault":true,"purchasePrice":142.5,"supplierAddressId":"3f6c1a52-7b1e-4d2a-9c8e-2b5f0d6a91e4","supplierArticleNumber":"700-P2422H"}],"taxKeyCode":"STANDARD","unitCode":"STK"}'

View as Markdown · Interactive reference · OpenAPI