How are "Additional Addresses" given with createOrder API different from those in the Additional Addresses tab in the DOM Configurator?

Answer

CUSTOMER ADDITIONAL ADDRESSES

In the DOM Configurator, when you view the details of a Customer of type Consumer, there is already an address defined. But there is a tab called "Additional Addresses" where you can define other addresses for that Customer.

When Additional addresses are defined using the Configurator, you must identify whether the address is a Bill To, Ship To or Sold To address. All or none can be selected.

One Customer can have zero or many Additional Addresses

These addresses are stored in the YFS_PERSON_INFO table, and linked to the YFS_CUSTOMER table by a record in the YFS_CUSTOMER_ADDNL_ADDRESS table using the CUSTOMER_KEY and PERSON_INFO_KEY fields.

CUSTOMER CONTACT ADDITIONAL ADDRESSES

In the Customer Setup screen of the Configurator, there is also a tab for "Contacts". If you open up a contact to edit the details, you will find another "Additional Addresses" tab.

This type of Additional Address is similar to the Customer Additional Address described above. It also requires you to identify whether or not it is a Bill To, Ship To, Sold To, etc.

In the same manner as above, these addresses are also stored in the YFS_PERSON_INFO table, and linked to the YFS_CUSTOMER table by a record in the YFS_CUSTOMER_ADDNL_ADDRESS table using the CUSTOMER_KEY and PERSON_INFO_KEY fields.
The only difference is that these addresses will also be linked to the YFS_CUSTOMER_CONTACT table by the CUSTOMER_CONTACT_KEY field of the YFS_CUSTOMER_ADDNL_ADDRESS record.

ORDER ADDITIONAL ADDRESSES

In the Input XML of the createOrder API, you can also provide "Additional Addresses" for the order you are creating.

"AdditionalAddresses" is a container tag for one or more AdditionalAddress tags.

"AdditionalAddress" is a container tag for PersonInfo, with one element, AddressType.

This is a free-form text field that can take any value. This means the address you create here does not qualify or need to be a Bill To, Ship To, Sold To, etc. type of address. You can give your own custom address type.

A record for this address will be inserted into YFS_PERSON_INFO if one doesn't already exist having all of the same info. The YFS_PERSON_INFO record is connected to the YFS_ORDER_HEADER record by an intermediate table YFS_ENTITY_ADDRESS. The field ENTITY_KEY points to the YFS_ORDER_HEADER record and PERSON_INFO_KEY points to the YFS_PERSON_INFO record.

This info will subsequently be visible in the getOrderDetails output XML for this order.

There is currently no out-of-the-box functionality to use existing additional addresses when creating an order unless the full PersonInfo record is given in the createOrder inXML manually and it matches an existing PersonInfo record exactly.