Attentive Integration

Attentive is an SMS and mobile marketing platform. Connecting it to UltraCart lets you collect SMS subscribers during checkout and feed shopper activity into Attentive so your journeys can trigger on real cart and order behavior.

The integration has two halves that you turn on separately.

• Server side, from UltraCart to the Attentive API. This carries subscribe, add to cart, checkout, purchase, and order shipped activity, and uploads your product catalog. It runs off the Attentive API key saved on each StoreFront.
• The Attentive tag, a small piece of JavaScript UltraCart adds to your StoreFront pages for you. It reports product views, which the server cannot see, and it displays the sign-up units you have built in Attentive. It runs off your Attentive Company ID.

You can run either half on its own. Entering only the API key gives you the server events with no tag on your pages. Entering only the Company ID gives you the tag with no server events. Most merchants want both.

No theme edits are required either way. UltraCart adds the tag to your pages automatically once the Company ID is saved.

What UltraCart sends to Attentive

Each event is sent by exactly one half of the integration. Attentive has no way to recognize the same event arriving twice, so UltraCart never sends one from both.

Event	Sent by	Sent when	Sent to Attentive as
Subscribe	Server	Alongside an add-to-cart or purchase event, only when the shopper opted in to SMS with a mobile number	/v1/subscriptions
Unsubscribe	Server	A shopper opts out through UltraCart	/v1/subscriptions/unsubscribe
Add to Cart	Server	An item is added to a cart that has an email address or a consented mobile number	/v1/events/ecommerce/add-to-cart
Add to Cart	Tag	An item is added to a cart with no email address and no consented mobile number	addToCart
Checkout Started	Server	The shopper enters checkout	Custom event, type Checkout Started
Checkout Abandoned	Server	The shopper leaves checkout without ordering	Custom event, type Checkout Abandoned
Purchase	Server	An order is placed	/v1/events/ecommerce/purchase
Order Shipped	Server	An order ships	Custom event, type Order Shipped
Product View	Tag	A shopper opens a product page	productView
Identify	Tag	The shopper's email address becomes known, at checkout and on the receipt	identify
Product catalog sync	Server	The catalog sync job runs	/v1/product-catalog/uploads

Product view is the reason to run the tag. UltraCart's servers never see a product page load, so there is no server-side equivalent and no other way to feed browse behavior into Attentive.

The Identify event matters more than its name suggests. It ties Attentive's own visitor cookie to a shopper you can contact, which is what lets Attentive connect anonymous browsing earlier in the session to the person who eventually checked out. Without it, product views from a shopper who had not yet entered an email address stay unattached to any subscriber.

Before you begin

Confirm the following:

• You have an active Attentive account with SMS marketing enabled.
• You have administrator or developer access in Attentive, enough to create an app and view sign-up units.
• Transactional messaging is enabled in Attentive if you plan to send order-related texts.
• You can access UltraCart with Marketing permissions.

Some sign-up units may need to be created for you by your Attentive Customer Success Manager. If you cannot find the units described below, contact them before continuing.

Step 1: Create an Attentive API key

UltraCart authenticates to Attentive with a private API key, sent as a bearer token on every request.

1. Sign in to your Attentive admin account.
2. Open the integrations or app marketplace area and choose to create an app.
3. Give the app a recognizable name, such as UltraCart Integration, and enter a contact email address.
4. Grant the app write permission to eCommerce, Subscribers, and Custom Events. UltraCart needs all three: eCommerce for add-to-cart and purchase, Subscribers for opt-ins and opt-outs, and Custom Events for the checkout events.
5. Create the app and copy the generated key.

warning

Attentive may display the API key only once. Copy it somewhere safe before leaving the page. If you lose it, generate a new key and update UltraCart, because the old key stops working.

Step 2: Collect your sign-up source IDs

Sign-up source IDs are the numeric identifiers of your Attentive sign-up units. In Attentive, open Sign-Up Units and stay on the Sign-up units tab, then note the value in the ID column for each unit you plan to use.

warning

Take the IDs from the Sign-up units tab, not the A/B tests tab alongside it. The A/B tests tab also has an ID column, but those are test identifiers. Entering one in UltraCart produces no error and no events reach the intended sign-up source.

Two of these IDs are in use today. Both are optional:

• Transactional Source ID, the unit UltraCart subscribes SMS-consented shoppers to when they place an order. Leave it blank if you have no transactional unit; purchase events are still sent, and only the subscribe is skipped.
• Add to Cart Source ID, the unit UltraCart subscribes SMS-consented shoppers to when they add an item to the cart. Leave it blank and add-to-cart events are still sent without a subscribe.

