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 ofGOODS,SERVICE,SUBSCRIPTION,TEXT,FEE; default"GOODS")basePriceUnit(string): Unit of the base priceblockReason(string): Reason of the block (max length 255)blockedFrom(string (date), nullable): First day of the block (YYYY-MM-DD)blockedUntil(string (date), nullable): AfterblockedFromcommissionRate(number, nullable): Commission in percentcontentQuantity(number, nullable): Content quantity (for the base price)contentUnit(string): Unit of the content quantitycreatedAt(string (date-time), read-only): Creation timecreatedBy(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 numberdefaultSupplierId(string (uuid), read-only): Id of the default supplier linkdefaultWarehouseCode(string): Default warehousedescription(string): Beschreibung: long text without limitdimensionUnit(string): Unit of length, width and height (one ofMM,CM,M)ean(string): EAN/GTIN with 8, 12, 13 or 14 digits and check digitheight(number, nullable): Height indimensionUnitid(string (uuid), read-only): Id of the articleisBatchTracked(boolean): Only for GOODSisBlocked(boolean): Blocked articleisCommissionEligible(boolean): Commission is paidisDiscountEligible(boolean): Discounts may be grantedisSerialTracked(boolean): Only for GOODSisSkontoEligible(boolean): Cash discount (Skonto) may be grantedisStockItem(boolean): Only for GOODSlength(number, nullable): Length indimensionUnitmanufacturerAddressId(string (uuid), nullable): Manufacturer addressmanufacturerName(string): Manufacturer name (max length 255)manufacturerPartNumber(string): Manufacturer part number (MPN) (max length 64)memo(string): Internal memominPrice(number, nullable): Lowest net price the article may be sold for; not abovesalesPricename(string): Bezeichnung: optional, may span several lines; documents useshortNamewhen empty (max length 2000)originCountryCode(string): Country of origin (ISO 3166-1 alpha-2)priceQuantity(number): Quantity the sales price refers to (default1)productGroupId(string (uuid), nullable): Required except for TEXT (cleared there)productGroupName(string, read-only): Name of the product grouppurchasePrice(number, read-only): Purchase price of the default suppliersalesPrice(number, nullable): Net sales price perpriceQuantity; 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 belowminPriceand not abovesalesPricespecialValidFrom(string (date), nullable): First day of the special price (dropped withoutspecialPrice)specialValidTo(string (date), nullable): Last day of the special price; not beforespecialValidFromsuppliers(array of ProductSupplier): Suppliers with one purchase price eachpurchasePrice(number, required): Net purchase pricesupplierAddressId(string (uuid), required): Supplier address; once per articlecurrencyCode(string): Currency of the purchase price (ISO 4217)deliveryDays(integer, nullable): Delivery time in daysid(string (uuid)): Id of the supplier linkisDefault(boolean): At most one; the first supplier is the default when none is setlastPurchaseAt(string (date), nullable): Date of the last purchase (YYYY-MM-DD)minOrderQty(number, nullable): Minimum order quantityorderUnitCode(string): Order unit (code ofunits)supplierArticleNumber(string): The supplier's article number (max length 64)supplierName(string, read-only): Display name of the supplier address
svcAutoRenew(boolean): Subscription renews automaticallysvcBilling(string): Must not be NONE for SUBSCRIPTION (one ofNONE,ADVANCE,ARREARS; default"NONE")svcBillingCycleMonths(integer, nullable): Billing cycle; required for SUBSCRIPTION (max 120)svcNoticePeriodMonths(integer, nullable): Notice period of the subscription in monthssvcTermMonths(integer, nullable): Subscription term; required for SUBSCRIPTIONsyncStatus(string, read-only): Reserved for an ERP synchronisation; STANDALONE for records of this API (one ofSTANDALONE,PENDING_CREATION,PENDING_UPDATE,SYNCED,CONFLICT,ERROR)taxKeyCode(string): Code oftax-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 ofunits; empty takes the product group's default unit; required except for TEXTupdatedAt(string (date-time), read-only): Time of the last changeupdatedBy(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 kgwidth(number, nullable): Width indimensionUnit
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 ofGOODS,SERVICE,SUBSCRIPTION,TEXT,FEE; default"GOODS")basePriceUnit(string): Unit of the base priceblockReason(string): Reason of the block (max length 255)blockedFrom(string (date), nullable): First day of the block (YYYY-MM-DD)blockedUntil(string (date), nullable): AfterblockedFromcommissionRate(number, nullable): Commission in percentcontentQuantity(number, nullable): Content quantity (for the base price)contentUnit(string): Unit of the content quantitycreatedAt(string (date-time), read-only): Creation timecreatedBy(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 numberdefaultSupplierId(string (uuid), read-only): Id of the default supplier linkdefaultWarehouseCode(string): Default warehousedescription(string): Beschreibung: long text without limitdimensionUnit(string): Unit of length, width and height (one ofMM,CM,M)ean(string): EAN/GTIN with 8, 12, 13 or 14 digits and check digitheight(number, nullable): Height indimensionUnitid(string (uuid), read-only): Id of the articleisBatchTracked(boolean): Only for GOODSisBlocked(boolean): Blocked articleisCommissionEligible(boolean): Commission is paidisDiscountEligible(boolean): Discounts may be grantedisSerialTracked(boolean): Only for GOODSisSkontoEligible(boolean): Cash discount (Skonto) may be grantedisStockItem(boolean): Only for GOODSlength(number, nullable): Length indimensionUnitmanufacturerAddressId(string (uuid), nullable): Manufacturer addressmanufacturerName(string): Manufacturer name (max length 255)manufacturerPartNumber(string): Manufacturer part number (MPN) (max length 64)memo(string): Internal memominPrice(number, nullable): Lowest net price the article may be sold for; not abovesalesPricename(string): Bezeichnung: optional, may span several lines; documents useshortNamewhen empty (max length 2000)originCountryCode(string): Country of origin (ISO 3166-1 alpha-2)priceQuantity(number): Quantity the sales price refers to (default1)productGroupId(string (uuid), nullable): Required except for TEXT (cleared there)productGroupName(string, read-only): Name of the product grouppurchasePrice(number, read-only): Purchase price of the default suppliersalesPrice(number, nullable): Net sales price perpriceQuantity; 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 belowminPriceand not abovesalesPricespecialValidFrom(string (date), nullable): First day of the special price (dropped withoutspecialPrice)specialValidTo(string (date), nullable): Last day of the special price; not beforespecialValidFromsuppliers(array of ProductSupplier): Suppliers with one purchase price eachpurchasePrice(number, required): Net purchase pricesupplierAddressId(string (uuid), required): Supplier address; once per articlecurrencyCode(string): Currency of the purchase price (ISO 4217)deliveryDays(integer, nullable): Delivery time in daysid(string (uuid)): Id of the supplier linkisDefault(boolean): At most one; the first supplier is the default when none is setlastPurchaseAt(string (date), nullable): Date of the last purchase (YYYY-MM-DD)minOrderQty(number, nullable): Minimum order quantityorderUnitCode(string): Order unit (code ofunits)supplierArticleNumber(string): The supplier's article number (max length 64)supplierName(string, read-only): Display name of the supplier address
svcAutoRenew(boolean): Subscription renews automaticallysvcBilling(string): Must not be NONE for SUBSCRIPTION (one ofNONE,ADVANCE,ARREARS; default"NONE")svcBillingCycleMonths(integer, nullable): Billing cycle; required for SUBSCRIPTION (max 120)svcNoticePeriodMonths(integer, nullable): Notice period of the subscription in monthssvcTermMonths(integer, nullable): Subscription term; required for SUBSCRIPTIONsyncStatus(string, read-only): Reserved for an ERP synchronisation; STANDALONE for records of this API (one ofSTANDALONE,PENDING_CREATION,PENDING_UPDATE,SYNCED,CONFLICT,ERROR)taxKeyCode(string): Code oftax-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 ofunits; empty takes the product group's default unit; required except for TEXTupdatedAt(string (date-time), read-only): Time of the last changeupdatedBy(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 kgwidth(number, nullable): Width indimensionUnit
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"}'