purchaseorderep

type BulkDeletePurchaseOrdersEndpoint struct{}

type BulkDeletePurchaseOrdersRequest struct {
	// IDs of the purchase orders to delete.
	PurchaseOrderIDs []string `json:"purchase_order_ids" validate:"required"`
}

type ChangePurchaseOrderStatusEndpoint struct{}

type ChangePurchaseOrderStatusRequest struct {
	// Purchase order ID.
	PurchaseOrderID string `path:"id" validate:"required"`
	// The lifecycle transition to apply.
	//
	// - `issue`: move an `estimate` order to `issued`. Creates the order's receiving order with a line for each order line.
	// - `unissue`: move an `issued` order back to `estimate`. Deletes the receiving order.
	// - `close`: move an `issued` order to `fulfilled`. Marks the receiving order complete.
	// - `open`: move a `fulfilled` order back to `issued`. Re-opens the receiving order.
	StatusChange constants.SalesOrderStatusChange `json:"status_change" validate:"required"`
	// Whether to email the purchase order to the order's contacts.
	//
	// Only applies to the `issue` action. When `true`, the purchase order submission email is sent to the order's email contacts and `acknowledgment_status` is set to `sent`. An order with no email contacts still moves to `sent` even though no email goes out.
	SendEmail bool `json:"send_email"`
}

type CreatePurchaseOrderEndpoint struct{}

type CreatePurchaseOrderLineEndpoint struct{}

type CreatePurchaseOrderLineInput struct {
	apirequest.OrderLineInput
}

type CreatePurchaseOrderLineRequest struct {
	// Purchase order ID.
	PurchaseOrderID string `path:"id" validate:"required"`
	apirequest.OrderLineInput
}

type CreatePurchaseOrderRequest struct {
	// ID of the supplier account to place the order with.
	SupplierAccountID string `json:"supplier_account_id" validate:"required"`
	// Free-form note to record on the order.
	Note field.Optional[string] `json:"note,omitzero"`
	// ID of the carrier for the order's freight.
	CarrierID field.Optional[string] `json:"carrier_id,omitzero" validate:"omitempty"`
	// ID of the carrier service level for the order's freight.
	ServiceLevelID field.Optional[string] `json:"service_level_id,omitzero" validate:"omitempty"`
	// Which party the carrier bills for freight on this order.
	//
	// - `sender`: the carrier bills the party shipping the goods.
	// - `third_party`: the carrier bills the account given in `carrier_billing_account`.
	CarrierBillingType field.Optional[constants.CarrierBillingType] `json:"carrier_billing_type,omitzero" validate:"omitempty"`
	// Carrier account number to bill when the billing type is `third_party`.
	CarrierBillingAccount field.Optional[string] `json:"carrier_billing_account,omitzero" validate:"omitempty,max=255"`
	// Priority level for fulfilling the order.
	PriorityCode constants.PriorityCode `json:"priority_code" validate:"required"`
	// ID of the shipping term that applies to the order.
	ShippingTermID field.Optional[string] `json:"shipping_term_id,omitzero" validate:"omitempty"`
	// ID of the payment term agreed with the supplier.
	PaymentTermID field.Optional[string] `json:"payment_term_id,omitzero" validate:"omitempty"`
	// Bill-to address name.
	BillToName field.Optional[string] `json:"bill_to_name,omitzero" validate:"omitempty,max=255"`
	// Bill-to street line 1.
	BillToStreetLine1 field.Optional[string] `json:"bill_to_street_line_1,omitzero" validate:"omitempty,max=255"`
	// Bill-to street line 2.
	BillToStreetLine2 field.Optional[string] `json:"bill_to_street_line_2,omitzero" validate:"omitempty,max=255"`
	// Bill-to locality/city.
	BillToLocality field.Optional[string] `json:"bill_to_locality,omitzero" validate:"omitempty,max=255"`
	// Bill-to state/province.
	BillToState field.Optional[string] `json:"bill_to_state,omitzero" validate:"omitempty,max=255"`
	// Bill-to postal code.
	BillToPostalCode field.Optional[string] `json:"bill_to_postal_code,omitzero" validate:"omitempty,max=255"`
	// Bill-to country as a two-letter code.
	BillToCountry field.Optional[string] `json:"bill_to_country,omitzero" validate:"omitempty,max=2"`
	// Ship-to address name.
	ShipToName field.Optional[string] `json:"ship_to_name,omitzero" validate:"omitempty,max=255"`
	// Ship-to street line 1.
	ShipToStreetLine1 field.Optional[string] `json:"ship_to_street_line_1,omitzero" validate:"omitempty,max=255"`
	// Ship-to street line 2.
	ShipToStreetLine2 field.Optional[string] `json:"ship_to_street_line_2,omitzero" validate:"omitempty,max=255"`
	// Ship-to locality/city.
	ShipToLocality field.Optional[string] `json:"ship_to_locality,omitzero" validate:"omitempty,max=255"`
	// Ship-to state/province.
	ShipToState field.Optional[string] `json:"ship_to_state,omitzero" validate:"omitempty,max=255"`
	// Ship-to postal code.
	ShipToPostalCode field.Optional[string] `json:"ship_to_postal_code,omitzero" validate:"omitempty,max=255"`
	// Ship-to country as a two-letter code.
	ShipToCountry field.Optional[string] `json:"ship_to_country,omitzero" validate:"omitempty,max=2"`
	// Order lines to create with the order.
	//
	// Lines can also be added afterwards through the create-line endpoint.
	Lines []CreatePurchaseOrderLineInput `json:"lines"`
	// IDs of account users to add as email contacts on the order.
	//
	// Contacts receive the purchase order email when the order is issued with `send_email`.
	ContactAccountUserIDs []string `json:"contact_account_user_ids,omitzero"`
	// Promised delivery date in `YYYY-MM-DD` format.
	//
	// Returned as `scheduled_at` on the purchase order resource.
	PromisedAt field.Optional[string] `json:"promised_at,omitzero"`
}

