# GET List shares

Lists the share links shoppers made for designs from the authenticated Store's customisers, newest first in the order they were made (their `id` order). Requires `shares:read`. Follow `links.next` while `pagination.has_more` is true, sending each cursor back unchanged with the same filters and `timezone`. The filters match the merchant admin's Shares page. `filter[customiser_name]` finds shares whose customiser name contains the text, ignoring case and surrounding spaces. `filter[sign_category]` keeps shares from customisers of that sign category. `filter[created_from]` and `filter[created_to]` are inclusive calendar days, counted in `timezone` (UTC when it is absent).

- Source URL: https://www.signcustomiser.com/help/api/v3-get-list-shares/
- Markdown URL: https://www.signcustomiser.com/help/api/v3-get-list-shares.md
- Group: Shares
- OpenAPI for this group: https://www.signcustomiser.com/help/openapi/shares.json
- Method: GET
- Path: /api/v3/shares
- Auth: Bearer token
- Required scopes: `shares:read`

## Query parameters

- limit (string, optional): Page size from 1 to 100. Defaults to 20. Example: 20
- cursor (string, optional): The opaque next_cursor from a previous page. Example: eyJ2IjoxfQ
- filter[customiser_id] (string, optional): Only return shares from this customiser. Example: 42
- filter[customiser_name] (string, optional): Only return shares whose customiser name contains this text, ignoring case. At most 255 characters. Example: neon
- filter[sign_category] (string, optional): Only return shares from customisers of this `sign_category`. Example: neon
- filter[created_from] (string, optional): Earliest day to include, inclusive, as YYYY-MM-DD in `timezone`. Example: 2026-07-01
- filter[created_to] (string, optional): Latest day to include, inclusive, as YYYY-MM-DD in `timezone`. Must not be earlier than filter[created_from]. Example: 2026-07-31
- timezone (string, optional): The IANA timezone the created days are counted in. Defaults to `UTC`. Example: Australia/Sydney

## cURL example

```bash
curl https://web.signcustomiser.com/api/v3/shares?limit=20&cursor=eyJ2IjoxfQ&filter%5Bcustomiser_id%5D=42&filter%5Bcustomiser_name%5D=neon&filter%5Bsign_category%5D=neon&filter%5Bcreated_from%5D=2026-07-01&filter%5Bcreated_to%5D=2026-07-31&timezone=Australia%2FSydney \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_TOKEN'
```

## Response examples

### 200 GET 200 example 1

```json
{
  "data": [
    {
      "object": "share",
      "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
  },
  "links": {
    "self": "https://web.signcustomiser.com/api/v3/shares",
    "documentation": "https://www.signcustomiser.com/help/api/",
    "next": null
  },
  "meta": {
    "api_version": "v3",
    "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
  }
}
```

### 401 Missing API key

```json
{
  "type": "https://www.signcustomiser.com/help/api/problems/missing_api_key",
  "title": "Missing API key",
  "status": 401,
  "code": "missing_api_key",
  "detail": "Provide a store API key as a bearer token.",
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}
```

### 403 Insufficient scope

```json
{
  "type": "https://www.signcustomiser.com/help/api/problems/insufficient_scope",
  "title": "Insufficient scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "This operation requires the shares:read scope.",
  "required_scopes": [
    "shares:read"
  ],
  "granted_scopes": [
    "customisers:read"
  ],
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}
```

### 422 Unsupported filter value

```json
{
  "type": "https://www.signcustomiser.com/help/api/problems/invalid_parameter",
  "title": "Invalid query parameter",
  "status": 422,
  "code": "invalid_parameter",
  "detail": "The filter[sign_category] value is not a supported sign category.",
  "errors": [
    {
      "parameter": "filter[sign_category]",
      "code": "unsupported_value",
      "detail": "The filter[sign_category] value is not a supported sign category.",
      "allowed_values": [
        "neon",
        "acrylic_channel_letter"
      ]
    }
  ],
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}
```

### 429 Rate limited

```json
{
  "type": "https://www.signcustomiser.com/help/api/problems/rate_limited",
  "title": "Too many requests",
  "status": 429,
  "code": "rate_limited",
  "detail": "You have exceeded the request limit for this API key.",
  "retry_after": 60,
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}
```
