Accessing Distributions via API

Distributions represent how funds from an order are split across Merchants and Channels. These APIs allow you to programmatically retrieve and search distributions tied to orders, enabling clear financial visibility and auditability.

Violet exposes the following APIs for access to Distributions data:

• Get Distributions

• Search Distributions

Each of these APIs provides a different way to access the data you need. The Get Distributions API allows you to retrieve all distributions for you or a specific merchant you are connected to, while the Search Distributions API enables you to filter and search for distributions based on various criteria. You can learn more about each API by clicking on the links above.

Understanding the Distribution Object

The Distribution object represents the calculated split of funds from an order, including amounts for merchants, channels, Violet, and any associated adjustments like tax, shipping, or commissions.

Each distribution record contains critical financial and metadata fields that allow you to trace, audit, and reconcile payments through Violet.

Fields

Field	Type	Description
id	integer	Unique identifier for the distribution record.
type	string	Type of distribution: PAYMENT or REFUND.
payout_account_id	integer	ID of the Violet Payout Account the distribution is tied to.
payout_account_type	string	Entity type: MERCHANT or DEVELOPER.
currency	string	ISO 4217 currency code (e.g., USD, EUR).
distribution_amount	integer	Original amount before deductions, in minor units (e.g., cents).
net_distribution_amount	integer	Final amount after all deductions (fees, commissions, discounts).
tax_amount	integer	Portion of the distribution that covers tax charges.
shipping_amount	integer	Portion of the distribution that covers shipping charges.
commission	integer	Commission amount earned by the channel.
payment_provider_total_fee	integer	Total fee charged by the payment provider for the transaction.
payment_provider_volume_fee	integer	Volume-based fee charged by the payment provider.
payment_provider_fixed_fee	integer	Fixed fee charged by the payment provider.
app_id	integer	ID of the Violet App associated with the transaction.
app_name	string	Name of the Violet App.
merchant_id	integer	ID of the merchant involved in the transaction.
merchant_name	string	Merchant’s name.
merchant_commission_rate	double	Commission rate applied to the merchant.
payment_provider_transaction_id	string	Payment provider’s transaction ID (e.g., Stripe Charge ID).
payment_provider	string	Payment service that processed the transaction (e.g., STRIPE).
status	string	Status of the distribution: PENDING, SENT, REVERSED, FAILED.
bag_id	long	ID of the Bag (checkout/cart) associated with the distribution.
bag_sub_total	integer	Pre-discount and pre-tax total for the bag.
bag_commissionable_amount	integer	Amount eligible for commission after adjustments.
bag_shipping_total	integer	Total shipping charges for the bag.
bag_tax_total	integer	Total taxes applied to the bag.
bag_discount_total	integer	Discounts applied to the bag.
bag_total	integer	Final bag total after shipping, taxes, and discounts.
external_order_id	string	External ecommerce platform order ID (e.g., Shopify Order ID).
order_id	long	Violet internal order ID.
order_total	integer	Total value of the Violet Order.
payout_id	integer	ID of the payout batch this distribution was included in.
payout_amount	long	Amount of the payout batch.
date_payout_created	datetime	Timestamp when the payout was created.
date_payout_settled	datetime	Timestamp when the payout settled in the bank account.
payout_transfer_id	long	ID of the transfer associated with this distribution.
refund_id	long	Refund ID if the distribution is related to a refund.
refund_discrepancy	integer	Discrepancy amount, if any, due to refund errors.
tax_remitter	string	Who is responsible for tax remittance: APP or MERCHANT.
date_created	datetime	Timestamp of when the distribution record was created.
date_last_modified	datetime	Timestamp of the last modification to the record.