- v1.0.0-latest-prod
A FulfillmentDestination provides an encapsulation of geographic location data. Fulfillment Destinations are used by calculators to specify which geographic areas the calculator should apply to. A Fulfillment Calculator can be configured with a single Fulfillment Destination.
A FulfillmentDestinationDetail contains fields such as country, region, and postal code to precisely specify geographic areas.
Within a single Fulfillment Destination, multiple Fulfillment Destination Details can be used to precisely configure the geographic areas included in the Fulfillment Destination.
Fulfillment Destinations have two lists of Fulfillment Destination Details, Included Destinations and Excluded Destinations. Included Destinations indicate which geographic areas are considered part of the Fulfillment Destination. Excluded Destinations indicate smaller areas of Included Destinations that should be excluded.
For example, a Fulfillment Destination for "Contiguous USA States" could include the whole country US, and exclude the states Alaska and Hawaii.
There are 2 types of Destination Details, Zone and Radius.
The Zone type specifies areas by Country, State, City, or Postal Code. Country is required; the other fields are optional. In the above example, there is a country-only detail and two details that specify a state.
The Radius type determines an area by calculating a circle around a central point. Specify a distance for the radius of the circle and specify the middle with either a street address or coordinates.
Determining whether an address is within a radius requires some type of geolocation. Fulfillment Services does not provide any geolocation services out of the box. However, there are a few options to supply geolocation data:
Implement a GeolocationProvider to get latitude and longitude coordinates for addresses from a third-party geolocation service of your choosing. If a GeolocationProvider bean is available, the DefaultGeoCoordinateService will use it to get coordinates for addresses. The DefaultGeoCoordinateService has an implementation of the Haversine formula to calculate distance between latitude and longitude coordinates. See Haversine Formula on Wikipedia.
If a third-party geolocation service can directly calculate distance between two addresses, a custom GeoCoordinateService can be implemented to connect to the third-party and return the distance response.
Latitude and longitude can be supplied by the front-end when submitting an address on checkout. The DefaultGeoCoordinateService will use the Haversine Formula to calculate if the address is within a Destination’s radius. A Destination Detail’s radius center point must be specified with coordinates if there is no back-end GeolocationProvider configured.
The DefaultFulfillmentCalculatorFilterService evaluates which calculators should be used for fulfillment pricing, including checking that the calculator’s Fulfillment Destination matches the fulfillment address.
When matching to an address, a Destination’s included details are checked against the address first. If any included details match the address, then the excluded details are evaluated. The calculator will qualify on the destination check if the address matches an included detail and does not match an excluded detail.