A third field, Product View Source ID, has no effect and you can leave it blank. It was added in anticipation of product view tracking, but product views turned out to be reported by the Attentive tag rather than the API, and the tag identifies visitors by its own cookie instead of a sign-up source. UltraCart stores whatever you enter and never sends it.

Source IDs must be numeric. A value containing anything other than digits is discarded when you save.

Some Attentive accounts use one marketing unit for several purposes, and reusing the same ID across fields is valid if that matches how your account is set up. Confirm with Attentive if you are unsure. Attentive documents where these IDs live in its Subscribe user reference.

Step 3: Enter your credentials in UltraCart

Attentive is configured per StoreFront. Enter the settings on every StoreFront that should send to Attentive.

StoreFront settings

1. Go to StoreFronts and select the StoreFront you want to configure.
2. Choose Privacy & Tracking.
3. Open the Other tab.
4. Scroll to the Attentive SMS block.

Field	Maximum length
Private API Key	250 characters
Company ID	40 characters
Add to Cart Source ID	20 characters
Product View Source ID	20 characters
Transactional Source ID	20 characters

Company ID is the field that turns on the Attentive tag, and it exists only here, not at the account level. See Turning on the Attentive tag.

Because non-numeric source IDs are discarded when you save, entering one leaves that field blank, and the matching subscribe is skipped.

One StoreFront, one Attentive account

Each StoreFront uses only its own settings. There is no account-level fallback.

• A StoreFront with no Private API Key sends nothing to Attentive: no subscribes, no events, and no catalog upload. Leave the key blank on any StoreFront you want kept out, such as an affiliate or wholesale StoreFront.
• StoreFronts can point at different Attentive accounts. Enter a different key and source IDs on each. StoreFronts that share the same key report into the same account.
• Every event is sent with the settings of the StoreFront the cart or order belongs to, whatever items it contains. Routing events to an account by item is not supported.

The Marketing Attentive screen

The older Home -> Marketing -> Attentive screen holds an account-level API key and source IDs. Those values are no longer used for StoreFront events or catalog sync. Use the StoreFront settings above instead. The Log button on that screen still opens the integration log described in Verifying the integration.

Turning on the Attentive tag

Enter your Attentive Company ID in the StoreFront settings and click Save. UltraCart starts adding the tag to that StoreFront's pages immediately. There is nothing to paste into a theme and nothing to deploy.

Your Company ID is the identifier in your Attentive tag snippet. If Attentive gave you a line that looks like https://cdn.attn.tv/YOURBRAND/dtag.js, then YOURBRAND is the value to enter. It is a short text code rather than a number, and it is not a secret, unlike your API key.

Clearing the field removes the tag from your pages. Your server-side events keep running, because those depend on the API key instead.

The tag also displays your sign-up units

Attentive's tag does two jobs. It reports the browser events listed above, and it displays the sign-up units you have configured in Attentive: the popups, full-screen takeovers, footers, and spin-to-win offers that collect phone numbers and email addresses.

If you have no active sign-up units in Attentive, nothing appears and the tag is invisible to shoppers. If you do have active units, they will start appearing on your UltraCart StoreFront the same way they appear on the rest of your site.

warning

Sign-up units display automatically and UltraCart cannot suppress them. Before saving your Company ID, check which units are active in Attentive and where they are set to appear. A popup over your checkout form will cost you orders.

Control this in Attentive rather than in UltraCart, using the Hide sign-up unit if section of each unit's display rules. Add your checkout path to URL contains there to keep units off the pages where they do damage.

If you already collect SMS opt-ins with UltraCart's own SMS opt-in checkout widgets, decide which one you want. Running an Attentive sign-up unit alongside the UltraCart widget asks the same shopper for the same consent twice.

How shoppers are identified

Attentive needs at least one identifier to attach an event to a shopper. Which identifiers UltraCart is willing to send is a consent question as much as a technical one.

• Add to Cart, Checkout Started, Checkout Abandoned, Purchase, and Order Shipped are sent when the cart or order has a valid email address or a mobile number the shopper consented to receive SMS marketing on. If it has neither, the event is skipped and recorded in the integration log with a status of WARNING.
• Events are sent whether or not the shopper is an Attentive subscriber.

Phone numbers require an SMS opt-in

A phone number reaches Attentive only when the shopper has opted in to SMS marketing, and only the mobile number they opted in with. Shipping and billing phone numbers are fulfillment contact details rather than marketing consent, so they stay out of every event. Numbers are sent in E.164 format.

Shoppers give that consent through the SMS opt-in checkbox on your checkout, or through whichever StoreFront widget you have configured to capture it. If you are not seeing phone numbers in Attentive, make sure you are collecting a positive opt-in in your checkout.

A cart whose only identifier is an unconsented phone number has nothing Attentive can use, so its events are skipped and recorded in the integration log with a status of WARNING.

Subscriptions are SMS only

