Party City Scraper

Scrape Party City — the online retailer for party supplies, balloons, costumes, tableware, and seasonal decor. Browse any category, search by keyword, look up specific products by handle/URL, or list the entire live collection/category taxonomy. Get price, sale price, discount percentage, brand, variant options (color/size/theme), images, and image dimensions. No login, no proxy required.

What this actor does

• Four modes: byCategory (paginated category browse), search (keyword search), byHandles (direct product lookup), listCollections (every live collection/category on the storefront, for discovery)
• 58 built-in categories in the dropdown — birthday themes, licensed characters (Disney, Marvel, Star Wars, etc.), balloons, tableware, decorations, costumes, and special occasions — plus a free-text override for any other category, or use listCollections to discover the full live list (140+) dynamically
• Price tracking: current price, original (compare-at) price, computed discount percentage, on-sale flag
• 14 filter dimensions: price range, brand, product type (substring or exact-match dropdown of 61 known types), title keyword, tags, SKU, stock status, discount %
• Sorting: best-selling (real ranking via Shopify's Storefront GraphQL API, since the legacy REST feed ignores sort entirely), price, title, or newest/oldest (all applied client-side for accuracy)
• Empty fields are omitted — every field present in a record has real data

Output per product

• productId, handle, productUrl — canonical Party City product page
• title, brand, productType, category, tags[]
• description — plain text (HTML stripped)
• price, maxPrice — lowest / highest variant price
• comparePrice, onSale, discountPercent — sale tracking
• currency — always USD
• variantCount, availableVariantCount, available
• skus[] — up to 20
• variants[] — up to 30, each with variantTitle, sku, price, comparePrice, available, variantImageUrl (photo for that specific color/size when Party City provides one), and option values (color/size/theme)
• imageUrl, images[] — up to 15; imageWidth, imageHeight — pixel dimensions of the primary image
• options[] — variant option names/values (e.g. color, size, character theme)
• createdAt, updatedAt, publishedAt
• recordType: "product", scrapedAt

Output per collection (mode = listCollections)

• collectionId, handle, collectionUrl — canonical Party City collection page
• title, description — plain text (HTML stripped)
• productsCount — number of products currently in the collection
• imageUrl, imageAlt — collection banner image
• updatedAt, publishedAt
• recordType: "collection", scrapedAt

Input

Field	Type	Default	Description
mode	string	byCategory	byCategory / search / byHandles / listCollections
category	string	birthday	Category dropdown (mode=byCategory)
categoryHandle	string	–	Custom category handle override
searchQuery	string	–	Keyword search (mode=search), top 10 results
productHandles	array	–	Product handles or URLs (mode=byHandles)
sortBy	string	best-selling	Sort order for category browse
maxItems	int	100	Hard cap (1–10000) — also caps listCollections
imageQuality	string	master	Shopify CDN image size
minPrice / maxPrice	number	–	Price range filter (USD)
onSaleOnly	bool	false	Only discounted products
minDiscountPercent	int	–	Minimum discount %
brandContains	string	–	Brand name substring filter
productTypeContains	string	–	Product type substring filter
productTypeEquals	string	–	Product type exact-match dropdown (61 known types, e.g. Costumes, Balloons, Plates)
titleContains	string	–	Title substring filter
tagAnyOf / tagNoneOf	array	–	Tag allow/block list
skuContains	string	–	SKU substring filter
includeUnavailable	bool	false	Include out-of-stock products
useApifyProxy	bool	false	Force Apify proxy from the start
requestDelaySecs	int	1	Delay between page fetches

Example: browse a category

{
  "mode": "byCategory",
  "category": "birthday",
  "maxItems": 100,
  "sortBy": "best-selling"
}

Example: on-sale Halloween costumes

{
  "mode": "byCategory",
  "category": "halloween-costumes",
  "onSaleOnly": true,
  "minDiscountPercent": 20,
  "maxItems": 200
}

Example: search by keyword

{
  "mode": "search",
  "searchQuery": "balloon arch kit"
}

Example: look up specific products

{
  "mode": "byHandles",
  "productHandles": [
    "https://www.partycity.com/products/colorful-collage-paper-plate-8ct"
  ]
}

Example: discover every collection/category

{
  "mode": "listCollections",
  "maxItems": 200
}

Example: exact product-type filter

{
  "mode": "byCategory",
  "category": "halloween-costumes",
  "productTypeEquals": "Costumes",
  "maxItems": 100
}

Use cases

• Price tracking — monitor a category or theme for sale prices and discount depth
• Seasonal planning — pull current inventory/pricing ahead of Halloween, graduation, or birthday seasons
• Market research — analyze party-supply pricing and licensed-character assortment
• Affiliate content — pull current pricing/availability for party-planning guides
• Competitive intelligence — compare Party City pricing against other party/costume retailers

FAQ

Is this affiliated with Party City? No. This is a third-party actor that reads Party City's public storefront data — no login required.

Why does search only return up to 10 results? Party City's in-store search runs on Shopify's predictive-search API, which caps relevance results at 10 by platform design. For larger result sets, use byCategory browse with titleContains to filter by keyword within a category.

Why does byCategory sometimes deliver fewer products than a collection's productsCount? byCategory paginates /collections/<handle>/products.json until either maxItems is reached or the storefront returns a genuinely empty page — it never stops early on a short page. For most collections this reaches the collection's own reported productsCount exactly. A few large collections (e.g. party-supplies) are an exception: Party City's storefront JSON feed itself only ever serves a subset of the products counted in the collection's metadata (the rest are catalog-linked but not published to the JSON feed — visiting further pages returns {"products":[]} well before the metadata count is reached). This is a source-side data gap, not a scraper limitation — the actor already delivers every product Party City's public API exposes for that category.

Why are some fields missing from a product? Fields are only included when Party City's storefront actually returns that data. For example, comparePrice/discountPercent only appear on discounted products, and maxPrice only appears when variants (e.g. size/color options) have different prices.

What do the options/variants fields represent? Party City products often come in multiple options — color, size, or character theme (e.g. "Lunch" vs "Dessert" plates, or costume sizes). Each combination is a separate variant with its own price and stock status. When Party City has a distinct photo for a specific option (e.g. a costume size), it appears as variantImageUrl on that variant.

What's the difference between productTypeContains and productTypeEquals? productTypeContains matches any product type containing your text as a substring. productTypeEquals is a dropdown of the 61 exact product types Party City uses catalog-wide (e.g. Balloons, Costumes, Plates) — use it when you want only that exact category, not a broader match.

What does listCollections return? Every live collection/category on partycity.com — over 140 at any given time — with title, description, product count, and banner image. Use it to discover category handles beyond the 58 built into the category dropdown, then feed a handle into categoryHandle for byCategory mode.

How fresh is the data? Every run fetches live data directly from partycity.com at request time.

Does this actor require a proxy? No. Party City's storefront JSON endpoints are publicly accessible from standard datacenter IPs. The actor automatically retries via Apify proxy if a request is ever blocked.