Send authenticated customer information
To authenticate a customer profile, your backend server must make two independent API calls, which we recommend running in parallel for better performance:
-
createCart: Generates the Zonos cart. For detailed guidance, refer to the Set up Zonos Checkout section within the custom integration documentation. -
checkoutCustomerProfileAuthenticate: Submits and validates the customer's information.
mutation checkoutCustomerProfileAuthenticate($input: CheckoutCustomerProfileAuthenticateInput!) { checkoutCustomerProfileAuthenticate(input: $input) { email customerId organizationId name phone locations { administrativeArea countryCode locality line1 line2 postalCode } oneTimePassword }}When validating the customer session, ensure that the customerId you pass in the request matches the correct profile to display accurate customer information at checkout. Keep in mind that when creating a cart, you should not include customerId in the metadata, as it will be overwritten.
After the customer is authenticated and the order is placed, the customerId will be available in order.references when retrieving order details via the order query, allowing you to associate the order with the correct customer.
Create cart with customer profile
After you call both mutations, you will get the following back:
-
cartIdfrom thecreateCartmutation to generate the cart. -
A
oneTimePasswordfrom thecheckoutCustomerProfileAuthenticatemutation for the customer authentication.
You can pass both of these values in the createCartId callback in the Zonos.init function to load the provided customer profile information in Checkout.
Zonos.init({ ... checkoutSettings: { ... createCartId: async () => { const result = await fetch( 'https://api.merchant.com/api/get-cart-info', { body: JSON.stringify(payload), method: 'POST', }, ); const json = await result.json(); return { cartId: json.cartId, customerAuthenticationToken: json.customerProfileAuthenticate ?.checkoutCustomerProfileAuthenticate.oneTimePassword || '', }; } },}Manage customer profiles
The first time you submit customer information, Zonos will store the provided customer information. Payment methods will be stored securely in Stripe. Each time new address or payment method details are passed in, they will be added to the customer’s profile.
Addresses and payment methods can only be added—existing ones cannot be edited or removed. A customer's name, email, and phone can be updated with checkoutCustomerUpsert.
Create or update a profile without a shopper
checkoutCustomerProfileAuthenticate requires the shopper to be present, since it issues a one-time password for that checkout session. When you want to create or update a profile outside of a checkout—loading your customer list ahead of time, syncing profile changes from your own system, or attaching tax exemptions before a customer's first order—use checkoutCustomerUpsert instead.
mutation checkoutCustomerUpsert($input: CheckoutCustomerProfileInput!) { checkoutCustomerUpsert(input: $input) { customerId email name phone locations { administrativeArea countryCode line1 line2 locality postalCode } }}Profiles are matched on customerId, so calling this repeatedly updates the same profile rather than creating duplicates. It is safe to run across your whole customer list on a schedule.
Three things to know about how updates apply:
- Omitted fields are left alone. Sending only
nameupdates the name and leaves email and phone as they were. - Values cannot be cleared. Sending an empty value is treated the same as omitting the field, so there is no way to remove a name, email, or phone once set.
- Addresses are only added. A location that already exists on the profile is not duplicated, and locations left out of the request are not removed.
Customer profiles
Pre-load recurring shopper information into Zonos Checkout.Customer profiles streamline your checkout experience by allowing customers with an account to pre-load their address and payment details.
This feature is currently only available for custom API integrations. This feature is not yet available for merchants using Checkout plugins.
If you sell to resellers, government agencies, or nonprofits, you can also sync their tax exemption certificates to a customer profile.