Report Toaster
Mechanic allows developers to integrate directly with Report Toaster to retrieve and update data. Use Report Toaster's powerful reporting engine to retrieve and operate on your Shopify data.
Report Toaster is offered by Cloudlab. Get assistance with this integration at support.cloudlab.com, or by emailing [email protected].
Report Toaster is a Shopify app that allows merchants to access their data in ways not possible via the Shopify Admin.
Introducing Report Toaster, created by Cloudlab. The most powerful reporting and analytics app available for Shopify merchants. Access any data in your store to create, schedule and export custom reports across all of your sales channels. You can also select from our list of over 80 pre-built reports.
Some terms to know when using Report Toaster.
Any report that comes included when the Report Toaster app is installed. Report Toaster includes over 80 pre-built reports.
The set of reports customized and saved by a Report Toaster user. Each account will have its own unique set of "My Reports".
Used to uniquely identify any Report Toaster report. Found in the URL when navigating to a specific report, as in the example below with the Report ID being
v_qygPGcofjQ.https://reporttoaster.cloudlab.com/my-reports/v_qygPGcofjQ
The Report Toaster integration includes a report_toaster action which can be used to perform one or more operations on data within Report Toaster.
This action accepts two options, one specifying a Report Toaster operation, and the other varying based on the specified operation.
The Report operation is used to run a report using the Report Toaster engine. The report can be from Pre-Built reports or My Reports.
This operation is most useful in concert with the
report_toaster/reports/create webhook, by which a task may take the resulting report and pass to another service, or parse to complete additional tasks.Report results can be returned inline, in which case there will be a 10MB limit. Alternatively, a file URL can be returned in a variety of formats.
Operation option | Description |
|---|---|
reports | Required; an array of objects defining the reports that will be executed. See below for the report options. |
Report option | Description |
|---|---|
id | Required; a string specifying the unique identifier for a pre-defined report to be executed |
file | Optional; an object describing a file to be returned when inline JSON results are not desired. Available file formats are "json", "csv", and "pdf" |
meta | Optional; an object providing context for the report execution. This value will be returned with the report_toaster/reports/create webhook |
{% action "report_toaster" %}
{
{% comment %}
Generate one or more reports. When each report is complete, a
'report_toaster/reports/create' event will be created with the result.
{% endcomment %}
"operation": "report",
{% comment %}
This batch array identifies one or more reports to be run.
{% endcomment %}
"batch": [
{
{% comment %}
The id of one of your 'My Reports'. This id is on the query string
when you run the report in Report Toaster.
{% endcomment %}
"id": "vVYKue9k7P",
{% comment %}
Optional custom context that will be returned with the report
data in the 'report_toaster/reports/create' event.
{% endcomment %}
"meta": {
"internal_request_id": "something something",
"task_id": {{ task.id | json }}
}
}
]
}
{% endaction %}
{% action "report_toaster" %}
{
{% comment %}
Generate one or more reports. When each report is complete, a
'report_toaster/reports/create' event will be created with the result.
{% endcomment %}
"operation": "report",
{% comment %}
This batch array identifies one or more reports to be run.
{% endcomment %}
"batch": [
{
{% comment %}
The id of one of your 'My Reports'. This id is on the query string
when you run the report in Report Toaster.
{% endcomment %}
"id": "v_t3a23v4e23",
{% comment %}
Optionally set this to create a download link to the report data
instead of returning the report data in the event. Options are
'json', 'csv' and 'pdf'.
{% endcomment %}
"file": {
"format": "csv"
},
{% comment %}
Optional custom context that will be returned with the report
data in the 'report_toaster/reports/create' event.
{% endcomment %}
"meta": {
"internal_request_id": "something something",
"task_id": {{ task.id | json }}
}
},
{ "id": "v_123" },
{ "id": "v_456" }
]
}
{% endaction %}
The Update operation is used to update some data in the Report Toaster dataset. Results will be returned as part of the standard
mechanic/actions/perform webhook.The update operation will be limited to attributes that are intended for update via external sources.
Operation option | Description |
|---|---|
[the name of the model to be updated; currently, only "Order" is supported] | Required; an array of update objects which use the Merge/Patch format. Current limitations are as follows:
1. The "id" attribute must be used to identify an Order.
2. Currently only "shipping_cost" and "transaction_fees" can be updated. |
{% action "report_toaster" %}
{
{% comment %}
Update operation to update values in Report Toaster
{% endcomment %}
"operation": "update",
{% comment %}
Update any number of orders with their corresponding shipping costs
and/or transaction fees
{% endcomment %}
"Order": [
{ "id": 4192644956357, "shipping_cost": 6.54 },
{ "id": 4192637419717, "transaction_fees": 5.32 },
{ "id": 4192651182277, "shipping_cost": 4.76, "transaction_fees": null }
]
}
{% endaction %}
The Report Toaster action sends webhook events to Mechanic, reporting back on the results of an action.
Occurs when a Report Toaster report has been created and is available for download.
{
"id": "vVYKue9k7P",
"name": "30-Day Summary",
"data": {....},
"meta": {
"internal_request_id": "something something",
"task_id": "fc3872b8-66a0-4ffb-bcaf-6f1b4a966aba"
},
"definition": {....}
}
{
"id": "vVYKue9k7P",
"name": "30-Day Summary",
"file": {
"format": "pdf",
"url": "https://example.com/report.pdf"
"size": 1234567
},
"meta": {
"internal_request_id": "something something",
"task_id": "fc3872b8-66a0-4ffb-bcaf-6f1b4a966aba"
},
"definition": {....}
}
Occurs when a requested Report Toaster report has failed.
{
"id": "vVYKue9k7P",
"name": "30-Day Summary",
"error": {....},
"meta": {
"internal_request_id": "something something",
"task_id": "fc3872b8-66a0-4ffb-bcaf-6f1b4a966aba"
},
"definition": {....}
}
Last modified 10mo ago