Core Concepts
Platform
Techniques
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].
What is Report Toaster?
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.
Terminology
Some terms to know when using Report Toaster.
Pre-Built Reports
Any report that comes included when the Report Toaster app is installed. Report Toaster includes over 80 pre-built reports.
My Reports
The set of reports customized and saved by a Report Toaster user. Each account will have its own unique set of "My Reports".
Report ID
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
Action
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.
Report
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 object definition
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 webhookBasic Example: Single operation returning JSON Data (limit 10 MB)
1
{% action "report_toaster" %}
2
{
3
{% comment %}
4
Generate one or more reports. When each report is complete, a
5
'report_toaster/reports/create' event will be created with the result.
6
{% endcomment %}
7
"operation": "report",
8
9
{% comment %}
10
This batch array identifies one or more reports to be run.
11
{% endcomment %}
12
"batch": [
13
{
14
{% comment %}
15
The id of one of your 'My Reports'. This id is on the query string
16
when you run the report in Report Toaster.
17
{% endcomment %}
18
"id": "vVYKue9k7P",
19
20
{% comment %}
21
Optional custom context that will be returned with the report
22
data in the 'report_toaster/reports/create' event.
23
{% endcomment %}
24
"meta": {
25
"internal_request_id": "something something",
26
"task_id": {{ task.id | json }}
27
}
28
}
29
]
30
}
31
{% endaction %}
Copied!
Basic Example: Batch operation - return one CSV file and two JSON
1
{% action "report_toaster" %}
2
{
3
{% comment %}
4
Generate one or more reports. When each report is complete, a
5
'report_toaster/reports/create' event will be created with the result.
6
{% endcomment %}
7
"operation": "report",
8
9
{% comment %}
10
This batch array identifies one or more reports to be run.
11
{% endcomment %}
12
"batch": [
13
{
14
{% comment %}
15
The id of one of your 'My Reports'. This id is on the query string
16
when you run the report in Report Toaster.
17
{% endcomment %}
18
"id": "v_t3a23v4e23",
19
20
{% comment %}
21
Optionally set this to create a download link to the report data
22
instead of returning the report data in the event. Options are
23
'json', 'csv' and 'pdf'.
24
{% endcomment %}
25
"file": {
26
"format": "csv"
27
},
28
29
{% comment %}
30
Optional custom context that will be returned with the report
31
data in the 'report_toaster/reports/create' event.
32
{% endcomment %}
33
"meta": {
34
"internal_request_id": "something something",
35
"task_id": {{ task.id | json }}
36
}
37
},
38
{ "id": "v_123" },
39
{ "id": "v_456" }
40
]
41
}
42
{% endaction %}
Copied!
Update
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.
Basic Example: Update shipping costs
1
{% action "report_toaster" %}
2
{
3
{% comment %}
4
Update operation to update values in Report Toaster
5
{% endcomment %}
6
"operation": "update",
7
8
{% comment %}
9
Update any number of orders with their corresponding shipping costs
10
and/or transaction fees
11
{% endcomment %}
12
"Order": [
13
{ "id": 4192644956357, "shipping_cost": 6.54 },
14
{ "id": 4192637419717, "transaction_fees": 5.32 },
15
{ "id": 4192651182277, "shipping_cost": 4.76, "transaction_fees": null }
16
]
17
}
18
{% endaction %}
Copied!
Event topics
The Report Toaster action sends webhook events to Mechanic, reporting back on the results of an action.
report_toaster/reports/create
Occurs when a Report Toaster report has been created and is available for download.
Basic Example: Return JSON data
1
{
2
"id": "vVYKue9k7P",
3
"name": "30-Day Summary",
4
"data": {....},
5
"meta": {
6
"internal_request_id": "something something",
7
"task_id": "fc3872b8-66a0-4ffb-bcaf-6f1b4a966aba"
8
},
9
"definition": {....}
10
}
Copied!
Basic Example: Return file
1
{
2
"id": "vVYKue9k7P",
3
"name": "30-Day Summary",
4
"file": {
5
"format": "pdf",
6
"url": "https://example.com/report.pdf"
7
"size": 1234567
8
},
9
"meta": {
10
"internal_request_id": "something something",
11
"task_id": "fc3872b8-66a0-4ffb-bcaf-6f1b4a966aba"
12
},
13
"definition": {....}
14
}
Copied!
report_toaster/reports/fail
Occurs when a requested Report Toaster report has failed.
Basic Example
1
{
2
"id": "vVYKue9k7P",
3
"name": "30-Day Summary",
4
"error": {....},
5
"meta": {
6
"internal_request_id": "something something",
7
"task_id": "fc3872b8-66a0-4ffb-bcaf-6f1b4a966aba"
8
},
9
"definition": {....}
10
}
Copied!
Last modified 15d ago
Copy link
Edit on GitHub