Recover abandoned carts with a workflow

A buyer fills a cart and leaves. Once the cart has sat untouched past your window, the Carts app marks it abandoned and announces it with a cart.abandoned event. A cart that is reopened and abandoned again gets a new event. A workflow reads the cart and the buyer, and sends a reminder through your own mail server or CRM. The buyer follows the link into your storefront, and your storefront reopens the cart with its lines as they were. This guide builds the workflow, the storefront's reopen call, and the retention settings that decide whether the cart still exists when the buyer comes back.

This is for integrators who run a storefront on the platform and want a reminder flow built as a workflow instead of a listener they host. You need a tenant with the Carts app and Integration Studio installed, access to Cockpit (the admin interface at app.revenexx.com) to change the app's settings and build a workflow, an SMTP server or a CRM with an HTTPS API for the reminder itself, and a storefront whose server side can call the API (see Sign a buyer in). The Carts app's scope is carts.* (see which scope covers which app). New to the platform? Prerequisites covers Cockpit, your tenant slug, installing an app and a test tenant.

What the platform does, and what it leaves to you

The Carts app abandons a cart and says so. It sends nothing to a buyer. Everything after the announcement is yours.

How a cart ends up abandoned

A cart is active while a buyer fills it. These are the moves it can make:

active ──► abandoned ──► active      (reopened)
   │
   ├──► ordered    final: the record of a sale, never deleted
   └──► merged     final: folded into another cart

Two things mark a cart abandoned, and the event says which in reason:

Idle is measured from the buyer's last change to the cart. The tick that abandons a cart does not count as a change, so noticing an idle cart never restarts its clock. That matters for step 1.

Before you start: three keys

Create them in Cockpit under API keys (see create an API key), with custom scopes. Narrow scopes limit which operations a key can call.

Step 2 also reads the event catalog, which has no documented scope name. Run it with a development key with * (see which scope covers which app), or skip it and type the topics from step 2. Do not keep a * key beyond that read: revoke it afterwards.

export REVENEXX_TENANT="<TENANT_SLUG>"
export REVENEXX_API_KEY="rvxk_..."             # the setup key
export REVENEXX_DEV_API_KEY="rvxk_..."         # a development key with *, for the catalog read in step 2 only
export REVENEXX_STOREFRONT_API_KEY="rvxk_..."  # the storefront key, for step 6

REVENEXX_TENANT is the value you send as X-Revenexx-Tenant. The shell examples use jq to pick values out of the answers.

1. Set the windows

Open Apps → Installed Apps → Carts → Settings in Cockpit. Three settings decide the timing, and all three are market-scoped: the tick holds each cart against the value of its own market, and a market you have not set inherits the tenant value. How settings resolve is in Settings.

abandon_after_minutes is your reminder delay. The workflow in this guide has no wait step, and the node catalog ships none (as of 2026-10): the event arrives when the window ends. A buyer who last touched the cart at 09:00 with the default setting is announced on the first tick after 09:00 the next day, up to 15 minutes late. At 0 a market abandons nothing. A market that sets its own window uses it, even if the tenant value is 0, and a market that inherits a tenant 0 produces no idle_sweep events. If every market is at 0, only abandonments by hand (reason: requested) emit an event.

The delete settings are the only thing in this app that removes carts on its own, so ask before you set one. A dry run reports what a window would do and writes nothing:

curl -s -X POST https://api.revenexx.com/v1/carts/maintenance/run \
  -H "X-Revenexx-Tenant: $REVENEXX_TENANT" \
  -H "X-Revenexx-Api-Key: $REVENEXX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dry_run": true}' \
  | jq '{dry_run, abandon: {found: .abandon.found, capped: .abandon.capped}, purge: {found: .purge.found, would_delete_items: .purge.would_delete_items, capped: .purge.capped}}'

