Amazon Finance API V2 | Openbridge Help Center

This document describes the Openbridge datasets derived from the Amazon Selling Partner API (SP-API) Finances API v2024-06-19. These datasets provide structured, tabular representations of financial transaction data for Amazon seller accounts.

The Finances API returns financial information relevant to a seller’s business, including transaction-level detail for orders, refunds, shipments, and other financial events. Openbridge normalizes the nested JSON response from this API into six relational CSV datasets that can be loaded into your data warehouse (Snowflake, BigQuery, Redshift, or Databricks) for analysis.

Amazon Finances API Reference: https://developer-docs.amazon.com/sp-api/docs/finances-api

Key Concepts

Each API response returns a list of Transaction objects. A transaction represents a financial event on a seller’s account (e.g., an order payment, a refund, or an adjustment).

Transactions contain nested structures including items, breakdowns (hierarchical charge decompositions), related identifiers (order IDs, shipment IDs, etc.), and contexts (product details, deferral information, payment metadata).

Transaction statuses reflect the lifecycle of financial events. DEFERRED means the transaction is pending release, RELEASED means it is available, and DEFERRED_RELEASED means it was previously deferred but has since been released.

Data Model

Openbridge flattens the nested Finances API response into six normalized tables. The tables are linked by composite keys based on ob_seller_id and ob_transaction_id.

Item-level and breakdown-level tables use additional index columns (ob_idx, ob_item_idx, ob_level, ob_parent_idx) to preserve the hierarchical relationships from the source data.

Entity Relationship Summary

The six tables form a parent-child hierarchy:

sp_finances_transactions is the root table with one row per transaction.
sp_finances_transaction_related_identifiers contains identifiers linked to each transaction (ORDER_ID, SHIPMENT_ID, FINANCIAL_EVENT_GROUP_ID, etc.).
sp_finances_transaction_breakdowns provides the hierarchical charge breakdown at the transaction level.
sp_finances_items contains line-item detail within each transaction.
sp_finances_item_related_identifiers contains identifiers linked to each item (ORDER_ADJUSTMENT_ITEM_ID, COUPON_ID, etc.).
sp_finances_item_breakdowns provides the hierarchical charge breakdown at the item level.

Dataset Schemas

sp_finances_transactions

The primary transaction table. Each row represents a single financial transaction on the seller’s account. Context fields (contexts_0_*, contexts_1_*) are flattened from the nested contexts array in the API response.

Primary key: ob_seller_id + ob_transaction_id (mapped from transaction_id)

Column Name	Type	Description
ob_seller_id	string	Openbridge-assigned seller identifier, used as a partition key across all tables.
selling_partner_id	string	The Amazon selling partner ID associated with the transaction.
account_type	string	The type of seller account (e.g., Standard Orders).
marketplace_id	string	The Amazon marketplace ID where the account is registered.
transaction_id	string	Unique identifier for the transaction, generated by Amazon.
transaction_type	string	The type of transaction (e.g., Shipment).
transaction_status	string	Status of the transaction: DEFERRED, RELEASED, or DEFERRED_RELEASED.
description	string	Human-readable description (e.g., Order Payment, Refund Order).
posted_date	datetime	The date and time the transaction was posted (ISO 8601).
marketplace_details_marketplace_id	string	Marketplace ID where the transaction occurred.
marketplace_details_marketplace_name	string	Name of the marketplace (e.g., Amazon.com).
total_amount_currency_code	string	Three-digit ISO 4217 currency code (e.g., USD).
total_amount_currency_amount	decimal	The total monetary amount of the transaction.
contexts_0_context_type	string	Type of the first context entry (e.g., DeferredContext, ProductContext).
contexts_0_asin	string	ASIN from the first context entry.
contexts_0_sku	string	SKU from the first context entry.
contexts_0_quantity_shipped	integer	Quantity shipped from the first context entry.
contexts_0_fulfillment_network	string	Fulfillment network (e.g., AFN for Amazon Fulfillment Network).
contexts_0_deferral_reason	string	Deferral policy code (e.g., DD7 for delivery date, B2B for invoiced).
contexts_0_maturity_date	datetime	Release date for deferred transactions.
contexts_0_payment_type	string	Payment type from the first context.
contexts_0_payment_method	string	Payment method from the first context.
contexts_0_payment_reference	string	Payment reference number from the first context.
contexts_0_payment_date	datetime	Payment date from the first context.
contexts_0_channel	string	Channel details from the first context.
contexts_0_order_type	string	Order type from the first context.
contexts_0_store_name	string	Store name from the first context.
contexts_0_start_time	datetime	Start time from the first context.
contexts_0_end_time	datetime	End time from the first context.
contexts_1_*	various	Repeated context fields for the second context entry (same schema as contexts_0_*).

