Nash Zones API

openapi: 3.1.0
info:
  title: Nash AI Functions Zones API
  version: 1.0.0
  description: LLM-backed domain tools
servers:
- url: https://api.sandbox.usenash.com
  description: Sandbox API
- url: https://api.sandbox.ap-southeast-2.usenash.com
  description: Sandbox API (Australia)
- url: https://api.usenash.com
  description: Production API
- url: https://api.ap-southeast-2.usenash.com
  description: Production API (Australia)
tags:
- name: Zones
  description: Zones
  x-nash-topic: config
paths:
  /v1/zone-restrictions:
    get:
      tags:
      - Zones
      summary: Get zone restrictions
      description: List all zone restrictions for the organization. Zone restrictions define rules that control delivery behavior within specific zones.
      operationId: get_zone_restrictions_v1_zone_restrictions_get
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListZoneRestrictionsResponse'
        '422':
          description: Unprocessable Content
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NashValidationError'
    post:
      tags:
      - Zones
      summary: Create zone restriction
      description: Create a zone restriction rule that controls delivery behavior within a specific zone, such as provider restrictions or time-based rules.
      operationId: create_zone_restriction_v1_zone_restrictions_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateZoneRestrictionInputSerializer'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZoneRestrictionResponse'
        '422':
          description: Unprocessable Content
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NashValidationError'
  /v1/zone-restrictions/upsert:
    post:
      tags:
      - Zones
      summary: Upsert multiple zone restrictions
      description: Create or update multiple zone restrictions in a single request. Existing restrictions are matched by ID for updates.
      operationId: upsert_zone_restrictions_v1_zone_restrictions_upsert_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertZoneRestrictionsInputSerializer'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListZoneRestrictionsResponse'
        '422':
          description: Unprocessable Content
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NashValidationError'
  /v1/zone-restrictions/{id}:
    patch:
      tags:
      - Zones
      summary: Update zone restriction
      description: Update an existing zone restriction's rules or configuration. Only provided fields are updated.
      operationId: update_zone_restriction_v1_zone_restrictions__string_id__patch
      parameters:
      - name: id
        in: path
        description: The ID of the zone restriction.
        required: true
        schema:
          title: Id
          type: string
          description: The ID of the zone restriction.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateZoneRestrictionInputSerializer'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZoneRestrictionResponse'
        '422':
          description: Unprocessable Content
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NashValidationError'
  /v1/zones:
    get:
      tags:
      - Zones
      summary: Get zones
      description: List zones for the organization with pagination. Use size and offset parameters to paginate. Optionally include deleted zones with is_deleted.
      operationId: get_zones_list_v1_zones_get
      parameters:
      - name: size
        in: query
        description: The size of the zones to return.
        required: false
        schema:
          title: Size
          type: integer
          description: The size of the zones to return.
          default: 10
      - name: offset
        in: query
        description: The offset of the zones to return.
        required: false
        schema:
          title: Offset
          type: integer
          description: The offset of the zones to return.
          default: 0
      - name: isDeleted
        in: query
        description: Whether to return deleted zones.
        required: false
        schema:
          title: Isdeleted
          type: boolean
          description: Whether to return deleted zones.
          default: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListZonesResponse'
        '422':
          description: Unprocessable Content
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NashValidationError'
    post:
      tags:
      - Zones
      summary: Create a zone
      description: Create a geographic zone defined by a polygon boundary. Zones are used to define delivery areas for store locations and apply zone-based restrictions.
      operationId: create_zone_v1_zones_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateZoneInputSerializer'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZoneResponse'
        '422':
          description: Unprocessable Content
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NashValidationError'
  /v1/zones/coverage:
    get:
      tags:
      - Zones
      summary: Get zones that cover specified location (latitude & longitude, city_zipcode)
      description: Find zones whose polygon boundaries contain a given geographic point. Provide latitude/longitude, city_zipcode, or zipcode to find matching zones.
      operationId: get_zones_coverage_v1_zones_coverage_get
      parameters:
      - name: latitude
        in: query
        description: The latitude of the location to check coverage for. If used, must specify longitude
        required: false
        schema:
          title: Latitude
          anyOf:
          - type: string
          - type: 'null'
          description: The latitude of the location to check coverage for. If used, must specify longitude
          default: null
          example: '0.00'
        example: '0.00'
      - name: longitude
        in: query
        description: The longitude of the location to check coverage for. If used, must specify latitude
        required: false
        schema:
          title: Longitude
          anyOf:
          - type: string
          - type: 'null'
          description: The longitude of the location to check coverage for. If used, must specify latitude
          default: null
          example: '0.00'
        example: '0.00'
      - name: cityZipcode
        in: query
        description: The city_zipcode pair to check coverage for. The location must have coverage set up using the `City & Zip Code` unique field, not the separate `City` or `Zip Code` fields.
        required: false
        schema:
          title: Cityzipcode
          anyOf:
          - type: string
          - type: 'null'
          description: The city_zipcode pair to check coverage for. The location must have coverage set up using the `City & Zip Code` unique field, not the separate `City` or `Zip Code` fields.
          default: null
          example: sanfrancisco_94114
        example: sanfrancisco_94114
      - name: zipcode
        in: query
        description: The zipcode to check coverage for.
        required: false
        schema:
          title: Zipcode
          anyOf:
          - type: string
          - type: 'null'
          description: The zipcode to check coverage for.
          default: null
          example: '94114'
        example: '94114'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListZonesResponse'
        '422':
          description: Unprocessable Content
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NashValidationError'
  /v1/zones/external_identifier/{externalIdentifier}:
    get:
      tags:
      - Zones
      summary: Get zone by external identifier
      description: Retrieve a zone using your external identifier instead of the Nash zone ID.
      operationId: get_zone_by_external_id_v1_zones_external_identifier__string_externalIdentifier__get
      parameters:
      - name: externalIdentifier
        in: path
        required: true
        schema:
          title: Externalidentifier
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZoneResponse'
        '422':
          description: Unprocessable Content
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NashValidationError'
  /v1/zones/query:
    post:
      tags:
      - Zones
      summary: Query zones
      description: Return full zone details for many zones in a single call. Filter by `ids` and/or `externalIds` (combined with OR); omit both to page through all of the organization's zones. Results come back under `data` with pagination under `meta`; each `data` item matches the shape of `GET /v1/zones/<id>`.
      operationId: zones_v1_query_zones_route_query_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ZonesQueryRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZonesQueryResponse'
        '422':
          description: Unprocessable Content
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NashValidationError'
  /v1/zones/upsert:
    post:
      tags:
      - Zones
      summary: Upsert multiple zones
      description: Create or update multiple zones in a single request. Existing zones are matched by ID or external identifier for updates.
      operationId: upsert_zones_v1_zones_upsert_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertZonesInputSerializer'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListZonesResponse'
        '422':
          description: Unprocessable Content
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NashValidationError'
  /v1/zones/{id}:
    get:
      tags:
      - Zones
      summary: Get zone
      description: Retrieve a single zone by ID, including its polygon boundary and associated store locations.
      operationId: get_zone_v1_zones__string_id__get
      parameters:
      - name: id
        in: path
        required: true
        schema:
          title: Id
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZoneResponse'
        '422':
          description: Unprocessable Content
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NashValidationError'
    delete:
      tags:
      - Zones
      summary: Delete a zone
      description: Delete a zone by ID. Removes the zone and its store location associations.
      operationId: delete_zone_v1_zones__string_id__delete
      parameters:
      - name: id
        in: path
        required: true
        schema:
          title: Id
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZoneResponse'
        '422':
          description: Unprocessable Content
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NashValidationError'
    patch:
      tags:
      - Zones
      summary: Update a zone
      description: Update an existing zone's name, polygon boundary, or associated store locations. Only provided fields are updated.
      operationId: update_zone_v1_zones__string_id__patch
      parameters:
      - name: id
        in: path
        required: true
        schema:
          title: Id
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateZoneInputSerializer'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZoneResponse'
        '422':
          description: Unprocessable Content
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NashValidationError'
components:
  schemas:
    CreateZoneRestrictionInputSerializer:
      title: CreateZoneRestrictionInputSerializer
      required:
      - name
      type: object
      properties:
        externalId:
          title: Externalid
          anyOf:
          - type: string
          - type: 'null'
          description: The external ID of the zone restriction.
          default: null
        name:
          title: Name
          type: string
          description: The name of the zone restriction.
        isActive:
          title: Isactive
          anyOf:
          - type: boolean
          - type: 'null'
          description: Whether the zone restriction is active.
          default: null
        restrictionMetadata:
          title: Restrictionmetadata
          anyOf:
          - type: object
            additionalProperties: true
          - type: 'null'
          description: The metadata of the zone restriction.
          default: null
          example:
            key: value
      description: Expected payload for the create zone restriction endpoint.
    NashErrorDetails:
      title: NashErrorDetails
      required:
      - code
      - message
      type: object
      properties:
        code:
          title: Code
          type: string
        message:
          title: Message
          type: string
        details:
          title: Details
          anyOf:
          - type: object
            additionalProperties: true
          - type: 'null'
          default: null
    ListZoneRestrictionsResponse:
      title: ListZoneRestrictionsResponse
      required:
      - zoneRestrictions
      type: object
      properties:
        zoneRestrictions:
          title: Zonerestrictions
          type: array
          items:
            $ref: '#/components/schemas/ZoneRestrictionResponse'
      description: Response for list zone restrictions.
    ListZonesResponse:
      title: ListZonesResponse
      required:
      - zones
      type: object
      properties:
        zones:
          title: Zones
          type: array
          items:
            $ref: '#/components/schemas/ZoneResponse'
      description: Response for list zones.
    ParsedAddressInputSerializer:
      title: ParsedAddressInputSerializer
      required:
      - street
      - city
      - country
      type: object
      properties:
        number:
          title: Number
          anyOf:
          - type: string
          - type: 'null'
          description: The number of the address.
          default: null
          example: '1600'
        secondaryNumber:
          title: Secondarynumber
          anyOf:
          - type: string
          - type: 'null'
          description: The secondary number of the address.
          default: null
          example: null
        street:
          title: Street
          type: string
          description: 'The street of the address. If your geocoding service does not split numbers from street names, you can pass the street name with the number in this field. Example: 1600 Pennsylvania Avenue NW.'
          example: Pennsylvania Avenue NW
        county:
          title: County
          anyOf:
          - type: string
          - type: 'null'
          description: The county of the address.
          default: null
          example: Washington
        city:
          title: City
          type: string
          description: The city of the address.
          example: Washington
        state:
          title: State
          anyOf:
          - type: string
          - type: 'null'
          description: The state of the address.
          default: null
          example: DC
        postalCode:
          title: Postalcode
          anyOf:
          - type: string
          - type: 'null'
          description: The postal code of the address.
          default: null
          example: '20500'
        country:
          title: Country
          type: string
          description: The country of the address.
          example: US
        latitude:
          title: Latitude
          anyOf:
          - type: number
          - type: 'null'
          description: The latitude of the address.
          default: null
          example: 38.8948949
        longitude:
          title: Longitude
          anyOf:
          - type: number
          - type: 'null'
          description: The longitude of the address.
          default: null
          example: -77.0371581
      description: Parsed address input serializer for creating a job.
    StoreLocationResponse:
      title: StoreLocationResponse
      required:
      - id
      - name
      - phoneNumber
      - location
      - zoneIds
      - zoneAssociations
      - tags
      - integrationMetadata
      type: object
      properties:
        externalId:
          title: Externalid
          anyOf:
          - type: string
          - type: 'null'
          description: Store location unique identifier from an external system.
          default: null
          example: '40123'
        operatingHours:
          title: Operatinghours
          anyOf:
          - type: object
            additionalProperties: true
          - type: 'null'
          description: '[Integration Specific]: An object with keys that correspond to days of week (monday, tuesday, etc) and their corresponding operating hours / delivery windows.'
          default: null
          example:
            friday:
              active: true
              shifts:
              - - '10:00'
                - '19:00'
            monday:
              active: true
              shifts:
              - - '10:00'
                - '19:00'
            saturday:
              active: true
              shifts:
              - - '10:00'
                - '19:00'
            sunday:
              active: true
              shifts:
              - - '11:00'
                - '18:00'
            thursday:
              active: true
              shifts:
              - - '10:00'
                - '19:00'
            tuesday:
              active: true
              shifts:
              - - '10:00'
                - '19:00'
            wednesday:
              active: true
              shifts:
              - - '10:00'
                - '19:00'
        prepTimeMinutes:
          title: Preptimeminutes
          anyOf:
          - type: integer
          - type: 'null'
          description: '[Integration Specific]: the preparation time to apply for orders, if relying on Nash to compute the delivery windows. This only applies to specific integrations.'
          default: null
        blackoutDates:
          title: Blackoutdates
          anyOf:
          - type: array
            items:
              type: string
          - type: 'null'
          description: The blackout dates of the store location.
          default: null
          example:
          - '2024-01-01'
          - '2024-01-02'
        firstName:
          title: Firstname
          anyOf:
          - type: string
          - type: 'null'
          description: First name of the person at the store location. If unknown, pass 'Manager'. Limited to 80 characters.
          default: null
          example: Taylor
        lastName:
          title: Lastname
          anyOf:
          - type: string
          - type: 'null'
          description: Last name of the person at the store location. If unknown, pass 'Manager'. Limited to 80 characters.
          default: null
          example: Swift
        email:
          title: Email
          anyOf:
          - type: string
          - type: 'null'
          description: The email of the person at the store location.
          default: null
          example: taylor@swift.com
        pickupInstructions:
          title: Pickupinstructions
          anyOf:
          - type: string
          - type: 'null'
          description: 'The pickup instructions of the store location. Limited to 280 characters. Nash Recommended Input: Order [insert order number] for [insert customer name] from [business name]'
          default: null
          example: Once you arrive at the store, please click above to let us know you are here. Then, go ahead and find a sales associate inside - they'll be happy to help you!
        id:
          title: Id
          type: string
          description: The ID of the store location.
          example: stl_01234567890123456789
        name:
          title: Name
          type: string
          description: The name of the store location.
          example: White House
        phoneNumber:
          title: Phonenumber
          type: string
          description: The phone number of the person at the store location.
          example: '+1234567890'
        location:
          $ref: '#/components/schemas/ParsedAddressInputSerializer'
          description: The location of the store location.
        zoneIds:
          title: Zoneids
          anyOf:
          - type: array
            items:
              type: string
          - type: 'null'
          description: The zone ids of the store location.
          example:
          - zone_01234567890123456789
          - zone_01234567890123456789
        zoneAssociations:
          title: Zoneassociations
          anyOf:
          - type: array
            items:
              type: object
              additionalProperties: true
          - type: 'null'
          description: The zone associations of the store location.
          example:
          - end_date: '2025-01-01'
            start_date: '2024-01-01'
            store_location_id: stl_01234567890123456789
            zone_id: zone_01234567890123456789
        tags:
          title: Tags
          anyOf:
          - type: array
            items:
              type: string
          - type: 'null'
          description: The tags of the store location.
          example: '[''service:rapid'', ''franchise_location'']'
        integrationMetadata:
          title: Integrationmetadata
          anyOf:
          - type: object
            additionalProperties: true
          - type: 'null'
          description: The integration metadata of the store location.
          example:
            integration_name: ABC
      description: Response for store location.
    ZoneCoverageAreaRead:
      title: ZoneCoverageAreaRead
      required:
      - id
      type: object
      properties:
        id:
          title: Id
          type: string
          description: Nash coverage area id.
        cityZipcodes:
          title: Cityzipcodes
          anyOf:
          - type: array
            items:
              type: string
          - type: 'null'
          description: City and zip code pairs covered.
          default: null
        zipCodes:
          title: Zipcodes
          anyOf:
          - type: array
            items:
              type: string
          - type: 'null'
          description: Zip codes covered.
          default: null
        cities:
          title: Cities
          anyOf:
          - type: array
            items:
              type: string
          - type: 'null'
          description: Cities covered.
          default: null
        states:
          title: States
          anyOf:
          - type: array
            items:
              type: string
          - type: 'null'
          description: States or regions covered.
          default: null
        countries:
          title: Countries
          anyOf:
          - type: array
            items:
              type: string
          - type: 'null'
          description: Two-letter ISO country codes covered.
          default: null
        polygons:
          title: Polygons
          type: array
          items:
            $ref: '#/components/schemas/ZonePolygonRead'
          description: Geometry boundaries attached to this coverage area.
    UpsertZoneInputSerializer:
      title: UpsertZoneInputSerializer
      type: object
      properties:
        name:
          title: Name
          anyOf:
          - type: string
          - type: 'null'
          description: The name of the zone.
          default: null
          example: Zone 1
        coverageAreaId:
          title: Coverageareaid
          anyOf:
          - type: string
          - type: 'null'
          description: The coverage area id to associate with the zone.
          default: null
        polygon:
          title: Polygon
          anyOf:
          - type: array
            items:
              type: array
              items:
                type: number
          - type: 'null'
          description: The zone boundary, as a single closed ring of [latitude, longitude] coordinate pairs. The first and last point must be identical to close the ring. Setting this replaces the polygon on the zone's coverage area (creating a coverage area if the zone has none).
          default: null
          example:
          - - 37.7749
            - -122.4194
          - - 37.8049
            - -122.4194
          - - 37.8049
            - -122.3894
          - - 37.7749
            - -122.3894
          - - 37.7749
            - -122.4194
        storeLocationIds:
          title: Storelocationids
          anyOf:
          - type: array
            items:
              type: string
          - type: 'null'
          description: The store location ids to associate with the zone.
          default: null
        storeLocationAssociations:
          title: Storelocationassociations
          anyOf:
          - type: array
            items:
              type: object
              additionalProperties: true
          - type: 'null'
          description: The store location associations to associate with the zone.
          default: null
          example:
          - end_date: '2025-01-01'
            start_date: '2024-01-01'
            store_location_id: stl_01234567890123456789
        tags:
          title: Tags
          anyOf:
          - type: array
            items:
              type: string
          - type: 'null'
          description: Free form tags specific to the location.
          default: null
          example: '[''service:rapid'', ''service:express'', ''franchise_location'']'
        zoneMetadata:
          title: Zonemetadata
          anyOf:
          - type: object
            additionalProperties: true
          - type: 'null'
          description: The metadata of the zone.
          default: null
          example:
            key: value
        externalId:
          title: Externalid
          anyOf:
          - type: string
          - type: 'null'
          description: The external id of the zone.
          default: null
          example: zone_01234567890123456789
        cityZipcodes:
          title: Cityzipcodes
          anyOf:
          - type: array
            items:
              type: string
          - type: 'null'
          description: The city-zipcode pairs to associate with the zone.
          default: null
          example:
          - Melbourne_3000
          - Sydney_2000
      description: Expected input payload for upserting a zone by external id.
    UpdateZoneInputSerializer:
      title: UpdateZoneInputSerializer
      type: object
      properties:
        name:
          title: Name
          anyOf:
          - type: string
          - type: 'null'
          description: The name of the zone.
          default: null
          example: Zone 1
        coverageAreaId:
          title: Coverageareaid
          anyOf:
          - type: string
          - type: 'null'
          description: The coverage area id to associate with the zone.
          default: null
        polygon:
          title: Polygon
          anyOf:
          - type: array
            items:
              type: array
              items:
                type: number
          - type: 'null'
          description: The zone boundary, as a single closed ring of [latitude, longitude] coordinate pairs. The first and last point must be identical to close the ring. Setting this replaces the polygon on the zone's coverage area (creating a coverage area if the zone has none).
          default: null
          example:
          - - 37.7749
            - -122.4194
          - - 37.8049
            - -122.4194
          - - 37.8049
            - -122.3894
          - - 37.7749
            - -122.3894
          - - 37.7749
            - -122.4194
        storeLocationIds:
          title: Storelocationids
          anyOf:
          - type: array
            items:
              type: string
          - type: 'null'
          description: The store location ids to associate with the zone.
          default: null
        storeLocationAssociations:
          title: Storelocationassociations
          anyOf:
          - type: array
            items:
              type: object
              additionalProperties: true
          - type: 'null'
          description: The store location associations to associate with the zone.
          default: null
          example:
          - end_date: '2025-01-01'
            start_date: '2024-01-01'
            store_location_id: stl_01234567890123456789
        tags:
          title: Tags
          anyOf:
          - type: array
            items:
              type: string
          - type: 'null'
          description: Free form tags specific to the location.
          default: null
          example: '[''service:rapid'', ''service:express'', ''franchise_location'']'
        zoneMetadata:
          title: Zonemetadata
          anyOf:
          - type: object
            additionalProperties: true
          - type: 'null'
          descrip

# --- truncated at 32 KB (53 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/nash/refs/heads/main/openapi/nash-zones-api-openapi.yml