Round Up

Round-Up rounds each eligible transaction up to the next whole dollar (or a fixed/boosted amount you configure) and, on a fixed cadence, sweeps the accumulated round-ups from a funding account into a destination account.

This guide explains how Round-Up works and walks through testing the entire flow end-to-end in sandbox: link an external bank, inject synthetic transactions with the linked-institution simulation endpoints, and observe round-ups accrue and sweep, without moving real money.

Round-Up can track two kinds of accounts:

• Spidr accounts: a card/deposit account issued on your Spidr program.
• Linked institution accounts: an external bank the user connected via Plaid (transaction aggregation).

This guide focuses on the linked institution path, because the simulation endpoints let you drive it entirely from the API.

Quick Start: the sandbox test loop

1. Link an external bank for transaction aggregation:
   session/create, then session/simulate-link (dynamicTransactions: true), then session/complete
2. Enroll in Round-Up, tracking the linked institution account:
   POST /v1/roundup/create
3. Inject transactions on the linked bank:
   POST /ztm/v1/linked-institution/{id}/simulate-transactions
4. Verify the round-ups landed:
   GET /ztm/v1/linked-institution/{id}/transactions, where each row in data.rows carries a roundUp array
5. Sweep on cadence, then review results via GET /v1/roundup/{id}/listSweepTransfers

Important: the institution must be linked with dynamicTransactions: true on session/simulate-link. Plaid only materializes injected transactions on its user_transactions_dynamic sandbox user; on the default sandbox test user, simulate-transactions succeeds but the transactions never appear.

The dynamic user is a package deal: along with injection support, the linked accounts arrive with a generated transaction history (typically 100+ rows) and keep producing new transactions on their own. Locate your injected rows by amount, not by description or row counts (see Step 4).

How Round-Up Works

A Round-Up enrollment ties together three account roles:

Each transaction on a tracking account is evaluated as it is ingested (for linked institutions, when the transaction syncs from the provider). If it is eligible, a roundUp entry is stamped on it. On the configured cadence, a sweep job aggregates the accrued round-ups, applies the caps, pulls the total from the funding account(s), and deposits it into the receiving account(s).

Calculation modes

Cadence

Eligibility filters (optional)

By default, every transaction on a tracking account is eligible. You can narrow that:

Credits, refunds, and cash-back are never rounded up. Only outflows (purchases) accrue round-ups.

Prerequisites

• A sandbox environment. The simulation endpoints refuse to run in production or against a non-sandbox Plaid configuration.
• Your API key (apikey header) for the sandbox environment.
• A user with a Spidr funding account and a Spidr receiving (destination) account.
• The receiving product must have Round-Up enabled (the roundup account feature). Without it, POST /v1/roundup/create returns ROUNDUP_NOT_ENABLED.
• For linked institution tracking, the tracking product must be enrolled for Plaid transaction_aggregation. If only account_linking is enrolled, session/create with transaction_aggregation returns ZTM_PRODUCT_NOT_ENROLLED, and you cannot produce a linked_institution_account to track.

All example IDs below are placeholders. Substitute your own.

Step 1: Link an External Bank for Transaction Aggregation

Round-Up on a linked institution needs real transaction data flowing in, so link with the transaction_aggregation service.

Do the full sandbox link with three calls. This mirrors the Linked Institution Integration Guide, with one addition: dynamicTransactions: true.

1a. Create the session

API Reference: Create Linked Institution Session

POST /ztm/v1/linked-institution/session/create
Content-Type: application/json
apikey: <your-api-key>
x-client-request-id: <unique-request-id>

{
  "userId": "6984f595c07bda200b0e92d6",
  "productId": "6823a83e59a0f48f78787c29",
  "provider": "plaid",
  "services": ["account_linking", "transaction_aggregation"],
  "providerOptions": {
    "displayName": "My App"
  }
}

Save data.linkedInstitutionSessionId from the response.

1b. Simulate the Plaid Link flow

