Transactions

Overview

The Transactions API allows you to retrieve, create, and manage financial transactions in SellerCenter. Transactions represent financial movements including commissions, fees, refunds, and other monetary operations associated with orders, products, and account statements.

In SellerCenter, transactions are central to financial operations:

Transaction retrieval: Query transactions by various filters including date ranges, order items, statements, and transaction types
Transaction creation: Create manual transactions (admin only) for adjustments and corrections
Order item transactions: Retrieve transactions specifically related to order items with detailed breakdowns
Transaction tracking: Track transactions across different statement types (marketplace or consignment)

Transaction Sources:

sellercenter: Transactions created automatically by SellerCenter
web: Transactions created through the web interface
csv: Transactions imported via CSV
api: Transactions created via API (v2.1 endpoint)

Statement Types:

marketplace: Transactions associated with marketplace account statements
consignment: Transactions associated with consignment account statements

Important: Transaction creation via API is restricted to admin users and requires request signing. Transaction types and account statement groups can be retrieved from their respective endpoints.

Retrieve Transactions

GET /v2/finance/transactions

Summary: Retrieve transactions

Description: Retrieve a paginated list of transactions for a specified period and statement IDs. This endpoint provides extensive filtering options to find specific transactions based on dates, order items, products, transaction types, and more.

Parameters:

statementIds[] (query, optional): List of financial statement IDs associated with transactions
sellerId (query, optional): Seller ID (admin only - automatically set to current seller for non-admins)
startDate (query, optional): Start date of the period (ISO 8601 format)
endDate (query, optional): End date of the period (ISO 8601 format)
source (query, optional): Transaction source (sellercenter, web, or csv)
country (query, optional): Country filter
orderItemId (query, optional): Order item ID filter
orderItemSrcId (query, optional): Order item source ID filter
orderNumbers[] (query, optional): Order numbers filter
numbers[] (query, optional): Transaction numbers filter
typeIds[] (query, optional): Transaction type IDs filter
isHybrid (query, optional): Filter by order item is_hybrid field
isOutlet (query, optional): Filter by order item is_outlet field
isPaid (query, optional): Filter by paid statement status
product[] (query, optional): Filter by product name/shop SKU/seller SKU
statementType (query, optional): Statement type filter (marketplace or consignment, default: marketplace)
sort (query, optional): Sort field (id or date)
sortDir (query, optional): Sort direction (asc or desc)
limit (query, optional): Maximum number of items to return
offset (query, optional): Number of items to skip

Note:

Returns paginated results with transaction details
Supports filtering by multiple criteria simultaneously
Transaction amounts include VAT and WHT breakdowns
Statement ID of 0 represents the current statement
Use statementIds[] to filter by multiple statements (e.g. statementIds[]=1&statementIds[]=2&statementIds[]=3)

Authorization

BearerAuth

AuthorizationBearer <token>

OAuth 2.0 Bearer token authentication

In: header

Query Parameters

statementIds[]?array<integer>

A list of IDs of the financial statements associated with the transactions to retrieve.

sellerId?integer

The ID of the seller to retrieve transactions for. This parameter can only be set by an administrator. If the user is not an administrator, the parameter is automatically set to the ID of the current seller.

startDate?string

The start date of the period for which to retrieve transactions.

Formatdate-time

endDate?string

The end date of the period for which to retrieve transactions.

Formatdate-time

source?string

The source of the transactions.

Value in"sellercenter" | "web" | "csv"

country?string

The country filter.

orderItemId?integer

The ID of the order item associated with the transactions.

orderItemSrcId?string

The source ID of the order item associated with the transactions.

orderNumbers[]?array<string>

The order number associated with the transactions.

sort?string

The field to sort the results by.

Value in"id" | "date"

sortDir?string

The direction in which to sort the results ("asc" or "desc").

Value in"asc" | "desc"

numbers[]?array<string>

Transaction number

typeIds[]?array<integer>

Transaction type Id

isHybrid?boolean

Filter by order item field is_hybrid (Size Refill)

isOutlet?boolean

Filter by order item field is_outlet

isPaid?boolean

Filter by paid statement

product[]?array<string>

Filter by product data (name / shop sku / seller sku).

statementType?string

Filter by statement type of the transaction

Default"marketplace"

Value in"marketplace" | "consignment"

limit?integer

The maximum number of items to return.

offset?integer

The number of items to skip before starting to return results.

Response Body

`application/json`

