> For the complete documentation index, see [llms.txt](https://docs.violet.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.violet.io/prism/payments/payouts/distributions/distributions-apis.md).

# 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](/api-reference/payments/distributions/get-distributions.md)
* [Search Distributions](/api-reference/payments/distributions/search-distributions.md)

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`, `REFUND` or `ADJUSTMENT`.                                                                                                                                                                                                                                   |
| `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  | On `PAYMENT` rows, the account's share before the payment provider's processing fee, in minor units (e.g., cents). Not set on `REFUND` rows: use `net_distribution_amount`.                                                                                                                  |
| `net_distribution_amount`         | integer  | The amount that moves for this account: what it is paid on a sale (positive), or what is taken back on a refund (negative). See [Reading Refund Rows](#reading-refund-rows).                                                                                                                 |
| `tax_amount`                      | integer  | Tax on this row for the account that remits it. On refund rows it is the tax refunded, always shown as a positive figure.                                                                                                                                                                    |
| `shipping_amount`                 | integer  | Shipping on this row. On refund rows it is the shipping refunded, always shown as a positive figure.                                                                                                                                                                                         |
| `duty_amount`                     | integer  | Duty on this row for the account that remits it. On refund rows it is the duty refunded, always shown as a positive figure.                                                                                                                                                                  |
| `commission`                      | integer  | The bag's commission, signed from this account's point of view: positive on the channel's sale row, negative on the retailer's. On refund rows it repeats the whole bag's commission with the signs flipped, for reference; it is not this refund's figure.                                  |
| `commission_reversed_amount`      | integer  | Refund rows only: the commission this refund reversed. `0` under the `RETAIN` [return policy](/prism/payments/payouts/return-commission-policy.md). Sum it across refunds; do not sum `commission` on refund rows, which repeats the bag's figure.                                           |
| `commission_retained_amount`      | integer  | Refund rows only: the commission the channel kept under `RETAIN`. Same sign convention as `commission_reversed_amount`. `null` under `REVERSE`.                                                                                                                                              |
| `payment_provider_total_fee`      | integer  | The payment provider's processing fee, on the row of the account that pays it. On refund rows it is `0` on that account's row and `null` on the other: the provider does not return its fee when a payment is refunded.                                                                      |
| `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`, `QUEUED`, `SENT`, `PARTIALLY_REVERSED`, `REVERSED`, `FAILED` or `BYPASSED`. A row is held, with nothing moved, while it is `FAILED` with a `NET_RECEIPTS_HOLD:` marker (see [Net Receipts](/prism/payments/payouts/net-receipts.md#hold-conditions)). |
| `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  | Refund rows only, negative: the part of a refund that is more than everything left to refund on the bag. `null` when there is none, which is almost always. See [Refunds Entered as an Amount](/prism/payments/payouts/return-commission-policy.md#refunds-entered-as-an-amount).            |
| `tax_remitter`                    | string   | Who is responsible for tax remittance: `APP` or `MERCHANT`.                                                                                                                                                                                                                                  |
| `duty_remitter`                   | string   | Who is responsible for duty: `APP` or `MERCHANT`.                                                                                                                                                                                                                                            |
| `return_commission_policy`        | string   | The [return commission policy](/prism/payments/payouts/return-commission-policy.md) recorded on the sale: `REVERSE` or `RETAIN`. `null` for sales made before the policy was recorded, which are treated as `REVERSE`.                                                                       |
| `date_created`                    | datetime | Timestamp of when the distribution record was created.                                                                                                                                                                                                                                       |
| `date_last_modified`              | datetime | Timestamp of the last modification to the record.                                                                                                                                                                                                                                            |

## Reading Refund Rows

Each refund writes one `REFUND` row for the retailer and one for your app. Read them this way:

* **`net_distribution_amount` is the only figure that moves.** It is negative on a refund row: the amount taken back from that account. Add it up per account, or per transfer, to reconcile. `distribution_amount` is not set on refund rows.
* **Components are positive.** `tax_amount`, `duty_amount` and `shipping_amount` on a refund row are the amounts refunded, shown as positive figures. The direction comes from `net_distribution_amount`.
* **Commission fields are signed from each account's point of view:** positive on the retailer's row, negative on yours. For this refund's own figure, use `commission_reversed_amount` (under `REVERSE`) or `commission_retained_amount` (under `RETAIN`). `commission` on a refund row is the whole bag's commission, repeated on every refund of the bag; do not add it up.
* **No processing fee comes back.** The payment provider keeps its processing fee when a payment is refunded, so refund rows record `0` for the fee on the payer's row, and nothing changes hands for it.

{% hint style="info" %}
**If your app collects payments in its own Stripe account,** Violet sends transfers to retailers but never to you. The retailer's rows are the ones that move money: a transfer, a reversal of one, or an amount netted against the next transfer. Your rows record your share of each order and refund; they are a record, not a transfer.
{% endhint %}

### Is the money moved yet?

`status` tells you. `SENT` rows have gone out. `PENDING` and `QUEUED` rows go out with the retailer's next transfer. A row held for a missing [Net Receipts](/prism/payments/payouts/net-receipts.md) fee shows `FAILED` with a `NET_RECEIPTS_HOLD:` marker and moves once the fee arrives. One transfer can carry several rows, from several orders, refunds and adjustments; its amount is the sum of the `net_distribution_amount` of the rows linked to it through `payout_transfer_id`.

### Example: a partial refund under each policy

A sale of $100.00 of goods, $10.00 shipping and $8.00 tax remitted by the retailer, at 15% commission. Your app pays the payment provider's fee. The shopper returns one $40.00 item and is refunded $43.20, including $3.20 tax. Amounts are in cents.

| Field                        | Retailer's row, `REVERSE` | Your row, `REVERSE` | Retailer's row, `RETAIN` | Your row, `RETAIN` |
| ---------------------------- | ------------------------- | ------------------- | ------------------------ | ------------------ |
| `net_distribution_amount`    | `-3720`                   | `-600`              | `-3720`                  | `0`                |
| `distribution_amount`        | `null`                    | `null`              | `null`                   | `null`             |
| `tax_amount`                 | `320`                     | `0`                 | `320`                    | `0`                |
| `shipping_amount`            | `0`                       | `0`                 | `0`                      | `0`                |
| `commission`                 | `1500`                    | `-1500`             | `1500`                   | `-1500`            |
| `commission_reversed_amount` | `600`                     | `-600`              | `0`                      | `0`                |
| `commission_retained_amount` | `null`                    | `null`              | `600`                    | `-600`             |
| `payment_provider_total_fee` | `null`                    | `0`                 | `null`                   | `0`                |

Under `RETAIN` the retailer still owes the $6.00 you kept. Violet recovers it from the retailer's payouts through a recovery case, which you follow in the [Recovery Cases API](/prism/payments/payouts/commission-recovery/recovery-cases-api.md) and [webhooks](/prism/webhooks/events/recovery-case-webhooks.md). A recovery does not add a distribution row today; see [Retained Commission Recovery](/prism/payments/payouts/commission-recovery.md#in-distributions).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.violet.io/prism/payments/payouts/distributions/distributions-apis.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
