> ## Documentation Index
> Fetch the complete documentation index at: https://developers.bspk.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Shoppers

<table>
  <tbody>
    <tr>
      <td>File Prefix</td>

      <td>
        <code>SHOPPER</code>
      </td>
    </tr>

    <tr>
      <td>Current Version</td>

      <td>
        <code>V3</code>
      </td>
    </tr>

    <tr>
      <td>Previous Version</td>

      <td>
        <code>V2 [Link to V2 Documentation page](/core-data-integration/file-types/shoppers_v2)</code>
      </td>
    </tr>
  </tbody>
</table>

<table>
  <tbody>
    <tr>
      <td><strong>Attribute</strong></td>
      <td><strong>Format</strong></td>
      <td><strong>Length</strong></td>
      <td><strong>Required</strong></td>
      <td><strong>Description</strong></td>
      <td><strong>Example</strong></td>
    </tr>

    <tr>
      <td><strong>shopper\_ref</strong></td>
      <td>Alphanumeric</td>
      <td>1-255</td>
      <td>Yes</td>
      <td>Unique shopper reference descriptor</td>
      <td>103495</td>
    </tr>

    <tr>
      <td><strong>barcode</strong></td>
      <td>Alphanumeric</td>
      <td>1-255</td>
      <td>No</td>
      <td>Shopper barcode used for scanning at the cashier/point-of-sale level</td>
      <td>SHR-199877-98</td>
    </tr>

    <tr>
      <td><strong>profile\_type</strong></td>
      <td>Alphanumeric</td>
      <td>1-255</td>
      <td>No</td>
      <td>Shopper profule type enum, valid typed: `person` or `organization`. When ommited, `person` is choosed by default.</td>
      <td>person</td>
    </tr>

    <tr>
      <td><strong>first\_name</strong></td>
      <td>Alphanumeric</td>
      <td>1-255</td>
      <td>No</td>
      <td>Shopper first name</td>
      <td>Marie</td>
    </tr>

    <tr>
      <td><strong>last\_name</strong></td>
      <td>Alphanumeric</td>
      <td>1-255</td>
      <td>No</td>
      <td>Shopper last name</td>
      <td>Curie</td>
    </tr>

    <tr>
      <td><strong>alternate\_first\_name</strong></td>
      <td>Alphanumeric</td>
      <td>1-255</td>
      <td>No</td>
      <td>Shopper other first name</td>
      <td>Maria Salomea</td>
    </tr>

    <tr>
      <td><strong>alternate\_last\_name</strong></td>
      <td>Alphanumeric</td>
      <td>1-255</td>
      <td>No</td>
      <td>Shopper other last name</td>
      <td>Sklodowska</td>
    </tr>

    <tr>
      <td><strong>gender</strong></td>
      <td>Alphanumeric</td>
      <td>1-255</td>
      <td>No</td>
      <td>Gender of the client, being: M = Male or F = Female or NB = Non-binary</td>
      <td>F</td>
    </tr>

    <tr>
      <td><strong>email</strong></td>
      <td>Alphanumeric</td>
      <td>1-255</td>
      <td>No</td>
      <td>Shopper email</td>
      <td>[marie\_curie@email.com](mailto:marie_curie@email.com)</td>
    </tr>

    <tr>
      <td><strong>title</strong></td>
      <td>Alphanumeric</td>
      <td>1-20</td>
      <td>No</td>
      <td>Shopper title</td>
      <td>Mr.</td>
    </tr>

    <tr>
      <td><strong>mobile\_phone</strong></td>
      <td>E.164</td>
      <td>1-255</td>
      <td>No</td>
      <td>Shopper mobile phone. Must be unique per shopper</td>
      <td>+14155551212</td>
    </tr>

    <tr>
      <td><strong>other\_phone</strong></td>
      <td>E.164</td>
      <td>1-255</td>
      <td>No</td>
      <td>Shopper other phone</td>
      <td>+14155551213</td>
    </tr>

    <tr>
      <td><strong>address</strong></td>
      <td>Alphanumeric</td>
      <td>1-255</td>
      <td>No</td>
      <td>Shopper address</td>
      <td>2nd Street</td>
    </tr>

    <tr>
      <td><strong>address\_2</strong></td>
      <td>Alphanumeric</td>
      <td>1-255</td>
      <td>No</td>
      <td>Shopper address follow up</td>
      <td>Appartment 3</td>
    </tr>

    <tr>
      <td><strong>address\_3</strong></td>
      <td>Alphanumeric</td>
      <td>1-255</td>
      <td>No</td>
      <td>Shopper address follow up</td>
      <td>Lotissement Vert</td>
    </tr>

    <tr>
      <td><strong>address\_4</strong></td>
      <td>Alphanumeric</td>
      <td>1-255</td>
      <td>No</td>
      <td>Shopper address follow up</td>
      <td>PO Box #123</td>
    </tr>

    <tr>
      <td><strong>city</strong></td>
      <td>Alphanumeric</td>
      <td>1-255</td>
      <td>No</td>
      <td>Shopper address city</td>
      <td>Paris</td>
    </tr>

    <tr>
      <td><strong>state</strong></td>
      <td>Alphanumeric</td>
      <td>1-255</td>
      <td>No</td>
      <td>Shopper address state</td>
      <td>Ile-de-France</td>
    </tr>

    <tr>
      <td><strong>zip\_code</strong></td>
      <td>Alphanumeric</td>
      <td>1-255</td>
      <td>No</td>
      <td>Shopper address zip code</td>
      <td>75002</td>
    </tr>

    <tr>
      <td><strong>country\_code</strong></td>
      <td>ISO 3166 Must belong to our [supported countries](/core-data-integration/supported-countries)</td>
      <td>2</td>
      <td>No</td>
      <td>Shopper address country code</td>
      <td>FR</td>
    </tr>

    <tr>
      <td><strong>preferences</strong></td>
      <td>Alphanumeric, key:value ; separated list</td>
      <td>1-500</td>
      <td>No</td>
      <td>Shopper preferred product categories. Must belong to the company "shopper preferences", as explained below</td>
      <td>profession:Young Professional,Lawyer</td>
    </tr>

    <tr>
      <td><strong>preferred\_contact\_channel</strong></td>
      <td>Alphanumeric</td>
      <td>1-255</td>
      <td>No</td>
      <td>Valid entries are chat, email, line, whatsapp, wechat, call</td>
      <td>whatsapp</td>
    </tr>

    <tr>
      <td><strong>nationality</strong></td>
      <td>ISO 3166 Must belong to our [supported countries](/core-data-integration/supported-countries)</td>
      <td>2</td>
      <td>No</td>
      <td>Shopper nationality</td>
      <td>GB</td>
    </tr>

    <tr>
      <td><strong>languages</strong></td>
      <td>ISO 639-1 Must belong to our [supported languages](/core-data-integration/supported-languages). Can be one language or a `;` separated list of languages</td>
      <td>2</td>
      <td>No</td>
      <td>Language(s) spoken by shopper</td>
      <td>fr</td>
    </tr>

    <tr>
      <td><strong>email\_contact</strong></td>
      <td>Boolean \[TRUE|FALSE]</td>

      <td />

      <td>No</td>
      <td>Define if shopper gave their agreement to be contacted by email</td>
      <td>TRUE</td>
    </tr>

    <tr>
      <td><strong>phone\_call\_contact</strong></td>
      <td>Boolean \[TRUE|FALSE]</td>

      <td />

      <td>No</td>
      <td>Define if shopper gave their agreement to be contacted by phone call</td>
      <td>FALSE</td>
    </tr>

    <tr>
      <td><strong>chat\_contact</strong></td>
      <td>Boolean \[TRUE|FALSE]</td>

      <td />

      <td>No</td>
      <td>Define if shopper gave their agreement to be contacted by chat</td>
      <td>TRUE</td>
    </tr>

    <tr>
      <td><strong>whatsapp\_contact</strong></td>
      <td>Boolean \[TRUE|FALSE]</td>

      <td />

      <td>No</td>
      <td>Define if shopper gave their agreement to be contacted by Whatsapp</td>
      <td>TRUE</td>
    </tr>

    <tr>
      <td><strong>line\_contact</strong></td>
      <td>Boolean \[TRUE|FALSE]</td>

      <td />

      <td>No</td>
      <td>Define if shopper gave their agreement to be contacted by Line</td>
      <td>TRUE</td>
    </tr>

    <tr>
      <td><strong>wechat\_contact</strong></td>
      <td>Boolean \[TRUE|FALSE]</td>

      <td />

      <td>No</td>
      <td>Define if shopper gave their agreement to be contacted by Wechat</td>
      <td>TRUE</td>
    </tr>

    <tr>
      <td><strong>do\_not\_contact</strong></td>
      <td>Boolean \[TRUE|FALSE]</td>

      <td />

      <td>No</td>
      <td>Define if shopper should not be contacted in anyhow. Once set it will take precedence over the `email_contact`, `phone_call` and `chat_contact`.</td>
      <td>FALSE</td>
    </tr>

    <tr>
      <td><strong>interested\_in\_new\_products</strong></td>
      <td>Boolean \[TRUE|FALSE]</td>

      <td />

      <td>No</td>
      <td>Define if shopper is interested in receiving messages about new products</td>
      <td>TRUE</td>
    </tr>

    <tr>
      <td><strong>creation\_date</strong></td>
      <td>Date ISO 8601</td>
      <td>10</td>
      <td>No</td>
      <td>Date when the shopper record was created</td>
      <td>2022-01-17</td>
    </tr>

    <tr>
      <td><strong>store\_ref</strong></td>
      <td>Alphanumeric</td>
      <td>1-255</td>
      <td>No</td>
      <td>Shopper record was created at this store</td>
      <td>STORE-1</td>
    </tr>

    <tr>
      <td><strong>sales\_associate\_ref</strong></td>
      <td>Alphanumeric</td>
      <td>1-255</td>
      <td>No</td>
      <td>Shopper's current associate</td>
      <td>SALES\_ASSOCIATE-1</td>
    </tr>

    <tr>
      <td><strong>segment</strong></td>
      <td>Alphanumeric</td>
      <td>1-255</td>
      <td>No</td>
      <td>Shopper's segment</td>
      <td>VIP</td>
    </tr>

    <tr>
      <td><strong>birthday</strong></td>
      <td>Date ISO 8601 (full or partial)</td>
      <td>10</td>
      <td>No</td>
      <td>Shopper's birthday full date (YYYY-MM-DD) or partial (MM-DD)</td>
      <td>1980-07-23</td>
    </tr>

    <tr>
      <td><strong>passport\_number</strong></td>
      <td>Alphanumeric</td>
      <td>1-255</td>
      <td>No</td>
      <td>Shopper's passport number</td>
      <td>WWO7288834</td>
    </tr>
  </tbody>
