settlementep

type CreateSettlementAllocationRequest struct {
	// ID of the transaction (payment, rebate, adjustment, or credit memo) to allocate from.
	TransactionID string `json:"transaction_id" validate:"required"`
	// ID of the invoice the amount is applied to.
	InvoiceID string `json:"invoice_id" validate:"required"`
	// The part of the transaction's amount to apply to this invoice, as a decimal string in US dollars.
	//
	// This is not checked against the transaction's unallocated balance or the invoice's outstanding total; applying more than an invoice owes leaves that invoice `overpaid`.
	Amount string `json:"amount" validate:"required"`
	// Free-form note about this allocation.
	Note field.Optional[string] `json:"note,omitzero"`
}

type CreateSettlementEndpoint struct{}

type CreateSettlementRequest struct {
	// ID of the user responsible for this settlement.
	//
	// Accepts either an account user ID or a user ID; the value is resolved to an account user in the current account.
	ResponsibleUserID string `json:"responsible_user_id" validate:"required"`
	// Allocations to record in this settlement.
	Allocations []CreateSettlementAllocationRequest `json:"allocations" validate:"required,min=1"`
}

type DeleteSettlementEndpoint struct{}

type DeleteSettlementRequest struct {
	// Settlement ID.
	SettlementID string `path:"id" validate:"required"`
}

type ListSettlementsEndpoint struct{}

type ListSettlementsRequest struct {
	apiresource.PaginationRequest
	// Only return settlements that allocate at least one of these transactions.
	TransactionIDs []string `query:"transaction_ids"`
	// Only return settlements that allocate to at least one of these invoices.
	InvoiceIDs []string `query:"invoice_ids"`
	// Only return settlements created on or after the start of this date (`YYYY-MM-DD`, UTC).
	StartDate *string `query:"starts_at"`
	// Only return settlements created on or before this date (`YYYY-MM-DD`, UTC), covering that whole day.
	EndDate *string `query:"ends_at"`
}

type RetrieveSettlementEndpoint struct{}

type RetrieveSettlementRequest struct {
	// Settlement ID.
	SettlementID string `path:"id" validate:"required"`
	// Sub-resources to include in the response.
	Includes []string `include:"true"`
}

type SettlementSvc interface {
	ListSettlements(ctx context.Context, req *ListSettlementsRequest) (*apiresource.List[apiresource.SettlementSummary], *apierror.APIError)
	GetSettlement(ctx context.Context, req *RetrieveSettlementRequest) (*apiresource.Settlement, *apierror.APIError)
	CreateSettlement(ctx context.Context, req *CreateSettlementRequest) (*apiresource.Settlement, *apierror.APIError)
	UpdateSettlement(ctx context.Context, req *UpdateSettlementRequest) (*apiresource.Settlement, *apierror.APIError)
	DeleteSettlement(ctx context.Context, req *DeleteSettlementRequest) (*apiresource.Settlement, *apierror.APIError)
}

type SettlementSvcConfig struct {
	// CoreClient (required) is the core-service gRPC client.
	CoreClient pb.CoreServiceClient
}

type UpdateSettlementEndpoint struct{}

type UpdateSettlementRequest struct {
	// Settlement ID.
	SettlementID string `path:"id" validate:"required"`
	// New settlement number.
	//
	// Must be unique within the account.
	Number field.Optional[string] `json:"number,omitzero" validate:"omitempty,max=255"`
	// Note for this settlement.
	Note field.Optional[string] `json:"note,omitzero"`
	// ID of the user responsible for this settlement.
	//
	// Accepts either an account user ID or a user ID; the value is resolved to an account user in the current account.
	ResponsibleUserID field.Optional[string] `json:"responsible_user_id,omitzero" validate:"omitempty"`
}