Store Allocation

Store Allocation API

View as Markdown

Returns a ranked list of stores best suited to fulfil a delivery for a given destination and pickup time. The ranking is determined by the location selection strategy configured on your brand — based on distance, earliest processing time, or a combination of both.

Endpoint

POST {{domain}}/{{tenant_id}}/deliveries/quote/allocation

Authentication: Bearer token required via the Authorization header.

Location Selection Strategies

The ranking logic applied to results is controlled by your brand-level configuration:

StrategyDescription
distance_onlyRanks stores by straight-line distance to the destination only.
time_and_distanceReturns the earliest_RFP_datetime per store but does not affect ranking unless used as a tie-break between stores at equivalent distances.
timeline_over_distancePrioritises stores by earliest earliest_RFP_datetime, then uses distance as a tie-break.

Contact your Rendr implementation partner to confirm or update the strategy configured for your account.

Request Payload

POST /{{tenant_id}}/deliveries/quote/allocation
1{
2    "ready_for_pickup_at": "2025-03-12T12:00:00.000",
3    "store_ids": [
4        "store_001",
5        "store_002",
6        "store_003"
7    ],
8    "recommend_store_count": 3,
9    "address": {
10        "latitude": -37.1444,
11        "longitude": 144.9999
12    }
13}

Request Fields

FieldTypeRequiredDescription
address.latitudeNumberYesLatitude of the delivery destination.
address.longitudeNumberYesLongitude of the delivery destination.
ready_for_pickup_atString (ISO 8601)NoThe intended pickup time. Used to calculate earliest_RFP_datetime per store based on store hours, pickup hours, and processing time.
store_ids / store_referencesArrayNoA list of specific stores to consider for allocation. Accepts either Rendr store_id values or merchant store references. Limiting the candidate list is recommended for performance.
recommend_store_countIntegerNoThe number of ranked stores to return. Defaults to 3.
use_asyncBooleanNoWhen true, the request is processed asynchronously and a job ID is returned. The result can be polled at the allocation/status/ endpoint. Webhook-based return workflows can be configured on a case-by-case basis.

Sample Response

200 OK
1{
2    "store_allocation_ranks": [
3        {
4            "rank": 1,
5            "store_id": "store_001",
6            "store_reference": "ABC1",
7            "est_distance_km": 1,
8            "earliest_processing_datetime": "2025-03-12T12:00:00.000"
9        },
10        {
11            "rank": 2,
12            "store_id": "store_002",
13            "store_reference": "ABC2",
14            "est_distance_km": 2,
15            "earliest_processing_datetime": "2025-03-12T12:00:00.000"
16        },
17        {
18            "rank": 3,
19            "store_id": "store_003",
20            "store_reference": "ABC3",
21            "est_distance_km": 3,
22            "earliest_processing_datetime": "2025-03-12T12:00:00.000"
23        }
24    ]
25}

Response Fields

FieldTypeDescription
store_allocation_ranksArrayAn ordered array of store objects ranked by the configured allocation strategy.
store_allocation_ranks[].rankIntegerThe calculated rank of the store.
store_allocation_ranks[].store_idStringThe Rendr store ID for the location.
store_allocation_ranks[].store_referenceStringThe merchant store reference for the location.
store_allocation_ranks[].est_distance_kmIntegerThe distance estimate used in ranking, rounded to the nearest kilometre.
store_allocation_ranks[].earliest_processing_datetimeString (ISO 8601)The earliest datetime the store can process the order, based on store hours, pickup hours, and configured processing time.

Fields returned within each store object may vary depending on your account configuration and the active allocation strategy.