Stamped.io User Management API Guide

Auth method: HTTP Basic Auth using API Public Key (username) and API Private Key (password). Keys are retrieved from the Stamped dashboard under Settings > API.

Setup steps

1. Log in to the Stamped.io dashboard.
2. Navigate to Settings > API Keys.
3. Copy the API Public Key and API Private Key.
4. Encode 'PUBLIC_KEY:PRIVATE_KEY' in Base64.
5. Pass as Authorization: Basic header on all requests.

List customers

• Method: GET
• URL: https://stamped.io/api/v2/{storeHash}/customers
• Watch out for: Replace {storeHash} with your store's unique identifier found in the Stamped dashboard.

Request example

GET /api/v2/{storeHash}/customers?page=1&limit=20
Authorization: Basic <base64>

Response example

{
  "data": [
    {"email": "user@example.com", "firstName": "Jane", "points": 150}
  ],
  "total": 1,
  "page": 1
}

Get single customer

• Method: GET
• URL: https://stamped.io/api/v2/{storeHash}/customers/{email}
• Watch out for: Email must be URL-encoded in the path.

Request example

GET /api/v2/{storeHash}/customers/user%40example.com
Authorization: Basic <base64>

Response example

{
  "email": "user@example.com",
  "firstName": "Jane",
  "lastName": "Doe",
  "points": 150,
  "tier": "Gold"
}

Create or update customer

• Method: POST
• URL: https://stamped.io/api/v2/{storeHash}/customers
• Watch out for: Acts as an upsert - if the email already exists, the record is updated rather than creating a duplicate.

Request example

POST /api/v2/{storeHash}/customers
Content-Type: application/json

{"email":"user@example.com","firstName":"Jane","points":100}

Response example

{
  "email": "user@example.com",
  "firstName": "Jane",
  "points": 100,
  "createdAt": "2025-01-01T00:00:00Z"
}

Update customer points

• Method: POST
• URL: https://stamped.io/api/v2/{storeHash}/customers/points
• Watch out for: The 'action' field accepts 'add', 'subtract', or 'set'. Using 'set' overwrites the existing balance entirely.

Request example

POST /api/v2/{storeHash}/customers/points
Content-Type: application/json

{"email":"user@example.com","points":50,"action":"add"}

Response example

{
  "email": "user@example.com",
  "points": 200,
  "updatedAt": "2025-06-01T10:00:00Z"
}

Delete customer

• Method: DELETE
• URL: https://stamped.io/api/v2/{storeHash}/customers/{email}
• Watch out for: Deletion is permanent and removes all associated loyalty data for the customer.

Request example

DELETE /api/v2/{storeHash}/customers/user%40example.com
Authorization: Basic <base64>

Response example

{
  "success": true,
  "message": "Customer deleted."
}

List reviews for a customer

• Method: GET
• URL: https://stamped.io/api/v2/{storeHash}/reviews
• Watch out for: Filtering by email returns reviews authored by that customer across all products.

Request example

GET /api/v2/{storeHash}/reviews?email=user%40example.com
Authorization: Basic <base64>

Response example

{
  "data": [
    {"reviewId": "abc123", "rating": 5, "body": "Great product!"}
  ],
  "total": 1
}

Create loyalty transaction (reward event)

• Method: POST
• URL: https://stamped.io/api/v2/{storeHash}/loyalty/transactions
• Watch out for: Custom transaction types must be pre-configured in the loyalty program settings before use via API.

Request example

POST /api/v2/{storeHash}/loyalty/transactions
Content-Type: application/json

{"email":"user@example.com","type":"custom","points":25,"note":"Referral bonus"}

Response example

{
  "transactionId": "txn_001",
  "email": "user@example.com",
  "points": 25,
  "type": "custom"
}

Get loyalty program tiers

• Method: GET
• URL: https://stamped.io/api/v2/{storeHash}/loyalty/tiers
• Watch out for: Tier configuration is read-only via API; changes must be made in the Stamped dashboard.

Request example

GET /api/v2/{storeHash}/loyalty/tiers
Authorization: Basic <base64>

Response example

{
  "tiers": [
    {"name": "Silver", "minPoints": 0},
    {"name": "Gold", "minPoints": 500}
  ]
}

• Rate limits: Stamped.io does not publicly document specific rate limit thresholds or per-plan tiers in their developer docs as of the research date.

• Rate-limit headers: No