{
  "items": [
    {
      "id": 0,
      "date": "2019-08-24T14:15:22Z",
      "number": "string",
      "typeId": 0,
      "treStatementGroupId": 2,
      "amount": 0,
      "vatAmount": 0,
      "whtAmount": 0,
      "source": "sellercenter",
      "comment": "string",
      "statementId": 0,
      "orderItemId": 0,
      "currency": "USD",
      "country": "DE",
      "typeName": "string",
      "groupName": "string",
      "orderNumber": "string",
      "statementType": "marketplace"
    }
  ],
  "pagination": {
    "limit": 0,
    "offset": 0,
    "total": 0
  }
}

{
  "title": "Bad Request",
  "status": 400,
  "detail": "The request parameters are invalid"
}

{
  "title": "Unauthorized",
  "status": 401,
  "detail": "Authentication credentials were not provided or are invalid"
}

{
  "title": "Access Denied",
  "status": 403,
  "detail": "You do not have permission to access this resource"
}

{
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "The provided data failed validation"
}

{
  "title": "Service Unavailable",
  "status": 500,
  "detail": "The service is temporarily unavailable. Please try again later."
}

{
  "title": "Service Unavailable Due to Maintenance Mode",
  "status": 503,
  "detail": "The service is currently under maintenance. Please try again later."
}

Retrieve Transaction Paginatable Collection (v2.1)

GET /v2.1/finance/transactions

Summary: Retrieve transaction paginatable collection

Description: Retrieve a paginated list of transactions with enhanced filtering capabilities. This is the v2.1 version of the transactions endpoint with improved filtering options and response structure.

Parameters:

statementType (query, optional): Filter by statement type (marketplace, consignment, or all, default: marketplace)
sellerId (query, optional): Seller ID filter (admin only)
gteCreatedAt (query, optional): Filter by creation date greater than or equal (seller center timezone)
lteCreatedAt (query, optional): Filter by creation date less than or equal (seller center timezone)
country (query, optional): Country filter
source (query, optional): Transaction source (sellercenter, api, web, or csv)
orderItemIds[] (query, optional): Order item IDs filter
orderItemSrcIds[] (query, optional): Order item region IDs filter
orderNumbers[] (query, optional): Order numbers filter
numbers[] (query, optional): Transaction numbers filter
products[] (query, optional): Filter by product (region SKU, seller SKU, or name)
statementId (query, optional, deprecated): Account statement ID (0 represents current statement). Use statementIds[] instead.
statementIds[] (query, optional): Filter by multiple account statement identifiers (0 represents current statement)
accountStatementGroupIds[] (query, optional): Filter by account statement group IDs.
transactionTypeIds[] (query, optional): Transaction type IDs filter
isOutlet (query, optional): Filter by outlet order items (default: false)
isHybrid (query, optional): Filter by hybrid order items (default: false)
isPaid (query, optional): Filter by paid account statements (default: false)
sort (query, optional): Sort field (createdAt, transactionType, transactionNumber, or amount, default: createdAt)
sortDir (query, optional): Sort direction (asc or desc, default: desc)
limit (query, optional): Maximum items to return (default: 100)
offset (query, optional): Items to skip (default: 0)

Note:

Enhanced version with more filtering options and improved response structure
Returns detailed transaction information including account statement details
Supports filtering by multiple criteria with better performance
Includes account statement payment status and dates

Authorization

BearerAuth

AuthorizationBearer <token>

OAuth 2.0 Bearer token authentication

In: header

Query Parameters

statementType?string

Filter by the transaction's associated statement type.

Default"marketplace"

Value in"marketplace" | "consignment" | "all"

sellerId?number

Filter by the transaction's association with the seller. This filter is exclusive to admin clients. The default value will be the seller ID of the associated client.

gteCreatedAt?string

Filter by the transaction's association with a creation date that is greater than or equal to the provided value (Base on seller center timezone).

lteCreatedAt?string

Filter by the transaction's association with a creation date that is lower than or equal to the provided value (Base on seller center timezone).

country?string

Filter by the transaction's association with the country in which the orders were placed.

source?string

Filter by the transaction's association with the source created by the transaction's creator.

Value in"sellercenter" | "api" | "web" | "csv"

orderItemIds[]?array<integer>

Filter by the transaction's association with order item identifier.

orderItemSrcIds[]?array<string>

Filter by the transaction's association with order item region identifier.

orderNumbers[]?array<string>

Filter by the transaction's association with order number.

numbers[]?array<string>

Filter by the transaction's association with transaction number.

products[]?array<string>

Filter by the transaction's association with a product using region SKU, seller SKU, or name.

statementId?numberDeprecated

The identifier of the account statement. The value 0 is representing the current statement. Deprecated. Use statementIds[] instead for filtering by multiple statements.

