Shopify Admin Checkout Abandonment Report

Purpose

Aggregates abandoned checkout data broken down by cart value bucket and hour of day (UTC). Helps identify when and at what price point customers are most likely to abandon checkout. Scoped to what the abandonedCheckouts API provides — device type and geographic location are not available in this API and are not reported.

Prerequisites

• Authenticated Shopify CLI session: shopify auth login --store <domain>
• API scopes: read_checkouts

Parameters

Workflow Steps

1. OPERATION: abandonedCheckouts — query Inputs: first: 250, query: "created_at:>='<date_range_start>' created_at:<='<date_range_end>'", pagination cursor Expected output: All abandoned checkouts in range with totalPrice and createdAt; paginate until hasNextPage: false; then aggregate in-memory: (1) count by cart value bucket, (2) count by hour of day (UTC, 0–23)

GraphQL Operations

graphqlCopy code
# abandonedCheckouts:query — validated against api_version 2025-04
query AbandonedCheckoutsReport($first: Int!, $after: String, $query: String) {
  abandonedCheckouts(first: $first, after: $after, query: $query) {
    edges {
      node {
        id
        createdAt
        totalPriceSet {
          shopMoney {
            amount
            currencyCode
          }
        }
        customer {
          defaultEmailAddress {
            emailAddress
          }
        }
        lineItems {
          edges {
            node {
              title
              quantity
              variant {
                price
              }
            }
          }
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Session Tracking

Claude MUST emit the following output at each stage. This is mandatory.

On start, emit:

Copy code
╔══════════════════════════════════════════════╗
║  SKILL: checkout-abandonment-report          ║
║  Store: <store domain>                       ║
║  Started: <YYYY-MM-DD HH:MM UTC>             ║
╚══════════════════════════════════════════════╝

After each step, emit:

Copy code
[N/TOTAL] <QUERY|MUTATION>  <OperationName>
          → Params: <brief summary of key inputs>
          → Result: <count or outcome>

On completion, emit:

For format: human (default):

Copy code
══════════════════════════════════════════════
OUTCOME SUMMARY
  Total abandoned:   <n>
  Date range:        <start> to <end>
  Errors:            0
  Output:            none
══════════════════════════════════════════════

For format: json, emit:

jsonCopy code
{
  "skill": "checkout-abandonment-report",
  "store": "<domain>",
  "started_at": "<ISO8601>",
  "completed_at": "<ISO8601>",
  "dry_run": false,
  "steps": [
    { "step": 1, "operation": "AbandonedCheckoutsReport", "type": "query", "params_summary": "<date_range_start> to <date_range_end>", "result_summary": "<n> checkouts", "skipped": false }
  ],
  "outcome": {
    "total_abandoned": 0,
    "date_range_start": "<date_range_start>",
    "date_range_end": "<date_range_end>",
    "by_cart_value": [
      { "range": "$0 – $25", "count": 0, "pct": 0.0 }
    ],
    "by_hour_utc": [
      { "hour": "00:00", "count": 0, "pct": 0.0 }
    ],
    "errors": 0,
    "output_file": null
  }
}

Output Format

Two tables displayed inline (no CSV):

Table 1: Abandonment by Cart Value Bucket

Table 2: Abandonment by Hour of Day (UTC)

For format: json, by_cart_value is an array of {range, count, pct} objects; by_hour_utc is an array of {hour, count, pct} objects.

Note: Device type and geographic location are not available in the abandonedCheckouts API and are not reported by this skill.

Error Handling

Best Practices

1. For high-traffic stores, narrow the date range to 7–14 days for faster results; paginating 90 days of data can produce many API calls.
2. The default cart_value_buckets of [0,25,50,100,250] works for most stores — adjust thresholds to match your AOV distribution.
3. Hours are reported in UTC — convert to your store's local timezone before drawing conclusions about peak abandonment times.
4. Run this report weekly and compare the by-hour pattern to your promotional send times to find timing opportunities.
5. email is included in the query result — combine with the abandoned-cart-recovery skill to act on the customers most likely to convert based on their cart value tier.