How ShopMagic handles customers and guest users

How ShopMagic handles customers and guest users#

ShopMagic supports both registered WordPress users and customers who interact with your site without an account. It provides a shared Customer interface so automations can access customer information without requiring separate logic for each type.

This article explains how guest records are identified, how their data can change, and how customer data differs from information stored on an order.

Guest checkout and registered users in WooCommerce#

A guest order is not linked to a registered WordPress user account. WooCommerce stores its billing and shipping details with the order.

A registered customer has a WordPress user account, while each order also contains its own billing and shipping information. Account details and order details are separate sources of data and do not always contain the same values.

For automations, ShopMagic needs a way to identify guests across supported interactions without relying exclusively on individual order records.

How ShopMagic identifies guests#

ShopMagic stores its own guest records. A guest record is not a WordPress account: it does not create login credentials or give the visitor access to an account.

ShopMagic uses the email address to look up an existing guest record. When a supported integration captures guest data, it can reuse the matching record or create a new one.

For example, when processing a guest order, ShopMagic checks that:

• The order is not assigned to a registered user.
• The order has a billing email address.

It then looks for a guest with that email address and creates or updates the guest record.

Entering an email address into an arbitrary field does not automatically create a ShopMagic guest. The data must be captured through a supported ShopMagic integration or tracking mechanism.

How guest data is updated#

When ShopMagic processes another guest order with a matching email address, it can update the existing guest record with billing and shipping information from that order.

This means that a guest record represents shared customer information rather than a permanent snapshot of one order.

• Non-empty values captured from an order can replace previously stored guest metadata.
• Empty order fields are skipped when copying billing and shipping metadata, so an older value may remain in the guest record.
• Processing an order can update the guest record; do not assume that every stored field always comes from the chronologically newest order.

If you need information associated with a particular purchase, read it from that order rather than assuming that the current guest record contains the same values.

What happens when a guest registers an account?#

ShopMagic handles account registration separately from login.

When a new WordPress user is registered, ShopMagic looks for a guest record with the same email address. If it finds one, it:

1. Stores a reference to the previous guest ID in the new user’s metadata.
2. Triggers its guest-to-user merge hook.
3. Deletes the separate guest record.

This process links the previous guest identity to the registered user. It should not be interpreted as copying every guest field into the user’s WordPress profile.

Logging in to an existing account does not trigger this registration process. Guest and registered-user records with the same email address can therefore coexist.

What is a Customer in ShopMagic?#

\WPDesk\ShopMagic\Customer\Customer is a shared interface for accessing registered users and ShopMagic guests.

It provides methods such as:

• get_id()
• is_guest()
• get_email()
• get_first_name()
• get_last_name()
• get_full_name()
• get_phone()
• get_language()

A Customer is not an additional account with an independent copy of all customer data. Registered users are exposed through adapter objects, while ShopMagic guest records implement the same interface.

Available values depend on the underlying record and the event context. Some fields can be empty.

How customer IDs work#

WordPress users and ShopMagic guests have separate numeric ID sequences. ShopMagic distinguishes them by adding g_ to guest IDs.

Customer type	Example Customer ID
Registered WordPress user	123
ShopMagic guest	g_123

The Customer interface returns IDs as strings. Preserve the full value, including the guest prefix, when storing or passing Customer IDs.

Do not convert every Customer ID to an integer. Doing so would remove the distinction between user 123 and guest g_123.

Customer data and order data can differ#

Customer placeholders and order placeholders read different sources:

• {{ customer.email }} reads the email of the Customer supplied to the automation.
• {{ order.billing_email }} reads the billing email stored on the current order.

For a registered customer, the account email can differ from the billing email entered for an order. A shared guest record can also change independently of information stored on an older order.

When a registered customer is supplied in an order context, ShopMagic can use order values as fallbacks for certain empty account fields. This does not make the account and order records identical.

Choose placeholders according to the information you need:

• Use customer.* placeholders for the customer identity supplied by the event.
• Use the relevant order.* placeholders for information stored on a specific order.

Order placeholders require an event that provides order data.

Developer notes#

• Use the Customer interface for data shared by registered users and guests.
• Check is_guest() before using implementation-specific methods.
• When calling CustomerRepository::find(), pass the full prefixed ID for a guest, such as g_123. A numeric ID is treated as a registered-user ID.
• When looking up a Customer by email through CustomerRepository, a matching registered user takes precedence over a guest record.
• After guest-to-user conversion, CustomerRepository can resolve a previous guest ID to the registered user using the stored conversion reference.

Custom integrations can listen for the following action during guest-to-user conversion:

shopmagic/core/customer/merge_guest

The action receives the new WP_User object and the matching ShopMagic Guest object. It runs before the guest record is deleted.

For an example of accessing event resources in custom code, see Adding custom placeholders in the developer documentation.