found names the carts the window would abandon or delete. Each half examines the 1000 oldest carts per pass, oldest first, and says capped: true when there may be more. A tenant with a very large number of idle carts can see carts held back for a few ticks.

2. Look up the topics

The event is called cart.abandoned. A workflow trigger matches the topic, which puts the vendor and the app in front. Read the topics from your tenant's event catalog instead of typing them:

curl -s https://api.revenexx.com/v1/events/catalog \
  -H "X-Revenexx-Tenant: $REVENEXX_TENANT" \
  -H "X-Revenexx-Api-Key: $REVENEXX_DEV_API_KEY" \
  | jq -r '.emits[] | select(.app == "carts" and (.name | IN("cart.abandoned", "cart.reopened", "cart.merged", "cart.ordered"))) | .topic'

By the naming rule on the Event catalog page, it should answer with revenexx.carts.cart.abandoned, revenexx.carts.cart.reopened, revenexx.carts.cart.merged and revenexx.carts.cart.ordered. If your catalog lists something else, use what it lists. REVENEXX_DEV_API_KEY is the development key from the environment block above.

The catalog also lists cart.created, cart.updated and cart.deleted. Ignore them: cart.updated fires on every line write, so a workflow subscribed to it, or to a revenexx.carts.> pattern that includes it, starts a run for every click in every cart.

3. Start the workflow on the event

In Cockpit, open Integration Studio → Workflows → New and add an Event trigger. Enter the topic as the Subject:

revenexx.carts.cart.abandoned

Save, and leave the switch in the editor's header on Paused. You activate the workflow in step 8, once the nodes behind it exist. See Event triggers for subject patterns and for the underscore note.

The event's own fields sit under data:

The event does not carry the cart's lines, the buyer's email or the cart's name. It says which cart, whose, and how much. Steps 4 and 5 fetch the rest. The cart_id is the cart; ${{ trigger.payload.id }} is the event. Reaching for the wrong one gives every later call an id no cart has, and because both ids are in the payload, nothing refuses the expression: the mistake shows only in what those later calls answer.

Add two If condition nodes behind the trigger. Conditions are not expressions: pick the field with the expression picker, then an operator and a value.

1. reason equals idle_sweep. A requested abandonment comes from a person or your own code, a minute ago, on purpose. A reminder now would be wrong. Wire the false port to nothing, or to a No Operation node.
2. contact_id is not empty. A guest cart has no address on the platform, so there is nobody to write to. The node's operator list is not documented, so find the one that tests for empty in the dropdown (as of 2026-10).

The trigger de-duplicates on the event id, and the platform gives a sweep's event one fixed id per cart and UTC day, so a delivery repeated within the day starts one run. Delivery is at least once, so keep the reminder step in step 5 safe to run twice anyway.

4. Read the cart and the buyer

Add three Generic API Call nodes with the Revenexx API credential from the workflow key. See the node catalog.

Order matters in two places.

Check the cart's status right after the first node, with another If condition: continue only when status equals abandoned. The run starts a little after the abandonment, and the buyer may have come back and ordered in between. A cart that is active, ordered or merged by now needs no reminder.

Check the buyer before you send. status is invited, active or blocked, and a blocked contact gets no mail. A contact also carries a registration_status of pending, approved or rejected, which you may want to check as well. email can be empty on a contact that exists, so route that case to a Stop and Error node or to a branch your team reads, instead of sending to nothing. Mail to someone who never agreed to marketing mail is a legal question that the platform does not answer for you: the contact record has no consent field, so keep that decision in your own system (as of 2026-10).

A cart with more lines than one page answers page.hasMore: true. A reminder usually names the first few lines and links to the rest, so you do not need to page through them.

5. Send the reminder through your own channel

The reminder leaves from your own mail server or CRM. The platform sends no cart mail. Pick one.

Mail. Add a Send Email node (SMTP). It takes a stored credential of the SMTP type, which you create under Integration Studio → Credentials and pick on the node (see Credentials). from, to, subject and the body accept expressions:

to:      ${{ nodes.buyer.outputs.response.email }}
subject: You left something in your cart
body:    Hello ${{ nodes.buyer.outputs.response.first_name }},
         your cart ("${{ nodes.cart.outputs.response.name }}") is still saved.
         Pick it up here: https://shop.example.com/cart/recover?cart=${{ trigger.payload.data.cart_id }}

buyer and cart are the ids you gave the two nodes from step 4, and the exact path after outputs. depends on the port the node resolves, so confirm each expression with the picker in the node's input panel. See Expressions. Render the lines from the Lines node with a JSON Transform or Set Fields node first, if you want them in the mail.

CRM. Add an HTTP Request node that posts the cart id, the contact and abandoned_at to your CRM's API, and let the CRM's own automation send the mail. Use an HTTP Bearer Token credential, as in Send low-stock alerts to the ERP. Key the CRM record on cart_id and abandoned_at together, so a repeated run updates it instead of creating a second.

Three decisions that are yours:

• The link. The platform has no recovery URL. The link points at a route on your storefront, which does step 6. A link that carries only the cart id, like the one above, is safe only if your storefront does what step 6 says: have the buyer sign in and check that the cart is theirs. The platform does not enforce it, and without that check, anyone holding the link can reopen the cart.
• A second send. A cart that is reopened and abandoned again on a later UTC day produces a new event with a new abandoned_at, and so a new run. Decide whether a buyer gets one reminder per cart, or one per abandonment, and keep that count in your CRM or mail system. The platform does not.
• Prices. subtotal and the line prices are the cart as the buyer left it, net of tax and shipping. By default an order is booked at the price the buyer was shown, and the Carts app's price_snapshot_mode setting can switch that to the live price (see Carts). Quote a price in the mail only if you have decided which one applies.

Set Max attempts to 1 on the send node and On error to Route to error output, both in its Settings tab, then wire the error port to something your team reads. A node is tried three times by default, and an SMTP send that timed out after the server accepted the mail would otherwise go out again. See Failure handling. There is no alert on a failed run (as of 2026-10), so check Integration Studio → Runs filtered to failed.

6. Bring the buyer back

The buyer follows your link to your storefront. The storefront's server, not the browser, calls the API with the storefront key.

curl -s "https://api.revenexx.com/v1/carts/<CART_ID>" \
  -H "X-Revenexx-Tenant: $REVENEXX_TENANT" \
  -H "X-Revenexx-Api-Key: $REVENEXX_STOREFRONT_API_KEY" \
  | jq '{id, status, contact_id, merged_into_cart_id}'

What the storefront does with each answer:

curl -s -X POST "https://api.revenexx.com/v1/carts/<CART_ID>/reopen" \
  -H "X-Revenexx-Tenant: $REVENEXX_TENANT" \
  -H "X-Revenexx-Api-Key: $REVENEXX_STOREFRONT_API_KEY"

The cart is active again, with every line and both totals as they were, and abandoned_at cleared. A cart in any other status answers 400 naming the status it holds. Reopening also counts as a change, so the idle clock starts again.

Two things to know about a reopened cart:

• Reopening does not make the cart current. If your storefront resumes the buyer's cart by is_current, call POST /v1/carts/<CART_ID>/activate afterwards.
• Reopen before any write. An abandoned cart refuses new lines with a 400 until it is reopened. A storefront that adds to the cart without checking its status hits that error on exactly the buyers this guide brings back.

The buyer already started a new cart

A buyer who found your shop again without the link may hold a fresh active cart. Reopen the old one, then fold one into the other with POST /v1/carts/{id}/merge-into. The path id is the cart you give away, and the body's target_cart_id names the cart that survives. Both must be active, different and in the same currency. See Carts.

A guest returns

