# Fulfillment & Delivery

### Fulfillment

#### Pickup Points

Manage the association between orders and physical pickup points. Pickup points represent designated locations where customers collect their orders.

### `POST /order_pickup_points` - Create Order Pickup Point

Associate an order with a pickup point.

#### Request Body

```json
{
  "orderId": 1927055,
  "pickupPointId": 42
}
```

##### Request Body Properties

Every field in the example is listed below. Explicit requiredness is shown when the endpoint contract defines it.

| Property | Type | Example | Description |
| --- | --- | --- | --- |
| orderId | integer | 1927055 | Identifier of the order. |
| pickupPointId | integer | 42 | Identifier of the associated pickup point. |

#### Response

```json
{
  "status": 200,
  "code": "order_pickup_point_created",
  "message": "The order pickup point has been created.",
  "data": {
    "orderPickupPointId": 789,
    "orderId": 1927055,
    "pickupPointId": 42
  }
}
```

##### Response Properties

Every field in the example is listed below. Explicit requiredness is shown when the endpoint contract defines it.

| Property | Type | Example | Description |
| --- | --- | --- | --- |
| status | integer | 200 | HTTP status code returned by the API. |
| code | string | "order\_pickup\_point\_created" | Machine-readable application code for the result. |
| message | string | "The order pickup point has been created." | Human-readable result message. Do not use this value for program logic. |
| data | object | {…} | Endpoint-specific response payload. |
| data.orderPickupPointId | integer | 789 | Identifier of the associated order pickup point. |
| data.orderId | integer | 1927055 | Identifier of the order. |
| data.pickupPointId | integer | 42 | Identifier of the associated pickup point. |

### `GET /order_pickup_points/{orderPickupPointId}` - Get Order Pickup Point

Retrieve a specific order-pickup-point association by its ID.

#### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| orderPickupPointId | integer | Yes | The order pickup point ID. |

#### Response

```json
{
  "status": 200,
  "code": "order_pickup_point_retrieved",
  "message": "The order pickup point has been retrieved.",
  "data": {
    "orderPickupPointId": 789,
    "orderId": 1927055,
    "pickupPointId": 42
  }
}
```

##### Response Properties

Every field in the example is listed below. Explicit requiredness is shown when the endpoint contract defines it.

| Property | Type | Example | Description |
| --- | --- | --- | --- |
| status | integer | 200 | HTTP status code returned by the API. |
| code | string | "order\_pickup\_point\_retrieved" | Machine-readable application code for the result. |
| message | string | "The order pickup point has been retrieved." | Human-readable result message. Do not use this value for program logic. |
| data | object | {…} | Endpoint-specific response payload. |
| data.orderPickupPointId | integer | 789 | Identifier of the associated order pickup point. |
| data.orderId | integer | 1927055 | Identifier of the order. |
| data.pickupPointId | integer | 42 | Identifier of the associated pickup point. |

### `GET /order_pickup_points/orders/{orderId}` - Get Pickup Point by Order

Retrieve the pickup point associated with a given order.

#### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| orderId | integer | Yes | The order ID. |

#### Response

```json
{
  "status": 200,
  "code": "order_pickup_point_retrieved",
  "message": "The order pickup point has been retrieved.",
  "data": {
    "orderPickupPointId": 789,
    "orderId": 1927055,
    "pickupPointId": 42
  }
}
```

##### Response Properties

Every field in the example is listed below. Explicit requiredness is shown when the endpoint contract defines it.

| Property | Type | Example | Description |
| --- | --- | --- | --- |
| status | integer | 200 | HTTP status code returned by the API. |
| code | string | "order\_pickup\_point\_retrieved" | Machine-readable application code for the result. |
| message | string | "The order pickup point has been retrieved." | Human-readable result message. Do not use this value for program logic. |
| data | object | {…} | Endpoint-specific response payload. |
| data.orderPickupPointId | integer | 789 | Identifier of the associated order pickup point. |
| data.orderId | integer | 1927055 | Identifier of the order. |
| data.pickupPointId | integer | 42 | Identifier of the associated pickup point. |

