Skip to main content

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.

Low rate limit

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).

Image URLs must link directly to the image

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​

EndpointDescription
Create Regular ProductCreate a standalone product that is sold as-is.
Create Master Product with VariantsCreate a master product and all of its variants in one call.
Add Variant to Master ProductAdd one variant to an existing master product.
Update ProductChange an existing product's core fields, specifications, identifiers, and images.
Reclassify Master ProductChange 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 null are always identical. Leaving a property out of the JSON body is the same as sending null.
  • 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. ProductName and productname are equivalent, as are Inactive and inactive. Identifier values are a separate matter and are described under Identifiers.
TermMeaning in this documentation
OmittedThe property is absent from the JSON body.
nullThe property is present with the value null. Treated exactly like omitted.
EmptyAn empty string ("") or an empty array ([]).
UnchangedThe 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​

NameDescriptionTypeAdditional information
companyIdThe unique Company Id that was provided in your onboarding packageintegerRequired

Body Parameters​

NameTypeRequiredOmitted, null, or empty
ProductNamestringYesRequired. 1 to 450 characters; a blank or whitespace-only name is rejected.
ShortDescriptionstringNoOmitted, null, or "": the product has no short description. Maximum 450 characters.
LongDescriptionstringNoOmitted, null, or "": the product has no long description. Maximum 20,000 characters.
IsBatchTrackedbooleanYesRequired. Omitting it is rejected. There is no default.
MeasurementTypestringYesRequired. One of the MeasurementType values. Omitted, null, "", or an unknown value is rejected.
RegularPricedecimalNoOmitted or null: no price is set. When supplied it must be greater than zero; 0 and negative numbers are rejected.
ClassificationobjectYesRequired. Both ClassificationTreeId and ClassificationId are required.
Specificationsarray of SpecificationNoOmitted, null, or []: no specifications are set.
UpcsarrayNoOmitted, null, or []: the product has no UPCs. See Identifier entries.
SuppliersarrayNoOmitted, null, or []: the product has no supplier SKUs. See Identifier entries.
MainImageUrlstringNoOmitted, null, or "": no main image. When supplied, the image is downloaded and becomes the product's main (hero) image.
AdditionalImageUrlsarray of stringNoOmitted, null, or []: no additional images.

Specification value​

Each Specifications entry is { "Id": <field id>, "Value": <text> }.

  • Id is 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), Value is 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 a 400 that names the field and the option that was not found.
  • For all other field types, Value is stored exactly as supplied.

Identifier entries on create​

PropertyUsed byNotes
UpcUpcsThe UPC value. Maximum 50 characters.
SupplierSkuSuppliersThe supplier's SKU. Maximum 50 characters.
SupplierIdSuppliersOptional. 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.
DescriptionbothOptional. 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​

NameDescriptionTypeAdditional information
companyIdThe unique Company Id that was provided in your onboarding packageintegerRequired

Body Parameters​

NameTypeRequiredOmitted, null, or empty
MasterProductNamestringYesRequired. 1 to 450 characters; a blank or whitespace-only name is rejected.
ShortDescriptionstringNoOmitted, null, or "": no short description on the master. Maximum 450 characters.
LongDescriptionstringNoOmitted, null, or "": no long description on the master. Maximum 20,000 characters.
ClassificationobjectYesRequired. Both ClassificationTreeId and ClassificationId are required. Applies to the master and is shared by every variant.
SpecificationsarrayNoOmitted, null, or []: none. Same format as Specification value.
UpcsarrayNoOmitted, null, or []: none. Same format as Identifier entries.
SuppliersarrayNoOmitted, null, or []: none. Same format as Identifier entries.
MainImageUrlstringNoOmitted, null, or "": no main image on the master.
AdditionalImageUrlsarray of stringNoOmitted, null, or []: none.
Variantsarray of VariantYesRequired, 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:

