[{"value":"Usage limits","id":"usage-limits","hLevel":2,"level":1},{"value":"Usage example","id":"usage-example","hLevel":2,"level":1},{"value":"Downloading and processing files","id":"downloading-and-processing-files","hLevel":2,"level":1},{"value":"Failures and exceptions","id":"failures-and-exceptions","hLevel":2,"level":1},{"value":"Results notification","id":"results-notification","hLevel":2,"level":1}]

Bulk Change Task

Using the Bulk Change Task interface, you can submit a bulk change operation to SHOPLINE.

The bulk interface can include POST, PUT, PATCH, and DELETE requests to handle bulk data modifications.
This operation is an asynchronous task, and the results will not be immediately returned.
You need to set the file_url field in the payload of the Bulk Change Task interface request.
The file URL must be publicly accessible without requiring authentication; otherwise, the task submission will fail.
The time required for the task depends on its complexity. Once the task is completed, the results will be generated in a temporary file in JSONL format, which will be valid for 12 hours.
You can use the Bulk Task Result Query interface to check the execution status and retrieve the results. The task results will be returned as a URL to a JSONL file in the HTTP response.
You need to download the content of that file to obtain the final task result data.

Note:

Bulk change tasks are store-specific and executed sequentially. At any given time, each store can only have one ongoing bulk change task. If an app submits a bulk change task for a store, SHOPLINE will reject any other bulk change tasks for that store until the previous task is completed, regardless of whether the tasks are from the same app.
If you don’t retrieve the results via the Bulk Task Result Query prior to running another bulk query task, the previous task results will be lost and will need to be run again.

Usage limits

A store can submit only one asynchronous change task, and during the processing stage, you cannot submit new queries.
The app must have the write_bulkoperation and read_bulkoperation permissions.
The file_url cannot exceed 10MB, and the number of lines in the file cannot exceed 10,000.
The API version must be greater than or equal to v20220901.

Usage example

Suppose you want to import a batch of product data into SHOPLINE. You can follow these steps:

Ensure that your app has the write_products, read_bulkoperation, and write_bulkoperation permission scopes.

Prepare the parameters required for Product Creation. Put each product creation request information in a file and submit a Bulk Change Task as follows:

curl --location -g --request POST
 'https://{handle}.myshopline.com/admin/openapi/v20220901/bulk_operation_run_mutation_general.json' \
--header 'Authorization: {token}' \
--header 'Content-Type: app/json' \
--data-raw '{
    "file_url": "https://xxx.com/products.jsonl"
}'

In this example, "products.jsonl" is a JSONL file where each line contains a product creation request. Below is an example file with three product creation requests. The "url," "method," and "payload" fields represent the endpoint, method, and payload of Product Creation.

