Representations of resources that can be imported into a Project using the Import API.

Import Resources are almost identical to the equivalent type on the HTTP API, with the main difference that id values are not included.
When referencing other resources, such as defining the parent of a CategoryImport, only KeyReferences are accepted. This ensures that resources can be imported to multiple Projects, such as production and staging, without needing to change Project-specific id values.

Types that are identical on the HTTP API, we do not document here, but refer to the respective type on the HTTP API instead.

for Business Units

Business Units are represented as either Companies or Divisions.

CompanyBusinessUnitImport

Represents a Company, the top-level of a business.
key​
String​
User-defined unique identifier. If a BusinessUnit with this key exists, it is updated with the imported data.
MinLength: 2​MaxLength: 256​Pattern: ^[A-Za-z0-9_-]+$​
unitType​
Company

The type of Business Unit.

name​
String​

The name of the Business Unit.

status​

The status of the Business Unit.

contactEmail​
String​

The contact email address for the Business Unit.

associates​
Array of AssociateDraft​

List of Associates to be assigned to the Business Unit.

addresses​
Array of Address​

The addresses for the Business Unit.

shippingAddresses​
Array of Int​
The indices of the shipping addresses in the addresses array.
defaultShippingAddress​
Int​
The index of the default shipping address in the addresses array.
billingAddresses​
Array of Int​
The indices of the billing addresses in the addresses array.
defaultBillingAddress​
Int​
The index of the default billing address in the addresses array.
stores​
Array of StoreKeyReference​

The Stores of the Business Unit.

storeMode​
Default: Explicit​
custom​

Custom fields for the Business Unit.

Example: json
{
  "key": "acme-business-unit",
  "name": "ACME Business Unit",
  "unitType": "Company"
}

DivisionBusinessUnitImport

Represents a Division, a sub-unit of a Company or another Division.
key​
String​
User-defined unique identifier. If a BusinessUnit with this key exists, it is updated with the imported data.
MinLength: 2​MaxLength: 256​Pattern: ^[A-Za-z0-9_-]+$​
unitType​
Division

The type of Business Unit.

name​
String​

The name of the Business Unit.

status​

The status of the Business Unit.

contactEmail​
String​

The contact email address for the Business Unit.

associates​
Array of AssociateDraft​

List of Associates to be assigned to the Business Unit.

addresses​
Array of Address​

The addresses for the Business Unit.

shippingAddresses​
Array of Int​
The indices of the shipping addresses in the addresses array.
defaultShippingAddress​
Int​
The index of the default shipping address in the addresses array.
billingAddresses​
Array of Int​
The indices of the billing addresses in the addresses array.
defaultBillingAddress​
Int​
The index of the default billing address in the addresses array.
stores​
Array of StoreKeyReference​

The Stores of the Business Unit.

storeMode​
If Explicit, the stores field cannot be empty and the Business Unit is explicitly associated with the given Stores. If FromParent, the Business Unit inherits the Stores from its parent.
Default: FromParent​
parentUnit​

The parent Business Unit of this Division.

associateMode​
If Explicit, Associates are not inherited from the parent. If ExplicitAndFromParent, Associates are inherited from the parent.
Default: ExplicitAndFromParent​
approvalRuleMode​
If Explicit, approval rules are not inherited from the parent. If ExplicitAndFromParent, approval rules are inherited from the parent.
Default: ExplicitAndFromParent​
custom​

Custom fields for the Business Unit.

Example: json
{
  "key": "acme-business-unit-division-a",
  "name": "ACME Business Unit: Division A",
  "unitType": "Division",
  "parentUnit": {
    "key": "acme-business-unit",
    "typeId": "business-unit"
  }
}

AssociateDraft

Draft for an Associate in a Business Unit.

customer​

The Customer to be part of the Business Unit.

associateRoleAssignments​

The roles to assign to the Associate.

AssociateRoleAssignmentDraft

The role of an Associate in a Business Unit.

associateRole​

The role to assign to the Associate.

Determines whether the AssociateRole is inherited. If Disabled, the AssociateRole is not inherited from a parent Business Unit.

for Categories

CategoryImport

Represents the data used to import a Category. Once imported, this data is persisted as a Category in the Project.
key​
String​
User-defined unique identifier. If a Category with this key exists, it is updated with the imported data.
MinLength: 2​MaxLength: 256​Pattern: ^[A-Za-z0-9_-]+$​
externalId​
String​
Maps to Category.externalId.
name​
Maps to Category.name.
slug​
Maps to Category.slug. Must match the pattern ^[A-Za-z0-9_-]{2,256}+$.
description​
Maps to Category.description.
parent​
Maps to Category.parent. If the referenced Category does not exist, the state of the ImportOperation will be set to unresolved until the referenced Category is created.
orderHint​
String​
Maps to Category.orderHint.
metaTitle​
Maps to Category.metaTitle.
metaDescription​
Maps to Category.metaDescription.
metaKeywords​
Maps to Category.metaKeywords.
assets​
Array of Asset​
Maps to Category.assets.
custom​
Maps to Category.custom.
Example: json
{
  "key": "category-to-import",
  "name": {
    "en": "Category to import"
  },
  "slug": {
    "en": "category-to-import-slug"
  },
  "description": {
    "en": "Description of category to import"
  },
  "parent": {
    "typeId": "category",
    "key": "key-of-parent-category"
  }
}

for Customers

CustomerImport

Represents the data used to import a Customer. Once imported, this data is persisted as a Customer in the Project.
key​
String​
User-defined unique identifier. If a Customer with this key exists, it is updated with the imported data.
MinLength: 2​MaxLength: 256​Pattern: ^[A-Za-z0-9_-]+$​
customerNumber​
String​
Maps to Customer.customerNumber.
externalId​
String​
Maps to Customer.externalId.
email​
String​
Maps to Customer.email.
password​
String​
Maps to Customer.password. Required when authenticationMode is set to Password. This field is only used when creating new Customers, and is ignored when updating Customers. However, due to the Import API's upsert behavior, a non-empty value must still be provided when updating Customers.
stores​
Array of StoreKeyReference​
Maps to Customer.stores. If the referenced Stores do not exist, the state of the ImportOperation will be set to unresolved until the referenced Stores are created.
firstName​
String​
Maps to Customer.firstName.
lastName​
String​
Maps to Customer.lastName.
middleName​
String​
Maps to Customer.middleName.
title​
String​
Maps to Customer.title.
salutation​
String​
Maps to Customer.salutation.
dateOfBirth​
Date​
Maps to Customer.dateOfBirth.
companyName​
String​
Maps to Customer.companyName.
vatId​
String​
Maps to Customer.vatId.
isEmailVerified​
Boolean​
Maps to Customer.isEmailVerified.
customerGroup​
Maps to Customer.customerGroup. If the referenced CustomerGroup does not exist, the state of the ImportOperation will be set to unresolved until the referenced CustomerGroup is created.
addresses​
Array of CustomerAddress​
Maps to Customer.addresses.
defaultBillingAddress​
Int​
Index of the address in the addresses array to use as the default billing address. The defaultBillingAddressId of the Customer will be set to the id of that address.
billingAddresses​
Array of Int​
Indices of the billing addresses in the addresses array. The billingAddressIds of the Customer will be set to the id of these addresses.
defaultShippingAddress​
Int​
The index of the address in the addresses array. The defaultShippingAddressId of the Customer will be set to the id of that address.
shippingAddresses​
Array of Int​
Indices of the shipping addresses in the addresses array. The shippingAddressIds of the Customer will be set to the id of these addresses.
locale​
String​
Maps to Customer.locale.
Pattern: ^[a-zA-Z]{2,3}(?:-[a-zA-Z]{4})?(?:-(?:[a-zA-Z]{2}|d{3}))?$​
authenticationMode​
  • Set to Password to make the password field required for the Customer.
  • Set to ExternalAuth when the password is not required for the Customer.
Default: Password​
custom​
Maps to Customer.custom.
Example: json
{
  "key": "customer-to-import",
  "customerNumber": "12345",
  "email": "john@example.com",
  "password": "D0cEx@mpl3!2025",
  "firstName": "John",
  "lastName": "Doe",
  "dateOfBirth": "1980-01-01",
  "isEmailVerified": false,
  "externalId": "external-id-123",
  "customerGroup": {
    "typeId": "customer-group",
    "key": "customer-group-key"
  },
  "addresses": [
    {
      "key": "john-doe-address-key",
      "streetName": "Main Street",
      "streetNumber": "123",
      "postalCode": "12345",
      "city": "Berlin",
      "country": "DE"
    }
  ],
  "authenticationMode": "Password"
}