NameTypeRequiredOmitted, null, or empty
VariantProductNamestringYesRequired. 1 to 450 characters; a blank or whitespace-only name is rejected.
ShortDescriptionstringNoOmitted, null, or "": no short description. Maximum 450 characters.
LongDescriptionstringNoOmitted, null, or "": no long description. Maximum 20,000 characters.
IsBatchTrackedbooleanYesRequired. Omitting it is rejected. There is no default.
MeasurementTypestringYesRequired. One of the MeasurementType values.
RegularPricedecimalNoOmitted or null: no price is set. When supplied it must be greater than zero.
SpecificationsarrayNoOmitted, null, or []: none. Same format as Specification value.
UpcsarrayNoOmitted, null, or []: none.
SuppliersarrayNoOmitted, null, or []: none.
MainImageUrlstringNoOmitted, null, or "": no main image for this variant.
AdditionalImageUrlsarray of stringNoOmitted, 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​

NameDescriptionTypeAdditional information
companyIdThe unique Company Id that was provided in your onboarding packageintegerRequired
masterProductIdThe id of the master product to add the variant tointegerRequired

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​

NameDescriptionTypeAdditional information
companyIdThe unique Company Id that was provided in your onboarding packageintegerRequired
productIdThe product's id (the ProductId returned when it was created)GUIDRequired

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.

NameTypeDescription
NamestringNew product name. Maximum 450 characters.
ShortDescriptionstringNew short description. Maximum 450 characters.
LongDescriptionstringNew long description. Maximum 20,000 characters.
LifeCyclestringNew life cycle. One of the LifeCycle values.
SpecificationsobjectSpecification changes: Upserts and Deletes. See Specifications.
AssetsobjectImage changes: Adds and Deletes. See Assets.
SupplierSkusobjectSupplier SKU changes: Upserts and Deletes. See Identifiers.
UPCsobjectUPC changes: Upserts and Deletes. See Identifiers.
ManufacturerSkusobjectManufacturer SKU changes: Upserts and Deletes. See Identifiers.

Omitted, null, and empty at a glance​

PropertyOmitted or nullEmpty ("" or [])
NameUnchanged.Not supported. A product always has a name; do not send an empty Name.
ShortDescriptionUnchanged."" clears the short description.
LongDescriptionUnchanged."" clears the long description.
LifeCycleUnchanged."" is not a valid life cycle and is rejected.
SpecificationsNo specification changes.{} is the same as omitted: no changes.
Specifications.UpsertsNo specifications set.[]: no changes.
Specifications.DeletesNo specifications removed.[]: no changes.
Specifications.Upserts[].ValueDo not omit. Always supply a value; to remove a value use Deletes."" not supported. Use Deletes to remove values.
Assets, Assets.Adds, Assets.DeletesNo image changes.{} or []: no changes.
SupplierSkus, UPCs, ManufacturerSkusNo changes to that identifier type.{}: no changes.
Upserts, Deletes (identifiers)No identifiers added, changed, or removed.[]: no changes.
Identifier upsert DescriptionThe existing description is kept. A newly created identifier has no description."" clears the description.
Supplier SKU upsert SupplierIdSelects (and creates) the SKU that has no supplier.Not applicable. Supplied ids must be positive.
Supplier SKU delete SupplierIdDeletes 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 Deletes list.
  • null never clears anything. A null or 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 in Deletes.
  • 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 "" for ShortDescription or LongDescription is a supported clearing operation.

Core fields​

Name, ShortDescription, LongDescription, and LifeCycle replace the existing value when supplied.

Value sentResult
Omitted or nullUnchanged.
A non-empty stringThe existing value is replaced.
"" for ShortDescription or LongDescriptionThe description is cleared.
"" for NameNot supported.
"" for LifeCycleRejected 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, Value is 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 only Blue selected. Every option must match an option defined for the field, otherwise the request is rejected before anything is written.
  • For other field types, Value is stored as supplied.
  • Value: "" not supported. To remove a value altogether use Deletes.

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 Id must be a positive integer.
  • A field id can appear only once across Upserts and Deletes combined. 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 in Warnings.

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 in Warnings. 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 (commonly 404).
  • Always inspect Warnings after 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.

