commerce

type Cart struct {
	// ID is the cart's id — what every other cart op addresses it by, and what a
	// storefront persists against the browser session.
	ID string `json:"id"`
	// Status is "active" for a cart still being filled, "ordered" once checkout
	// turned it into an order, and "discarded" when the shopper abandoned it.
	Status string `json:"status"`
	// Currency is the ISO 4217 code every amount below is denominated in.
	Currency string `json:"currency"`
	// Email is the shopper's address, when the cart carries one.
	Email string `json:"email,omitempty"`
	// User is the signed-in shopper this cart belongs to, empty for a guest cart.
	User string `json:"user,omitempty"`
	// Store is the storefront the cart is being filled on.
	Store string `json:"store,omitempty"`
	// Order is the order this cart became, once checkout completed it. Empty
	// until then, and its presence is what makes a cart final.
	Order string `json:"order,omitempty"`
	// Items are the cart's lines, in the order they were added.
	Items []CartItem `json:"items"`
	// LineTotalCents is the sum of the lines before any discount, in whole cents.
	LineTotalCents int64 `json:"lineTotalCents"`
	// DiscountCents is what coupons and promotions took off, in whole cents.
	DiscountCents int64 `json:"discountCents"`
	// SubtotalCents is LineTotalCents less DiscountCents, in whole cents.
	SubtotalCents int64 `json:"subtotalCents"`
	// ShippingCents is the shipping charge, in whole cents. It stays zero until a
	// shipping option is priced at checkout.
	ShippingCents int64 `json:"shippingCents"`
	// TaxCents is the sales tax, in whole cents. It stays zero until checkout
	// resolves the shopper's tax region.
	TaxCents int64 `json:"taxCents"`
	// TotalCents is what the shopper pays: subtotal plus shipping plus tax, in
	// whole cents.
	TotalCents int64 `json:"totalCents"`
	// CreatedAt is when the cart was opened, RFC3339.
	CreatedAt string `json:"createdAt,omitempty"`
	// UpdatedAt is when the cart was last amended, RFC3339.
	UpdatedAt string `json:"updatedAt,omitempty"`
}

type CartItem struct {
	// ID is the line's identity — the variant id when the line is a variant,
	// otherwise the product id. It is what a subsequent set call addresses.
	ID string `json:"id"`
	// Kind is "variant" when this line is a specific sellable variant and
	// "product" when it is the product itself.
	Kind string `json:"kind"`
	// Name is the item's display name, cached onto the line when it was added so
	// a cart renders without a second read.
	Name string `json:"name,omitempty"`
	// SKU is the line's stock-keeping unit — the variant's when it has one,
	// otherwise the product's. Empty when neither carries one.
	SKU string `json:"sku,omitempty"`
	// Quantity is how many units of this item the cart holds.
	Quantity int `json:"quantity"`
	// PriceCents is the unit price in whole cents, cached at the moment the line
	// was added. The line's contribution to the cart is this times Quantity.
	PriceCents int64 `json:"priceCents"`
	// Free reports a line that costs nothing because a coupon or a promotion made
	// it so, rather than because its price is zero.
	Free bool `json:"free,omitempty"`
}

type CartItemSet struct {
	// ID is the cart to amend, from the path.
	ID string `json:"id"`
	// Product names the catalog product to set, by its id or its URL slug. Give
	// this or Variant, never both; a request naming neither is refused.
	Product string `json:"product,omitempty" url:"-"`
	// Variant names the specific sellable variant to set, by its id or its SKU.
	// Prefer it over Product for anything sold in sizes, colours or tiers — the
	// price and the stock are the variant's, not the product's.
	Variant string `json:"variant,omitempty" url:"-"`
	// Quantity is how many of that item the cart should hold AFTER this call — it
	// is the resulting count, not a delta, so sending 3 twice leaves 3 and not 6.
	// ZERO REMOVES the line, which is the only way to take an item out.
	Quantity int `json:"quantity" url:"-"`
}

type CartOpen struct {
	// Email is the shopper's address, for a cart that belongs to someone who has
	// not signed in. It is what a guest checkout and an abandoned-cart follow-up
	// key on. Empty is fine.
	Email string `json:"email,omitempty" url:"-"`
	// User is the id of the signed-in shopper this cart belongs to, when there is
	// one. Empty means a guest cart identified only by its own id.
	User string `json:"user,omitempty" url:"-"`
	// Store is the storefront this cart is being filled on. Empty uses the org's
	// default store, which is what a single-storefront merchant always wants.
	Store string `json:"store,omitempty" url:"-"`
	// Currency is the ISO 4217 code the cart is priced in, lower-cased. Empty
	// means usd.
	Currency string `json:"currency,omitempty" url:"-"`
}

type CartRef struct {
	// ID is the cart's id, as the open call answered it.
	ID string `json:"id"`
}

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"`
}