Skip to main content
File PrefixSHOPPER-ADDRESS
Current VersionV3

​
Overview

The SHOPPER-ADDRESS_V3 import allows you to import, update, and manage shopper addresses. The import supports multiple addresses per shopper, setting default addresses, and soft-deleting addresses that are no longer active.

​
Key Features

  • Multiple addresses per shopper: Each shopper can have multiple addresses identified by unique address_ref values
  • Update existing addresses: Addresses with matching address_ref will be updated rather than duplicated
  • Soft delete: Use the active column to mark addresses as deleted without removing them from the database
  • Undelete: Setting active=TRUE on a previously deleted address will restore it
  • Default address: Mark one address as default per shopper using the is_default flag
  • Grouped by shopper: All rows are grouped by shopper_ref before processing

​
Column Specifications

AttributeFormatLengthRequiredDescriptionExample
shopper_refAlphanumeric1-255YesReference to the shopper. Must match an existing shopper’s external_id_strSHOPPER001
address_refAlphanumeric1-255YesUnique address reference (maps to external_id_str). Used to identify and update existing addressesHOME_ADDR
address_1Alphanumeric1-255YesPrimary address line123 Main Street
first_nameAlphanumeric1-255NoFirst name for this addressJohn
last_nameAlphanumeric1-255NoLast name for this addressDoe
company_nameAlphanumeric1-255NoCompany name for this addressAcme Corp
address_2Alphanumeric1-255NoAdditional address lineApt 4B
address_3Alphanumeric1-255NoAdditional address lineBuilding A
address_4Alphanumeric1-255NoAdditional address linePO Box #123
cityAlphanumeric1-255NoCity nameNew York
provinceAlphanumeric1-255NoProvince or state nameNew York
province_codeAlphanumeric1-255NoProvince or state codeNY
countryAlphanumeric1-255NoCountry nameUnited States
country_codeISO 3166. Must belong to supported countries2NoCountry codeUS
zipAlphanumeric1-255NoPostal/ZIP code10001
phoneE.1641-255NoPhone number for this address+12125551234
is_defaultBoolean [TRUE|FALSE]NoWhether this is the default address for the shopper. Only one address per shopper should be defaultTRUE
activeBoolean [TRUE|FALSE]NoWhether the address is active. FALSE means the address is soft-deletedTRUE

​
Import Behavior

​
Shopper Reference Validation

  • If a shopper_ref does not match an existing shopper, a warning is added to the row but the import continues
  • No addresses will be imported for non-existent shoppers

​
Address Creation and Updates

  • Addresses are matched by shopper_ref + address_ref combination
  • If an address with the same address_ref exists for the shopper, it will be updated
  • If no matching address exists, a new one will be created
  • This prevents duplicate addresses for the same address_ref

​
Soft Delete and Undelete

  • Setting active=FALSE marks the address as deleted (is_deleted=TRUE in database)
  • Setting active=TRUE on a previously deleted address restores it (is_deleted=FALSE)
  • If active is not provided, the address defaults to active

​
Default Address

  • Set is_default=TRUE to mark an address as the default for a shopper
  • Only one address per shopper should be marked as default
  • If is_default is not provided, it defaults to FALSE

​
Example CSV

shopper_ref,address_ref,first_name,last_name,company_name,address_1,address_2,address_3,address_4,city,province,province_code,country,country_code,zip,phone,is_default,active
SHOPPER001,HOME_ADDR,John,Doe,,123 Main Street,Apt 4B,Building A,,New York,New York,NY,United States,US,10001,+12125551234,true,true
SHOPPER001,WORK_ADDR,John,Doe,Acme Corp,456 Business Ave,Suite 200,,,New York,New York,NY,United States,US,10002,+12125555678,false,true
SHOPPER001,OLD_ADDR,John,Doe,,789 Old Street,,,,,,,United States,US,10003,,false,false
SHOPPER002,BILLING_ADDR,Jane,Smith,,10 Rue de la Paix,,,,Paris,Île-de-France,,France,FR,75002,+33123456789,true,true
This example demonstrates:
  • Multiple addresses for SHOPPER001 (HOME_ADDR, WORK_ADDR, OLD_ADDR)
  • A default address (HOME_ADDR with is_default=true)
  • A soft-deleted address (OLD_ADDR with active=false)
  • A work address with company name
  • An address for a different shopper (SHOPPER002)
Important: Once you import a SHOPPER-ADDRESS file, BSPK will no longer use the address fields from the SHOPPERS file. From that point on, the SHOPPER-ADDRESS file becomes the sole source of truth for managing shopper addresses.