</table>

### Mobile Phone

Mobile phone will be cleaned and converted to E.164 format. Then we will check if it is a valid mobile phone, and apply the following:

* If it is a valid mobile phone, it is mapped to shopper `mobile_phone` attribute

* If it is not valid and if shopper `other_phone` is empty, it is mapped to shopper `other_phone` attribute

* If it is not valid and shopper `other_phone` is not empty, an error will be raised and shopper won't be imported

### Segment

Segment allows sales associates to assign a client to a CRM segment or to change the current segment of the client. Segment values are specified by the brand. They are imported into BSPK from the brand CRM. A single value can be selected at a time per client.

### Migrating from SHOPPER\_V2 to SHOPPER\_V3?

<Warning>
  In the SHOPPER\_V3, as mentioned earlier, the `segment` column has been repurposed.
  Therefore, the column previously known as `segment` in SHOPPER\_V2 is now referred to as `preferences` in SHOPPER\_V3, and it should be remapped accordingly.
</Warning>

### Preferences

The `preferences` column is used to populate shopper's preferred product categories. If a value corresponds to one of company shopper preferences value, it will be added to shopper preferred product categories. For example if company has the following shopper preferences:

* color: Green, Orange

* styles: Modern, Vintage

* dislike-color: Green, Orange, Blue

Then a shopper can be imported with the following preferences: `color:Green,Orange;Black;styles:Vintage;dislike-color:Blue`. And shopper preferred product categories will be:

* color: Green, Orange

* styles: Vintage

* dislike-color: Blue

(`Black` is ignored because it can't be mapped to any company shopper preferences)

### Shopper's Addresses

<Warning> **Important:** Once you start importing addresses using the **SHOPPER-ADDRESS** file, BSPK will **ignore any address fields in this file**. From that point on, the **SHOPPER-ADDRESS** file becomes the **source of truth** for shopper addresses. </Warning>