Delivery contacts and customer pre-create
Lesson 17 of 24 9 min read
How Supply Lens matches, creates and addresses Unleashed delivery contacts, why some orders fail on purpose, and what it costs in API calls.
Unleashed added a delivery contact to the sales order: a named person, with an email and phone number, that carriers can use. It sounds simple, but Unleashed's rules around contacts and addresses have some sharp edges, and one of them once sent gift orders to the previous recipient. This lesson explains how Supply Lens handles delivery contacts so you can switch them on with confidence.
Why the customer is created first
A delivery contact belongs to a customer. Testing against a live Unleashed account showed three things:
- When Unleashed creates a customer from an order, it does not create a contact, and does not set a delivery contact on the order.
- An order cannot be corrected afterwards: sending it again is refused because the order already exists.
- So the contact must be right in the very first order, and the customer must exist before that.
That is why Supply Lens now creates the customer before the order. If that customer creation fails, Supply Lens logs a warning and carries on; Unleashed then creates the customer from the order as before, and only the delivery contact is lost.
The steps for each order
The settings
| setDeliveryContact | Off by default. When on, the order's ship-to contact (or the customer contact as a fallback) is matched against the customer's contacts in Unleashed, and the order references the match. With it off, no delivery contact is sent at all. |
|---|---|
| createDeliveryContactIfMissing | When on, a contact that matches none of the customer's contacts is added to the customer and used. Contacts created this way are marked for shipping, and only one is created per customer per run. |
| createDeliveryContactAddress | Off by default. When on, a contact with no default delivery address is given the order's address as one, added to the customer as a Shipping address if needed. A contact that already has a default is never changed. |
| deliveryContactUseDefaultDeliveryAddress | When on, asks Unleashed to use the matched contact's default address on the order, which fills Unleashed's Delivery Address field. Only asked for when that default is the order's own delivery address. |
How a contact matches
A contact matches only when every field matches: first name, last name, email address and telephone.
- Name and email ignore case. A blank matches only a blank, so an order with no email never takes a contact that has one.
- Phone formatting (spaces, dashes, brackets) is ignored, and the number may be held as phone, mobile or office. But
07700 900001and+44 7700 900001count as different numbers. - There is no looser fallback to name alone, because a shared customer (every Shopify order on one account, say) collects several people of the same name, and the carrier relies on the right phone number.
When nothing matches and creating is off, no delivery contact is sent. That is deliberate: Unleashed reads a contact with no identifier as an instruction to clear the contact already on the order.
Why some orders fail on purpose
Unleashed identifies a contact by first name, last name and email, and will not create a second contact with the same three. So if the customer already has a contact with the order's name and email but a different phone number (or one has a phone and the other does not), Supply Lens cannot use that contact without giving the carrier the wrong number, and cannot create a new one. The order fails with a message naming both contacts and both numbers.
To fix it: correct the phone number on the contact in Unleashed, or give the delivery contact an email address that tells the two apart, then reprocess.
Addresses, and the gift-order lesson
When createDeliveryContactAddress gives a contact an address, Supply Lens names the address after the order's delivery name, because Unleashed copies an address's name onto the delivery name of every order that uses it. If another address already has that name, the next free name is used: Alex Jones (2), Alex Jones (3) and so on. This is because Unleashed overwrites a Shipping address of the same name without warning.
A Postal address is never made a contact's default. Here is why. A business sending gifts found that each order went to the previous order's recipient. The buyer was the delivery contact on every order; their default had become the customer's Postal address; and the customer update after each order rewrote that Postal address with the latest recipient. Supply Lens now never uses a Postal address as a default, and only asks Unleashed to use the contact's default address when that default is the order's own address. In every other case, the order keeps the address built from the order itself.
What it costs in API calls
Unleashed limits how many calls can be made per minute. With delivery contacts, contact creation and status validation all on, a worst-case order for a brand-new customer goes from 3 calls to 5, or 7 with createDeliveryContactAddress. Contacts and statuses are remembered for the length of a run, so many orders for the same customer cost much less than orders for many different customers.
| A run of 10 orders | Before | After |
|---|---|---|
| One customer, already in Unleashed | 11 | 13 |
| One customer, new to Unleashed | 22 | 24 |
| Ten customers, all new | 30 | 51 |
Plan your rate limit against the worst case: five calls per order.
Hilltop's courier asks for phone numbers
Hilltop's courier now wants a contact phone number for every café delivery. Priya turns on setDeliveryContact and createDeliveryContactIfMissing for café orders, and createDeliveryContactAddress so each new contact has an address. On day two, one order fails: the café already has a contact Jo Smith with the same email but an old mobile number. Priya updates Jo's number in Unleashed and reprocesses the order.
Recap
- The customer is created before the order so the order can name a delivery contact from the start.
- A contact matches only on first name, last name, email and phone together.
- Orders fail on purpose when name and email match but the phone differs; fix the contact or the email.
- Postal addresses are never used as a contact's default, which prevents gift orders going to the previous recipient.
- Delivery contacts add API calls; plan for five per order in the worst case.
Quick guides for this topic
Your progress is saved in this browser. Create a free account to keep it everywhere, take quizzes and earn certificates.