Spencer Grimes
1e6881ba86
- Full Node.js application with Shopify GraphQL API integration - Compare At price support for promotional pricing - Comprehensive error handling and retry logic - Progress tracking with markdown logging - Complete test suite with unit and integration tests - Production-ready with proper exit codes and signal handling
288 lines
8.2 KiB
Markdown
288 lines
8.2 KiB
Markdown
# Shopify Price Updater
|
|
|
|
A Node.js script that bulk updates product prices in your Shopify store based on product tags using Shopify's GraphQL Admin API.
|
|
|
|
## Features
|
|
|
|
- **Tag-based filtering**: Update prices only for products with specific tags
|
|
- **Percentage-based adjustments**: Increase or decrease prices by a configurable percentage
|
|
- **Batch processing**: Handles large inventories with automatic pagination
|
|
- **Error resilience**: Continues processing even if individual products fail
|
|
- **Rate limit handling**: Automatic retry logic for API rate limits
|
|
- **Progress tracking**: Detailed logging to both console and Progress.md file
|
|
- **Environment-based configuration**: Secure credential management via .env file
|
|
|
|
## Prerequisites
|
|
|
|
- Node.js (version 14 or higher)
|
|
- A Shopify store with Admin API access
|
|
- Shopify Private App or Custom App with the following permissions:
|
|
- `read_products`
|
|
- `write_products`
|
|
|
|
## Installation
|
|
|
|
1. Clone or download this repository
|
|
2. Install dependencies:
|
|
```bash
|
|
npm install
|
|
```
|
|
3. Copy the environment template:
|
|
```bash
|
|
copy .env.example .env
|
|
```
|
|
4. Configure your environment variables (see Configuration section)
|
|
|
|
## Configuration
|
|
|
|
Edit the `.env` file with your Shopify store details:
|
|
|
|
```env
|
|
# Your Shopify store domain (without https://)
|
|
SHOPIFY_SHOP_DOMAIN=your-store.myshopify.com
|
|
|
|
# Your Shopify Admin API access token
|
|
SHOPIFY_ACCESS_TOKEN=shpat_your_access_token_here
|
|
|
|
# The product tag to filter by
|
|
TARGET_TAG=sale
|
|
|
|
# Price adjustment percentage (positive for increase, negative for decrease)
|
|
# Examples: 10 (increase by 10%), -15 (decrease by 15%), 5.5 (increase by 5.5%)
|
|
PRICE_ADJUSTMENT_PERCENTAGE=10
|
|
```
|
|
|
|
### Getting Your Shopify Credentials
|
|
|
|
#### For Private Apps (Recommended):
|
|
|
|
1. Go to your Shopify Admin → Apps → App and sales channel settings
|
|
2. Click "Develop apps" → "Create an app"
|
|
3. Configure Admin API access with `read_products` and `write_products` permissions
|
|
4. Install the app and copy the Admin API access token
|
|
|
|
#### For Custom Apps:
|
|
|
|
1. Go to your Shopify Admin → Settings → Apps and sales channels
|
|
2. Click "Develop apps" → "Create an app"
|
|
3. Configure the required API permissions
|
|
4. Generate and copy the access token
|
|
|
|
## Usage
|
|
|
|
### Basic Usage
|
|
|
|
Run the script with your configured environment:
|
|
|
|
```bash
|
|
npm start
|
|
```
|
|
|
|
or
|
|
|
|
```bash
|
|
node src/index.js
|
|
```
|
|
|
|
### Debug Mode
|
|
|
|
Before running the main script, you can use the debug mode to see what tags exist in your store and verify your target tag:
|
|
|
|
```bash
|
|
npm run debug-tags
|
|
```
|
|
|
|
This will:
|
|
|
|
- Show all products and their tags in your store
|
|
- Check if your target tag exists
|
|
- Suggest similar tags if exact match isn't found
|
|
- Help troubleshoot tag-related issues
|
|
|
|
### Example Scenarios
|
|
|
|
#### Increase prices by 10% for sale items:
|
|
|
|
```env
|
|
TARGET_TAG=sale
|
|
PRICE_ADJUSTMENT_PERCENTAGE=10
|
|
```
|
|
|
|
#### Decrease prices by 15% for clearance items:
|
|
|
|
```env
|
|
TARGET_TAG=clearance
|
|
PRICE_ADJUSTMENT_PERCENTAGE=-15
|
|
```
|
|
|
|
#### Apply a 5.5% increase to seasonal products:
|
|
|
|
```env
|
|
TARGET_TAG=seasonal
|
|
PRICE_ADJUSTMENT_PERCENTAGE=5.5
|
|
```
|
|
|
|
## Output and Logging
|
|
|
|
The script provides detailed feedback in two ways:
|
|
|
|
### Console Output
|
|
|
|
- Configuration summary at startup
|
|
- Real-time progress updates
|
|
- Product-by-product price changes
|
|
- Final summary with success/failure counts
|
|
|
|
### Progress.md File
|
|
|
|
- Persistent log of all operations
|
|
- Timestamps for each run
|
|
- Detailed error information for debugging
|
|
- Historical record of price changes
|
|
|
|
Example console output:
|
|
|
|
```
|
|
🚀 Starting Shopify Price Updater
|
|
📋 Configuration:
|
|
Store: your-store.myshopify.com
|
|
Tag: sale
|
|
Adjustment: +10%
|
|
|
|
🔍 Found 25 products with tag 'sale'
|
|
✅ Updated Product A: $19.99 → $21.99
|
|
✅ Updated Product B: $29.99 → $32.99
|
|
⚠️ Skipped Product C: Invalid price data
|
|
...
|
|
📊 Summary: 23 products updated, 2 skipped, 0 errors
|
|
```
|
|
|
|
## Error Handling
|
|
|
|
The script is designed to be resilient:
|
|
|
|
- **Rate Limits**: Automatically retries with exponential backoff
|
|
- **Network Issues**: Retries failed requests up to 3 times
|
|
- **Invalid Data**: Skips problematic products and continues
|
|
- **API Errors**: Logs errors and continues with remaining products
|
|
- **Missing Environment Variables**: Validates configuration before starting
|
|
|
|
## Testing
|
|
|
|
### Before Running on Production
|
|
|
|
1. **Test with a development store** or backup your data
|
|
2. **Start with a small subset** by using a specific tag with few products
|
|
3. **Verify the percentage calculation** with known product prices
|
|
4. **Check the Progress.md file** to ensure logging works correctly
|
|
|
|
### Recommended Testing Process
|
|
|
|
1. Create a test tag (e.g., "price-test") on a few products
|
|
2. Set `TARGET_TAG=price-test` in your .env
|
|
3. Run the script with a small percentage (e.g., 1%)
|
|
4. Verify the changes in your Shopify admin
|
|
5. Once satisfied, update your configuration for the actual run
|
|
|
|
## Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
**"Authentication failed"**
|
|
|
|
- Verify your `SHOPIFY_ACCESS_TOKEN` is correct
|
|
- Ensure your app has `read_products` and `write_products` permissions
|
|
|
|
**"No products found"**
|
|
|
|
- Run `npm run debug-tags` to see all available tags in your store
|
|
- Check that products actually have the specified tag
|
|
- Tag matching is case-sensitive
|
|
- Verify the tag format (some tags may have spaces, hyphens, or different capitalization)
|
|
|
|
**"Rate limit exceeded"**
|
|
|
|
- The script handles this automatically, but you can reduce load by processing smaller batches
|
|
|
|
**"Invalid percentage"**
|
|
|
|
- Ensure `PRICE_ADJUSTMENT_PERCENTAGE` is a valid number
|
|
- Use negative values for price decreases
|
|
|
|
### Debugging Steps
|
|
|
|
1. **Run the debug script first**: `npm run debug-tags` to see what tags exist in your store
|
|
2. **Check the Progress.md file** for detailed error information
|
|
3. **Verify your .env configuration** matches the required format
|
|
4. **Test with a small subset** of products first
|
|
5. **Ensure your Shopify app** has the necessary permissions
|
|
|
|
### Debug Scripts
|
|
|
|
The project includes debugging tools:
|
|
|
|
- `npm run debug-tags` - Analyze all product tags in your store
|
|
- `debug-tags.js` - Standalone script to check tag availability and troubleshoot tag-related issues
|
|
|
|
## Security Notes
|
|
|
|
- Never commit your `.env` file to version control
|
|
- Use environment-specific access tokens
|
|
- Regularly rotate your API credentials
|
|
- Test changes in a development environment first
|
|
|
|
## File Structure
|
|
|
|
```
|
|
shopify-price-updater/
|
|
├── src/
|
|
│ ├── config/
|
|
│ │ └── environment.js # Environment configuration
|
|
│ ├── services/
|
|
│ │ ├── shopify.js # Shopify API client
|
|
│ │ ├── product.js # Product operations
|
|
│ │ └── progress.js # Progress logging
|
|
│ ├── utils/
|
|
│ │ ├── price.js # Price calculations
|
|
│ │ └── logger.js # Logging utilities
|
|
│ └── index.js # Main entry point
|
|
├── tests/ # Unit tests for the application
|
|
├── debug-tags.js # Debug script to analyze store tags
|
|
├── .env # Your configuration (create from .env.example)
|
|
├── .env.example # Configuration template
|
|
├── package.json # Dependencies and scripts
|
|
├── Progress.md # Generated progress log
|
|
└── README.md # This file
|
|
```
|
|
|
|
## Technical Details
|
|
|
|
### API Implementation
|
|
|
|
- Uses Shopify's GraphQL Admin API (version 2024-01)
|
|
- Implements `productVariantsBulkUpdate` mutation for price updates
|
|
- Built-in HTTPS client using Node.js native modules (no external HTTP dependencies)
|
|
- Automatic tag formatting (handles both "tag" and "tag:tagname" formats)
|
|
|
|
### Rate Limiting
|
|
|
|
- Implements exponential backoff for rate limit handling
|
|
- Maximum 3 retry attempts with increasing delays (1s, 2s, 4s)
|
|
- Respects Shopify's API rate limits automatically
|
|
|
|
### Error Recovery
|
|
|
|
- Continues processing even if individual products fail
|
|
- Comprehensive error categorization and reporting
|
|
- Non-retryable errors are identified and logged appropriately
|
|
|
|
## Available Scripts
|
|
|
|
- `npm start` - Run the main price update script
|
|
- `npm run debug-tags` - Analyze all product tags in your store
|
|
- `npm test` - Run the test suite (if implemented)
|
|
|
|
## License
|
|
|
|
This project is provided as-is for educational and commercial use. Please test thoroughly before using in production environments.
|