/assets

Overview

This endpoint retrieves asset transaction history (punch cards and gifts) for the business. Unlike /member/assets, this endpoint does not require a specific member to be identified and returns transactions across all members, similar to /payments.

When to Use This Endpoint

Use this endpoint in the following cases:

• To generate business-wide reports on gift or punch card asset activity
• To analyze loyalty program asset usage across all members
• To audit or review all asset redemptions and distributions in the system
• To export asset transaction data for business intelligence purposes

Key Considerations

• The assetType parameter determines whether to retrieve gift, punch card, or all asset transactions
• Results can be filtered by date range using fromDate and toDate
• Pagination is supported through limit and offset parameters
• Does not require a specific member to be identified
• Returns transactions with member identification (membershipKey) included
• The type field reflects the campaign kind (Gift or PunchCard)

Request Details

Method & URL

POST /assets

See API Servers for the base URL to use in place of {{server}}.

Headers

Header	Type	Required	Description
x-api-key	string	Yes	API key for authentication
x-source-type	string	Yes	Origin of the request (e.g., POS, Web)
x-source-name	string	Yes	Name of the client or integration system
x-pos-id	string	Yes	POS terminal identifier
x-branch-id	string	Yes	Branch or store location identifier

Request Body

Field	Type	Required	Default	Description
assetType	string	Yes	—	Type of asset: gift, punchCard, or all
limit	integer	No	40	Max number of records (1–100)
offset	integer	No	0	Records to skip for pagination (≥0)
fromDate	string	No	—	Filter start date (ISO 8601 format)
toDate	string	No	—	Filter end date (ISO 8601 format)

Request Example

curl --location --request POST 'https://{{server}}/v1/assets' \
--header 'Content-Type: application/json' \
--header 'x-api-key: {{api-key}}' \
--header 'x-source-type: POS' \
--header 'x-source-name: pos_terminal_01' \
--header 'x-pos-id: POS001' \
--header 'x-branch-id: BR001' \
--data-raw '{
  "assetType": "gift",
  "limit": 20,
  "offset": 0,
  "fromDate": "2024-01-01T00:00:00Z",
  "toDate": "2024-12-31T23:59:59Z"
}'

Success Response

{
  "status": "success",
  "transactions": [
    {
      "transactionId": "confirmation-uuid-or-db-id",
      "confirmation":  "transactions-uuid",
      "createdAt": "2024-06-15T14:30:00.000Z",
      "operation": "ReceiveAsset",
      "type": "Gift",
      "amount": 1,
      "membershipKey": "abc123",
      "assetId": "campaign-object-id"
    },
    {
      "transactionId": "conf-uuid-2",
      "confirmation":  "transactions-uuid",
      "createdAt": "2024-06-10T12:15:00.000Z",
      "operation": "Punched",
      "type": "PunchCard",
      "amount": 1,
      "membershipKey": "def456",
      "assetId": "campaign-object-id-2"
    }
  ]
}

Response Fields

Field	Type	Description
status	string	Request status indicator
transactions	array	Array of transaction objects
transactionId	string	Unique identifier for the transaction (confirmation or DB _id)
confirmation	string	Unique identifier for the transaction (transactionId)
createdAt	string	ISO 8601 timestamp of the transaction
operation	string	Operation type: Punched, ReceiveAsset, RedeemAsset
type	string	Campaign kind with capital letter: Gift or PunchCard
amount	number	Transaction amount
membershipKey	string	The member's membership key
assetId	string	The campaign/asset ID the transaction belongs to

Error Response Examples

Missing Required Header

{
  "status": "error",
  "error": {
    "code": "101",
    "message": "Missing X-Api-Key header"
  }
}

Invalid Asset Type

{
  "status": "error",
  "error": {
    "code": "1006",
    "message": "Invalid or missing assetType. Must be 'gift', 'punchCard', or 'all'"
  }
}

Invalid Date Format

{
  "status": "error",
  "error": {
    "code": "1002",
    "message": "Invalid fromDate format. Use ISO 8601 format"
  }
}

Error Codes

Code	Description
101	Missing X-Api-Key header
102	Missing X-Source-Type header
103	Missing X-Source-Name header
104	Missing X-Pos-Id header
105	Missing X-Branch-Id header
1006	Invalid or missing assetType. Must be gift, punchCard, or all
1002	Invalid fromDate format. Use ISO 8601 format
1003	Invalid toDate format. Use ISO 8601 format
1011	Invalid limit (must be an integer between 1 and 100)
1012	Invalid offset (must be an integer of 0 or more)
1010	Internal server error

Related Use Cases

• Generating business-wide gift and punch card transaction reports
• Analyzing asset program performance and usage patterns
• Auditing all asset distributions and redemptions across the business
• Exporting asset transaction data for accounting or business intelligence
• Monitoring loyalty program health through asset engagement metrics