CustomerAddress

Different from Address in that key is required and id is not supported.
key​
String​

User-defined identifier for the address. Must be unique per customer.

MinLength: 2​MaxLength: 256​Pattern: ^[a-zA-Z0-9_-]{2,256}$​
externalId​
String​

ID for the contact used in an external system.

country​

Name of the country.

Pattern: ^[A-Z]{2}$​
title​
String​

Title of the contact, for example 'Dr.'

salutation​
String​

Salutation of the contact, for example 'Mr.' or 'Ms.'

firstName​
String​

Given name (first name) of the contact.

lastName​
String​

Family name (last name) of the contact.

streetName​
String​

Name of the street.

streetNumber​
String​

Street number.

additionalStreetInfo​
String​

Further information on the street address.

postalCode​
String​

Postal code.

city​
String​

Name of the city.

region​
String​

Name of the region.

state​
String​

Name of the state, for example, Colorado.

company​
String​

Name of the company.

department​
String​

Name of the department.

building​
String​

Number or name of the building.

apartment​
String​

Number or name of the apartment.

pOBox​
String​

Post office box number.

phone​
String​

Phone number of the contact.

mobile​
String​

Mobile phone number of the contact.

email​
String​

Email address of the contact.

fax​
String​

Fax number of the contact.

additionalAddressInfo​
String​

Further information on the Address.

custom​

Custom Fields for the address.

Example: json
{
  "key": "john-doe-address-key",
  "streetName": "Main Street",
  "streetNumber": "123",
  "postalCode": "12345",
  "city": "Berlin",
  "country": "DE"
}

for Discount Codes

DiscountCodeImport

Represents the data used to import a DiscountCode. Once imported, this data is persisted as a DiscountCode in the Project.
key​
String​
User-defined unique identifier. If a DiscountCode with this key exists, it is updated with the imported data.
MinLength: 2​MaxLength: 256​Pattern: ^[A-Za-z0-9_-]+$​
name​
Maps to DiscountCode.name.
description​
Maps to DiscountCode.description.
code​
String​
Maps to DiscountCode.code. This value cannot be updated. Attempting to update this value will result in an InvalidFieldsUpdate error.
cartDiscounts​
Maps to DiscountCode.cartDiscounts. If the referenced CartDiscounts do not exist, the state of the ImportOperation will be set to unresolved until the referenced CartDiscounts are created.
cartPredicate​
String​
Maps to DiscountCode.cartPredicate.
isActive​
Boolean​
Maps to DiscountCode.isActive.
maxApplications​
Int64​
Maps to DiscountCode.maxApplications.
maxApplicationsPerCustomer​
Int64​
Maps to DiscountCode.maxApplicationsPerCustomer.
groups​
Array of String​
Maps to DiscountCode.groups.
validFrom​
Maps to DiscountCode.validFrom.
validUntil​
Maps to DiscountCode.validUntil.
custom​
Maps to DiscountCode.custom.
Example: json
{
  "key": "discountCodeKey",
  "code": "Save10",
  "name": {
    "en": "Save10"
  },
  "cartDiscounts": [
    {
      "typeId": "cart-discount",
      "key": "cartDiscountKey"
    }
  ],
  "isActive": false,
  "groups": []
}

for Inventory

InventoryImport

Represents the data used to import an InventoryEntry. Once imported, this data is persisted as a InventoryEntry in the Project.
key​
String​
User-defined unique identifier. If an InventoryEntry with this key exists, it is updated with the imported data.
MinLength: 2​MaxLength: 256​Pattern: ^[A-Za-z0-9_-]+$​
sku​
String​
Maps to InventoryEntry.sku
quantityOnStock​
Int64​
Maps to InventoryEntry.quantityOnStock
restockableInDays​
Int64​
Maps to InventoryEntry.restockableInDays
expectedDelivery​
Maps to InventoryEntry.expectedDelivery
reservationExpirationInMinutes​
Int32​
Maps to InventoryEntry.reservationExpirationInMinutes
Minimum: 1​Maximum: 44640​
supplyChannel​
Maps to InventoryEntry.supplyChannel. If the referenced Channel does not exist, the state of the ImportOperation will be set to unresolved until the referenced Channel is created.
custom​
Maps to InventoryEntry.custom.
Example: json
{
  "key": "inventory-import-key",
  "sku": "product-variant-sku",
  "quantityOnStock": 15,
  "restockableInDays": 2,
  "expectedDelivery": "2022-06-30T14:00:00.000Z",
  "supplyChannel": {
    "typeId": "channel",
    "key": "channel-key"
  }
}

for Product Types

ProductTypeImport

Represents the data used to import a ProductType. Once imported, this data is persisted as a ProductType in the Project.
key​
String​
User-defined unique identifier. If a ProductType with this key exists, it is updated with the imported data.
MinLength: 2​MaxLength: 256​Pattern: ^[A-Za-z0-9_-]+$​
name​
String​
Maps to ProductType.name.
description​
String​
Maps to ProductType.description.
attributes​
The attributes of ProductType.
Example: json
{
  "key": "product-type-key",
  "name": "Product Type name",
  "description": "Test product type",
  "attributes": [
    {
      "name": "product-ref-attribute",
      "label": {
        "en": "selling product"
      },
      "isRequired": false,
      "isSearchable": false,
      "type": {
        "name": "reference",
        "referenceTypeId": "category"
      },
      "attributeConstraint": "Unique",
      "inputTip": {
        "en": "product input tip"
      },
      "inputHint": "SingleLine"
    }
  ]
}

for Products

When updating existing Products by import, you must include the existing values of the Product. The import process will remove the values of omitted fields.

ProductImport

Represents the data used to import a Product. Once imported, this data is persisted as a Product in the Project.

This is the minimal representation required for creating a Product in Composable Commerce.

key​
String​
User-defined unique identifier. If a Product with this key exists, it is updated with the imported data.
MinLength: 2​MaxLength: 256​
name​
Maps to ProductData.name.
productType​
Maps to Product.productType. If the referenced ProductType does not exist, the state of the ImportOperation will be set to unresolved until the referenced ProductType is created.
slug​
Maps to ProductData.slug.
description​
Maps to ProductData.description.
categories​
Maps to ProductData.categories. If the referenced Categories do not exist, the state of the ImportOperation will be set to unresolved until the referenced Categories are created.
attributes​
Array of Attribute​
metaTitle​
Maps to ProductData.metaTitle.
metaDescription​
Maps to ProductData.metaDescription.
metaKeywords​
Maps to ProductData.metaKeywords.
taxCategory​
Maps to Product.taxCategory. If the referenced TaxCategory does not exist, the state of the ImportOperation will be set to unresolved until the referenced TaxCategory is created.
searchKeywords​
SearchKeywords​
Maps to ProductData.searchKeywords.
state​
Maps to Product.state. If the referenced State does not exist, the state of the ImportOperation will be set to unresolved until the referenced State is created.
publish​
Boolean​
Determines the published status and current/staged projection of the Product. For more information, see Managing the published state of Products.
Default: false​
priceMode​
ProductPriceModeEnum​
Maps to Product.priceMode.
Example: json
{
  "key": "product-key",
  "name": {
    "en": "t-shirt"
  },
  "productType": {
    "typeId": "product-type",
    "key": "product-type-key"
  },
  "slug": {
    "en": "t-shirt-slug"
  },
  "description": {
    "en": "t-shirt-description"
  },
  "categories": [
    {
      "typeId": "category",
      "key": "category-key"
    }
  ],
  "taxCategory": {
    "typeId": "tax-category",
    "key": "tax-category-key"
  },
  "state": {
    "typeId": "state",
    "key": "state-key"
  }
}

ProductDraftImport

The representation of a Product Draft for the import purpose.

key​
String​
User-defined unique identifier. If a Product with this key exists, it is updated with the imported data.
MinLength: 2​MaxLength: 256​
productType​
Maps to Product.productType. If the referenced ProductType does not exist, the state of the ImportOperation will be set to unresolved until the referenced ProductType is created.
name​
Maps to ProductData.name.
slug​
Maps to ProductData.slug.
description​
Maps to ProductData.description.
categories​
Maps to ProductData.categories. If the referenced Categories do not exist, the state of the ImportOperation will be set to unresolved until the referenced Categories are created.
attributes​
Array of Attribute​
metaTitle​
Maps to ProductData.metaTitle.
metaDescription​
Maps to ProductData.metaDescription.
metaKeywords​
Maps to ProductData.metaKeywords.
masterVariant​
The master ProductVariant. Required if variants contains at least one ProductVariant.
variants​

