Payouts

Beta

This endpoint is in beta. Its shape may still change, and until it is generally available the list action returns a single payout per page (see List payouts).

Overview

This resource exposes SmilyPay payouts — the money Smily pays out — together with the per-booking breakdown that explains each payout. For every line it shows the payment collected, the Smily fees deducted on top of it, the resulting payout and that line's contribution to the payout total.

The row_type of an item depends on who collected the guest's money:

• Direct bookings — SmilyPay collected the guest's card payment. row_type is smily_pay_payment, and this endpoint accounts for the whole amount. See Direct bookings below.
• OTA bookings — a channel collected from the guest and wired Smily a net amount. row_type is channel_payout. This endpoint reports only the Smily fees deducted from that net amount, not how the channel arrived at it; for that, use related_channel_payout_references to look the booking up on Channel Payouts.

Both apply to the same booking when a property manager sells an upsell on an OTA booking and collects it through SmilyPay: that payment produces a smily_pay_payment line in addition to the channel_payout line. See OTA bookings with a SmilyPay upsell.

This endpoint therefore reports the fees Smily deducted between collection and payout. On an OTA booking, a payout lower than the guest was charged with no Smily fee to account for it means the channel wired less — an OTA commission, an adjustment or a resolution — which is reported on Channel Payouts. On a direct booking there is no upstream: the cause is on this endpoint, usually the split-payment distribution or a payment that settled in a different payout.

Each payout carries a list of items. The relationship to reconcile against is at the payout level, not the line level:

Σ(item.balance_in_cents) = payout.amount_in_cents

This holds when every line in the payout settles to a single party. It does not hold on an account using split payment, where a booking's line appears in both parties' payouts carrying the combined figure — see Split payment. amount_in_cents is always authoritative: it is what this payout moved to this gateway. Where the two disagree, trust amount_in_cents.

balance_in_cents is each line's own contribution to that total, and how it is derived depends on row_type — there is no single per-line equation. In particular balance_in_cents is not smily_payout_amount_in_cents; the two answer different questions and on a channel line they routinely differ.

• channel_payout — balance is the net amount the channel wired for this booking, less the Smily fees taken from it: smily_pay_payment_amount − smily_traveller_fee − smily_cancelation_protection_fee − smily_split_payment_fee. Note that this net is already after whatever the channel itself deducted; Smily's fees come off on top of that. A line where the channel wired 150.00 and Smily took a 15.00 traveller fee has balance_in_cents: 13500.

  smily_payout_amount_in_cents answers a different question — what was actually transferred to the property manager and the owner.

• smily_pay_payment — balance is the distribution the booking's reconciliation decided: the amount owed to the property manager plus the amount owed to the owner. When that comes to zero it is instead the negative of the gateway fee — a booking that paid nothing out but still cost a gateway fee reduces the payout. This is why balance_in_cents can be negative.

• the four carry-over rows — balance is the negative of the amount collected.

• cancelation_protection_reimbursement — balance is the amount reimbursed, positive.

• account_channel_payout — balance is the account-level movement less its traveller and split-payment fees.

Every row type other than the two booking rows carries no smily_pay_payment_amount_in_cents at all (null), because it moves money that was not collected on this line. Read row_type before doing arithmetic on a line.

The OTA-side decomposition (channel commission, withheld city tax, …) is therefore intentionally not on this endpoint; a channel-settled booking only carries related_channel_payout_references here.

For a walk-through of how the two endpoints fit together — including how to diagnose a payout that is smaller than expected — see the Understanding payouts guide.

Payouts are scoped to a single payment gateway — you must pass payment_gateway_id on every request (see Required parameters).

note

This endpoint is read-only. Payouts are produced internally by Smily; there is no way to create, update or delete them through the API.

Required parameters

Name	Type	Description
payment_gateway_id	Integer	Required. The Payment Gateway whose payouts to return. Omitting it returns 400 Bad Request.

Parameters

OAuth Scopes:

payouts_read

Name	Type	Read/Write	Description
payout_id	Integer	Read	Payout's id.
currency	String	Read	Payout's currency code, list of codes described in enums section.
amount_in_cents	Integer	Read	The total amount Smily paid out, in cents.
scheduled_at	Time	Read	When the payout was scheduled. The default sort key.
updated_at	Time	Read	When the payout was last updated. This is what updated_since filters on.
items	Array	Read	The per-booking breakdown of the payout. See Payout item below.

Payout item

Each element of items:

Name	Type	Description
row_type	String	The kind of line. One of smily_pay_payment, channel_payout, account_channel_payout, gateway_fees_debt, traveller_fee_debt, split_payment_fee_debt, cancelation_protection_debt, cancelation_protection_reimbursement.
payout_type	String	How the line arose. Either one of three values Smily sets, or the channel's own value passed through verbatim — see Payout types. May be null.
booking_id	Integer	The Booking this item belongs to. null on account_channel_payout lines.
initial_price_in_cents	Integer	The booking's initial price, in cents. May be null.
final_price_in_cents	Integer	The booking's final price, in cents. May be null.
channel_price_in_cents	Integer	The booking's channel price, in cents. null for direct bookings that never had a channel price.
smily_pay_payment_amount_in_cents	Integer	The payment amount SmilyPay collected for this line, in cents.
smily_split_payment_fee_in_cents	Integer	The Smily split-payment fee deducted, in cents. May be null when not applicable. On a split_payment_fee_debt line it carries the whole carry-over amount rather than a fee taken from a payment.
smily_traveller_fee_in_cents	Integer	The Smily traveller fee deducted, in cents. May be null. On a traveller_fee_debt line it carries the whole carry-over amount rather than a fee taken from a payment.
smily_cancelation_protection_fee_in_cents	Integer	The Smily cancelation-protection fee deducted, in cents. May be null. On a cancelation_protection_debt line it carries the whole carry-over amount rather than a fee taken from a payment.
smily_payment_gateway_fee_in_cents	Integer	The Smily payment-gateway fee deducted, in cents. 0 on channel-settled lines; null on account_channel_payout, cancelation_protection_reimbursement and on the three carry-over lines that are not gateway fees; and on a gateway_fees_debt line it carries the whole carry-over amount rather than a fee taken from a payment.
smily_payout_amount_in_cents	Integer	The amount transferred for this line, in cents — the property-manager and owner shares combined on a booking line, 0 on a carry-over line. Under split payment this is the booking's total across both parties, not the part this payout moved. May be null on lines that transfer nothing.
balance_in_cents	Integer	This line's contribution to the payout total, in cents. Not a running total, and not the same as smily_payout_amount_in_cents — see Overview for how it is derived per row_type. Negative on carry-over lines, which reduce what is paid out. These sum to amount_in_cents only when each line settles to a single party — see split payment.
related_channel_payout_references	Array	References of the Channel Payouts related to this line's booking, so you can pivot to the channel-movements endpoint. Empty on a direct booking; populated on a smily_pay_payment line covering an upsell on an OTA booking. A carry-over or reimbursement line can be empty whatever the booking's origin, so do not use this alone to classify a line — read row_type first. Normally populated on account_channel_payout lines, which carry their own payout's reference.

Payout types

payout_type has two different origins depending on the line, and only one of them is a closed set.

Set by Smily — these three, and no others:

Value	On which lines	Meaning
Reservation	smily_pay_payment	Money SmilyPay collected — a direct booking, or an upsell on an OTA booking.
Smily carry-over amount collection	gateway_fees_debt, traveller_fee_debt, split_payment_fee_debt, cancelation_protection_debt	A Smily fee an earlier payout could not fund, collected now. All four carry-over kinds print this same value — read row_type to tell them apart, and see the note below.
Cancellation protection reimbursement	cancelation_protection_reimbursement	A cancellation-protection payout back to the property manager.

Passed through from the channel — an open set. On channel_payout and account_channel_payout lines, payout_type is whatever the channel put on the movement. Smily does not normalise, translate or validate it, so treat it as an opaque string rather than an enum. Values we have observed:

• Airbnb — Reservation, Resolution Adjustment, Resolution Payout, Pass Through Tot, Cancellation Fee
• Booking.com — Reservation, RESERVATION, Net, NET, GROSS, Damage deposit, DAMAGE_POLICY, Commission adjustment, and at account level COMMISSION_CORRECTION, DOCUMENT_CLEARING, credit_note, customer_complaint

That list is a snapshot of what we have seen, not a contract. A channel can start sending a new type at any time and it will flow through to you without any change on our side. Match the ones you care about and pass the rest through — do not raise on an unrecognised value.

Three things to code around:

• Reservation does not tell you the origin. Smily uses it for direct bookings, and both channels use it too. Read row_type to know which endpoint owns the rest of the story.
• Casing is not normalised on channel values — Booking.com sends both Reservation and RESERVATION, both Net and NET. Compare case-insensitively.
• null is possible, when the channel's stored entry declares no type. The line's amounts are still valid; only the label is missing.