type DeletePurchaseOrderEndpoint struct{}

type DeletePurchaseOrderLineEndpoint struct{}

type DeletePurchaseOrderLineRequest struct {
	// Purchase order ID.
	PurchaseOrderID string `path:"id" validate:"required"`
	// Purchase order line ID.
	PurchaseOrderLineID string `path:"line_id" validate:"required"`
}

type DeletePurchaseOrderRequest struct {
	// Purchase order ID.
	PurchaseOrderID string `path:"id" validate:"required"`
}

type ListPurchaseOrderStatusesEndpoint struct{}

type ListPurchaseOrderStatusesRequest struct {
	apiresource.PaginationRequest
}

type ListPurchaseOrdersEndpoint struct{}

type ListPurchaseOrdersRequest struct {
	apiresource.PaginationRequest
	// Filter to orders with any of these statuses.
	StatusCodes []constants.SalesOrderStatusCode `query:"status_codes"`
	// Filter to orders with at least one line referencing any of these items.
	ItemIDs []string `query:"item_ids"`
	// Filter to orders placed with any of these suppliers.
	SupplierIDs []string `query:"supplier_ids"`
	// Filter to orders created on or after this date, in `YYYY-MM-DD` format.
	StartDate *string `query:"starts_at"`
	// Filter to orders created up to this date, in `YYYY-MM-DD` format.
	//
	// Compared against the start of the given day, so orders created later that same day are excluded.
	EndDate *string `query:"ends_at"`
}

type PurchaseOrderSvc interface {
	ListPurchaseOrders(ctx context.Context, req *ListPurchaseOrdersRequest) (*apiresource.List[apiresource.PurchaseOrder], *apierror.APIError)
	GetPurchaseOrder(ctx context.Context, req *RetrievePurchaseOrderRequest) (*apiresource.PurchaseOrder, *apierror.APIError)
	CreatePurchaseOrder(ctx context.Context, req *CreatePurchaseOrderRequest) (*apiresource.PurchaseOrder, *apierror.APIError)
	UpdatePurchaseOrder(ctx context.Context, req *UpdatePurchaseOrderRequest) (*apiresource.PurchaseOrder, *apierror.APIError)
	DeletePurchaseOrder(ctx context.Context, req *DeletePurchaseOrderRequest) (*apiresource.EmptyResource, *apierror.APIError)
	BulkDeletePurchaseOrders(ctx context.Context, req *BulkDeletePurchaseOrdersRequest) (*apiresource.EmptyResource, *apierror.APIError)
	ChangePurchaseOrderStatus(ctx context.Context, req *ChangePurchaseOrderStatusRequest) (*apiresource.PurchaseOrder, *apierror.APIError)
	CreatePurchaseOrderLine(ctx context.Context, req *CreatePurchaseOrderLineRequest) (*apiresource.PurchaseOrderLine, *apierror.APIError)
	UpdatePurchaseOrderLine(ctx context.Context, req *UpdatePurchaseOrderLineRequest) (*apiresource.PurchaseOrderLine, *apierror.APIError)
	DeletePurchaseOrderLine(ctx context.Context, req *DeletePurchaseOrderLineRequest) (*apiresource.EmptyResource, *apierror.APIError)
	ListPurchaseOrderStatuses(ctx context.Context, req *ListPurchaseOrderStatusesRequest) (*apiresource.List[apiresource.SalesOrderStatus], *apierror.APIError)
}