statementIds[]?array<integer>

Filter by multiple account statement identifiers. The value 0 represents the current statement.

accountStatementGroupIds[]?array<>

Filter by the transaction's association with account statement groups.

transactionTypeIds[]?array<integer>

Filter by the transaction's association with transaction types.

isOutlet?boolean

Filter by the transaction's association with order item which is outlet.

isHybrid?boolean

Filter by the transaction's association with order item which is hybrid.

isPaid?boolean

Filter by the transaction's association with account statement is paid.

sort?string

Sort the collection by predefined options.

Default"createdAt"

Value in"createdAt" | "transactionType" | "transactionNumber" | "amount"

sortDir?string

Specify the sorting direction.

Default"desc"

Value in"asc" | "desc"

limit?integer

The maximum number of items to return.

offset?integer

The number of items to skip before starting to return results.

Header Parameters

Accept*string

Set to application/json to receive a JSON response.

Default"application/json"

Value in"application/json"

Response Body

`application/json`

{
  "items": [
    {
      "createdAt": "string",
      "transactionNumber": "string",
      "transactionType": {
        "id": 0,
        "name": "string",
        "accountStatementGroup": {
          "id": 0,
          "name": "string"
        }
      },
      "userId": 0,
      "comment": "string",
      "amount": {
        "value": 0,
        "vatTax": 0,
        "whtTax": 0,
        "currency": "string"
      },
      "accountStatementId": 0,
      "orderNumber": "string",
      "productSku": "string",
      "country": "string",
      "isWhtInAmount": true,
      "transactionReference": 0,
      "qcUserId": 0,
      "hash": "string",
      "statementType": "marketplace",
      "isPaid": true,
      "accountStatementIsPaid": true,
      "accountStatementNumber": "string",
      "accountStatementStartDate": "string",
      "accountStatementEndDate": "string",
      "accountStatementPaymentDueDate": "2019-08-24T14:15:22Z",
      "ruleId": 0
    }
  ],
  "pagination": {
    "limit": 0,
    "offset": 0,
    "total": 0
  }
}

{
  "title": "Bad Request",
  "status": 400,
  "detail": "The request parameters are invalid"
}

{
  "title": "Unauthorized",
  "status": 401,
  "detail": "Authentication credentials were not provided or are invalid"
}

{
  "title": "Access Denied",
  "status": 403,
  "detail": "You do not have permission to access this resource"
}

{
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "The provided data failed validation"
}

{
  "title": "Service Unavailable",
  "status": 500,
  "detail": "The service is temporarily unavailable. Please try again later."
}

{
  "title": "Service Unavailable Due to Maintenance Mode",
  "status": 503,
  "detail": "The service is currently under maintenance. Please try again later."
}

Retrieve Order Item Transactions

GET /v2/finance/order-item-transactions

Summary: Retrieve transactions

Description: Retrieve transactions specifically related to order items with detailed financial breakdowns including commissions, fees, VAT, WHT, and payout amounts. This endpoint is optimized for order-item-level financial analysis.

Parameters:

statementId (query, optional, deprecated): Account statement ID (0 represents current statement). Use statementIds[] instead.
statementIds[] (query, optional): Filter by multiple account statement identifiers (0 represents current statement)
startDate (query, optional): Start date without timezone
endDate (query, optional): End date without timezone
products[] (query, optional): Product filter
productSkus[] (query, optional): Product SKUs filter
orderNumbers[] (query, optional): Order numbers filter
payoutStatus (query, optional): Payout status (paid, unpaid, or partiallyPaid)
shipmentTypes[] (query, optional): Shipment types (dropshipping, cross-docking, or warehouse)
status[] (query, optional): Status of an Order Item (pending, shipped, canceled, returned, failed, delivered, ready_to_ship, return_shipped_by_customer, return_waiting_for_approval, return_rejected, return_delivered, or payment_pending)
isHybrid (query, optional): Filter by is_hybrid field
isOutlet (query, optional): Filter by is_outlet field
statementType (query, optional): Statement type (marketplace, consignment, or all, default: marketplace)
sort (query, optional): Sort field (id, date, orderNumber, orderDate, payoutStatus, price, commission, fees, or payoutAmount)
sortDir (query, optional): Sort direction (asc or desc)
statementPeriodStart (query, optional): Statement period start date
statementPeriodEnd (query, optional): Statement period end date
country (query, optional): Deprecated country filter
limit (query, optional): Maximum items to return
offset (query, optional): Items to skip

Note:

Returns transactions with order item context
Includes detailed breakdown: commission, fees, VAT, WHT, and payout amounts
Useful for analyzing financial performance at the order item level
Supports filtering by payout status, shipment types, and order item status
Use statementIds[] to filter by multiple statements (e.g. statementIds[]=1&statementIds[]=2)
pagination.totalCount is deprecated, always returns 0, and will be removed in the future. Use pagination.hasNext to check whether another page exists

Authorization

BearerAuth

AuthorizationBearer <token>

OAuth 2.0 Bearer token authentication

In: header

Query Parameters

statementId?numberDeprecated

The identifier of the account statement. The value 0 is representing the current statement. Deprecated. Use statementIds[] instead for filtering by multiple statements.

statementIds[]?array<integer>

Filter by multiple account statement identifiers. The value 0 represents the current statement.

startDate?string

The start date of the period for which to retrieve transactions (without timezone).

Formatdate-time

endDate?string

The end date of the period for which to retrieve transactions (without timezone).

Formatdate-time

products[]?array<string>

The product associated with the transactions.

productSkus[]?array<string>

The product SKUs associated with the transactions.

orderNumbers[]?array<string>

The order number associated with the transactions.

payoutStatus?string

Payout Status of Statement

Value in"paid" | "unpaid" | "partiallyPaid"

shipmentTypes[]?array<>

Shipment type

status[]?array<>

Status of an Order Item

isHybrid?boolean

Filter by order item field is_hybrid (Size Refill)

isOutlet?boolean

Filter by order item field is_outlet

statementType?string

Filter by the transaction's associated statement type.

Default"marketplace"

Value in"marketplace" | "consignment" | "all"

limit?integer

The maximum number of items to return.

offset?integer

The number of items to skip before starting to return results.

sort?string

The field to sort the results by.

sortDir?string

The direction in which to sort the results ("asc" or "desc").

Value in"asc" | "desc"

statementPeriodStart?string

The start date of the period for statement.

Formatdate-time

statementPeriodEnd?string

The end date of the period for statement.

Formatdate-time

country?stringDeprecated

Deprecated, the country filter in ISO 3166-1 alpha-2 format.

Header Parameters

Accept*string

Set to application/json to receive a JSON response.

Default"application/json"

Value in"application/json"

Response Body

`application/json`

