Bulk Import of Customer Accounts and Addresses

Oracle Commerce now supports bulk import of customer accounts, and addresses. This enhancement allows merchants to efficiently synchronize customer financial data from external systems into Oracle Commerce using JSON or CSV files.

Capability Highlights

  • Customer Accounts Import: Import customer accounts along with billing accounts and associated addresses.
  • Billing Accounts Import: Support for importing billing accounts and their secondary addresses.
  • Address Import Enhancements: Import and associate addresses with customer accounts and billing accounts.
  • Data Formats: Supports both JSON and CSV file formats in standalone or bundle modes.
  • Operation Support: Create, update (merge), or delete customer accounts and related records using the importOperationCode attribute.
  • Extensible Plugins: Leverages bulk import plugins (CustomerAccounts, Addresses) to manage financial data at scale.

The following is a list of bulk import IDs available for the import of Customer Accounts and Addresses:

ID Comment Supports Import Supports Export
CustomerAccounts This is a new plugin to import customer accounts data and associate them with the accounts Yes No
Addresses This is an existing plugin. Now enhanced to associates the addresses to the customer accounts and billing accounts Yes No

Customer Accounts:

This is a new plugin to import customer accounts, billing accounts, addresses and associate them with the accounts.

Customer accounts have the following properties:

Property Name Type Description Required
id string The ID of the customer account being imported No
partyId string The party id of the customer account Yes
partyName string The party name of the customer account No
defaultShippingAddress object The default shipping address details of the customer account No
secondaryAddresses list The list of secondary addresses associated with the customer account No
billingAccounts list The list of billing accounts associated with the customer account No
parentId list The list of billing accounts associated with the customer account No
parentId string ID of the OCC account. Ensure that this field contains valid organizationId value No. However, if the parentId property is not provided, an externalParentId is required.
externalParentId string The external ID of the parent customer account No. However, if the parentId property is not provided, an externalParentId is required.

importOperationCode

 string

The following values are supported:

merge (default): Creates a new record if no matching record is found, otherwise it updates the record

create: Creates the record. If a matching record is found, an error is generated. Can be used for performance gains for new

records

delete: Deletes the record		 No

Billing account has following properties in the data file:

Property Name Type Description Required
id string The ID of the billing account being imported No
accountId string The account id of the billing account Yes
accountNumber string The account number of the billing account No
accountName string The account name of the billing account No
defaultAddress object The default address details of the billing account No
secondaryAddresses list The list of secondary addresses associated with the billing account No

In addition to the existing address properties, the address has the following properties in the data file:

Property Name Type Description Required
id string The ID of the address being imported No
externalId string The external id of the address     Yes
Property Name Type Description Required
id  string The ID of the address being imported No
externalId

string

 The external id of the address Yes
externalNumber string The external number of the address No
siteId string The site id of the address. No
siteUseId string The site use id of the address. No
formattedAddress string The formatted address. No
setId string The set id of the address For billing account address, this property is required
isDefaultBillingAddress

boolean

 This flag is set to true if the address being imported is the default address of the billing account. This flag is valid for billing account address. No
isDefaultBillingAddressForCustomerAccount boolean This flag is set to true if the address being imported is the default billing address of the customer account. This flag is valid for billing account address. No
isDefaultShippingAddress boolean

This flag is set to true if the address being imported is the default shipping address of the customer account. This flag is valid for customer account address.

No

The following is an example of a customer account import record in CSV format. The example below includes one customer account with the following associations:

  • One customer account
  • Two secondary addresses associated with the customer account
  • Two billing accounts
  • Each billing account has two secondary addresses associated with it
importOperationCode,partyId,partyNumber,partyName,parentId,externalParentId,billingAccounts.row#,billingAccounts.accountId,billingAccounts.accountNumber,billingAccounts.accountName,billingAccounts.secondaryAddresses.row#,billingAccounts.secondaryAddresses.country,billingAccounts.secondaryAddresses.phoneNumber,billingAccounts.secondaryAddresses.address1,billingAccounts.secondaryAddresses.city,billingAccounts.secondaryAddresses.postalCode,billingAccounts.secondaryAddresses.companyName,billingAccounts.secondaryAddresses.state,billingAccounts.secondaryAddresses.formattedAddress,billingAccounts.secondaryAddresses.id,billingAccounts.secondaryAddresses.externalId,billingAccounts.secondaryAddresses.externalNumber,billingAccounts.secondaryAddresses.siteUseId,billingAccounts.secondaryAddresses.setId,billingAccounts.secondaryAddresses.isDefaultBillingAddress,billingAccounts.secondaryAddresses.isDefaultBillingAddressForCustomerAccount,secondaryAddresses.row#,secondaryAddresses.country,secondaryAddresses.phoneNumber,secondaryAddresses.address1,secondaryAddresses.city,secondaryAddresses.postalCode,secondaryAddresses.companyName,secondaryAddresses.state,secondaryAddresses.formattedAddress,secondaryAddresses.externalId,secondaryAddresses.externalNumber,secondaryAddresses.siteId,secondaryAddresses.siteUseId,secondaryAddresses.setId,secondaryAddresses.isDefaultShippingAddress

