Lots API endpoints for querying and managing value tranches
Lots are individual tranches of value within a wallet. Each lot tracks its own balance, attributes, expiration, and restrictions. The system automatically manages lots during credits, transfers, and debits.
Retrieve details of a specific lot.
Parameter Type Description lot_idstring The lot ID (e.g., lot_xyz789abc123)
curl -X GET {{BASE_URL}}/lots/{{LOT_ID}} \ -H " Authorization: Bearer {{API_KEY}} " { " data " : { " id " : " lot_xyz789abc123 " , " wallet_id " : " wal_abc123def456 " , " asset " : " POINTS " , " initial_amount " : " 500.00 " , " current_amount " : " 350.00 " , " reserved_amount " : " 50.00 " , " available_amount " : " 300.00 " , " status " : " active " , " expires_at " : " 2024-12-31T23:59:59Z " , " attributes " : { " source " : " promotion " , " campaign " : " winter_2024 " , " tier_multiplier " : 1.5 } , " restrictions " : [ { " type " : " category " , " allowed " : [ " merchandise " , " food " ] } ] , " source " : { " type " : " credit " , " id " : " crd_xyz789abc123 " , " reference " : " purchase_order_789 " } , " created_at " : " 2024-01-15T10:30:00Z " , " updated_at " : " 2024-01-20T14:00:00Z " } } Code Description LOT_NOT_FOUNDNo lot exists with this ID
Retrieve all lots for a specific wallet.
GET /wallets/{{WALLET_ID}}/lots Parameter Type Description wallet_idstring The wallet ID
Parameter Type Default Description limitinteger 20 Number of results (max 100) cursorstring - Pagination cursor assetstring - Filter by asset type statusstring - Filter by status: active, depleted, expired has_balanceboolean - Filter to lots with remaining balance expiring_beforestring - Filter lots expiring before date (ISO 8601) attributestring - Filter by attribute (format: key:value)
curl -X GET " {{BASE_URL}}/wallets/{{WALLET_ID}}/lots?status=active&has_balance=true&asset=POINTS " \ -H " Authorization: Bearer {{API_KEY}} " { " data " : [ { " id " : " lot_xyz789abc123 " , " wallet_id " : " wal_abc123def456 " , " asset " : " POINTS " , " current_amount " : " 350.00 " , " reserved_amount " : " 50.00 " , " available_amount " : " 300.00 " , " status " : " active " , " expires_at " : " 2024-12-31T23:59:59Z " , " attributes " : { " source " : " promotion " , " campaign " : " winter_2024 " } , " created_at " : " 2024-01-15T10:30:00Z " } , { " id " : " lot_abc456def789 " , " wallet_id " : " wal_abc123def456 " , " asset " : " POINTS " , " current_amount " : " 200.00 " , " reserved_amount " : " 0.00 " , " available_amount " : " 200.00 " , " status " : " active " , " expires_at " : null , " attributes " : { " source " : " purchase " } , " created_at " : " 2024-01-10T08:00:00Z " } ] , " pagination " : { " has_more " : false , " next_cursor " : null } } Retrieve the transaction history for a specific lot.
GET /lots/{{LOT_ID}}/history Parameter Type Description lot_idstring The lot ID
Parameter Type Default Description limitinteger 20 Number of results (max 100) cursorstring - Pagination cursor
curl -X GET " {{BASE_URL}}/lots/{{LOT_ID}}/history?limit=10 " \ -H " Authorization: Bearer {{API_KEY}} " { " data " : [ { " id " : " evt_001 " , " type " : " lot.created " , " amount " : " 500.00 " , " balance_after " : " 500.00 " , " source " : { " type " : " credit " , " id " : " crd_xyz789abc123 " } , " created_at " : " 2024-01-15T10:30:00Z " } , { " id " : " evt_002 " , " type " : " lot.reserved " , " amount " : " -100.00 " , " balance_after " : " 400.00 " , " source " : { " type " : " reservation " , " id " : " rsv_abc123def456 " } , " created_at " : " 2024-01-16T14:00:00Z " } , { " id " : " evt_003 " , " type " : " lot.debited " , " amount " : " -50.00 " , " balance_after " : " 350.00 " , " source " : { " type " : " transfer " , " id " : " txf_lmn123opq456 " } , " created_at " : " 2024-01-17T09:00:00Z " } ] , " pagination " : { " has_more " : false , " next_cursor " : null } } Modify the attributes of a lot. This does not affect the lot's balance.
Parameter Type Description lot_idstring The lot ID
Field Type Required Description attributesobject No Merge with existing attributes (set value to null to remove) restrictionsarray No Replace all restrictions
curl -X PATCH {{BASE_URL}}/lots/{{LOT_ID}} \ -H " Authorization: Bearer {{API_KEY}} " \ -H " Content-Type: application/json " \ -H " Idempotency-Key: {{IDEMPOTENCY_KEY}} " \ -d ' { "attributes": { "tier_multiplier": 2.0, "old_attribute": null } } ' { " data " : { " id " : " lot_xyz789abc123 " , " wallet_id " : " wal_abc123def456 " , " asset " : " POINTS " , " current_amount " : " 350.00 " , " status " : " active " , " attributes " : { " source " : " promotion " , " campaign " : " winter_2024 " , " tier_multiplier " : 2.0 } , " updated_at " : " 2024-01-20T15:00:00Z " } } Code Description LOT_NOT_FOUNDNo lot exists with this ID LOT_IMMUTABLELot cannot be modified (e.g., depleted or expired)
Manually expire a lot before its scheduled expiration date.
POST /lots/{{LOT_ID}}/expire Parameter Type Description lot_idstring The lot ID
Field Type Required Description reasonstring No Reason for manual expiration
curl -X POST {{BASE_URL}}/lots/{{LOT_ID}}/expire \ -H " Authorization: Bearer {{API_KEY}} " \ -H " Content-Type: application/json " \ -H " Idempotency-Key: {{IDEMPOTENCY_KEY}} " \ -d ' { "reason": "Promotional campaign ended early" } ' { " data " : { " id " : " lot_xyz789abc123 " , " wallet_id " : " wal_abc123def456 " , " asset " : " POINTS " , " current_amount " : " 350.00 " , " expired_amount " : " 350.00 " , " status " : " expired " , " expiration_reason " : " Promotional campaign ended early " , " expires_at " : " 2024-12-31T23:59:59Z " , " expired_at " : " 2024-01-20T15:00:00Z " } } Code Description LOT_NOT_FOUNDNo lot exists with this ID LOT_ALREADY_EXPIREDLot is already expired LOT_HAS_RESERVATIONSCannot expire lot with active reservations
Get a summary of lots expiring within a time range.
GET /wallets/{{WALLET_ID}}/lots/expiring Parameter Type Description wallet_idstring The wallet ID
Parameter Type Default Description daysinteger 30 Number of days to look ahead assetstring - Filter by asset type
curl -X GET " {{BASE_URL}}/wallets/{{WALLET_ID}}/lots/expiring?days=7&asset=POINTS " \ -H " Authorization: Bearer {{API_KEY}} " { " data " : { " wallet_id " : " wal_abc123def456 " , " period " : { " from " : " 2024-01-20T00:00:00Z " , " to " : " 2024-01-27T00:00:00Z " } , " summary " : [ { " asset " : " POINTS " , " total_expiring " : " 750.00 " , " lot_count " : 3 } ] , " lots " : [ { " id " : " lot_xyz789abc123 " , " asset " : " POINTS " , " available_amount " : " 300.00 " , " expires_at " : " 2024-01-22T23:59:59Z " } , { " id " : " lot_abc456def789 " , " asset " : " POINTS " , " available_amount " : " 250.00 " , " expires_at " : " 2024-01-25T23:59:59Z " } , { " id " : " lot_def789ghi012 " , " asset " : " POINTS " , " available_amount " : " 200.00 " , " expires_at " : " 2024-01-26T23:59:59Z " } ] } } Status Description activeLot has remaining balance and is not expired depletedLot balance has been fully used expiredLot has passed its expiration date
Event Type Description lot.createdLot was created (via credit) lot.reservedFunds were reserved from the lot lot.releasedReserved funds were released lot.debitedFunds were debited (transfer or commit) lot.expiredLot expired (automatic or manual) lot.attributes_updatedLot attributes were modified
