Bulk product upload (BPU)

Understand how to use BPU.

Bulk Product Upload (BPU)

Use the Bulk Product Upload (BPU) process to add, update, or remove multiple products or product combinations. The BPU process creates categories based on the provided category path. The BPU process is an inbound event.

The BPU uses the Bulk Import to add, update, or remove products.

Bulk import XML file

The following example shows the smallest possible Bulk Import XML file:

<?xml version="1.0" encoding="utf-8"?>
<loader xmlns="urn:com.digitalriver.bulkloader">
    <loaderType>incremental</loaderType>
    <ownerCompanyID>myCompanyID</ownerCompanyID>
    <catalogID>858100</catalogID>
    <noOverwriteIfEmpty>true</noOverwriteIfEmpty>
    <items>
        <product>
            <productID>42716000</productID>
            <action>UPDATE</action>
            <companyID>myCompanyID</companyID>
        </product>
    </items>
</loader>

Bulk import XML file with category import

The following example shows a Bulk Import XML file with Category Import:

<?xml version="1.0" encoding="utf-8"?>
<loader xmlns="urn:com.digitalriver.bulkloader">
    <loaderType>incremental</loaderType>
    <ownerCompanyID>myCompanyID</ownerCompanyID>
    <catalogID>858100</catalogID>
    <noOverwriteIfEmpty>true</noOverwriteIfEmpty>
    <items>
      <productCategory>
          <categoryPath>
            <categoryName>Accessories1</categoryName>
            <categoryName>Cameras1</categoryName>
          </categoryPath>
          <categoryData>
            <locale>en_GB</locale>
            <categoryDisplayName>Cameras1</categoryDisplayName>
            <categoryImageURI></categoryImageURI>
            <isViewable>true</isViewable>
            <shortDescription></shortDescription>
            <longDescription>Camera Type</longDescription>
            <attributes/>
          </categoryData>
    </productCategory>
        <product>
            <productID>42716000</productID>
            <action>UPDATE</action>
            <companyID>myCompanyID</companyID>
        </product>
    </items>
</loader>

Note: BPU is non-interactive. When the BPU process finishes, there is no required notification response. When the BPU process finishes, the presence of a BulkImportResponse file indicates the bulk file upload has finished.

When using Bulk Import to import categories, consider the following tips:

  • Ensure all categories are listed in the file before products. Follow the sequence in the schema.

  • A category path cannot be empty.

  • Define the loaderType to Add or Update the category, if the noOverwriteIfEmptyData flag is not set.

  • If you run an incremental upload and the category action is REMOVE, then categories with subcategories or products in a predeployed state will not be deleted.

  • If you run a full catalog upload, all categories that are not in the import file will be removed.

Bulk import response XML file

The BPU Import process creates the Bulk Import Response file after the Bulk Import process completes. The Bulk Import Response file reports when the BPU Import process successfully adds, updates, or retires a product. If an error occurs during the import, The BPU Import process adds the error and stackTrace elements to provide more information.

<?xml version="1.0" encoding="utf-8"?>
<loader xmlns="urn:com.digitalriver.bulkloader">
    <loaderType>incremental</loaderType>
    <ownerCompanyID>myCompanyID</ownerCompanyID>
    <catalogID>858100</catalogID>
    <noOverwriteIfEmpty>true</noOverwriteIfEmpty>
    <items>
      <productCategory>
          <categoryPath>
            <categoryName>Accessories1</categoryName>
            <categoryName>Cameras1</categoryName>
          </categoryPath>
          <categoryData>
            <locale>en_GB</locale>
            <categoryDisplayName>Cameras1</categoryDisplayName>
            <categoryImageURI></categoryImageURI>
            <isViewable>true</isViewable>
            <shortDescription></shortDescription>
            <longDescription>Camera Type</longDescription>
            <attributes/>
          </categoryData>
    </productCategory>
        <product>
            <productID>42716000</productID>
            <action>UPDATE</action>
            <companyID>myCompanyID</companyID>
        </product>
    </items>
</loader>

Terminology

externalReferenceId