An array of related ProductVariants.

taxCategory​
Maps to Product.taxCategory. If the referenced TaxCategory does not exist, the state of the ImportOperation will be set to unresolved until the referenced TaxCategory is created.
searchKeywords​
SearchKeywords​
Maps to ProductData.searchKeywords.
state​
Maps to Product.state. If the referenced State does not exist, the state of the ImportOperation will be set to unresolved until the referenced State is created.
publish​
Boolean​
Determines the published status and current/staged projection of the Product. For more information, see Managing the published state of Products.
Default: false​
priceMode​
ProductPriceModeEnum​
Maps to Product.priceMode. If not provided, the existing Product.priceMode is not changed.
Example: json
{
  "key": "product-draft-key",
  "name": {
    "en": "blue shirt"
  },
  "slug": {
    "en": "blue-t-shirt"
  },
  "productType": {
    "typeId": "product-type",
    "key": "sample"
  },
  "masterVariant": {
    "key": "master-variant-key",
    "attributes": [
      {
        "type": "reference",
        "name": "product-ref-attribute",
        "value": {
          "key": "category-key",
          "typeId": "category"
        }
      },
      {
        "type": "reference",
        "name": "product-custom-object-ref-attribute",
        "value": {
          "key": "custom-object-key",
          "container": "custom-object-container-key",
          "typeId": "key-value-document"
        }
      }
    ]
  }
}

ProductVariantDraftImport

The representation of a Product Variant Draft for the import purpose.

key​
String​

User-defined unique identifier for the ProductVariant.

sku​
String​

User-defined unique SKU of the Product Variant.

prices​
Array of PriceDraftImport​
The Embedded Prices for the Product Variant. Each Price must have its unique Price scope (with same currency, country, Customer Group, Channel, validFrom and validUntil).
attributes​
Array of Attribute​

Attributes according to the respective AttributeDefinition.

images​
Array of Image​

Images for the Product Variant.

assets​
Array of Asset​

Media assets for the Product Variant.

EmbeddedPriceDraftImport

The representation of a Price Draft for the import purpose.

key​
String​

User-defined unique identifier for the Embedded Price.

MinLength: 2​MaxLength: 256​Pattern: ^[A-Za-z0-9_-]+$​
value​

Money value of this Price.

country​

Set this field if this Price is only valid for the specified country.

Pattern: ^[A-Z]{2}$​
customerGroup​
Set this field if this Price is only valid for the referenced CustomerGroup. If the referenced CustomerGroup does not exist, the state of the ImportOperation will be set to unresolved until the referenced CustomerGroup is created.
channel​
Set this field if this Price is only valid for the referenced ProductDistribution Channel. If the referenced Channel does not exist, the state of the ImportOperation will be set to unresolved until the referenced Channel is created.
validFrom​
Set this field if this Price is only valid from the specified date and time. Must be at least 1 ms earlier than validUntil.
validUntil​
Set this field if this Price is only valid until the specified date and time. Must be at least 1 ms later than validFrom.
discounted​
Set this field to add a DiscountedPrice from an external service.
tiers​
Array of PriceTier​

The tiered prices for this price.

custom​

Custom Fields for the Embedded Price.

for Product Variants

When updating an existing Product Variant by import, you must include the existing values of all fields in ProductVariantImport. The import process will remove the values of omitted fields.

ProductVariantImport

Represents the data used to import a ProductVariant. Once imported, this data is persisted as a ProductVariant in the Project.
key​
String​
User-defined unique identifier. If a ProductVariant with this key exists on the specified product, it is updated with the imported data.
sku​
String​
Maps to ProductVariant.sku.
isMasterVariant​
Boolean​
  • When creating a new ProductVariant, set to false; otherwise, the import operation will fail with a NewMasterVariantAdditionNotAllowed error.
  • Set to true if the ProductVariant exists and you want to set this ProductVariant as the Master Variant.
attributes​
Array of Attribute​
Maps to ProductVariant.attributes. The referenced attribute must be defined in an already existing ProductType in the project, or the state of the ImportOperation will be unresolved.
images​
Array of Image​
Maps to ProductVariant.images.
assets​
Array of Asset​
Maps to ProductVariant.assets.
staged​
Boolean​
Default: true​
product​
The Product containing this ProductVariant. If the referenced Product does not exist, the state of the ImportOperation will be set to unresolved until the referenced Product is created.
Example: json
{
  "key": "red-t-shirt",
  "sku": "red-t-shirt",
  "product": {
    "key": "t-shirt",
    "typeId": "product"
  },
  "isMasterVariant": true,
  "attributes": [
    {
      "name": "new",
      "type": "boolean",
      "value": true
    },
    {
      "name": "weight",
      "type": "number",
      "value": 12.5
    }
  ]
}

Attribute

Represents the Attribute value to be persisted in a Product Variant.
When importing nested Attributes BETA, do not include the type field, and value should be an array of Attributes. For more information about nested Attributes, see the Nested Attribute type learning page.
You can import Products with nested Attributes by using a ProductDraftImport or a ProductVariantImport.
Import a Product with nested Attributes using Product-Draftjson
{
  "type": "product-draft",
  "resources": [
    {
      "key": "example-t-shirt",
      "name": {
        "en": "example-t-shirt"
      },
      "slug": {
        "en": "example-t-shirt"
      },
      "productType": {
        "typeId": "product-type",
        "key": "t-shirt-product-type"
      },
      "masterVariant": {
        "key": "example-t-shirt-variant1",
        "attributes": [
          {
            "name": "fit",
            "value": "regular"
          },
          {
            "name": "fabricComposition",
            "value": [
              [
                {
                  "name": "percentage",
                  "value": 80
                },
                {
                  "name": "materialName",
                  "value": "COTTON"
                }
              ],
              [
                {
                  "name": "percentage",
                  "value": 20
                },
                {
                  "name": "materialName",
                  "value": "POLYESTER"
                }
              ]
            ]
          }
        ]
      }
    }
  ]
}
Import a Product Variant with nested Attributes using Product-Variantjson
{
  "type": "product-variant",
  "resources": [
    {
      "key": "example-t-shirt-variant1",
      "sku": "example-t-shirt-variant1",
      "product": {
        "key": "example-t-shirt",
        "typeId": "product"
      },
      "isMasterVariant": true,
      "attributes": [
        {
          "name": "fit",
          "value": "regular"
        },
        {
          "name": "fabricComposition",
          "value": [
            [
              {
                "name": "percentage",
                "value": 80
              },
              {
                "name": "materialName",
                "value": "COTTON"
              }
            ],
            [
              {
                "name": "percentage",
                "value": 15
              },
              {
                "name": "materialName",
                "value": "POLYESTER"
              }
            ],
            [
              {
                "name": "percentage",
                "value": 5
              },
              {
                "name": "materialName",
                "value": "ELASTANE"
              }
            ]
          ]
        }
      ]
    }
  ]
}

BooleanAttribute

This type represents an attribute whose value is either "true" or "false".

type​
String​
"boolean"
Must match type of an AttributeDefinition of the Product Type. The type is required if this type is used in a product variant and must not be set when used in a product variant patch.
value​
Boolean​
true or false

BooleanSetAttribute

This type represents an attribute whose value is set of boolean values.

name​
String​
Required if used for ProductVariantImport. Must not be set if used for ProductVariantPatch.
Must match name of an AttributeDefinition of the Product Type.
type​
String​
"boolean-set"
Must match type of an AttributeDefinition of the Product Type. The type is required if this type is used in a product variant and must not be set when used in a product variant patch.
value​
Array of Boolean​

A set of boolean values.

DateAttribute

This type represents an attribute whose value is a date.

name​
String​
Required if used for ProductVariantImport. Must not be set if used for ProductVariantPatch.
Must match name of an AttributeDefinition of the Product Type.
type​
String​
"date"
Must match type of an AttributeDefinition of the Product Type. The type is required if this type is used in a product variant and must not be set when used in a product variant patch.
value​
Date​
A date in the format YYYY-MM-DD.

DateSetAttribute

This type represents an attribute whose value is a set of dates.

name​
String​
Required if used for ProductVariantImport. Must not be set if used for ProductVariantPatch.
Must match name of an AttributeDefinition of the Product Type.
type​
String​
"date-set"
Must match type of an AttributeDefinition of the Product Type. The type is required if this type is used in a product variant and must not be set when used in a product variant patch.
value​
Array of Date​
A set of dates in the format YYYY-MM-DD.

DateTimeAttribute

This type represents an attribute whose value is a date with time.

