Collections (Shared)

Collections are the container for scrape jobs. Each collection belongs to one supplier type (amazon or officeworks.com.au). All endpoints require authentication via API Key or Session Token.

Create Collection

POST

https://multicartapi.com/api/v1/schedules/add_schedule/

API Key or Session Token

Create a new collection. Status is force-set to draft on creation and auto-promoted to enable when the first ASIN or SKU is added.

curl "https://multicartapi.com/api/v1/schedules/add_schedule/" \
  -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "AU Laptops",
  "request_type": "amazon",
  "schedule": "Daily",
  "priority": "Normal",
  "notification_email": "[email protected]",
  "fetch_mode": "full"
}'

Parameters

Parameter	In	Type	Required	Default	Description
`name`	body	string	Required	—	Human-readable collection name.
`request_type`	body	string	Required	—	Supplier type: amazon or officeworks.com.au. For category scrapes use the dedicated category endpoint.
`schedule`	body	string	Required	—	Run frequency: Every X Minutes, Daily, Weekly, Monthly, or Manual.
`priority`	body	string	Required	—	Queue priority: Highest, High, Normal, Low, or Lowest.
`notification_email`	body	string	Required	—	Email address for run-completion notifications.
`fetch_mode`	body	string	Optional	full	full returns product details + availability; availability_only returns stock status only.
`schedule_time`	body	object	Optional	{}	Schedule configuration object. For Every X Minutes: { "minutes_frequency": "57", "days_of_week": ["tuesday"], "hours": ["00.00", "04.00"] }.
`destinations`	body	string	Optional	—	Optional webhook or destination configuration.

Request body

{
  "name": "AU Laptops",
  "request_type": "amazon",
  "schedule": "Daily",
  "priority": "Normal",
  "notification_email": "[email protected]",
  "fetch_mode": "full"
}

Response

{
  "code": 200,
  "data": {
    "id": 101,
    "name": "AU Laptops",
    "status": "draft",
    "schedule_status": "Pending",
    "request_type": "amazon",
    "fetch_mode": "full",
    "created_at": "2026-06-20T10:00:00Z",
    "updated_at": "2026-06-20T10:00:00Z"
  },
  "status": 1
}

Notes

Collection status starts as draft. Adding the first ASIN or SKU auto-promotes it to enable. All responses use HTTP 200 — check the envelope status field for business-logic errors.

List Collections

POST

https://multicartapi.com/api/v1/schedules/get_schedules/

API Key or Session Token

List all collections for the authenticated user. Returns only status=enable collections; drafts are excluded.

curl "https://multicartapi.com/api/v1/schedules/get_schedules/" \
  -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "sort_by": "updated_at",
  "sort_order": "desc"
}'

Parameters

Parameter	In	Type	Required	Default	Description
`sort_by`	body	string	Optional	updated_at	Field to sort results by. Default is updated_at descending.
`sort_order`	body	string	Optional	desc	Sort direction: asc or desc.

Request body

{
  "sort_by": "updated_at",
  "sort_order": "desc"
}

Response

{
  "code": 200,
  "data": [
    {
      "id": 101,
      "name": "AU Laptops",
      "status": "enable",
      "schedule_status": "Completed",
      "request_type": "amazon",
      "fetch_mode": "full",
      "asin_count": 250,
      "created_at": "2026-06-20T10:00:00Z",
      "updated_at": "2026-06-20T12:00:00Z"
    }
  ],
  "status": 1
}

Notes

Collections with schedule_status=Processing are always sorted to the top regardless of sort_by. Response includes asin_count per collection.

Get Collection

POST

https://multicartapi.com/api/v1/schedules/get/

API Key or Session Token

Retrieve a single collection by its ID.

curl "https://multicartapi.com/api/v1/schedules/get/" \
  -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "schedule_id": 101
}'

Parameters

Parameter	In	Type	Required	Default	Description
`schedule_id`	body	integer	Required	—	Collection ID to retrieve.

Request body

{
  "schedule_id": 101
}

Response

{
  "code": 200,
  "data": {
    "id": 101,
    "name": "AU Laptops",
    "status": "enable",
    "schedule_status": "Completed",
    "request_type": "amazon",
    "schedule": "Daily",
    "priority": "Normal",
    "fetch_mode": "full",
    "notification_email": "[email protected]",
    "created_at": "2026-06-20T10:00:00Z",
    "updated_at": "2026-06-20T12:00:00Z"
  },
  "status": 1
}

Notes

The landing /api-docs incorrectly shows collection_id as the body parameter. The backend requires schedule_id. Using collection_id will return a not-found error.

Update Collection

POST

https://multicartapi.com/api/v1/schedules/update_schedule/

API Key or Session Token

Partial update of any writable field on an existing collection.

curl "https://multicartapi.com/api/v1/schedules/update_schedule/" \
  -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "schedule_id": 101,
  "priority": "High",
  "schedule": "Weekly"
}'

Parameters

Parameter	In	Type	Required	Default	Description
`schedule_id`	body	integer	Required	—	Collection ID to update.
`name`	body	string	Optional	—	New collection name.
`schedule`	body	string	Optional	—	New run frequency: Every X Minutes, Daily, Weekly, Monthly, or Manual.
`priority`	body	string	Optional	—	New queue priority: Highest, High, Normal, Low, or Lowest.
`notification_email`	body	string	Optional	—	New notification email address.
`fetch_mode`	body	string	Optional	—	full or availability_only.
`schedule_time`	body	object	Optional	—	New schedule configuration object.