The BPU process uses externalReferenceId to identify products. It frees clients from the need to consume and store Digital River product IDs. When using this field to identify products, ensure the externalReferenceId is unique across the product-owning company.

locale in prices

The locale in the price node is not tied to the locale of the enclosing product node. To use locale-specific prices, specify the locale at the price level.

noOverwriteIfEmpty

This value should be set to true. Setting this value to false can result in undesired side effects.

productConfigType

While appearing in the schema, this complex type is not consumed by the BPU process. It does not affect the BPU process when you include it in the XML.

retiring products

The “remove” action for products works slightly differently for products with multiple locales than those with a single locale. For products with multiple locales, “remove” deletes that locale from the product. If only a single locale exists, the “remove” action will retire the product.

Schemas

VersionSchema Components TableRaw SchemaSample XML

7 (Current)

Not available

6

5

Product association feed

Use the Product Association Feed to add, modify, or remove product associations. Product Associations allow users to associate one product with one or more other products. The Product Associations framework is generic.

The Product Association Feed is a webhook event.

Details

The Product Association Feed Integration is the automated mechanism through which Digital River adds, modifies, and deletes product associations in an Association Group.

The following list describes when you cannot create an association.

  • The owning product is not deployed. You can only create associations (via the feed) when the owning product is deployed.

  • The associated product is not deployed. You can only create an association group when the product you want to associate with the owning product is deployed.

  • The locale of the owning product in the feed is not a valid locale for that product.

Note: If you create an association group that includes deployed products in the association, the created association group will not include the undeployed products. The locale for the owning product in the feed is not a valid locale for that product.

The following table describes the request and response types for exporting and importing product association details.

TaskRequest TypeResponse Type

View the existing product association details by exporting the product association details

ProductAssociationFeedExportRequest

ProductAssociationFeedExportResponse

View the existing product association details by exporting the product association details

ProductAssociationFeedImportRequest

ProductAssociationFeedImportResponse

A Product Association Type defines the behavior of a specific type of product association. The behavior defined by the type includes but may not be limited to the following:

  • Enforcement of cardinality between parent and child products.

Example: one-to-one (1:1) or one-to-many (1:M)

  • State-dependent behavior, including whether you can:

    • Display the association on a shopper site

    • Add the products to the association

    • Modify the association name

  • State transition rules

Each Product Association Type is associated with a collection of one or more Categories specific to that type. The Categories are company-specific, and you must create them before you create specific Product Associations.

Example: Categories you could create for a Related Items Type include "Related Trial Ware" and "Related Products".

Each Category appears as a separate panel or container in an administrator interface. Associations of that Type and Category will be managed entirely within that panel.

Also, the Product Association Type and Category combine to allow site designers to display certain association Groups at certain locations on the shopper site.

A Product Association Group defines a relationship between a single Parent Product and a collection of Child Products. The Group links the Parent Product with the Child Products. Also, the Group inherits behavior defined by the Product Association Type and, to a lesser extent, by the Category within that type. Groups can be sorted within a Category.

You can give the Product Association Group a localized Group Name. When you create a localized Group Name, you must:

  • Associate each Group Name with a specific Locale.

  • Define one Group Name as the default.

You can add additional Group Names for other locales. A Client may ask for the name of a Group by Locale. If a localized name matches the Locale in the request, that name is provided; otherwise, the default name is provided. Group Name may be optional for some Product Association Types.

The Parent Product is the Key Product in an Association Group. It drives the maintenance and display of Product Associations. You cannot remove a Parent Product from a Group.

A Group contains a collection of Associated Products in relative sort order. You can add or remove Associated Products from a Group if its state allows it.

The Product Association Tag is a display API that provides Product Association Group information that you can use in shopper-side views.

You can send a productAssociationFeedImportRequest and expect a productAssociationFeedImportResponse in real-time.

You can send a productAssociationFeedImportRequest and expect a productAssociationFeedImportResponse at a later point.

The following example shows the request and response for adding an Associated Product and Associations.

