Shop Management

Overview

Before managing listings, you need to interact with your shop. This chapter covers:

The Shop Object

An Etsy shop contains metadata about your store:

{
    "shop_id": 12345678,
    "shop_name": "YourShopName",
    "user_id": 87654321,
    "title": "Your Shop Title",
    "currency_code": "USD",
    "url": "https://www.etsy.com/shop/YourShopName",
    "listing_active_count": 150,
    "digital_listing_count": 150,
    "sale_message": "Thanks for your purchase!",
    "is_vacation": false,
    "vacation_message": null,
    "accepts_custom_requests": true
}

For digital product shops, notice digital_listing_count—this helps you confirm all your listings are properly marked as digital.

Getting Your Shop Information

Find Shop by User

When authenticated, retrieve your shop:

from client import EtsyClient

client = EtsyClient()
shop = client.get("/application/shops")
print(f"Shop ID: {shop['results'][0]['shop_id']}")
print(f"Active listings: {shop['results'][0]['listing_active_count']}")

Get Shop by ID

If you know your shop ID:

shop_id = 12345678
shop = client.get(f"/application/shops/{shop_id}")

This returns detailed information including shop policies, announcement, and more.

Shop Sections (Categories)

Shop sections help organize your products. For digital sellers, you might have sections like:

Listing All Sections

sections = client.get(f"/application/shops/{shop_id}/sections")
for section in sections["results"]:
    print(f"{section['title']}: {section['active_listing_count']} listings")

Creating a New Section

new_section = client.post(
    f"/application/shops/{shop_id}/sections",
    data={"title": "New Templates"}
)
print(f"Created section ID: {new_section['shop_section_id']}")

Updating a Section

client.put(
    f"/application/shops/{shop_id}/sections/{section_id}",
    data={"title": "Updated Section Name"}
)

Practical Example: Shop Health Check

Here’s a useful script that checks your shop’s status. Full code in code/shop.py.

def shop_health_check(client, shop_id):
    shop = client.get(f"/application/shops/{shop_id}")
    
    print(f"Shop: {shop['shop_name']}")
    print(f"Active Listings: {shop['listing_active_count']}")
    print(f"Digital Listings: {shop['digital_listing_count']}")
    
    if shop['is_vacation']:
        print("⚠️  Shop is in vacation mode!")
    
    # Check for non-digital listings
    physical = shop['listing_active_count'] - shop['digital_listing_count']
    if physical > 0:
        print(f"⚠️  {physical} listings are not marked as digital")

Shop Policies for Digital Products

Digital products have specific policy considerations:

No Returns Policy

Most digital sellers have a “no returns” policy since digital files can’t be returned. Check your policies via API:

policies = client.get(f"/application/shops/{shop_id}/policies")
print(f"Return Policy: {policies['policy_return']}")

Download Instructions

Your sale message (sent after purchase) should include download instructions:

# Update sale message
client.put(
    f"/application/shops/{shop_id}",
    data={
        "sale_message": "Thank you! Your files are ready to download. "
                       "Go to Purchases > Download Files."
    }
)

Vacation Mode

When you need a break, toggle vacation mode:

# Enable vacation mode
client.put(
    f"/application/shops/{shop_id}",
    data={
        "is_vacation": True,
        "vacation_message": "On vacation! Orders will be delivered upon return."
    }
)

# Disable vacation mode
client.put(
    f"/application/shops/{shop_id}",
    data={"is_vacation": False}
)

For digital products, vacation mode is less critical since delivery is automatic. But it can prevent customer confusion if you’re unavailable for support.

Shop Statistics

Get basic shop statistics:

shop = client.get(f"/application/shops/{shop_id}")

stats = {
    "total_listings": shop["listing_active_count"],
    "digital_listings": shop["digital_listing_count"],
    "favorites": shop["num_favorers"],
    "currency": shop["currency_code"]
}

For detailed analytics (sales, revenue), see the Analytics chapter.

Caching Shop Information

Shop data doesn’t change frequently. Cache it to reduce API calls:

import json
from pathlib import Path
from datetime import datetime, timedelta

CACHE_FILE = Path("shop_cache.json")
CACHE_DURATION = timedelta(hours=1)

def get_shop_cached(client, shop_id):
    if CACHE_FILE.exists():
        cache = json.loads(CACHE_FILE.read_text())
        cached_time = datetime.fromisoformat(cache["timestamp"])
        if datetime.now() - cached_time < CACHE_DURATION:
            return cache["data"]
    
    shop = client.get(f"/application/shops/{shop_id}")
    CACHE_FILE.write_text(json.dumps({
        "timestamp": datetime.now().isoformat(),
        "data": shop
    }))
    return shop

Handling Multiple Shops

If you manage multiple Etsy shops (different accounts), structure your code to handle this:

SHOPS = {
    "shop1": {"shop_id": 11111, "name": "PrintablesShop"},
    "shop2": {"shop_id": 22222, "name": "TemplatesShop"},
}

def get_all_shops_stats(client):
    results = {}
    for key, shop_info in SHOPS.items():
        stats = client.get(f"/application/shops/{shop_info['shop_id']}")
        results[key] = {
            "name": stats["shop_name"],
            "listings": stats["listing_active_count"]
        }
    return results

Note: Each shop requires separate authentication.

Common Shop Management Tasks

Task API Endpoint
Get shop info GET /application/shops/{shop_id}
Update shop PUT /application/shops/{shop_id}
List sections GET /application/shops/{shop_id}/sections
Create section POST /application/shops/{shop_id}/sections
Get policies GET /application/shops/{shop_id}/policies

What’s Next

Now that you can access your shop data, the next chapter covers the core operation for digital sellers: creating and managing product listings.

← Previous: Authentication Next: Creating Listings →

← Back to Table of Contents