{
  "items": [
    {
      "orderItemId": 0,
      "orderId": 0,
      "commission": 0,
      "fees": 0,
      "vatAmount": 0,
      "whtAmount": 0,
      "payoutAmount": 0,
      "statementId": 0,
      "currency": "USD",
      "country": "DE",
      "statementType": "marketplace",
      "payoutStatus": "string",
      "accountStatementPaymentDueDate": "2019-08-24T14:15:22Z"
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 10,
    "hasNext": false,
    "totalCount": 0
  }
}

{
  "title": "Bad Request",
  "status": 400,
  "detail": "The request parameters are invalid"
}

{
  "title": "Unauthorized",
  "status": 401,
  "detail": "Authentication credentials were not provided or are invalid"
}

{
  "title": "Access Denied",
  "status": 403,
  "detail": "You do not have permission to access this resource"
}

{
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "The provided data failed validation"
}

{
  "title": "Service Unavailable",
  "status": 500,
  "detail": "The service is temporarily unavailable. Please try again later."
}

{
  "title": "Service Unavailable Due to Maintenance Mode",
  "status": 503,
  "detail": "The service is currently under maintenance. Please try again later."
}

Create Transaction

POST /v2/finance/transaction

Summary: This endpoint will return a collection of transactions.

Description: Create a new transaction manually. This endpoint is restricted to admin users and requires request signing. Use this endpoint to create adjustments, corrections, or manual financial entries.

Request Body:

sellerId (required): Seller identifier
transactionTypeId (required): Transaction type identifier (get from /v2/finance/transaction/types)
accountStatementGroupId (required): Account statement group identifier (get from /v2/finance/transactions/account-statement-groups)
value (required): Transaction value (positive or negative)
currency (required): Transaction currency (must be supported by seller)
description (optional): Transaction description
referenceId (optional): Reference identifier (required for order/product context)
vatTax (optional): VAT tax value
whtTax (optional): WHT tax value

Note:

Admin only: This endpoint is restricted to admin users
Request signing required: Must include request signature
Currency must be supported by the seller, otherwise transaction creation will fail
Transaction type and account statement group IDs can be retrieved from their respective endpoints
Returns the created transaction object

Authorization

BearerAuth

AuthorizationBearer <token>

OAuth 2.0 Bearer token authentication

In: header

Header Parameters

Accept*string

Set to application/json to receive a JSON response.

Default"application/json"

Value in"application/json"

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

`application/json`

{
  "id": 1,
  "sellerId": 1,
  "transactionTypeId": 1,
  "treStatementGroupId": 2,
  "transactionGroupName": "string",
  "transactionTriggerEventId": 1,
  "isUnique": true,
  "transactionSource": "sellercenter",
  "userId": 0,
  "description": "string",
  "value": 65.3,
  "taxesVat": 2.3,
  "taxesWht": 1.3,
  "isWhtInAmount": true,
  "ref": 12,
  "refDate": 0,
  "number": "string",
  "transactionStatementId": 0,
  "createdAt": "2021-09-22T23:21:42+02:00",
  "updatedAt": "2021-09-22T23:21:42+02:00",
  "qcUserId": 44,
  "hash": "string",
  "currency": "USD",
  "reference": 0,
  "referenceType": "string"
}

{
  "title": "Bad Request",
  "status": 400,
  "detail": "The request parameters are invalid"
}

{
  "title": "Unauthorized",
  "status": 401,
  "detail": "Authentication credentials were not provided or are invalid"
}

{
  "title": "Access Denied",
  "status": 403,
  "detail": "You do not have permission to access this resource"
}

{
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "The provided data failed validation"
}

{
  "title": "Service Unavailable",
  "status": 500,
  "detail": "The service is temporarily unavailable. Please try again later."
}

{
  "title": "Service Unavailable Due to Maintenance Mode",
  "status": 503,
  "detail": "The service is currently under maintenance. Please try again later."
}

Get Transactions by Order Item IDs

GET /v2/transactions (Deprecated)

Deprecated: This endpoint is deprecated and will be removed in a future release. Use GET /v2.1/finance/transactions with the orderItemIds[] filter instead.

Summary: This endpoint will return a collection of transactions which belongs to an order item.

Description: Search for transactions by order item IDs. This endpoint returns all transactions associated with the specified order items. If you request transactions from another seller, you will receive an empty response.

Parameters:

orderItemIds[] (query, required): Array of order item IDs (minimum 1 required)

Note:

Returns transactions for order items belonging to your seller account
Empty response if order items belong to another seller
Useful for retrieving all financial transactions related to specific order items
Returns an array of transaction objects

Authorization

BearerAuth

AuthorizationBearer <token>

OAuth 2.0 Bearer token authentication

In: header

Query Parameters

orderItemIds[]*array<integer>

Search by order item ids. You have to add at least 1 order item id.

Items1 <= items

Response Body

`application/json`

[
  {
    "id": 1,
    "sellerId": 1,
    "transactionTypeId": 1,
    "treStatementGroupId": 2,
    "transactionGroupName": "string",
    "transactionTriggerEventId": 1,
    "isUnique": true,
    "transactionSource": "sellercenter",
    "userId": 0,
    "description": "string",
    "value": 65.3,
    "taxesVat": 2.3,
    "taxesWht": 1.3,
    "isWhtInAmount": true,
    "ref": 12,
    "refDate": 0,
    "number": "string",
    "transactionStatementId": 0,
    "createdAt": "2021-09-22T23:21:42+02:00",
    "updatedAt": "2021-09-22T23:21:42+02:00",
    "qcUserId": 44,
    "hash": "string",
    "currency": "USD",
    "reference": 0,
    "referenceType": "string"
  }
]

{
  "title": "Unauthorized",
  "status": 401,
  "detail": "Authentication credentials were not provided or are invalid"
}

{
  "title": "Service Unavailable",
  "status": 500,
  "detail": "The service is temporarily unavailable. Please try again later."
}

{
  "title": "Service Unavailable Due to Maintenance Mode",
  "status": 503,
  "detail": "The service is currently under maintenance. Please try again later."
}

Transactions

200application/json

400application/json

401application/json

403application/json

422application/json

500application/json

503application/json

200application/json

400application/json

401application/json

403application/json

422application/json

500application/json

503application/json

200application/json

400application/json

401application/json

403application/json

422application/json

500application/json

503application/json

201application/json

400application/json

401application/json

403application/json

422application/json

500application/json

503application/json

200application/json

401application/json

500application/json

503application/json

On this page

200application/json

400application/json

401application/json

403application/json

422application/json

500application/json

503application/json

200application/json

400application/json

401application/json

403application/json

422application/json

500application/json

503application/json

200application/json

400application/json

401application/json

403application/json

422application/json

500application/json

503application/json

201application/json

400application/json

401application/json

403application/json

422application/json

500application/json

503application/json

200application/json

401application/json

500application/json

503application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`