sp_finances_transaction_related_identifiers

Stores the related identifiers for each transaction. Each row represents a single identifier associated with a transaction, such as an order ID, shipment ID, or financial event group ID.

Composite key: ob_seller_id + ob_transaction_id + ob_idx

Column Name	Type	Description
ob_seller_id	string	Openbridge-assigned seller identifier.
ob_transaction_id	string	References the parent transaction.
ob_idx	integer	Zero-based index of the identifier within the transaction.
related_identifier_name	string	The identifier type. Possible values: ORDER_ID, SHIPMENT_ID, FINANCIAL_EVENT_GROUP_ID, REFUND_ID, INVOICE_ID, DISBURSEMENT_ID, TRANSFER_ID, DEFERRED_TRANSACTION_ID, RELEASE_TRANSACTION_ID, SETTLEMENT_ID.
related_identifier_value	string	The value of the related identifier.

sp_finances_transaction_breakdowns

Contains the hierarchical charge breakdown at the transaction level. Breakdowns describe how the transaction’s total amount is decomposed into constituent charges (e.g., Sales, ProductCharges, Tax). The ob_level and ob_parent_idx columns encode the tree structure.

Composite key: ob_seller_id + ob_transaction_id + ob_level + ob_idx

Column Name	Type	Description
ob_seller_id	string	Openbridge-assigned seller identifier.
ob_transaction_id	string	References the parent transaction.
ob_level	integer	Depth level in the breakdown hierarchy (0 = top level).
ob_parent_idx	integer	Index of the parent breakdown at the previous level. Empty for top-level entries.
ob_idx	integer	Zero-based index of this breakdown within its level and parent.
breakdown_type	string	The type of charge (e.g., Sales, ProductCharges, Tax, FBAFees).
breakdown_amount_currency_code	string	Three-digit ISO 4217 currency code.
breakdown_amount_currency_amount	decimal	The monetary amount of this breakdown component.

sp_finances_items

Contains line-item detail for each transaction. Each row represents a single item within a transaction. Context fields are flattened from the item-level contexts array, following the same pattern as the transaction-level contexts.

Composite key: ob_seller_id + ob_transaction_id + ob_idx

Column Name	Type	Description
ob_seller_id	string	Openbridge-assigned seller identifier.
ob_transaction_id	string	References the parent transaction.
ob_idx	integer	Zero-based index of the item within the transaction.
description	string	Description of the item.
total_amount_currency_code	string	Three-digit ISO 4217 currency code.
total_amount_currency_amount	decimal	The total monetary amount for this item.
contexts_0_context_type	string	Type of the first item-level context entry (e.g., ProductContext).
contexts_0_asin	string	ASIN of the item from the first context.
contexts_0_sku	string	SKU of the item from the first context.
contexts_0_quantity_shipped	integer	Quantity shipped from the first context.
contexts_0_fulfillment_network	string	Fulfillment network (e.g., AFN).
contexts_0_*	various	Additional context fields following the same pattern as the transaction contexts.
contexts_1_*	various	Repeated context fields for the second context entry.

sp_finances_item_related_identifiers

Stores identifiers related to individual items within transactions. Each row represents a single identifier associated with a specific item.

Composite key: ob_seller_id + ob_transaction_id + ob_item_idx + ob_idx

Column Name	Type	Description
ob_seller_id	string	Openbridge-assigned seller identifier.
ob_transaction_id	string	References the parent transaction.
ob_item_idx	integer	Index of the parent item within the transaction.
ob_idx	integer	Zero-based index of the identifier within the item.
item_related_identifier_name	string	The identifier type. Possible values: ORDER_ADJUSTMENT_ITEM_ID, COUPON_ID, REMOVAL_SHIPMENT_ITEM_ID, TRANSACTION_ID.
item_related_identifier_value	string	The value of the related identifier.

