The latest version of the Cin7 Core API (V2) is available, with more advanced functionality and support for recent system changes. See the full API documentation to get started.
The BillOfMaterials resource allows Products BOM to be listed, created, updated, and deleted. Here are some example URIs:
- /BillOfMaterials/E6E8163F-6911-40e9-B740-90E5A0A3A996 - returns BOM of a particular Product;
- /BillOfMaterials?page=2 - returns the second page of 100 Products with BOM;
- /BillOfMaterials - returns the first 100 Products with BOM because page number 1 is the default;
- /BillOfMaterials?page=2&limit=500 - returns the second page of 500 Products with BOM; i.e. the 501st to 1000th;
- /BillOfMaterials?sku=ABC - returns BOM of the product with specified sku;
The full range of URIs and HTTP Verbs supported are:
| Operation | HTTP Action |
|---|---|
| List of paginated products with BOM | GET /BillOfMaterials?page={pageNumber} |
| View any Product with BOM | GET /BillOfMaterials/{id} |
| Update a set of Product BOMs. Product attributes are updated and BOM entries of the product are synced with provided BOM. | PUT /BillOfMaterials |
For PUT action, you always need to supply the full BOM for each product, otherwise if some BOM line is not provided then these BOM components will be deleted. This action automatically deletes, creates or updates product BOM to sync data in the system with provided BOM for each product.
These filters can be used with the GET BillOfMaterials endpoint:
| Filter | Description |
|---|---|
| limit | Specifies the page size for pagination. Default page size is 100 Products. |
| name | Only return Products that start with the specific Product name |
| sku | Return one Product that has provided sku |
| onlyProductsWithBOM | Only return Products with BOM defined |
| includeDeprecated | Returns all Products, including deprecated, if set to true. If set to false or if it is not specified then returns only active (i.e. non-deprecated) Products |
Filters are used by adding the filter and value to the URI: /BillOfMaterials?name=ABC&onlyProductsWithBOM=true
Using PUT action:
With PUT action you can delete/create/update BOM components and services for multiple products at once:
{ Products: [{...}, {...},...] }
Up to 100 Products can be updated in one batch.
As a result of the call to PUT action you will get the following response:
{ "Products": [ { ..., "OperationStatus":"failed", "Errors": [ {"ErrorText":"Supplier with specified name does not exist"} ], BOMComponents: [{…}, {…},…], BOMServices: [{…}, {…},…] }, { ..., "OperationStatus":"succeeded", "Errors": [], BOMComponents: [{…}, {…},…], BOMServices: [{…}, {…},…] }, … ] }
Where “errors” property for every Product in a batch indicates problems executing sync of BOM. If “errors” array property has no items then operation completed successfully. You can also check “operationStatus” property to find out if specific action in a batch succeeded or failed.
Available Fields for Product:
| Property | Type | Length | Required | Notes |
|---|---|---|---|---|
| BOMComponents (see below) | ||||
| BOMServices (see below) | ||||
| Errors (see below) | ||||
| ID | Guid | Yes | Unique Product ID | |
| OperationStatus | String | Read-only field. Empty in Get action result and one of two possible values as a result of PUT action: “failed” or “succeeded” | ||
| SKU | String | Product SKU. Read-only field, only returned in GET action. Ignored by PUT action | ||
| Name | String | Product Name. Read-only field, only returned in GET action. Ignored by PUT action | ||
| BillOfMaterials | Boolean | Yes | “true” if this product has BOM, “false” otherwise. When BillOfMaterials = “true” there should be at least one component of service associated with this product |
|
| AutoAssembly | Boolean | Yes | “true” if this product is a kit or needs to be automatically assembled on sale order authorization. BillOfMaterials must be “true” when AutoAssembly = “true”. Can be used to implement unit conversion. | |
| AutoDisassembly | Boolean | Yes | “true” if this product needs to be disassembled automatically into BOM on purchase authorization. Can be used to implement unit conversion. BillOfMaterials must be “true” when AutoDisassembly = “true”. | |
| QuantityToProduce | Decimal (up to 10 decimal places) | Quantity of the product to be produced by its BOM. Default is 1. | ||
| Status | String | Product status. “Active” or “Deprecated”. Read-only field, only returned in GET action. Ignored by PUT action |
BOMComponent:
| Property | Type | Length | Required | Notes |
|---|---|---|---|---|
| ProductID | Guid | Yes | Unique product ID. Product identifier by this ID must be active and should be of type “Stock”. | |
| SKU | String | 50 | BOM Component SKU. Read-only field. Ignored on PUT action | |
| Name | String | 256 | BOM Component Name. Read-only field. Ignored on PUT action | |
| Quantity | Decimal (up to 10 decimal places) | Yes | Quantity of the component required to produce QuantityToProduce amount of the product. | |
| WastagePercent | Decimal (up to 10 decimal places) | Wastage percentage of this component when assembling the product. WastagePercent and WastageQuantity are mutually exclusive. 0 by default. | ||
| WastageQuantity | Decimal (up to 10 decimal places) | Wastage quantity of this component when assembling the product. WastagePercent and WastageQuantity are mutually exclusive. 0 by default. | ||
| CostPercentage | Money | This value is used to create custom cost proportion between different components in the same BOM when disassembly task is created. Default is 0. If all components is BOM have 0 CostPercentage then in Disassembly cost will be distributed evenly between components. |
BOMServices:
| Property | Type | Length | Required | Notes |
|---|---|---|---|---|
| ProductID | Guid | Yes | Unique product ID. Product identifier by this ID must be active and should be of type “Service”. | |
| Name | String | 256 | BOM Service Name. Read-only field. Ignored on PUT action | |
| Quantity | Decimal (up to 10 decimal places) | Yes | Quantity of the service required to produce QuantityToProduce amount of the product. | |
| PriceTier | Integer | Price tier number that defines this service cost per unit when producing the product. | ||
| ExpenseAccount | String | 50 | Yes | Code of active Expense account used when Finished Goods / Disassembly transactions |
Errors:
| Property | Type | Length | Required | Notes |
|---|---|---|---|---|
| ErrorText | String | Read-only field indicating problem when executing action on associated entity |