merge,19921,19921,Test Account,or-100005,or-100005,0,123,123,test billing account1,0,US,973-974-99991,82 Euclid Ave #544,Montgomery,36130,Oracle,AL,"82 Euclid Ave #544, Montgomery,36130, Alabama",ex7,124,124,siteUs,204,,,0,US,973-974-99992,70 Euclid Ave #722,Bohemia,11716,Oracle,NY,"70 Euclid Ave #722, 11716, New York",128,128,siteUs,siteUs,204,

,,,,,,,,,,1,US,973-974-99993,9780 Main St,Anchorage,99501,Oracle,AZ,"9780 Main St, Anchorage, 99501, Arizona",ex8,125,125,siteUs,204,,,1,US,973-974-99994,639 Main St,Anchorage,99501,Oracle,AZ,"639 Main St, Anchorage, 99501, Arizona",129,129,siteUs,siteUs,204,TRUE

,,,,,,1,456,456,test billing account2,0,US,973-974-99995,71 Dexter Avenue,Montgomery,36130,Oracle,AL,"71 Dexter Avenue, Montogmerym 36130, Alabama",ex9,126,126,siteUs,204,,,,,,,,,,,,,,,,,

,,,,,,,,,,1,US,973-974-99996,72 Dexter Avenue,Montgomery,36130,Oracle,AL,"72 Dexter Avenue, Montogmerym 36130, Alabama",ex10,127,127,siteUs,204,TRUE,TRUE,,,,,,,,,,,,,,,

The following is a sample import in json format

{

   "customerAccount":[

      {

         "id":"cu-21",

         "partyId":"199212",

         "partyNumber":"199212",

         "partyName":"test21",

         "parentId":"or-100003",

         "billingAccounts":[

            {

               "accountId":"19921233",

               "accountName":"Account Name",

               "secondaryAddresses":[

                  {

                     "country":"US",

                     "phoneNumber":"973-974-99999",

                     "address1":"Dexter111 Avenue",

                     "city":"Montgomery",

                     "postalCode":36130,

                     "companyName":"Oracle",

                     "state":"AL",

                     "externalId":"12121",

                     "siteId":"siteUs",

                     "isDefaultBillingAddress":true,

                     "isDefaultBillingAddressForCustomerAccount":true

                  }

               ]

            }

         ],

         "secondaryAddresses":[

            {

               "country":"US",

               "phoneNumber":"973-974-99999",

               "address1":"Dexter111 Avenue",

               "city":"Montgomery",

               "postalCode":36130,

               "companyName":"Oracle",

               "state":"AL",

               "externalId":"12121",

               "siteId":"siteUs",

               "isDefaultShippingAddress":null

            }

         ]

      }

   ]

}

Addresses
This is an existing plugin. It is enhanced to associate addresses to the customer accounts and billing accounts. In addition to the existing address properties, address has the following properties:

Property Name Type Description Required
parentType string

The type of the parent address.

This can be set to either contact or account or billingAccount or customerAccount, depending on which address is being linked

 Yes
parentId string The ID of the parent resource. Ensure that this field contains a valid profileId, organizationId, customerAccountId, or billingAccountId value, depending on the address type.
The customerAccountId and billingAccountId can be retrieved from the getCustomerAccoutnts API. customerAccountId is id field of the Customer and the billingAccountId is the id of the billing account		 Yes
externalId string The external id of the address For billing account and customer account address, this property is required
externalNumber string The external number of the address No
siteId string The site id of the address No
siteUseId string The site use id of the address No
formattedAddress list The formatted address No
setId list The set id of the address. For billing account address, this property is required

The following is an example of an address import record in CSV format. The example below includes two addresses:

  • One Customer Address
  • One Billing Address
id,parentType,parentId,externalId,externalNumber,address1,city,state,country,postalCode,phoneNumber,formattedAddress,siteId,siteUseId,setId,isDefaultShippingAddress,isDefaultBillingAddress

ci-cust-1,customerAccount,ca10009,130,130,456 Columbus Avenue,CHICAGO,IL,US,60601,1111119999,456 Columbus Avenue CHICAGO IL 60601-3475,siteUS,siteUS,204,TRUE,

ci-cust-2,billingAccount,ba10016,140,140,456 Columbus Avenue,CHICAGO,IL,US,60601,1111119999,456 Columbus Avenue CHICAGO IL 60601-3475,siteUS,siteUS,204,,TRUE

Please note that addresses can be imported using both the CustomerAccounts and the Addresses plugin.

The bulk import capability simplifies data onboarding, ensures data consistency, and improves overall system performance. It also reduces manual effort by automating large-scale data synchronization.

Steps to Enable

You don't need to do anything to enable this feature.

Tips And Considerations

  • For bulk imports, ensure all required fields (e.g., partyId, accountId, externalId) are correctly mapped in your file.
  • Use the merge operation (default) for incremental updates, create for performance when adding new records, and delete for removing outdated records.
  • Addresses must be linked to business units through Set IDs to ensure validity during order submission.
  • API-based retrieval is available for both administrators and buyers to confirm imported data.
  • This feature is only applicable for Commerce on CPQ customers.