logo
Sign InSign Up

Amazon Category

Scrape an entire Amazon category page by URL and browse node ID. Each call creates its own collection with request_type='amazon_category_scrape' and dispatches to a dedicated Celery queue. Currently filters (prime, delivery day) are supported on amazon.com.au only; a valid cookie file for the domain+postcode must exist before submitting.

Submit Category Scrape

POST
https://multicartapi.com/api/v1/schedules/amazon/category/add_schedule/
API Key or Session Token

Submit an Amazon category URL for scraping; validates that a cookie file exists for the domain+postcode, creates a collection, and queues the task on the amazon_category Celery queue.

curl "https://multicartapi.com/api/v1/schedules/amazon/category/add_schedule/" \
  -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "category_url": "https://www.amazon.com.au/s?rh=n%3A4851693051&dc",
  "amazon_node_id": "4851693051",
  "domain": "amazon.com.au",
  "postcode": "4500",
  "filter_prime_ships_from_au": true,
  "filter_delivery_day": "within_2_days",
  "price_min_cents": 0,
  "price_max_cents": 50000
}'

Parameters

ParameterTypeRequiredDescription
category_urlstring (URL)RequiredFull Amazon category URL e.g. https://www.amazon.com.au/s?rh=n%3A4851693051&dc
amazon_node_idstringRequiredAmazon browse node ID extracted from the category URL e.g. 4851693051
domainstringRequiredDomain name exactly as it appears in /settings/domains/ e.g. amazon.com.au. Must be present in domain_config.DOMAINS.
postcodestringRequiredPostcode string e.g. 4500. Validated against the domain's postcode_regex. A cookie file for this domain+postcode must already exist (create one via /zipcodes/create-zipcode/).
namestringOptionalHuman-readable collection name. Defaults to amazon_category_<node_id>.
filter_prime_ships_from_aubooleanOptionalFilter to products that ship from AU and are Prime-eligible. Currently supported on amazon.com.au only.
filter_delivery_daystringOptionalDelivery speed filter: tomorrow or within_2_days (or omit/null for no filter). amazon.com.au only.
price_min_centsintegerOptionalMinimum price filter in cents e.g. 0
price_max_centsintegerOptionalMaximum price filter in cents e.g. 50000 for $500.00
notification_emailstring (email)OptionalEmail address for completion notification. Defaults to the authenticated user's email.
prioritystringOptionalQueue priority: Highest, High, Normal, Low, or Lowest.
Request body
{
  "category_url": "https://www.amazon.com.au/s?rh=n%3A4851693051&dc",
  "amazon_node_id": "4851693051",
  "domain": "amazon.com.au",
  "postcode": "4500",
  "filter_prime_ships_from_au": true,
  "filter_delivery_day": "within_2_days",
  "price_min_cents": 0,
  "price_max_cents": 50000
}
Response
{
  "code": 200,
  "data": { "id": 20326, "runner_id": 412 },
  "status": 1
}

Notes

Returns id (collection_id) and runner_id — save both for polling /result/ and /cancel/. Returns code 402 if the user has insufficient credits. Returns code 400 if no cookie file exists for the domain+postcode combination; add the postcode via /zipcodes/create-zipcode/ first and wait for status to become active. Refinement filters (filter_prime_ships_from_au, filter_delivery_day) are only applied for amazon.com.au; they are silently ignored on other domains.

Poll Category Scrape Result

POST
https://multicartapi.com/api/v1/schedules/amazon/category/result/
API Key or Session Token

Poll the status and fetch the results of a category scrape. Returns a single-element array; poll until is_download_generated is true or stage is failed.

curl "https://multicartapi.com/api/v1/schedules/amazon/category/result/" \
  -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "collection_id": 20326
}'

Parameters

ParameterTypeRequiredDescription
collection_idintegerRequiredCollection ID returned in the id field of /add_schedule/ response.
Request body
{
  "collection_id": 20326
}
Response
{
  "code": 200,
  "data": [{
    "id": 412,
    "collection": 20326,
    "is_download_generated": true,
    "stage": "done",
    "asin_count": 450,
    "asins": [
      { "asin": "B0ABC123", "title": "Example Product", "price": "$29.99" }
    ],
    "download_links": {
      "pages": ["https://multicartapi.com/api/v1/results/20326/412/category_asins.json"],
      "all_pages": ""
    }
  }],
  "status": 1
}

Notes

Response is always a single-element array. While scraping, is_download_generated is false and stage reflects the current phase (e.g. scraping) with a progress object showing current page and total pages. When is_download_generated is true, asins is inlined from the server-side file results/<user_id>/<collection_id>/<runner_id>/category_asins.json. Terminal states to watch for: stage=done (success) or stage=failed (unrecoverable error). The download_links.all_pages field is an empty string for category results — use download_links.pages[0] to download the full result file.

Cancel Category Scrape

POST
https://multicartapi.com/api/v1/schedules/amazon/category/cancel/
API Key or Session Token

Cancel an in-flight category scrape by revoking the Celery task; sets the collection schedule_status to Failed with message Cancelled by user.

curl "https://multicartapi.com/api/v1/schedules/amazon/category/cancel/" \
  -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "collection_id": 20326
}'

Parameters

ParameterTypeRequiredDescription
collection_idintegerRequiredCollection ID returned in the id field of /add_schedule/ response.
Request body
{
  "collection_id": 20326
}
Response
{
  "code": 200,
  "data": { "id": 20326, "revoked": true },
  "status": 1
}

Notes

revoked: true means the Celery task was found in the broker and revoked. revoked: false means the task had already completed or was not found in the broker — the collection may already be in a terminal state. After cancellation the collection schedule_status is set to Failed and failed_message is set to Cancelled by user. A cancelled collection cannot be restarted; submit a new /add_schedule/ request if a fresh run is needed.