get https://{subdomain}.myshoplaza.com/openapi/2024-07/shoplazza-payment/settlements/details
Requires
financeaccess scope.
List Settlement Details
The List Settlement Details API returns a list of settled details sorted in descending order of creation date, with the most recently created objects appearing first.
This API is especially useful for:
- Retrieving a list of detailed settlement transactions.
- Filtering settlement details by transaction type, currency, and settlement time.
- Paginating settlement data using cursors for efficient querying.
Request Parameters
Public Request Parameters
Query Parameters
Query Parameters
| Field | Type | Required | Example | Description |
|---|---|---|---|---|
cursor | string | No | "abc123" | Cursor for pagination; use the cursor value returned in the previous response. |
limit | int32 | No | 10 | A limit on the number of objects to return. The default is 10, and the range is 1-100. |
trans_type | string | No | "payment" | Type of transaction. Valid values: payment, reserve_release, chargeback, chargeback_win, refund, refund_reversal, ship_ins_comm_transfer, ship_ins_comm_reversal, adjustment, debit_negative_balance, debit_negative_balance_reversal. |
currency | string | No | "USD" | Currency of the settlement account. |
settlement_time_min | string | No | "1714281600" | Filter option: settlement initiation start time (Unix timestamp). |
settlement_time_max | string | No | "1714368000" | Filter option: settlement initiation end time (Unix timestamp). |
Response Explanation
Public Response Parameters
Successful Response
| Field | Type | Example | Description |
|---|---|---|---|
code | string | "Success" | Status code for the response. |
message | string | "Request successful" | Additional message about the response. |
data | object | Contains the settlement details. | |
data.list | array | Array of settlement detail objects. | |
data.list[].store_id | string | "store123" | Store ID associated with the settlement. |
data.list[].currency | string | "USD" | Currency of the settlement account. |
data.list[].trans_type | string | "payment" | Transaction type. Refer to valid trans_type values in the request parameters. |
data.list[].trans_id | string | "trans456" | Unique transaction ID for the settlement. |
data.list[].fee_amount | string | "5.00" | Fee amount associated with the transaction. |
data.list[].settlement_amount | string | "100.00" | Total settlement amount. |
data.list[].reserve_amount | string | "10.00" | Reserve amount for the transaction. |
data.list[].settlement_time | string | "1714281600" | Settlement time in Unix timestamp format. |
data.list[].merchant_id | string | "merchant789" | Merchant ID associated with the settlement. |
data.has_more | boolean | true | Indicates if there are more pages of results. |
data.cursor | string | "abc123" | Cursor to fetch the next page of results. |
Error Response
Error responses in the API can be represented using two different fields: errors and error. Both fields provide details about issues encountered during request processing. Below is an explanation of the fields with their respective examples and descriptions.
| Field | Type | Description | Example |
|---|---|---|---|
code | string | The error code indicating the type of issue. | InvalidParameter |
message | string | A detailed message describing the error. | wrong cursor |
| Field | Type | Example | Description |
|---|---|---|---|
error | String | "store is not active" | Indicates an error encountered during the process |
Error Detail
| Status Code | Message | Possible Reason | Example Response |
|---|---|---|---|
| 400 | Bad Request | Invalid input format or request structure (e.g., missing required fields or incorrect data types). | Bad Request |
| Unauthorized | The request is missing valid authentication credentials or the credentials provided are invalid. | Unauthorized | |
| 500 | InvalidParameter | Currency is not provided. | Currency is required |