Attentive creates an email subscription for any subscribe call that includes an email address. UltraCart therefore never sends an email address in a subscribe call.

• A shopper is subscribed only when they opted in to SMS and have a mobile number, and only with that mobile number.
• A shopper with no SMS opt-in is never subscribed. Their add-to-cart, purchase, and other events are still sent, carrying their email address.
• A subscribe is also skipped when the matching source ID is blank.

Each skipped subscribe is recorded in the integration log with a status of WARNING, so WARNING entries for shoppers without an SMS opt-in are expected.

Collecting SMS consent at checkout

Use UltraCart's checkout sms opt-in StoreFront Visual Builder element. It shows an unchecked consent checkbox, a mobile number field, and disclosure text you can edit, including links to your Terms and Privacy pages. Leave its default-on setting at No, because a pre-checked box is not valid consent under TCPA rules.

The lighter checkout sms opt-in checkbox element records consent but does not collect a mobile number. A shopper who checks it without a mobile number on the cart is not subscribed, so prefer the full checkout sms opt-in element for Attentive.

Customer profile data

Every event carries the shopper's name and address into Attentive as custom identifiers, so the data is available for segmentation. UltraCart sends firstName, lastName, address1, address2, city, state, zip, and country.

The shipping address is preferred. If the shipping address is incomplete, UltraCart falls back to the billing address as a whole rather than mixing fields from both, so a digital-only order with no shipping address still produces a complete profile.

Marketing versus transactional subscriptions

An add-to-cart subscribe uses the Add to Cart Source ID, and a purchase subscribe uses the Transactional Source ID. When UltraCart subscribes a shopper, it compares the sign-up source ID being used against your configured Transactional Source ID:

• The two match, so the subscription is sent as TRANSACTIONAL.
• The two differ, or no Transactional Source ID is configured, so the subscription is sent as MARKETING.

This matters because Attentive applies different consent and messaging rules to each type. If your transactional messages are not going out, verify that the Transactional Source ID in UltraCart matches the transactional unit in Attentive exactly.

Checkout event data

Checkout Started and Checkout Abandoned are sent as Attentive custom events. Custom events carry a flat set of properties rather than a line item array, so UltraCart summarizes the cart into values you can trigger journeys on:

Property	Contents
itemCount	Number of distinct items in the cart
totalQuantity	Total quantity across all items
cartValue	Sum of item cost multiplied by quantity
currency	Cart currency code
productIds	Comma-separated list of item IDs
productNames	Comma-separated list of item descriptions

Kit component items are excluded from all cart and order events, so a kit reports as the single item the shopper actually bought.

Order shipped event data

Order Shipped is sent as an Attentive custom event, because Attentive has no shipment endpoint. Use it to trigger shipping notification journeys. Its properties are:

Property	Contents
orderId	UltraCart order ID
carrier	Shipping carrier code
shippingMethod	Shipping method name
trackingNumbers	Comma-separated list of tracking numbers
trackingUrl	Tracking link for the first tracking number that has one
shipDate	Ship date
productIds	Comma-separated list of item IDs
productNames	Comma-separated list of item descriptions

The event time is when UltraCart sends the event, not the ship date, because Attentive ignores events more than 12 hours old when triggering journeys. Each order uses the same external event ID, OrderShipped- followed by the order ID, so a re-sent shipment can be recognized as the same event.

Item IDs in events

Add to Cart and Purchase line items carry the UltraCart item ID as both the product ID and the variant ID, along with the item name, unit price, and quantity. The catalog sync uses the same item IDs, so events for items without variations match the catalog UltraCart uploads.

For an item with variations, the event carries the purchased child item's ID in both fields, while the catalog lists that child as a variant under its parent. Product matching for variation items may therefore be incomplete in Attentive.

If your Attentive catalog came from another platform with different product IDs, events will not match it.

Product catalog sync

UltraCart uploads your catalog to Attentive so journeys can reference real products.

Each product includes its ID, name, description, price, image, and URL. Items with variations are uploaded as a single parent product with a variants array, and each variant carries its own ID, name, SKU, price, image, link, and option values such as size and color. Child items are not uploaded as separate products. Inactive items and inactive child items are skipped.

The catalog is uploaded once per Attentive account. StoreFronts that share a Private API Key share one upload, with category and collection data merged from each of those StoreFronts. A StoreFront with a different key gets its own upload, and a StoreFront with no key is skipped. Every upload contains all of your items; it is not limited to the items a particular StoreFront sells.

If your account has linked child accounts, the parent account gathers and uploads the catalog for the whole family. Child accounts are skipped so items are not uploaded twice.

UltraCart waits for Attentive to validate each upload instead of sending and forgetting. It polls for up to 10 minutes, and the resulting counts or per-item errors are written to the integration log.

