Product Management
Create and update catalog products: names and descriptions, classification (including reclassifying a master product), specifications, identifiers (UPCs, supplier SKUs, manufacturer SKUs), images, and life cycle.
All requests require a bearer token (see Authentication) and a JSON body with Content-Type: application/json.
The calls in this API are limited to 10 calls per minute to avoid flooding the system. Plan bulk creates and updates around this limit. See Rate Limiting for how limits are applied and what happens when you exceed them (429 Too Many Requests).
Every image URL you send must be publicly accessible, and it must resolve directly to the image file itself (for example https://example.com/front.png). A link to a web page that merely displays or offers the image won't work; the image isn't attached and the problem is reported in Warnings. This is common with file-sharing services such as Dropbox and Google Drive, whose share links open a preview page or a download-request page instead of returning the image.
To check a URL, open it in a private browser window where you're not signed in. It should show only the image, with no surrounding page.
Endpoints
| Endpoint | Description |
|---|---|
| Create Regular Product | Create a standalone product that is sold as-is. |
| Create Master Product with Variants | Create a master product and all of its variants in one call. |
| Add Variant to Master Product | Add one variant to an existing master product. |
| Update Product | Change an existing product's core fields, specifications, identifiers, and images. |
| Reclassify Master Product | Change the classification of an existing master product and all of its variants. |
How values are interpreted
These rules apply to every request on this page. Each endpoint then lists the exact behavior for its own properties.
- Omitted and
nullare always identical. Leaving a property out of the JSON body is the same as sendingnull. - Empty (
""or[]) is not the same as omitted. Where an empty value means something different from omitted, the property is called out explicitly. - Collections are never "replace all". On create, a collection describes what the new product has. On update, a collection lists only the entries you want to change; anything you do not name is left exactly as it is.
- Property names and enumerated values are not case-sensitive.
ProductNameandproductnameare equivalent, as areInactiveandinactive. Identifier values are a separate matter and are described under Identifiers.
| Term | Meaning in this documentation |
|---|---|
| Omitted | The property is absent from the JSON body. |
null | The property is present with the value null. Treated exactly like omitted. |
| Empty | An empty string ("") or an empty array ([]). |
| Unchanged | The existing value on the product is left as it is. |
Create Regular Product
POST /productmanagement/v1/companies/{companyId}/RegularProduct
Creates a standalone product: a master product with no variants that is directly sellable.
Required permission: CanManageCatalog
Example of a call would be:
POST /productmanagement/v1/companies/{companyId}/RegularProduct
Host: api.covasoft.net
Authorization: Bearer {your token}
Accept: application/json
Content-Type: application/json
{
"ProductName": "16oz Widget",
"ShortDescription": "Short copy",
"LongDescription": "Longer marketing copy.",
"IsBatchTracked": false,
"MeasurementType": "SingleUnit",
"RegularPrice": 9.99,
"Classification": { "ClassificationTreeId": 3, "ClassificationId": 12 },
"Specifications": [ { "Id": 5, "Value": "Blue" } ],
"Upcs": [ { "Upc": "001234567890", "Description": "Retail UPC" } ],
"Suppliers": [ { "SupplierId": 7, "SupplierSku": "SKU-1", "Description": "Supplier reference" } ],
"MainImageUrl": "https://example.com/front.png",
"AdditionalImageUrls": [ "https://example.com/back.png" ]
}
Request Information
URI Parameters
| Name | Description | Type | Additional information |
|---|---|---|---|
| companyId | The unique Company Id that was provided in your onboarding package | integer | Required |
Body Parameters
| Name | Type | Required | Omitted, null, or empty |
|---|---|---|---|
| ProductName | string | Yes | Required. 1 to 450 characters; a blank or whitespace-only name is rejected. |
| ShortDescription | string | No | Omitted, null, or "": the product has no short description. Maximum 450 characters. |
| LongDescription | string | No | Omitted, null, or "": the product has no long description. Maximum 20,000 characters. |
| IsBatchTracked | boolean | Yes | Required. Omitting it is rejected. There is no default. |
| MeasurementType | string | Yes | Required. One of the MeasurementType values. Omitted, null, "", or an unknown value is rejected. |
| RegularPrice | decimal | No | Omitted or null: no price is set. When supplied it must be greater than zero; 0 and negative numbers are rejected. |
| Classification | object | Yes | Required. Both ClassificationTreeId and ClassificationId are required. |
| Specifications | array of Specification | No | Omitted, null, or []: no specifications are set. |
| Upcs | array | No | Omitted, null, or []: the product has no UPCs. See Identifier entries. |
| Suppliers | array | No | Omitted, null, or []: the product has no supplier SKUs. See Identifier entries. |
| MainImageUrl | string | No | Omitted, null, or "": no main image. When supplied, the image is downloaded and becomes the product's main (hero) image. |
| AdditionalImageUrls | array of string | No | Omitted, null, or []: no additional images. |
Specification value
Each Specifications entry is { "Id": <field id>, "Value": <text> }.
Idis the specification field's id from the company's catalog configuration.- For fields that offer a fixed list of choices (single select or multi select),
Valueis the display text of the option, for example"Blue". For multi select, supply several options separated by commas, for example"Blue, Red". Matching ignores case and surrounding spaces. If any option text does not match, the request is rejected with a400that names the field and the option that was not found. - For all other field types,
Valueis stored exactly as supplied.
Identifier entries on create
| Property | Used by | Notes |
|---|---|---|
| Upc | Upcs | The UPC value. Maximum 50 characters. |
| SupplierSku | Suppliers | The supplier's SKU. Maximum 50 characters. |
| SupplierId | Suppliers | Optional. Omitted or null creates a supplier SKU that is not associated with a supplier. When supplied, it must be a supplier that exists in the company, otherwise the request is rejected. |
| Description | both | Optional. Omitted, null, or "": no description. Maximum 250 characters. |
Manufacturer SKUs cannot be supplied at creation. Add them afterwards with Update Product.
Response Information
200 OK with the created product. See Product. ProductId, CatalogSku, and MasterProductId are assigned by the server.
If the product is created but the price or an image cannot be applied, the call still succeeds and the problem is described in Warnings. See Warnings.
{
"Name": "16oz Widget",
"ProductId": "5f0ab1de-4f6c-4b0a-9f23-0d7d8f1a2c11",
"CatalogSku": "1000234",
"MasterProductId": 55,
"Warnings": []
}
Create Master Product with Variants
POST /productmanagement/v1/companies/{companyId}/MasterProductWithVariants
Creates a master product and all of its variants in one call. The master carries what the variants have in common (classification, shared specifications, shared images); each variant carries what makes it distinct (measurement, price, its own specifications and identifiers).
Required permission: CanManageCatalog
Example of a call would be:
POST /productmanagement/v1/companies/{companyId}/MasterProductWithVariants
Host: api.covasoft.net
Authorization: Bearer {your token}
Accept: application/json
Content-Type: application/json
{
"MasterProductName": "Widget",
"ShortDescription": "A widget in several colors",
"Classification": { "ClassificationTreeId": 3, "ClassificationId": 12 },
"Specifications": [ { "Id": 8, "Value": "Acme" } ],
"MainImageUrl": "https://example.com/widget.png",
"Variants": [
{
"VariantProductName": "Widget - Blue",
"IsBatchTracked": false,
"MeasurementType": "SingleUnit",
"RegularPrice": 9.99,
"Specifications": [ { "Id": 5, "Value": "Blue" } ],
"Upcs": [ { "Upc": "001234567890" } ]
},
{
"VariantProductName": "Widget - Green",
"IsBatchTracked": false,
"MeasurementType": "SingleUnit",
"RegularPrice": 9.99,
"Specifications": [ { "Id": 5, "Value": "Green" } ]
}
]
}
Request Information
URI Parameters
| Name | Description | Type | Additional information |
|---|---|---|---|
| companyId | The unique Company Id that was provided in your onboarding package | integer | Required |
Body Parameters
| Name | Type | Required | Omitted, null, or empty |
|---|---|---|---|
| MasterProductName | string | Yes | Required. 1 to 450 characters; a blank or whitespace-only name is rejected. |
| ShortDescription | string | No | Omitted, null, or "": no short description on the master. Maximum 450 characters. |
| LongDescription | string | No | Omitted, null, or "": no long description on the master. Maximum 20,000 characters. |
| Classification | object | Yes | Required. Both ClassificationTreeId and ClassificationId are required. Applies to the master and is shared by every variant. |
| Specifications | array | No | Omitted, null, or []: none. Same format as Specification value. |
| Upcs | array | No | Omitted, null, or []: none. Same format as Identifier entries. |
| Suppliers | array | No | Omitted, null, or []: none. Same format as Identifier entries. |
| MainImageUrl | string | No | Omitted, null, or "": no main image on the master. |
| AdditionalImageUrls | array of string | No | Omitted, null, or []: none. |
| Variants | array of Variant | Yes | Required, with at least one entry. Omitted, null, or [] is rejected. |
The master has no IsBatchTracked, MeasurementType, or RegularPrice of its own. Those belong to each variant.
Variant body
Each entry in Variants, and the body of Add a variant:
| Name | Type | Required | Omitted, null, or empty |
|---|---|---|---|
| VariantProductName | string | Yes | Required. 1 to 450 characters; a blank or whitespace-only name is rejected. |
| ShortDescription | string | No | Omitted, null, or "": no short description. Maximum 450 characters. |
| LongDescription | string | No | Omitted, null, or "": no long description. Maximum 20,000 characters. |
| IsBatchTracked | boolean | Yes | Required. Omitting it is rejected. There is no default. |
| MeasurementType | string | Yes | Required. One of the MeasurementType values. |
| RegularPrice | decimal | No | Omitted or null: no price is set. When supplied it must be greater than zero. |
| Specifications | array | No | Omitted, null, or []: none. Same format as Specification value. |
| Upcs | array | No | Omitted, null, or []: none. |
| Suppliers | array | No | Omitted, null, or []: none. |
| MainImageUrl | string | No | Omitted, null, or "": no main image for this variant. |
| AdditionalImageUrls | array of string | No | Omitted, null, or []: none. |
Response Information
200 OK with the created master and its variants. See MasterWithVariants.
Warnings are reported where they occurred: a master image problem appears in the top-level Warnings; a price problem for a variant appears in that variant's Warnings.
{
"Name": "Widget",
"MasterProductId": 55,
"Variants": [
{
"Name": "Widget - Blue",
"ProductId": "5f0ab1de-4f6c-4b0a-9f23-0d7d8f1a2c11",
"CatalogSku": "1000234",
"MasterProductId": 55,
"Warnings": []
},
{
"Name": "Widget - Green",
"ProductId": "b9a1c7e0-34a5-4d6b-8e22-7a1c9b6d3f45",
"CatalogSku": "1000235",
"MasterProductId": 55,
"Warnings": []
}
],
"Warnings": []
}
Add Variant to Master Product
POST /productmanagement/v1/companies/{companyId}/MasterProduct/{masterProductId}/VariantProduct
Adds a single variant to an existing master product. The variant inherits the master's classification.
Required permission: CanManageCatalog
Example of a call would be:
POST /productmanagement/v1/companies/{companyId}/MasterProduct/{masterProductId}/VariantProduct
Host: api.covasoft.net
Authorization: Bearer {your token}
Accept: application/json
Content-Type: application/json
{
"VariantProductName": "Widget - Red",
"IsBatchTracked": false,
"MeasurementType": "SingleUnit",
"RegularPrice": 9.99,
"Specifications": [ { "Id": 5, "Value": "Red" } ],
"Upcs": [ { "Upc": "001234567891" } ],
"MainImageUrl": "https://example.com/red.png"
}
Request Information
URI Parameters
| Name | Description | Type | Additional information |
|---|---|---|---|
| companyId | The unique Company Id that was provided in your onboarding package | integer | Required |
| masterProductId | The id of the master product to add the variant to | integer | Required |
Body Parameters
The body is a Variant body. There is no Classification property: the variant always uses its master's classification.
Response Information
200 OK with the created variant. See Product.
Update Product
PATCH /productmanagement/v1/companies/{companyId}/products/{productId}
Changes an existing product. A single call can change core fields (name, descriptions, life cycle), specifications, identifiers (supplier SKUs, UPCs, manufacturer SKUs), and images.
This is a patch: you describe only the changes you want. Everything you do not mention is left exactly as it is.
Required permission: EditProducts
In this section: Omitted, null, and empty at a glance, Core fields, Specifications, Assets, Identifiers, Order of processing, partial success, and retries, Response, Update errors, Update warnings.
Example of a call would be:
PATCH /productmanagement/v1/companies/{companyId}/products/{productId}
Host: api.covasoft.net
Authorization: Bearer {your token}
Accept: application/json
Content-Type: application/json
{
"Name": "New name",
"ShortDescription": "Updated copy",
"LifeCycle": "Inactive",
"Specifications": {
"Upserts": [ { "Id": 5, "Value": "Blue" } ],
"Deletes": [ 9 ]
},
"Assets": {
"Adds": [ "https://example.com/extra.png" ],
"Deletes": [ "0336721d-5d83-4c5d-bc5b-a0a495b94b72" ]
},
"SupplierSkus": {
"Upserts": [ { "SupplierId": 7, "SupplierSku": "SKU-1", "Description": "Supplier reference" } ],
"Deletes": [ { "SupplierId": 7, "SupplierSku": "OLD-SKU" } ]
},
"UPCs": {
"Upserts": [ { "Upc": "001234567890" } ],
"Deletes": [ { "Upc": "009876543210" } ]
},
"ManufacturerSkus": {
"Upserts": [ { "Sku": "MFR-2" } ],
"Deletes": [ { "Sku": "MFR-1" } ]
}
}
Request Information
URI Parameters
| Name | Description | Type | Additional information |
|---|---|---|---|
| companyId | The unique Company Id that was provided in your onboarding package | integer | Required |
| productId | The product's id (the ProductId returned when it was created) | GUID | Required |
Body Parameters
Every property is optional, but at least one change must be present. A body that contains nothing to change, such as {} or only empty collections, is rejected with a 400.
| Name | Type | Description |
|---|---|---|
| Name | string | New product name. Maximum 450 characters. |
| ShortDescription | string | New short description. Maximum 450 characters. |
| LongDescription | string | New long description. Maximum 20,000 characters. |
| LifeCycle | string | New life cycle. One of the LifeCycle values. |
| Specifications | object | Specification changes: Upserts and Deletes. See Specifications. |
| Assets | object | Image changes: Adds and Deletes. See Assets. |
| SupplierSkus | object | Supplier SKU changes: Upserts and Deletes. See Identifiers. |
| UPCs | object | UPC changes: Upserts and Deletes. See Identifiers. |
| ManufacturerSkus | object | Manufacturer SKU changes: Upserts and Deletes. See Identifiers. |
Omitted, null, and empty at a glance
| Property | Omitted or null | Empty ("" or []) |
|---|---|---|
Name | Unchanged. | Not supported. A product always has a name; do not send an empty Name. |
ShortDescription | Unchanged. | "" clears the short description. |
LongDescription | Unchanged. | "" clears the long description. |
LifeCycle | Unchanged. | "" is not a valid life cycle and is rejected. |
Specifications | No specification changes. | {} is the same as omitted: no changes. |
Specifications.Upserts | No specifications set. | []: no changes. |
Specifications.Deletes | No specifications removed. | []: no changes. |
Specifications.Upserts[].Value | Do not omit. Always supply a value; to remove a value use Deletes. | "" not supported. Use Deletes to remove values. |
Assets, Assets.Adds, Assets.Deletes | No image changes. | {} or []: no changes. |
SupplierSkus, UPCs, ManufacturerSkus | No changes to that identifier type. | {}: no changes. |
Upserts, Deletes (identifiers) | No identifiers added, changed, or removed. | []: no changes. |
Identifier upsert Description | The existing description is kept. A newly created identifier has no description. | "" clears the description. |
Supplier SKU upsert SupplierId | Selects (and creates) the SKU that has no supplier. | Not applicable. Supplied ids must be positive. |
Supplier SKU delete SupplierId | Deletes the SKU that has no supplier. | Not applicable. Supplied ids must be positive. |
Key points that follow from this table:
- There is no "send an empty list to remove everything". Nothing is ever removed unless you name it in a
Deleteslist. nullnever clears anything. Anullor omitted core field, description, or collection means "leave it alone". To clear a description, send"". To remove a specification, an identifier, or an image, name it inDeletes.- A request must still contain a real change. A body containing only omitted/null fields or empty change collections is rejected rather than silently doing nothing. Sending
""forShortDescriptionorLongDescriptionis a supported clearing operation.
Core fields
Name, ShortDescription, LongDescription, and LifeCycle replace the existing value when supplied.
| Value sent | Result |
|---|---|
Omitted or null | Unchanged. |
| A non-empty string | The existing value is replaced. |
"" for ShortDescription or LongDescription | The description is cleared. |
"" for Name | Not supported. |
"" for LifeCycle | Rejected as an invalid value. |
Classification cannot be changed with this call. Use Reclassify Master Product instead.
Specifications
Specifications has two optional lists.
Upserts: set the value of specification fields. Each entry is { "Id": <field id>, "Value": <text> }.
- If the product already has a value for that field, it is replaced. If it does not, the value is added.
- For single select and multi select fields,
Valueis the display text of the option (comma-separated for multi select, for example"Blue, Red"). The supplied options replace the previous selection: sending"Blue"for a field that was"Blue, Red"leaves onlyBlueselected. Every option must match an option defined for the field, otherwise the request is rejected before anything is written. - For other field types,
Valueis stored as supplied. Value: ""not supported. To remove a value altogether useDeletes.
Deletes: list of field ids (integers) whose values should be removed from the product.
- Deleting a field that currently has no value is not an error.
- Fields you do not mention are unchanged.
Rules for both lists
- Every
Idmust be a positive integer. - A field id can appear only once across
UpsertsandDeletescombined. Setting and deleting the same field in one request is rejected.
Assets
Assets has two optional lists.
Adds: image URLs to download and attach to the product.
- Each image is added as an additional image. It does not become the main (hero) image.
- Each URL always creates a new image. Adds are not de-duplicated, so retrying a request that already succeeded attaches the image again.
- An image that the service rejects (for example because the URL cannot be downloaded or the file is not a supported image) does not fail the request; it is reported as an
[assets]entry inWarnings.
Deletes: list of image ids (GUIDs) to detach from the product.
- Ids must be non-empty GUIDs and must be unique within the list.
- A removal the service rejects is reported as an
[assets]entry inWarnings. Only include ids of images that are currently attached to the product: an id that is not attached may instead fail the request with an error (commonly404). - Always inspect
Warningsafter changing images.
Images already on the product that you do not list in Deletes are never removed.
Identifiers
Supplier SKUs, UPCs, and manufacturer SKUs are patched with the same pattern: an Upserts list to add or update entries, and a Deletes list to remove entries.
| Property | Entry value property | How an existing entry is identified |
|---|---|---|
SupplierSkus | SupplierSku | The SKU value and its supplier (SupplierId). No SupplierId means "no supplier". |
UPCs | Upc | The UPC value. |
ManufacturerSkus | Sku | The SKU value. |
Values
- Values are strings of at most 50 characters and cannot be blank.
- Matching ignores case but is otherwise exact. Whitespace is not trimmed, punctuation is not removed, and leading zeros are significant:
0123and123are different UPCs. Descriptionis optional and at most 250 characters.
Upserts
An upsert says "this identifier should exist with these details".
| Situation | Result |
|---|---|
| No existing identifier matches the value (and supplier, for supplier SKUs) | A new identifier is added. |
| An existing identifier matches | It is updated. If nothing actually differs, nothing is written. |
The only difference is letter case (for example abc-1 against existing ABC-1) | The identifier is updated to the case you sent. |
Details:
- An upsert never renames. Sending a different value adds a new identifier and leaves the old one in place. To change a value, delete the old one and upsert the new one in the same request (see the examples below).
- Description: omitted or
nullkeeps the existing description;""clears it; any other text replaces it. - Supplier SKUs and
SupplierId: the supplier is part of the identity.SupplierId: 7matches a SKU for supplier 7 and, if none exists, creates one for supplier 7. OmittingSupplierIdmatches only a SKU that has no supplier and, if none exists, creates one with no supplier. An upsert never changes which supplier an existing SKU belongs to; to move a SKU to a different supplier, delete the old one and upsert the new one. - Repeating an identical upsert is safe: it does not create a duplicate.
- Entries you do not mention are never removed.
Deletes
A delete removes the identifier you describe.
| Entry | What it deletes |
|---|---|
{ "Upc": "009876543210" } | The UPC with that value. |
{ "Sku": "MFR-1" } | The manufacturer SKU with that value. |
{ "SupplierId": 7, "SupplierSku": "OLD-SKU" } | The SKU OLD-SKU that belongs to supplier 7. |
{ "SupplierSku": "OLD-SKU" } | The SKU OLD-SKU that has no supplier. It does not delete a SKU belonging to a supplier. |
- If you are deleting a supplier SKU that has a supplier, you must include its
SupplierId. - The value is required and cannot be blank.
- Deleting something that is not there is not an error. The delete simply has nothing to do, which makes retries safe.
Conflicts between entries
The following are rejected with a 400 before anything is written:
- Two entries that target the same identifier (for example two upserts for the same value, or an upsert and a delete for the same value).
- An upsert that would produce the same value (and supplier) as another identifier already on the product.
- Swapping values between two existing identifiers in one request.
- A
nullentry inside anyUpsertsorDeleteslist.
Identifier examples
Add a UPC and keep everything else:
{ "UPCs": { "Upserts": [ { "Upc": "001234567890", "Description": "Retail UPC" } ] } }
Clear the description of an existing manufacturer SKU:
{ "ManufacturerSkus": { "Upserts": [ { "Sku": "MFR-1", "Description": "" } ] } }
Replace a UPC value (delete the old, add the new):
{
"UPCs": {
"Deletes": [ { "Upc": "009876543210" } ],
"Upserts": [ { "Upc": "009876543211" } ]
}
}
Move a supplier SKU from supplier 7 to supplier 9:
{
"SupplierSkus": {
"Deletes": [ { "SupplierId": 7, "SupplierSku": "SKU-1" } ],
"Upserts": [ { "SupplierId": 9, "SupplierSku": "SKU-1" } ]
}
}
Assign a supplier to a SKU that currently has none:
{
"SupplierSkus": {
"Deletes": [ { "SupplierSku": "SKU-2" } ],
"Upserts": [ { "SupplierId": 7, "SupplierSku": "SKU-2" } ]
}
}
Order of processing, partial success, and retries
All request validation, identifier matching, and select-option resolution happen before any change is written. A request that fails validation changes nothing.
Once validation passes, changes are applied area by area, in this order:
- Core fields
- Specifications
- Identifiers
- Images
Each area succeeds or fails on its own. If the service rejects one area (for example a specification value the catalog does not accept), that area is skipped, a warning describing it is added to Warnings, and the remaining areas are still attempted. The response is 200 either way, so a 200 does not by itself mean your changes were applied. Always check Warnings.
The update is not transactional. Areas that succeeded stay applied when another area fails; nothing is rolled back. Failures that are not a rejection of your request (an outage or an authorization problem, for example) stop processing at that point and return an error; areas processed before that remain applied. After any warning or error, read the product again before deciding what to retry, and retry only the area that failed.
Guidance for retries and concurrency:
- Specification upserts, identifier upserts, and deletes of identifiers that are already gone are safe to retry.
- Image
Addsare not safe to retry; each attempt attaches the image again. Retrying imageDeletesfor images that are already gone may fail. - Updates to the same product should be serialized by the caller. If two clients change the same product at the same time, one change may overwrite the other.
- You do not supply a version or concurrency token on this call.
Update response
200 OK:
{
"ProductId": "5f0ab1de-4f6c-4b0a-9f23-0d7d8f1a2c11",
"MasterProductId": 55,
"Version": 4,
"Warnings": []
}
| Name | Type | Description |
|---|---|---|
| ProductId | GUID | The product that was updated. |
| MasterProductId | integer | The master product the product belongs to. |
| Version | integer | The product's revision number after the update. Informational only; 0 means revision information is not available for the product. You never need to send it back. |
| Warnings | array of string | One entry for each area that was rejected, such as [specifications] Update failed. Invalid option. Empty when every requested area was applied. See Update warnings. |
If every area in the request is rejected, the API still returns 200 OK, with a warning for each area in Warnings. In that case nothing was changed. The HTTP status alone does not tell you whether an update was applied; always inspect Warnings.
{
"ProductId": "5f0ab1de-4f6c-4b0a-9f23-0d7d8f1a2c11",
"MasterProductId": 55,
"Version": 4,
"Warnings": [
"[specifications] Update failed. Invalid option",
"[identifiers] Update failed. Duplicate identifier"
]
}
Update errors
Update errors use the shapes described in Errors. The ones specific to this call:
| Status | When | Nothing written? |
|---|---|---|
400 | The body failed validation: nothing to change, invalid LifeCycle, duplicate or non-positive ids, malformed identifier entries, conflicting entries, or an unrecognized select option. | Yes. |
403 | The caller does not have the EditProducts permission for the company. | Yes. |
404 | The product does not exist in the company. | Yes. |
A rejection of the request by the underlying service is not an error on this call: it is returned as a 200 with a warning, so the remaining areas can still be applied. See Update warnings.
Reclassify Master Product
PUT /productmanagement/v1/companies/{companyId}/products/master/{masterProductId}/reclassify
Changes the classification of an existing master product. The new classification applies to all of the master's variants. If the master already has that classification, nothing is changed and the call still succeeds.
Required permission: EditProducts
Example of a call would be:
PUT /productmanagement/v1/companies/{companyId}/products/master/{masterProductId}/reclassify
Host: api.covasoft.net
Authorization: Bearer {your token}
Accept: application/json
Content-Type: application/json
{
"ClassificationId": 123
}
Request Information
URI Parameters
| Name | Description | Type | Additional information |
|---|---|---|---|
| companyId | The unique Company Id that was provided in your onboarding package | integer | Required |
| masterProductId | The id of the master product to reclassify | integer | Required |
Body Parameters
| Name | Type | Required | Omitted, null, or empty |
|---|---|---|---|
| ClassificationId | integer | Yes | Required. Must be a positive integer: the id of the classification to assign to the master product. |
Response Information
204 No Content with no body when the classification was applied (or was already assigned).
Reclassify errors
Reclassify errors use the shapes described in Errors. The ones specific to this call:
| Status | When | Nothing written? |
|---|---|---|
400 | ClassificationId is missing, zero, or negative. | Yes. |
403 | The caller does not have the EditProducts permission for the company. | Yes. |
404 | The master product does not exist in the company. | Yes. |
Warnings
A 200 response means the request was processed. Warnings lists problems with individual parts of the request that did not stop the rest from being applied. A 200 does not guarantee that everything you asked for happened, and on an update it does not even guarantee that anything did. Always check Warnings.
Create warnings
On the create endpoints the product is created and Warnings describes anything secondary that was not applied:
- The price could not be set.
- An image was rejected, for example because the URL could not be downloaded. The message includes the reason given by the service.
Warnings on a master with variants appear where they occurred: master images in the top-level Warnings, a variant's price in that variant's Warnings. The product exists, and the missing part can be applied afterwards with the update call (images) or the Item Pricing API (price).
Update warnings
Every update warning starts with a section prefix in square brackets, for example [specifications] Update failed. Invalid option. The prefix is stable and case-sensitive, so it is safe to parse; the text after it is meant for people and may change.
| Prefix | Area | What it means |
|---|---|---|
[product] | Finding the product | The product could not be retrieved or was not found. No changes were attempted. |
[core-fields] | Name, ShortDescription, LongDescription, LifeCycle | The service rejected the change. |
[specifications] | Specifications | The service rejected the change. |
[identifiers] | SupplierSkus, UPCs, ManufacturerSkus | The service rejected the change, or the product's current identifiers could not be read to match your entries. |
[product-fields-and-identifiers] | Name, descriptions, specifications, and identifiers | For some products these are written as a single group. If it is rejected, none of the group was applied, and the warning does not say which field or identifier was at fault. |
[lifecycle] | LifeCycle | For the same products, the life cycle is written separately from the group above. |
[assets] | Assets | An image could not be uploaded or attached, or an image removal was rejected. |
An update therefore reports either [core-fields], [specifications], and [identifiers] individually, or [product-fields-and-identifiers] and [lifecycle]. Handle both.
Things to know:
- A response whose
Warningsis non-empty means those areas were not applied. Areas without a warning were applied. - Because the call still returns
200, an update can contain only warnings and change nothing. When every requested area has a warning, no change was made. - If a warning with the
[product]prefix says the product "was not found", treat the update as failed. (For some products a missing product is returned as a404instead.) - Correct the cause named in the warning and retry only the affected area. Do not resend areas that succeeded, in particular image
Adds, which would attach the images again.
Errors
Create and update calls report errors the same way. An error response has one of three shapes, so read Errors when it is present and otherwise Message.
1. Request validation: Errors array. Returned as 400 Bad Request when the request fails the checks described on this page (for example nothing to update, an invalid price, an unknown classification, or a select option that does not exist). Nothing was written.
{ "Errors": [ "RegularPrice must be a decimal greater than zero. Provide 'null' for no price." ] }
When creating a master with several variants, an error that belongs to one variant is prefixed with its position in the Variants array, for example Variants[1]:Invalid MeasurementType 'Cubic'.
2. Malformed body: standard validation problem details. Returned as 400 Bad Request when a property is missing or malformed before the request is processed (for example a missing IsBatchTracked, or a name outside 1 to 450 characters). The errors property maps field names to messages.
3. Everything else: Message.
{ "Message": "An upstream service call failed (HTTP 503)." }
| Status | When |
|---|---|
401 | The token is missing or invalid. |
403 | The user does not have the required permission for the company. |
404 | The product, or the master product, does not exist in the company. |
Other 4xx | The underlying service rejected the request. The status is passed through and Message contains the reason it gave. |
502 | The underlying service was unavailable or failed, or refused the service's own credentials. Retry later; this is not a problem with your request. |
On a create call, an image that the service rejects with a validation error is a warning, not an error. Other failures while attaching images can return an error even though the product itself was created. After a 502 or other unexpected error on a create call, check whether the product already exists before retrying, to avoid creating a duplicate.
Models
Product
Returned by Create a regular product and Add a variant.
| Name | Type | Description |
|---|---|---|
| Name | string | The product name. |
| ProductId | GUID | The product's id. Use it with PATCH /productmanagement/v1/companies/{companyId}/products/{productId}. |
| CatalogSku | string | The catalog SKU assigned to the product. |
| MasterProductId | integer | The master product the product belongs to. For a regular product this is the product's own master. |
| Warnings | array of string | See Warnings. |
MasterWithVariants
Returned by Create a master with variants.
| Name | Type | Description |
|---|---|---|
| Name | string | The master product name. |
| MasterProductId | integer | The id of the new master product. |
| Variants | array of Product | The created variants, each with its own ProductId and Warnings. |
| Warnings | array of string | Warnings that apply to the master, such as a master image problem. |
MeasurementType
SingleUnit, Mass, Length, Volume
LifeCycle
Active, ComingSoon, Inactive, Discontinued, Archived