Sign Customiser

Navigation

Dark mode

Store

attach_store_logo

destructive write

Attach store logo

Copy page

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

readOnlyHintfalse
destructiveHinttrue
idempotentHinttrue
openWorldHintfalse

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

logostringrequired

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

upload_idstringrequired

The id of an upload created with purpose store_logo, whose bytes have already been sent to its target. Each upload is single use.

confirmbooleanrequired unless dry_run is true

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.

idempotency_keystringrequired unless dry_run is true

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.

dry_runboolean

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.

request_idstringalways present
storeobjectalways present
store.idintegeralways present
store.namestringalways present
logostringalways present

The logo the call addressed.

One of: store, customiser_links

resourceobject

The Store, or the Customiser Links page, as it now stands with logo_url set. Absent on a dry run.

idempotent_replayboolean

True when this call replayed a previously recorded response for the same idempotency_key instead of applying the write again.

dry_runboolean

Present and true only when dry_run was requested.

validboolean

Present only on a dry run, and always true: a failing dry run returns a tool error instead.

verdictobject

Present only on a dry run: the attach verdict.

Error cases

confirmation_required

Send confirm: true. Attaching replaces the current logo and deletes its file unless something else still uses it.

insufficient_scope

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.

resource_not_found

No upload with that id belongs to this store. Create one with create_upload.

upload_already_attached

The upload was already used. Create a new upload for each logo.

upload_purpose_mismatch

The upload was created for another purpose. Create a new upload with purpose store_logo.

upload_rejected

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

tools/call
{
  "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"
    }
  }
}
result
{
  "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)

tools/call
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "attach_store_logo",
    "arguments": {
      "logo": "customiser_links",
      "upload_id": "upl_01jz9x2k7c8f3m5n6p7q8r9s0t",
      "dry_run": true
    }
  }
}
result
{
  "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"
        ]
      }
    }
  }
}

Type a question and press Enter. Use the arrow keys to move between the results.