shipmentep

type AdminUpdateShipmentTrackingEndpoint struct{}

type AdminUpdateShipmentTrackingRequest struct {
	// ID of the shipment to correct.
	ShipmentID string `path:"id" validate:"required"`
	// Carrier master tracking number covering the shipment as a whole.
	MasterTrackingNumber field.Optional[string] `json:"master_tracking_number,omitzero" validate:"omitempty,max=255"`
	// ID of the carrier that actually carried the shipment; the shipment's cases move with it.
	CarrierID field.Optional[string] `json:"carrier_id,omitzero" validate:"omitempty"`
	// ID of the carrier service level the shipment actually travelled on.
	// Sending this without `carrier_id` keeps the existing carrier, so the service level should belong to that carrier; send `null` to drop the service level entirely.
	ServiceLevelID field.Clearable[string] `json:"service_level_id,omitzero" validate:"omitempty"`
}

type CreateShipmentLineEndpoint struct{}

type CreateShipmentLineRequest struct {
	// ID of the shipment to add the line to.
	ShipmentID string `path:"shipment_id" validate:"required"`
	// ID of the sales order line this shipment line fulfills.
	SalesOrderLineID string `json:"sales_order_line_id" validate:"required"`
	// Quantity shipped, as a decimal string.
	QuantityValue string `json:"quantity_value" validate:"required"`
	// ID of the unit of measure for `quantity_value`.
	QuantityUnitID string `json:"quantity_unit_id" validate:"required"`
}

type DeleteShipmentEndpoint struct{}

type DeleteShipmentLineEndpoint struct{}

type DeleteShipmentLineRequest struct {
	// Shipment ID.
	ShipmentID string `path:"shipment_id" validate:"required"`
	// Shipment line ID.
	ShipmentLineID string `path:"id" validate:"required"`
}

type DeleteShipmentRequest struct {
	// Shipment ID.
	ShipmentID string `path:"id" validate:"required"`
}

type EstimateRateEndpoint struct{}

type EstimateRateRequest struct {
	// ID of the carrier to rate.
	CarrierID string `json:"carrier_id" validate:"required"`
	// ID of the carrier service level to rate.
	ServiceLevelID string `json:"service_level_id" validate:"required"`
	// Product lines of the items being shipped, used to apply freight exemptions.
	//
	// If any listed product line is freight exempt, the estimated rate is `0`.
	ProductLineIDs []string `json:"product_line_ids,omitzero"`
	// ID of the customer the shipment is for, used to apply the customer's freight policy and default shipping term.
	//
	// A customer that is freight exempt through its own policy or through one of its groups, or whose shipping term is free freight, yields a rate of `0`; a flat-rate shipping term returns the flat rate. Omitting the customer skips all of these rules and quotes the plain carrier rate.
	CustomerID field.Optional[string] `json:"customer_id,omitzero"`
	// Origin address.
	//
	// A live carrier rate requires a postal code and country here; without them the request fails rather than returning a meaningless estimate.
	FromAddress apirequest.AddressInput `json:"from_address" validate:"required"`
	// Destination address.
	ToAddress apirequest.AddressInput `json:"to_address" validate:"required"`
	// Parcels to estimate rates for.
	Parcels []ParcelInput `json:"parcels" validate:"required,min=1"`
	// Total value of the order, used to evaluate the free-shipping minimum order value on the customer's shipping term.
	//
	// Free shipping applies only when the total is strictly above the threshold, and only for the service levels the shipping term allows.
	OrderTotal field.Optional[float64] `json:"order_total,omitzero"`
}

type ListShipmentLinesEndpoint struct{}

type ListShipmentLinesRequest struct {
	// Shipment ID.
	ShipmentID string `path:"shipment_id" validate:"required"`
	apiresource.PaginationRequest
}

type ListShipmentsEndpoint struct{}