Carry-over lines

The four carry-over row types all print the same payout_type, Smily carry-over amount collection, so that value cannot tell them apart. What distinguishes them is row_type and which fee column carries the amount — the two always agree:

row_type	Column carrying the amount
gateway_fees_debt	smily_payment_gateway_fee_in_cents
traveller_fee_debt	smily_traveller_fee_in_cents
split_payment_fee_debt	smily_split_payment_fee_in_cents
cancelation_protection_debt	smily_cancelation_protection_fee_in_cents

Every other fee column on a carry-over line is null.

A carry-over line collects a Smily fee an earlier payout could not fund, and the booking it names is the original one the fee was due on — not the booking being paid in this payout. By design it is not a second charge: the original line was charged less by the same amount. See the Payouts guide for how the two sides pair up.

Channel-settled lines

An item with row_type: "channel_payout" covers a booking an OTA collected for and settled by wiring Smily a net amount. smily_pay_payment_amount_in_cents is that net amount; the smily_* fee columns are what Smily took from it. The OTA-side explanation of why the net was what it was lives on Channel Payouts.

A fee column shows what this payout could fund, not what was due

When the money a channel wires does not cover the Smily fees due on it, the fees are not waived and the payout is not held back. The part that cannot be funded is deferred and collected from a later payout as a carry-over line, and the fee column on this line is reduced by exactly that amount.

So on a channel_payout line, a fee column reading less than you expected — or 0 — can mean either "no such fee was due" or "the fee was due and part of it was deferred". The response does not distinguish the two. To settle it, look for a carry-over line naming the same booking in a later payout.

When several fees are due and the money does not cover them all, each takes what it can and the rest is deferred, so more than one carry-over line can arise from the same booking.

Deferring a fee does not change the payout-level arithmetic: the deferred amount leaves the fee column and balance_in_cents together, so it neither creates nor closes a gap between the lines and amount_in_cents.

To see what a booking owes overall rather than what a single payout moved, read internal_fees on the Booking — payouts are not an accounting view.

Payment-gateway fees are not reported on this line

smily_payment_gateway_fee_in_cents is always 0 on a channel_payout line, because gateway fees apply to money SmilyPay collected and this line covers money the channel wired.

A booking sold through a channel can still incur a gateway fee when part of its money went through SmilyPay — an upsell, for instance. That fee is normally taken during the reconciliation of the SmilyPay payment itself and appears on that booking's smily_pay_payment line, not here.

It becomes a gateway_fees_debt carry-over line only in the edge case where the fee could not be taken from the payment it relates to — typically after a refund.

Account-level lines

An item with row_type: "account_channel_payout" belongs to the account rather than to any single booking. It covers channel money that is not tied to one reservation — an account-wide commission correction, for instance — and it is also the fallback when a channel wires money for a booking that does not exist in Smily.

booking_id is null, smily_pay_payment_amount_in_cents is null, and smily_payout_amount_in_cents carries the amount. The OTA-side explanation lives on Channel Payouts under the same name.

Direct bookings

A direct booking is one Smily sold itself, with no channel involved: SmilyPay collected the guest's card payment. It appears as a smily_pay_payment item with a payout_type of Reservation — a fixed label for this row type, not a value reported by anyone else — and an empty related_channel_payout_references.

OTA bookings with a SmilyPay upsell

row_type names how the money was collected, not where the booking came from. smily_pay_payment means "SmilyPay collected this money", which is true of every direct booking and also of an upsell sold on an OTA booking.

When a property manager sells an upsell on a channel booking and collects it through SmilyPay, that payment goes through the same reconciliation a direct booking does. The booking then appears twice in the payout: a smily_pay_payment line for the upsell, and a channel_payout line for the net amount the OTA wired.

That smily_pay_payment line does carry related_channel_payout_references, because the booking really does have channel payouts. Use the references to tell the two apart:

• empty → a direct booking;
• populated → the SmilyPay-collected part of an OTA booking.

Where its numbers come from

Two different sources feed one line, and the distinction matters when a figure looks off:

• smily_pay_payment_amount_in_cents, smily_payment_gateway_fee_in_cents and smily_payout_amount_in_cents come from the money movements settled in this payout. They describe this payout, not the booking as a whole.
• The traveller fee, the cancellation-protection fee, the split-payment fee and the amounts owed to the property manager and to the owner come from the booking's reconciliation — the record that decides how the collected money is distributed. These are the reconciliation's figures for the booking, so on a booking settling across several payouts they are not necessarily specific to this one.