A guest cart gets no reminder, because it has no address, but its owner may come back in the same browser session and then sign in. Reopen it first, then claim the session. POST /v1/carts/claim hands over only the active carts of a session, and a cart the guest had abandoned stays with the session.

curl -s -X POST https://api.revenexx.com/v1/carts/claim \
  -H "X-Revenexx-Tenant: $REVENEXX_TENANT" \
  -H "X-Revenexx-Api-Key: $REVENEXX_STOREFRONT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"session_key":"<SESSION_KEY>","contact_id":"<CONTACT_ID>","target_cart_id":"<CUSTOMERS_CART_ID>","strategy":"merge"}'

Take session_key from your storefront's own server-side session, never from a request parameter: the route hands the carts of whatever session it is given to whatever contact it is given.

Without target_cart_id the guest carts are adopted as they stand. With it they fold into that cart, and the app's cart_merge_strategy setting (Cart merge strategy, default merge) decides what happens to the target's own lines: merge keeps them and adds the guest lines, replace clears them first. strategy in the body overrides the setting for one call, and the answer says which one ran. The merge strategy applies to a claim only, not to merge-into.

7. Close the loop

Three more events say how a recovery went. Give each its own workflow, with its own Subject, instead of a pattern.

cart.ordered carries every line because retention may delete the cart long before you read the feed. cart.merged is published for the target, the cart that survives, and a claim that adopts a guest cart without a target publishes no merge event at all (as of 2026-10), so a guest cart changing owner shows up only as the cart's own update. A refused reopen or merge publishes nothing.

Key your records on cart_id. A reminder sent for a cart that was later merged belongs to the source_cart_id in the event.

8. Test it once

Do this on a test tenant, because it changes a setting that applies to every cart on it. You need a contact with your own email address (see Storefront accounts), and its id.

Test step 1. Set Abandon a cart after (minutes) to 1 for the test, and leave the delete settings at 0.

Test step 2. Create a cart for the contact and add a line:

CART_ID=$(curl -s -X POST https://api.revenexx.com/v1/carts \
  -H "X-Revenexx-Tenant: $REVENEXX_TENANT" \
  -H "X-Revenexx-Api-Key: $REVENEXX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contact_id":"<CONTACT_ID>","name":"Reminder test"}' | jq -r '.id')

curl -s -X POST "https://api.revenexx.com/v1/carts/$CART_ID/items" \
  -H "X-Revenexx-Tenant: $REVENEXX_TENANT" \
  -H "X-Revenexx-Api-Key: $REVENEXX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sku":"ACME-4711-BLK","quantity":2,"unit_price":19.90}'

Test step 3. Activate the workflow: flip the switch in the editor's header from Paused to Active. Check the switch after you save: a workflow with unfilled required settings is saved paused.

Test step 4. Wait more than a minute, then run the tick by hand. It does exactly what the 15-minute tick does, so every cart on the tenant that is idle past the window is abandoned and announced:

curl -s -X POST https://api.revenexx.com/v1/carts/maintenance/run \
  -H "X-Revenexx-Tenant: $REVENEXX_TENANT" \
  -H "X-Revenexx-Api-Key: $REVENEXX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}' | jq '{abandoned: .abandon.abandoned, cart_ids: .abandon.cart_ids}'

Test step 5. Open Integration Studio → Runs: one run for your cart, and the mail in your inbox. Then follow the link through your storefront, or call the reopen route from step 6 yourself, with the storefront key.

Test step 6. Set the window back to what you decided in section 1.

A cart you abandon with POST /v1/carts/{id}/abandon fires the event too, with reason: requested, and the workflow ends at the first condition. That is a way to test the trigger without waiting, and it proves the reason filter.

Troubleshooting

Where to go next

• Carts — every cart route, the lifecycle, claiming and merging.
• Event catalog — the topics and the fields each event carries.
• Choose an event surface — when a workflow is the right consumer of an event and when a webhook is.
• Failure handling — retries, error routing and timeouts for the nodes above.