name​
String​
Required if used for ProductVariantImport. Must not be set if used for ProductVariantPatch.
Must match name of an AttributeDefinition of the Product Type.
type​
String​
"datetime"
Must match type of an AttributeDefinition of the Product Type. The type is required if this type is used in a product variant and must not be set when used in a product variant patch.
value​
A date with time in the format YYYY-MM-DDTHH:mm:ss.SSSZ. The time zone is optional and defaults to UTC if not specified. If the time zone is specified, it must be in the format ±HH:mm or Z for UTC.

DateTimeSetAttribute

This type represents an attribute whose value is a set of dates with time.

name​
String​
Required if used for ProductVariantImport. Must not be set if used for ProductVariantPatch.
Must match name of an AttributeDefinition of the Product Type.
type​
String​
"datetime-set"
Must match type of an AttributeDefinition of the Product Type. The type is required if this type is used in a product variant and must not be set when used in a product variant patch.
value​
Array of DateTime​
A set of dates with time in the format YYYY-MM-DDTHH:mm:ss.SSSZ. The time zone is optional and defaults to UTC if not specified. If the time zone is specified, it must be in the format ±HH:mm or Z for UTC.

EnumAttribute

This type represents an attribute whose value is an enum. The attribute value refers to the key of the enum value.

name​
String​
Required if used for ProductVariantImport. Must not be set if used for ProductVariantPatch.
Must match name of an AttributeDefinition of the Product Type.
type​
String​
"enum"
Must match type of an AttributeDefinition of the Product Type. The type is required if this type is used in a product variant and must not be set when used in a product variant patch.
value​
String​
The key of the enum value. Must match the key of an AttributePlainEnumValue in the Product Type.

EnumSetAttribute

This type represents an attribute whose value is an enum. The attribute value refers to the key of the enum value.

name​
String​
Required if used for ProductVariantImport. Must not be set if used for ProductVariantPatch.
Must match name of an AttributeDefinition of the Product Type.
type​
String​
"enum-set"
Must match type of an AttributeDefinition of the Product Type. The type is required if this type is used in a product variant and must not be set when used in a product variant patch.
value​
Array of String​
A set of enum values, each represented by its key. Each key must match the key of an AttributePlainEnumValue in the Product Type.

LocalizableEnumAttribute

This type represents an attribute whose value is a localized enum. The attribute value refers to the key of the enum value.

name​
String​
Required if used for ProductVariantImport. Must not be set if used for ProductVariantPatch.
Must match name of an AttributeDefinition of the Product Type.
type​
String​
"lenum"
Must match type of an AttributeDefinition of the Product Type. The type is required if this type is used in a product variant and must not be set when used in a product variant patch.
value​
String​
The key of the localized enum value. Must match the key of an AttributeLocalizedEnumValue in the Product Type.

LocalizableEnumSetAttribute

This type represents an attribute whose value is a localized enum. The attribute value refers to the key of the enum value.

name​
String​
Required if used for ProductVariantImport. Must not be set if used for ProductVariantPatch.
Must match name of an AttributeDefinition of the Product Type.
type​
String​
"lenum-set"
Must match type of an AttributeDefinition of the Product Type. The type is required if this type is used in a product variant and must not be set when used in a product variant patch.
value​
Array of String​
A set of localized enum values, each represented by its key. Each key must match the key of an AttributeLocalizedEnumValue in the Product Type.

LocalizableTextAttribute

This type represents an attribute whose value is a localized text.

name​
String​
Required if used for ProductVariantImport. Must not be set if used for ProductVariantPatch.
Must match name of an AttributeDefinition of the Product Type.
type​
String​
"ltext"
Must match type of an AttributeDefinition of the Product Type. The type is required if this type is used in a product variant and must not be set when used in a product variant patch.
value​

A localized string.

LocalizableTextSetAttribute

This type represents an attribute whose value is a localized text.

name​
String​
Required if used for ProductVariantImport. Must not be set if used for ProductVariantPatch.
Must match name of an AttributeDefinition of the Product Type.
type​
String​
"ltext-set"
Must match type of an AttributeDefinition of the Product Type. The type is required if this type is used in a product variant and must not be set when used in a product variant patch.
value​
Array of LocalizedString​

A set of localized strings.

MoneyAttribute

This type represents an attribute whose value is a money object.

name​
String​
Required if used for ProductVariantImport. Must not be set if used for ProductVariantPatch.
Must match name of an AttributeDefinition of the Product Type.
type​
String​
"money"
Must match type of an AttributeDefinition of the Product Type. The type is required if this type is used in a product variant and must not be set when used in a product variant patch.
value​

A money value in cent precision format.

MoneySetAttribute

This type represents an attribute whose value is a set of money objects.

name​
String​
Required if used for ProductVariantImport. Must not be set if used for ProductVariantPatch.
Must match name of an AttributeDefinition of the Product Type.
type​
String​
"money-set"
Must match type of an AttributeDefinition of the Product Type. The type is required if this type is used in a product variant and must not be set when used in a product variant patch.
value​
Array of TypedMoney​

A set of money values in cent precision format.

NumberAttribute

This type represents an attribute whose value is a number.

name​
String​
Required if used for ProductVariantImport. Must not be set if used for ProductVariantPatch.
Must match name of an AttributeDefinition of the Product Type.
type​
String​
"number"
Must match type of an AttributeDefinition of the Product Type. The type is required if this type is used in a product variant and must not be set when used in a product variant patch.
value​
Float​

A number value. Can be an integer or a floating-point number.

NumberSetAttribute

This type represents an attribute whose value is a set of numbers.

name​
String​
Required if used for ProductVariantImport. Must not be set if used for ProductVariantPatch.
Must match name of an AttributeDefinition of the Product Type.
type​
String​
"number-set"
Must match type of an AttributeDefinition of the Product Type. The type is required if this type is used in a product variant and must not be set when used in a product variant patch.
value​
Array of Number​

A set of number values. Each value can be an integer or a floating-point number.

ReferenceAttribute

This type represents an attribute whose value is a key reference.

name​
String​
Required if used for ProductVariantImport. Must not be set if used for ProductVariantPatch.
Must match name of an AttributeDefinition of the Product Type.
type​
String​
"reference"
Must match type of an AttributeDefinition of the Product Type. The type is required if this type is used in a product variant and must not be set when used in a product variant patch.
value​

References a resource by key.

Example: json
{
  "type": "reference",
  "name": "product-custom-object-ref-attribute",
  "value": {
    "key": "custom-object-key",
    "container": "custom-object-container",
    "typeId": "key-value-document"
  }
}

ReferenceSetAttribute

This type represents an attribute whose value is a set of references.

name​
String​
Required if used for ProductVariantImport. Must not be set if used for ProductVariantPatch.
Must match name of an AttributeDefinition of the Product Type.
type​
String​
"reference-set"
Must match type of an AttributeDefinition of the Product Type. The type is required if this type is used in a product variant and must not be set when used in a product variant patch.
value​
Array of KeyReference​

A set of references, each referencing a resource by key. Each reference must match the key of an existing resource in the project.

TextAttribute

This type represents an attribute whose value is a string.

name​
String​
Required if used for ProductVariantImport. Must not be set if used for ProductVariantPatch.
Must match name of an AttributeDefinition of the Product Type.
type​
String​
"text"
Must match type of an AttributeDefinition of the Product Type. The type is required if this type is used in a product variant and must not be set when used in a product variant patch.
value​
String​

A text value.

TextSetAttribute

This type represents an attribute whose value is a set of strings.

name​
String​
Required if used for ProductVariantImport. Must not be set if used for ProductVariantPatch.
Must match name of an AttributeDefinition of the Product Type.
type​
String​
"text-set"
Must match type of an AttributeDefinition of the Product Type. The type is required if this type is used in a product variant and must not be set when used in a product variant patch.
value​
Array of String​

A set of text values.

TimeAttribute

This type represents an attribute whose value is a time.

name​
String​
Required if used for ProductVariantImport. Must not be set if used for ProductVariantPatch.
Must match name of an AttributeDefinition of the Product Type.
type​
String​
"time"
Must match type of an AttributeDefinition of the Product Type. The type is required if this type is used in a product variant and must not be set when used in a product variant patch.
value​
Time​
A time value in the format HH:mm:ss.SSS. The time zone is optional and defaults to UTC if not specified. If the time zone is specified, it must be in the format ±HH:mm or Z for UTC.

TimeSetAttribute

This type represents an attribute whose value is a set of times.