sp_finances_item_breakdowns

Contains the hierarchical charge breakdown at the item level. Structure mirrors the transaction-level breakdowns but scoped to a specific line item.

Composite key: ob_seller_id + ob_transaction_id + ob_item_idx + ob_level + ob_idx

Column Name	Type	Description
ob_seller_id	string	Openbridge-assigned seller identifier.
ob_transaction_id	string	References the parent transaction.
ob_item_idx	integer	Index of the parent item within the transaction.
ob_level	integer	Depth level in the breakdown hierarchy (0 = top level).
ob_parent_idx	integer	Index of the parent breakdown at the previous level. Empty for top-level entries.
ob_idx	integer	Zero-based index of this breakdown within its level and parent.
breakdown_type	string	The type of charge (e.g., ProductCharges, OurPricePrincipal, FBAFees).
breakdown_amount_currency_code	string	Three-digit ISO 4217 currency code.
breakdown_amount_currency_amount	decimal	The monetary amount of this breakdown component.

Join Patterns

Below are the standard join keys for combining these datasets in your warehouse.

Column Name	Type	Description
transactions ↔ transaction_related_identifiers	JOIN ON	ob_seller_id AND ob_transaction_id
transactions ↔ transaction_breakdowns	JOIN ON	ob_seller_id AND ob_transaction_id
transactions ↔ items	JOIN ON	ob_seller_id AND ob_transaction_id
items ↔ item_related_identifiers	JOIN ON	ob_seller_id AND ob_transaction_id AND ob_idx = ob_item_idx
items ↔ item_breakdowns	JOIN ON	ob_seller_id AND ob_transaction_id AND ob_idx = ob_item_idx

Reference

Context Types

The contexts array in both transactions and items can contain multiple typed context objects. Each context type provides different metadata about the transaction or item.

Column Name	Type	Description
ProductContext	Product info	Contains ASIN, SKU, quantity shipped, and fulfillment network.
DeferredContext	Deferral info	Contains the deferral reason code and maturity (release) date.
PaymentsContext	Payment info	Contains payment type, method, reference, and date.
AmazonPayContext	Amazon Pay	Contains store name, order type, and channel.
BusinessContext	Business line	Contains the store name associated with the transaction.
TimeRangeContext	Time range	Contains start and end times for the transaction.
AddressContext	Address info	Contains address-related metadata for the transaction.

Transaction Statuses

Column Name	Type	Description
DEFERRED	Active	Transaction is currently deferred and pending release.
RELEASED	Final	Transaction has been released and funds are available.
DEFERRED_RELEASED	Final	Transaction was previously deferred but has now been released.

Related Identifier Names - Transaction-Level Identifiers

Column Name	Type	Description
ORDER_ID	Filterable	The Amazon order ID associated with the transaction.
SHIPMENT_ID	Informational	The shipment ID associated with the transaction.
FINANCIAL_EVENT_GROUP_ID	Filterable	The financial event group ID (settlement cycle).
REFUND_ID	Informational	The refund ID for refund transactions.
INVOICE_ID	Informational	The invoice ID associated with the transaction.
DISBURSEMENT_ID	Informational	Disbursement ID for Amazon bank transfers.
TRANSFER_ID	Informational	The transfer ID associated with the transaction.
DEFERRED_TRANSACTION_ID	Informational	Transaction ID of the related deferred transaction.
RELEASE_TRANSACTION_ID	Informational	Transaction ID of the related released transaction.
SETTLEMENT_ID	Informational	The settlement group ID associated with the transaction.

Item-Level Identifiers

Column Name	Type	Description
ORDER_ADJUSTMENT_ITEM_ID	Adjustment	Amazon-defined identifier for refunds, guarantee claims, and chargebacks.
COUPON_ID	Promotion	Identifier for a coupon applied to the transaction.
REMOVAL_SHIPMENT_ITEM_ID	Removal	Identifier for an item in a removal shipment.
TRANSACTION_ID	Reference	The transaction ID of the item.

Finances API v0 vs. v2024-06-19: Key Differences

