Build a custom integration

​

High-level flow

1. Identify the customer. Look up a customer with GET /v2/loyalty/programs/{programId}/customers, or create one with POST /v2/loyalty/programs/{programId}/customers. A local phone number matches the stored E.164 value using the program country.
2. Record activity. Add points with POST /v2/loyalty/programs/{programId}/customers/{customerId}/points/add. Read program transactions with GET /v2/loyalty/programs/{programId}/transactions.
3. Surface state back to the user. Fetch the wallet pass URL, point balance, or gift card balance to display in your UI.

​

A minimal example

# 1. Create the customer
curl -sS -X POST "$LOYALTYDOG_API_URL/loyalty/programs/prog_123/customers" \
  -H "Authorization: Bearer $LOYALTYDOG_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 11111111-2222-4333-8444-555555555555" \
  -d '{
    "email": "[email protected]"
  }'

# 2. Award points
curl -sS -X POST "$LOYALTYDOG_API_URL/loyalty/programs/prog_123/customers/cust_456/points/add" \
  -H "Authorization: Bearer $LOYALTYDOG_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 66666666-7777-4888-8999-aaaaaaaaaaaa" \
  -d '{
    "points": 50
  }'

​

Best practices

• Make calls idempotent. Send an Idempotency-Key header on customer creates and points writes. Use a new UUID for each operation, and send that same key again when you retry it. See Idempotency.
• Handle 429s gracefully. Back off when you see rate-limit responses and respect the Retry-After header.
• Subscribe to webhooks. Don’t poll for state changes — let LoyaltyDog notify you. See Webhooks.
• Scope tokens per integration. Use a dedicated app key for each integration so you can rotate or revoke without impacting other systems.

​

Reference