name​
String​
Required if used for ProductVariantImport. Must not be set if used for ProductVariantPatch.
Must match name of an AttributeDefinition of the Product Type.
type​
String​
"time-set"
Must match type of an AttributeDefinition of the Product Type. The type is required if this type is used in a product variant and must not be set when used in a product variant patch.
value​
Array of Time-only​
A set of time values in the format HH:mm:ss.SSS. The time zone is optional and defaults to UTC if not specified. If the time zone is specified, it must be in the format ±HH:mm or Z for UTC.

ProductVariantPatch

Represents the data used to update a ProductVariant.
productVariant​
Reference to the ProductVariant to update.
attributes​
Maps to ProductVariant.attributes.
  • The referenced Attribute must be defined in an existing ProductType, or the state of the ImportOperation will be validationFailed.
  • Setting the value of a non-required Attribute to null will remove the Attribute.
  • Attempting to set a null value to a required Attribute will make the import operation fail with an InvalidOperation error.
  • Importing LocalizableTextAttributes or LocalizableTextSetAttributes follows an override pattern, meaning that omitted localized fields will be deleted, new fields will be created, and existing fields will be updated. You can delete localized fields by setting their value to null.
staged​
Boolean​
If false, the attribute changes are applied to both current and staged projected representations of the Product.
Default: true​
product​
Reference to the Product that contains the ProductVariant.
We recommend to set this value to minimize concurrency errors. If set, this field is required for every ProductVariantPatch in the ProductVariantPatchRequest.
If the referenced Product does not exist, the state of the ImportOperation will be set to unresolved until the referenced Product is created.
Example: json
{
  "productVariant": {
    "typeId": "product-variant",
    "key": "red-t-shirt"
  },
  "attributes": {
    "attribute-to-update": {
      "type": "boolean",
      "value": true
    },
    "name-of-attribute-to-delete": null,
    "name-of-localized-attribute-to-update": {
      "type": "ltext",
      "value": {
        "en": "Existing field",
        "es": null,
        "de": "Updating field"
      }
    },
    "name-of-localized-attribute-set-to-update": {
      "type": "ltext-set",
      "value": [
        {
          "en": "Existing field",
          "es": null,
          "de": "Updating field",
          "br": "New field"
        },
        {
          "en": "Another Existing field",
          "es": null,
          "de": "Another Updating field",
          "br": "Another New field"
        }
      ]
    }
  },
  "staged": false
}

for Variants

This import resource is only available for Projects with productCatalogModel set to Modular.

VariantImport

Represents the data used to import a Variant. Once imported, this data is persisted as a Variant in the Project.
This import resource is only available for Projects with productCatalogModel set to Modular.
key​
String​
User-defined unique identifier. If a Variant with this key exists, it is updated with the imported data.
sku​
String​
Maps to VariantData.sku.
product​
Maps to Variant.product.
publish​
Boolean​
Indicates whether the Variant is published. If true, the Variant is immediately available in the current published state. Maps to VariantDraft.publish.
Default: false​
images​
Array of Image​
Maps to VariantData.images.
attributes​
Array of Attribute​
Maps to VariantData.attributes.
assets​
Array of Asset​
Maps to VariantData.assets.

for Product Selections

ProductSelectionImport

Represents the data used to import a ProductSelection. Once imported, this data is persisted as a ProductSelection in the Project.
key​
String​
User-defined unique identifier. If an ProductSelection with this key exists, it is updated with the imported data.
name​
Maps to ProductSelection.name.
Maps to ProductSelection.mode.
Default: Individual​
assignments​

List of product assignments.

custom​
Maps to ProductSelection.custom.

ProductSelectionAssignment

An assignment of a product and either variantSelection or variantExclusion (not both).

product​

Reference to the Product by key.

variantSelection​
VariantSelection​

Variant selection specifying included SKUs.

variantExclusion​
VariantExclusion​

Variant exclusion specifying excluded SKUs.

VariantSelectionType

Defines how variants are selected for the product.

includeOnly

Only the specified SKUs are included.

includeAllExcept

All variants except the specified SKUs are included.

for Product Tailoring

ProductTailoringImport

Represents the data used to import a Product Tailoring. Once imported, this data is persisted as a ProductTailoring in the Project.
key​
String​
User-defined unique identifier. If a ProductTailoring with this key exists, it is updated with the imported data.
MinLength: 2​MaxLength: 256​
store​
The Store to which the ProductTailoring belongs. If the referenced Store does not exist, the state of the ImportOperation will be set to unresolved until the referenced Store is created.
product​
The Product to which the ProductTailoring belongs. If the referenced Product does not exist, the state of the ImportOperation will be set to unresolved until the referenced Product is created.
name​
Maps to ProductTailoring.name.
description​
Maps to ProductTailoring.description.
metaTitle​
Maps to ProductTailoring.metaTitle.
metaDescription​
Maps to ProductTailoring.metaDescription.
metaKeywords​
Maps to ProductTailoring.metaKeywords.
slug​
Maps to ProductTailoring.slug.
publish​
Boolean​

Whether to publish the ProductTailoring immediately. Otherwise, the tailored product information is just staged.

Default: false​
variants​

Tailored Variants of the Product.

attributes​
Array of Attribute​

Attributes of the tailored Product.

Example: json
{
  "key": "product-tailoring-key",
  "store": {
    "typeId": "store",
    "key": "store-key"
  },
  "product": {
    "typeId": "product",
    "key": "product-key"
  },
  "name": {
    "en": "Tailored Product Name"
  },
  "description": {
    "en": "Tailored product description"
  },
  "slug": {
    "en": "tailored-product-slug"
  },
  "publish": false,
  "variants": [
    {
      "sku": "tailored-variant-sku",
      "images": [
        {
          "url": "https://example.com/image.png",
          "dimensions": {
            "w": 100,
            "h": 100
          },
          "label": "Tailored image"
        }
      ]
    }
  ]
}

ProductVariantTailoringImport

Represents the data of a Product Variant to be tailored for a Store.

sku​
String​
The sku of the ProductVariant to be tailored.
images​
Array of Image​
Maps to ProductVariantTailoring.images.
assets​
Array of Asset​
Maps to ProductVariantTailoring.assets.
attributes​
Array of Attribute​
Maps to ProductVariantTailoring.attributes.

for Prices

EmbeddedPriceImport

Represents the data used to import an Embedded Price . Once imported, this data is persisted as a Price in a Product Variant.
key​
String​
User-defined unique identifier for the Embedded Price. If a Price with this key exists on the specified productVariant, it is updated with the imported data.
MinLength: 2​MaxLength: 256​Pattern: ^[A-Za-z0-9_-]+$​
value​
Maps to Price.value.
country​
Maps to Price.county.
Pattern: ^[A-Z]{2}$​
validFrom​
Maps to Price.validFrom.
validUntil​
Maps to Price.validUntil.
customerGroup​
Maps to Price.customerGroup. If the referenced CustomerGroup does not exist, the state of the ImportOperation will be set to unresolved until the referenced CustomerGroup is created.
channel​
Maps to Price.channel. If the referenced Channel does not exist, the state of the ImportOperation will be set to unresolved until the referenced Channel is created.
discounted​

Sets a discounted price from an external service.

staged​
Boolean​
Default: true​
tiers​
Array of PriceTier​

The tiered prices for this price.

productVariant​
The ProductVariant which contains this Embedded Price. If the referenced ProductVariant does not exist, the state of the ImportOperation will be set to unresolved until the referenced ProductVariant is created.
product​
The Product which contains the productVariant. If the referenced Product does not exist, the state of the ImportOperation will be set to unresolved until the referenced Product is created.
custom​
Maps to Price.custom.
Example: json
{
  "key": "price-key",
  "country": "DE",
  "validFrom": "2021-04-11T14:00:00.000Z",
  "validUntil": "2022-04-11T14:00:00.000Z",
  "customerGroup": {
    "typeId": "customer-group",
    "key": "customer-group-key"
  },
  "channel": {
    "typeId": "channel",
    "key": "channel-key"
  },
  "productVariant": {
    "typeId": "product-variant",
    "key": "red-t-shirt"
  },
  "product": {
    "typeId": "product",
    "key": "t-shirt"
  },
  "value": {
    "type": "centPrecision",
    "currencyCode": "EUR",
    "centAmount": 300
  }
}

StandalonePriceImport

