--- updatedAt: 2026-06-24T17:15:43.000Z agentTools: projectIndex: https://docs.gospidr.com/llms.txt --- # Create Round-Up Enrollment Use ```/v1/roundup/create``` to create a round-up enrollment. The enrollment defines how round-ups are calculated for a user's tracked transactions, the cadence on which accumulated round-ups are swept, and the funding and receiving accounts used to move the money. At least one tracking, funding, and receiving account is required. # OpenAPI definition ````json { "openapi": "3.1.0", "info": { "title": "Unified API", "version": "0.0.1" }, "paths": { "/v1/roundup/create": { "post": { "operationId": "PostV1RoundupCreate", "summary": "Create Round-Up Enrollment", "description": "Use ```/v1/roundup/create``` to create a round-up enrollment. The enrollment defines how round-ups are calculated for a user's tracked transactions, the cadence on which accumulated round-ups are swept, and the funding and receiving accounts used to move the money. At least one tracking, funding, and receiving account is required.", "tags": [ "Round-Up" ], "requestBody": { "description": "POST /v1/roundup/create Request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostV1RoundupCreateRequestBody" } } } }, "security": [ { "APIKEY_1": [], "APIKEY_2": [] } ], "responses": { "200": { "description": "POST /v1/roundup/create Positive response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostV1RoundupCreatePositiveResponse" } } } }, "400": { "description": "POST /v1/roundup/create Negative response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostV1RoundupCreateNegativeResponse" } } } } } } } }, "components": { "schemas": { "PostV1RoundupCreatePositiveResponse": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the round-up enrollment." }, "companyId": { "type": "string", "description": "ID of the company that owns this round-up enrollment." }, "userId": { "type": "string", "description": "ID of the user who owns this round-up enrollment." }, "status": { "type": "string", "enum": [ "active", "paused", "closed" ], "description": "Current lifecycle status of the enrollment: `active`, `paused`, or `closed`." }, "calculationMode": { "type": "string", "enum": [ "round_to_nearest_dollar", "fixed_amount_per_transaction", "round_to_nearest_dollar_plus_boost" ], "description": "How each round-up contribution is calculated: `round_to_nearest_dollar`, `fixed_amount_per_transaction`, or `round_to_nearest_dollar_plus_boost`." }, "fixedAmount": { "type": "number", "format": "double", "exclusiveMinimum": 0, "maximum": 10000000, "description": "For `fixed_amount_per_transaction` mode, the flat amount contributed per eligible transaction." }, "boostAmount": { "type": "number", "format": "double", "exclusiveMinimum": 0, "maximum": 10000000, "description": "For `round_to_nearest_dollar_plus_boost` mode, the additional amount added to each round-to-nearest-dollar contribution." }, "currencyCode": { "type": "string", "description": "ISO 4217 three-letter currency code for the enrollment. Defaults to `USD`." }, "eligibleCategories": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "category", "subCategory" ], "description": "Whether the eligibility entry targets a primary `category` or a `subCategory`." }, "value": { "type": "string", "description": "The Spidr transaction category or subcategory value that is eligible for round-ups." } }, "required": [ "type", "value" ] }, "description": "Optional list of Spidr transaction categories or subcategories eligible for round-ups. When omitted, all categories are eligible." }, "eligibleMccCodes": { "type": "array", "items": { "type": "string" }, "description": "Optional list of merchant category codes (MCCs) eligible for round-ups. When omitted, all MCCs are eligible." }, "cadence": { "type": "string", "enum": [ "daily", "weekly", "biweekly", "monthly" ], "description": "How often accumulated round-ups are swept and transferred: `daily`, `weekly`, `biweekly`, or `monthly`." }, "cadenceKey": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 28, "description": "Day the sweep runs within the cadence period. For weekly and biweekly cadences this is the day of week (1-7); for monthly it is the day of month (1-28)." }, "cadenceMaxAmount": { "type": "number", "format": "double", "exclusiveMinimum": 0, "maximum": 10000000, "description": "Optional cap on the total round-up amount swept per cadence period." }, "minimumSweepAmount": { "type": "number", "format": "double", "minimum": 0, "maximum": 10000000, "description": "Optional minimum accumulated amount required before a sweep runs. Periods below this amount are skipped." }, "achHoldDays": { "type": "number", "format": "double", "minimum": -1.7976931348623157e+308, "maximum": 1.7976931348623157e+308, "description": "Optional number of days to hold ACH-funded amounts before transferring to receiving accounts. Must be at least the receiving product's configured minimum, and no more than 6. The upper bound is the window in which an undelivered sweep is automatically retried, so a longer hold would leave the funds sitting on the hub account with no automatic retry left." }, "pausedAt": { "type": "string", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?Z$", "description": "Timestamp when the enrollment was last paused (ISO-8601)." }, "pauseReason": { "type": "string", "enum": [ "user_requested", "retry_exhausted" ], "description": "Why the enrollment is paused: `user_requested` (manual) or `retry_exhausted` (a transfer-failure retry chain ran out of attempts). Absent when active." }, "resumedAt": { "type": "string", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?Z$", "description": "Timestamp when the enrollment was last resumed (ISO-8601)." }, "closedAt": { "type": "string", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?Z$", "description": "Timestamp when the enrollment was closed (ISO-8601)." }, "trackingAccounts": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "spidr", "linked_institution_account" ], "description": "Type of tracking account: `spidr` for a Spidr account, or `linked_institution_account` for an externally linked account." }, "trackingAccountId": { "type": "string", "description": "ID of the account whose transactions are tracked for round-ups." } }, "required": [ "type", "trackingAccountId" ] }, "description": "Accounts whose transactions are monitored to accumulate round-ups. At least one is required." }, "fundingAccounts": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "spidr", "ach_account" ], "description": "Type of funding account: `spidr` for a Spidr account, or `ach_account` for an external ACH account." }, "fundingAccountId": { "type": "string", "description": "ID of the account debited to fund round-up sweeps." }, "cadenceMaxAmount": { "type": "number", "format": "double", "exclusiveMinimum": 0, "maximum": 10000000, "description": "Optional cap on the amount drawn from this funding account per cadence period." }, "minimumBalance": { "type": "number", "format": "double", "minimum": 0, "maximum": 10000000, "description": "Optional minimum balance that must remain in this funding account; sweeps will not draw the balance below this amount." }, "fundingPercentage": { "type": "number", "format": "double", "exclusiveMinimum": 0, "maximum": 100, "description": "Percentage (greater than 0, up to 100) of each sweep funded from this account. Percentages across funding accounts should total 100." } }, "required": [ "type", "fundingAccountId", "fundingPercentage" ] }, "description": "Accounts debited to fund each sweep. At least one is required." }, "receivingAccounts": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "spidr" ], "description": "Type of receiving account. Currently only `spidr` is supported." }, "receivingAccountId": { "type": "string", "description": "ID of the account credited with swept round-up funds." }, "allocationPercentage": { "type": "number", "format": "double", "exclusiveMinimum": 0, "maximum": 100, "description": "Percentage (greater than 0, up to 100) of each sweep allocated to this receiving account. Percentages across receiving accounts should total 100." } }, "required": [ "type", "receivingAccountId", "allocationPercentage" ] }, "description": "Accounts credited with the swept round-up funds. At least one is required." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?Z$", "description": "Timestamp when the record was created (ISO-8601)." }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?Z$", "description": "Timestamp when the record was last updated (ISO-8601)." }, "spidrActionId": { "type": "string", "description": "Unique ID to identify the action within Spidr. Each type of action (e.g. create user, create account, replace card) has its own unique action ID." } }, "required": [ "id", "companyId", "userId", "status", "calculationMode", "currencyCode", "cadence", "trackingAccounts", "fundingAccounts", "receivingAccounts", "createdAt", "updatedAt", "spidrActionId" ] } }, "required": [ "status", "data" ] }, "PostV1RoundupCreateNegativeResponse": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "errorType": { "type": "string" }, "errorCode": { "type": "string", "description": "Specific error code for programmatic handling. See the [Error Code Reference](https://docs.gospidr.com/docs/spidr-errors#/) for details on all possible error codes." }, "errorData": { "format": "any" } }, "required": [ "message", "errorType", "errorCode" ], "description": "Error details. For a complete list of error codes and their meanings, see the [Error Code Reference](https://docs.gospidr.com/docs/spidr-errors#/)." } }, "required": [ "status", "error" ] }, "PostV1RoundupCreateRequestBody": { "type": "object", "properties": { "calculationMode": { "type": "string", "enum": [ "round_to_nearest_dollar", "fixed_amount_per_transaction", "round_to_nearest_dollar_plus_boost" ], "description": "How each round-up contribution is calculated: `round_to_nearest_dollar`, `fixed_amount_per_transaction`, or `round_to_nearest_dollar_plus_boost`." }, "fixedAmount": { "type": "number", "format": "double", "exclusiveMinimum": 0, "maximum": 10000000, "description": "For `fixed_amount_per_transaction` mode, the flat amount contributed per eligible transaction." }, "boostAmount": { "type": "number", "format": "double", "exclusiveMinimum": 0, "maximum": 10000000, "description": "For `round_to_nearest_dollar_plus_boost` mode, the additional amount added to each round-to-nearest-dollar contribution." }, "currencyCode": { "type": "string", "default": "USD", "description": "ISO 4217 three-letter currency code for the enrollment. Defaults to `USD`." }, "eligibleCategories": { "type": "array", "items": { "discriminator": { "propertyName": "type" }, "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "category", "description": "Whether the eligibility entry targets a primary `category` or a `subCategory`." }, "value": { "type": "string", "enum": [ "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" ], "description": "The Spidr transaction category or subcategory value that is eligible for round-ups." } }, "required": [ "type", "value" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "subCategory", "description": "Whether the eligibility entry targets a primary `category` or a `subCategory`." }, "value": { "type": "string", "enum": [ "dining.restaurants", "dining.fast_food", "dining.coffee_shops", "dining.bars_and_nightlife", "groceries.groceries", "groceries.convenience_stores", "shopping.clothing_and_accessories", "shopping.electronics", "shopping.software_and_apps", "shopping.home_goods_and_furniture", "shopping.online_marketplaces", "shopping.department_and_general_merchandise", "shopping.hobbies_and_sporting_goods", "shopping.books_and_media", "shopping.gifts", "transportation.gas_and_fuel", "transportation.ev_charging", "transportation.rideshare_and_taxi", "transportation.public_transit", "transportation.parking_and_tolls", "transportation.auto_service_and_parts", "transportation.bike_and_scooter_share", "travel.flights", "travel.hotels_and_lodging", "travel.car_rental", "travel.cruises", "utilities.electricity_and_natural_gas", "utilities.water", "utilities.trash_and_recycling", "utilities.internet", "utilities.mobile_phone", "home.rent", "home.home_improvement", "home.home_services", "home.lawn_and_garden", "health_and_wellness.doctors_and_medical", "health_and_wellness.dental", "health_and_wellness.vision_and_eyecare", "health_and_wellness.pharmacy", "health_and_wellness.mental_health", "health_and_wellness.fitness_and_gym", "personal_care.hair_and_beauty", "personal_care.spa_and_massage", "personal_care.laundry_and_dry_cleaning", "entertainment.events_and_movies", "entertainment.cable_and_streaming", "entertainment.music", "entertainment.gaming", "entertainment.recreation_and_sports", "entertainment.amusement", "entertainment.gambling", "family_and_pets.childcare", "family_and_pets.pet_care", "family_and_pets.veterinary", "education.tuition", "professional_services.legal", "professional_services.financial_and_accounting", "professional_services.shipping_and_postage", "professional_services.storage", "professional_services.other_services", "charity_and_giving.donations", "charity_and_giving.religious", "charity_and_giving.political", "groceries.alcohol", "shopping.tobacco_and_vape", "taxes_and_government.taxes", "taxes_and_government.government_fees", "taxes_and_government.fines", "cash_out.cash_withdrawal", "income.paycheck", "income.interest_and_dividends", "income.government_benefits", "income.tax_refund", "income.other_income", "transfers.account_transfer", "transfers.savings", "transfers.investments", "transfers.crypto", "transfers.wire", "loan_payments.credit_card_payment", "loan_payments.mortgage", "loan_payments.auto_loan", "loan_payments.student_loan", "loan_payments.personal_loan", "fees_and_adjustments.bank_fees", "fees_and_adjustments.atm_fees", "fees_and_adjustments.interest_paid", "fees_and_adjustments.foreign_transaction_fee" ], "description": "The Spidr transaction category or subcategory value that is eligible for round-ups." } }, "required": [ "type", "value" ] } ] }, "description": "Optional list of Spidr transaction categories or subcategories eligible for round-ups. When omitted, all categories are eligible." }, "eligibleMccCodes": { "type": "array", "items": { "type": "string" }, "description": "Optional list of merchant category codes (MCCs) eligible for round-ups. When omitted, all MCCs are eligible." }, "cadence": { "type": "string", "enum": [ "daily", "weekly", "biweekly", "monthly" ], "description": "How often accumulated round-ups are swept and transferred: `daily`, `weekly`, `biweekly`, or `monthly`." }, "cadenceKey": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 28, "description": "Day the sweep runs within the cadence period. For weekly and biweekly cadences this is the day of week (1-7); for monthly it is the day of month (1-28)." }, "cadenceMaxAmount": { "type": "number", "format": "double", "exclusiveMinimum": 0, "maximum": 10000000, "description": "Optional cap on the total round-up amount swept per cadence period." }, "minimumSweepAmount": { "type": "number", "format": "double", "minimum": 0, "maximum": 10000000, "description": "Optional minimum accumulated amount required before a sweep runs. Periods below this amount are skipped." }, "achHoldDays": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 6, "description": "Optional number of days to hold ACH-funded amounts before transferring to receiving accounts. Must be at least the receiving product's configured minimum, and no more than 6. The upper bound is the window in which an undelivered sweep is automatically retried, so a longer hold would leave the funds sitting on the hub account with no automatic retry left." }, "trackingAccounts": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "spidr", "linked_institution_account" ], "description": "Type of tracking account: `spidr` for a Spidr account, or `linked_institution_account` for an externally linked account." }, "trackingAccountId": { "type": "string", "description": "ID of the account whose transactions are tracked for round-ups." } }, "required": [ "type", "trackingAccountId" ] }, "minItems": 1, "description": "Accounts whose transactions are monitored to accumulate round-ups. At least one is required." }, "fundingAccounts": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "spidr", "ach_account" ], "description": "Type of funding account: `spidr` for a Spidr account, or `ach_account` for an external ACH account." }, "fundingAccountId": { "type": "string", "description": "ID of the account debited to fund round-up sweeps." }, "cadenceMaxAmount": { "type": "number", "format": "double", "exclusiveMinimum": 0, "maximum": 10000000, "description": "Optional cap on the amount drawn from this funding account per cadence period." }, "minimumBalance": { "type": "number", "format": "double", "minimum": 0, "maximum": 10000000, "description": "Optional minimum balance that must remain in this funding account; sweeps will not draw the balance below this amount." }, "fundingPercentage": { "type": "number", "format": "double", "exclusiveMinimum": 0, "maximum": 100, "description": "Percentage (greater than 0, up to 100) of each sweep funded from this account. Percentages across funding accounts should total 100." } }, "required": [ "type", "fundingAccountId", "fundingPercentage" ] }, "minItems": 1, "description": "Accounts debited to fund each sweep. At least one is required." }, "receivingAccounts": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "spidr" ], "description": "Type of receiving account. Currently only `spidr` is supported." }, "receivingAccountId": { "type": "string", "description": "ID of the account credited with swept round-up funds." }, "allocationPercentage": { "type": "number", "format": "double", "exclusiveMinimum": 0, "maximum": 100, "description": "Percentage (greater than 0, up to 100) of each sweep allocated to this receiving account. Percentages across receiving accounts should total 100." } }, "required": [ "type", "receivingAccountId", "allocationPercentage" ] }, "minItems": 1, "description": "Accounts credited with the swept round-up funds. At least one is required." } }, "required": [ "calculationMode", "cadence", "cadenceKey", "trackingAccounts", "fundingAccounts", "receivingAccounts" ] } }, "securitySchemes": { "APIKEY_1": { "type": "apiKey", "in": "header", "name": "apikey" }, "APIKEY_2": { "type": "apiKey", "in": "header", "name": "x-client-request-id" } } }, "tags": [ { "name": "Round-Up", "description": "Round-up savings configuration and sweep transfer records" } ], "servers": [ { "url": "https://api.sb.spidrsrv.com" } ] } ````