Customisers
import_customiser_text_template_artwork
writeImport text template artwork
Add the SVG artwork a cut-out metal text template with Frame Fit references.
Overview
Imports an SVG staged with create_upload (purpose text_template_svg) as text template artwork: kind production for the Frame Fit metal artwork, which needs its physical size or width_mm, or kind graphic for a graphic area. The SVG is checked and normalised; scripts, styles and external references are refused. It returns the artwork id and sha256 to reference in update_customiser_text_template, and changes no template. It requires the customisers:write scope and an idempotency_key, and supports dry_run.
Permission
Requires thecustomisers:writepermission. A connection without it answersinsufficient_scopenaming the permission to approve.
Annotations
Prerequisites
- An upload with purpose text_template_svg from create_upload, with its bytes sent.
- A cut-out metal customiser with Frame Fit pricing on a Store with text fields.
- A merchant has connected this store and approved the customisers:write scope.
Side effects
- Spends the upload and stores the normalised SVG as a Store asset. The same file imported again returns the existing asset.
Arguments
The customiser id, from list_customisers.
production for the template production artwork, graphic for a graphic area.
One of: production, graphic
The upload id from create_upload.
Production only: the width of a file without physical units, in millimetres, one decimal.
A client-generated key unique to this logical write, such as a UUID. Required: repeating the call with the same key and the same arguments replays the original result instead of writing twice, and the same key with different arguments is an idempotency_key_conflict.
When true, the import is checked and nothing is written: the result is the same verdict the apply would have reached, and a problem the apply would have raised comes back as the same tool error. Defaults to false. A dry run claims no key.
Result
The artwork: id, sha256, width_mm and height_mm. A dry run checks the upload and the customiser without reading the file.
One of: production, graphic
The imported artwork. Absent on a dry run.
Present and true only when dry_run was requested.
Present only on a dry run, and always true: a failing dry run returns a tool error instead.
Present only on a dry run: the validation verdict.
True when this call replayed a previously recorded response for the same idempotency_key instead of applying the write again.
Error cases
The connection was approved without customisers:write.
The error code names the rule the file broke. Fix the file and upload it again.
Wait retry_after seconds; the limit is 30 a minute.
Only cut-out metal with Frame Fit takes artwork.
Create a new upload with purpose text_template_svg.
An error at /width_mm (units_missing, width_mismatch, aspect_mismatch, frame_out_of_range) leaves the upload usable: retry with the right width_mm.
Import production artwork without physical units
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "import_customiser_text_template_artwork",
"arguments": {
"customiser_id": 42,
"kind": "production",
"upload_id": "upl_9f2c4b7ad13e6058ba41cd4201",
"width_mm": 600,
"idempotency_key": "d3e4f5a6-7182-4c9d-8e0f-2a3b4c5d6e7f"
}
}
}{
"jsonrpc": "2.0",
"id": 1,
"result": {
"structuredContent": {
"request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t",
"store": {
"id": 12,
"name": "Demo Signs"
},
"customiser_id": 42,
"kind": "production",
"artwork": {
"id": "tas_abcdefghijklmnop",
"sha256": "ec68d6053154d01f7161b2faba67f38e46584456c7303c6a5d66248b666debea",
"width_mm": 600,
"height_mm": 600
},
"idempotent_replay": false
}
}
}An SVG with a script is refused (error)
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "import_customiser_text_template_artwork",
"arguments": {
"customiser_id": 42,
"kind": "graphic",
"upload_id": "upl_9f2c4b7ad13e6058ba41cd4201",
"idempotency_key": "e4f5a6b7-8293-4dae-8f10-3b4c5d6e7f80"
}
}
}{
"jsonrpc": "2.0",
"id": 1,
"result": {
"isError": true,
"structuredContent": {
"error": {
"code": "invalid_svg",
"title": "Invalid SVG",
"detail": "The file contains a script.",
"recovery": "The SVG failed the shape constraint named in detail. Correct the file and upload it again.",
"errors": [
{
"pointer": "/upload_id",
"code": "script_present",
"detail": "The file contains a script."
}
]
}
}
}
}