Initial commit: Complete Shopify Price Updater implementation
- 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
This commit is contained in:
287
README.md
Normal file
287
README.md
Normal file
@@ -0,0 +1,287 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user