<ProductAssociationFeedImportRequest 
xmlns="http://integration.digitalriver.com/ProductAssociationFeed">
  <companyID>mycompany</companyID>
  <reportingLevel>all</reportingLevel>
  <lenientCommit>true</lenientCommit>
  <productAssociation>
    <action>add</action>
    <associationInfo>
      <categoryName>Related Products</categoryName>
      <parentProduct>
        <externalReferenceID>111111</externalReferenceID>
        <companyID>mycompany</companyID>
        <locale>en_US</locale>
      </parentProduct>
    </associationInfo>
    <groupData>
      <groupDataInfo>
        <groupName>Inkjet Ink/Print Cartridge</groupName>
        <locale>en_US</locale>
        <isDefault>1</isDefault>
      </groupDataInfo>
    </groupData>
    <associatedProduct>
      <action>add</action>
      <associatedProductInfo>
        <productKey>
          <externalReferenceID>222222</externalReferenceID>
          <companyID>mycompany</companyID>
          <locale>en_US</locale>
        </productKey>
        <sortOrder>1</sortOrder>
      </associatedProductInfo>
    </associatedProduct>
    <associatedProduct>
      <action>add</action>
      <associatedProductInfo>
        <productKey>
          <externalReferenceID>333333</externalReferenceID>
          <companyID>mycompany</companyID>
          <locale>en_US</locale>
        </productKey>
        <sortOrder>2</sortOrder>
      </associatedProductInfo>
    </associatedProduct>
  </productAssociation>
</ProductAssociationFeedImportRequest>

The following example shows the request and response for modifying an Associated Product and Associations.

<?xml version="1.0" encoding="utf-8"?>
<ProductAssociationFeedImportRequest 
xmlns="http://integration.digitalriver.com/ProductAssociationFeed">
  <companyID>mycompany</companyID>
  <reportingLevel>all</reportingLevel>
  <lenientCommit>true</lenientCommit>
  <productAssociation>
    <action>update</action>
    <associationInfo>
      <associationID>12345</associationID>
      <categoryName>Related Products</categoryName>
      <parentProduct>
        <externalReferenceID>111111</externalReferenceID>
        <companyID>mycompany</companyID>
        <locale>en_US</locale>
      </parentProduct>
    </associationInfo>
	<groupData>
      <groupDataInfo>
        <groupName>Inkjet Ink/Print Cartridge</groupName>
        <locale>en_US</locale>
        <isDefault>1</isDefault>
      </groupDataInfo>
    </groupData>
	<associatedProduct>
      <action>update</action>
      <associatedProductInfo>
        <productKey>
          <externalReferenceID>222222</externalReferenceID>
          <companyID>mycompany</companyID>
          <locale>en_US</locale>
        </productKey>
        <sortOrder>1</sortOrder>
      </associatedProductInfo>
    </associatedProduct>
    <associatedProduct>
      <action>update</action>
      <associatedProductInfo>
        <productKey>
          <externalReferenceID>333333</externalReferenceID>
          <companyID>mycompany</companyID>
          <locale>en_US</locale>
        </productKey>
        <sortOrder>2</sortOrder>
      </associatedProductInfo>
    </associatedProduct>
  </productAssociation>
</ProductAssociationFeedImportRequest>

The following example shows the request and response for deleting an Associated Product and Associations.

<?xml version="1.0" encoding="utf-8"?>
<ProductAssociationFeedImportRequest 
xmlns="http://integration.digitalriver.com/ProductAssociationFeed">
	<companyID>mycompany</companyID>
	<reportingLevel>all</reportingLevel>
	<lenientCommit>true</lenientCommit>
	<productAssociation>
		<action>delete</action>
		<associationInfo>
			<associationID>12345</associationID>
			<categoryName>Related Products</categoryName>
			<parentProduct>
				<externalReferenceID>111111</externalReferenceID>
				<companyID>mycompany</companyID>
				<locale>en_US</locale>
			</parentProduct>
		</associationInfo>
		<groupData>
      <groupDataInfo>
        <groupName>Inkjet Ink/Print Cartridge</groupName>
        <locale>en_US</locale>
        <isDefault>1</isDefault>
      </groupDataInfo>
    </groupData>
	<associatedProduct>
      <action>update</action>
      <associatedProductInfo>
        <productKey>
          <externalReferenceID>222222</externalReferenceID>
          <companyID>mycompany</companyID>
          <locale>en_US</locale>
        </productKey>
        <sortOrder>1</sortOrder>
      </associatedProductInfo>
    </associatedProduct>
	</productAssociation>
