Shopify Admin Discount Cost Trend

Purpose

Tracks how much money the store gave away in discounts over time, bucketed by week, month, or quarter, and broken down by discount code and discount type (percentage / fixed amount / free shipping / automatic). Answers: "is our discount spend trending up or down, and which campaigns are driving it?" Read-only — no mutations. Complements discount-roi-calculator (per-discount return) with a longitudinal view of total cost.

Prerequisites

• Authenticated Shopify CLI session: shopify store auth --store --scopes read_orders
• API scopes: read_orders

Parameters

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | store | string | yes | — | Store domain (e.g., mystore.myshopify.com) | | period | string | no | month | Bucket size: week, month, or quarter | | periodsback | integer | no | 12 | Number of buckets to report | | topcodes | integer | no | 10 | Top discount codes to break out individually; remainder grouped as other | | includeshippingdiscounts | bool | no | true | Whether to count shipping discounts in the totals | | format | string | no | human | Output format: human or json |

Safety

> ℹ️ Read-only skill — no mutations are executed. Safe to run at any time.

Workflow Steps

1. Compute window from period × periods_back (e.g., month × 12 → last 12 calendar months starting from the first day of the bucket 11 months ago)

1. OPERATION: orders — query

Inputs: query: "created_at:>='' financial_status:paid", first: 250, select createdAt, discountCodes, currentTotalDiscountsSet, totalDiscountsSet, cartDiscountAmountSet, discountApplications { allocationMethod, targetType, value, ... on DiscountCodeApplication { code }, ... on AutomaticDiscountApplication { title }, ... on ManualDiscountApplication { title } }, shippingLines { discountAllocations { allocatedAmountSet } }, pagination cursor Expected output: All paid orders in the window with discount data; paginate until hasNextPage: false

1. For each order, attribute discount cost:

• cart_discount = currentTotalDiscountsSet.shopMoney.amount
• shipping_discount = sum of shippingLines.discountAllocations.allocatedAmountSet (only if include_shipping_discounts: true)
• total_discount = cartdiscount + shippingdiscount
• Attribute by code: prefer first discountApplications.code for code discounts, title for automatic / manual

1. Bucket each order into its period (week-of-year, year-month, or year-quarter) and aggregate:

• Total discount cost per bucket
• Per discount code per bucket
• Per discount type per bucket (percentage, fixed_amount, shipping, automatic)

1. Identify top codes by total cost across the window; aggregate the rest as other

GraphQL Operations

# orders:query — validated against api_version 2025-01
query DiscountCostTrend($query: String!, $after: String) {
  orders(first: 250, after: $after, query: $query) {
    edges {
      node {
        id
        name
        createdAt
        discountCodes
        currentTotalDiscountsSet { shopMoney { amount currencyCode } }
        totalDiscountsSet { shopMoney { amount currencyCode } }
        cartDiscountAmountSet { shopMoney { amount currencyCode } }
        discountApplications(first: 10) {
          edges {
            node {
              allocationMethod
              targetType
              targetSelection
              value {
                ... on PricingPercentageValue { percentage }
                ... on MoneyV2 { amount currencyCode }
              }
              ... on DiscountCodeApplication { code }
              ... on AutomaticDiscountApplication { title }
              ... on ManualDiscountApplication { title description }
            }
          }
        }
        shippingLines(first: 5) {
          edges {
            node {
              title
              discountAllocations {
                allocatedAmountSet { shopMoney { amount currencyCode } }
              }
            }
          }
        }
      }
    }
    pageInfo { hasNextPage endCursor }
  }
}

Session Tracking

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

On start, emit:

╔══════════════════════════════════════════════╗
║  SKILL: Discount Cost Trend                  ║
║  Store:                        ║
║  Period:  ×            ║
║  Started:              ║
╚══════════════════════════════════════════════╝

After each step, emit:

[N/TOTAL]   
          → Params: 
          → Result: 

On completion, emit:

For format: human (default):

══════════════════════════════════════════════
DISCOUNT COST TREND  (last  s)
  Total discount cost:    $
  Avg per :        $
  Latest :         $   (% vs prior)

  By bucket:
    2025-Q1  $   (cart $ / shipping $)
    2025-Q2  $   (cart $ / shipping $)

  By discount type:
    code            $   (%)
    automatic       $   (%)
    manual          $   (%)
    shipping        $   (%)

  Top codes (by total cost):
    ""        $   (%)
    ""        $   (%)
    other           $   (%)

  Output: discount_cost_trend_.csv
══════════════════════════════════════════════

For format: json, emit:

{
  "skill": "discount-cost-trend",
  "store": "",
  "period": "month",
  "periods_back": 12,
  "total_discount_cost": 0,
  "by_bucket": [],
  "by_type": { "code": 0, "automatic": 0, "manual": 0, "shipping": 0 },
  "top_codes": [],
  "currency": "USD",
  "output_file": "discount_cost_trend_.csv"
}

Output Format

CSV file discount_cost_trend_.csv with columns: bucket, discount_code_or_title, discount_type, orders_count, cart_discount, shipping_discount, total_discount, currency

Error Handling

| Error | Cause | Recovery | |-------|-------|----------| | THROTTLED | API rate limit exceeded | Wait 2 seconds, retry up to 3 times | | Stacked discount codes | Multiple codes on one order | Attribute proportionally to each code by their value share, or label as multi-code if equal | | Manual discount with no title | Cashier-entered with empty title | Group as manual:untitled | | Multi-currency orders | Presentment currency != shop currency | Sum on shopMoney.amount (shop currency) for consistency |

Best Practices

• Use period: week for promotional businesses with frequent campaigns; period: month for stores with steady evergreen offers; period: quarter for board reporting.
• A flat or rising trend with no campaign activity often points to automatic discount creep — review automatic discounts that have no end date.
• Cross-reference the latest bucket against discount-roi-calculator to verify the cost increase is producing matching incremental revenue.
• Set include_shipping_discounts: false if your accounting books shipping subsidy separately from product discounts.
• Set up monthly automation: discount spend that drifts above budget should trigger a finance review before it shows up in margin reports.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: 40RTY-ai
• Source: 40RTY-ai/shopify-admin-skills
• License: MIT
• Homepage: http://skills.40rty.ai

Install and usage instructions live in the source repository linked above.