Marketplace · Tenvelo API

GET/v1/marketplace-listings

List the locations on the marketplace

No. listMarketplaceListingsAuth no token

The locations that have joined the marketplace and can take an order, nearest the point given first (docs/decisions/0115). Public: a guest browses before signing in, and a location that joined asked to be found. A location is listed only with an address, a place on the map, business hours and a way to order.

Parameters

latitudequery · number · double
Required
Where the guest is, or the place they chose.
longitudequery · number · double
Required
cursorquery · string
Opaque cursor from a previous page's next_cursor. Omit to start from the beginning.
Pass it back exactly as received. It is base64 and its structure is not part of this contract — decoding it, or constructing one by hand, will break without notice.
limitquery · integer · int32
Maximum items to return. The server may return fewer, so always drive the loop from has_more rather than from the size of the page you got back.

Responses

200
A page of the marketplace.
MarketplaceListingPage · application/json
- has_moreboolean
  
  Required
  Whether another page follows.
- itemsarray of MarketplaceListing
  
  Required
  - namestring
    
    Required
    The location's name.
  - accepting_ordersboolean
    
    Required
    Whether the ordering page takes an order now. False while it is paused or off.
  - addressAddress
    
    Required
    A postal address.
    The address_line_* fields carry the most specific part of the address — street number, street name, building name. Less specific detail belongs in locality, administrative_district_level_* and country.
    The administrative_district_level_* fields are deliberately generic because their meaning is country-dependent: in the US level 1 is the state and level 2 the county; in the UK level 1 is the county.
    
    address_line_1string
    
    Required
    First line of the address — street number, street name, building name.
    ≤ 255 chars
    
    address_line_2string
    Second line of the address, if any.
    ≤ 255 chars
    
    address_line_3string
    Third line of the address, if any.
    ≤ 255 chars
    
    administrative_district_level_1string
    A civil entity within the country. The state in the US; the county in the UK.
    ≤ 128 chars
    
    administrative_district_level_2string
    A civil entity within administrative_district_level_1.
    ≤ 128 chars
    
    countryCountry
    
    Required
    ISO 3166-1 alpha-2 country code.
    ZZ is the unknown/unspecified placeholder.
    One of 250 values; see the schema.
    
    localitystring
    The city or town.
    ≤ 128 chars
    
    postal_codestring
    The postal or ZIP code.
    ≤ 32 chars
    
    sublocalitystring
    A civil region within the locality, if any.
    ≤ 128 chars
  - business_hoursarray of DaypartWindow
    
    Required
    The hours the location trades, in its own timezone.
    ≤ 8 items
    
    daysarray of integer
    The weekdays this window opens on, 1 (Monday) through 7 (Sunday). An empty or absent list is every day.
    ≤ 7 items
    
    end_minuteinteger
    
    Required
    1–1440
    
    start_minuteinteger
    
    Required
    0–1439
  - business_namestring
    
    Required
    The business the location belongs to, by its trading name where it has one.
  - collectionboolean
    
    Required
    Whether a guest can order online to collect.
  - coordinatesCoordinates
    
    Required
    A point on the WGS 84 ellipsoid, in decimal degrees. Square's location coordinates.
    
    latitudenumber · double
    
    Required
    -90–90
    
    longitudenumber · double
    
    Required
    -180–180
  - descriptionstring
    
    Required
    What the location says about itself. Empty when it says nothing.
    ≤ 280 chars
  - distance_metersinteger · int64
    
    Required
    How far the location is from the point asked about, along the great circle, in meters.
    ≥ 0
  - location_idstring · uuid
    
    Required
  - page_urlstring · uri
    
    RequiredNullable
    The location's ordering page, or null when it takes orders only at its tables.
  - prep_time_minutesinteger · int32
    
    Required
    What the location quotes for collection, in minutes.
    ≥ 0
  - table_orderingboolean
    
    Required
    Whether a guest at a table can scan its code to order and pay.
  - timezoneTimezone
    
    Required
    IANA time zone identifier.
    Used to resolve a location's business day for reporting and settlement.
    One of 348 values; see the schema.
- next_cursorstring
  
  Nullable
  Opaque cursor for the next page, or null on the last page. Pass it back verbatim as the cursor query parameter; its contents are not part of this contract.
400
The request could not be parsed. Malformed JSON, a bad query parameter, or a header that failed to decode, among them an API-Version later than the server speaks or not a date (api-version-unknown, with the server's own in api_version).
Distinct from 422: a 400 never reached validation, so invalid_params is absent. Retrying without changing the request will fail again, except that a request refused for its API-Version goes once the server is updated.
401
No credentials, or credentials that could not be verified — missing bearer token, malformed JWT, expired token, or a signature that failed against the issuer's JWKS.
Refresh the token and retry once. Repeated 401 after a refresh means the device needs to re-enrol.
403
Authenticated, but not permitted. The token is valid and its merchant was resolved, but the caller's role does not allow this operation, or the target belongs to a different merchant.
Cross-tenant access is reported as 403 on a resource the caller may not see, and as 404 where even confirming existence would leak information. Retrying will not help.
410
The request names an API-Version this server no longer serves (docs/decisions/0011). Nothing in it was read. api_version names the version the server speaks: the client is behind, and sends the request again once it is updated.
429
Rate limit exceeded. Honour Retry-After rather than applying your own backoff.
A fleet of tills coming back online together after an outage is the realistic cause, which is exactly when uncoordinated client-side retry turns a brief outage into a sustained one. The limit is per process, and per site for what records trade there — a request spends its site's budget, and a till's own smaller one inside it — and per (client, merchant) for everything else; no RateLimit field is sent, so this response and its Retry-After are the whole of the contract.
500
Something failed on our side. trace_id identifies the request in our tracing — quote it in a support ticket.
The body never carries internal detail: no SQL, no stack traces, no upstream error strings. Safe to retry with the same Idempotency-Key.

Request

curl -X GET 'https://api.tenvelo.com/v1/marketplace-listings?latitude=…&longitude=…'

Response

{
  "has_more": false,
  "items": [
    {
      "name": "string",
      "accepting_orders": false,
      "address": {
        "address_line_1": "12 Bridge Street",
        "address_line_2": "string",
        "address_line_3": "string",
        "administrative_district_level_1": "Somerset",
        "administrative_district_level_2": "string",
        "country": "ZZ",
        "locality": "Bristol",
        "postal_code": "BS1 4ST",
        "sublocality": "string"
      },
      "business_hours": [
        {
          "days": [
            1
          ],
          "end_minute": 1,
          "start_minute": 0
        }
      ],
      "business_name": "string",
      "collection": false,
      "coordinates": {
        "latitude": 51.5459,
        "longitude": -0.0552
      },
      "description": "string",
      "distance_meters": 0,
      "location_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b",
      "page_url": "https://example.com",
      "prep_time_minutes": 0,
      "table_ordering": false,
      "timezone": "Europe/Andorra"
    }
  ],
  "next_cursor": "string"
}