Skip to main content

Basics of pushing products

To upload and update products in EVA, we offer the extensive ImportProducts API. This page describes how to use this API in various scenarios.

For more background information on all the aspects of products, please refer to the Products section on docs.

Identifiers​

In the Common IDs section of our docs we describe the various product identifiers you have at your disposal in EVA, with the BackendID (simply called ‘ID’ in the ImportProducts API) being the most important.

Important to note is that ImportProducts also requires a SystemID to be added to your request. This is the identifier of the system pushing in the data. It's the combination of the SystemID and the ID of the product that makes a truly unique product in EVA.

Unique BackendIDs

In theory you can have multiple products with identical product (Backend)IDs in EVA, if their SystemID is different. We do not advise doing so in practice however, it's more of an edge case possibility. Instead, we strongly advise you to use the same consistent SystemID across your integration with EVA and to avoid any unintended duplicates.

Upload types​

In the ImportProducts API call, there are three types of product uploads that can be defined in the Type field, using a value 0, 1 or 2.

Normal (0)​

This type of import is the standard process where both the product structure and content are created or updated.

If content is present, it will be stored along with the product information. This mode is typically used for regular product updates or initial imports.

ContentOnly (1)​

In this mode, only the content associated with existing products is imported. The product structure itself is not created or updated.

It's essential that the products already exist in the system before using this mode. ContentOnly is useful when updating e-commerce content without altering the product structure. It helps prevent accidentally adding new products and is suitable for scenarios where multiple systems are managing content independently.

PreviewOnly (2)​

This mode is essentially a dry-run: it doesn't execute any modifications to the system.

Instead, it returns a representation of the product structure that would be generated in the response if the import were to be performed. PreviewOnly is handy for reviewing the potential changes before actually committing them to the system. It allows users to verify the outcome without affecting the database.

Uploading a single product​

A simple, single product upload through ImportProducts would look something like this:

{
  "SystemID": "InsomniaImport",
  "Products": [
        {
      "ID": "0001",
      "Name": "Unisex T-shirt",
      "TaxCode": "High"
    }
  ]
}

In the above example, we create a product called 'NewBorn T-shirt' with a BackendID (ID) and a TaxCode. We use SystemID to identify the system from which we are importing our products.

In addition to the BackendID we provide in the ID field, a product can have a CustomID. If you don't explicitly specify a CustomID, it will be the same as your BackendID.

Success response

Your products will always have an EvaID assigned upon creation. Your response will include these EVA IDs, grouped by which products were updated or created. When products are created, they are also always updated. Additionally, we return a BackendID / EvaID mapping.

{
    "UpdatedProductIDs": [
        1
    ],
    "CreatedProductIDs": [
        1
    ],
    "ProductMap": [
        {
            "BackendID": "0001",
            "ID": 1
        }
    ]
}
info

Products with different BackendIDs can have the same CustomID, for example when the latter replaces the first as a successor.

Failure response

Sometimes, your call will only succeed partly.

Let's assume you made an API call to update 100 products but out of this, only 90 products were updated. The remaining 10 failed to update in EVA.

The response would then contain the parts of the call that failed, and the reason why they failed.

The message contains technical-human-readable text that can be used for debugging.

{
  "Error": {
    "Message": "Product 123 uses unknown TaxCode",
    "Type": "ImportProducts:UnknownTaxCode",
    "Code": "JMJVDCGE",
    "RequestID": "1cc5912d5059455594a992d1c17c1a5b"
  }
}

Editing products​

To edit products, just use the same request and alter the information. EVA will know to update the product if the specified ID is already in use.

Deleting products​

To delete products, use the same ImportProducts request, but add the IsDeleted property on the products and set it to true. The products will then be considered deleted. It's good to know that the products actually remain in EVA, their status will just be: Deleted and they won't be visible on the front ends anymore.

Sample: Deleting a product sample
{
  "SystemID": "Mulesoft",
  "Type": 0,
  "Products": [
    {
      "ID": "0001",
      "Name": "Unisex T-shirt",
      "TaxCode": "Clothing",
      "IsDeleted": true
    }
  ]
}

Using the Type property​

By using the Type property, you can indicate what kind of product it is, such as stock-keeping, gift card or service product.