### `GET /order_pickup_points/pickup_points/{pickupPointId}` - Get Orders by Pickup Point

Retrieve all order associations for a given pickup point.

#### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| pickupPointId | integer | Yes | The pickup point ID. |

#### Response

```json
{
  "status": 200,
  "code": "order_pickup_point_retrieved",
  "message": "The order pickup point has been retrieved.",
  "data": [
    {
      "orderPickupPointId": 789,
      "orderId": 1927055,
      "pickupPointId": 42
    },
    {
      "orderPickupPointId": 790,
      "orderId": 1927060,
      "pickupPointId": 42
    }
  ]
}
```

##### Response Properties

Every field in the example is listed below. Explicit requiredness is shown when the endpoint contract defines it.

| Property | Type | Example | Description |
| --- | --- | --- | --- |
| status | integer | 200 | HTTP status code returned by the API. |
| code | string | "order\_pickup\_point\_retrieved" | Machine-readable application code for the result. |
| message | string | "The order pickup point has been retrieved." | Human-readable result message. Do not use this value for program logic. |
| data | array | \[…\] | Endpoint-specific response payload. |
| data\[\] | object | {…} | Endpoint-specific response payload. |
| data\[\].orderPickupPointId | integer | 789 | Identifier of the associated order pickup point. |
| data\[\].orderId | integer | 1927055 | Identifier of the order. |
| data\[\].pickupPointId | integer | 42 | Identifier of the associated pickup point. |

### Cart Management

Manage saved carts. Carts can be referenced during order creation via the `cartId` field.

### `DELETE /carts/{cartId}` - Delete Cart

Delete a saved cart by its ID. No authentication required.

#### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| cartId | string | Yes | The cart ID to delete. |

#### Response

```json
{
  "status": 200,
  "code": "cart_deleted",
  "message": "Cart deleted successfully."
}
```

##### Response Properties

Every field in the example is listed below. Explicit requiredness is shown when the endpoint contract defines it.

| Property | Type | Example | Description |
| --- | --- | --- | --- |
| status | integer | 200 | HTTP status code returned by the API. |
| code | string | "cart\_deleted" | Machine-readable application code for the result. |
| message | string | "Cart deleted successfully." | Human-readable result message. Do not use this value for program logic. |

### Delivery Areas

Managing a restaurant's delivery zones (listing, replacing, and binding them to consumption modes) is documented in [Restaurant Operations → Delivery Areas](https://developers.innovorder.io/docs/restaurant-operations/delivery-areas.md). The read-only endpoints below are useful in ordering flows: listing zones across a whole brand, and reading the weekly schedules of a single zone. To resolve the zone matching a customer address, see the [Delivery](https://developers.innovorder.io/docs/orders/orders-fulfillment-delivery.md) section below.

### `GET /areas/brand/{brandId}` - List Delivery Areas by Brand

Retrieve all restaurants of a brand with their delivery areas.

#### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| brandId | integer | Yes | The unique identifier of the brand. |

#### Response

```json
{
  "status": 200,
  "code": "restaurant_succeed",
  "data": [
    {
      "name": "Le Bistrot",
      "restaurantId": 200,
      "areas": [
        {
          "areaId": 45,
          "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "name": "Paris Centre",
          "deliveryFee": 350,
          "deliveryDelay": 30,
          "isActivated": true,
          "minimumAmount": 1500
        }
      ]
    }
  ]
}
```

##### Response Properties

Every field in the example is listed below. Explicit requiredness is shown when the endpoint contract defines it.

