commerce

type Client = types.CommerceClient

type CollectOut struct {
	// Invoice is the invoice AFTER the attempt — its status is the authority on
	// what happened, not this struct's other fields.
	Invoice *InvoiceOut `json:"invoice"`
	// Paid reports whether the invoice is now settled in full. A false here with
	// no error is a DECLINE: the invoice stays open and may be collected again.
	Paid bool `json:"paid"`
	// CreditUsedCents is how much was covered by credit grants.
	CreditUsedCents int64 `json:"creditUsedCents"`
	// BalanceUsedCents is how much was covered by prepaid balance.
	BalanceUsedCents int64 `json:"balanceUsedCents"`
	// CardChargedCents is how much was charged to the card on file.
	CardChargedCents int64 `json:"cardChargedCents"`
	// ProcessorRef is the processor's reference for any card charge — the field
	// that proves money moved at the gateway rather than only in our ledger.
	ProcessorRef string `json:"processorRef,omitempty"`
	// Reason explains a decline or partial collection. Empty on success.
	Reason string `json:"reason,omitempty"`
}

type InvoiceLineIn struct {
	// Description is the human-readable line, e.g. "Advisory retainer — August".
	Description string `json:"description"`
	// Amount is the line total in whole cents (250000 is $2,500.00).
	Amount int64 `json:"amount"`
	// Quantity is the number of units, when the line is metered. Optional.
	Quantity int64 `json:"quantity,omitempty"`
	// UnitPrice is the per-unit price in cents, when the line is metered. Optional.
	UnitPrice int64 `json:"unitPrice,omitempty"`
}

type InvoiceOut struct {
	// ID is the invoice id — what the issue, collect and void ops address.
	ID string `json:"id"`
	// Number is the human-facing invoice number, e.g. "INV-0042". A draft has
	// none; issuing assigns it.
	Number string `json:"number,omitempty"`
	// UserID is the customer billed.
	UserID string `json:"userId"`
	// CustomerEmail is where it is sent.
	CustomerEmail string `json:"customerEmail,omitempty"`
	// Status is draft, open, paid, void or uncollectible. A draft is not
	// collectible; issuing moves it to open.
	Status string `json:"status"`
	// Currency is the ISO 4217 code.
	Currency string `json:"currency"`
	// SubtotalCents is the sum of the lines.
	SubtotalCents int64 `json:"subtotalCents"`
	// AmountDueCents is what remains collectible.
	AmountDueCents int64 `json:"amountDueCents"`
	// AmountPaidCents is what has been collected so far.
	AmountPaidCents int64 `json:"amountPaidCents"`
	// Lines are the charges on the invoice.
	Lines []InvoiceLineIn `json:"lines,omitempty"`
	// PaymentRef is the processor reference for the collection, once paid.
	PaymentRef string `json:"paymentRef,omitempty"`
	// CreatedAt is when the draft was raised, RFC3339.
	CreatedAt string `json:"createdAt,omitempty"`
}

type InvoiceRefIn struct {
	// ID is the invoice id.
	ID string `json:"id"`
}

type PaymentIn struct {
	// SourceID is the single-use payment token that stands in for the card: a
	// Square Web Payments SDK nonce minted in the browser, or a Square sandbox
	// test nonce when the org's credentials are sandbox ones. The card number
	// itself never reaches this process, which is what keeps it out of PCI scope.
	SourceID string `json:"sourceId"`
	// AmountCents is the amount to charge, in whole cents (5000 is $50.00).
	// Server-side bounds apply and are authoritative — the default floor is $1
	// and the ceiling $5,000, so a fat-fingered or hostile amount is refused
	// before any money moves.
	AmountCents int64 `json:"amountCents"`
	// Currency is the ISO 4217 code, lower-cased. Empty means usd.
	Currency string `json:"currency,omitempty"`
	// IdempotencyKey makes a retry safe: the same key never charges twice, it
	// replays the first result. Sending one is strongly recommended for an agent,
	// which retries by construction. Empty falls back to a windowed key derived
	// from the amount and currency, so a double-submit inside 15 minutes still
	// collapses onto one charge.
	IdempotencyKey string `json:"idempotencyKey,omitempty"`
}

type PaymentOut struct {
	// ID is the ledger transaction id for the credit. It is what getPayment
	// reads back, and the customer-visible receipt for the money.
	ID string `json:"id"`
	// BalanceCents is the org's balance AFTER this payment, read back from the
	// same key just credited so it matches what the balance endpoint reports.
	BalanceCents int64 `json:"balanceCents"`
	// Status is "ok" on a settled charge. A charge that did not settle is an
	// error with the processor's reason, never a status field to inspect.
	Status string `json:"status"`
	// ProcessorRef is the payment processor's own reference for the charge
	// (Square's payment id). It is the field that proves money actually moved at
	// the gateway rather than only in our ledger — the thing to quote when
	// reconciling against a processor dashboard.
	ProcessorRef string `json:"processorRef,omitempty"`
	// Test reports which bucket this credited: true is a SANDBOX charge crediting
	// the test balance, false is live money. It is always stated so a receipt can
	// never be mistaken for the other kind.
	Test bool `json:"test"`
}

type PaymentRecord struct {
	// ID is the ledger transaction id.
	ID string `json:"id"`
	// Subject is the billing key this payment credited.
	Subject string `json:"subject"`
	// AmountCents is the credited amount in whole cents.
	AmountCents int64 `json:"amountCents"`
	// Currency is the ISO 4217 code.
	Currency string `json:"currency"`
	// Status is the payment's state. This ledger writes a deposit only AFTER the
	// processor settled, so a payment that can be read is one that succeeded.
	Status string `json:"status"`
	// Test reports whether this was a sandbox charge (test balance) or live money.
	Test bool `json:"test"`
	// Notes is the ledger memo, carrying the processor and its reference.
	Notes string `json:"notes,omitempty"`
	// CreatedAt is when the credit was written, RFC3339.
	CreatedAt string `json:"createdAt,omitempty"`
}

type PaymentRef struct {
	// ID is the ledger transaction id a payment returned.
	ID string `json:"id"`
}

type RaiseInvoiceIn struct {
	// UserID identifies the customer being billed, within the caller's own org.
	// Required — an invoice with no addressee is not an invoice.
	UserID string `json:"userId"`
	// CustomerEmail is where the invoice is sent. Optional.
	CustomerEmail string `json:"customerEmail,omitempty"`
	// Currency is the ISO 4217 code, lower-cased. Empty means usd.
	Currency string `json:"currency,omitempty"`
	// Lines are the charges. The invoice subtotal and amount due are COMPUTED
	// from these — there is no total field to send, because a total that
	// disagreed with its own lines would bill a number nobody could derive.
	Lines []InvoiceLineIn `json:"lines,omitempty"`
}