# Get Settlement **GET /settlements/{settlementId}** Returns the details of a single settlement (bank deposit), including its settled-transaction line items. A deposit can span several processor batches, so each line item carries its own `batchId`. For line items with a `transactionId`, look up the ID via [`GET /transactions`](#operation-gettransactions) (e.g. `?filters=id==trx_...`) for full transaction detail. Every line item the deposit contains is returned, including any that moved no money, so `lineItems` always matches the settlement's own `transactionCount`. How far those lines reconcile to the deposit total depends on the settlement `type`: - **Ach, `fundingType` Net**: the deposit is built up from its lines, so *sum of line `amount`s, less any deposit-level fees, equals the settlement's `amount`*. Deposit-level fees are the ones [`GET /fee-charges`](#operation-getfeecharges) returns for this `settlementId` with no `settledTransaction` - a `PerSettlementFee` is charged against the deposit as a whole and belongs to no line. - **Ach, `fundingType` Gross**: nothing is withheld, so *sum of line `amount`s equals the settlement's `amount`* exactly. The fees for the period are billed separately and appear as `StatementOnly` fee charges, dated to the month they are taken in rather than to this deposit. - **Card**: `amount` is the processor's own control total for the deposit, while the line items are matched best-effort from its transaction reporting, and card fees are assessed against the deposit rather than against any line. The two are not expected to agree exactly. ## Servers - https://api.omni.integratedcommerce.io/v1: https://api.omni.integratedcommerce.io/v1 () ## Authentication methods - Api key header ## Parameters ### Path parameters - **settlementId** (string) The settlement ID, prefixed with `stl_`. ### Query parameters - **merchantIds** (string) Comma-separated list of merchant IDs to report on. Forward-compatible parameter for multi-merchant API keys; currently every ID must be the merchant resolved from the API key, and any other ID is rejected with `401`. Omit it to default to that merchant. ## Responses ### 200 The settlement details #### Body: application/json (object) - **id** (string) The settlement ID, prefixed with `stl_`. - **type** (string) The kind of settlement, derived from the settlement provider. **Card**: A card settlement, deposited from the card processor. **Ach**: An ACH settlement, deposited from the ACH processor. - **settlementDate** (string(date)) The date the settlement was deposited to the merchant's bank account. - **currency** (string) - **amount** (integer) The deposit as it landed in the merchant's bank account, smallest denomination. Signed - normally positive, but may be negative when returns/adjustments in the deposit exceed sales. `fundingType` states which reading it is: net of the fees the provider withheld from it, or the gross deposit whose fees are billed separately. - **fundingType** (string) Whether the rail this deposit came in on withholds the fees it bills from its deposits or bills them apart from them. An `amount` is never returned without a `fundingType` in scope, so nothing has to be looked up in the merchant's configuration to know what an amount this API returned is. **Net**: the fees were withheld, so `amount` is the deposit after them. They are itemized by [`GET /fee-charges`](#operation-getfeecharges) against this deposit's `settlementId`. **Gross**: nothing was withheld - `amount` is the gross deposit - and the fees for it are billed separately, arriving as `StatementOnly` fee charges on the monthly statement. - **netAmount** (integer) **Deprecated - read `amount` instead.** This member mirrors `amount` exactly and cannot hold a different figure. `fundingType` on this payload states whether that figure is the gross deposit or one already net of withheld fees, and is the only authoritative reading of it. Deprecated on 2026-08-21 and removed one month later in its own release, at which point `netAmount` also stops being accepted as a filter or sort field. Its value changed when `amount` was introduced: for a gross-funded merchant it now reports the gross deposit - the figure that actually reached the bank - so despite its name it is not necessarily a net figure. - **transactionCount** (integer) Number of settled-transaction line items in the settlement. Always equal to the length of the `lineItems` array returned by [`GET /settlements/{settlementId}`](#operation-getsettlement), which withholds no line. - **status** (string) Status of the settlement. **Settled**: The settlement has been deposited to the merchant's bank account. **Adjusted**: Reserved for a future reconciliation follow-up (e.g. a late return posted against an already-settled deposit). Not produced yet. - **merchantId** (string) The ID of the merchant the settlement was deposited to, prefixed with `mer_`. - **lineItems** (array[object]) A single settled transaction within a settlement. ### 401 Unauthorized response due to an invalid or missing API key. #### Body: application/json (object) - **code** (number) Numeric error code. These are grouped into ranges for easier identification and troubleshooting. * `0` - Unknown * `1000` - AuthenticationGenericError * `1001` - MerchantNotAuthorizedForResource * `2000` - RequestValidationGenericError * `2010` - InvalidPaymentMethodType - The payment method type is not supported for this operation. This includes: ACH tokens cannot be used for auth, void, or subscription transactions. * `2011` - InvalidTransactionType * `2012` - InvalidAmount * `2013` - PaymentMethodUsageRestricted * `2020` - InvalidPaymentMethodOwner * `2021` - InvalidAccountHolderOwner * `2100` - InvalidAccountHolderInformation * `2101` - InvalidCountryCode * `2102` - InvalidZipCode * `2103` - MissingCountryCodeOrZipCode * `2105` - InvalidEmailAddress * `2201` - MissingUniqueToken * `2202` - TransactionDeclinedError * `2900` - RequestValidationUnsupportedPayload * `2901` - RequestValidationWebhookMissingTypeAndDmnType * `2902` - RequestValidationUnsupportedWebhookTokenization * `2903` - RequestValidationUnsupportedWebhookType * `3000` - UnknownServerGenericError * `3201` - InvalidOrExpiredSession * `3202` - FailedToCreateSessionInAdapter * `3203` - ErrorWhileTokenizingCard * `3204` - FailedToLoadThirdPartySdk * `3205` - SessionExpired * `3299` - JavaScriptError * `3400` - ResourceNotReadyError * `3401` - TransactionNotCompleteYet * `3501` - CouldNotCreateBillingSubscription * `3502` - CouldNotCancelBillingSubscription * `3503` - BillingSubscriptionInvalidStatus * `4000` - ResourceNotFound * `4001` - TokenizedCardNotFound * `4002` - PaymentMethodNotFound * `4003` - AccountHolderNotFound * `4004` - BillingSubscriptionNotFound * `6000` - SdkGenericError * `6001` - SdkJavaScriptError * `6100` - SdkSessionLoadFailed * `6101` - SdkSessionExpired * `6102` - SdkSessionNotInitialized * `6103` - SdkEnvironmentMismatch * `6200` - SdkCardFieldsInvalid * `6201` - SdkCardTokenizationFailed * `6202` - SdkCardInitFailed * `6203` - SdkCardProcessingFailed * `6300` - SdkAchFieldsInvalid * `6301` - SdkAchProcessingFailed * `6400` - SdkEftProcessingFailed * `6500` - SdkWalletError * `6501` - SdkWalletProcessingFailed * `6600` - SdkThirdPartySdkLoadFailed * `6700` - SdkFormValidationFailed * `6701` - SdkBillingValidationFailed * `6800` - Sdk3dsAuthenticationFailed — Issuer ACS rejected the 3DS authentication. Only emitted when `formConfig.enable3DSecure: true`. * `6801` - Sdk3dsAuthenticationUnavailable — 3DS authentication could not be completed due to an upstream technical issue. * `6802` - Sdk3dsNotEnrolled — The card is not enrolled in 3DS. * `9000` - UnhandledGenericError * `9999` - MaxErrorCode - **status** (string) Execution status of the request sent to the payment gateway. * Completed - The request completed successfully. * Rejected - The request was rejected by the payment gateway. No action or side effects occurred. The transaction can safely be retried. * Interrupted - The request was interrupted, and the final status is unknown. Possible side effects may have occurred (e.g., a Sale (Token) that returns Interrupted might still charge the customer, even if an error is returned). Additional checks are required before retrying the transaction. * Unknown - **message** (string) Developer-facing error message. - **traceId** (string) Unique trace identifier for tracking and debugging this request. - **timestamp** (string(date-time)) The timestamp when the error occurred (UTC). - **errorDetails** (array[object]) Represents a validation error that occurred during the request. ### 404 The settlement does not exist or does not belong to the merchant. #### Body: application/json (object) - **code** (number) Numeric error code. These are grouped into ranges for easier identification and troubleshooting. * `0` - Unknown * `1000` - AuthenticationGenericError * `1001` - MerchantNotAuthorizedForResource * `2000` - RequestValidationGenericError * `2010` - InvalidPaymentMethodType - The payment method type is not supported for this operation. This includes: ACH tokens cannot be used for auth, void, or subscription transactions. * `2011` - InvalidTransactionType * `2012` - InvalidAmount * `2013` - PaymentMethodUsageRestricted * `2020` - InvalidPaymentMethodOwner * `2021` - InvalidAccountHolderOwner * `2100` - InvalidAccountHolderInformation * `2101` - InvalidCountryCode * `2102` - InvalidZipCode * `2103` - MissingCountryCodeOrZipCode * `2105` - InvalidEmailAddress * `2201` - MissingUniqueToken * `2202` - TransactionDeclinedError * `2900` - RequestValidationUnsupportedPayload * `2901` - RequestValidationWebhookMissingTypeAndDmnType * `2902` - RequestValidationUnsupportedWebhookTokenization * `2903` - RequestValidationUnsupportedWebhookType * `3000` - UnknownServerGenericError * `3201` - InvalidOrExpiredSession * `3202` - FailedToCreateSessionInAdapter * `3203` - ErrorWhileTokenizingCard * `3204` - FailedToLoadThirdPartySdk * `3205` - SessionExpired * `3299` - JavaScriptError * `3400` - ResourceNotReadyError * `3401` - TransactionNotCompleteYet * `3501` - CouldNotCreateBillingSubscription * `3502` - CouldNotCancelBillingSubscription * `3503` - BillingSubscriptionInvalidStatus * `4000` - ResourceNotFound * `4001` - TokenizedCardNotFound * `4002` - PaymentMethodNotFound * `4003` - AccountHolderNotFound * `4004` - BillingSubscriptionNotFound * `6000` - SdkGenericError * `6001` - SdkJavaScriptError * `6100` - SdkSessionLoadFailed * `6101` - SdkSessionExpired * `6102` - SdkSessionNotInitialized * `6103` - SdkEnvironmentMismatch * `6200` - SdkCardFieldsInvalid * `6201` - SdkCardTokenizationFailed * `6202` - SdkCardInitFailed * `6203` - SdkCardProcessingFailed * `6300` - SdkAchFieldsInvalid * `6301` - SdkAchProcessingFailed * `6400` - SdkEftProcessingFailed * `6500` - SdkWalletError * `6501` - SdkWalletProcessingFailed * `6600` - SdkThirdPartySdkLoadFailed * `6700` - SdkFormValidationFailed * `6701` - SdkBillingValidationFailed * `6800` - Sdk3dsAuthenticationFailed — Issuer ACS rejected the 3DS authentication. Only emitted when `formConfig.enable3DSecure: true`. * `6801` - Sdk3dsAuthenticationUnavailable — 3DS authentication could not be completed due to an upstream technical issue. * `6802` - Sdk3dsNotEnrolled — The card is not enrolled in 3DS. * `9000` - UnhandledGenericError * `9999` - MaxErrorCode - **status** (string) Execution status of the request sent to the payment gateway. * Completed - The request completed successfully. * Rejected - The request was rejected by the payment gateway. No action or side effects occurred. The transaction can safely be retried. * Interrupted - The request was interrupted, and the final status is unknown. Possible side effects may have occurred (e.g., a Sale (Token) that returns Interrupted might still charge the customer, even if an error is returned). Additional checks are required before retrying the transaction. * Unknown - **message** (string) Developer-facing error message. - **traceId** (string) Unique trace identifier for tracking and debugging this request. - **timestamp** (string(date-time)) The timestamp when the error occurred (UTC). - **errorDetails** (array[object]) Represents a validation error that occurred during the request. [Powered by Bump.sh](https://bump.sh)