# Cold-start quickstart

Create a scoped key, identify its Store, list customisers, and read pricing.

- Source URL: https://www.signcustomiser.com/help/api/guides/quickstart/
- Markdown URL: https://www.signcustomiser.com/help/api/guides/quickstart.md

## Guide

This walkthrough starts with no local configuration. It identifies the Store behind a key, lists that Store's customisers, and reads one customiser's pricing document.

You need Bash, `curl`, and `jq`.

## 1. Create a scoped key

In Sign Customiser, open the intended Store and go to **Tools & Settings > API Tokens**. Create a key with these scopes:

- `store:read`
- `customisers:read`
- `pricing:read`

Keep the one-time secret dialog open until you have entered the key in the next step. See [Authentication and key lifecycle](/help/api/guides/authentication/) for Shopify, Universal, multi-Store, and storage details.

## 2. Set the base URL and key

Run this in Bash. The silent prompt keeps the key out of shell history and does not print it. `SIGN_CUSTOMISER_API_BASE` defaults to production, but a value already set by your environment is preserved.

```bash
set -o pipefail
: "${SIGN_CUSTOMISER_API_BASE:=https://web.signcustomiser.com}"
read -rsp "Sign Customiser API key: " SIGN_CUSTOMISER_API_KEY
printf '\n'
export SIGN_CUSTOMISER_API_BASE SIGN_CUSTOMISER_API_KEY
```

## 3. Identify the Store

```bash
curl --fail-with-body --silent --show-error \
  --header "Accept: application/json" \
  --header "Authorization: Bearer ${SIGN_CUSTOMISER_API_KEY}" \
  "${SIGN_CUSTOMISER_API_BASE}/api/v3/stores/me" | jq
```

Check `data.id`, `data.name`, and `data.platform`. Also check that `data.scopes` contains the three scopes above. Stop here if this is not the Store you expected: select the correct Store in the admin and create a new key.

## 4. List customisers

The following block saves the response in a temporary directory, prints it, and selects the first customiser ID. The cleanup trap removes the response when the shell exits.

```bash
SIGN_CUSTOMISER_TMP_DIR="$(mktemp -d)"
trap 'rm -rf "${SIGN_CUSTOMISER_TMP_DIR}"' EXIT

curl --fail-with-body --silent --show-error \
  --header "Accept: application/json" \
  --header "Authorization: Bearer ${SIGN_CUSTOMISER_API_KEY}" \
  "${SIGN_CUSTOMISER_API_BASE}/api/v3/customisers" \
  > "${SIGN_CUSTOMISER_TMP_DIR}/customisers.json"

jq . "${SIGN_CUSTOMISER_TMP_DIR}/customisers.json"
CUSTOMISER_ID="$(jq --exit-status --raw-output '.data[0].id' \
  "${SIGN_CUSTOMISER_TMP_DIR}/customisers.json")" || {
    printf 'This Store has no customisers. Create one, then run this step again.\n' >&2
    exit 1
  }
```

If `pagination.has_more` is `true`, follow `links.next` exactly as returned. Treat cursors as opaque; do not edit or construct them.

## 5. Read pricing

```bash
curl --fail-with-body --silent --show-error \
  --header "Accept: application/json" \
  --header "Authorization: Bearer ${SIGN_CUSTOMISER_API_KEY}" \
  "${SIGN_CUSTOMISER_API_BASE}/api/v3/customisers/${CUSTOMISER_ID}/pricing" | jq
```

The shape of `data` depends on `pricing_model`. A customiser on the retired fixed-height pricing model returns a `422 legacy_pricing_model` problem instead of a pricing document. That is different from the supported `fixed_height` sizing strategy used by some `simple_letter` sizes.

## Recover from a problem response

`curl --fail-with-body` exits non-zero for a 4xx or 5xx response but keeps the problem body visible. Read these fields before deciding what to do:

- `status` and stable `code` classify the failure.
- `detail` explains this occurrence.
- `request_id` identifies it for support and logs.
- `errors` may point to individual invalid fields and list `allowed_values`.

Common first-run fixes:

| Response | What to do |
|---|---|
| `401 invalid_api_key` | Enter the complete key again. If it expired or was revoked, create a replacement. |
| `403 insufficient_scope` | Read `required_scopes` and `granted_scopes`, then create a replacement key with the missing scope. |
| `404 resource_not_found` | List customisers again. The ID may belong to another Store or may no longer exist. |
| `422 legacy_pricing_model` | Recreate the customiser with `simple_letter` pricing and, when needed, the `fixed_height` sizing strategy. |
| `429 rate_limited` | Wait for the `Retry-After` interval before trying again. |

See [Errors and retries](/help/api/guides/errors-and-retries/) before adding automated retries or write operations.

## Clear the local key

```bash
unset SIGN_CUSTOMISER_API_KEY
```

Your deployed integration should read the key from its secret store, not an interactive prompt or checked-in environment file.