Distribution APIs
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:
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. |