balance_in_cents on a direct-booking line is the property-manager amount plus the owner amount. When that comes to zero, it is instead the negative of the gateway fee — a booking that paid nothing out but still cost a gateway fee reduces the payout. If the booking has not been reconciled, it falls back to the amount this payout actually moved for the booking.

On these lines, "no fee" is 0 and not null

The reconciliation-sourced fee fields — smily_traveller_fee_in_cents, smily_cancelation_protection_fee_in_cents and smily_split_payment_fee_in_cents — normally carry a number on a smily_pay_payment line. When no such fee applies they read 0, and they read 0 rather than null whether or not the booking has been reconciled yet.

This is the opposite of the convention on Channel Payouts, where null means "not known" and is deliberately distinct from 0. Do not carry that distinction over to these three fields — here there is only 0.

One booking can appear in more than one payout

A booking whose money arrives in several payments settles per payment, so each payout carries only the part that settled in it. A line that looks short against the guest's total price is often complete for the payment it covers. Reconcile across every payout that carries the booking, not against a single one.

When the distribution does not match the configuration

When a booking's money is to be divided between the property manager and the owner, Smily reconciles it before paying out — working out how the collected money is split. That step can fail, most often because the booking is not fully paid, because it carries payments taken outside SmilyPay, or because the booking's source is not eligible for split payments.

Such a booking still pays out, but on a fallback distribution rather than the configured one: the whole amount is directed to a single party instead of being divided. Which party is configured per booking and can be either the property manager or the owner — one property manager may have different fallbacks for different rentals — so do not assume it resolves to the property manager. Nothing on the response announces that a fallback was used; if a booking's payout is not the share you expected, the cause is on the booking, not on the payout.

Split payment

When split payment applies, the SmilyPay payments on a booking are divided between the property manager and the owner rather than paid to a single recipient:

• smily_split_payment_fee_in_cents is Smily's fee for performing the split. The reconciliation records how much of it came from the owner and how much from the property manager.
• This endpoint exposes the total split-payment fee only. The per-party breakdown — how much each side absorbed, and the separate property-manager and owner amounts — is recorded on the reconciliation and surfaced in the payout CSV export, but is not on this response today.
• The two parties are paid through their own payment gateways, so their shares reach them in separate payouts, each requestable from its own payment_gateway_id.

A payout item is party-agnostic

An item describes what happened to the booking, not what this payout paid you. Both balance_in_cents and smily_payout_amount_in_cents cover the property-manager and owner shares together — and because each party is paid from its own gateway, the same booking line appears in both payouts carrying that same combined figure.

Two consequences:

• Σ(item.balance_in_cents) does not equal amount_in_cents on a split-payment account. It includes the share that settled to the other party's gateway. amount_in_cents is correct — it is what this payout actually moved.
• No field on this response tells you how the booking's total divided between the two sides. Do not derive your share by subtracting one line from another.

Per-party attributes that make split-payment payouts reconcilable line by line are planned. Until they ship, reconcile a split-payment account against amount_in_cents per payout.

List payouts

List payouts for a given payment gateway, most recently scheduled first.

GET /payouts?payment_gateway_id=:payment_gateway_id

Pagination

While the endpoint is in beta, rows may be computed on the fly, which is expensive. To avoid timeouts the list action returns one payout per page by default (and caps per_page at 1). Page through the payouts with the standard page parameter; the response meta carries the usual pagination headers.

OAuth Scopes:

payouts_read

response.json

