The ListPayoutEntries endpoint provides a list of payout entries associated with a specific payout.
Payouts API

List Payout Entries

The ListPayoutEntries endpoint provides a list of payout entries associated with a specific payout. You need to pass payout-entries as an argument to this endpoint. To call this endpoint, set PAYOUTS_READ for the OAuth scope.

Payout entries are the individual transactions that are part of each payout. Chargebacks, refunds, and disputes appear independently as payout entries. If a seller is paying for Square SaaS products, the subscription fee payment appears as a payout entry as well.

You can order the payout entries in ascending or descending order. You cannot, however, retrieve a specific payout entry.

Similar to the ListPayouts endpoint, the ListPayoutEntries endpoint supports pagination.

List Payout Entries
  • 1
  • 2
  • 3
  • 4
curl https://connect.squareupsandbox.com/v2/payouts/{{PAYOUT_ID}}/payout-entries \
  -H 'Square-Version: 2023-03-15' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

The following is an example response:

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
  • 26
  • 27
  • 28
  • 29
  • 30
  • 31
  • 32
  • 33
  • 34
  • 35
  • 36
  • 37
  • 38
  • 39
  • 40
  • 41
  • 42
  • 43
  • 44
  • 45
  • 46
  • 47
  • 48
  • 49
  • 50
  • 51
  • 52
  • 53
  • 54
  • 55
  • 56
  • 57
  • 58
  • 59
  • 60
  • 61
  • 62
  • 63
  • 64
{
  "payout_entries": [
    {
      "id": "poe_5DhstmLsgJD0x3Cym3Cnislc0KM",
      "payout_id": "po_070431e4-e351-11eb-a8bb-02420a140009",
      "effective_at": "2021-07-08T08:41:27Z",
      "type": "CHARGE",
      "gross_amount_money": {
        "amount": 300,
        "currency_code": "EUR"
      },
      "fee_amount_money": {
        "amount": 25,
        "currency_code": "EUR"
      },
      "net_amount_money": {
        "amount": 275,
        "currency_code": "EUR"
      },
      "type_charge_details": {
        "payment_id": "PN5zqrHRbWR8fLkgVarzGaW9TYMZY"
      }
    },
    {
      "id": "poe_EOmSnV5uar_z06m2AvY0wTvHwVg",
      "payout_id": "po_070431e4-e351-11eb-a8bb-02420a140009",
      "effective_at": "2021-07-08T08:34:49Z",
      "type": "CHARGE",
      "gross_amount_money": {
        "amount": 100,
        "currency_code": "EUR"
      },
      "fee_amount_money": {
        "amount": 18,
        "currency_code": "EUR"
      },
      "net_amount_money": {
        "amount": 82,
        "currency_code": "EUR"
      },
      "type_charge_details": {
        "payment_id": "LVkuK15FwYPjRdmVXetEo15oUUKZY"
      }
    },
    {
      "id": "poe_q6wpw3W-VD7PVvmvXUduMy-zCTY",
      "payout_id": "po_070431e4-e351-11eb-a8bb-02420a140009",
      "effective_at": "2021-06-10T21:54:15Z",
      "type": "ADJUSTMENT",
      "gross_amount_money": {
        "amount": 100,
        "currency_code": "EUR"
      },
      "fee_amount_money": {
        "amount": 0,
        "currency_code": "EUR"
      },
      "net_amount_money": {
        "amount": 100,
        "currency_code": "EUR"
      }
    }
  ]
}

The type_<payout entry type>_details field in a payout entry contains information specific to the type of the payout entry.

For the following types of payout entries, you can call other APIs using the type_<payout entry type>_details IDs to get more information:

In the following example, the type_charge_details field represents a payout entry that captures a credit card payment.

To get details about the payment, you can use the payment_id with the Payments API.

In the following example, the type_open_dispute_details field represents a payout entry that is a balance change for a dispute that has been filed.

To get details about the payment, use the payment_id with the Payments API. To get details about the dispute, use the dispute_id with the Disputes API.

In the following example, the type_refund_details field represents a payout entry that is a refund.

To get details about the payment, use the payment_id with the Payments API. To get details about the refund, use the refund_id with the Refunds API.

For a full list and definitions, see Payouts API Reference.

For charges or refunds, you can retrieve the total taxes and tip amounts, where applicable, using the additional details that you get back in a payout entry.

For example, in the following payout entry, the payment_id of F2eGGWCJZYf4sm4C3g9ial4sepWZY from the type_charge_details field represents the payment:

You can retrieve the payment by using the v2/payments/F2eGGWCJZYf4sm4C3g9ial4sepWZY endpoint.

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
  • 26
  • 27
  • 28
  • 29
  • 30
  • 31
  • 32
  • 33
  • 34
{
  "payment": {
    "id": "F2eGGWCJZYf4sm4C3g9ial4sepWZY",
    "created_at": "2022-01-26T20:07:45.491Z",
    "updated_at": "2022-01-26T20:07:47.927Z",
    "amount_money": {
      "amount": 1000,
      "currency": "USD"
    },
     ...
    "location_id": "LCRS9JV5GZ9AZ",
    "order_id": "vhZTpadtU5FPT4JaIWBMMEvVFFTZY",
    "processing_fee": [
      {
        "effective_at": "2022-01-26T22:07:46.000Z",
        "type": "INITIAL",
        "amount_money": {
          "amount": 50,
          "currency": "USD"
        }
      }
    ],
    "customer_id": "BXRNCQ6T94T6Z27RMCD8KS8B14",
    "total_money": {
      "amount": 1000,
      "currency": "USD"
    },
    "approved_money": {
      "amount": 1000,
      "currency": "USD"
    },
     ...
  }
}

With the order ID from the Payment object, you can use the orders endpoint (v2/orders/vhZTpadtU5FPT4JaIWBMMEvVFFTZY) to retrieve the order information containing the taxes and tips. For more information, see RetrieveOrder.

We've made improvements to our docs.
Prefer the old format?