Skip to content
CharmCharmCharm

API quickstart

Five steps, about five minutes. You need a store with Charm installed and API access switched on (ask in the in-app support chat; it is free on every plan).

1. Create a key

Section titled “1. Create a key”

In the Charm admin, open Settings → API → Create API key. Name it after the integration (Quickstart) and keep the read-only preset plus points:write. Copy the token: it starts with chrm_live_ and is shown once.

Terminal window
export CHARM_KEY="chrm_live_..."
export CHARM="https://charm.appfleece.app/api/v1"

2. Read the shop

Section titled “2. Read the shop”
Terminal window
curl "$CHARM/shop" -H "Authorization: Bearer $CHARM_KEY"
{
  "domain": "your-store.myshopify.com",
  "name": "Your Store",
  "currency": "EUR",
  "plan": "growth",
  "program_enabled": true,
  "program_name": "Rewards Club",
  "points_name": "points"
}

A 401 means the header is off (it must read Bearer <key>); a 403 access_required means API access is not switched on yet. Every error links to its fix in the error catalog.

3. Look up a customer

Section titled “3. Look up a customer”

By email:

Terminal window
curl "$CHARM/customers?email=jane@example.com" -H "Authorization: Bearer $CHARM_KEY"

Lists always answer { "data": [...], "next_cursor": null, "has_more": false }. Take the customer’s id (a Shopify customer GID) or legacy_id and read the full record, including the gap to the next tier:

Terminal window
curl "$CHARM/customers/7712345" -H "Authorization: Bearer $CHARM_KEY"

4. Award points, safely

Section titled “4. Award points, safely”
Terminal window
curl -X POST "$CHARM/customers/7712345/points/earn" \
  -H "Authorization: Bearer $CHARM_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "points": 50, "source_ref": "quickstart-1", "reason": "Welcome to the API" }'
{
  "changed": true,
  "deduplicated": false,
  "points_awarded": 50,
  "balance": { "id": "gid://shopify/Customer/7712345", "legacy_id": 7712345, "points_balance": 170, "points_earned": 170, "points_redeemed": 0, "pending_points": 0 }
}

Two safety nets make retries harmless:

  • the Idempotency-Key replays the first response when you retry the same request;
  • source_ref is unique per customer, so the same event can never earn twice. Run the command again: changed becomes false.

The award shows up in the customer’s points history with your reason, in the widget, and in analytics, exactly as if it had happened inside Charm.

5. Get told instead of polling

Section titled “5. Get told instead of polling”

Register a webhook (the key needs webhooks:manage):

Terminal window
curl -X POST "$CHARM/webhooks" \
  -H "Authorization: Bearer $CHARM_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/charm-hook", "topics": ["points.earned"] }'

Store the secret from the response (shown once), award points again, and your endpoint receives a signed points.earned event. Verify it as described in Webhooks.

Next

Section titled “Next”