When updating an existing StandalonePrice by import, you must include the existing values of all fields in StandalonePriceImport. The import process will remove the values of omitted fields.
Represents the data used to import a StandalonePrice. Once imported, this data is persisted as a StandalonePrice) in the Project.
key​
String​
User-defined unique identifier for the StandalonePrice. If a StandalonePrice) with this key exists, it is updated with the imported data.
MinLength: 2​MaxLength: 256​Pattern: ^[A-Za-z0-9_-]+$​
sku​
String​
Maps to StandalonePrice.sku. This value is not validated to exist in Product Variants.
value​
Maps to StandalonePrice.value.
country​
Maps to StandalonePrice.country. This value cannot be updated. Attempting to update this value will result in an InvalidFieldsUpdate error.
Pattern: ^[A-Z]{2}$​
customerGroup​
Maps to StandalonePrice.customerGroup. If the referenced CustomerGroup does not exist, the state of the ImportOperation will be set to unresolved until the referenced CustomerGroup is created.
This value cannot be updated. Attempting to update this value will result in an InvalidFieldsUpdate error.
channel​
Maps to StandalonePrice.channel. If the referenced Channel does not exist, the state of the ImportOperation will be set to unresolved until the referenced Channel is created.
This value cannot be updated. Attempting to update this value will result in an InvalidFieldsUpdate error.
validFrom​
Maps to StandalonePrice.validFrom.
validUntil​
Maps to StandalonePrice.validUntil.
tiers​
Array of PriceTier​
Maps to StandalonePrice.tiers.
discounted​

Sets a discounted price for this Price that is different from the base price with value.

active​
Boolean​
Maps to StandalonePrice.active.
To exclude the StandalonePrice from Product price selection, set to false.
Default: true​
custom​
Maps to StandalonePrice.custom.
Example: json
{
  "key": "standalone-price-key",
  "sku": "variantSku",
  "value": {
    "type": "centPrecision",
    "currencyCode": "EUR",
    "centAmount": 100
  },
  "active": true
}

for Orders

OrderImport

Represents the data used to import an Order. Once imported, this data is persisted as an Order in the Project.

An OrderImport is a snapshot of an order at the time it was imported.

orderNumber​
String​
Maps to Order.orderNumber, String that uniquely identifies an order. It should be unique across a project. Once it's set it cannot be changed.
customer​
key of the Customer that the Order belongs to. If the referenced Customer does not exist, the state of the ImportOperation will be set to unresolved until the referenced Customer is created.
customerEmail​
String​
Maps to Order.customerEmail.
lineItems​
Maps to Order.lineItems.
customLineItems​
Maps to Order.customLineItems
totalPrice​
Maps to Order.totalPrice.
taxedPrice​
TaxedPrice​
Maps to Order.taxedPrice.
shippingAddress​
Maps to Order.shippingAddress.
billingAddress​
Maps to Order.billingAddress.
customerGroup​
Maps to Order.customerGroup. If the referenced CustomerGroup does not exist, the state of the ImportOperation will be set to unresolved until the referenced CustomerGroup is created.
country​
String​
Maps to Order.country.
orderState​
Maps to Order.orderState.
shipmentState​
Maps to Order.shipmentState.
paymentState​
Maps to Order.paymentState.
shippingInfo​
Maps to Order.shippingInfo.
completedAt​
Maps to Order.completedAt.
inventoryMode​
Maps to Order.inventoryMode.
taxRoundingMode​
Maps to Order.taxRoundingMode.
taxCalculationMode​
Maps to Order.taxCalculationMode.
origin​
Maps to Order.origin.
itemShippingAddresses​
Array of Address​
Maps to Order.itemShippingAddresses.
store​
Maps to Order.store. If the referenced Store does not exist, the state of the ImportOperation will be set to unresolved until the referenced Store is created.
state​
Maps to Order.state. If the referenced State does not exist, the state of the ImportOperation will be set to unresolved until the referenced State is created.
custom​
Maps to Order.custom.
Example: json
{
  "orderNumber": "order-number",
  "customer": {
    "typeId": "customer",
    "key": "order-customer-key"
  },
  "lineItems": [
    {
      "name": {
        "en": "abc"
      },
      "quantity": 10,
      "price": {
        "value": {
          "type": "centPrecision",
          "centAmount": 100,
          "currencyCode": "EUR"
        }
      },
      "supplyChannel": {
        "typeId": "channel",
        "key": "supplier-channel-key"
      },
      "variant": {
        "productVariant": {
          "typeId": "product-variant",
          "key": "product-key"
        },
        "sku": "variant-sku"
      }
    }
  ],
  "customerGroup": {
    "typeId": "customer-group",
    "key": "customer-group-key"
  },
  "totalPrice": {
    "type": "centPrecision",
    "currencyCode": "EUR",
    "centAmount": 4200
  }
}

LineItemImportDraft

Represents an individual Line Item in an Order. A line item is a snapshot of a product at the time it was added to the order.

You cannot create an Order that includes line item operations that do not exist in the Project or have been deleted. Products and Product Variants referenced by a line item must already exist in the Project. Product Attributes are merged with Variant Attributes to ensure the full Attribute context of the Product Variant.

product​
Maps to LineItem.productId. If the referenced Product does not exist, the state of the ImportOperation will be set to unresolved until the referenced Product is created.
name​
Maps to LineItem.name.
variant​
Maps to ProductVariantImportDraft.
price​
Maps to LineItem.price.
quantity​
Int64​
Maps to LineItem.quantity.
state​
Array of ItemState​
Maps to LineItem.state.
supplyChannel​
Maps to LineItem.supplyChannel. If the referenced Channel does not exist, the state of the ImportOperation will be set to unresolved until the referenced Channel is created.
distributionChannel​
Maps to LineItem.distributionChannel. If the referenced Channel does not exist, the state of the ImportOperation will be set to unresolved until the referenced Channel is created.
taxRate​
TaxRate​
Maps to LineItem.taxRate.
shippingDetails​
Maps to LineItem.shippingDetails.
custom​
Maps to LineItem.custom.

CustomLineItemDraft

name​
Maps to CustomLineItem.name.
money​
Maps to CustomLineItem.money.
taxedPrice​
CustomLineItemTaxedPrice​
Maps to CustomLineItem.taxedPrice.
totalPrice​
Maps to CustomLineItem.totalPrice.
slug​
String​
Maps to CustomLineItem.slug.
quantity​
Int64​
Maps to CustomLineItem.quantity.
state​
Array of ItemState​
Maps to CustomLineItem.state.
taxCategory​
Maps to CustomLineItem.taxCategory. References a tax category by key. If the referenced TaxCategory does not exist, the state of the ImportOperation will be set to unresolved until the referenced TaxCategory is created.
taxRate​
TaxRate​
Maps to CustomLineItem.taxRate.
externalTaxRate​
External Tax Rate for the Custom Line Item if the Cart has the External TaxMode.
discountedPricePerQuantity​
Maps to CustomLineItem.discountedPricePerQuantity.
shippingDetails​
Maps to CustomLineItem.shippingDetails.

LineItemProductVariantImportDraft

productVariant​
Maps to ProductVariant.product. If the referenced ProductVariant does not exist, the state of the ImportOperation will be set to unresolved until the referenced ProductVariant is created.
sku​
String​
Maps to ProductVariantImportDraft.sku.
prices​
Array of LineItemPrice​
Maps to ProductVariantImportDraft.prices
attributes​
Array of Attribute​
Maps to ProductVariantImportDraft.attributes
images​
Array of Image​
Maps to ProductVariantImportDraft.images.

LineItemPrice

value​
Maps to Price.value.
country​
Maps to Price.county.
Pattern: ^[A-Z]{2}$​
validFrom​
Maps to Price.validFrom.
validUntil​
Maps to Price.validUntil.
customerGroup​
Maps to Price.customerGroup. References a customer group by key. If the referenced CustomerGroup does not exist, the state of the ImportOperation will be set to unresolved until the referenced CustomerGroup is created.
channel​
Maps to Price.channel. References a channel by key. If the referenced Channel does not exist, the state of the ImportOperation will be set to unresolved until the referenced Channel is created.
discounted​

Sets a discounted price from an external service.

tiers​
Array of PriceTier​
Maps to Price.tiers.
custom​
Maps to Price.custom.

DiscountedPrice

value​

Money value of the discounted price.

discount​
Reference to a ProductDiscount. If the referenced ProductDiscount does not exist, the state of the ImportOperation will be set to unresolved until the referenced ProductDiscount is created.

DiscountedLineItemPriceDraft

value​

Discounted money value.

includedDiscounts​

Discounts to be applied.

ShippingInfoImportDraft

Maps to an Order's shippingInfo property. This field is usually populated by the Cart associated with the Order, but when importing Orders you must provide a draft representation as a part of the OrderImport.
shippingMethodName​
String​
Maps to shippingInfo.shippingMethodName.
price​
Maps to shippingInfo.price.
shippingRate​