| Property | Type | Example | Description |
| --- | --- | --- | --- |
| status | integer | 200 | HTTP status code returned by the API. |
| code | string | "restaurant\_succeed" | Machine-readable application code for the result. |
| data | array | \[…\] | Endpoint-specific response payload. |
| data\[\] | object | {…} | Endpoint-specific response payload. |
| data\[\].name | string | "Le Bistrot" | The name value. |
| data\[\].restaurantId | integer | 200 | Identifier of the restaurant. |
| data\[\].areas | array | \[…\] | List of areas entries. |
| data\[\].areas\[\] | object | {…} | Object containing areas fields. |
| data\[\].areas\[\].areaId | integer | 45 | Identifier of the associated area. |
| data\[\].areas\[\].uuid | string | "a1b2c3d4-e5f6-7890-abcd-ef1234567890" | The uuid value. |
| data\[\].areas\[\].name | string | "Paris Centre" | The name value. |
| data\[\].areas\[\].deliveryFee | integer | 350 | The delivery fee value. |
| data\[\].areas\[\].deliveryDelay | integer | 30 | The delivery delay value. |
| data\[\].areas\[\].isActivated | boolean | true | Whether activated is enabled or applies. |
| data\[\].areas\[\].minimumAmount | integer | 1500 | The minimum amount value. |

### `GET /areas/{areaUuid}/area_schedules` - Get Area Schedules

Retrieve the weekly schedules of a delivery area by its UUID. No authentication required.

#### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| areaUuid | string | Yes | The UUID of the delivery area. |

#### Response

```json
{
  "status": 200,
  "code": "area_schedules_succeed",
  "message": "You can access to these area schedules.",
  "data": [
    {
      "areaScheduleId": 12,
      "areaId": 45,
      "day": "MON",
      "start": 690,
      "end": 840,
      "orderingQuota": 20
    }
  ]
}
```

##### Response Properties

Every field in the example is listed below. Explicit requiredness is shown when the endpoint contract defines it.

| Property | Type | Example | Description |
| --- | --- | --- | --- |
| status | integer | 200 | HTTP status code returned by the API. |
| code | string | "area\_schedules\_succeed" | Machine-readable application code for the result. |
| message | string | "You can access to these area schedules." | Human-readable result message. Do not use this value for program logic. |
| data | array | \[…\] | Endpoint-specific response payload. |
| data\[\] | object | {…} | Endpoint-specific response payload. |
| data\[\].areaScheduleId | integer | 12 | Identifier of the associated area schedule. |
| data\[\].areaId | integer | 45 | Identifier of the associated area. |
| data\[\].day | string | "MON" | The day value. |
| data\[\].start | integer | 690 | The start value. |
| data\[\].end | integer | 840 | The end value. |
| data\[\].orderingQuota | integer | 20 | The ordering quota value. |

### Location

The Location endpoints provide geocoding, address autocomplete, and place details powered by Google Maps. These are typically used in delivery flows to let customers search for and validate their delivery address.

#### Autocomplete Address

Returns address suggestions as the customer types. Use a consistent `sessiontoken` across autocomplete and place details calls to group them into a single billing session on Google Maps.

### `GET /location/autocomplete` - Search address suggestions

Returns a list of address suggestions matching the search text. Pass a unique session token to group this call with a subsequent place details lookup.

#### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| searchText | string | Yes | Partial address text typed by the user. |
| sessiontoken | string | Yes | A UUID that groups autocomplete and place details requests into a single session for billing. |

#### Response

```json
{
  "status": 200,
  "code": "autocomplete_success",
  "message": "Points of interest have been found",
  "data": {
    "suggestions": [
      {
        "name": "10 Rue de la Paix, Paris, France",
        "provider": "google",
        "providerId": "ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      {
        "name": "10 Rue de la Paix, Lyon, France",
        "provider": "google",
        "providerId": "ChIJMcbr7Crq9EcRoC_unOSfQE0"
      }
    ]
  }
}
```

##### Response Properties

Every field in the example is listed below. Explicit requiredness is shown when the endpoint contract defines it.

| Property | Type | Example | Description |
| --- | --- | --- | --- |
| status | integer | 200 | HTTP status code returned by the API. |
| code | string | "autocomplete\_success" | Machine-readable application code for the result. |
| message | string | "Points of interest have been found" | Human-readable result message. Do not use this value for program logic. |
| data | object | {…} | Endpoint-specific response payload. |
| data.suggestions | array | \[…\] | List of suggestions entries. |
| data.suggestions\[\] | object | {…} | Object containing suggestions fields. |
| data.suggestions\[\].name | string | "10 Rue de la Paix, Paris, France" | The name value. |
| data.suggestions\[\].provider | string | "google" | The provider value. |
| data.suggestions\[\].providerId | string | "ChIJLU7jZClu5kcR4PcOOO6p3I0" | Identifier of the associated provider. |

