Sign Customiser

Navigation

Dark mode

See which customisers shoppers share designs from, and obtain the share ids get_share and delete_share take.

Overview

Lists the share links shoppers made for designs from the connected Store customisers, newest first, with each share id, its customiser id and name, the customiser product image and its creation date. Filters narrow the list by customiser, by customiser name text, by sign category and by creation day, counted in an IANA timezone (UTC by default). The link token and the stored design are not returned. It requires the shares:read scope and has no side effects.

Permission

Requires theshares:readpermission. A connection without it answersinsufficient_scopenaming the permission to approve.

Annotations

readOnlyHinttrue
destructiveHintfalse
idempotentHinttrue
openWorldHintfalse

Prerequisites

  • A merchant has connected this store and approved the shares:read scope.

Arguments

limitinteger

How many shares to return per page, between 1 and 100. Defaults to 20.

cursorstring

The opaque next_cursor value from the previous page, sent back with identical filters and timezone.

filterobject

Optional filters. An unknown filter is rejected, never ignored.

filter.customiser_idinteger

Only shares from this customiser.

filter.customiser_namestring

Only shares whose customiser name contains this text, ignoring case and surrounding spaces.

filter.sign_categorystring

Only shares from customisers of this sign category.

One of: neon, acrylic_channel_letter, metal_channel_letter, metal_cut_out, stencil, lightbox, wood_letter, aluminium_plate, braille_sign, wood_frame

filter.created_fromstring

The first included creation day, YYYY-MM-DD, counted in timezone.

filter.created_tostring

The last included creation day, YYYY-MM-DD, counted in timezone. It must not precede created_from.

timezonestring

The IANA timezone the creation days are counted in, such as Australia/Sydney. Defaults to UTC.

Result

Up to `limit` shares, newest first, plus the cursor for the next page.

request_idstringalways present
storeobjectalways present
store.idintegeralways present
store.namestringalways present
sharesarray of objectalways present

The page of shares, newest first.

shares[].idintegeralways present
shares[].customiser_idintegeralways present
shares[].customiser_namestringalways present
shares[].image_urlstring or null

The product image of the customiser, as the merchant admin shows it. Null when the customiser has none.

shares[].created_atstring or null

When the shopper made the link, UTC. Null on links older than the record.

paginationobjectalways present
pagination.has_morebooleanalways present
pagination.next_cursorstring or null

Error cases

insufficient_scope

The connection was approved without shares:read.

invalid_cursor

The cursor was altered or reused for a different collection, Store, filters, or timezone; restart with no cursor.

invalid_parameter

A filter value is blank or too long, sign_category is not a supported value, a date is not YYYY-MM-DD, created_to precedes created_from, or timezone is not an IANA timezone name.

unknown_filter

Remove the filter named in parameter. This tool forwards unknown filter names so the API can refuse them explicitly.

Neon shares made in July, Sydney time

tools/call
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_shares",
    "arguments": {
      "limit": 1,
      "filter": {
        "sign_category": "neon",
        "created_from": "2026-07-01",
        "created_to": "2026-07-31"
      },
      "timezone": "Australia/Sydney"
    }
  }
}
result
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t",
      "store": {
        "id": 12,
        "name": "Demo Signs"
      },
      "shares": [
        {
          "id": 512,
          "customiser_id": 42,
          "customiser_name": "Neon signs",
          "image_url": "https://cdn.example.com/customisers/42/product.png",
          "created_at": "2026-07-18T03:14:15Z"
        }
      ],
      "pagination": {
        "has_more": false,
        "next_cursor": null
      }
    }
  }
}

A connection without shares:read (error)

tools/call
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_shares",
    "arguments": {}
  }
}
result
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "isError": true,
    "structuredContent": {
      "error": {
        "code": "insufficient_scope",
        "title": "Insufficient scope",
        "detail": "The tool [list_shares] requires the shares:read scope, which this connection was not granted.",
        "recovery": "The connection was authorised without the scope this tool needs. Ask the merchant to reconnect the Sign Customiser connector and approve the scope named in required_scopes. If the approval screen does not offer that permission, ask them to remove the connector from this AI agent and add it again. Do not retry this call.",
        "required_scopes": [
          "shares:read"
        ],
        "granted_scopes": [
          "store:read"
        ]
      }
    }
  }
}

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