type PurchaseOrderSvcConfig struct {
	// CoreClient (required) is the core-service purchasing gRPC client.
	CoreClient pb.CorePurchaseServiceClient

	// SalesClient (required) is the core-service sales gRPC client.
	SalesClient pb.CoreSalesServiceClient
}

type RetrievePurchaseOrderEndpoint struct{}

type RetrievePurchaseOrderRequest struct {
	// Purchase order ID.
	PurchaseOrderID string `path:"id" validate:"required"`
}

type UpdatePurchaseOrderEndpoint struct{}

type UpdatePurchaseOrderLineEndpoint struct{}

type UpdatePurchaseOrderLineRequest struct {
	// Purchase order ID.
	PurchaseOrderID string `path:"id" validate:"required"`
	// Purchase order line ID.
	PurchaseOrderLineID string `path:"line_id" validate:"required"`
	// ID of the product ordered on this line.
	ProductID field.Optional[string] `json:"product_id,omitzero" validate:"omitempty"`
	// ID of the inventory item to tie this line to.
	ItemID field.Optional[string] `json:"item_id,omitzero" validate:"omitempty"`
	// SKU of the ordered product.
	ProductSKU field.Optional[string] `json:"product_sku,omitzero" validate:"omitempty,max=255"`
	// Free-text description of the ordered product.
	ProductDescription field.Optional[string] `json:"product_description,omitzero"`
	// Quantity ordered, as a decimal string.
	QuantityValue field.Optional[string] `json:"quantity_value,omitzero" format:"decimal"`
	// ID of the unit the quantity is measured in.
	QuantityUnitID field.Optional[string] `json:"quantity_unit_id,omitzero" validate:"omitempty"`
	// Purchase price per unit, as a decimal string.
	UnitPriceValue field.Optional[string] `json:"unit_price_value,omitzero" format:"decimal"`
	// ID of the unit price's numerator unit (e.g. a currency unit).
	UnitPriceNumeratorUnitID field.Optional[string] `json:"unit_price_numerator_unit_id,omitzero" validate:"omitempty"`
	// ID of the unit price's denominator unit (the unit the price is per).
	UnitPriceDenominatorUnitID field.Optional[string] `json:"unit_price_denominator_unit_id,omitzero" validate:"omitempty"`
	// Recorded cost per unit, as a decimal string.
	UnitCostValue field.Optional[string] `json:"unit_cost_value,omitzero" format:"decimal"`
	// ID of the unit cost's numerator unit (e.g. a currency unit).
	UnitCostNumeratorUnitID field.Optional[string] `json:"unit_cost_numerator_unit_id,omitzero" validate:"omitempty"`
	// ID of the unit cost's denominator unit (the unit the cost is per).
	UnitCostDenominatorUnitID field.Optional[string] `json:"unit_cost_denominator_unit_id,omitzero" validate:"omitempty"`
}

type UpdatePurchaseOrderRequest struct {
	// Purchase order ID.
	PurchaseOrderID string `path:"id" validate:"required"`
	// Free-form note to record on the order.
	Note field.Optional[string] `json:"note,omitzero"`
	// New purchase order number, replacing the one assigned at creation.
	//
	// Must be unique within the account; a number already used by another order is rejected.
	Number field.Optional[string] `json:"number,omitzero" validate:"omitempty,max=255"`
	// Priority level for fulfilling the order (`low`, `normal`, or `high`).
	PriorityCode field.Optional[constants.PriorityCode] `json:"priority_code,omitzero" validate:"omitempty"`
	// ID of an existing address to use as the bill-to address.
	BillingAddressID field.Optional[string] `json:"billing_address_id,omitzero" validate:"omitempty"`
	// ID of an existing address to use as the ship-to address.
	ShippingAddressID field.Optional[string] `json:"shipping_address_id,omitzero" validate:"omitempty"`
	// Promised delivery date in `YYYY-MM-DD` format.
	//
	// Returned as `scheduled_at` on the purchase order resource.
	PromisedAt field.Optional[string] `json:"promised_at,omitzero"`
	// IDs of account users to set as the order's email contacts.
	//
	// Replaces the full set of existing contacts; omit the field to leave contacts unchanged.
	ContactAccountUserIDs field.Optional[[]string] `json:"contact_account_user_ids,omitzero"`
}