Skip to main content

Introduction to Commerce APIs

The Commerce APIs of webround.com are designed to manage core e-commerce logic: from product catalogs and inventory to cart management and order processing.

All Commerce APIs are scoped by store-id and require either administrative or customer-level authentication, depending on the context.

Localization & Translations​

For every entity that supports multiple languages (such as Products, Tags, or Attributes), we use a dedicated translations object. This allows you to manage localized content efficiently within a single request.

To send translations, include the translations object in the request body. Each key in this object must be a valid ISO locale code (e.g., en, it, es), containing the fields specific to that language.

Data in the default language must be provided outside the translations field, using the standard keys. For example, suppose you are modifying a product's versions in Italian and Spanish, using English as the default language.

Example: Product Translation​

{

    "name": "Product Name",
    "seoDescription": "High quality item",
    "translations": {
        "it": {
            "name": "Nome del prodotto",
            "seoDescription": "Articolo di alta qualità"
        },
        "es": {
            "name": "Nombre del producto",
            "seoDescription": "Articulo de alta calidad"
        }
    }
}

Entity Linking: "Delete and Replace" Logic​

All endpoints dedicated to syncing or replacing links between entities (such as linking Assets and Tags to Products) follow a strict "Delete and Replace" logic.

This means the array of IDs you send becomes the new source of truth. The system does not append data; it overwrites the existing state.

Important Behaviors:​

  • Resetting Associations: To remove all existing links (e.g., removing all tags from a product), send an empty array [].
  • Single Selection: If you send an array with a single ID ["uuid-1"], only that specific link will persist. Any other previously existing links will be deleted.
  • Extending Selection: If you want to add a new link while keeping the existing ones, you must send the entire list of IDs (current ones + the new one).

Warning: Always fetch the current state of links before performing a sync if you intend to preserve existing associations.

Asset Management Workflow​

It is important to understand the distinction between storing an asset and linking it to commerce entities:

  • Upload & Storage: To physically upload a file (image, video) to webround.com, you must use the Core APIs. Example: Upload an image.
  • Linking: Once the upload is complete and you have obtained a valid Asset ID, you can use the Commerce APIs to create a link between that Asset and a Product or Variant.

A Commerce API endpoint will never accept a binary file; it only manages the relationship between an existing Asset ID and your products.

Core Principles​

  1. Scoping Headers: Every request must include the necessary headers (store-id) and authentication tokens.
  2. Consistency: Use Bulk endpoints for high-volume operations to minimize network overhead.
  3. Data Integrity: Validation is strictly enforced via validation schemas. Ensure your payloads match the documented DTOs to avoid 400 Bad Request errors.