# Store Allocation API

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:

| Strategy                 | Description                                                                                                                                  |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `distance_only`          | Ranks stores by straight-line distance to the destination only.                                                                              |
| `time_and_distance`      | Returns the `earliest_RFP_datetime` per store but does not affect ranking unless used as a tie-break between stores at equivalent distances. |
| `timeline_over_distance` | Prioritises 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

```json title="POST /{{tenant_id}}/deliveries/quote/allocation"
{
    "ready_for_pickup_at": "2025-03-12T12:00:00.000",
    "store_ids": [
        "store_001",
        "store_002",
        "store_003"
    ],
    "recommend_store_count": 3,
    "address": {
        "latitude": -37.1444,
        "longitude": 144.9999
    }
}
```

### Request Fields

| Field                            | Type              | Required | Description                                                                                                                                                                                                             |
| -------------------------------- | ----------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `address.latitude`               | Number            | Yes      | Latitude of the delivery destination.                                                                                                                                                                                   |
| `address.longitude`              | Number            | Yes      | Longitude of the delivery destination.                                                                                                                                                                                  |
| `ready_for_pickup_at`            | String (ISO 8601) | No       | The intended pickup time. Used to calculate `earliest_RFP_datetime` per store based on store hours, pickup hours, and processing time.                                                                                  |
| `store_ids` / `store_references` | Array             | No       | A 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_count`          | Integer           | No       | The number of ranked stores to return. Defaults to `3`.                                                                                                                                                                 |
| `use_async`                      | Boolean           | No       | When `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

```json title="200 OK"
{
    "store_allocation_ranks": [
        {
            "rank": 1,
            "store_id": "store_001",
            "store_reference": "ABC1",
            "est_distance_km": 1,
            "earliest_processing_datetime": "2025-03-12T12:00:00.000"
        },
        {
            "rank": 2,
            "store_id": "store_002",
            "store_reference": "ABC2",
            "est_distance_km": 2,
            "earliest_processing_datetime": "2025-03-12T12:00:00.000"
        },
        {
            "rank": 3,
            "store_id": "store_003",
            "store_reference": "ABC3",
            "est_distance_km": 3,
            "earliest_processing_datetime": "2025-03-12T12:00:00.000"
        }
    ]
}
```

### Response Fields

| Field                                                   | Type              | Description                                                                                                                |
| ------------------------------------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `store_allocation_ranks`                                | Array             | An ordered array of store objects ranked by the configured allocation strategy.                                            |
| `store_allocation_ranks[].rank`                         | Integer           | The calculated rank of the store.                                                                                          |
| `store_allocation_ranks[].store_id`                     | String            | The Rendr store ID for the location.                                                                                       |
| `store_allocation_ranks[].store_reference`              | String            | The merchant store reference for the location.                                                                             |
| `store_allocation_ranks[].est_distance_km`              | Integer           | The distance estimate used in ranking, rounded to the nearest kilometre.                                                   |
| `store_allocation_ranks[].earliest_processing_datetime` | String (ISO 8601) | The earliest datetime the store can process the order, based on store hours, pickup hours, and configured processing time. |

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