type ListShipmentsRequest struct {
	apiresource.PaginationRequest
	// Only include shipments with this status, either `packed` or `shipped`.
	Status *string `query:"status"`
	// Only include shipments containing at least one line for any of these items.
	ItemIDs []string `query:"item_ids"`
	// Only include shipments for any of these customers.
	CustomerIDs []string `query:"customer_ids"`
	// Only include shipments containing at least one line whose product belongs to any of these product lines.
	ProductLineIDs []string `query:"product_line_ids"`
	// Only include shipments whose customer belongs to any of these customer groups.
	CustomerGroupIDs []string `query:"customer_group_ids"`
	// Only include shipments whose customer is assigned to any of these sales reps, given as account
	// user IDs matching the customer's default sales rep.
	SalesRepIDs []string `query:"sales_rep_ids"`
	// Only include shipments created on or after this date (`YYYY-MM-DD`).
	//
	// Filters on when the shipment was created, not on when it was shipped.
	StartDate *string `query:"starts_at"`
	// Only include shipments created on or before this date (`YYYY-MM-DD`).
	//
	// Filters on when the shipment was created, not on when it was shipped.
	EndDate *string `query:"ends_at"`
}

type ParcelInput struct {
	// Parcel weight in pounds.
	Weight float64 `json:"weight" validate:"required"`
	// Parcel length in inches.
	Length float64 `json:"length" validate:"required"`
	// Parcel width in inches.
	Width float64 `json:"width" validate:"required"`
	// Parcel height in inches.
	Height float64 `json:"height" validate:"required"`
}

type RateShopEndpoint struct{}

type RateShopRequest struct {
	// Product lines of the items being shipped, used to apply freight exemptions.
	//
	// If any listed product line is freight exempt, no options are returned and `exemption_type` is `freight_exempt`.
	ProductLineIDs []string `json:"product_line_ids,omitzero"`
	// ID of the customer the shipment is for, used to apply the customer's freight policy and default shipping term.
	//
	// A customer that is freight exempt through its own policy or through one of its groups, or whose shipping term is free freight, returns no options with `exemption_type` set to `freight_exempt`; a flat-rate shipping term replaces carrier rates with the flat rate. Omitting the customer skips all of these rules and returns plain carrier rates.
	CustomerID field.Optional[string] `json:"customer_id,omitzero"`
	// Origin address.
	//
	// When omitted, the account's configured ship-from origin is used, which is how customer portal callers rate shop without knowing the seller's address.
	FromAddress field.Optional[apirequest.AddressInput] `json:"from_address,omitzero"`
	// Destination address.
	ToAddress apirequest.AddressInput `json:"to_address" validate:"required"`
	// Parcels to rate shop.
	Parcels []ParcelInput `json:"parcels" validate:"required,min=1"`
	// Total value of the order, used to evaluate the free-shipping minimum order value on the customer's shipping term.
	//
	// Free shipping applies only when the total is strictly above the threshold, and only for the service levels the shipping term allows.
	OrderTotal field.Optional[float64] `json:"order_total,omitzero"`
}

type RetrieveShipmentEndpoint struct{}

type RetrieveShipmentLineEndpoint struct{}

type RetrieveShipmentLineRequest struct {
	// Shipment ID.
	ShipmentID string `path:"shipment_id" validate:"required"`
	// Shipment line ID.
	ShipmentLineID string `path:"id" validate:"required"`
}

type RetrieveShipmentRequest struct {
	// Shipment ID.
	ShipmentID string `path:"id" validate:"required"`
}

type ShipShipmentEndpoint struct{}

type ShipShipmentRequest struct {
	// ID of the shipment to ship.
	ShipmentID string `path:"id" validate:"required"`
	// Whether to email the customer a shipping notification.
	//
	// Whether to email the customer the invoice raised for this shipment.
	EmailCustomer bool `json:"email_customer"`
}

