Store
attach_store_logo
destructive writeAttach store logo
Set or replace the Store logo or the Customiser Links page logo.
Overview
Makes a staged upload the Store logo, which branded emails show, or the logo of the hosted Customiser Links page. Create the upload first with create_upload and purpose store_logo, send the bytes to its target, then pass its upload_id here. Only PNG, JPEG and WebP up to 2 MiB are accepted. Attaching replaces the current logo and deletes its file unless something else still uses it, so the call needs confirm: true. It requires the store:write scope and an idempotency_key, and supports dry_run.
Permission
Requires thestore:writepermission. A connection without it answersinsufficient_scopenaming the permission to approve.
Annotations
Prerequisites
- An upload created with create_upload and purpose store_logo, whose bytes were sent to its target. Creating it also needs store:write.
- A merchant has connected this store and approved the store:write scope.
Side effects
- Sets the logo and deletes the file it replaces, unless something else still uses it.
- Consumes the upload, which is single use.
- Claims the idempotency_key for at least 24 hours.
Arguments
Which logo to set: store for the Store logo that branded emails show, customiser_links for the hosted Customiser Links page logo.
One of: store, customiser_links
The id of an upload created with purpose store_logo, whose bytes have already been sent to its target. Each upload is single use.
Must be true to apply the change, because attaching replaces the current logo and deletes its file unless something else still uses it. Without it the call returns a confirmation_required error and changes nothing.
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 upload and its purpose are checked and the upload is not consumed 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. A dry run does not require the confirm argument.
Result
The Store, or the Customiser Links page, as it now stands with logo_url set. A dry run returns the attach verdict and consumes nothing.
The logo the call addressed.
One of: store, customiser_links
The Store, or the Customiser Links page, as it now stands with logo_url set. Absent on a dry run.
True when this call replayed a previously recorded response for the same idempotency_key instead of applying the write again.
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 attach verdict.
Error cases
Send confirm: true. Attaching replaces the current logo and deletes its file unless something else still uses it.
The connection was approved without store:write. Ask the merchant to reconnect and approve it, or to remove the connector and add it again if the approval screen does not offer it.
No upload with that id belongs to this store. Create one with create_upload.
The upload was already used. Create a new upload for each logo.
The upload was created for another purpose. Create a new upload with purpose store_logo.
The bytes were not a readable PNG, JPEG or WebP image within 2 MiB. Create a new upload with a valid file.
Set the Store logo
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "attach_store_logo",
"arguments": {
"logo": "store",
"upload_id": "upl_01jz9x2k7c8f3m5n6p7q8r9s0t",
"confirm": true,
"idempotency_key": "6b1f0c2a-3d4e-4f5a-8b6c-7d8e9f0a1b2c"
}
}
}{
"jsonrpc": "2.0",
"id": 1,
"result": {
"structuredContent": {
"request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t",
"store": {
"id": 12,
"name": "Demo Signs"
},
"logo": "store",
"resource": {
"id": 12,
"name": "Demo Signs",
"logo_url": "https://cdn.signcustomiser.com/files/2f6c0b9e.png",
"use_branding_for_emails": true
},
"idempotent_replay": false
}
}
}An upload made for another purpose (error)
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "attach_store_logo",
"arguments": {
"logo": "customiser_links",
"upload_id": "upl_01jz9x2k7c8f3m5n6p7q8r9s0t",
"dry_run": true
}
}
}{
"jsonrpc": "2.0",
"id": 1,
"result": {
"isError": true,
"structuredContent": {
"error": {
"code": "upload_purpose_mismatch",
"title": "Upload purpose mismatch",
"detail": "This slot accepts uploads created with purpose store_logo, and this upload was created with purpose option_image. Create a new upload with the purpose of the slot.",
"recovery": "The upload was created for a different purpose. Start again at create_upload with the purpose this attachment needs.",
"pointer": "/upload_id",
"allowed_values": [
"store_logo"
]
}
}
}
}