Suki.Cards Developer API Documentation #

Version: 2.0.0

This documentation outlines the endpoints, authentication methods, and integration recipes for the Suki.Cards platform. This API allows you to manage digital wallet passes, process loyalty transactions, sync customer data, and automate workflows via tools like n8n.

---

1. General Information #

Base URL #

All API requests must be made to the following base URL:

https://api.digitalwallet.cards/api/v2

Authentication #

The API requires authentication via specific HTTP Headers. You must include your API Key in every request.

Header Name	Value	Description
X-API-Key	{YOUR_API_KEY}	Used for standard resources (Cards, Customers, Reports).
X-App-Token	{YOUR_APP_TOKEN}	Used specifically for Marketplace/POS integration endpoints.
Content-Type	application/json	Required for all POST/PATCH requests.

---

2. Card Management #

These endpoints allow you to issue, retrieve, and update digital cards.

List Cards #

Retrieve a list of cards. This is useful for finding cards based on status (e.g., expired) or customer data.

Endpoint: GET /cards

Query Parameters:

• templateId (int): Filter by specific card design.
• customerId (uuid): Filter by customer UUID.
• customerPhone (string): Search by phone.
• customerEmail (string): Search by email.
• status (string): Filter by status (e.g., expired, active).
• page (int): Page number.
• itemsPerPage (int): Results per page (max 1000).

Create Card #

Issue a new card to a customer.

Endpoint: POST /cards

{
  "templateId": 123,                 // Required: The ID of the card template
  "customerId": "uuid-string",       // Required: The Customer's UUID
  "customFields": []                 // Optional: Custom fields defined in template
}

Edit Card (Batch or Single) #

Update card details, often used in automation flows (like your n8n workflow).

Endpoint: PATCH /cards/{id} (or /cards for batch operations depending on implementation).

{
  "customFields": [
    { "id": "field_name", "value": "New Value" }
  ]
}

Set Expiration Date #

Endpoint: POST /cards/{id}/set-expiration-date
Body: {"expiresAt": "2025-12-31T23:59:59+00:00"}

---

3. Transactions (Loyalty Accrual) #

Use these endpoints to add Stamps, Points, or Visits when a user makes a purchase.

Path Parameter: id = The Card Serial Number.

Action	Endpoint	Payload JSON
Add Stamps	POST /cards/{id}/add-stamp	{"stamps": 1, "purchaseSum": 10.00}
Add Points	POST /cards/{id}/add-point	{"points": 50, "purchaseSum": 10.00}
Add Visit	POST /cards/{id}/add-visit	{"visits": 1, "purchaseSum": 0}
Add Cash	POST /cards/{id}/add-transaction-amount	{"amount": 25, "purchaseSum": 25.00}
Add Scores	POST /cards/{id}/add-scores	{"scores": 10, "comment": "Bonus"}

Redemptions (Subtracting) #

To redeem rewards or correct errors, use the subtract endpoints:

• POST /cards/{id}/subtract-stamp
• POST /cards/{id}/subtract-point
• POST /cards/{id}/subtract-visit
• POST /cards/{id}/receive-reward (Body: {"id": "reward_tier_id"})

---

4. Customer Management #

List Customers #

Endpoint: GET /customers
Useful for syncing your CRM with Suki.Cards.

Query Parameters: phone, email, page, itemsPerPage.

Create Customer #

Endpoint: POST /customers

{
  "firstName": "Jane",
  "surname": "Doe",
  "phone": "+15550199",        // Required
  "email": "jane@example.com",
  "dateOfBirth": "1990-05-20"
}

---

5. Marketplace / POS Integration #

These endpoints are designed for Point of Sale systems to process transactions without needing the Card ID upfront. The system finds the user by phone/email/serial.

Accrual Action #

Endpoint: POST /marketplace/accrue
Header: X-App-Token (Required)

{
  "transactionId": "POS_TX_999", // Unique POS ID
  "phone": "+15550199",          // Identify user by Phone, Email, or Serial
  "check": {
    "amount": 55.00,
    "currency": "USD"
  },
  "credentials": [{}]
}

---