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.

All communication runs server side, from UltraCart to the Attentive API. There is no Attentive JavaScript tag to add to your storefront, and no theme edits are required.

What UltraCart sends to Attentive

Event	Sent when	Sent to Attentive as
Subscribe	A shopper opts in, and automatically alongside each add-to-cart event	/v1/subscriptions
Unsubscribe	A shopper opts out through UltraCart	/v1/subscriptions/unsubscribe
Add to Cart	An item is added to the cart	/v1/events/ecommerce/add-to-cart
Checkout Started	The shopper enters checkout	Custom event, type Checkout Started
Checkout Abandoned	The shopper leaves checkout without ordering	Custom event, type Checkout Abandoned
Purchase	An order is placed	/v1/events/ecommerce/purchase
Product catalog sync	The catalog sync job runs	/v1/product-catalog/uploads

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:

• Transactional Source ID, the unit tied to transactional opt-in, used for order and shipping notifications.
• Add to Cart Source ID, the unit UltraCart subscribes shoppers to when they add an item to the cart.

A third field, Product View Source ID, is reserved for a forthcoming storefront pixel. UltraCart stores the value but does not yet send product view events, so filling it in has no effect today. The field is optional and you can leave it blank.

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

The same four settings exist in two places, and which one you use depends on how your account is organized.

Account-level settings

Navigate to Home -> Marketing -> Attentive.

Field	Value to enter
API Key	The private key from Step 1
Transactional Source ID	Sign-up source ID for transactional opt-ins
Product View Source ID	Optional. Reserved for future use, no effect today
Add to Cart Source ID	Sign-up source ID for cart activity

Click Save. The Log button on this screen opens the integration log described in Verifying the integration.

StoreFront-level settings

The same four settings also exist per StoreFront. Use these when different StoreFronts should report into different Attentive sign-up units.

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
Add to Cart Source ID	20 characters
Product View Source ID	20 characters
Transactional Source ID	20 characters

Which setting wins

A StoreFront value overrides the account-level value, for that StoreFront only.

Resolution happens one field at a time, not all or nothing. A field you leave blank on a StoreFront inherits the account-level value instead of blanking it. So you can enter the private API key once at the account level and override only a single source ID on one StoreFront.

Because non-numeric source IDs are discarded when you save, entering one on a StoreFront leaves that field blank, and the StoreFront quietly falls back to the account-level value.

This override applies to the subscribe, unsubscribe, and product catalog sync paths. The add-to-cart and purchase events do not resolve per-StoreFront settings yet, so they always use the account-level values regardless of what a StoreFront specifies.

How shoppers are identified

Attentive needs at least one identifier to attach an event to a shopper.

• Add to Cart, Checkout Started, and Checkout Abandoned are sent when the cart has a valid email address or any phone number. If the cart has neither, the event is skipped and recorded in the integration log with a status of WARNING.
• Purchase requires an email address.

When a cart or order carries more than one phone number, UltraCart uses the first one available in this order: cell phone, ship-to phone, then the general phone number. All phone numbers are sent in E.164 format.

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

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.

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.

Category and collection data is not included yet. The sync job does not resolve a StoreFront, so no catalog host is available and category and collection information is skipped. The upload still reports success, and a warning is written to the integration log. Do not build Attentive segments that depend on product category or collection until this is delivered.

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 event was skipped, most often because the cart had no email or phone
ERROR	Attentive rejected the call, or the request failed

tip

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

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 API key and source IDs are saved.
• A WARNING entry means the cart had no valid email address and no phone number.
• An ERROR entry includes the status code Attentive returned.

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. The integration is entirely server side.

Why does UltraCart subscribe shoppers on add to cart? 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.

Related resources

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