Verifying the integration

Every Attentive call is written to the UltraCart integration log, including the JSON payload that was sent and the HTTP status code that came back. The API key is masked. Use the Log button on the Marketing Attentive screen to open it.

Statuses you will see:

Status	Meaning
SUCCESS	Attentive returned HTTP 200 and accepted the event
WARNING	The call was skipped: the cart or order had no usable identifier, its only phone number lacked an SMS opt-in, or a subscribe had no SMS opt-in or no source ID
ERROR	Attentive rejected the call, or the request failed

Start troubleshooting here. The log tells you whether UltraCart sent the event at all, which separates a UltraCart configuration problem from an Attentive journey problem.

The integration log covers the server side only. Events sent by the Attentive tag go straight from the shopper's browser to Attentive and never pass through UltraCart, so they do not appear here. Check those in Attentive's own reporting, or in your browser's developer tools by watching for requests to events.attentive while you browse a product page.

Troubleshooting

Authentication errors

A 401 response means Attentive rejected the API key. Confirm the key was copied in full, confirm the app in Attentive still exists and has write permission to eCommerce, Subscribers, and Custom Events, then regenerate the key and save it in UltraCart again.

Events are not reaching Attentive

Check the integration log first.

• No log entry at all means UltraCart never attempted the call. Verify the Private API Key is saved on the StoreFront the cart or order belongs to. The Marketing Attentive screen does not count.
• A WARNING entry means the cart carried no identifier Attentive can use. Read the message: it distinguishes a cart with no email address and no phone number at all from one whose only phone number had no SMS opt-in behind it.
• An ERROR entry includes the status code Attentive returned.

Product views are not appearing in Attentive

Product views come from the Attentive tag, not the server, so the integration log will not show them either way. Check the Company ID is saved on the StoreFront the shopper is browsing, because it is a per-StoreFront setting with no account-level fallback.

Then open a product page with your browser's developer tools on the Network tab and look for a request to cdn.attn.tv. If it is missing, the tag is not loading: confirm the Company ID is correct, and check whether a privacy or consent banner on your StoreFront is holding it back, since UltraCart withholds the tag until a shopper grants marketing consent.

A sign-up unit is appearing where you do not want it

Sign-up units are controlled entirely in Attentive. Open the unit, find the Hide sign-up unit if section of its display rules, and add the path you want it kept off in URL contains. Clearing your UltraCart Company ID also removes every unit at once, along with product view tracking.

Journeys are not triggering

If the log shows SUCCESS but nothing happens in Attentive, the problem is on the Attentive side. Confirm the journey is active, confirm the shopper is subscribed, and confirm the journey is listening on the same sign-up source ID you configured in UltraCart.

Products are missing from the catalog

Inactive items are skipped by design, as are child items of a variation parent, which appear inside the parent's variants instead. If a whole catalog is missing, check the integration log for the upload result, which reports validation errors per item.

Frequently asked questions

Can I use the same source ID in more than one field? Yes, if your Attentive account uses a shared marketing unit. Be aware that the transactional or marketing classification is decided by comparing against the Transactional Source ID, so sharing that particular ID changes how subscriptions are classified.

What happens if I regenerate my Attentive API key? UltraCart calls start failing with a 401 until you save the new key. Update it in UltraCart immediately after regenerating.

Do I need to add anything to my storefront theme? No. UltraCart adds the Attentive tag to your pages for you once you save a Company ID, and removes it when you clear the field.

Can I run the Attentive tag for tracking without the sign-up popups? Not from UltraCart. The tag is one file and it carries both. Your options are to keep every sign-up unit paused or archived in Attentive, to scope them with display rules so they never match your StoreFront pages, or to ask Attentive support to disable auto-load on your account.

Why does UltraCart subscribe shoppers on add to cart? When a shopper has opted in to SMS, add-to-cart events include a subscribe call using your Add to Cart Source ID, so the shopper exists in Attentive and can be targeted by cart recovery journeys. Shoppers without an SMS opt-in are not subscribed.

Will UltraCart create email subscriptions in Attentive? No. Subscribe calls carry only the consented mobile number. See Subscriptions are SMS only.

Can I keep one StoreFront out of Attentive? Yes. Leave the Private API Key blank on that StoreFront and it sends nothing. See One StoreFront, one Attentive account.

Can UltraCart send my past orders to Attentive? No. Only orders placed after the integration is connected are sent.

I am not seeing phone numbers in Attentive. Why? Make sure you are collecting a positive SMS opt-in in your checkout. A phone number is sent only when the shopper has opted in, and only the mobile number they opted in with. See Phone numbers require an SMS opt-in.

Related resources

• 3rd Party Marketing for the full list of supported providers
• Attentive guides
• Attentive developer documentation