#### Place Details

After the customer selects a suggestion from the autocomplete results, call this endpoint with the `providerId` to get the full structured address including coordinates.

### `GET /location/place_details` - Get full address from a place ID

Retrieves detailed address information (street, city, postal code, coordinates) for a given Google place ID. Use the same session token as the preceding autocomplete call.

#### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| placeId | string | Yes | The provider place ID returned by the autocomplete endpoint (providerId). |
| sessiontoken | string | Yes | The same session token used in the autocomplete request. |

#### Response

```json
{
  "status": 200,
  "code": "place_details_success",
  "message": "The place details have been found",
  "data": {
    "place": {
      "name": "10 Rue de la Paix, 75002 Paris, France",
      "provider": "google",
      "providerId": "ChIJLU7jZClu5kcR4PcOOO6p3I0",
      "streetNumber": "10",
      "route": "Rue de la Paix",
      "locality": "Paris",
      "postalCode": "75002",
      "administrativeAreaLevel1": "Ile-de-France",
      "administrativeAreaLevel2": "Paris",
      "country": "France",
      "lat": 48.8698,
      "lng": 2.3308
    }
  }
}
```

##### Response Properties

Every field in the example is listed below. Explicit requiredness is shown when the endpoint contract defines it.

| Property | Type | Example | Description |
| --- | --- | --- | --- |
| status | integer | 200 | HTTP status code returned by the API. |
| code | string | "place\_details\_success" | Machine-readable application code for the result. |
| message | string | "The place details have been found" | Human-readable result message. Do not use this value for program logic. |
| data | object | {…} | Endpoint-specific response payload. |
| data.place | object | {…} | Object containing place fields. |
| data.place.name | string | "10 Rue de la Paix, 75002 Paris, France" | The name value. |
| data.place.provider | string | "google" | The provider value. |
| data.place.providerId | string | "ChIJLU7jZClu5kcR4PcOOO6p3I0" | Identifier of the associated provider. |
| data.place.streetNumber | string | "10" | The street number value. |
| data.place.route | string | "Rue de la Paix" | The route value. |
| data.place.locality | string | "Paris" | The locality value. |
| data.place.postalCode | string | "75002" | The postal code value. |
| data.place.administrativeAreaLevel1 | string | "Ile-de-France" | The administrative area level1 value. |
| data.place.administrativeAreaLevel2 | string | "Paris" | The administrative area level2 value. |
| data.place.country | string | "France" | The country value. |
| data.place.lat | number | 48.8698 | The lat value. |
| data.place.lng | number | 2.3308 | The lng value. |

#### Geocode Address

Converts a free-text address string into geographic coordinates and a structured address. This is useful when you already have a full address and need to resolve its latitude and longitude.

### `GET /location/geocode` - Geocode an address to coordinates

Takes a full address string and returns latitude, longitude, and the resolved street name.

#### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| address | string | Yes | The full address to geocode (e.g., "10 Rue de la Paix, 75002 Paris, France"). |

#### Response

```json
{
  "status": 200,
  "code": "geocode_found",
  "message": "Address coordinates have been found",
  "data": {
    "lat": 48.8698,
    "lng": 2.3308,
    "route": "Rue de la Paix"
  }
}
```

##### Response Properties

Every field in the example is listed below. Explicit requiredness is shown when the endpoint contract defines it.

| Property | Type | Example | Description |
| --- | --- | --- | --- |
| status | integer | 200 | HTTP status code returned by the API. |
| code | string | "geocode\_found" | Machine-readable application code for the result. |
| message | string | "Address coordinates have been found" | Human-readable result message. Do not use this value for program logic. |
| data | object | {…} | Endpoint-specific response payload. |
| data.lat | number | 48.8698 | The lat value. |
| data.lng | number | 2.3308 | The lng value. |
| data.route | string | "Rue de la Paix" | The route value. |

