About the Async Job API

The Async Job API allows you to access asynchronous jobs from across Wix's APIs. Use this API to check job status (initialized, processing, etc.) and job item successes and failures.

Note that this API is not useful on its own - it's a way to access asynchronous jobs from other Wix APIs. For example, Wix Stores' Bulk Update Products by Filter.

Use cases

Terminology

  • Job: An asynchronous activity executed by Wix's servers. For example, bulk updating products.
  • Job item: An individual action executed as part of a job. For example, an individual product update.
  • Job status: The current stage or progress of the asynchronous job process. Statuses include:
    • Initialized.
    • Processing.
    • Finished.
    • Failed.
Did this help?

Sample Flow

This article shares some typical use cases you can support, as well as an example flow that supports each use case. You're certainly not limited to these use cases, but they can be a helpful jumping off point as you plan your implementation.

Get job results for Bulk Update Products by Filter call

You can update Wix Stores products in bulk, collect the resulting job ID, and check the status and updated products with the Async Jobs API.

  1. Call Wix Stores' Bulk Update Products by Filter with products to update and collect the jobId from the response.
  2. Call Get Async Job to get the job status and number of items remain to be processed.
  3. Call List Async Job Items to retrieve the updated products.
Did this help?

Async Job Object


Properties
idstringRead-onlyformat GUID

Job ID.


metadatastruct

Optional job metadata, used to store any parameters used during job execution, user-defined statuses, etc.


statusstring

Current job execution status.


countersCountersdeprecated - use counts instead

Current counters.


createdDatestringRead-onlyformat date-time

Date and time the job was created in ISO-8601 format.


updatedDatestringRead-onlyformat date-time

Date and time the job was last updated in ISO-8601 format.


ownerOwnerRead-onlydeprecated - use createdBy instead

Job owner.


createdByCreatedByRead-only

Job creator.


countsCounts

Current execution counts.

AsyncJob
JSON
{ "job": { "id": "076e0505-6944-4645-a248-80b197ee9cfd", "metadata": { "meta1": "value1" }, "status": "INITIALIZED", "counters": { "items_to_process": null, "items_succeeded": 0, "items_failed": 0, "error_count_by_code": {} }, "created_date": "2024-04-22T10:23:25.798Z", "updated_date": "2024-04-22T10:23:25.798Z", "owner": { "service_id": "338acb04-5b9b-4cdd-beb3-ea6739546d3a" } } }
Did this help?

GET

Get Async Job


Retrieves a job.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
READ ASYNC JOBS
Manage Stores - all permissions
Manage Products
Learn more about app permissions.
Endpoint
GET
https://www.wixapis.com/async-jobs/v1/async-jobs/{jobId}

Path Params
jobIdstringRequired

Job ID.

Response Object
jobJob

Returned job.

Get Async Job
Request
cURL
curl -X GET \ 'https://www.wixapis.com/async-jobs/v1/async-jobs/076e0505-6944-4645-a248-80b197ee9cfd' \ -H 'Authorization: <AUTH>'
Response
JSON
{ "job": { "id": "076e0505-6944-4645-a248-80b197ee9cfd", "metadata": { "meta1": "value1" }, "status": "INITIALIZED", "createdDate": "2024-04-22T10:23:25.798Z", "updatedDate": "2024-04-22T10:23:25.798Z", "createdBy": { "type": "APP_ID", "appIdOptions": { "appId": "338acb04-5b9b-4cdd-beb3-ea6739546d3a" } }, "counts": { "total": null, "successCount": 0, "failCount": 0, "errorByCodeCount": {} } } }
Did this help?

GET

List Async Job Items


Retrieves a list of job items.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
READ ASYNC JOBS
Manage Stores - all permissions
Manage Products
Learn more about app permissions.
Endpoint
GET
https://www.wixapis.com/async-jobs/v1/async-jobs/{jobId}/items

Path Params
jobIdstringRequired

Job ID.

Query Params
paging.limitintegerminimum 0maximum 100format int32

Maximum number of items to return in the results.


paging.cursorstringmaxLength 16000

Pointer to the next or previous page in the list of results.

Pass the relevant cursor token from the pagingMetadata object in the previous call's response. Not relevant for the first request.


statusFilterstring

async job item status filter.

Response Object
resultsArray <AsyncJobItem>

Job items.


pagingMetadataPagingMetadata

Paging metadata.

List Async job Items
Request
cURL
curl -X GET \ 'https://www.wixapis.com/async-jobs/v1/async-jobs/076e0505-6944-4645-a248-80b197ee9cfd/items?limit=10' \ -H 'Authorization: <AUTH>'
Response
JSON
{ "results": [ { "id": "365b44a2-61b2-42a0-87cf-272e7c42cc6e", "data": {}, "entityId": "entity1", "success": true }, { "id": "6fe127a3-9846-480f-8d9c-dc1e00623eaa", "data": {}, "entityId": "entity2", "success": true } ], "pagingMetadata": { "count": 2, "cursors": {}, "hasNext": false } }
Did this help?