Import API

Learn about recent changes to the Import API, and how to apply them using the TypeScript or Java SDK.

After completing this page, you should be able to:

Identify how the changes affect the TypeScript and Java SDKs.
Apply the updated features using the TypeScript or Java SDK.

Do you want a simpler way to import large quantities of products into Composable Commerce? The Import API helps you in achieving this by:

Checking automatically if a record exists, and creating or updating the record appropriately.
Passing the correct resource version number for you.
Letting you send fragments of the product at different times, resolving the fragments, and importing the record. For example, when you import products with a reference to a Category that hasn't been created in this environment yet, the unresolved reference is considered a retryable error. At a later point when the Category has been added, the Import API will automatically retry the Product import and it will be successful.

In the last year, we have had several significant updates to the Import API to make it even better:

You can now import Types to your Project.
When importing Customers, the Customer addresses in CustomerImportRequest is now optional, making it easier for you to create and update Customers with the Import API.
Additionally, the CustomerImportRequest now supports AuthenticationMode. It lets you specify how a Customer will be authenticated (externally or with a password), making the CustomerImportRequest password field optional.
When importing Orders, the OrderImportRequest now supports States and Custom Fields for Parcels and shipping address.

The following example shows how you can add a Custom Type containing a Notes text field to a Customer resource:

import { apiRootImport } from '../impl/apiClientImport.js'; // Update to map to your Import API root

const containerKey = 'training-container-47';
const importRequest = {
  type: 'type',
  resources: [
    {
      key: 'additional-info-47',
      name: {
        'en-US': 'Additional information',
      },
      description: {
        'en-US': 'Loreum Ipsum',
      },
      resourceTypeIds: ['customer'],
      fieldDefinitions: [
        {
          name: 'Notes',
          label: {
            'en-US': 'Notes',
          },
          required: false,
          type: {
            name: 'String',
          },
          inputHint: 'MultiLine',
        },
      ],
    },
  ],
};

async function importType(containerKey, importRequest) {
  try {
    const response = await apiRootImport
      .importContainers()
      .post({
        body: {
          key: containerKey,
          resourceType: 'type',
        },
      })
      .execute();

    console.log(
      'Import container created',
      JSON.stringify(response.body, null, 2)
    );

    const typeRespone = await apiRootImport
      .types()
      .importContainers()
      .withImportContainerKeyValue({ importContainerKey: containerKey })
      .post({ body: importRequest })
      .execute();

    console.log(
      'Import container created',
      JSON.stringify(typeRespone.body, null, 2)
    );
  } catch (error) {
    console.log(JSON.stringify(error, null, 2));
  }
}

importType(containerKey, importRequest);

You can see the Custom Type in the Customer list of the Merchant Center by navigating to Customer > Customer list.

Import API

Test your knowledge