#### Typical Flow

1.  Generate a UUID to use as `sessiontoken`.
2.  Call `GET /location/autocomplete` as the user types, passing the `sessiontoken`.
3.  When the user selects a suggestion, call `GET /location/place_details` with the `providerId` and the same `sessiontoken`.
4.  Use the returned coordinates (`lat`, `lng`) to check delivery eligibility via `GET /deliveries/restaurant/{restaurantId}`.

### Delivery

The Delivery endpoint determines whether a given set of coordinates falls within a restaurant's configured delivery area. If the address is within range, it returns the matching delivery area configuration including fees, delays, and minimum order amounts.

### `GET /deliveries/restaurant/{restaurantId}` - Get delivery configuration for coordinates

Checks whether the given latitude and longitude fall within one of the restaurant's active delivery areas. Returns the matching area with its delivery fee, estimated delay, minimum order amount, and schedule settings. Throws an error if no delivery area covers the specified coordinates.

#### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| restaurantId | string | Yes | The unique identifier of the restaurant. |
| lat | number | Yes | Latitude of the delivery address. |
| lng | number | Yes | Longitude of the delivery address. |

#### Response

```json
{
  "status": 200,
  "code": "delivery_area_by_address_succeed",
  "message": "Your address can be delivered by this area.",
  "data": {
    "areaId": 542,
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Paris Centre",
    "deliveryFee": 350,
    "deliveryDelay": 30,
    "isActivated": true,
    "minimumAmount": 1500,
    "minimumAmountForFreeDelivery": 3000,
    "paymentLater": false,
    "forceOnlinePayment": true,
    "restaurantId": 200,
    "priority": 1,
    "isScheduleModeEnabled": false,
    "schedules": [
      {
        "day": "monday",
        "startTime": "11:00",
        "endTime": "14:00"
      },
      {
        "day": "monday",
        "startTime": "18:00",
        "endTime": "22:00"
      }
    ]
  }
}
```

##### Response Properties

Every field in the example is listed below. Explicit requiredness is shown when the endpoint contract defines it.

| Property | Type | Example | Description |
| --- | --- | --- | --- |
| status | integer | 200 | HTTP status code returned by the API. |
| code | string | "delivery\_area\_by\_address\_succeed" | Machine-readable application code for the result. |
| message | string | "Your address can be delivered by this area." | Human-readable result message. Do not use this value for program logic. |
| data | object | {…} | Endpoint-specific response payload. |
| data.areaId | integer | 542 | Identifier of the associated area. |
| data.uuid | string | "a1b2c3d4-e5f6-7890-abcd-ef1234567890" | The uuid value. |
| data.name | string | "Paris Centre" | The name value. |
| data.deliveryFee | integer | 350 | The delivery fee value. |
| data.deliveryDelay | integer | 30 | The delivery delay value. |
| data.isActivated | boolean | true | Whether activated is enabled or applies. |
| data.minimumAmount | integer | 1500 | The minimum amount value. |
| data.minimumAmountForFreeDelivery | integer | 3000 | The minimum amount for free delivery value. |
| data.paymentLater | boolean | false | The payment later value. |
| data.forceOnlinePayment | boolean | true | The force online payment value. |
| data.restaurantId | integer | 200 | Identifier of the restaurant. |
| data.priority | integer | 1 | The priority value. |
| data.isScheduleModeEnabled | boolean | false | Whether schedule mode enabled is enabled or applies. |
| data.schedules | array | \[…\] | List of schedules entries. |
| data.schedules\[\] | object | {…} | Object containing schedules fields. |
| data.schedules\[\].day | string | "monday" | The day value. |
| data.schedules\[\].startTime | string | "11:00" | The start time value. |
| data.schedules\[\].endTime | string | "14:00" | The end time value. |

**Note:** If the coordinates do not fall within any active delivery area for the restaurant, the API returns an error with the code `no_delivery_area_found`. Your application should handle this case by informing the customer that delivery is not available at their address.