Used to determine the price.

taxRate​
TaxRate​
Maps to shippingInfo.taxRate.
taxCategory​
Maps to shippingInfo.taxCategory. If the referenced TaxCategory does not exist, the state of the ImportOperation will be set to unresolved until the referenced TaxCategory is created.
shippingMethod​
Maps to shippingInfo.shippingMethod. If the referenced ShippingMethod does not exist, the state of the ImportOperation will be set to unresolved until the referenced ShippingMethod is created.
deliveries​
Array of Delivery​
Maps to shippingInfo.deliveries. You cannot add a DeliveryItem on import, as LineItems and CustomLineItems are not yet referenceable by an id.
discountedPrice​
Maps to shippingInfo.discountedPrice.
shippingMethodState​
Maps to shippingInfo.shippingMethodState.

OrderPatchImport

Represents the data used to update an Order in a Project.
orderNumber​
String​
User-defined unique identifier. If an Order with this orderNumber exists, it is updated with the imported data.
fields​
Each field referenced must be defined in an existing Order or the ImportOperationState is set to validationFailed.

OrderField

Order fields that needs to be added or updated.

addReturnInfo​
Maps to Order.returnInfo
addParcelToDelivery​
Maps to Order.delivery
addDeliveries​
Array of DeliveryDraft​
Maps to Order.delivery
removeDelivery​
Maps to Order.removeDelivery
removeParcelFromDelivery​
Maps to Order.removeParcelFromDelivery
setDeliveryAddress​
Maps to Order.addressDraft
setParcelMeasurements​
Maps to Order.parcelMeasurements
setParcelTrackingData​
Maps to Order.parcelTrackingData
setParcelItems​
Array of ParcelItems​
Maps to Order.parcelItems

ReturnInfo

items​
Array of ReturnItemDraft​

Information on the Line Items or Custom Line Items returned.

returnTrackingId​
String​

User-defined identifier to track the return.

returnDate​

Date and time (UTC) the return is initiated.

DeliveryParcel

deliveryId​
String​

Unique identifier of the Delivery.

measurements​

Information about the dimensions of the Parcel.

trackingData​

Shipment tracking information of the Parcel.

items​
Array of DeliveryItem​

Line Items or Custom Line Items delivered in this Parcel.

DeliveryItem

id​
String​
id of the LineItem or CustomLineItem delivered.
quantity​
Int64​

Quantity of Line Items or Custom Line Items delivered.

DeliveryDraft

items​
Array of DeliveryItem​
Line Items or Custom Line Items to deliver. It can also be specified individually for each Parcel.
address​

Address to which the Parcels are delivered.

parcels​

Information regarding the appearance, content, and shipment of a parcel.

DeliveryParcelDraft

measurements​

Information about the dimensions for the Parcel.

trackingData​

Shipment tracking information for the Parcel.

items​
Array of DeliveryItem​

Line Items or Custom Line Items delivered in this Parcel.

DeliveryAddressDraft

deliveryId​
String​

Unique identifier of the Delivery.

address​

Address to which Parcels are delivered.

ParcelMeasurement

heightInMillimeter​
Int32​

Height of the Parcel.

lengthInMillimeter​
Int32​

Length of the Parcel.

widthInMillimeter​
Int32​

Width of the Parcel.

weightInGram​
Int32​

Weight of the Parcel.

ParcelMeasurementDraft

parcelId​
String​
id of an existing Parcel.
measurements​

Information about the dimensions of the Parcel.

ParcelTrackingData

parcelId​
String​
id of an existing Parcel.
trackingData​

Information that helps track a Parcel.

TrackingData

trackingId​
String​

Identifier to track the Parcel.

carrier​
String​

Name of the carrier that delivers the Parcel.

provider​
String​

Name of the provider that serves as facade to several carriers.

providerTransaction​
String​
Transaction identifier with the provider.
isReturn​
Boolean​
Whether the Parcel is being returned. If false, the Parcel is being delivered to the customer.

ParcelItems

parcelId​
String​
id of an existing Parcel.
items​
Array of DeliveryItem​

Items in the Parcel.

RemoveDeliveryDraft

id​
String​

RemoveParcelFromDeliveryDraft

parcelId​
String​
id of the Parcel to be removed from the Delivery.

for Custom Types

TypeImport

Represents the data used to import a Type. Once imported, this data is persisted as a Type in the Project.
key​
String​
User-defined unique identifier for the Type. If a Type with this key exists, it is updated with the imported data.
MinLength: 2​MaxLength: 256​Pattern: ^[A-Za-z0-9_-]+$​
name​
Maps to Type.name.
description​
Maps to Type.description.
resourceTypeIds​
Array of ResourceTypeId​
Maps to Type.resourceTypeIds. This value cannot be changed after the Type is imported.
MinItems: 1​
fieldDefinitions​
Array of FieldDefinition​
Maps to Type.fieldDefinitions.
Example: json
{
  "key": "type-key",
  "name": {
    "en": "Name of type"
  },
  "description": {
    "en": "Description of type"
  },
  "resourceTypeIds": [
    "customer"
  ],
  "fieldDefinitions": [
    {
      "type": {
        "name": "String"
      },
      "name": "exampleStringField",
      "label": {
        "en": "Example string field."
      },
      "required": false,
      "inputHint": "SingleLine"
    }
  ]
}

ResourceTypeId

IDs indicating the type of resource. Maps to Type.resourceTypeIds.
address
asset
business-unit
cart-discount
category
channel
customer
customer-group
custom-line-item
discount-code
inventory-entry
line-item
order
Cart and Order. When a Cart is ordered, the CustomFields need to be copied to the Order. For this reason, the Types for Carts are also valid for Orders, and hence both have the same identifier: order.
order-edit
order-delivery
order-parcel
order-return-item
payment
payment-interface-interaction
product-price
product-selection
quote
Quote, QuoteRequest and StagedQuote. When a StagedQuote is created, the CustomFields will be copied from the QuoteRequest and when a Quote is created, the CustomFields will be copied from the StagedQuote. For this reason, the Types for Quotes are also valid for QuoteRequests and StagedQuotes, and hence all have the same identifier: quote.
review
shipping
shipping-method
shopping-list
shopping-list-text-line-item
standalone-price
store
transaction

FieldDefinition

Defines a Custom Field and its meta-information. Maps to Type.FieldDefinition.
type​

Data type of the Custom Field to define.

name​
String​
Name of the Custom Field that you want to define. The name must be unique for a given ResourceTypeId. If a FieldDefinition with the same name is defined in another Type for the same ResourceTypeId, then both FieldDefinitions must have the same type. This value can't be changed after you import the Type.
MinLength: 2​MaxLength: 36​Pattern: ^[A-Za-z0-9_-]+$​
label​

A human-readable label for the field.

required​
Boolean​

Defines whether the field is required to have a value. This value cannot be changed after the Type is imported.

inputHint​
Provides a visual representation type for this field. It is only relevant for string-based field types like CustomFieldStringType and CustomFieldLocalizedStringType.
Default: SingleLine​

TypeTextInputHint

Provides a visual representation type for this field. It is only relevant for string-based field types like CustomFieldStringType and CustomFieldLocalizedStringType.
SingleLine

Hint for GUIs to display the field's content in a single line of text.

MultiLine

Hint for GUIs to display the field's content over multiple lines of text.

common to Import Resources

Custom Fields

The value representations of Custom Fields defined on Import Resources.

Custom

The representation to be sent to the server when creating a resource with Custom Fields.

type​
The Type that provides the field definitions for this object. If the referenced Type does not exist, the state of the ImportOperation will be set to unresolved until the referenced Type is created.
fields​

The Custom Fields of this object.

FieldContainer

JSON object containing key-value pairs with

Example FieldContainer with three Custom Fields of different FieldTypesjson
{
  "example-boolean-field": {
    "type": "Boolean",
    "value": true
  },
  "example-localized-string-field": {
    "type": "LocalizedString",
    "value": {
      "en": "English text",
      "es": "texto en español"
    }
  },
  "example-datetime-field": {
    "type": "DateTime",
    "value": "2018-10-14T14:00:00.000Z"
  }
}

CustomField

JSON object with two fields:

  • type: The name of the corresponding FieldType.
  • value: The actual value of the Custom Field compliant to the type, see specific types in this section.

BooleanField

A field with a boolean value.

type​
String​
"Boolean"

The type of this field.

value​
Boolean​
true or false

StringField

A field with a string value.

type​
String​
"String"

The type of this field.

