Your data

Customers and order history

Who your customers are and what they bought: the assistant's «usual».

What it does in the conversation

From the order history the assistant knows each customer's «usual»: the products they buy, in the quantity of the last purchase. When the customer writes «milk», it adds the one they always buy and says so, instead of asking them to choose; «the usual» reorders in one go; a customer who has ordered before is not treated as new (welcome and comeback discounts depend on it).

Orders confirmed in the chat enter the same history by themselves. The history you load is matched to the customer only where the identity is guaranteed: on WhatsApp (the channel verifies the number), and on the chat of your site only for customers logged in to your site, through a token your server asks for (POST /v1/chat_identity_tokens). On an anonymous chat, a phone number typed by the customer opens no history: otherwise anyone could read someone else's purchases by typing their number.

The customer master data (code, name, phone, email, address) links the history to your customers and lets your server open the chat in their name.

Example

Customer: Add my usual pasta

Assistant: I added your usual: • Pasta Spaghetti n.5 500g [Barilla] 2x500g – €2.58 Anything else?

Two packs, as in the customer's last order in the history. Illustrative example, with the products of the template and an invented store.

If it is missing

  • Without the history, the assistant does not know your customers' usual items and always offers a choice.
  • A customer who has bought from you for years is treated as new: welcome discount instead of comeback discount.
  • Without the customer code, your server cannot open the chat of your site in the customer's name.
  • Cancelled orders do not become habits: mark them «cancelled».

The fields

Required: without it the product is not sold the way the customer expects. Recommended: without it there is a declared fallback, but the experience is poorer. Optional: an improvement.

  • order_refrequired
    Column in the file
    Order code
    Type
    text
    Example
    ORD-1001 · ORD-1002
    Rule
    required, max 128 characters; the lines of one order share the code
  • customer_refrecommended
    Column in the file
    Customer code
    Type
    text
    Example
    CLI-0042
    Rule
    the customer code in your system (the one in the customers file); this or the phone is needed
  • phonerecommended
    Column in the file
    Phone
    Type
    text
    Example
    +39 000 000 0001 · +39 000 000 0002
    Rule
    international, with the country code (+44…); this or the customer code is needed
  • order_daterequired
    Column in the file
    Order date
    Type
    date
    Example
    2026-10-01 · 15/10/2026
    Rule
    YYYY-MM-DD or DD/MM/YYYY; the last 12 months are recommended
  • skurequired
    Column in the file
    SKU
    Type
    text
    Example
    000201111 · 000301555
    Rule
    the item code, the same as in the catalog; a code no longer in the catalog counts for habits, not for the cart
  • titlerecommended
    Column in the file
    Product name
    Type
    text
    Example
    Pasta Spaghetti n.5 500g · Acqua naturale 6x1,5l
    Rule
    max 512 characters
  • quantityrequired
    Column in the file
    Quantity
    Type
    number
    Example
    2 · 1 · 3
    Rule
    greater than zero, in the sales unit (packs, cases; kg if by weight)
  • unit_priceoptional
    Column in the file
    Unit price
    Type
    number (¤)
    Example
    1.29 · 3.30
    Rule
    VAT included, not negative
  • statusoptional
    Column in the file
    Status
    Type
    text
    Example
    delivered · cancelled
    Rule
    delivered or cancelled; a cancelled order does not become a habit
  • store_codeoptional
    Column in the file
    Store code
    Type
    text
    Rule
    only with several stores, max 64 characters
  • delivery_dateoptional
    Column in the file
    Delivery date
    Type
    date
    Example
    2026-10-02
    Rule
    YYYY-MM-DD or DD/MM/YYYY, once per order
  • delivery_slotoptional
    Column in the file
    Delivery slot
    Type
    text
    Example
    09-13
    Rule
    max 64 characters, once per order
  • order_totaloptional
    Column in the file
    Order total
    Type
    number (¤)
    Example
    12.48 · 3.87
    Rule
    VAT included, once per order
  • payment_methodoptional
    Column in the file
    Payment method
    Type
    text
    Example
    carta · contanti
    Rule
    max 64 characters, once per order

Customer master data (PUT /v1/customers)

  • external_refrequired
    Type
    text
    Example
    CLI-0042
    Rule
    The customer code in your system: the same «customer code» of the history.
  • display_namerecommended
    Type
    text
    Example
    Anna Esempio
    Rule
    Name and surname.
  • phonerecommended
    Type
    E.164
    Example
    +39 000 000 0001
    Rule
    International, with the country prefix.
  • emailoptional
    Type
    email
    Example
    anna@esempio.it
    Rule
    —
  • addressoptional
    Type
    object
    Example
    {"street":"Via Prova 1","city":"Borgo Prova"}
    Rule
    Street, number, city, postal code.

Download the template

The first row is the header; the second row (starting with #) describes each column; the three example rows also start with # and are not imported. Column names are recognised in all six languages and by their field name.

Frequent errors and their message

  • TELEFONO_NON_E164

    «The phone number needs the international prefix (+39…).»(explanation of this guide: Core returns the code)

    What to do: Write it as +, country code and number.

  • ORDINE_SENZA_CLIENTE

    «The row has neither the customer code nor the phone.»(explanation of this guide: Core returns the code)

    What to do: Every row needs one of the two.

  • QUANTITA_NON_VALIDA

    «The quantity must be greater than zero.»(explanation of this guide: Core returns the code)

    What to do: In the sales unit: packs, cases, or kilos for products sold by weight.

  • DATA_NON_VALIDA

    «The date cannot be read.»(explanation of this guide: Core returns the code)

    What to do: Write YYYY-MM-DD or DD/MM/YYYY.

How to send it

  • From the portalComing

    Coming: the order history file (CSV or Excel) from the portal.

  • From the APIIn part

    Today: PUT /v1/customers (customers:write) for the master data, and POST /v1/chat_identity_tokens (chat:write) for logged-in customers. PUT /v1/order_history exists, but the key permission history:write cannot be created from the portal yet.

Availability as measured on the live service on 30 October 2026.

Send two customers

curl

curl -X PUT "https://oxjqgjbiltoviwldailg.supabase.co/functions/v1/core-api/v1/customers" \
  -H "Authorization: Bearer $GAI_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: clienti-2026-11-02" \
  -d '{"customers":[{"external_ref":"CLI-0042","display_name":"Anna Esempio","phone":"+390000000001"},{"external_ref":"CLI-0043","display_name":"Luca Esempio","phone":"+390000000002"}]}'

Node.js (18+)

const risposta = await fetch("https://oxjqgjbiltoviwldailg.supabase.co/functions/v1/core-api/v1/customers", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${process.env.GAI_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    customers: [
      { external_ref: "CLI-0042", display_name: "Anna Esempio", phone: "+390000000001" },
      { external_ref: "CLI-0043", display_name: "Luca Esempio", phone: "+390000000002" },
    ],
  }),
});
console.log(risposta.status, await risposta.json());

API documentation