It's a straightforward addition, but we'll give you some samples here to make it as clear as possible.

Stock-keeping

In most cases you want EVA to keep track of the stock levels on each item. To flag an item as stock-keeping, add a value true to the type Stock.

{
  "SystemID": "Mulesoft",
  "Products": [
        {
      "ID": "0001",
    "Name": "Unisex T-shirt",
      "TaxCode": "Clothing",
      "Type": {
        "Stock": true
      }
    }
  ]
}
Service Product

To create a service product (like Dry Cleaning), include Service as its Type.

In most cases, services are sold at a price defined in the Apps themselves - so not a pre-defined price from a pricelist. In that case, also add the AllowCustomPricing flag. 

{
    "SystemID": "Mulesoft",
    "Products": [
        {
            "ID": "0009",
            "Name": "Dry Cleaning",
            "TaxCode": "Services",
            "Type": {
                "Service": true,
                "AllowCustomPricing": true
            }
        }
    ]
}
Gift card Product

To create a gift card product use the GiftCard type flag.

Just like in the previous example, in most cases gift cards are sold at a price defined in the Apps themselves – so not a pre-defined price from a pricelist. In that case, also add the AllowCustomPricing flag.

{
    "SystemID": "Mulesoft",
    "Products": [
        {
            "ID": "0010",
            "Name": "Gift Card",
            "TaxCode": "GiftCards",
            "Type": {
                "GiftCard": true,
                "AllowCustomPricing": true
            }
        }
    ]
}

Available product types​

To make it easier to set your product types, here's an overview of all available ones:

Product hierarchy​

Product hierarchy is defined by the Variations property. This in turn contains a new Products property where every product should contain a value for the variation.

The following two samples display how you can use this variation to apply different levels of variations, leading to Configurable products.

Sample 1 contains a product with four sizes across a single level of hierarchy. This leads EVA to create one Configurable product called "Unisex T-shirt" and 4 sellable SKUs for the individual sizes - in other words: a t-shirt in four sizes.

Sample 2 goes one level deeper: suppose you want to upload a "New Black Hoodie" that comes in two different colors, with each in turn coming in two sizes.


{
  "SystemID": "Mulesoft",
  "Products": [
    {
      "ID": "0001",
      "Name": "Unisex T-shirt",
      "TaxCode": "Clothing",
      "IsDeleted": false,
      "Variations": {
        "Property": "size",
        "LogicalLevel": "size",
        "Products": [
          {
            "ID": "0001-978020137957",
            "Name": "Unisex T-shirt",
            "IsDeleted": false,
            "TaxCode": "Clothing",
            "VariationValues": [
              {
                "Value": "S"
              }
            ],
            "Type": {
              "Stock": true
            }
          },
          {
            "ID": "0001-978020137958",
            "Name": "Unisex T-shirt",
            "IsDeleted": false,
            "TaxCode": "Clothing",
            "VariationValues": [
              {
                "Value": "M"
              }
            ],
            "Type": {
              "Stock": true
            }
          },
          {
            "ID": "0001-978020137959",
            "Name": " Unisex T-shirt",
            "IsDeleted": false,
            "TaxCode": "Clothing",
            "VariationValues": [
              {
                "Value": "L"
              }
            ],
            "Type": {
              "Stock": true
            }
          },
          {
            "ID": "0001-978020137960",
            "Name": "Unisex T-shirt",
            "IsDeleted": false,
            "TaxCode": "Clothing",
            "VariationValues": [
              {
                "Value": "XL"
              }
            ],
            "Type": {
              "Stock": true
            }
          }
        ]
      }
    }
  ]
}

Barcodes​

To add a barcode to a product, use the Barcodes element.

You can also specify a Barcode (and its Quantity) for an existing unit of measure in the call to allow for easy scanning. 

{
  "SystemID": "PimCore",
  "Products": [
        {
      "ID": "121",
      "Name": "NewBorn T-Shirt",
      "TaxCode": "High",
      "Barcodes": [
        "978020137957"
      ]
    }
  ]
}
Note

Both color and size (used in the second sample) are NOT native EVA product properties. These have to be created before they can be used. See Custom product properties.