BackstageClient.ledger
BackstageClient.ledger in @ticketlayer/backstage.
@ticketlayer/backstage / BackstageClient / ledger
ledger: {
balances: (options?: {
accountId: string;
asOf?: string;
book?: "live" | "test";
currency?: string;
groupBy?: "event";
}, requestOptions?: RequestOptions) => Promise<{
accountId: string;
asOf: string | null;
book: "live" | "test";
counterparties: {
amountOwed: number;
balance: number;
counterpartyAccountId: string;
currency: string;
direction: "owes" | "owed";
eventFirstOccurrenceAt: string | null;
eventId: string | null;
path: string;
postingCount: number;
}[];
groupBy: "event" | null;
totals: {
currency: string;
net: number;
owed: number;
owes: number;
}[];
}>;
createSettlement: (request: {
allocations?: {
amount: number;
eventId: string;
}[];
amount: number;
book?: "live" | "test";
currency: string;
method: "other" | "bank_transfer" | "cash" | "internal_offset";
note?: string;
paidAt?: string;
payeeAccountId: string;
payerAccountId: string;
reference?: string;
}, requestOptions?: RequestOptions) => Promise<{
payable: {
amountOwed: number;
balance: number;
counterpartyAccountId: string;
currency: string;
direction: "owes" | "owed";
eventFirstOccurrenceAt: string | null;
eventId: string | null;
path: string;
postingCount: number;
};
replayed: boolean;
settlement: {
allocations: {
amount: number;
eventId: string;
eventName: string | null;
source: "explicit" | "oldest_first";
}[];
amount: number;
book: "live" | "test";
createdAt: string;
currency: string;
id: string;
journalId: string;
method: "other" | "bank_transfer" | "cash" | "internal_offset";
note: string | null;
paidAt: string;
payeeAccountId: string;
payerAccountId: string;
recordedByUserId: string | null;
reference: string | null;
reversalReason: string | null;
reversedAt: string | null;
reversedByJournalId: string | null;
reversedByUserId: string | null;
status: "recorded" | "reversed";
unallocatedAmount: number;
};
}>;
eventStatement: (eventId: string, options?: {
book?: "live" | "test";
currency?: string;
ordersCursor?: string;
ordersLimit?: number;
}, requestOptions?: RequestOptions) => Promise<{
book: "live" | "test";
currencies: {
costs: {
bearerId: string;
platformFees: number;
processingFees: number;
total: number;
}[];
currency: string;
fees: {
charged: number;
earnerId: string;
net: number;
refunded: number;
}[];
feeWaivers: number | null;
holders: {
beneficiaryId: string;
holderId: string;
outstanding: {
amount: number;
amountOwed: number;
counterpartyId: string;
owedBy: string | null;
owedTo: string | null;
partyId: string;
postingCount: number;
state: "outstanding" | "settled" | "empty";
};
owed: number;
settled: number;
}[];
owner: | {
chargebacks: number;
discounts: number;
gross: number;
net: number;
partyId: string;
postingCount: number;
refunds: number;
tax: number;
}
| null;
revenue: (
| {
chargebacks: number;
discounts: number;
gross: number;
net: number;
partyId: string;
postingCount: number;
refunds: number;
tax: number;
}
| null)[];
}[];
eventId: string;
eventName: string;
orders: {
chargebacks: number;
createdAt: string;
currency: string;
discounts: number;
gross: number;
net: number;
orderId: string;
orderNumber: string;
orderTotal: number;
refundJournalIds: string[];
refunds: number;
saleJournalId: string | null;
status: string;
}[];
ordersNextCursor: string | null;
ownerAccountId: string;
view: "party" | "full";
visibleParties: string[] | null;
}>;
exceptions: (options?: {
cursor?: string;
includeResolved?: "true" | "false";
kind?: | "refund"
| "other"
| "payment"
| "payout"
| "dispute"
| "balance_transaction"
| "application_fee";
limit?: number;
status?: "open" | "resolved" | "all";
}, requestOptions?: RequestOptions) => Promise<{
exceptions: {
attempts: number;
causeId: string;
causeType: string;
error: string;
errorCode: string | null;
firstSeenAt: string;
id: string;
inboundEventId: string | null;
kind: | "refund"
| "other"
| "payment"
| "payout"
| "dispute"
| "balance_transaction"
| "application_fee";
lastSeenAt: string;
resolvedAt: string | null;
retryable: boolean;
source: "api" | "workflow" | "webhook" | "replay" | "script";
}[];
nextCursor: string | null;
}>;
payout: (payoutId: string, requestOptions?: RequestOptions) => Promise<{
fees: number;
gross: number;
groups: {
adjustments: {
amount: number;
fee: number;
lines: {
amount: number;
availableOn: string | null;
category: | "refund"
| "other"
| "payout"
| "dispute"
| "charge"
| "application_fee_refund"
| "platform_application_fee";
currency: string;
disputeId: string | null;
externalId: string;
fee: number;
id: string;
journalId: string | null;
matched: boolean;
net: number;
occurredAt: string;
orderId: string | null;
orderNumber: string | null;
paymentId: string | null;
refundId: string | null;
sourceId: string | null;
type: string;
}[];
net: number;
};
applicationFees: {
amount: number;
fee: number;
lines: {
amount: number;
availableOn: string | null;
category: | "refund"
| "other"
| "payout"
| "dispute"
| "charge"
| "application_fee_refund"
| "platform_application_fee";
currency: string;
disputeId: string | null;
externalId: string;
fee: number;
id: string;
journalId: string | null;
matched: boolean;
net: number;
occurredAt: string;
orderId: string | null;
orderNumber: string | null;
paymentId: string | null;
refundId: string | null;
sourceId: string | null;
type: string;
}[];
net: number;
};
charges: {
amount: number;
fee: number;
lines: {
amount: number;
availableOn: string | null;
category: | "refund"
| "other"
| "payout"
| "dispute"
| "charge"
| "application_fee_refund"
| "platform_application_fee";
currency: string;
disputeId: string | null;
externalId: string;
fee: number;
id: string;
journalId: string | null;
matched: boolean;
net: number;
occurredAt: string;
orderId: string | null;
orderNumber: string | null;
paymentId: string | null;
refundId: string | null;
sourceId: string | null;
type: string;
}[];
net: number;
};
disputes: {
amount: number;
fee: number;
lines: {
amount: number;
availableOn: string | null;
category: | "refund"
| "other"
| "payout"
| "dispute"
| "charge"
| "application_fee_refund"
| "platform_application_fee";
currency: string;
disputeId: string | null;
externalId: string;
fee: number;
id: string;
journalId: string | null;
matched: boolean;
net: number;
occurredAt: string;
orderId: string | null;
orderNumber: string | null;
paymentId: string | null;
refundId: string | null;
sourceId: string | null;
type: string;
}[];
net: number;
};
fees: {
amount: number;
fee: number;
lines: {
amount: number;
availableOn: string | null;
category: | "refund"
| "other"
| "payout"
| "dispute"
| "charge"
| "application_fee_refund"
| "platform_application_fee";
currency: string;
disputeId: string | null;
externalId: string;
fee: number;
id: string;
journalId: string | null;
matched: boolean;
net: number;
occurredAt: string;
orderId: string | null;
orderNumber: string | null;
paymentId: string | null;
refundId: string | null;
sourceId: string | null;
type: string;
}[];
net: number;
};
refunds: {
amount: number;
fee: number;
lines: {
amount: number;
availableOn: string | null;
category: | "refund"
| "other"
| "payout"
| "dispute"
| "charge"
| "application_fee_refund"
| "platform_application_fee";
currency: string;
disputeId: string | null;
externalId: string;
fee: number;
id: string;
journalId: string | null;
matched: boolean;
net: number;
occurredAt: string;
orderId: string | null;
orderNumber: string | null;
paymentId: string | null;
refundId: string | null;
sourceId: string | null;
type: string;
}[];
net: number;
};
};
net: number;
payout: {
amount: number;
arrivalDate: string;
balanceTransactionCount: number;
book: "live" | "test";
currency: string;
destinationLast4: string | null;
externalId: string;
failedAt: string | null;
failureCode: string | null;
holderId: string;
id: string;
journalId: string | null;
paidAt: string | null;
pspBalanceId: string;
reconciled: boolean;
reconciledAt: string | null;
reversalJournalId: string | null;
status: "failed" | "paid" | "pending" | "in_transit" | "canceled";
unmatchedCount: number;
};
reconciled: boolean;
unmatchedCount: number;
}>;
payouts: (options?: {
accountId?: string;
book?: "live" | "test";
cursor?: string;
from?: string;
limit?: number;
pspBalanceId?: string;
status?: "failed" | "paid" | "pending" | "in_transit" | "canceled";
to?: string;
}, requestOptions?: RequestOptions) => Promise<{
nextCursor: string | null;
payouts: {
amount: number;
arrivalDate: string;
balanceTransactionCount: number;
book: "live" | "test";
currency: string;
destinationLast4: string | null;
externalId: string;
failedAt: string | null;
failureCode: string | null;
holderId: string;
id: string;
journalId: string | null;
paidAt: string | null;
pspBalanceId: string;
reconciled: boolean;
reconciledAt: string | null;
reversalJournalId: string | null;
status: "failed" | "paid" | "pending" | "in_transit" | "canceled";
unmatchedCount: number;
}[];
}>;
retryException: (exceptionId: string, requestOptions?: RequestOptions) => Promise<{
exception: {
attempts: number;
causeId: string;
causeType: string;
error: string;
errorCode: string | null;
firstSeenAt: string;
id: string;
inboundEventId: string | null;
kind: | "refund"
| "other"
| "payment"
| "payout"
| "dispute"
| "balance_transaction"
| "application_fee";
lastSeenAt: string;
resolvedAt: string | null;
retryable: boolean;
source: "api" | "workflow" | "webhook" | "replay" | "script";
};
outcome: "failed" | "resolved";
}>;
reverseSettlement: (settlementId: string, request: {
reason: string;
}, requestOptions?: RequestOptions) => Promise<{
journal: {
description: string | null;
journalId: string;
lines: {
amount: number;
eventId: string | null;
path: string;
postingId: string;
}[];
occurredAt: string;
};
position: {
events: {
after: {
amount: number;
amountOwed: number;
counterpartyId: string;
owedBy: string | null;
owedTo: string | null;
partyId: string;
postingCount: number;
state: "outstanding" | "settled" | "empty";
};
before: {
amount: number;
amountOwed: number;
counterpartyId: string;
owedBy: string | null;
owedTo: string | null;
partyId: string;
postingCount: number;
state: "outstanding" | "settled" | "empty";
};
current: {
amount: number;
amountOwed: number;
counterpartyId: string;
owedBy: string | null;
owedTo: string | null;
partyId: string;
postingCount: number;
state: "outstanding" | "settled" | "empty";
};
} & {
allocated: number;
eventId: string;
eventName: string | null;
}[];
total: {
after: {
amount: number;
amountOwed: number;
counterpartyId: string;
owedBy: string | null;
owedTo: string | null;
partyId: string;
postingCount: number;
state: "outstanding" | "settled" | "empty";
};
before: {
amount: number;
amountOwed: number;
counterpartyId: string;
owedBy: string | null;
owedTo: string | null;
partyId: string;
postingCount: number;
state: "outstanding" | "settled" | "empty";
};
current: {
amount: number;
amountOwed: number;
counterpartyId: string;
owedBy: string | null;
owedTo: string | null;
partyId: string;
postingCount: number;
state: "outstanding" | "settled" | "empty";
};
};
};
reversal: {
description: string | null;
journalId: string;
lines: {
amount: number;
eventId: string | null;
path: string;
postingId: string;
}[];
occurredAt: string;
} & Record<string, never>;
settlement: {
allocations: {
amount: number;
eventId: string;
eventName: string | null;
source: "explicit" | "oldest_first";
}[];
amount: number;
book: "live" | "test";
createdAt: string;
currency: string;
id: string;
journalId: string;
method: "other" | "bank_transfer" | "cash" | "internal_offset";
note: string | null;
paidAt: string;
payeeAccountId: string;
payerAccountId: string;
recordedByUserId: string | null;
reference: string | null;
reversalReason: string | null;
reversedAt: string | null;
reversedByJournalId: string | null;
reversedByUserId: string | null;
status: "recorded" | "reversed";
unallocatedAmount: number;
};
}>;
settlement: (settlementId: string, requestOptions?: RequestOptions) => Promise<{
journal: {
description: string | null;
journalId: string;
lines: {
amount: number;
eventId: string | null;
path: string;
postingId: string;
}[];
occurredAt: string;
};
position: {
events: {
after: {
amount: number;
amountOwed: number;
counterpartyId: string;
owedBy: string | null;
owedTo: string | null;
partyId: string;
postingCount: number;
state: "outstanding" | "settled" | "empty";
};
before: {
amount: number;
amountOwed: number;
counterpartyId: string;
owedBy: string | null;
owedTo: string | null;
partyId: string;
postingCount: number;
state: "outstanding" | "settled" | "empty";
};
current: {
amount: number;
amountOwed: number;
counterpartyId: string;
owedBy: string | null;
owedTo: string | null;
partyId: string;
postingCount: number;
state: "outstanding" | "settled" | "empty";
};
} & {
allocated: number;
eventId: string;
eventName: string | null;
}[];
total: {
after: {
amount: number;
amountOwed: number;
counterpartyId: string;
owedBy: string | null;
owedTo: string | null;
partyId: string;
postingCount: number;
state: "outstanding" | "settled" | "empty";
};
before: {
amount: number;
amountOwed: number;
counterpartyId: string;
owedBy: string | null;
owedTo: string | null;
partyId: string;
postingCount: number;
state: "outstanding" | "settled" | "empty";
};
current: {
amount: number;
amountOwed: number;
counterpartyId: string;
owedBy: string | null;
owedTo: string | null;
partyId: string;
postingCount: number;
state: "outstanding" | "settled" | "empty";
};
};
};
reversal: {
description: string | null;
journalId: string;
lines: {
amount: number;
eventId: string | null;
path: string;
postingId: string;
}[];
occurredAt: string;
} & Record<string, never>;
settlement: {
allocations: {
amount: number;
eventId: string;
eventName: string | null;
source: "explicit" | "oldest_first";
}[];
amount: number;
book: "live" | "test";
createdAt: string;
currency: string;
id: string;
journalId: string;
method: "other" | "bank_transfer" | "cash" | "internal_offset";
note: string | null;
paidAt: string;
payeeAccountId: string;
payerAccountId: string;
recordedByUserId: string | null;
reference: string | null;
reversalReason: string | null;
reversedAt: string | null;
reversedByJournalId: string | null;
reversedByUserId: string | null;
status: "recorded" | "reversed";
unallocatedAmount: number;
};
}>;
settlements: (options?: {
book?: "live" | "test";
counterpartyAccountId?: string;
currency?: string;
cursor?: string;
eventId?: string;
from?: string;
limit?: number;
party?: string;
status?: "recorded" | "reversed";
to?: string;
}, requestOptions?: RequestOptions) => Promise<{
nextCursor: string | null;
settlements: {
allocations: {
amount: number;
eventId: string;
eventName: string | null;
source: "explicit" | "oldest_first";
}[];
amount: number;
book: "live" | "test";
createdAt: string;
currency: string;
id: string;
journalId: string;
method: "other" | "bank_transfer" | "cash" | "internal_offset";
note: string | null;
paidAt: string;
payeeAccountId: string;
payerAccountId: string;
recordedByUserId: string | null;
reference: string | null;
reversalReason: string | null;
reversedAt: string | null;
reversedByJournalId: string | null;
reversedByUserId: string | null;
status: "recorded" | "reversed";
unallocatedAmount: number;
}[];
}>;
statement: (options?: {
accountId?: string;
book?: "live" | "test";
counterpartyAccountId?: string;
currency: string;
cursor?: string;
eventId?: string;
from?: string;
limit?: number;
party?: string;
to?: string;
}, requestOptions?: RequestOptions) => Promise<{
accountId: string;
basis: "position" | "counterparty";
book: "live" | "test";
closingBalance: number;
counterpartyAccountId: string | null;
currency: string;
eventId: string | null;
from: string | null;
lines: {
amount: number;
category: | "other"
| "sales"
| "discounts"
| "refunds"
| "chargebacks"
| "fees_earned"
| "fees_and_costs"
| "payouts"
| "settlements_paid"
| "settlements_received";
causeId: string;
causeType: string;
currency: string;
description: string | null;
effect: number;
eventId: string | null;
journalId: string;
occurredAt: string;
orderId: string | null;
path: string;
postedAt: string;
postingId: string;
pspPayoutId: string | null;
reversesJournalId: string | null;
runningBalance: number;
settlementId: string | null;
}[];
nextCursor: string | null;
openingBalance: number;
pageOpeningBalance: number;
party: string;
path: string;
summary: {
categories: {
category: | "other"
| "sales"
| "discounts"
| "refunds"
| "chargebacks"
| "fees_earned"
| "fees_and_costs"
| "payouts"
| "settlements_paid"
| "settlements_received";
closing: number;
lineCount: number;
movement: number;
opening: number;
}[];
closing: number;
currency: string;
movement: number;
opening: number;
};
to: string | null;
}>;
};Defined in: client.ts:10734
Ledger methods
balances()#
balances: (options?: {
accountId: string;
asOf?: string;
book?: "live" | "test";
currency?: string;
groupBy?: "event";
}, requestOptions?: RequestOptions) => Promise<{
accountId: string;
asOf: string | null;
book: "live" | "test";
counterparties: {
amountOwed: number;
balance: number;
counterpartyAccountId: string;
currency: string;
direction: "owes" | "owed";
eventFirstOccurrenceAt: string | null;
eventId: string | null;
path: string;
postingCount: number;
}[];
groupBy: "event" | null;
totals: {
currency: string;
net: number;
owed: number;
owes: number;
}[];
}>;Read an account ledger balance
What one party is owed and owes, per counterparty and currency, derived from the postings every time - there is no cached balance to drift. Read from the party's own buckets: its Payables (what it owes, owes) and its Receivables (what it is owed, owed). Whoever holds a buyer's money owes each party entitled to it, and the entitled party's Receivable mirrors the holder's Payable, so a promoter paid through a venue's Stripe account reads what the venue owes it. The party may be an Account or the organisation itself (its own org_ id), which holds the money of an organisation-wide provider. groupBy=event splits each figure by event. Amounts are integer MINOR UNITS and are signed; nothing is clamped at zero, so an over-payment reports a negative amountOwed, meaning the direction has reversed. The organisation is the caller's own, from the credential; requires ledger.read for the named account, or across the whole organisation to read the organisation. An organisation API key also needs its organisation to allow API keys to read the ledger (allowApiKeyLedgerRead on the organisation), or it is refused with 403 API_KEY_LEDGER_READ_NOT_ALLOWED. Reads one book: live unless book=test is asked for, which is where a test order's journals are.
Parameters#
| Parameter | Type |
|---|---|
options? | { accountId: string; asOf?: string; book?: "live" | "test"; currency?: string; groupBy?: "event"; } |
options.accountId? | string |
options.asOf? | string |
options.book? | "live" | "test" |
options.currency? | string |
options.groupBy? | "event" |
requestOptions? | RequestOptions |
Returns#
Promise<{
accountId: string;
asOf: string | null;
book: "live" | "test";
counterparties: {
amountOwed: number;
balance: number;
counterpartyAccountId: string;
currency: string;
direction: "owes" | "owed";
eventFirstOccurrenceAt: string | null;
eventId: string | null;
path: string;
postingCount: number;
}[];
groupBy: "event" | null;
totals: {
currency: string;
net: number;
owed: number;
owes: number;
}[];
}>
Operation Id#
getLedgerBalances
createSettlement()#
createSettlement: (request: {
allocations?: {
amount: number;
eventId: string;
}[];
amount: number;
book?: "live" | "test";
currency: string;
method: "other" | "bank_transfer" | "cash" | "internal_offset";
note?: string;
paidAt?: string;
payeeAccountId: string;
payerAccountId: string;
reference?: string;
}, requestOptions?: RequestOptions) => Promise<{
payable: {
amountOwed: number;
balance: number;
counterpartyAccountId: string;
currency: string;
direction: "owes" | "owed";
eventFirstOccurrenceAt: string | null;
eventId: string | null;
path: string;
postingCount: number;
};
replayed: boolean;
settlement: {
allocations: {
amount: number;
eventId: string;
eventName: string | null;
source: "explicit" | "oldest_first";
}[];
amount: number;
book: "live" | "test";
createdAt: string;
currency: string;
id: string;
journalId: string;
method: "other" | "bank_transfer" | "cash" | "internal_offset";
note: string | null;
paidAt: string;
payeeAccountId: string;
payerAccountId: string;
recordedByUserId: string | null;
reference: string | null;
reversalReason: string | null;
reversedAt: string | null;
reversedByJournalId: string | null;
reversedByUserId: string | null;
status: "recorded" | "reversed";
unallocatedAmount: number;
};
}>;Record a settlement between two accounts
Record that one party paid another, and discharge that much of the obligation. This does NOT mark anything paid: it writes the settlement and, in the same transaction, posts four lines - DR {payer}:Payable:{payee}, CR {payer}:Cash, DR {payee}:Cash, CR {payee}:Receivable:{payer} - so both sides read lower because the postings cancel, and each party's own lines balance. Paying less than the balance leaves the remainder as a balance - there is no partially-settled state. Paying more takes the payable past zero and the payee then owes the payer; that is not an error and is not clamped. Amounts are integer MINOR UNITS. Each party is an Account of your organisation or the organisation itself (its own org_ id); Ticketlayer moves no money between them, this records a payment made elsewhere. book is live unless test is named. The payment may be ALLOCATED to events (allocations, summing to amount); without them it is allocated oldest first across the events the payer owes the payee for, and what is left over is unallocated. Each part posts its own four lines tagged with the event, so what is settled for an event is on its statement. With an Idempotency-Key header the key is kept with the settlement, for good rather than for a day: a retry with the same key and the same request returns that settlement with 200 and posts nothing, and the same key on a different request is refused (422 IDEMPOTENCY_KEY_REUSED). Requires ledger.settle on BOTH the payer and the payee (across the whole organisation for the organisation), which ledger.read does not grant.
Parameters#
| Parameter | Type |
|---|---|
request | { allocations?: { amount: number; eventId: string; }[]; amount: number; book?: "live" | "test"; currency: string; method: "other" | "bank_transfer" | "cash" | "internal_offset"; note?: string; paidAt?: string; payeeAccountId: string; payerAccountId: string; reference?: string; } |
request.allocations? | { amount: number; eventId: string; }[] |
request.amount? | number |
request.book? | "live" | "test" |
request.currency? | string |
request.method? | "other" | "bank_transfer" | "cash" | "internal_offset" |
request.note? | string |
request.paidAt? | string |
request.payeeAccountId? | string |
request.payerAccountId? | string |
request.reference? | string |
requestOptions? | RequestOptions |
Returns#
Promise<{
payable: {
amountOwed: number;
balance: number;
counterpartyAccountId: string;
currency: string;
direction: "owes" | "owed";
eventFirstOccurrenceAt: string | null;
eventId: string | null;
path: string;
postingCount: number;
};
replayed: boolean;
settlement: {
allocations: {
amount: number;
eventId: string;
eventName: string | null;
source: "explicit" | "oldest_first";
}[];
amount: number;
book: "live" | "test";
createdAt: string;
currency: string;
id: string;
journalId: string;
method: "other" | "bank_transfer" | "cash" | "internal_offset";
note: string | null;
paidAt: string;
payeeAccountId: string;
payerAccountId: string;
recordedByUserId: string | null;
reference: string | null;
reversalReason: string | null;
reversedAt: string | null;
reversedByJournalId: string | null;
reversedByUserId: string | null;
status: "recorded" | "reversed";
unallocatedAmount: number;
};
}>
Operation Id#
createLedgerSettlement
eventStatement()#
eventStatement: (eventId: string, options?: {
book?: "live" | "test";
currency?: string;
ordersCursor?: string;
ordersLimit?: number;
}, requestOptions?: RequestOptions) => Promise<{
book: "live" | "test";
currencies: {
costs: {
bearerId: string;
platformFees: number;
processingFees: number;
total: number;
}[];
currency: string;
fees: {
charged: number;
earnerId: string;
net: number;
refunded: number;
}[];
feeWaivers: number | null;
holders: {
beneficiaryId: string;
holderId: string;
outstanding: {
amount: number;
amountOwed: number;
counterpartyId: string;
owedBy: string | null;
owedTo: string | null;
partyId: string;
postingCount: number;
state: "outstanding" | "settled" | "empty";
};
owed: number;
settled: number;
}[];
owner: | {
chargebacks: number;
discounts: number;
gross: number;
net: number;
partyId: string;
postingCount: number;
refunds: number;
tax: number;
}
| null;
revenue: (
| {
chargebacks: number;
discounts: number;
gross: number;
net: number;
partyId: string;
postingCount: number;
refunds: number;
tax: number;
}
| null)[];
}[];
eventId: string;
eventName: string;
orders: {
chargebacks: number;
createdAt: string;
currency: string;
discounts: number;
gross: number;
net: number;
orderId: string;
orderNumber: string;
orderTotal: number;
refundJournalIds: string[];
refunds: number;
saleJournalId: string | null;
status: string;
}[];
ordersNextCursor: string | null;
ownerAccountId: string;
view: "party" | "full";
visibleParties: string[] | null;
}>;Read an event's statement: owed, settled and outstanding
What an event sold and who owes whom for it, a block per currency (never summed across them): the owner's gross face value, discounts, refunds, chargebacks and net, with tax; fees a code waived; booking fees on its orders by who earns them; what each holder of the buyers' money owed the party entitled to it, what settlements allocated to the event paid, and what is outstanding, with the direction in words (when more was settled than is now owed, the beneficiary owes the holder); the payment provider's and the platform's costs on its charges, by who bore them; and a page of its orders with their sale and refund journals (ordersCursor). Requires ledger.read on the event's owner for the whole of it. With ledger.read only on another party - the venue that held the money - you see that party's side (view: party): its balances, fees and costs, not the owner's revenue, and no orders. Accept: text/csv streams the event's orders with the event's figures on each (the whole view only). Amounts are integer MINOR UNITS. An organisation API key also needs its organisation to allow API keys to read the ledger (allowApiKeyLedgerRead), or 403 API_KEY_LEDGER_READ_NOT_ALLOWED.
Parameters#
| Parameter | Type |
|---|---|
eventId | string |
options? | { book?: "live" | "test"; currency?: string; ordersCursor?: string; ordersLimit?: number; } |
options.book? | "live" | "test" |
options.currency? | string |
options.ordersCursor? | string |
options.ordersLimit? | number |
requestOptions? | RequestOptions |
Returns#
Promise<{
book: "live" | "test";
currencies: {
costs: {
bearerId: string;
platformFees: number;
processingFees: number;
total: number;
}[];
currency: string;
fees: {
charged: number;
earnerId: string;
net: number;
refunded: number;
}[];
feeWaivers: number | null;
holders: {
beneficiaryId: string;
holderId: string;
outstanding: {
amount: number;
amountOwed: number;
counterpartyId: string;
owedBy: string | null;
owedTo: string | null;
partyId: string;
postingCount: number;
state: "outstanding" | "settled" | "empty";
};
owed: number;
settled: number;
}[];
owner: | {
chargebacks: number;
discounts: number;
gross: number;
net: number;
partyId: string;
postingCount: number;
refunds: number;
tax: number;
}
| null;
revenue: (
| {
chargebacks: number;
discounts: number;
gross: number;
net: number;
partyId: string;
postingCount: number;
refunds: number;
tax: number;
}
| null)[];
}[];
eventId: string;
eventName: string;
orders: {
chargebacks: number;
createdAt: string;
currency: string;
discounts: number;
gross: number;
net: number;
orderId: string;
orderNumber: string;
orderTotal: number;
refundJournalIds: string[];
refunds: number;
saleJournalId: string | null;
status: string;
}[];
ordersNextCursor: string | null;
ownerAccountId: string;
view: "party" | "full";
visibleParties: string[] | null;
}>
Operation Id#
getLedgerEventStatement
exceptions()#
exceptions: (options?: {
cursor?: string;
includeResolved?: "true" | "false";
kind?: | "refund"
| "other"
| "payment"
| "payout"
| "dispute"
| "balance_transaction"
| "application_fee";
limit?: number;
status?: "open" | "resolved" | "all";
}, requestOptions?: RequestOptions) => Promise<{
exceptions: {
attempts: number;
causeId: string;
causeType: string;
error: string;
errorCode: string | null;
firstSeenAt: string;
id: string;
inboundEventId: string | null;
kind: | "refund"
| "other"
| "payment"
| "payout"
| "dispute"
| "balance_transaction"
| "application_fee";
lastSeenAt: string;
resolvedAt: string | null;
retryable: boolean;
source: "api" | "workflow" | "webhook" | "replay" | "script";
}[];
nextCursor: string | null;
}>;List the money events the ledger is missing
A posting exception is a money event - a payment, a refund, a payout - whose journal could not be written and will not be by retrying: a failure a later attempt could fix is retried on the backoff ladder, and one that is permanent, or still failing on the last delivery, is recorded here instead of being lost. Most recently seen first, keyset paged: pass nextCursor back as cursor (limit 100 by default, at most 500). status is open unless resolved or all is asked for, and kind narrows to one kind of money event. An exception seen again while you page moves to the top of the list; a later page never repeats a row. Requires ledger.read across the whole organisation: an exception may name a payment whose Account could not even be read. An organisation API key also needs its organisation to allow API keys to read the ledger (allowApiKeyLedgerRead), or 403 API_KEY_LEDGER_READ_NOT_ALLOWED.
Parameters#
| Parameter | Type |
|---|---|
options? | { cursor?: string; includeResolved?: "true" | "false"; kind?: | "refund" | "other" | "payment" | "payout" | "dispute" | "balance_transaction" | "application_fee"; limit?: number; status?: "open" | "resolved" | "all"; } |
options.cursor? | string |
options.includeResolved? | "true" | "false" |
options.kind? | | "refund" | "other" | "payment" | "payout" | "dispute" | "balance_transaction" | "application_fee" |
options.limit? | number |
options.status? | "open" | "resolved" | "all" |
requestOptions? | RequestOptions |
Returns#
Promise<{
exceptions: {
attempts: number;
causeId: string;
causeType: string;
error: string;
errorCode: string | null;
firstSeenAt: string;
id: string;
inboundEventId: string | null;
kind: | "refund"
| "other"
| "payment"
| "payout"
| "dispute"
| "balance_transaction"
| "application_fee";
lastSeenAt: string;
resolvedAt: string | null;
retryable: boolean;
source: "api" | "workflow" | "webhook" | "replay" | "script";
}[];
nextCursor: string | null;
}>
Operation Id#
listLedgerExceptions
payout()#
payout: (payoutId: string, requestOptions?: RequestOptions) => Promise<{
fees: number;
gross: number;
groups: {
adjustments: {
amount: number;
fee: number;
lines: {
amount: number;
availableOn: string | null;
category: | "refund"
| "other"
| "payout"
| "dispute"
| "charge"
| "application_fee_refund"
| "platform_application_fee";
currency: string;
disputeId: string | null;
externalId: string;
fee: number;
id: string;
journalId: string | null;
matched: boolean;
net: number;
occurredAt: string;
orderId: string | null;
orderNumber: string | null;
paymentId: string | null;
refundId: string | null;
sourceId: string | null;
type: string;
}[];
net: number;
};
applicationFees: {
amount: number;
fee: number;
lines: {
amount: number;
availableOn: string | null;
category: | "refund"
| "other"
| "payout"
| "dispute"
| "charge"
| "application_fee_refund"
| "platform_application_fee";
currency: string;
disputeId: string | null;
externalId: string;
fee: number;
id: string;
journalId: string | null;
matched: boolean;
net: number;
occurredAt: string;
orderId: string | null;
orderNumber: string | null;
paymentId: string | null;
refundId: string | null;
sourceId: string | null;
type: string;
}[];
net: number;
};
charges: {
amount: number;
fee: number;
lines: {
amount: number;
availableOn: string | null;
category: | "refund"
| "other"
| "payout"
| "dispute"
| "charge"
| "application_fee_refund"
| "platform_application_fee";
currency: string;
disputeId: string | null;
externalId: string;
fee: number;
id: string;
journalId: string | null;
matched: boolean;
net: number;
occurredAt: string;
orderId: string | null;
orderNumber: string | null;
paymentId: string | null;
refundId: string | null;
sourceId: string | null;
type: string;
}[];
net: number;
};
disputes: {
amount: number;
fee: number;
lines: {
amount: number;
availableOn: string | null;
category: | "refund"
| "other"
| "payout"
| "dispute"
| "charge"
| "application_fee_refund"
| "platform_application_fee";
currency: string;
disputeId: string | null;
externalId: string;
fee: number;
id: string;
journalId: string | null;
matched: boolean;
net: number;
occurredAt: string;
orderId: string | null;
orderNumber: string | null;
paymentId: string | null;
refundId: string | null;
sourceId: string | null;
type: string;
}[];
net: number;
};
fees: {
amount: number;
fee: number;
lines: {
amount: number;
availableOn: string | null;
category: | "refund"
| "other"
| "payout"
| "dispute"
| "charge"
| "application_fee_refund"
| "platform_application_fee";
currency: string;
disputeId: string | null;
externalId: string;
fee: number;
id: string;
journalId: string | null;
matched: boolean;
net: number;
occurredAt: string;
orderId: string | null;
orderNumber: string | null;
paymentId: string | null;
refundId: string | null;
sourceId: string | null;
type: string;
}[];
net: number;
};
refunds: {
amount: number;
fee: number;
lines: {
amount: number;
availableOn: string | null;
category: | "refund"
| "other"
| "payout"
| "dispute"
| "charge"
| "application_fee_refund"
| "platform_application_fee";
currency: string;
disputeId: string | null;
externalId: string;
fee: number;
id: string;
journalId: string | null;
matched: boolean;
net: number;
occurredAt: string;
orderId: string | null;
orderNumber: string | null;
paymentId: string | null;
refundId: string | null;
sourceId: string | null;
type: string;
}[];
net: number;
};
};
net: number;
payout: {
amount: number;
arrivalDate: string;
balanceTransactionCount: number;
book: "live" | "test";
currency: string;
destinationLast4: string | null;
externalId: string;
failedAt: string | null;
failureCode: string | null;
holderId: string;
id: string;
journalId: string | null;
paidAt: string | null;
pspBalanceId: string;
reconciled: boolean;
reconciledAt: string | null;
reversalJournalId: string | null;
status: "failed" | "paid" | "pending" | "in_transit" | "canceled";
unmatchedCount: number;
};
reconciled: boolean;
unmatchedCount: number;
}>;Read a payout's statement
The payout, and the balance transactions the provider says it paid out, grouped: charges (with their orders), refunds, disputes, the provider's own fees, application fees and adjustments; with the gross, the fees and the net. reconciled is true when every one of them matched a payment, refund, dispute or payout Ticketlayer knows and their net is the payout's amount; each that matched nothing is counted in unmatchedCount, is in the balance's Suspense and has a posting exception. Accept: text/csv returns its balance transactions as CSV instead, one per row with its group, order and whether it matched, each repeating the payout. Requires ledger.read on the holder. Amounts are integer MINOR UNITS. An organisation API key also needs its organisation to allow API keys to read the ledger (allowApiKeyLedgerRead), or 403 API_KEY_LEDGER_READ_NOT_ALLOWED.
Parameters#
| Parameter | Type |
|---|---|
payoutId | string |
requestOptions? | RequestOptions |
Returns#
Promise<{
fees: number;
gross: number;
groups: {
adjustments: {
amount: number;
fee: number;
lines: {
amount: number;
availableOn: string | null;
category: | "refund"
| "other"
| "payout"
| "dispute"
| "charge"
| "application_fee_refund"
| "platform_application_fee";
currency: string;
disputeId: string | null;
externalId: string;
fee: number;
id: string;
journalId: string | null;
matched: boolean;
net: number;
occurredAt: string;
orderId: string | null;
orderNumber: string | null;
paymentId: string | null;
refundId: string | null;
sourceId: string | null;
type: string;
}[];
net: number;
};
applicationFees: {
amount: number;
fee: number;
lines: {
amount: number;
availableOn: string | null;
category: | "refund"
| "other"
| "payout"
| "dispute"
| "charge"
| "application_fee_refund"
| "platform_application_fee";
currency: string;
disputeId: string | null;
externalId: string;
fee: number;
id: string;
journalId: string | null;
matched: boolean;
net: number;
occurredAt: string;
orderId: string | null;
orderNumber: string | null;
paymentId: string | null;
refundId: string | null;
sourceId: string | null;
type: string;
}[];
net: number;
};
charges: {
amount: number;
fee: number;
lines: {
amount: number;
availableOn: string | null;
category: | "refund"
| "other"
| "payout"
| "dispute"
| "charge"
| "application_fee_refund"
| "platform_application_fee";
currency: string;
disputeId: string | null;
externalId: string;
fee: number;
id: string;
journalId: string | null;
matched: boolean;
net: number;
occurredAt: string;
orderId: string | null;
orderNumber: string | null;
paymentId: string | null;
refundId: string | null;
sourceId: string | null;
type: string;
}[];
net: number;
};
disputes: {
amount: number;
fee: number;
lines: {
amount: number;
availableOn: string | null;
category: | "refund"
| "other"
| "payout"
| "dispute"
| "charge"
| "application_fee_refund"
| "platform_application_fee";
currency: string;
disputeId: string | null;
externalId: string;
fee: number;
id: string;
journalId: string | null;
matched: boolean;
net: number;
occurredAt: string;
orderId: string | null;
orderNumber: string | null;
paymentId: string | null;
refundId: string | null;
sourceId: string | null;
type: string;
}[];
net: number;
};
fees: {
amount: number;
fee: number;
lines: {
amount: number;
availableOn: string | null;
category: | "refund"
| "other"
| "payout"
| "dispute"
| "charge"
| "application_fee_refund"
| "platform_application_fee";
currency: string;
disputeId: string | null;
externalId: string;
fee: number;
id: string;
journalId: string | null;
matched: boolean;
net: number;
occurredAt: string;
orderId: string | null;
orderNumber: string | null;
paymentId: string | null;
refundId: string | null;
sourceId: string | null;
type: string;
}[];
net: number;
};
refunds: {
amount: number;
fee: number;
lines: {
amount: number;
availableOn: string | null;
category: | "refund"
| "other"
| "payout"
| "dispute"
| "charge"
| "application_fee_refund"
| "platform_application_fee";
currency: string;
disputeId: string | null;
externalId: string;
fee: number;
id: string;
journalId: string | null;
matched: boolean;
net: number;
occurredAt: string;
orderId: string | null;
orderNumber: string | null;
paymentId: string | null;
refundId: string | null;
sourceId: string | null;
type: string;
}[];
net: number;
};
};
net: number;
payout: {
amount: number;
arrivalDate: string;
balanceTransactionCount: number;
book: "live" | "test";
currency: string;
destinationLast4: string | null;
externalId: string;
failedAt: string | null;
failureCode: string | null;
holderId: string;
id: string;
journalId: string | null;
paidAt: string | null;
pspBalanceId: string;
reconciled: boolean;
reconciledAt: string | null;
reversalJournalId: string | null;
status: "failed" | "paid" | "pending" | "in_transit" | "canceled";
unmatchedCount: number;
};
reconciled: boolean;
unmatchedCount: number;
}>
Operation Id#
getLedgerPayout
payouts()#
payouts: (options?: {
accountId?: string;
book?: "live" | "test";
cursor?: string;
from?: string;
limit?: number;
pspBalanceId?: string;
status?: "failed" | "paid" | "pending" | "in_transit" | "canceled";
to?: string;
}, requestOptions?: RequestOptions) => Promise<{
nextCursor: string | null;
payouts: {
amount: number;
arrivalDate: string;
balanceTransactionCount: number;
book: "live" | "test";
currency: string;
destinationLast4: string | null;
externalId: string;
failedAt: string | null;
failureCode: string | null;
holderId: string;
id: string;
journalId: string | null;
paidAt: string | null;
pspBalanceId: string;
reconciled: boolean;
reconciledAt: string | null;
reversalJournalId: string | null;
status: "failed" | "paid" | "pending" | "in_transit" | "canceled";
unmatchedCount: number;
}[];
}>;List the payouts the payment providers made
A payout is the payment provider paying a balance it holds out to the holder's bank: DR the holder's Cash, CR the balance's Clearing. Every provider mode is here: Ticketlayer Pay, your own Stripe account (direct and connected) and the sandbox's pretend payouts (book=test). Newest arrival first, keyset paged: pass nextCursor back as cursor. Filter by holder (accountId, an Account or your organisation's own id), PSP balance, status and arrival date. Requires ledger.read on the holder; with neither accountId nor pspBalanceId, across the whole organisation. Amounts are integer MINOR UNITS. An organisation API key also needs its organisation to allow API keys to read the ledger (allowApiKeyLedgerRead), or 403 API_KEY_LEDGER_READ_NOT_ALLOWED.
Parameters#
| Parameter | Type |
|---|---|
options? | { accountId?: string; book?: "live" | "test"; cursor?: string; from?: string; limit?: number; pspBalanceId?: string; status?: "failed" | "paid" | "pending" | "in_transit" | "canceled"; to?: string; } |
options.accountId? | string |
options.book? | "live" | "test" |
options.cursor? | string |
options.from? | string |
options.limit? | number |
options.pspBalanceId? | string |
options.status? | "failed" | "paid" | "pending" | "in_transit" | "canceled" |
options.to? | string |
requestOptions? | RequestOptions |
Returns#
Promise<{
nextCursor: string | null;
payouts: {
amount: number;
arrivalDate: string;
balanceTransactionCount: number;
book: "live" | "test";
currency: string;
destinationLast4: string | null;
externalId: string;
failedAt: string | null;
failureCode: string | null;
holderId: string;
id: string;
journalId: string | null;
paidAt: string | null;
pspBalanceId: string;
reconciled: boolean;
reconciledAt: string | null;
reversalJournalId: string | null;
status: "failed" | "paid" | "pending" | "in_transit" | "canceled";
unmatchedCount: number;
}[];
}>
Operation Id#
listLedgerPayouts
retryException()#
retryException: (exceptionId: string, requestOptions?: RequestOptions) => Promise<{
exception: {
attempts: number;
causeId: string;
causeType: string;
error: string;
errorCode: string | null;
firstSeenAt: string;
id: string;
inboundEventId: string | null;
kind: | "refund"
| "other"
| "payment"
| "payout"
| "dispute"
| "balance_transaction"
| "application_fee";
lastSeenAt: string;
resolvedAt: string | null;
retryable: boolean;
source: "api" | "workflow" | "webhook" | "replay" | "script";
};
outcome: "failed" | "resolved";
}>;Retry a posting exception's posting
Run the money event's posting again, through the path that first failed and nothing else: a stored webhook is delivered to the inbound consumer again, and a refund the API recorded is completed as the refund route completes it. Both are idempotent on the cause every journal is keyed on, so a retry never posts a money event twice: a journal that exists by now is found, not written. The answer is the exception after the attempt: outcome: resolved when the posting is in the book and the exception closed, failed when it failed again, with that attempt's error and attempts counting it. A resolved exception is 409 LEDGER_EXCEPTION_ALREADY_RESOLVED. One with no path to run again - a provider's balance transaction that matched nothing, whose journal went to the balance's Suspense, or a webhook no longer stored - is 422 LEDGER_EXCEPTION_NOT_RETRYABLE (retryable on the list says which are). Requires ledger.retry across the whole organisation, which ledger.read does not grant; a person only.
Parameters#
| Parameter | Type |
|---|---|
exceptionId | string |
requestOptions? | RequestOptions |
Returns#
Promise<{
exception: {
attempts: number;
causeId: string;
causeType: string;
error: string;
errorCode: string | null;
firstSeenAt: string;
id: string;
inboundEventId: string | null;
kind: | "refund"
| "other"
| "payment"
| "payout"
| "dispute"
| "balance_transaction"
| "application_fee";
lastSeenAt: string;
resolvedAt: string | null;
retryable: boolean;
source: "api" | "workflow" | "webhook" | "replay" | "script";
};
outcome: "failed" | "resolved";
}>
Operation Id#
retryLedgerException
reverseSettlement()#
reverseSettlement: (settlementId: string, request: {
reason: string;
}, requestOptions?: RequestOptions) => Promise<{
journal: {
description: string | null;
journalId: string;
lines: {
amount: number;
eventId: string | null;
path: string;
postingId: string;
}[];
occurredAt: string;
};
position: {
events: {
after: {
amount: number;
amountOwed: number;
counterpartyId: string;
owedBy: string | null;
owedTo: string | null;
partyId: string;
postingCount: number;
state: "outstanding" | "settled" | "empty";
};
before: {
amount: number;
amountOwed: number;
counterpartyId: string;
owedBy: string | null;
owedTo: string | null;
partyId: string;
postingCount: number;
state: "outstanding" | "settled" | "empty";
};
current: {
amount: number;
amountOwed: number;
counterpartyId: string;
owedBy: string | null;
owedTo: string | null;
partyId: string;
postingCount: number;
state: "outstanding" | "settled" | "empty";
};
} & {
allocated: number;
eventId: string;
eventName: string | null;
}[];
total: {
after: {
amount: number;
amountOwed: number;
counterpartyId: string;
owedBy: string | null;
owedTo: string | null;
partyId: string;
postingCount: number;
state: "outstanding" | "settled" | "empty";
};
before: {
amount: number;
amountOwed: number;
counterpartyId: string;
owedBy: string | null;
owedTo: string | null;
partyId: string;
postingCount: number;
state: "outstanding" | "settled" | "empty";
};
current: {
amount: number;
amountOwed: number;
counterpartyId: string;
owedBy: string | null;
owedTo: string | null;
partyId: string;
postingCount: number;
state: "outstanding" | "settled" | "empty";
};
};
};
reversal: {
description: string | null;
journalId: string;
lines: {
amount: number;
eventId: string | null;
path: string;
postingId: string;
}[];
occurredAt: string;
} & Record<string, never>;
settlement: {
allocations: {
amount: number;
eventId: string;
eventName: string | null;
source: "explicit" | "oldest_first";
}[];
amount: number;
book: "live" | "test";
createdAt: string;
currency: string;
id: string;
journalId: string;
method: "other" | "bank_transfer" | "cash" | "internal_offset";
note: string | null;
paidAt: string;
payeeAccountId: string;
payerAccountId: string;
recordedByUserId: string | null;
reference: string | null;
reversalReason: string | null;
reversedAt: string | null;
reversedByJournalId: string | null;
reversedByUserId: string | null;
status: "recorded" | "reversed";
unallocatedAmount: number;
};
}>;Reverse a settlement recorded in error
Correct a settlement: post the exact negation of its journal, line for line and event for event, as ONE journal (ledger.reversal), and mark the settlement reversed with the reason. Nothing is deleted - the payment and its reversal both stay on the statements - and every balance it moved goes back to what it was. A settlement is reversed at most once (409 LEDGER_SETTLEMENT_ALREADY_REVERSED). To record the payment correctly, record a new settlement. Requires ledger.settle on BOTH parties.
Parameters#
| Parameter | Type |
|---|---|
settlementId | string |
request | { reason: string; } |
request.reason | string |
requestOptions? | RequestOptions |
Returns#
Promise<{
journal: {
description: string | null;
journalId: string;
lines: {
amount: number;
eventId: string | null;
path: string;
postingId: string;
}[];
occurredAt: string;
};
position: {
events: {
after: {
amount: number;
amountOwed: number;
counterpartyId: string;
owedBy: string | null;
owedTo: string | null;
partyId: string;
postingCount: number;
state: "outstanding" | "settled" | "empty";
};
before: {
amount: number;
amountOwed: number;
counterpartyId: string;
owedBy: string | null;
owedTo: string | null;
partyId: string;
postingCount: number;
state: "outstanding" | "settled" | "empty";
};
current: {
amount: number;
amountOwed: number;
counterpartyId: string;
owedBy: string | null;
owedTo: string | null;
partyId: string;
postingCount: number;
state: "outstanding" | "settled" | "empty";
};
} & {
allocated: number;
eventId: string;
eventName: string | null;
}[];
total: {
after: {
amount: number;
amountOwed: number;
counterpartyId: string;
owedBy: string | null;
owedTo: string | null;
partyId: string;
postingCount: number;
state: "outstanding" | "settled" | "empty";
};
before: {
amount: number;
amountOwed: number;
counterpartyId: string;
owedBy: string | null;
owedTo: string | null;
partyId: string;
postingCount: number;
state: "outstanding" | "settled" | "empty";
};
current: {
amount: number;
amountOwed: number;
counterpartyId: string;
owedBy: string | null;
owedTo: string | null;
partyId: string;
postingCount: number;
state: "outstanding" | "settled" | "empty";
};
};
};
reversal: {
description: string | null;
journalId: string;
lines: {
amount: number;
eventId: string | null;
path: string;
postingId: string;
}[];
occurredAt: string;
} & Record<string, never>;
settlement: {
allocations: {
amount: number;
eventId: string;
eventName: string | null;
source: "explicit" | "oldest_first";
}[];
amount: number;
book: "live" | "test";
createdAt: string;
currency: string;
id: string;
journalId: string;
method: "other" | "bank_transfer" | "cash" | "internal_offset";
note: string | null;
paidAt: string;
payeeAccountId: string;
payerAccountId: string;
recordedByUserId: string | null;
reference: string | null;
reversalReason: string | null;
reversedAt: string | null;
reversedByJournalId: string | null;
reversedByUserId: string | null;
status: "recorded" | "reversed";
unallocatedAmount: number;
};
}>
Operation Id#
reverseLedgerSettlement
settlement()#
settlement: (settlementId: string, requestOptions?: RequestOptions) => Promise<{
journal: {
description: string | null;
journalId: string;
lines: {
amount: number;
eventId: string | null;
path: string;
postingId: string;
}[];
occurredAt: string;
};
position: {
events: {
after: {
amount: number;
amountOwed: number;
counterpartyId: string;
owedBy: string | null;
owedTo: string | null;
partyId: string;
postingCount: number;
state: "outstanding" | "settled" | "empty";
};
before: {
amount: number;
amountOwed: number;
counterpartyId: string;
owedBy: string | null;
owedTo: string | null;
partyId: string;
postingCount: number;
state: "outstanding" | "settled" | "empty";
};
current: {
amount: number;
amountOwed: number;
counterpartyId: string;
owedBy: string | null;
owedTo: string | null;
partyId: string;
postingCount: number;
state: "outstanding" | "settled" | "empty";
};
} & {
allocated: number;
eventId: string;
eventName: string | null;
}[];
total: {
after: {
amount: number;
amountOwed: number;
counterpartyId: string;
owedBy: string | null;
owedTo: string | null;
partyId: string;
postingCount: number;
state: "outstanding" | "settled" | "empty";
};
before: {
amount: number;
amountOwed: number;
counterpartyId: string;
owedBy: string | null;
owedTo: string | null;
partyId: string;
postingCount: number;
state: "outstanding" | "settled" | "empty";
};
current: {
amount: number;
amountOwed: number;
counterpartyId: string;
owedBy: string | null;
owedTo: string | null;
partyId: string;
postingCount: number;
state: "outstanding" | "settled" | "empty";
};
};
};
reversal: {
description: string | null;
journalId: string;
lines: {
amount: number;
eventId: string | null;
path: string;
postingId: string;
}[];
occurredAt: string;
} & Record<string, never>;
settlement: {
allocations: {
amount: number;
eventId: string;
eventName: string | null;
source: "explicit" | "oldest_first";
}[];
amount: number;
book: "live" | "test";
createdAt: string;
currency: string;
id: string;
journalId: string;
method: "other" | "bank_transfer" | "cash" | "internal_offset";
note: string | null;
paidAt: string;
payeeAccountId: string;
payerAccountId: string;
recordedByUserId: string | null;
reference: string | null;
reversalReason: string | null;
reversedAt: string | null;
reversedByJournalId: string | null;
reversedByUserId: string | null;
status: "recorded" | "reversed";
unallocatedAmount: number;
};
}>;Read a settlement's statement
The settlement statement: the payment (parties, amount, method, reference, when it was paid, who recorded it), its allocations to events, the postings it made (and its reversal's, once reversed), and what the payer owed the payee BEFORE and AFTER it, in total and per allocated event. before is as at paidAt and leaves out the settlement's own journal and its reversal; after adds its own lines; current is the book now. Each figure says in words who owes whom (owedBy, owedTo), and none is clamped: an over-payment is the direction reversing. Accept: text/csv returns it as CSV instead: a row for the whole payment, one per allocated event and one for what was not allocated, each repeating the settlement, with before, after and now. Requires ledger.read on either party. Amounts are integer MINOR UNITS. An organisation API key also needs its organisation to allow API keys to read the ledger (allowApiKeyLedgerRead), or 403 API_KEY_LEDGER_READ_NOT_ALLOWED.
Parameters#
| Parameter | Type |
|---|---|
settlementId | string |
requestOptions? | RequestOptions |
Returns#
Promise<{
journal: {
description: string | null;
journalId: string;
lines: {
amount: number;
eventId: string | null;
path: string;
postingId: string;
}[];
occurredAt: string;
};
position: {
events: {
after: {
amount: number;
amountOwed: number;
counterpartyId: string;
owedBy: string | null;
owedTo: string | null;
partyId: string;
postingCount: number;
state: "outstanding" | "settled" | "empty";
};
before: {
amount: number;
amountOwed: number;
counterpartyId: string;
owedBy: string | null;
owedTo: string | null;
partyId: string;
postingCount: number;
state: "outstanding" | "settled" | "empty";
};
current: {
amount: number;
amountOwed: number;
counterpartyId: string;
owedBy: string | null;
owedTo: string | null;
partyId: string;
postingCount: number;
state: "outstanding" | "settled" | "empty";
};
} & {
allocated: number;
eventId: string;
eventName: string | null;
}[];
total: {
after: {
amount: number;
amountOwed: number;
counterpartyId: string;
owedBy: string | null;
owedTo: string | null;
partyId: string;
postingCount: number;
state: "outstanding" | "settled" | "empty";
};
before: {
amount: number;
amountOwed: number;
counterpartyId: string;
owedBy: string | null;
owedTo: string | null;
partyId: string;
postingCount: number;
state: "outstanding" | "settled" | "empty";
};
current: {
amount: number;
amountOwed: number;
counterpartyId: string;
owedBy: string | null;
owedTo: string | null;
partyId: string;
postingCount: number;
state: "outstanding" | "settled" | "empty";
};
};
};
reversal: {
description: string | null;
journalId: string;
lines: {
amount: number;
eventId: string | null;
path: string;
postingId: string;
}[];
occurredAt: string;
} & Record<string, never>;
settlement: {
allocations: {
amount: number;
eventId: string;
eventName: string | null;
source: "explicit" | "oldest_first";
}[];
amount: number;
book: "live" | "test";
createdAt: string;
currency: string;
id: string;
journalId: string;
method: "other" | "bank_transfer" | "cash" | "internal_offset";
note: string | null;
paidAt: string;
payeeAccountId: string;
payerAccountId: string;
recordedByUserId: string | null;
reference: string | null;
reversalReason: string | null;
reversedAt: string | null;
reversedByJournalId: string | null;
reversedByUserId: string | null;
status: "recorded" | "reversed";
unallocatedAmount: number;
};
}>
Operation Id#
getLedgerSettlement
settlements()#
settlements: (options?: {
book?: "live" | "test";
counterpartyAccountId?: string;
currency?: string;
cursor?: string;
eventId?: string;
from?: string;
limit?: number;
party?: string;
status?: "recorded" | "reversed";
to?: string;
}, requestOptions?: RequestOptions) => Promise<{
nextCursor: string | null;
settlements: {
allocations: {
amount: number;
eventId: string;
eventName: string | null;
source: "explicit" | "oldest_first";
}[];
amount: number;
book: "live" | "test";
createdAt: string;
currency: string;
id: string;
journalId: string;
method: "other" | "bank_transfer" | "cash" | "internal_offset";
note: string | null;
paidAt: string;
payeeAccountId: string;
payerAccountId: string;
recordedByUserId: string | null;
reference: string | null;
reversalReason: string | null;
reversedAt: string | null;
reversedByJournalId: string | null;
reversedByUserId: string | null;
status: "recorded" | "reversed";
unallocatedAmount: number;
}[];
}>;List the settlements recorded between parties
Settlements are records of payments one party made another outside Ticketlayer (POST /ledger/settlements), each with its allocations to events. Reversed ones are listed and marked reversed unless status narrows them. Newest payment first, keyset paged: pass nextCursor back as cursor. Filter by party (either side), counterparty, currency, event (an allocation to it) and payment date. Requires ledger.read on either party: with party, on that party; without it, you see the settlements with at least one party you may read. Payouts - the payment providers paying a holder - are a separate list, GET /ledger/payouts. Amounts are integer MINOR UNITS. An organisation API key also needs its organisation to allow API keys to read the ledger (allowApiKeyLedgerRead), or 403 API_KEY_LEDGER_READ_NOT_ALLOWED.
Parameters#
| Parameter | Type |
|---|---|
options? | { book?: "live" | "test"; counterpartyAccountId?: string; currency?: string; cursor?: string; eventId?: string; from?: string; limit?: number; party?: string; status?: "recorded" | "reversed"; to?: string; } |
options.book? | "live" | "test" |
options.counterpartyAccountId? | string |
options.currency? | string |
options.cursor? | string |
options.eventId? | string |
options.from? | string |
options.limit? | number |
options.party? | string |
options.status? | "recorded" | "reversed" |
options.to? | string |
requestOptions? | RequestOptions |
Returns#
Promise<{
nextCursor: string | null;
settlements: {
allocations: {
amount: number;
eventId: string;
eventName: string | null;
source: "explicit" | "oldest_first";
}[];
amount: number;
book: "live" | "test";
createdAt: string;
currency: string;
id: string;
journalId: string;
method: "other" | "bank_transfer" | "cash" | "internal_offset";
note: string | null;
paidAt: string;
payeeAccountId: string;
payerAccountId: string;
recordedByUserId: string | null;
reference: string | null;
reversalReason: string | null;
reversedAt: string | null;
reversedByJournalId: string | null;
reversedByUserId: string | null;
status: "recorded" | "reversed";
unallocatedAmount: number;
}[];
}>
Operation Id#
listLedgerSettlements
statement()#
statement: (options?: {
accountId?: string;
book?: "live" | "test";
counterpartyAccountId?: string;
currency: string;
cursor?: string;
eventId?: string;
from?: string;
limit?: number;
party?: string;
to?: string;
}, requestOptions?: RequestOptions) => Promise<{
accountId: string;
basis: "position" | "counterparty";
book: "live" | "test";
closingBalance: number;
counterpartyAccountId: string | null;
currency: string;
eventId: string | null;
from: string | null;
lines: {
amount: number;
category: | "other"
| "sales"
| "discounts"
| "refunds"
| "chargebacks"
| "fees_earned"
| "fees_and_costs"
| "payouts"
| "settlements_paid"
| "settlements_received";
causeId: string;
causeType: string;
currency: string;
description: string | null;
effect: number;
eventId: string | null;
journalId: string;
occurredAt: string;
orderId: string | null;
path: string;
postedAt: string;
postingId: string;
pspPayoutId: string | null;
reversesJournalId: string | null;
runningBalance: number;
settlementId: string | null;
}[];
nextCursor: string | null;
openingBalance: number;
pageOpeningBalance: number;
party: string;
path: string;
summary: {
categories: {
category: | "other"
| "sales"
| "discounts"
| "refunds"
| "chargebacks"
| "fees_earned"
| "fees_and_costs"
| "payouts"
| "settlements_paid"
| "settlements_received";
closing: number;
lineCount: number;
movement: number;
opening: number;
}[];
closing: number;
currency: string;
movement: number;
opening: number;
};
to: string | null;
}>;Read a party's statement over a date range
A party's statement in one currency (never summed across currencies), oldest line first, keyset paged: pass nextCursor back as cursor (limit 100 by default, at most 500). Every page carries its opening running balance (pageOpeningBalance), so its running balances are right without reading the pages before it, and the whole range's summary: the opening, the movement and the closing per category (sales, discounts, refunds, chargebacks, fees earned, fees and costs, payouts, settlements paid, settlements received, other). Without counterpartyAccountId the balance is THE BALANCE THE PARTY IS OWED, net of what it owes: what a payment provider or a till holds for it, plus what other parties owe it, less what it owes them. Money already in its own bank is not in it, because it is no longer owed to anyone. Positive means the party is owed that much on balance, negative that it owes that much on balance. The lines are what moved it - its revenue, its costs and its bank's movements - each with its effect; a sale raises it, a payout to its bank or a settlement received lowers it. With counterpartyAccountId the balance is what the counterparty owes the party, and the lines are the two buckets between them as posted. eventId narrows either to the lines tagged with an event. Positive is in the party's favour and nothing is clamped: a negative balance means the party owes. Accept: text/csv streams every line of the range as CSV instead of one page. Reads one book: live unless book=test is asked for. Requires ledger.read on the party. Amounts are integer MINOR UNITS. An organisation API key also needs its organisation to allow API keys to read the ledger (allowApiKeyLedgerRead), or 403 API_KEY_LEDGER_READ_NOT_ALLOWED.
Parameters#
| Parameter | Type |
|---|---|
options? | { accountId?: string; book?: "live" | "test"; counterpartyAccountId?: string; currency: string; cursor?: string; eventId?: string; from?: string; limit?: number; party?: string; to?: string; } |
options.accountId? | string |
options.book? | "live" | "test" |
options.counterpartyAccountId? | string |
options.currency? | string |
options.cursor? | string |
options.eventId? | string |
options.from? | string |
options.limit? | number |
options.party? | string |
options.to? | string |
requestOptions? | RequestOptions |
Returns#
Promise<{
accountId: string;
basis: "position" | "counterparty";
book: "live" | "test";
closingBalance: number;
counterpartyAccountId: string | null;
currency: string;
eventId: string | null;
from: string | null;
lines: {
amount: number;
category: | "other"
| "sales"
| "discounts"
| "refunds"
| "chargebacks"
| "fees_earned"
| "fees_and_costs"
| "payouts"
| "settlements_paid"
| "settlements_received";
causeId: string;
causeType: string;
currency: string;
description: string | null;
effect: number;
eventId: string | null;
journalId: string;
occurredAt: string;
orderId: string | null;
path: string;
postedAt: string;
postingId: string;
pspPayoutId: string | null;
reversesJournalId: string | null;
runningBalance: number;
settlementId: string | null;
}[];
nextCursor: string | null;
openingBalance: number;
pageOpeningBalance: number;
party: string;
path: string;
summary: {
categories: {
category: | "other"
| "sales"
| "discounts"
| "refunds"
| "chargebacks"
| "fees_earned"
| "fees_and_costs"
| "payouts"
| "settlements_paid"
| "settlements_received";
closing: number;
lineCount: number;
movement: number;
opening: number;
}[];
closing: number;
currency: string;
movement: number;
opening: number;
};
to: string | null;
}>
Operation Id#
getLedgerStatement