value​
String​

A text value.

  "example-string-field": {
    "type": "String",
    "value": "Some String value"
  }

LocalizedStringField

A field with a localized string value.

type​
String​
"LocalizedString"

The type of this field.

value​

A localized string.

  "example-localized-string-field": {
    "type": "LocalizedString",
    "value": {
      "en": "English text",
      "es": "texto en español"
    }
  }

EnumField

A field with an enum value.

type​
String​
"Enum"

The type of this field.

value​
String​
The key of the enum value. Must be a key of one of the CustomFieldEnumValues defined in the CustomFieldEnumType.
  "example-enum-field": {
    "type": "Enum",
    "value": "key-of-the-enum-value"
  }

LocalizedEnumField

A field with a localized enum value.

type​
String​
"LocalizedEnum"

The type of this field.

value​
String​
The key of the localized enum value. Must match the key of a CustomFieldLocalizedEnumValue in the CustomFieldLocalizedEnumType.
  "example-localized-enum-field": {
    "type": "LocalizedEnum",
    "value": "key-of-the-localized-enum-value"
  }

NumberField

A field with a number value.

type​
String​
"Number"

The type of this field.

value​
Float​

A number value. Can be an integer or a floating-point number.

 "example-number-field": {
    "type": "Number",
    "value": 123
  }

MoneyField

A field with a money value.

type​
String​
"Money"

The type of this field.

value​

A money value in cent precision format.

  "example-money-field": {
    "type": "Money",
    "value": {
      "type": "centPrecision",
      "currencyCode": "USD",
      "centAmount": 124500,
      "fractionDigits": 2
    }
  }

DateField

A field with a date value.

type​
String​
"Date"

The type of this field.

value​
Date​
A date in the format YYYY-MM-DD.
  "example-date-field": {
    "type": "Date",
    "value": "2001-10-12"
  }

TimeField

A field with a time value.

type​
String​
"Time"

The type of this field.

value​
Time​
A time value in the format HH:mm:ss.SSS. The time zone is optional and defaults to UTC if not specified. If the time zone is specified, it must be in the format ±HH:mm or Z for UTC.
  "example-time-field": {
    "type": "Time",
    "value": "14:00:00.000"
  }

DateTimeField

A field with a date time value.

type​
String​
"DateTime"

The type of this field.

value​
A date with time in the format YYYY-MM-DDTHH:mm:ss.SSSZ. The time zone is optional and defaults to UTC if not specified. If the time zone is specified, it must be in the format ±HH:mm or Z for UTC.
  "example-datetime-field": {
    "type": "DateTime",
    "value": "2018-10-14T14:00:00.000Z"
  }

ReferenceField

A field with a reference value.

type​
String​
"Reference"

The type of this field.

value​

References a resource by key

  "example-reference-field": {
    "type": "Reference",
    "value": {
      "typeId": "product",
      "key": "key-of-a-product"
    }
  }

BooleanSetField

A field with a boolean set value.

type​
String​
"BooleanSet"

The type of this field.

value​
Array of Boolean​

JSON array of boolean values without duplicates. The order of items in the array is not fixed.

  "example-set-of-boolean-field": {
    "type": "BooleanSet",
    "value": [true, false, true]
  }

StringSetField

A field with a string set value.

type​
String​
"StringSet"

The type of this field.

value​
Array of String​

JSON array of strings. The order of items in the array is not fixed.

  "example-set-of-string-field": {
    "type": "StringSet",
    "value": ["Some String value 1", "Some String value 2"]
  }

LocalizedStringSetField

A field with a localized string set value.

type​
String​
"LocalizedStringSet"

The type of this field.

value​
Array of LocalizedString​

JSON array of localized strings. The order of items in the array is not fixed.

  "example-set-of-localized-string-field": {
    "type": "LocalizedStringSet",
    "value": [
      {
        "en": "English text 1",
        "es": "texto en español 1"
      },
      {
        "en": "English text 2",
        "es": "texto en español 2"
      }
    ]
  }

EnumSetField

A field with an enum set value.

type​
String​
"EnumSet"

The type of this field.

value​
Array of String​
JSON array of enum values, each represented by its key. Each key must match the key of a CustomFieldLocalizedEnumValue in the CustomFieldEnumType. The order of items in the array is not fixed.
  "example-set-of-enum-field": {
    "type": "Enum",
    "value": ["key-of-enum-value-1", "key-of-enum-value-2", "key-of-enum-value-3"]
  }

LocalizedEnumSetField

A field with a localized enum set value.

type​
String​
"LocalizedEnumSet"

The type of this field.

value​
Array of String​
JSON array of localized enum values, each represented by its key. Each key must match the key of an CustomFieldLocalizedEnumValue in the CustomFieldLocalizedEnumType. The order of items in the array is not fixed.
  "example-set-of-localized-enum-field": {
    "type": "Enum",
    "value": ["key-of-localized-enum-value-1", "key-of-localized-enum-value-2"]
  }

NumberSetField

A field with a number value.

type​
String​
"NumberSet"

The type of this field.

value​
Array of Number​

JSON array of integer or floating-point number values. The order of items in the array is not fixed.

  "example-set-of-number-field": {
    "type": "NumberSet",
    "value": [123, 456]
  }

MoneySetField

A field with a money set value.

type​
String​
"MoneySet"

The type of this field.

value​
Array of TypedMoney​

JSON array of money values in cent precision format. The order of items in the array is not fixed.

  "example-set-of-money-field": {
    "type": "MoneySet",
    "value": [
      {
        "type": "centPrecision",
        "currencyCode": "USD",
        "centAmount": 124500,
        "fractionDigits": 2
      },
      {
        "type": "centPrecision",
        "currencyCode": "USD",
        "centAmount": 1000,
        "fractionDigits": 2
      }
    ]
  }

DateSetField

A field with a date set value.

type​
String​
"DateSet"

The type of this field.

value​
Array of Date​
JSON array of date values in the format YYYY-MM-DD without duplicates. The order of items in the array is not fixed.
  "example-set-of-date-field": {
    "type": "DateSet",
    "value": ["2001-10-12", "2001-10-13"]
  }

TimeSetField

A field with a time set value.

type​
String​
"TimeSet"

The type of this field.

value​
Array of Time-only​
JSON array of time values in the format HH:mm:ss.SSS. The time zone is optional and defaults to UTC if not specified. If the time zone is specified, it must be in the format ±HH:mm or Z for UTC. The order of items in the array is not fixed.
  "example-set-of-time-field": {
    "type": "TimeSet",
    "value": ["14:00:00.000", "15:00:00.000"]
  }

DateTimeSetField

A field with a date time set value.

type​
String​
"DateTimeSet"

The type of this field.

value​
Array of DateTime​
JSON array of date time values in the format YYYY-MM-DDTHH:mm:ss.SSSZ without duplicates. The time zone is optional and defaults to UTC if not specified. If the time zone is specified, it must be in the format ±HH:mm or Z for UTC. The order of items in the array is not fixed.
  "example-set-of-datetime-field": {
    "type": "DateTimeSet",
    "value": ["2018-10-14T14:00:00.000Z", "2018-10-14T15:00:00.000Z"]
  }

ReferenceSetField

A field with a reference set value.

type​
String​
"ReferenceSet"

The type of this field.

value​
Array of KeyReference​

JSON array of references, each referencing an existing resource by key. The order of items in the array is not fixed.

  "example-set-of-reference-field": {
    "type": "ReferenceSet",
    "value": [
      {
        "typeId": "product",
        "key": "key-of-a-product"
      },
      {
        "typeId": "product",
        "key": "key-of-a-product"
      }
    ]
  }

References

KeyReference

References a resource by key.

key​
String​
User-defined unique identifier of the referenced resource. If the referenced resource does not exist, the state of the ImportOperation will be set to unresolved until the referenced resource is created.
MinLength: 2​MaxLength: 256​Pattern: ^[A-Za-z0-9_-]+$​
typeId​

Type of referenced resource.

ReferenceType

Type of referenced resource.

associate-role

References an associate role.

business-unit

References a business unit.

cart

References a cart.

cart-discount

References a cart discount.

category

References a category.

channel

References a channel.

customer

References a customer.

customer-group

References a customer group.

discount-code

References a discount code.

key-value-document

References a custom object

order

References an order.

payment

References a payment

price

References a price.

product

References a product.

product-discount

References a product discount.

product-type

References a product type.

product-variant

References a product variant.

variant

References a variant.

shipping-method

References a shipping method.

state

References a state.

store

References a store.

tax-category

References a tax-category.

type

References a type.