</ProductAssociationFeedImportRequest>

The Action Result denotes whether or no the action succeeded. The possible results are as follows:

  • SUCCESSFUL

  • FAILED

If the request failed, the following table describes the possible response codes associated with the failure:

Response CodeError NameMessage

100

ERR_INVALID_ACTION

Unrecognized action. The association group was not created.

110

ERR_NO_GROUP_FOUND

The product does not contain an association.

120

ERR_INVALID_CATEGORY

The company has no category, and Product Association was not created (updated or deleted).

130

ERR_ASSOCIATION_PARTIAL

Association was created, but errors occurred.

140

ERR_NOT_CREATED

Errors occurred, the association was not created.

200

ERR_GROUPDATA_ADD

Error in adding groupData.

210

ERR_NO_GROUPDATA_FOUND

The association does not contain locale.

220

ERR_GROUP_NOT_EDITABLE

Association cannot be modified: Group is not tied to the latest parent version.

230

ERR_NO_MODIFICATION

Errors occurred, the association was not modified.

300

ERR_CHILD_ADD

Could not add the associated product: product could not be found.

310

ERR_NO_CHILD_FOUND

Association does not contain a child product.

320

ERR_INVALID_CHILD

The child product can not be found. The child was not removed/updated.

400

ERR_INVALID_PARENT

Parent product can not be found. Product Association was not added/modified/deleted.

Schemas

VersionSchema Components TableRaw SchemaSample XML

1 (Current)

Channel bulk loader

Use the Channel Bulk Loader to import company information, payment details, channel contract agreement details, and other product information.

  • The Channel Bulk Loader process imports products, companies, contracts, payment disbursement, pricing, and other objects necessary to sell products in the marketStream business model of Digital River.

  • You can use the Channel Bulk Loader to add, update, or remove companies, products, and payment disbursement.

The Channel Bulk Loader is an inbound event.

Company examples

<?xml version="1.0" encoding="windows-1252"?>
<loader xmlns = "ns:test">
    <catalogName>Test Channel Catalog</catalogName>
    <loaderType>testLoader</loaderType>
    <ownerCompanyID>0</ownerCompanyID>
    <sourceID>Test</sourceID>
    <items>
        <company>
            <companyID>1234</companyID>
            <name><![CDATA[Test Software]]></name>
            <duns/>
            <contactName><![CDATA[Test Contact]]></contactName>
            <contactEmail><![CDATA[mail@test.com]]></contactEmail>
            <url><![CDATA[www.testcompany.com]]></url>
            <telephone>123-1234</telephone>
            <fax/>
            <taxID/>
            <companyShortName>testsoft</companyShortName>
        </company>
    </items>
</loader>

Payment disbursement examples