Instead of driving the Plaid UI, generate a sandbox publicToken directly. Set dynamicTransactions: true so the item can receive injected transactions.

API Reference: Simulate Plaid Link

POST /ztm/v1/linked-institution/session/simulate-link
Content-Type: application/json
apikey: <your-api-key>
x-client-request-id: <unique-request-id>

{
  "linkedInstitutionSessionId": "678abc123def456789012345",
  "institutionId": "ins_109508",
  "dynamicTransactions": true
}

dynamicTransactions: true cuts both ways: the same sandbox user that accepts injected transactions also arrives with a canned transaction backlog and keeps generating new transactions on its own. Those organic transactions flow through the same ingestion pipeline, so once your enrollment is active they accrue round-ups too. There is no injection-only "quiet" mode. Pause or close test enrollments when you are done with them, or they keep accruing indefinitely.

Response:

{
  "status": "success",
  "data": {
    "publicToken": "public-sandbox-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "linkedInstitutionSessionId": "678abc123def456789012345"
  }
}

1c. Complete the session

API Reference: Complete Linked Institution Session

POST /ztm/v1/linked-institution/session/complete
Content-Type: application/json
apikey: <your-api-key>
x-client-request-id: <unique-request-id>

{
  "linkedInstitutionSessionId": "678abc123def456789012345",
  "providerOptions": {
    "publicToken": "public-sandbox-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

From the response, save two IDs:

• data.linkedInstitutions[0].id, the linkedInstitutionId (used for simulate-transactions and transactions)
• data.linkedInstitutions[0].accounts[0].linkedInstitutionAccountId, the account you will track for round-ups

Step 2: Create a Round-Up Enrollment

Enroll the user, tracking the linked institution account captured in Step 1. Funding pulls from a Spidr account; the swept funds land in a Spidr receiving account.

API Reference: Create Round-Up Enrollment

POST /v1/roundup/create
Content-Type: application/json
apikey: <your-api-key>
x-client-request-id: <unique-request-id>

{
  "calculationMode": "round_to_nearest_dollar",
  "cadence": "weekly",
  "cadenceKey": 5,
  "cadenceMaxAmount": 50,
  "minimumSweepAmount": 1,
  "eligibleCategories": [
    { "type": "category", "value": "dining" },
    { "type": "category", "value": "transportation" }
  ],
  "trackingAccounts": [
    { "type": "linked_institution_account", "trackingAccountId": "6985060d649259b23141a602" }
  ],
  "fundingAccounts": [
    { "type": "spidr", "fundingAccountId": "6823a83e59a0f48f78787c30", "fundingPercentage": 100 }
  ],
  "receivingAccounts": [
    { "type": "spidr", "receivingAccountId": "6823a83e59a0f48f78787c31", "allocationPercentage": 100 }
  ]
}

Request Fields

Tracking account: { type, trackingAccountId } where type is spidr or linked_institution_account.

Funding account: { type, fundingAccountId, fundingPercentage, cadenceMaxAmount?, minimumBalance? } where type is spidr or ach_account. fundingPercentage (> 0, <= 100) is required and all funding percentages must total 100.

Receiving account: { type, receivingAccountId, allocationPercentage } where type is spidr. allocationPercentage (> 0, <= 100) is required and all allocation percentages must total 100.

The enrollment userId is derived from the tracking/funding account owners, so you do not pass it. The receiving account must belong to that user unless the receiving product allows cross-user receiving; otherwise the call returns ROUNDUP_RECEIVING_ACCOUNT_USER_MISMATCH.

Response

{
  "status": "success",
  "data": {
    "id": "69860a1f649259b23141a7c4",
    "companyId": "698609f0649259b23141a7b0",
    "userId": "6984f595c07bda200b0e92d6",
    "status": "active",
    "calculationMode": "round_to_nearest_dollar",
    "currencyCode": "USD",
    "eligibleCategories": [
      { "type": "category", "value": "dining" },
      { "type": "category", "value": "transportation" }
    ],
    "cadence": "weekly",
    "cadenceKey": 5,
    "cadenceMaxAmount": 50,
    "minimumSweepAmount": 1,
    "trackingAccounts": [
      { "type": "linked_institution_account", "trackingAccountId": "6985060d649259b23141a602" }
    ],
    "fundingAccounts": [
      { "type": "spidr", "fundingAccountId": "6823a83e59a0f48f78787c30", "fundingPercentage": 100 }
    ],
    "receivingAccounts": [
      { "type": "spidr", "receivingAccountId": "6823a83e59a0f48f78787c31", "allocationPercentage": 100 }
    ],
    "createdAt": "2026-07-06T14:02:11.000Z",
    "updatedAt": "2026-07-06T14:02:11.000Z",
    "spidrActionId": "69860a1f649259b23141a7c6"
  }
}

Save data.id, the enrollment ID, used to inspect sweeps. Enrollment write responses (create, update, updateStatus) also carry a spidrActionId for audit correlation.

Funding from a separate linked bank (ACH)

Funding accepts only spidr or ach_account, never linked_institution_account. To fund a sweep from an external bank (optionally a different bank than the one you track), link that bank with the account_linking service and register its account as an ach_account, then reference that ACH account as funding.

1. Link bank B with the same three-call flow as Step 1, but services: ["account_linking"] is enough (transaction_aggregation is not needed for funding).
2. Create an ACH account from bank B's linked account. POST /v1/achaccount/create accepts a linkedInstitutionAccountId and resolves the routing/account numbers for you:

POST /v1/achaccount/create
apikey: <your-api-key>
x-client-request-id: <unique-request-id>

{
  "accountId": "<a spidr account owned by the user>",
  "linkedInstitutionAccountId": "<bank B depository account id>",
  "name": "Jane Doe",
  "firstName": "Jane",
  "lastName": "Doe",
  "type": "checking"
}

Save data.achAccountId.
3. In the enrollment, set funding to that ACH account:

"fundingAccounts": [
  { "type": "ach_account", "fundingAccountId": "<achAccountId>", "fundingPercentage": 100 }
]

This yields the common configuration of tracking one external bank while funding from another: a linked_institution_account for tracking, and an ach_account sourced from the second bank for funding. Both are external banks; only the funding side runs through an ACH account.

Step 3: Simulate Transactions

This is the core of sandbox testing. Inject synthetic transactions onto the linked bank; Spidr runs them through the real ingestion pipeline exactly like organic transactions.

API Reference: Simulate Transactions

POST /ztm/v1/linked-institution/6985060d649259b23141a601/simulate-transactions
Content-Type: application/json
apikey: <your-api-key>
x-client-request-id: <unique-request-id>

{
  "transactions": [
    { "description": "Starbucks",       "amount": 4.35 },
    { "description": "Uber",            "amount": 18.72 },
    { "description": "Shell Oil",       "amount": 41.10 },
    { "description": "Refund - Amazon", "amount": -12.00 }
  ],
  "triggerSync": true
}

Or with curl:

curl -X POST "https://api.gospidr.com/ztm/v1/linked-institution/6985060d649259b23141a601/simulate-transactions" \
  -H "Content-Type: application/json" \
  -H "apikey: $SPIDR_API_KEY" \
  -H "x-client-request-id: $(uuidgen)" \
  -d '{
    "transactions": [
      { "description": "Starbucks", "amount": 4.35 },
      { "description": "Uber", "amount": 18.72 }
    ]
  }'

Request Fields

Controlling the category

Use merchant-like descriptions to steer categorization:

Category assignment is ultimately determined by Plaid. When testing eligibleCategories, assert on the mapped Spidr category after sync rather than assuming a specific one up front.

Plaid also normalizes the merchant name it stores: Shell Oil comes back as Shell, and Refund - Amazon comes back as Amazon. Do not expect your exact description text in the synced rows; match injected rows by amount.

Response

{
  "status": "success",
  "data": {
    "linkedInstitutionId": "6985060d649259b23141a601",
    "transactionsCreated": 4,
    "syncEnqueued": true
  }
}

The Plaid injection is all-or-nothing: transactionsCreated reflects the whole batch.

Timing matters. Give the link a moment to settle before injecting: a batch created within the first seconds after session/complete can be silently dropped by Plaid. The call still returns the full transactionsCreated count with a 200, but the rows never materialize, and no later sync recovers that batch. If nothing has appeared after ~30 seconds of polling in Step 4, re-inject the batch (a fresh simulate-transactions call also re-enqueues the sync).

Step 4: Verify the Round-Ups

Once the sync completes, fetch the linked institution's transactions. Each eligible transaction carries a roundUp array.

API Reference: Fetch Linked Institution Transactions

Note: the transactions are returned under data.rows, not data.transactions. Each row carries a roundUp array when it accrued. A round-up of 0 means the amount was already a whole dollar. Injected transactions can take a few seconds to sync; poll this endpoint until they appear. Two things to expect while polling:

• The list is not just your injections. The dynamic sandbox user arrives with its own transaction history (typically 100+ rows) and keeps generating more, so find your injected rows by amount: descriptions are normalized by Plaid, and row counts keep moving.
• Accrual can trail sync by a few seconds. A row can appear before its roundUp entry is stamped. Keep polling until the round-ups are present, not just the rows.

GET /ztm/v1/linked-institution/6985060d649259b23141a601/transactions?current=1&pageSize=50
apikey: <your-api-key>
x-client-request-id: <unique-request-id>

Query Parameters

Results are returned most recent first, with totalPages and totalRecords alongside rows.

Response (abridged rows)

{
  "status": "success",
  "data": {
    "rows": [
      {
        "transactionId": "6986113a649259b23141a812",
        "description": "Starbucks",
        "merchantDescription": "Starbucks",
        "amount": 4.35,
        "currencyCode": "USD",
        "status": "settled",
        "authDate": "2026-07-06",
        "postedDate": "2026-07-06",
        "category": "dining",
        "subCategory": "dining.coffee_shops",
        "linkedInstitutionAccountId": "6985060d649259b23141a602",
        "roundUp": [{ "amount": 0.65, "status": "pending" }]
      },
      {
        "description": "Uber",
        "amount": 18.72,
        "category": "transportation",
        "subCategory": "transportation.rideshare_and_taxi",
        "roundUp": [{ "amount": 0.28, "status": "pending" }]
      },
      {
        "description": "Shell",
        "amount": 41.10,
        "category": "transportation",
        "subCategory": "transportation.gas_and_fuel",
        "roundUp": [{ "amount": 0.90, "status": "pending" }]
      },
      {
        "description": "Amazon",
        "amount": -12.00,
        "category": "shopping"
      },
      {
        "description": "Madison Bicycle Shop",
        "amount": 78.23,
        "category": "shopping"
      }
    ],
    "totalPages": 3,
    "totalRecords": 122
  }
}

Note:

• $4.35 gives $0.65, $18.72 gives $0.28, and $41.10 gives $0.90, rounded up to the next dollar.
• Plaid normalized the injected descriptions: Shell Oil is stored as Shell, and Refund - Amazon as Amazon. This is why you match injected rows by amount.
• The refund is a credit (negative amount), so it has no roundUp.
• Madison Bicycle Shop is one of the dynamic user's own generated transactions (hence totalRecords: 122). It has no roundUp because it synced before the enrollment existed; organic rows that sync after the enrollment is active accrue like any other transaction, subject to your eligibility filters.
• roundUp is an array: a transaction matched by multiple enrollments gets one entry per enrollment.

Round-up entry statuses

Step 5: Sweep and Reconcile

Round-ups accumulate with status: "pending" until the sweep runs on your configured cadence. The sweep aggregates the period's round-ups (respecting cadenceMaxAmount and minimumSweepAmount), pulls the total from the funding account(s), and deposits it into the receiving account(s).

API Reference: List Round-Up Sweep Transfers
Review sweep results per enrollment:

GET /v1/roundup/69860a1f649259b23141a7c4/listSweepTransfers?current=1&pageSize=25
apikey: <your-api-key>
x-client-request-id: <unique-request-id>

Supports current (default 1) and pageSize (default 25, max 100) pagination, plus optional JSON-encoded filters and sort query parameters over status, currencyCode, sweepKey, period.startDate, period.endDate, createdAt, and updatedAt.

Each record shows how a cadence period's round-up total was calculated and the resulting funding and receiving transfers:

{
  "status": "success",
  "data": {
    "totalRecords": 1,
    "rows": [
      {
        "sweepId": "69875c02649259b23141a901",
        "sweepKey": "<period-key>",
        "status": "success",
        "currencyCode": "USD",
        "period": {
          "cadence": "weekly",
          "startDate": "2026-06-29T00:00:00.000Z",
          "endDate": "2026-07-05T23:59:59.999Z"
        },
        "calculation": {
          "eligibleTransactionCount": 3,
          "eligibleTransactionAmount": 64.17,
          "calculatedRoundUpAmount": 1.83,
          "cadenceMaxAmount": 50,
          "finalAmount": 1.83,
          "calculationMode": "round_to_nearest_dollar"
        },
        "fundingAccountTransfers": [
          {
            "type": "spidr",
            "fundingAccountId": "6823a83e59a0f48f78787c30",
            "amount": 1.83,
            "fundingPercentage": 100,
            "status": "success",
            "submittedAt": "2026-07-06T05:00:12.000Z",
            "completedAt": "2026-07-06T05:00:14.000Z"
          }
        ],
        "receivingAccountTransfers": [
          {
            "type": "spidr",
            "receivingAccountId": "6823a83e59a0f48f78787c31",
            "amount": 1.83,
            "allocationPercentage": 100,
            "status": "success"
          }
        ]
      }
    ]
  }
}

Sweep and transfer statuses

Individual funding/receiving transfers carry their own status (pending, submitted, success, failed, skipped) and an optional failureReason.

Sweeps run automatically on the configured cadence. There is currently no on-demand sweep trigger, so to observe a sweep during testing, use a cadence that fires within your test window (daily is the fastest: the enrollment is picked up by the next daily sweep run).

Managing the Enrollment

Beyond create, the enrollment has a full lifecycle API:

Pause, resume, or close with POST /v1/roundup/{id}/updateStatus. While an enrollment is paused, its sweeps are skipped (skipReason: "enrollment_paused"); closed ends the enrollment. The enrollment records pausedAt / resumedAt / closedAt timestamps.

POST /v1/roundup/69860a1f649259b23141a7c4/updateStatus
Content-Type: application/json
apikey: <your-api-key>
x-client-request-id: <unique-request-id>

{ "status": "paused" }

Reconfigure with PATCH /v1/roundup/{id}. Any subset of the create fields may be supplied; omitted fields are left unchanged. Use updateStatus (not PATCH) to change the lifecycle state.

Read with GET /v1/roundup/{id} for a single enrollment, or GET /v1/roundup/list for a paginated, filterable list of your enrollments.

Reference

Category values

eligibleCategories entries are { type, value }:

• type: "category": a top-level category.
• type: "subCategory": a more specific sub-category.

Category values (lowercase snake_case):

dining, groceries, shopping, transportation, travel, utilities, home, health_and_wellness, personal_care, entertainment, family_and_pets, education, professional_services, insurance, charity_and_giving, taxes_and_government, cash_out, income, transfers, loan_payments, fees_and_adjustments, uncategorized

Sub-category values use dot notation, <category>.<sub_category>, for example dining.coffee_shops, dining.fast_food, transportation.gas_and_fuel, transportation.rideshare_and_taxi, entertainment.cable_and_streaming. Transactions carry the same values in their category / subCategory fields, so read a few synced transactions to see which values your test data maps to.

Endpoint quick reference

Troubleshooting

Additional Resources

• Linked Institution Integration Guide
• Spidr API Reference
• Plaid Sandbox: Testing