Migrating from Primary EAN to the New Codes System in Mailship

This guide will walk you through the process of migrating from using the Primary EAN (productSku) to the new Codes system for your products in Mailship. Codes offer greater flexibility - most notably, the ability to assign multiple identification codes to a single product.

Why Switch to Codes?

The Primary EAN allows only one identification code to be assigned to each product (Internal SKU). The new Codes system brings the following advantages:

• Multiple codes per product - A single product (Internal SKU) can have multiple codes assigned at the same time.

• Better support for different barcode types - Each code stores its type (EAN8, EAN13, EAN14, UPC-A, UPC-E).

Important Conditions

Before starting the migration, please keep the following in mind:

Codes cannot be used together with the Primary EAN.
The system does not allow a product to have a Primary EAN filled in while also using Codes. If you send an API request containing both fields (productSku and codes), you will receive an error response:
"Provide product either via 'productSku' field or 'codes' field, not both at the same time."

Migration to Codes is only possible via API.
Codes can be managed (added, edited) only through the API. While it is possible to view and edit Codes in the Mailship portal, other synchronizations do not yet support Codes, so it is advisable to stay with the Primary EAN for those.

Changing the primary code is only possible when stock quantity is zero.
If a product has stock on hand, primary codes cannot be changed or deleted. In that case, the stock must first be depleted. If you attempt to update a product that has stock, you will receive an error response:
"Not possible to update 'productSku'. There are items already in stock."

Step-by-Step Migration Process (API)

Step 1: Check the Current State of the Product

First, verify what Primary EAN is currently set on the product.

API request:

GET /api/product/{product_id}

In the response, you will find the productSku field (Primary EAN) and the codes field (Codes). If the product uses the Primary EAN, the productSku field will be populated and the codes field will be empty ([]).

Step 2: Verify Stock Quantity

If you want to change the primary code on the product (which you are doing when migrating from Primary EAN to Codes), make sure the product has no stock on hand, or deplete the stock first.

If the product has stock and you still wish to proceed with the migration, please contact customer support.

Step 3: Delete the Primary EAN and Add Codes in a Single Request

The migration is performed with a single PUT API request, in which you simultaneously:

• Set productSku to null (delete the Primary EAN).

• Add new Codes to the codes array, with at least one of them marked as primary: true.

API request:

PUT /api/product/{product_id}

Request body (example):

{
    "productSku": null,
    "codes": [
        {
            "value": "8594012345678",
            "type": "ean13",
            "primary": true
        },
        {
            "value": "1234567",
            "type": "ean8",
            "primary": false
        }
    ]
}

In this example:

• The Primary EAN (productSku) is deleted (set to null).

• Two new codes are added - EAN13 as the primary code and EAN8 as the secondary code.

Tip: If you want to keep the value of the old Primary EAN as one of the new Codes, simply add it to the codes array:

{
    "productSku": null,
    "codes": [
        {
            "value": "ORIGINAL-EAN-VALUE",
            "type": "ean13",
            "primary": true
        }
    ]
}

This way, the existing EAN is effectively "moved" from the productSku field into the new Codes system.

Step 4: Verify the Result

After a successful request (response 200 OK), verify that:

• The productSku field is null.

• The codes field contains your new code(s).

• One of the codes has the flag primary: true.

GET /api/product/{product_id}

Rules for Working with Codes

When working with Codes, follow these rules:

• At least one primary code - There must always be at least one code marked as primary: true among the product's codes.

• Code uniqueness - Code values must be unique within a single product. The same code cannot be assigned as the primary code of two different products within the same organization.

• Codes vs. another product's productSku - A code value must not be the same as the productSku (Primary EAN) of another existing product in the organization.

• Supported code types - ean8, ean13, ean14, upcA, upcE, unknown.

Adding and Removing Codes on an Existing Product

Adding an Additional Code

Once a product uses Codes, you can add more codes using a PUT API request. Include all codes (existing and new) in the codes array.

Example - adding an additional code to a product that already has one code:

{
    "codes": [
        {
            "value": "8594012345678",
            "primary": true
        },
        {
            "value": "9876543210123",
            "type": "ean13",
            "primary": false
        }
    ]
}

Removing a Code

To remove a code, simply omit it from the codes array in the PUT request.

Note: Removing codes is only possible when the product has zero stock. If the product has stock and you attempt to remove a code, you will receive an error response: "There are items already in stock."

Frequently Asked Questions

Do I need to fill in the code type?
No - if you are unsure what type of barcode the product has, simply select unknown as the code type.

Can I switch back from Codes to the Primary EAN?
Yes - simply set productSku to the desired value in the PUT request and do not include the codes field. However, we recommend against doing so - the Codes system is the newer solution, and the Primary EAN is a feature that will gradually be phased out.

Do I need to migrate all products at once?
No - the migration can be done gradually, product by product. Each product can independently use either the Primary EAN or Codes.

Can I edit Codes from the Mailship portal?
If a product has no stock, it is possible to add new Codes through the Mailship portal. Editing existing codes is subsequently only possible through customer support or via the API.

Need Help?

If you are unsure how to proceed with the migration, or need assistance migrating a larger number of products, please contact our customer support team.