Request body

{
  "schedule_id": 101,
  "priority": "High",
  "schedule": "Weekly"
}

Response

{
  "code": 200,
  "data": {
    "id": 101,
    "name": "AU Laptops",
    "priority": "High",
    "schedule": "Weekly",
    "updated_at": "2026-06-20T13:00:00Z"
  },
  "status": 1
}

Notes

All fields except schedule_id are optional. Only supplied fields are modified.

Delete Collection

POST

https://multicartapi.com/api/v1/schedules/delete_schedule/

API Key or Session Token

Delete a single collection and remove all its result files from disk.

curl "https://multicartapi.com/api/v1/schedules/delete_schedule/" \
  -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "schedule_id": 101
}'

Parameters

Parameter	In	Type	Required	Default	Description
`schedule_id`	body	integer	Required	—	Collection ID to delete.

Request body

{
  "schedule_id": 101
}

Response

{ "code": 200, "data": { "detail": "Schedule deleted successfully." }, "status": 1 }

Notes

Also removes the result directory at results/<user_id>/<collection_id>/ from the server filesystem. This action is irreversible.

Delete Multiple Collections

POST

https://multicartapi.com/api/v1/schedules/delete_multiple/

API Key or Session Token

Delete multiple collections in a per-item loop (not a bulk SQL DELETE). Returns count of deleted items.

curl "https://multicartapi.com/api/v1/schedules/delete_multiple/" \
  -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "schedule_ids": [101, 102, 103]
}'

Parameters

Parameter	In	Type	Required	Default	Description
`schedule_ids`	body	array of integers	Required	—	JSON array of collection IDs to delete.

Request body

{
  "schedule_ids": [101, 102, 103]
}

Response

{ "code": 200, "data": { "detail": "3 schedule(s) and associated folder(s) deleted successfully." }, "status": 1 }

Notes

Must be a JSON array, not a comma-separated string. Call in batches of 50 or fewer — passing thousands of IDs in a single request will cause a timeout. Each item is committed individually, so a mid-batch failure leaves earlier deletions committed.

Run Collection

POST

https://multicartapi.com/api/v1/schedules/run/result/

API Key or Session Token

Immediately enqueue all ASINs or SKUs in a collection for scraping. Performs a credit check before queuing.

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

Parameters

Parameter	In	Type	Required	Default	Description
`collection_id`	body	integer	Required	—	Collection ID to run.

Request body

{
  "collection_id": 101
}

Response

{
  "code": 200,
  "data": "Scraping Processing Queued!",
  "status": 1
}

Notes

Returns immediately — scraping is asynchronous. Poll /schedules/collections/results/download/ for results. If the user has fewer credits than the collection's item count the envelope returns code 402, status 0, and a message describing the shortfall. HTTP transport is still 200.

List Run Results

POST

https://multicartapi.com/api/v1/schedules/collections/results/download/

API Key or Session Token

Poll run history for a collection and get download links for result JSON and ZIP files.

curl "https://multicartapi.com/api/v1/schedules/collections/results/download/" \
  -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "collection_id": 101,
  "skip": 0,
  "limit": 5
}'

Parameters

Parameter	In	Type	Required	Default	Description
`collection_id`	body	integer	Required	—	Collection ID to retrieve run history for.
`skip`	body	integer	Optional	0	Pagination offset (number of runner rows to skip).
`limit`	body	integer	Optional	5	Page size (number of runner rows to return).

Request body

{
  "collection_id": 101,
  "skip": 0,
  "limit": 5
}

Response

{
  "code": 200,
  "data": [
    {
      "id": 88,
      "collection": 101,
      "is_download_generated": true,
      "download_links": {
        "pages": [
          "https://multicartapi.com/api/v1/results/101/88/AU Laptops_88_Results_Page_1.json"
        ],
        "all_pages": "https://multicartapi.com/api/v1/results/101/88/AU Laptops_88_Results_All_Pages.zip"
      },
      "total_exacted_result": 250,
      "total_results": 250,
      "created_at": "2026-06-20T12:00:00Z",
      "updated_at": "2026-06-20T12:05:00Z"
    }
  ],
  "status": 1
}

Notes

Poll until is_download_generated is true before fetching the file URLs. Each entry in download_links.pages is a signed URL pointing to /api/v1/results/<collection_id>/<runner_id>/<file_name>. The all_pages ZIP bundles all page files for that runner.

Download Result File

GET

https://multicartapi.com/api/v1/results/<collection_id>/<runner_id>/<file_name>

API Key or Session Token

Stream a result file (JSON page or ZIP archive) as a binary attachment.

curl "https://multicartapi.com/api/v1/results/<collection_id>/<runner_id>/<file_name>" \
  -X GET \
  -H "x-api-key: YOUR_API_KEY"

Parameters

Parameter	In	Type	Required	Default	Description
`collection_id`	url	integer	Required	—	Collection ID.
`runner_id`	url	integer	Required	—	Runner ID from the download_links response.
`file_name`	url	string	Required	—	File name as returned in download_links, e.g. AU Laptops_88_Results_Page_1.json or AU Laptops_88_Results_All_Pages.zip.

Response

<binary stream — Content-Type: application/octet-stream, Content-Disposition: attachment>

Notes

Response is raw file bytes with no JSON envelope. Owner-scoped: the backend validates the collection belongs to the requesting user before streaming. Server-side file path is results/<user_id>/<collection_id>/<runner_id>/<file_name>. Use the URLs returned by /schedules/collections/results/download/ directly rather than constructing this path manually.