• Retry-After header: No

• Rate-limit notes: No explicit rate limit documentation found in official sources. Contact Stamped support for enterprise rate limit details.

• Pagination method: offset

• Default page size: 20

• Max page size: 100

• Pagination pointer: page and limit (or per)

• Webhooks available: Yes

• Webhook notes: Stamped.io supports outbound webhooks that fire on review and loyalty events. Webhooks are configured in the dashboard under Settings > Webhooks.

• Alternative event strategy: Polling the reviews and customers endpoints is an alternative for integrations that cannot receive inbound webhooks.

• Webhook events: review.created, review.published, review.updated, loyalty.points_earned, loyalty.points_redeemed, loyalty.tier_changed

• SCIM available: No
• SCIM version: Not documented
• Plan required: Not documented
• Endpoint: Not documented

Limitations:

• Stamped.io does not offer a SCIM 2.0 endpoint for identity provider provisioning.
• No IdP integrations (Okta, Entra ID, Google Workspace, OneLogin) are documented.
• User/customer management is handled via the proprietary REST API only.

Three integration patterns are well-supported by the documented API surface:

• Sync and seed on first purchase: POST to /api/v2/{storeHash}/customers (upsert by email) with customer identity fields, then POST to /api/v2/{storeHash}/loyalty/transactions to award initial points. Re-sending the same email on subsequent orders updates rather than duplicates the record - confirm idempotency behavior in your integration tests.

• Bulk customer export for CRM sync: GET /api/v2/{storeHash}/customers?page=1&limit=100, calculate total pages from the response 'total' field, and iterate by incrementing 'page'. Offset pagination with large datasets may return inconsistent results if records are modified mid-export; no cursor-based alternative is documented.

• Loyalty tier change notifications via webhook: Configure a webhook in Settings > Webhooks for the 'loyalty.tier_changed' event. Stamped POSTs the customer email, old tier, and new tier to your endpoint. Webhook retry behavior is not documented; implement idempotency on your receiver using payload identifiers.

Sync a new customer and seed loyalty points on first purchase

1. POST to /api/v2/{storeHash}/customers with email, firstName, lastName, and customerId from your platform.
2. POST to /api/v2/{storeHash}/loyalty/transactions with action type 'purchase' and the order value to award initial points.
3. GET /api/v2/{storeHash}/customers/{email} to confirm the points balance and tier assignment.

Watch out for: The upsert behavior of the customer POST means re-sending the same email on subsequent orders will update rather than duplicate the record.

Bulk export customers for an external CRM sync

1. GET /api/v2/{storeHash}/customers?page=1&limit=100 to retrieve the first page.
2. Inspect the 'total' field in the response to calculate the number of pages (ceil(total / 100)).
3. Iterate pages by incrementing the 'page' parameter until all records are retrieved.
4. Map Stamped customer fields (email, firstName, lastName, points, tier) to CRM contact fields.

Watch out for: No cursor-based pagination is available; offset pagination with large datasets may return inconsistent results if records are modified during the export.

Trigger a loyalty tier upgrade notification via webhook

1. In the Stamped dashboard, configure a webhook URL under Settings > Webhooks for the 'loyalty.tier_changed' event.
2. When a customer's points cross a tier threshold, Stamped fires a POST to your endpoint with the customer email, old tier, and new tier.
3. Your endpoint processes the payload and triggers a downstream notification (e.g., email, push) to the customer.

Watch out for: Webhook delivery reliability and retry behavior are not documented; implement idempotency on your receiving endpoint using the event payload's unique identifiers.

The primary integration trap is assuming Stamped.io's API can serve as a staff identity or access management layer - it cannot. The API is scoped to customer loyalty and review data; internal operator/staff account management is not exposed.

Rate limits are entirely undocumented; aggressive polling against the customers or reviews endpoints may trigger undocumented throttling with no Retry-After header to guide backoff. Pagination parameter naming varies between endpoint families (reviews vs.

customers vs. loyalty), requiring per-endpoint verification rather than a single shared client pattern. No versioning deprecation policy is published, so breaking changes carry no guaranteed advance notice - monitor the developer changelog actively.

For teams using an MCP server with 60+ deep IT/identity integrations to maintain a cross-tool identity graph, Stamped.io's customer fields (email, tier, points, totalSpend, tags) are joinable on email but represent customer-side data only; do not conflate them with internal staff identity signals.