<?xml version="1.0" encoding="windows-1252"?>
<loader xmlns ="ns:test">
    <catalogName>Test Channel Catalog</catalogName>
    <loaderType>testLoader</loaderType>
    <ownerCompanyID>0</ownerCompanyID>
    <sourceID>testSource</sourceID>
    <items>
        <paymentDisbursement>
            <companyID>1234</companyID>
            <companyName><![CDATA[Test Software]]></companyName>
            <payToVendorID>123123</payToVendorID>
            <minimumAmountToPay><![CDATA[0]]></minimumAmountToPay>
            <minimumAmountToPayCurrency><![CDATA[USD]]></minimumAmountToPayCurrency>
            <paymentType><![CDATA[CHECK]]></paymentType>
            <paymentCycle><![CDATA[0]]></paymentCycle>
            <name1><![CDATA[Test1 ]]></name1>
            <name2><![CDATA[Test2]]></name2>
            <payToName><![CDATA[Test Software]]></payToName>
            <paymentAddressLine1><![CDATA[EP]]></paymentAddressLine1>
            <paymentAddressLine2><![CDATA[11]]></paymentAddressLine2>
            <paymentAddressCity><![CDATA[Eden Prairie]]></paymentAddressCity>
            <paymentAddressState><![CDATA[MN]]></paymentAddressState>
            <paymentAddressZipCode><![CDATA[45567]]></paymentAddressZipCode>
            <paymentAddressCountry><![CDATA[US]]></paymentAddressCountry>
            <bankName/>
            <bankAddressLine1/>
            <bankAddressLine2/>
            <bankAddressCity/>
            <bankAddressState/>
            <bankAddressZipCode/>
            <bankAddressCountry/>
            <bankAccountNumber/>
            <swiftCode/>
            <beneficiaryName/>
            <beneficiaryAddressLine1/>
            <beneficiaryAddressLine2/>
            <beneficiaryAddressCity/>
            <beneficiaryAddressState/>
            <beneficiaryAddressZipCode/>
            <beneficiaryAddressCountry/>
            <intermediaryAddressLine1/>
            <intermediaryAddressLine2/>
            <intermediaryAddressLine3/>
            <specialInstructions/>
        </paymentDisbursement>
    </items>
</loader>

Add product example

<?xml version="1.0" encoding="utf-8"?>
<loader xmlns:xsi = "http://www.w3.org/2001/XMLSchema-instance" 
xmlns:bulk = "ns1:testBulkloader">
    <loaderType>testLoader</loaderType>
    <noOverwriteIfEmpty>true</noOverwriteIfEmpty>
    <noOverwriteExistingCategoryData>true</noOverwriteExistingCategoryData>
    <items>
        <product>
            <action>ADD</action>
            <externalReferenceID>123123</externalReferenceID>
            <locale>en_US</locale>
            <currencyCode>USD</currencyCode>
            <companyID>test</companyID>
            <catalogID>123123</catalogID>
            <productName>Test Product</productName>
            <displayName>Test Product</displayName>
            <shortDescription>Short Description</shortDescription>
            <longDescription><![CDATA[Long Description]]></longDescription>
            <thumbnailImageURI>http://images.com/1</thumbnailImageURI>
            <detailImageURI>http://images.com/2</detailImageURI>
            <manufacturer>Test</manufacturer>
            <mfrPartNumber>123123/12</mfrPartNumber>
            <sku>12312</sku>
            <upc>021212121</upc>
            <type></type>
            <keywords>123,123123,12312</keywords>
            <weight>1.00</weight>
            <weightUnits>lb</weightUnits>
            <taxableProductCode>989</taxableProductCode>
            <commodityCode>89910</commodityCode>
            <taxableUnspscCode>4000</taxableUnspscCode>
            <categories>
                <category>
                    <categoryPath>
                        <categoryName>ACC</categoryName>
                        <categoryName>ACC_TEST</categoryName>
                    </categoryPath>
                </category>
            </categories>
            <prices>
                <price>
                    <currencyCode>USD</currencyCode>
                    <type>LIST_PRICE</type>
                    <amount>12.99</amount>
                </price>
                <price>
                    <currencyCode>USD</currencyCode>
                    <type>MSRP_PRICE</type>
                    <amount>29.99</amount>
                </price>
            </prices>
            <attributes>
                <attribute>
                    <name>testDivision</name>
                    <value>testValue</value>
                    <familyName>testFamilyl</familyName>
                </attribute>
            </attributes>
            <more>
                <productFulfillment>
                    <fulfillerID>testComp</fulfillerID>
                    <fulfillerPartNumber>123123</fulfillerPartNumber>
                    <warehouseLocationID>4000</warehouseLocationID>
                </productFulfillment>
            </more>
            <isViewable>true</isViewable>
            <isOrderable>true</isOrderable>
            <limitedToSupportingLocales>true</limitedToSupportingLocales>
        </product>
    </items>
</loader>