{
  "payouts": [
    {
      "payout_id": 12,
      "currency": "EUR",
      "amount_in_cents": 23390,
      "scheduled_at": "2026-05-14T09:12:44Z",
      "updated_at": "2026-05-14T09:20:03Z",
      "items": [
        {
          "row_type": "smily_pay_payment",
          "payout_type": "Reservation",
          "booking_id": 21,
          "initial_price_in_cents": 100000,
          "final_price_in_cents": 120000,
          "channel_price_in_cents": 130000,
          "smily_pay_payment_amount_in_cents": 10000,
          "smily_split_payment_fee_in_cents": 0,
          "smily_traveller_fee_in_cents": 0,
          "smily_cancelation_protection_fee_in_cents": 0,
          "smily_payment_gateway_fee_in_cents": 110,
          "smily_payout_amount_in_cents": 9890,
          "balance_in_cents": 9890,
          "related_channel_payout_references": []
        },
        {
          "row_type": "channel_payout",
          "payout_type": "Reservation",
          "booking_id": 22,
          "initial_price_in_cents": 100000,
          "final_price_in_cents": 120000,
          "channel_price_in_cents": 130000,
          "smily_pay_payment_amount_in_cents": 15000,
          "smily_split_payment_fee_in_cents": 0,
          "smily_traveller_fee_in_cents": 1500,
          "smily_cancelation_protection_fee_in_cents": 0,
          "smily_payment_gateway_fee_in_cents": 0,
          "smily_payout_amount_in_cents": 13500,
          "balance_in_cents": 13500,
          "related_channel_payout_references": [
            "G-NSGICZAZU4AFZ57LJ2CVTORKUYCG34ZR"
          ]
        }
      ]
    }
  ],
  "meta": {
    "Link": {
      "first": "https://www.bookingsync.com/api/v3/payouts?page=1&payment_gateway_id=7",
      "last": "https://www.bookingsync.com/api/v3/payouts?page=1&payment_gateway_id=7"
    },
    "X-Total-Pages": "1",
    "X-Total-Count": "1",
    "X-Per-Page": "1"
  }
}

Search payouts

Search parameters allow to filter payouts by specified fields.

Example:

GET /payouts?payment_gateway_id=7&id=12

Search Parameters

Name	Type	Description
id	Integer	List of comma separated IDs. Returns only the payouts with these ids. While the endpoint is in beta per_page is capped at 1, so passing several ids returns them one page at a time.
updated_since	String	Returns only payouts updated after the given ISO 8601 timestamp — the standard incremental-sync cursor, matched against updated_at. See the Updated since flow guide.
sort	String	Sort by one or more attributes, comma separated, - for descending. Defaults to -scheduled_at,-id (most recently scheduled first); passing sort overrides that default. id, scheduled_at, created_at and updated_at are sortable.

When updated_since is given, the response meta also carries a deleted_ids array for parity with the other incremental-sync endpoints. Payouts are never soft-deleted, so it is always empty here.

Get a single payout

Returns a single payout identified by ID (still scoped by the required payment_gateway_id).

GET /payouts/:payout_id?payment_gateway_id=:payment_gateway_id

note

This action returns the same array envelope as the list action — {"payouts": [ … ]} with a single element — not a bare payout object. An unknown or unauthorized payment_gateway_id returns 404 Not Found.

OAuth Scopes:

payouts_read

response.json

{
  "payouts": [
    {
      "payout_id": 12,
      "currency": "EUR",
      "amount_in_cents": 23390,
      "scheduled_at": "2026-05-14T09:12:44Z",
      "updated_at": "2026-05-14T09:20:03Z",
      "items": [
        {
          "row_type": "smily_pay_payment",
          "payout_type": "Reservation",
          "booking_id": 21,
          "initial_price_in_cents": 100000,
          "final_price_in_cents": 120000,
          "channel_price_in_cents": 130000,
          "smily_pay_payment_amount_in_cents": 10000,
          "smily_split_payment_fee_in_cents": 0,
          "smily_traveller_fee_in_cents": 0,
          "smily_cancelation_protection_fee_in_cents": 0,
          "smily_payment_gateway_fee_in_cents": 110,
          "smily_payout_amount_in_cents": 9890,
          "balance_in_cents": 9890,
          "related_channel_payout_references": []
        },
        {
          "row_type": "channel_payout",
          "payout_type": "Reservation",
          "booking_id": 22,
          "initial_price_in_cents": 100000,
          "final_price_in_cents": 120000,
          "channel_price_in_cents": 130000,
          "smily_pay_payment_amount_in_cents": 15000,
          "smily_split_payment_fee_in_cents": 0,
          "smily_traveller_fee_in_cents": 1500,
          "smily_cancelation_protection_fee_in_cents": 0,
          "smily_payment_gateway_fee_in_cents": 0,
          "smily_payout_amount_in_cents": 13500,
          "balance_in_cents": 13500,
          "related_channel_payout_references": [
            "G-NSGICZAZU4AFZ57LJ2CVTORKUYCG34ZR"
          ]
        }
      ]
    }
  ],
  "meta": {
    "Link": {
      "first": "https://www.bookingsync.com/api/v3/payouts?page=1&payment_gateway_id=7",
      "last": "https://www.bookingsync.com/api/v3/payouts?page=1&payment_gateway_id=7"
    },
    "X-Total-Pages": "1",
    "X-Total-Count": "1",
    "X-Per-Page": "1"
  }
}