{"url":"https://goodgoods.myshopline.com/admin/openapi/v20230901/products/products.json","method":"post","payload":{"product":{"published_scope":"web","body_html":"sdf","images":[{"src":"https://img-va.myshopline.com/image/store/2000986376/1663054163488/Hbe20374eba504af8b3b088a2f5d87658h.jpg?w=1000&h=1000","alt":"sdf"}],"vendor":"sdf","subtitle":"sdf","options":[{"values_images":{"Red":"https://img-va.myshopline.com/image/store/2000986376/1663054163488/Hbe20374eba504af8b3"},"name":"Color"}],"handle":"t-shirt","variants":[{"image":{"src":"https://img-va.myshopline.com/image/store/2000986376/1663054163488/Hbe20374eba504af8b3b088a2f5d87658h.jpg?w=1000&h=1000","alt":"sdf"},"required_shipping":true,"compare_at_price":"11","taxable":true,"option5":"","weight":"1.2","inventory_policy":"deny","weight_unit":"kg","price":"10.11","option3":"","option4":"","inventory_tracker":true,"option1":"Red","option2":"","sku":"2111341123434","barcode":"1111111123434"}],"title":"sdf","product_category":"sdf","status":"active","tags":["sdf,sdf3"]}}}
{"url":"https://goodgoods.myshopline.com/admin/openapi/v20230901/products/products.json","method":"post","payload":{"product":{"published_scope":"web","body_html":"sdf","images":[{"src":"https://img-va.myshopline.com/image/store/2000986376/1663054163488/Hbe20374eba504af8b3b088a2f5d87658h.jpg?w=1000&h=1000","alt":"sdf"}],"vendor":"sdf","subtitle":"sdf","options":[{"values_images":{"Red":"https://img-va.myshopline.com/image/store/2000986376/1663054163488/Hbe20374eba504af8b3"},"name":"Color"}],"handle":"t-shirt","variants":[{"image":{"src":"https://img-va.myshopline.com/image/store/2000986376/1663054163488/Hbe20374eba504af8b3b088a2f5d87658h.jpg?w=1000&h=1000","alt":"sdf"},"required_shipping":true,"compare_at_price":"11","taxable":true,"option5":"","weight":"1.2","inventory_policy":"deny","weight_unit":"kg","
price":"10.11","option3":"","option4":"","inventory_tracker":true,"option1":"Red","option2":"","sku":"2111341123434","barcode":"1111111123434"}],"title":"sdf","product_category":"sdf","status":"active","tags":["sdf,sdf3"]}}}

If the response returns an HTTP status code of 200, it means the task has been successfully submitted.

Please use the batch task result query interface to check the tasks for your current store.

curl --location -g --request GET 'https://{handle}.myshopline.com/admin/openapi/v20220901/current_bulk_operation.json?type=MUTATION_GENERAL' \
--header 'Authorization: {token}' \
--header 'Content-Type: app/json' \
--data-raw ''

Note: In the request path, you need to add type=MUTATION_GENERAL to indicate that it is a batch task change.

{
  "partialDataUrl": null,
  "createdAt": "2023-05-24T14:53:45+08:00",
  "expiredAt": null,
  "reason": null,
  "completedAt": null,
  "errorCode": null,
  "id": "gid://shopline/BulkOperation/XX",
  "type": "QUERY",
  "completedCount": 0,
  "storeId": "xx",
  "url": null,
  "status": "CREATED"
}

Downloading and processing files

Once the task is completed, you can directly download the JSONL file by using the URL field returned from the Bulk Task Result Query interface.

If the task is interrupted, and not all data can be queried, the query task will fail.

In this case:

Obtain the URL of the partially completed task result file in JSONL format from the partialDataUrl field returned by the Bulk Task Result Query interface.
Download this JSONL file to obtain the already executed change results.
Parse the last line of this result to find the corresponding line number in the payload of the JSONL file.
Delete the content below that line number and resubmit the Bulk Change Task.

Please note that the JSONL files obtained from the url and partialDataUrl will be cleared after 12 hours.

You can use any programming language to parse the JSONL file. Each line represents a valid JSON data segment.

For example:

{"product":{"image":{"src":"https://img-va.myshopline.com/image/store/2000986376/1663054163488/Hbe20374eba504af8b3b088a2f5d87658h.jpg?w=1000&h=1000","alt":"sdf","id":"5949197836163148889"},"body_html":"sdf","images":[{"src":"https://img-va.myshopline.com/image/store/2000986376/1663054163488/Hbe20374eba504af8b3b088a2f5d87658h.jpg?w=1000&h=1000","alt":"sdf","id":"5949197836163148889"}],"created_at":"2023-05-24T19:32:12+08:00","template_path":null,"handle":"t-shirt-2","variants":[{"inventory_quantity":0,"image":{"src":"https://img-va.myshopline.com/image/store/2000986376/1663054163488/Hbe20374eba504af8b3b088a2f5d87658h.jpg?w=1000&h=1000","alt":"sdf","id":"5949197836163148889"},"required_shipping":true,"compare_at_price":"11.00","taxable":true,"option5":null,"created_at":"2023-05-24T19:32:12+08:00","weight":"1.20","title":"Red","inventory_policy":"deny","updated_at":"2023-05-24T19:32:12+08:00","weight_unit":"kg","inventory_item_id":"5949197838801706542","price":"10.11","product_id":"16059491978375601928251954","option3":null,"option4":null,"inventory_tracker":true,"option1":"Red","id":"18059491978379292915831954","option2":null,"sku":"2111341123434","barcode":"1111111123434"}],"title":"sdf","tags":"sdfsdf3","published_scope":"web","product_type":"NORMAL","updated_at":"2023-05-24T19:32:12+08:00","vendor":"sdf","subtitle":"sdf","options":[{"product_id":"16059491978375601928251954","values":["Red"],"values_images":{"Red":"https://img-va.myshopline.com/image/store/2000986376/1663054163488/Hbe20374eba504af8b3"},"name":"Color","id":"16159491978379292915851954"}],"spu":null,"id":"16059491978375601928251954","published_at":"2023-05-24T19:32:12+08:00","product_behavior":"","product_category":"sdf","status":"active"}}
{"product":{"image":{"src":"https://img-va.myshopline.com/image/store/2000986376/1663054163488/Hbe20374eba504af8b3b088a2f5d87658h.jpg?w=1000&h=1000","alt":"sdf","id":"5949197836163148889"},"body_html":"sdf","images":[{"src":"https://img-va.myshopline.com/image/store/2000986376/1663054163488/Hbe20374eba504af8b3b088a2f5d87658h.jpg?w=1000&h=1000","alt":"sdf","id":"5949197836163148889"}],"created_at":"2023-05-24T19:32:12+08:00","template_path":null,"handle":"t-shirt-2","variants":[{"inventory_quantity":0,"image":{"src":"https://img-va.myshopline.com/image/store/2000986376/1663054163488/Hbe20374eba504af8b3b088a2f5d87658h.jpg?w=1000&h=1000","alt":"sdf","id":"5949197836163148889"},"required_shipping":true,"compare_at_price":"11.00","taxable":true,"option5":null,"created_at":"2023-05-24T19:32:12+08:00","weight":"1.20","title":"Red","inventory_policy":"deny","updated_at":"2023-05-24T19:32:12+08:00","weight_unit":"kg","inventory_item_id":"5949197838801706542","price":"10.11","product_id":"16059491978375601928251954","option3":null,"option4":null,"inventory_tracker":true,"option1":"Red","id":"18059491978379292915831954","option2":null,"sku":"2111341123434","barcode":"1111111123434"}],"title":"sdf","tags":"sdfsdf3","published_scope":"web","product_type":"NORMAL","updated_at":"2023-05-24T19:32:12+08:00","vendor":"sdf","subtitle":"sdf","options":[{"product_id":"16059491978375601928251954","values":["Red"],"values_images":{"Red":"https://img-va.myshopline.com/image/store/2000986376/1663054163488/Hbe20374eba504af8b3"},"name":"Color","id":"16159491978379292915851954"}],"spu":null,"id":"16059491978375601928251954","published_at":"2023-05-24T19:32:12+08:00","product_behavior":"","product_category":"sdf","status":"active"}}

Failures and exceptions

During the query process, there are various reasons that can cause SHOPLINE to stop executing your task. The common reasons include:

Insufficient permissions:

You submitted a query but do not have the necessary permissions for the project. You need to apply for the appropriate permissions first.
Internal exceptions:

Your submitted query cannot be processed due to an unpredictable reason.
Token expiration:

Your access token expired during the execution of the task. You may need to resubmit the task with a new token.

Results notification

You can obtain the task execution results in two ways:

Periodically call the Bulk Task Result Query interface to check the progress of the task execution.
When the bulk change task is completed, we will provide webhook notifications with the event others/update. You can determine the progress of the task based on the status field in the notification result, identify the task type using the type field, and obtain the task results from the url field.

Please note that you should adapt the URLs provided to the actual API endpoints used in your system.

Was this article helpful to you?