PriceUpdaterAppv2/README.md

# 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%)
# Note: Only used in "update" mode, ignored in "rollback" mode
PRICE_ADJUSTMENT_PERCENTAGE=10

# Operation mode - determines whether to update prices or rollback to compare-at prices
# Options: "update" (default) or "rollback"
# When not specified, defaults to "update" for backward compatibility
OPERATION_MODE=update
```

### Operation Mode Configuration

The `OPERATION_MODE` environment variable controls the application behavior:

- **`update` (default)**: Performs price adjustments using `PRICE_ADJUSTMENT_PERCENTAGE`
- **`rollback`**: Sets prices to compare-at price values and removes compare-at prices

When `OPERATION_MODE` is not specified, the application defaults to `update` mode for backward compatibility.

### 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
```

### Operation Modes

The application supports two operation modes:

#### Update Mode (Default)

Adjusts product prices by a percentage:

```bash
npm run update
```

This performs the standard price adjustment functionality using the `PRICE_ADJUSTMENT_PERCENTAGE` setting.

#### Rollback Mode

Reverts prices by setting the main price to the compare-at price and removing the compare-at price:

```bash
npm run rollback
```

This is useful for reverting promotional pricing back to original prices. Products without compare-at prices will be skipped.

**Operation Mode Indicators:**

- The console output clearly displays which operation mode is active
- Progress.md logs distinguish between "Price Update Operation" and "Price Rollback Operation"
- Configuration summary shows the operation mode being used

### 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 price updater (defaults to update mode for backward compatibility)
- `npm run update` - Run the price update script (explicitly set to update mode)
- `npm run rollback` - Run the price rollback script (set prices to compare-at prices)
- `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.