{"id":30947521,"url":"https://github.com/eshaffer321/walmart-client-go","last_synced_at":"2026-05-26T02:33:14.268Z","repository":{"id":313704764,"uuid":"1052340111","full_name":"eshaffer321/walmart-client-go","owner":"eshaffer321","description":"Go client for walmart order history","archived":false,"fork":false,"pushed_at":"2025-12-22T21:30:09.000Z","size":4705,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-24T10:38:42.522Z","etag":null,"topics":["client","go","history","orders","walmart"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/eshaffer321.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-07T22:20:39.000Z","updated_at":"2025-12-22T21:29:53.000Z","dependencies_parsed_at":"2025-09-08T00:21:45.437Z","dependency_job_id":"ba8f3d7d-f464-421b-b434-c6b93f27eb56","html_url":"https://github.com/eshaffer321/walmart-client-go","commit_stats":null,"previous_names":["eshaffer321/walmart-client-go"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/eshaffer321/walmart-client-go","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eshaffer321%2Fwalmart-client-go","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eshaffer321%2Fwalmart-client-go/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eshaffer321%2Fwalmart-client-go/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eshaffer321%2Fwalmart-client-go/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/eshaffer321","download_url":"https://codeload.github.com/eshaffer321/walmart-client-go/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eshaffer321%2Fwalmart-client-go/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33501583,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-25T14:31:05.219Z","status":"online","status_checked_at":"2026-05-26T02:00:06.821Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["client","go","history","orders","walmart"],"created_at":"2025-09-11T01:46:51.362Z","updated_at":"2026-05-26T02:33:14.245Z","avatar_url":"https://github.com/eshaffer321.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Walmart API Client\n\n[![CI](https://github.com/eshaffer321/walmart-client-go/actions/workflows/ci.yml/badge.svg)](https://github.com/eshaffer321/walmart-client-go/actions/workflows/ci.yml)\n[![codecov](https://codecov.io/gh/eshaffer321/walmart-client-go/branch/main/graph/badge.svg)](https://codecov.io/gh/eshaffer321/walmart-client-go)\n[![Go Report Card](https://goreportcard.com/badge/github.com/eshaffer321/walmart-client)](https://goreportcard.com/report/github.com/eshaffer321/walmart-client)\n[![Go Reference](https://pkg.go.dev/badge/github.com/eshaffer321/walmart-client.svg)](https://pkg.go.dev/github.com/eshaffer321/walmart-client)\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n\nA robust Go library and CLI for accessing Walmart order history and purchase data through their GraphQL API.\n\nAvailable as both a **Go library** for programmatic access and a **CLI tool** for command-line usage.\n\n## Features\n\n- 🛒 Fetch complete order history (both in-store and delivery orders)\n- 📦 Get detailed order information including items, prices, tax, and totals\n- 💰 Driver tip tracking for delivery orders - see actual amount charged\n- 💳 **NEW:** Order ledger API for payment tracking - match orders to bank transactions\n- 🔍 Search orders for specific items\n- 📄 Pagination support for large order histories\n- 🍪 Automatic cookie management with rotation to prevent staleness\n- 💾 Persistent cookie storage in `~/.walmart-api/cookies.json`\n\n## Installation\n\n### As a Go Library\n```bash\ngo get github.com/eshaffer321/walmart-client\n```\n\n### As a CLI Tool\n```bash\n# Clone and build\ngit clone https://github.com/eshaffer321/walmart-client-go\ncd walmart-client-go\ngo build -o walmart-cli ./cmd/walmart\n\n# Or install directly\ngo install github.com/eshaffer321/walmart-client/cmd/walmart@latest\n```\n\n## Library Usage (Go SDK)\n\n### Quick Start\n```go\npackage main\n\nimport (\n    \"encoding/json\"\n    \"fmt\"\n    \"time\"\n    \n    walmart \"github.com/eshaffer321/walmart-client\"\n)\n\nfunc main() {\n    // Initialize client\n    config := walmart.ClientConfig{\n        RateLimit: 2 * time.Second,\n        AutoSave:  true,\n    }\n    \n    client, err := walmart.NewWalmartClient(config)\n    if err != nil {\n        panic(err)\n    }\n    \n    // Initialize from curl file (one-time setup)\n    err = client.InitializeFromCurl(\"curl.txt\")\n    if err != nil {\n        panic(err)\n    }\n    \n    // Get recent orders as Go structs\n    orders, err := client.GetRecentOrders(10)\n    if err != nil {\n        panic(err)\n    }\n    \n    // Access data programmatically\n    for _, order := range orders {\n        fmt.Printf(\"Order %s: %d items\\n\", order.OrderID, order.ItemCount)\n    }\n    \n    // Get full order details\n    if len(orders) \u003e 0 {\n        order, err := client.GetOrder(orders[0].OrderID, true)\n        if err != nil {\n            panic(err)\n        }\n        \n        // Access as structured data\n        fmt.Printf(\"Total: %.2f\\n\", order.PriceDetails.GrandTotal.Value)\n        fmt.Printf(\"Tax: %.2f\\n\", order.PriceDetails.TaxTotal.Value)\n        \n        // Or convert to JSON\n        jsonData, _ := json.MarshalIndent(order, \"\", \"  \")\n        fmt.Println(string(jsonData))\n    }\n}\n```\n\n### Logging\n\nThe client supports optional logger injection using Go's standard `log/slog` package for structured logging:\n\n```go\nimport (\n    \"log/slog\"\n    \"os\"\n    walmart \"github.com/eshaffer321/walmart-client\"\n)\n\n// Create a structured logger (JSON format)\nlogger := slog.New(slog.NewJSONHandler(os.Stdout, nil))\n\n// Pass logger to client\nconfig := walmart.ClientConfig{\n    RateLimit: 2 * time.Second,\n    Logger:    logger, // Optional - pass nil to disable logging\n}\n\nclient, err := walmart.NewWalmartClient(config)\n```\n\n**Logging Modes:**\n\n```go\n// JSON structured logging (recommended for production)\nlogger := slog.New(slog.NewJSONHandler(os.Stdout, nil))\n\n// Text logging (human-readable, good for development)\nlogger := slog.New(slog.NewTextHandler(os.Stdout, nil))\n\n// No logging (silent mode)\nconfig := walmart.ClientConfig{\n    Logger: nil, // All logs will be discarded\n}\n```\n\n**What Gets Logged:**\n\nAll logs use structured key=value pairs for easy parsing and filtering:\n\n```json\n{\"time\":\"2025-09-07T10:30:00Z\",\"level\":\"INFO\",\"msg\":\"cookie store initialized\",\"client\":\"walmart\",\"file_path\":\"~/.walmart-api/cookies.json\",\"cookies_loaded\":61}\n{\"time\":\"2025-09-07T10:30:01Z\",\"level\":\"INFO\",\"msg\":\"fetching purchase history\",\"client\":\"walmart\",\"limit\":10}\n{\"time\":\"2025-09-07T10:30:02Z\",\"level\":\"INFO\",\"msg\":\"fetched purchase history\",\"client\":\"walmart\",\"order_count\":10}\n{\"time\":\"2025-09-07T10:30:03Z\",\"level\":\"INFO\",\"msg\":\"fetched order\",\"client\":\"walmart\",\"order_id\":\"123\",\"total\":185.83,\"item_count\":15}\n```\n\n**Log Levels:**\n- `INFO`: Normal operations (fetching orders, cookie updates, successful operations)\n- `WARN`: Recoverable issues (rate limits, stale cookies, missing data)\n- `ERROR`: Failures (network errors, auth failures, parse errors)\n- `DEBUG`: Detailed trace information (request/response details)\n\nAll logs automatically include `client=walmart` attribute for filtering in multi-service environments.\n\n### Available Methods\n```go\n// Order operations\nclient.GetOrder(orderID string, isInStore bool) (*Order, error)\nclient.GetOrderAutoDetect(orderID string) (*Order, error)\nclient.GetDeliveryOrderWithTip(orderID string) (*Order, error) // Ensures tip info is included\nclient.GetOrderLedger(orderID string) (*OrderLedger, error)    // NEW: Get payment ledger for bank reconciliation\n\n// Purchase history\nclient.GetRecentOrders(limit int) ([]OrderSummary, error)\nclient.GetAllOrders(maxPages int) ([]OrderSummary, error)\nclient.SearchOrders(searchTerm string, limit int) ([]OrderSummary, error)\nclient.GetOrdersByType(orderType string, limit int) ([]OrderSummary, error)\n\n// Cookie management\nclient.InitializeFromCurl(curlFile string) error\nclient.Status() // Print status\nclient.RefreshFromBrowser() error\n\n// Helper methods for JSON output\nclient.GetOrdersAsJSON(limit int) (string, error)\nclient.GetOrderAsJSON(orderID string, isInStore bool) (string, error)\n```\n\n### Data Structures\nAll responses return strongly-typed Go structs with JSON tags:\n\n```go\ntype Order struct {\n    ID             string               `json:\"id\"`\n    OrderDate      string               `json:\"orderDate\"`\n    DisplayID      string               `json:\"displayId\"`\n    Groups         []OrderGroup         `json:\"groups_2101\"`\n    PriceDetails   *OrderPriceDetails   `json:\"priceDetails\"`\n    PaymentMethods []OrderPaymentMethod `json:\"paymentMethods\"`\n    // ... more fields\n}\n\ntype OrderPriceDetails struct {\n    SubTotal     *PriceLineItem  `json:\"subTotal\"`\n    TaxTotal     *PriceLineItem  `json:\"taxTotal\"`\n    GrandTotal   *PriceLineItem  `json:\"grandTotal\"`\n    DriverTip    *PriceLineItem  `json:\"driverTip\"`    // NEW: Driver tip for delivery\n    TotalWithTip *PriceLineItem  `json:\"totalWithTip\"` // NEW: Total including tip\n    Savings      *PriceLineItem  `json:\"savings\"`\n    Fees         []PriceLineItem `json:\"fees\"`         // NEW: Additional fees\n}\n```\n\n### Working with Delivery Orders and Tips\n\nFor delivery orders, the client now tracks driver tips to match the actual card charge:\n\n```go\n// Fetch a delivery order with tip information\norder, err := client.GetDeliveryOrderWithTip(\"200013441152420\")\nif err != nil {\n    log.Fatal(err)\n}\n\n// Access pricing with tip\nif order.PriceDetails != nil {\n    fmt.Printf(\"Subtotal: $%.2f\\n\", order.PriceDetails.SubTotal.Value)\n    fmt.Printf(\"Tax: $%.2f\\n\", order.PriceDetails.TaxTotal.Value)\n    fmt.Printf(\"Grand Total: $%.2f\\n\", order.PriceDetails.GrandTotal.Value)\n\n    // Driver tip (if available in API response)\n    if order.PriceDetails.DriverTip != nil {\n        fmt.Printf(\"Driver Tip: $%.2f\\n\", order.PriceDetails.DriverTip.Value)\n    }\n\n    // Total including tip (calculated automatically)\n    if order.PriceDetails.TotalWithTip != nil {\n        fmt.Printf(\"Total with Tip: $%.2f\\n\", order.PriceDetails.TotalWithTip.Value)\n        fmt.Println(\"This should match your credit card charge\")\n    }\n}\n\n// Check if an order is a delivery order\nif order.IsDeliveryOrder() {\n    fmt.Println(\"This is a delivery order\")\n}\n```\n\n### Payment Ledger and Bank Reconciliation\n\nThe order ledger API provides detailed payment information showing actual credit card charges, which is essential for matching Walmart orders to bank transactions when orders have been modified or split:\n\n```go\n// Get payment ledger for an order\nledger, err := client.GetOrderLedger(\"200013509224581\")\nif err != nil {\n    log.Fatal(err)\n}\n\n// Display payment breakdown\nfmt.Printf(\"Order #%s Payment Details:\\n\", ledger.OrderID)\n\nfor _, pm := range ledger.PaymentMethods {\n    if pm.PaymentType == \"CREDITCARD\" {\n        fmt.Printf(\"\\n%s ending in %s:\\n\", pm.CardType, pm.LastFour)\n\n        // Show individual charges (may be split)\n        for i, charge := range pm.FinalCharges {\n            fmt.Printf(\"  Charge %d: $%.2f\\n\", i+1, charge)\n        }\n\n        fmt.Printf(\"  Total: $%.2f\\n\", pm.TotalCharged)\n    } else if pm.PaymentType == \"GIFTCARD\" {\n        fmt.Printf(\"\\nWalmart Cash: $%.2f\\n\", pm.TotalCharged)\n    }\n}\n```\n\n**Why use the Order Ledger?**\n\nWhen Walmart modifies an order (item adjustments, substitutions, etc.), the charges to your credit card may be split into multiple transactions. For example:\n- Order total shows: $185.83\n- But your bank shows: $178.96 and $4.12 (two separate charges)\n- Plus Walmart Cash: $2.75\n\nThe order ledger provides these actual charge amounts, making it possible to accurately match orders to bank transactions for accounting and reconciliation purposes.\n\n## CLI Usage\n\n### Setup\n\n1. **Get your cookies from Walmart.com:**\n   - Log into walmart.com in Chrome/Firefox\n   - Go to your orders page\n   - Open DevTools (F12) → Network tab\n   - Refresh the page\n   - Find any 'getOrder' request\n   - Right-click → Copy → Copy as cURL\n   - Save to a file (e.g., `curl.txt`)\n\n2. **Initialize the CLI:**\n```bash\n./walmart-cli -init curl.txt\n```\n\nThis saves your cookies to `~/.walmart-api/cookies.json` for future use.\n\n### CLI Commands\n\n#### View Recent Orders\n```bash\n./walmart-cli -history\n\n# Output:\n# === Order History (10 orders) ===\n# \n# 1. Order #18420337004257359578\n#    Type: IN_STORE | Status: IN_STORE\n#    Date: Sep 05, 2025 purchase\n#    Store: MERIDIAN Supercenter\n#    Items (3):\n#      - Great Value Cracker Cut Sliced 4 Cheese Tray, 16 oz (qty: 1)\n#      ...\n```\n\n#### Search Orders\n```bash\n./walmart-cli -search \"cheese\"\n```\n\n#### Get Order Details\n```bash\n./walmart-cli -order 18420337004257359578\n\n# Output:\n# === Order Details ===\n# Order ID:     18420337004257359578\n# Display ID:   1842-0337-0042-5735-9578\n# Date:         Sep 5, 2025 at 4:16 PM\n# \n# Items (3):\n#   1. Great Value Cracker Cut Sliced 4 Cheese Tray, 16 oz\n#      Item #814783251\n#      Qty: 1 = $4.98\n#   ...\n# \n# === Price Summary ===\n# Subtotal:     $7.14\n# Tax:          $0.43\n# Total:        $7.57\n# \n# === Payment ===\n# Visa ending in 0953\n```\n\n#### List All Orders (with pagination)\n```bash\n./walmart-cli -list-all\n```\n\n#### Check Cookie Status\n```bash\n./walmart-cli -status\n\n# Output:\n# === Cookie Store Status ===\n# Total cookies: 61\n# Cookie file: /Users/you/.walmart-api/cookies.json\n# Essential cookies: 6\n# \n# Essential cookies:\n#   ✅ CID: 2m30s ago\n#   ✅ SPID: 2m30s ago\n#   ✅ auth: 2m30s ago\n#   ✅ customer: 2m30s ago\n```\n\n#### Refresh Cookies\n```bash\n./walmart-cli -refresh\n# Follow prompts to update cookies from browser\n```\n\n## How It Works\n\n### Authentication\n- Uses 61 cookies from your browser session\n- **CID** and **SPID** are the essential auth cookies\n- However, ALL 61 cookies are required to avoid bot detection (429/418 errors)\n- 19 cookies automatically update with each request to prevent staleness\n\n### API Endpoints\n\n1. **Purchase History** (`PurchaseHistoryV2`)\n   - Hash: `2c3d5a832b56671dca1ed0ec84940f274d0bc80821db4ad7481e496c0ad5847e`\n   - Returns all order types (IN_STORE, DELIVERY, PICKUP)\n   - Supports pagination with cursor\n   - Filtering by date range, order type, search terms\n\n2. **Order Details** (`getOrder`)\n   - Hash: `d0622497daef19150438d07c506739d451cad6749cf45c3b4db95f2f5a0a65c4`\n   - Returns complete order information\n   - Automatically detects if order is IN_STORE or DELIVERY\n\n### Data Available\n\nEach order includes:\n- ✅ Order ID, date, and display ID\n- ✅ Complete item list with names, quantities, and item IDs\n- ✅ Individual item prices\n- ✅ Subtotal, tax, and total amounts\n- ✅ **Driver tips for delivery orders (when available)**\n- ✅ **Total with tip - matches actual card charge**\n- ✅ Payment method information\n- ✅ Store information (for in-store purchases)\n- ✅ Delivery details (for online orders)\n\n## File Structure\n\n```\nwalmart-client/\n├── client.go            # Main client with cookie management\n├── models.go            # Data structures for orders\n├── purchase_history.go  # Purchase history API methods\n├── example_usage.go     # Library usage examples\n├── example_json.go      # JSON conversion helpers\n├── cmd/\n│   └── walmart/\n│       └── main.go      # CLI interface\n└── example/\n    └── main.go          # Example usage\n```\n\n## Cookie Storage\n\nCookies are stored in `~/.walmart-api/cookies.json` with metadata:\n```json\n{\n  \"cookies\": {\n    \"CID\": {\n      \"value\": \"...\",\n      \"last_update\": \"2025-09-07T08:40:57Z\",\n      \"source\": \"curl\",\n      \"essential\": true\n    },\n    ...\n  },\n  \"last_update\": \"2025-09-07T08:40:57Z\"\n}\n```\n\n## Technical Details\n\n### Rate Limiting\n- Built-in 2-second delay between requests\n- Automatic cookie updates to prevent staleness\n- Proper error handling for rate limits (429) and bot detection (418)\n\n### GraphQL Persisted Queries\nWalmart uses persisted queries where the query is stored server-side and referenced by hash:\n- Each operation type has a unique hash\n- Client sends hash + variables instead of full query\n- Reduces bandwidth and hides query complexity\n\n### Order Types\n- **IN_STORE**: Physical store purchases (`orderIsInStore: true`)\n- **DELIVERY**: Online orders delivered to home (`orderIsInStore: false`)\n- **PICKUP**: Online orders picked up at store\n\n## Notes\n\n- This is for personal use only - be respectful of Walmart's servers\n- Cookies expire after some time - refresh from browser when needed\n- Rate limiting is enforced to avoid detection\n- All 61 cookies are required despite only 2 containing auth data\n\n## License\n\nFor personal use only. This tool is designed for accessing your own order history.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feshaffer321%2Fwalmart-client-go","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feshaffer321%2Fwalmart-client-go","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feshaffer321%2Fwalmart-client-go/lists"}