---
title: "Special data types"
description: "Some Ordering API fields use structured JSON. Preserve the exact field names and value types shown by the target operation schema."
canonical: https://docs.ordering.co/api-reference/guides/special-data-types/
---

# Special data types

Some Ordering API fields use structured JSON. Preserve the exact field names and value types shown by the target operation schema.

## Schedules

Schedules are used by resources such as businesses, menus, and delivery areas. A non-null schedule contains exactly seven day objects. Each day has a Boolean `enabled` value and an array of `lapses`.

```json
[
  {"enabled": true, "lapses": [{"open": {"hour": 9, "minute": 0}, "close": {"hour": 17, "minute": 0}}]},
  {"enabled": true, "lapses": [{"open": {"hour": 9, "minute": 0}, "close": {"hour": 17, "minute": 0}}]},
  {"enabled": true, "lapses": [{"open": {"hour": 9, "minute": 0}, "close": {"hour": 17, "minute": 0}}]},
  {"enabled": true, "lapses": [{"open": {"hour": 9, "minute": 0}, "close": {"hour": 17, "minute": 0}}]},
  {"enabled": true, "lapses": [{"open": {"hour": 9, "minute": 0}, "close": {"hour": 17, "minute": 0}}]},
  {"enabled": true, "lapses": [{"open": {"hour": 9, "minute": 0}, "close": {"hour": 17, "minute": 0}}]},
  {"enabled": false, "lapses": []}
]
```

- `open` and `close` contain integer `hour` and `minute` fields.
- Use 24-hour values. Hours range from `0` to `23`, and minutes range from `0` to `59`.
- An opening time cannot be later than its closing time within the same lapse.
- The source convention orders days from Sunday through Saturday. The current validator enforces seven entries and their shape, but does not label the entries, so preserve the order required by the consuming operation.

## Order products

Order product input contains a product `id`, `quantity`, optional `comment`, ingredient identifiers, and selected options.

The legacy numeric form remains supported by current order handling:

```json
[
  {
    "id": 1309,
    "quantity": 1,
    "comment": "No onions",
    "ingredients": [10],
    "options": [
      {
        "id": 53,
        "suboptions": [174, 175]
      }
    ]
  }
]
```

The object form adds `position` and `quantity` for each suboption:

```json
[
  {
    "id": 1309,
    "quantity": 1,
    "comment": "No onions",
    "ingredients": [10],
    "options": [
      {
        "id": 53,
        "suboptions": [
          {
            "id": 174,
            "position": "left",
            "quantity": 1
          }
        ]
      }
    ]
  }
]
```

The conventional `position` values used for modifier placement are `left`, `right`, and `whole`; `whole` is also the default. These are documented usage values, not a claim that the API validates `position` against an enum.

Order handling preserves a non-`whole` position when both the project's `advanced_product_options` setting and the parent option's `with_half_option` setting are enabled. For a half placement, a non-null suboption `half_price` is used; when it is null, the backend falls back to the full `price`. The half price is configured rather than calculated as a percentage.

Suboption `quantity` defaults to `1` and is separate from the product-level `quantity`. The option's `allow_suboption_quantity` setting controls whether suboption quantities can be used, and configured `max` values can constrain them. Placement and quantity are distinct; this does not define how a half placement counts toward an option group's selection count.

The backend distinguishes numeric `0` from `null`, but the reviewed client UI uses a truthiness check for this price. Do not assume a zero half price is displayed consistently as free across clients.

For the Website flow, see [Customize and add a product](https://docs.ordering.co/docs/products/website/browse/customize-product/). For setup, see [Configure product options](https://docs.ordering.co/docs/products/dashboard/stores/create-edit-product/product-options/); for the suboption price fields, see the [Extra option suboption model](https://docs.ordering.co/api-reference/guides/extra-option-suboption-model/).

## Locations

Locations use latitude and longitude:

```json
{
  "lat": 40.8065,
  "lng": -73.9536
}
```

## Polygons

A polygon is an array of at least three distinct locations:

```json
[
  {"lat": 40.8065, "lng": -73.9536},
  {"lat": 40.8083, "lng": -73.9436},
  {"lat": 40.8013, "lng": -73.9375}
]
```

Delivery-zone validation normalizes `lat` and `lng` to numeric values and rejects malformed polygons.

## Radius-based delivery zones

The legacy contract uses the field name `radio` for the radius value. Preserve that literal key.

```json
{
  "center": {
    "lat": 40.8065,
    "lng": -73.9536
  },
  "radio": 10
}
```

The source documentation describes `radio` in kilometers. Confirm the unit in the target operation before calculating or transforming delivery-zone data.

## Customer data

Customer objects can include identity, contact, address, and location fields. Use synthetic data in examples and send only fields accepted by the target operation.

```json
{
  "id": -1,
  "name": "Example",
  "lastname": "Customer",
  "email": "customer@example.com",
  "address": "100 Example Street",
  "address_notes": "Leave at reception",
  "zipcode": "10001",
  "cellphone": "5550100",
  "phone": "5550101",
  "location": {
    "lat": 40.7314,
    "lng": -73.997
  },
  "map_data": {
    "library": "google",
    "place_id": "example-place-id"
  }
}
```

The historical contract uses `id: -1` for a non-registered customer. Verify that behavior against the operation that accepts the customer object.

## Map data

`map_data` can be `null` or an object containing the map provider and place identifier:

```json
{
  "library": "google",
  "place_id": "example-place-id"
}
```