SKUs, case sensitivity, Integrations and Onboarding

The Golden Rule

Always maintain exact SKU case consistency between our system and the client's ecommerce platform.

Even though our excise tax system treats SKUs case-insensitively internally, ecommerce integrations require exact matching for product sync, webhooks, and API operations to work properly.

How Our System Works

Our platform normalizes SKUs internally for tax calculations:

• sku123 = SKU123 = Sku123 (all treated as identical for lookups)
• Historical product data is retrieved correctly regardless of case
• Tax calculations work with any case variation

However, we preserve the original case for:

• Product sync with ecommerce platforms
• Webhook payloads sent to integrators
• API responses and reports

How Ecommerce Platforms Work

Shopify: STRICTLY Case-Sensitive ⚠️

Shopify treats SKUs as completely different products if the case doesn't match:

Shopify Product Database:
- SKU: "BlueDream-30mL" → Product ID: 12345

API Lookup with "bluedream-30ml" → NOT FOUND
API Lookup with "BlueDream-30mL" → SUCCESS

Impact: If your bulk upload uses different casing than Shopify, product sync will fail completely.

WooCommerce: Usually Case-Insensitive ✓

WooCommerce typically treats SKUs case-insensitively by default:

• sku123 and SKU123 would match the same product

However, maintaining exact case is still critical because:

• Custom database configurations may change this behavior
• Third-party plugins may expect exact matches
• Future migrations or integrations may be case-sensitive
• Data quality and consistency are important

BigCommerce: Best Practice is Exact Match

While BigCommerce's core behavior varies, many integrations and features expect exact case matching.

Critical Requirements for Bulk Uploads

❌ WRONG - High Risk of Sync Failure

Scenario: Client sends product list, you "clean it up"

Client's Shopify Store:
- BlueDream-30mL
- JUUL-Mint-5%
- strawberry-ice

Your Spreadsheet (normalized to lowercase):
- bluedream-30ml
- juul-mint-5%
- strawberry-ice

Result: Product sync FAILS for all three products

✅ CORRECT - Sync Works Perfectly

Scenario: You preserve exact casing from client's ecommerce platform

Client's Shopify Store:
- BlueDream-30mL
- JUUL-Mint-5%
- strawberry-ice

Your Spreadsheet (exact match):
- BlueDream-30mL
- JUUL-Mint-5%
- strawberry-ice

Result: Product sync SUCCESS

Step-by-Step: Safe Bulk Upload Process

1. Obtain SKU List from Source System

DO:

• Export SKU list directly from client's ecommerce admin panel
• Request CSV/Excel export from the platform
• Use copy-paste from authenticated platform views

DON'T:

• Accept manually typed SKU lists from clients
• Use SKUs from screenshots or PDFs
• Rely on verbal descriptions of SKUs

2. Preserve Original Casing

DO:

• Copy SKUs exactly as they appear in the platform
• Use formulas like =A1 (not =UPPER(A1) or =LOWER(A1))
• Keep all special characters, spaces, and punctuation unchanged

DON'T:

• Apply "UPPER()" or "LOWER()" functions to clean data
• Manually retype SKUs
• "Fix" SKUs that look inconsistent (e.g., "sku123" vs "SKU456")
• Use Excel's auto-correct features

3. Verify Before Upload

Before uploading your spreadsheet:

✓ Compare first 10 SKUs character-by-character with platform
✓ Check for any auto-corrections Excel may have applied
✓ Verify special characters are preserved (-, _, /, etc.)
✓ Confirm no leading/trailing spaces were added

4. Document Data Source

In your onboarding notes, record:

• Where SKUs came from (e.g., "Exported from Shopify admin 2025-10-09")
• Who provided the data
• Any transformations applied (ideally: none)

Common Pitfalls to Avoid

Troubleshooting Failed Product Syncs

Problem: "Products not syncing after bulk upload"

First Check: SKU Case Mismatch

1. Export current SKUs from client's ecommerce platform
2. Compare with SKUs in our system (check character-by-character)
3. Look for case differences:
   • BlueDream vs bluedream
   • JUUL-MINT vs juul-mint
   • StrawberryIce vs strawberryice

Solution: Re-upload with exact case matching

How to Check in Our System:

• Product webhooks show SKU exactly as stored
• API responses return original case
• If sync fails, case mismatch is likely culprit

Exception: When Case Doesn't Matter

Case consistency is less critical for:

• Internal tax calculations (our system normalizes)
• Historical product data lookups (case-insensitive search)
• Manual reports and exports (but still good practice)

Case consistency is absolutely critical for:

• Shopify integration (case-sensitive matching required)
• Product sync operations (must match ecommerce platform exactly)
• Webhook payloads to third-party systems
• API-based product updates

Best Practices Summary

1. Always export SKUs directly from the client's ecommerce platform
2. Never transform case during data preparation
3. Copy-paste, don't retype SKU data whenever possible
4. Verify first 10 SKUs before bulk upload
5. Document data source in onboarding notes
6. Test product sync immediately after upload
7. When in doubt, match the platform exactly

Real-World Example

Client: Vape shop using Shopify Products: 500 SKUs Issue: Product sync failing for 342 products after bulk upload

Root Cause:

• Shopify SKUs: Mixed case (BlueDream-30mL, JUUL-Mint, strawberry-ice)
• Uploaded SKUs: All lowercase (ops team "standardized" them)
• Result: 342 products with uppercase characters failed to sync

Resolution:

• Re-exported SKUs from Shopify preserving exact case
• Re-uploaded with no transformations
• All 500 products synced successfully

Time Lost: 4 hours of troubleshooting + client escalation

Prevention: Follow this guide's bulk upload process

Remember: When it comes to SKUs, exact case matching = zero sync problems.