type ShipmentSvc interface {
	ListShipments(ctx context.Context, req *ListShipmentsRequest) (*apiresource.List[apiresource.Shipment], *apierror.APIError)
	GetShipment(ctx context.Context, req *RetrieveShipmentRequest) (*apiresource.Shipment, *apierror.APIError)
	UpdateShipment(ctx context.Context, req *UpdateShipmentRequest) (*apiresource.Shipment, *apierror.APIError)
	AdminUpdateShipmentTracking(ctx context.Context, req *AdminUpdateShipmentTrackingRequest) (*apiresource.Shipment, *apierror.APIError)
	DeleteShipment(ctx context.Context, req *DeleteShipmentRequest) (*apiresource.EmptyResource, *apierror.APIError)
	ShipShipment(ctx context.Context, req *ShipShipmentRequest) (*apiresource.Shipment, *apierror.APIError)
	VoidShipment(ctx context.Context, req *VoidShipmentRequest) (*apiresource.Shipment, *apierror.APIError)
	EstimateRate(ctx context.Context, req *EstimateRateRequest) (*apiresource.EstimateRateResult, *apierror.APIError)
	RateShop(ctx context.Context, req *RateShopRequest) (*apiresource.RateShopResult, *apierror.APIError)
	ListShipmentLines(ctx context.Context, req *ListShipmentLinesRequest) (*apiresource.List[apiresource.ShipmentLine], *apierror.APIError)
	GetShipmentLine(ctx context.Context, req *RetrieveShipmentLineRequest) (*apiresource.ShipmentLine, *apierror.APIError)
	CreateShipmentLine(ctx context.Context, req *CreateShipmentLineRequest) (*apiresource.ShipmentLine, *apierror.APIError)
	UpdateShipmentLine(ctx context.Context, req *UpdateShipmentLineRequest) (*apiresource.ShipmentLine, *apierror.APIError)
	DeleteShipmentLine(ctx context.Context, req *DeleteShipmentLineRequest) (*apiresource.EmptyResource, *apierror.APIError)
}

type ShipmentSvcConfig struct {
	// CoreClient (required) is the core-service shipping gRPC client.
	CoreClient pb.CoreShippingServiceClient
}

type UpdateShipmentEndpoint struct{}

type UpdateShipmentLineEndpoint struct{}

type UpdateShipmentLineRequest struct {
	// Shipment ID.
	ShipmentID string `path:"shipment_id" validate:"required"`
	// Shipment line ID.
	ShipmentLineID string `path:"id" validate:"required"`
	// Quantity shipped, as a decimal string.
	QuantityValue field.Optional[string] `json:"quantity_value,omitzero"`
	// ID of the unit of measure for `quantity_value`.
	QuantityUnitID field.Optional[string] `json:"quantity_unit_id,omitzero" validate:"omitempty"`
}

type UpdateShipmentRequest struct {
	// ID of the shipment to update.
	ShipmentID string `path:"id" validate:"required"`
	// Note for the shipment.
	Note field.Optional[string] `json:"note,omitzero"`
	// Human-readable shipment number.
	Number field.Optional[string] `json:"number,omitzero" validate:"omitempty,max=255"`
	// Carrier master tracking number covering the shipment as a whole.
	MasterTrackingNumber field.Optional[string] `json:"master_tracking_number,omitzero" validate:"omitempty,max=255"`
	// ID of the carrier to set on the shipment's freight.
	//
	// Changing the carrier records the new selection only; it does not re-rate the shipment, so the freight charges already recorded on the shipping cases are left as they are.
	CarrierID field.Optional[string] `json:"carrier_id,omitzero" validate:"omitempty"`
	// ID of the carrier service level to set on the shipment's freight.
	//
	// Sending this without `carrier_id` keeps the existing carrier, so the service level should belong to that carrier; send `null` to drop the service level entirely.
	ServiceLevelID field.Clearable[string] `json:"service_level_id,omitzero" validate:"omitempty"`
}

type VoidShipmentEndpoint struct{}

type VoidShipmentRequest struct {
	// ID of the shipment to void.
	ShipmentID string `path:"id" validate:"required"`
}