The legacy Finances API (v0) and the current version (v2024-06-19) take fundamentally different approaches to modeling financial data. Understanding these differences is important both for users migrating from v0-based datasets and for interpreting the structure of the new datasets documented here.

API surface area

The v0 API exposed four separate operations: listFinancialEventGroups, listFinancialEventsByGroupId, listFinancialEventsByOrderId, and listFinancialEvents.

The v2024-06-19 API consolidates all of this into a single listTransactions operation, with query parameters (relatedIdentifierName, relatedIdentifierValue, transactionStatus, marketplaceId) replacing the need for dedicated per-group or per-order endpoints.

Data model architecture

This is the biggest structural change. The v0 API returned a FinancialEvents object that contained over 20 separate event-type-specific arrays — ShipmentEventList, RefundEventList, GuaranteeClaimEventList, ChargebackEventList, ServiceFeeEventList, PayWithAmazonEventList, LoanServicingEventList, RemovalShipmentEventList, AdjustmentEventList, and many more.

Each of these event types had its own unique schema with different field names and nesting structures. This meant consumers had to parse and handle dozens of distinct object types, and the downstream data model required a separate table (or wide union) for each event category.

The v2024-06-19 API replaces this with a unified Transaction object. Every financial event — regardless of type — uses the same structure: a transaction with a transactionType, transactionStatus, description, totalAmount, plus nested items, breakdowns, relatedIdentifiers, and contexts arrays. The variation that was previously expressed through separate event-type arrays is now expressed through the breakdowns hierarchy (which decomposes charges into typed categories like Sales, ProductCharges, Tax, FBAFees) and through typed contexts entries (ProductContext, DeferredContext, PaymentsContext, etc.).

Charge decomposition

In v0, charges, fees, and promotions were spread across separate flat lists within each event (e.g., OrderChargeList, ShipmentFeeList, OrderFeeList, PromotionList, DirectPaymentList). In v2024-06-19, all of this is handled through the recursive breakdowns tree, where each breakdown has a breakdownType, a monetary amount, and optionally its own child breakdowns. This gives a cleaner, hierarchical view of how a transaction's total decomposes into its components.

Transaction status and deferral tracking

The v0 API had no explicit concept of transaction status or deferral. The v2024-06-19 API introduces transactionStatus (DEFERRED, RELEASED, DEFERRED_RELEASED) and the DeferredContext type, which includes a deferralReason code and a maturityDate. This makes it straightforward to track when funds will be or have been released.

Related identifiers

In v0, identifiers like order IDs and shipment IDs were top-level fields on each event type (e.g., AmazonOrderId on ShipmentEvent). In v2024-06-19, these are normalized into a relatedIdentifiers array with name-value pairs, supporting a broader set of identifier types (ORDER_ID, SHIPMENT_ID, FINANCIAL_EVENT_GROUP_ID, REFUND_ID, INVOICE_ID, DISBURSEMENT_ID, TRANSFER_ID, DEFERRED_TRANSACTION_ID, RELEASE_TRANSACTION_ID, SETTLEMENT_ID).

Role requirements

The v0 API accepted multiple roles depending on the operation — Finance and Accounting, Account Information Service Provider (EU only), and Amazon Fulfillment (NA/FE only). The v2024-06-19 API requires only Finance and Accounting for its single listTransactions operation.

Availability

The v0 API is a legacy version. The v2024-06-19 API is the current version and is available for Sellers only (not Vendors) across NA, EU, and FE regions.

Important Notes

Data latency: Financial events may not include orders from the last 48 hours.
Date range limit: If postedAfter and postedBefore are more than 180 days apart, the API returns an empty response.
Breakdown hierarchy: Breakdown tables use ob_level and ob_parent_idx to represent a tree structure. Level 0 entries are top-level categories (e.g., Sales). Level 1 entries are children of level 0 (e.g., ProductCharges under Sales), and so on.
Context flattening: The contexts array is flattened into indexed columns (contexts_0_*, contexts_1_*). The number of context slots depends on the maximum observed contexts per transaction. Not all context fields will be populated for every row.
Filtering: At the API level, only FINANCIAL_EVENT_GROUP_ID and ORDER_ID are supported as filtering parameters via relatedIdentifierName. Other identifier types are informational only.
Seller availability: The Finances API v2024-06-19 is available for Sellers only (not Vendors).