Cart recovery
Abandoned carts, the recovery email and its restore link, share links, the email log and the recovery rate.
The carts worth chasing, the messages sent about them, and what came back. See Cart recovery.
List abandoned carts
/api/v1/kahunacart/carts/abandoned
Carts that have sat untouched past the store's abandoned window and still have an email address and something in them, biggest first by default. Each row carries the customer, how many lines it holds, what it is worth, when it was last touched, and whether a recovery message and its one reminder have gone out. The answer also says whether the sweep, the restore links and the reminder are switched on, so an empty mailed column can be told from sending being off.
Parameters
| Name | Type | Description |
|---|---|---|
| sort optional | string |
value is biggest cart first and activity is longest idle first; the rest sort by that column, with dir for the direction across every page
One of:
value, activity, cart, lines, mailed, remindedDefault:
value |
| dir optional | string |
The direction of the sort; with none, value and activity run biggest and longest first and the other columns run ascending
One of:
asc, desc |
| q optional | string | Words to search for in the email on the cart; every word has to be there, in any order. Applied before the sort and the page, and total counts what it found |
| hours optional | integer | Override the store's abandoned window for this call |
| page optional | integer |
At least 1.
Default:
1 |
| per_page optional | integer |
At least 1.
Default:
25 |
Send a cart its recovery email
/api/v1/kahunacart/carts/{id}/recovery-email
Queue the recovery message for one abandoned cart now instead of waiting for the sweep, and stamp the cart so the sweep does not mail it again. The message goes to the address already on the cart and never to one you supply. 409 when the cart has no address on it or when cart recovery is switched off.
Parameters
| Name | Type | Description |
|---|---|---|
| id required | integer | Cart (order) id |
Create a cart link
/api/v1/kahunacart/carts/{id}/link
Mint a signed link that opens one cart in a customer's own browser — the way a phone or social sale is handed over. A share link is single-use, short-lived and challenges an anonymous load for the address on the cart; a recovery link may be opened repeatedly and lives for recovery.link_days. Give an email address to send it as well as return it.
Parameters
| Name | Type | Description |
|---|---|---|
| id required | integer | Cart (order) id |
| purpose optional | string |
One of:
share, recoveryDefault:
share |
| email optional | string | Send the link here as well as returning it; omit to only return it |
List sent emails
/api/v1/kahunacart/emails
A page of the email log, newest first: every message the store queued for a customer with its kind, recipient, subject, order, how many attempts it took, whether it was sent, failed or is still pending, and the transport's own words on a failure. This is the log to read when a customer says they never got their receipt. KahunaCart does not track opens — opened_at and bounced_at are only ever filled by a transport that reports them.
Parameters
| Name | Type | Description |
|---|---|---|
| kind optional | string | One message kind, e.g. order_confirmation or abandoned_cart |
| recipient optional | string | Substring of the recipient address |
| status optional | string |
One of:
sent, failed, pending |
| order_id optional | integer | Only messages about this order |
| sort optional | string |
A column to sort the whole list by before it is paged; leave out for the usual order
One of:
message, recipient, order, result, attempts, queued, sent |
| dir optional | string |
One of:
asc, descDefault:
asc |
| page optional | integer |
At least 1.
Default:
1 |
| per_page optional | integer |
At least 1.
Default:
25 |
Cart recovery rate
/api/v1/kahunacart/reports/recovery
How well cart recovery is working over a window: carts mailed, carts reminded, carts recovered, the recovery rate, and what the recovered carts were worth once they became orders. A recovered cart is counted once however many times its link was opened. The money is one currency's, the base currency unless you pass currency, and recovered carts in the others are counted in other_currencies.
Parameters
| Name | Type | Description |
|---|---|---|
| currency_picker optional | string |
Ask for report_currency_available when the store has several currencies or historical foreign orders; no extra field on a single-currency store
One of:
1 |
| currency optional | string | A known currency code for native totals, or all for exact totals in base currency using each order's frozen fx_to_base. Unrated orders and refunds are excluded and counted separately. Left out, the base currency. A single-currency store stays unchanged; an unknown code is a 422. |
| days optional | integer |
At least 1, at most 365.
Default:
30 |
carts/abandoned is sorted by value, biggest first, and reports what has been mailed and what has come back. recovery-email queues a message for one cart and answers 409 when that cart has already had one. link mints a signed link over a row in kahunacart_cart_links rather than over the cart's id, so a link is revoked by spending its row without touching any other link the store has issued; purpose chooses between a repeatable recovery link and a single-use share link. There is no route that restores a cart, because restoring is the customer's own action behind their own link. emails is the email log, one row per queued message, updated on retry and never duplicated, with status derived from the timestamps rather than stored. reports/recovery counts a cart as recovered once however many times its link was opened, and applies the window to when each cart was mailed.