PropertyEntry value propertyHow an existing entry is identified
SupplierSkusSupplierSkuThe SKU value and its supplier (SupplierId). No SupplierId means "no supplier".
UPCsUpcThe UPC value.
ManufacturerSkusSkuThe 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: 0123 and 123 are different UPCs.
  • Description is optional and at most 250 characters.

Upserts​

An upsert says "this identifier should exist with these details".

SituationResult
No existing identifier matches the value (and supplier, for supplier SKUs)A new identifier is added.
An existing identifier matchesIt 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 null keeps the existing description; "" clears it; any other text replaces it.
  • Supplier SKUs and SupplierId: the supplier is part of the identity. SupplierId: 7 matches a SKU for supplier 7 and, if none exists, creates one for supplier 7. Omitting SupplierId matches 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.

EntryWhat 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 null entry inside any Upserts or Deletes list.

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:

  1. Core fields
  2. Specifications
  3. Identifiers
  4. 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 Adds are not safe to retry; each attempt attaches the image again. Retrying image Deletes for 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": []
}
NameTypeDescription
ProductIdGUIDThe product that was updated.
MasterProductIdintegerThe master product the product belongs to.
VersionintegerThe 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.
Warningsarray of stringOne entry for each area that was rejected, such as [specifications] Update failed. Invalid option. Empty when every requested area was applied. See Update warnings.
warning

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:

StatusWhenNothing written?
400The body failed validation: nothing to change, invalid LifeCycle, duplicate or non-positive ids, malformed identifier entries, conflicting entries, or an unrecognized select option.Yes.
403The caller does not have the EditProducts permission for the company.Yes.
404The 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​

NameDescriptionTypeAdditional information
companyIdThe unique Company Id that was provided in your onboarding packageintegerRequired
masterProductIdThe id of the master product to reclassifyintegerRequired

Body Parameters​

NameTypeRequiredOmitted, null, or empty
ClassificationIdintegerYesRequired. 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:

StatusWhenNothing written?
400ClassificationId is missing, zero, or negative.Yes.
403The caller does not have the EditProducts permission for the company.Yes.
404The 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.

PrefixAreaWhat it means
[product]Finding the productThe product could not be retrieved or was not found. No changes were attempted.
[core-fields]Name, ShortDescription, LongDescription, LifeCycleThe service rejected the change.
[specifications]SpecificationsThe service rejected the change.
[identifiers]SupplierSkus, UPCs, ManufacturerSkusThe 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 identifiersFor 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]LifeCycleFor the same products, the life cycle is written separately from the group above.
[assets]AssetsAn 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 Warnings is 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 a 404 instead.)
  • 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)." }
StatusWhen
401The token is missing or invalid.
403The user does not have the required permission for the company.
404The product, or the master product, does not exist in the company.
Other 4xxThe underlying service rejected the request. The status is passed through and Message contains the reason it gave.
502The 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.

NameTypeDescription
NamestringThe product name.
ProductIdGUIDThe product's id. Use it with PATCH /productmanagement/v1/companies/{companyId}/products/{productId}.
CatalogSkustringThe catalog SKU assigned to the product.
MasterProductIdintegerThe master product the product belongs to. For a regular product this is the product's own master.
Warningsarray of stringSee Warnings.

MasterWithVariants​

Returned by Create a master with variants.

NameTypeDescription
NamestringThe master product name.
MasterProductIdintegerThe id of the new master product.
Variantsarray of ProductThe created variants, each with its own ProductId and Warnings.
Warningsarray of stringWarnings that apply to the master, such as a master image problem.

MeasurementType​

SingleUnit, Mass, Length, Volume

LifeCycle​

Active, ComingSoon, Inactive, Discontinued, Archived