Get one customer

GET /customers/{customer_id}

Scope	customers:read
Customer session token	Accepted with the read scope, for the token’s own customer
Rate limit class	read (limits)
Idempotency key	Not used
MCP tool	charm_get_customer

Balance, tier, the gap to the next tier, referral code and enrollment state for one customer. Add include to render a whole loyalty page in one call: rewards (the catalog at this customer’s price, each with can_redeem and the reason when not), history (the latest 10 rows with the title the shopper reads, in their language), program (the program configuration) and referral (code and share link). Each part needs its read scope; no Shopify calls.

Parameters

Name	In	Type	Description
customer_id	path	string	Shopify customer GID (percent-encoded, e.g. gid%3A%2F%2Fshopify%2FCustomer%2F123) or the numeric customer id.
include (optional)	query	string	Comma-separated: rewards (needs redemptions:read), history (points:read), program (program:read), referral.
locale (optional)	query	string	Language for history titles and the referral link, e.g. de. Defaults to the customer’s language.

Response 200

Returns Customer.

Field	Type	Description
id	string	Shopify customer GID, e.g. gid://shopify/Customer/123. Accepted by every endpoint that takes a customer id, as is the numeric legacy_id.
legacy_id	integer or null	The numeric Shopify customer id (the part after the last slash of the GID). (nullable)
email	string or null	(nullable)
first_name	string or null	(nullable)
last_name	string or null	(nullable)
points_balance	number	Spendable points.
points_earned	number	Lifetime points earned.
points_redeemed	number	Lifetime points spent.
pending_points	number	Points waiting for the return window to pass.
tier	CustomerTier or null	(nullable)
next_tier	NextTier or null	(optional, nullable)
rewards	array of CustomerReward	With include=rewards. (optional)
history	array of HistoryEntry	With include=history: the latest 10 rows. (optional)
program	Program	(optional)
referral	Referral or null	(optional, nullable)
referral_code	string or null	(nullable)
excluded_from_program	boolean
enrolled_at	string or null	(nullable)
enrolled_via	string or null	(nullable)
birthday	Birthday or null	(nullable)
orders_count	number
lifetime_spend	number or null	In the shop currency. (nullable)
last_activity_at	string or null	(nullable)
updated_at	string or null	(nullable)

{
  "id": "gid://shopify/Customer/7712345",
  "legacy_id": 7712345,
  "email": "shopper@example.com",
  "first_name": "Jane",
  "last_name": "Doe",
  "points_balance": 120,
  "points_earned": 120,
  "points_redeemed": 120,
  "pending_points": 120,
  "tier": {
    "id": "id",
    "name": "Gold",
    "achieved_at": "2026-10-01T09:30:00.000Z",
    "grace_until": "2026-10-01T09:30:00.000Z",
    "points_in_period": 120,
    "is_manual_override": false,
    "manual_override_at": "2026-10-01T09:30:00.000Z"
  },
  "next_tier": {
    "id": "id",
    "name": "Gold",
    "gap": {
      "unit": "points",
      "value": 1
    },
    "progress": {
      "value": 1,
      "max": 1
    }
  },
  "rewards": [
    {
      "id": "id",
      "type": "earn",
      "enabled": true,
      "name": "Gold",
      "points_cost": 120,
      "discount_type": "percentage",
      "discount_value": 1,
      "code_valid_days": 1,
      "title": "title",
      "title_translations": {},
      "fields": {},
      "summary": "summary",
      "minimum_purchase": 1,
      "ends_at": "2026-10-01T09:30:00.000Z",
      "can_redeem": {
        "state": null,
        "points_needed": null,
        "required_tier": null,
        "starts_at": null
      }
    }
  ],
  "history": [
    {
      "id": "id",
      "type": "earn",
      "points": 120,
      "title": "title",
      "is_pending": false,
      "created_at": "2026-10-01T09:30:00.000Z"
    }
  ],
  "program": {
    "enabled": true,
    "program_name": "Rewards Club",
    "points_name": "points",
    "points_expiry": {
      "enabled": true,
      "months": 1
    },
    "reward_expiry": {
      "enabled": true,
      "code_valid_days": 1
    },
    "eligibility": {
      "customer_audience": "all",
      "excluded_customer_tags": [
        null
      ],
      "excluded_product_tags": [
        null
      ]
    },
    "referral": {
      "enabled": true,
      "code_prefix": "REF",
      "discount_type": "percentage",
      "discount_value": 1,
      "minimum_purchase": 1
    },
    "memberships_enabled": false,
    "tiers_enabled": false,
    "earning_rules": [
      {
        "id": null,
        "type": null,
        "enabled": null,
        "label": null,
        "points": null,
        "points_per_currency": null,
        "limit": null,
        "title": null,
        "title_translations": null,
        "fields": null,
        "summary": null
      }
    ],
    "redemption_rules": [
      {
        "id": null,
        "type": null,
        "enabled": null,
        "name": null,
        "points_cost": null,
        "discount_type": null,
        "discount_value": null,
        "code_valid_days": null,
        "title": null,
        "title_translations": null,
        "fields": null,
        "summary": null
      }
    ],
    "revision": 1,
    "updated_at": "2026-10-01T09:30:00.000Z"
  },
  "referral": {
    "code": "code",
    "link": "link",
    "shares": 1
  },
  "referral_code": "JANE10",
  "excluded_from_program": false,
  "enrolled_at": "2026-10-01T09:30:00.000Z",
  "enrolled_via": "Embedded Widget",
  "birthday": {
    "month": 1,
    "day": 1
  },
  "orders_count": 1,
  "lifetime_spend": 1,
  "last_activity_at": "2026-10-01T09:30:00.000Z",
  "updated_at": "2026-10-01T09:30:00.000Z"
}

Example

curl -X GET "https://charm.appfleece.app/api/v1/customers/7712345" \
  -H "Authorization: Bearer chrm_live_..."

Errors

unauthorized · invalid_token · token_expired · insufficient_scope · access_required · not_found · validation_error · rate_limited

Every error body carries code, message, request_id and a doc_url pointing at the matching entry in the error catalog.