Carts API Reference

import os
import time

import pandas as pd
import requests

BASE = "https://api.cartlytics.co/api/v1/public"
HEADERS = {"Authorization": "Bearer ck_YOUR_KEY"}
CSV = "cartlytics_carts.csv"


def fetch_all(path, params):
    """Follow nextCursor to the last page, and wait out a 429."""
    rows, cursor = [], None
    while True:
        query = dict(params, limit=250, **({"cursor": cursor} if cursor else {}))
        page = requests.get(f"{BASE}/{path}", headers=HEADERS, params=query, timeout=30)
        if page.status_code == 429:
            time.sleep(int(page.headers.get("Retry-After", "60")))
            continue
        page.raise_for_status()
        body = page.json()
        rows += body["data"]
        cursor = body["nextCursor"]
        if not cursor:
            return rows


COLUMNS = ["shop", "cart_id", "status", "modified_at", "last_activity", "cart_value",
           "customer_id", "customer_email", "variant_id", "product", "quantity", "line_price"]


def when(value):
    return pd.to_datetime(value, format="ISO8601", utc=True)


# Resume from the newest change already saved. The first run takes the last 30 days.
# dtype=str keeps the Shopify IDs as text, so a blank cell does not turn them into floats.
old = pd.read_csv(CSV, dtype=str) if os.path.exists(CSV) else pd.DataFrame(columns=COLUMNS)
since = {}
if not old.empty:
    since = {"modified_since": when(old["modified_at"]).max().strftime("%Y-%m-%dT%H:%M:%S.%fZ")}

changed = fetch_all("carts", since)
deleted = fetch_all("deleted-carts", {"deleted_since": since["modified_since"]} if since else {})

# A cart that changed during the run comes back twice: keep its newest version.
newest = {}
for cart in changed:
    seen = newest.get(cart["id"])
    if seen is None or when(cart["modifiedAt"]) > when(seen["modifiedAt"]):
        newest[cart["id"]] = cart

# Deletions come in time order, so the newest one per cart wins.
deleted_at = {d["id"]: when(d["deletedAt"]) for d in deleted}

rows = []
for cart in newest.values():
    # A deletion counts only when it came after the cart's last change.
    if cart["id"] in deleted_at and deleted_at[cart["id"]] >= when(cart["modifiedAt"]):
        continue
    customer = cart["customer"] or {}
    for line in cart["lineItems"] or [{}]:
        rows.append({
            "shop": cart["shop"], "cart_id": cart["id"], "status": cart["status"],
            "modified_at": cart["modifiedAt"], "last_activity": cart["lastActivityAt"],
            "cart_value": cart["totalValue"], "customer_id": customer.get("id"),
            "customer_email": customer.get("email"), "variant_id": line.get("variantId"),
            "product": line.get("title"), "quantity": line.get("quantity"),
            "line_price": line.get("linePrice"),
        })

# A changed cart replaces all of its old rows, and a deleted cart drops them.
old = old[~old["cart_id"].isin(set(newest) | set(deleted_at))]
out = pd.concat([old, pd.DataFrame(rows, columns=COLUMNS, dtype=object)], ignore_index=True)

# active and abandoned follow the clock, not a change, so work them out on every run.
recent = when(out["last_activity"]) > pd.Timestamp.now(tz="UTC") - pd.Timedelta(hours=24)
open_cart = ~out["status"].isin(["converted", "draft_order"])
out.loc[open_cart, "status"] = recent[open_cart].map({True: "active", False: "abandoned"})
out.to_csv(CSV, index=False)