---
title: "Create or update orders by external identifier (v2)"
method: POST
path: "/v2/orders/upsert/bulk"
tags: ["Order"]
---

# Create or update orders by external identifier (v2)

`POST /v2/orders/upsert/bulk`

Create new orders or update existing ones by external identifier. Returns a `results` array — one entry per input order, in the same order as the request — each carrying a `success` or `failed` status, plus a `summary` of the counts. A hard failure on one order does not fail the batch; the rest still commit.

## Request body

- CreateOrdersInput
  - `orders` OrderInput[], required — List of orders to create
    - `externalId` string, nullable — Order unique identifier from an external system.
    - `pickupAddress` string, nullable — The full address in one line for the pickup location. Format: [Number] [Street], [second line], [city], [state], [zip code].
    - `pickupPlaceId` string, nullable — Google place id for the pickup location.
    - `pickupPhoneNumber` string, nullable — The phone number to contact at the pickup location in the form: '+15555555555'
    - `pickupBusinessName` string, nullable — Pickup business name at the origin. Limited to 80 characters.
    - `pickupFirstName` string, nullable — First name of the person to pickup from. If unknown pass 'Manager'. Limited to 80 characters.
    - `pickupLastName` string, nullable — Last name of the person to pickup from. If unknown pass 'Manager'. Limited to 80 characters.
    - `pickupInstructions` string, nullable — Any special instructions for pickup. Limited to 280 characters.
    - `pickupStoreLocationId` string, nullable — A unique identifier for store location created in Nash.
    - `pickupExternalStoreLocationId` string, nullable — The external identifier used for your store.
    - `pickupStoreLocationIds` string[], nullable — A list of store location IDs (internal or external) to consider for the Order. The optimal store will be selected and returned in the response in `pickupStoreLocationId` and/or `pickupStoreLocationExternalId`.
    - `pickupZoneIds` string[], nullable — A list of zone IDs to consider for the Order. The pickup store location will be selected later via selected delivery window.
    - `pickupBarcodes` string[], nullable — Array containing barcode values that are required to be scanned at the pickup waypoint.
    - `pickupEmail` string, nullable — The email of the contact at the pickup location.
    - `dropoffAddress` string, nullable — The full address in one line for the dropoff location. Format: [Number] [Street], [second line], [city], [state], [zip code].
    - `dropoffPlaceId` string, nullable — Google place id for the dropoff location.
    - `dropoffPhoneNumber` string, nullable — The phone number to contact at the dropoff location in the form: '+15555555555'
    - `dropoffBusinessName` string, nullable — Name of the business at the destination. Should be left empty if there is no business. Limited to 80 characters.
    - `dropoffFirstName` string, nullable — First name of the contact at the destination. Limited to 80 characters.
    - `dropoffLastName` string, nullable — Last name of the contact at the destination. Limited to 80 characters.
    - `dropoffInstructions` string, nullable — Any special instructions for dropoff. Limited to 280 characters.
    - `dropoffBarcodes` string[], nullable — Array containing barcode values/types that are required to be scanned at the dropoff waypoint.
    - `dropoffEmail` string, nullable — The email of the contact at the dropoff location.
    - `deliveryMode` string, nullable — 'now' or 'scheduled' when the delivery should be scheduled
    - `pickupStartTime` string, date-time, nullable — The earliest pickup time in UTC in the form 'YYYY-MM-DDTHH:MM:SSZ'
    - `pickupEndTime` string, date-time, nullable — The latest pickup time in UTC in the form 'YYYY-MM-DDTHH:MM:SSZ'
    - `dropoffStartTime` string, date-time, nullable — The earliest dropoff time in UTC in the form 'YYYY-MM-DDTHH:MM:SSZ'
    - `dropoffEndTime` string, date-time, nullable — The latest dropoff time in UTC in the form 'YYYY-MM-DDTHH:MM:SSZ'
    - `deliveryWindowId` string, nullable — Delivery window id if using Nash delivery windows
    - `description` string, nullable — Order description and notes. Limited to 280 characters.
    - `itemsCount` integer, nullable — The number of items in this order
    - `currency` string, nullable — Local currency
    - `valueCents` union — Order value in cents
      - integer
      - string
    - `tipAmountCents` integer, nullable — Tip paid to the driver in cents
    - `requirements` union — Package requirements.
      - PackageRequirements[]
      - string[]
    - `minimumVehicleSize` 'any' | 'bike' | 'motorbike' | 'cargobike' | 'sedan' | 'car' | 'suv' | 'pickup_truck' | 'pickup' | 'van' | 'large_van' | 'extra_large_van' | 'truck', nullable — The requested minimum vehicle size. Allowed values: ['any', 'bike', 'motorbike', 'cargobike', 'sedan', 'car', 'suv', 'pickup_truck', 'pickup', 'van', 'large_van', 'extra_large_van', 'truck']
    - `dispatchStrategyId` string, nullable — The dispatch strategy id (or option group id) to be associated with the order. Note: Best practice is to allow automations to control dispatch strategy and not send the dispatch strategy id in the request.
    - `orderMetadata` object, nullable — Key-value data to attach to this order.
    - `tags` string[], nullable — Optional order tags, they will be included in every response
    - `referenceId` string, nullable — A non-unique identifier for orders, visible to the courier if supported by the provider.
    - `pickupAddressNumber` string, nullable — The number on a house.
    - `pickupAddressSecondarynumber` string, nullable — Secondary number on an address e.g. an apartment building.
    - `pickupAddressFormattedStreet` string, nullable — The street of the address.
    - `pickupAddressCity` string, nullable — The city of the pickup address.
    - `pickupAddressCounty` string, nullable — The county associated with the pickup address.
    - `pickupAddressState` string, nullable — The state of the pickup address.
    - `pickupAddressZip` string, nullable — The zip or postal code of the pickup address.
    - `pickupAddressCountry` string, nullable — The ISO 3166-1 alpha-2 country code of the pickup address.
    - `pickupLat` number, nullable — The pickup latitude coordinate.
    - `pickupLng` number, nullable — The pickup longitude coordinate.
    - `dropoffAddressNumber` string, nullable — The number on a house.
    - `dropoffAddressSecondarynumber` string, nullable — Secondary number on an address e.g. an apartment building.
    - `dropoffAddressFormattedStreet` string, nullable — The street of the address.
    - `dropoffAddressCity` string, nullable — The city of the dropoff address.
    - `dropoffAddressCounty` string, nullable — The county associated with the dropoff address.
    - `dropoffAddressState` string, nullable — The state of the dropoff address.
    - `dropoffAddressZip` string, nullable — The zip or postal code of the dropoff address.
    - `dropoffAddressCountry` string, nullable — The ISO 3166-1 alpha-2 country code of the dropoff address.
    - `dropoffLat` number, nullable — The dropoff latitude coordinate.
    - `dropoffLng` number, nullable — The dropoff longitude coordinate.
    - `weight` union — The total weight of the package in kilograms (kg)
      - number
      - integer
      - string
    - `height` union — The total height of the package in centimeters (cm)
      - number
      - integer
    - `width` union — The total width of the package in centimeters (cm)
      - number
      - integer
    - `depth` union — The total depth of the package in centimeters (cm)
      - number
      - integer
    - `items` ItemInput[], nullable — Lists of items in the delivery
      - `id` string, nullable — The merchant ID of the item
      - `description` string, nullable — The description of the item
      - `count` integer, nullable — The quantity of the item
      - `dimensions` Dimensions
        - `height` union — The height of the item in centimeters (cm)
          - number
          - integer
        - `width` union — The width of the item in centimeters (cm)
          - number
          - integer
        - `depth` union — The depth of the item in centimeters (cm)
          - number
          - integer
      - `weight` union — The weight of the item in kilograms (kg)
        - number
        - integer
      - `valueCents` integer, nullable — The value of the item in cents
      - `requirements` string[], nullable — List of requirements for this item
      - `category` string, nullable — The category of the item
      - `barcode` string, nullable — Barcode value for this item.
      - `metadata` object, nullable — Key-value data to attach to this item.
      - `subItems` SubItemInput[], nullable — The nested sub-items
        - `id` string, nullable — The merchant ID of the item
        - `description` string, nullable — The description of the item
        - `count` integer, nullable — The quantity of the item
        - `dimensions` Dimensions
          - `height` union — The height of the item in centimeters (cm)
            - number
            - integer
          - `width` union — The width of the item in centimeters (cm)
            - number
            - integer
          - `depth` union — The depth of the item in centimeters (cm)
            - number
            - integer
        - `weight` union — The weight of the item in kilograms (kg)
          - number
          - integer
        - `valueCents` integer, nullable — The value of the item in cents
        - `requirements` string[], nullable — List of requirements for this item
        - `category` string, nullable — The category of the item
        - `barcode` string, nullable — Barcode value for this item.
        - `metadata` object, nullable — Key-value data to attach to this item.
        - `sku` string, nullable — The SKU of the sub-item
        - `substitution` SubstitutionObject
          - `preference` string, nullable — Substitution preference: refund or substitute
          - `source` string, nullable — Source of substitution, e.g., merchant, customer
          - `substituteItems` SubstituteItemObject[], nullable — List of substitute items
            - `id` string, nullable — The ID of the substitute item
            - `sku` string, nullable — The SKU of the substitute item
            - `quantity` integer, nullable — The quantity of the substitute item
        - `subItems` SubItemInput[], nullable — The nested sub-items
    - `optimizationParameters` OptimizationParameters
      - `pickupDoorstepTimeSeconds` integer, nullable — Length of time (in seconds) it take the courier at the pickup location's doorstep.
      - `dropoffDoorstepTimeSeconds` integer, nullable — Length of time (in seconds) it take the courier at the dropoff location's doorstep.
      - `costsByMetric` object, nullable — The cost metric to use for the order
      - `clusterLabel` string, nullable — The cluster label for the order
      - `mxLabel` string, nullable — The mutually exclusive label for the order
      - `assignmentPriority` integer, nullable — The assignment priority for the order
      - `sequencePriority` integer, nullable — The sequence priority for the order
      - `sequenceGroup` string, nullable — The sequence group for the order
    - `pickupPayment` PickupPayment
      - `barcode` PickupPaymentBarcode
        - `type` string, nullable — The barcode symbology (e.g. CODE128, QR).
        - `value` string, nullable — The barcode value the courier should present at pickup.
      - `providerCard` boolean, nullable — If true, the courier pays for the order at pickup using a provider-issued card.
    - `reapplyAutomations` boolean, nullable — If set to true, the order will be re-evaluated with automations.
    - `maxDeliveryFeeCents` integer, nullable — The maximum delivery fee for the order in cents. This will override the dispatch strategy max delivery fee if both are set.

## Response `200`

OK

- BulkUpsertOrdersResponse — Response for `POST /v2/orders/upsert/bulk`. The orders specialisation of the generic `BulkUpsertResponse` envelope: `data` on each result is a full `BulkUpsertOrderData` (the upserted order). The `{results, summary}` shape and the `success`/`failed` per-row status come from the generic base in `server.serializers.bulk`.
  - `results` BulkUpsertResultBulkUpsertOrderData[], required — One entry per input row, in the same order as the request.
    - `externalId` string, nullable — The row's external identifier, echoed back to correlate results with the request.
    - `status` 'success' | 'failed', required — Per-row outcome of a bulk upsert. ``success`` means the row was upserted (created or updated). ``failed`` is reserved for hard errors (a precondition violation, lock contention, a missing required field, an unexpected error). Soft/validation issues that still persist the row are *not* failures — surface those on the returned object, not here.
    - `id` string, nullable — The upserted object's Nash id. Null when the row failed.
    - `data` BulkUpsertOrderData — The full upserted order returned in a successful v2 bulk-upsert result. Subclasses `OrderOutputExample` only to enable serialising directly from the `Order` ORM instance via `model_validate(order)`, mirroring `nash.schemas.delivery_window.DeliveryWindowResponse`: - `from_attributes` — read fields straight off the ORM object. - `coerce_numbers_to_str` — several columns are stored as `int` on the ORM but declared as `str` on the response shape (e.g. `items_count`, `value_cents`); the legacy GraphQL path stringified these via Graphene resolvers. The base schema itself is untouched, so v1's documented shape is unchanged.
      - `id` string, required — The id of the order
      - `createdAt` string, date-time, required — The date and time when the order was created
      - `externalId` string, nullable — The external id of the order
      - `externalGroupId` string, nullable — The external group id of the order
      - `referenceId` string, nullable — A non-unique identifier for orders, visible to the courier if supported by the provider.
      - `portalUrl` string, required — The URL of the order in the Nash portal
      - `publicTrackingUrl` string, required — The URL of the order in the public tracking system
      - `status` string, required — The status of the order
      - `tags` string[], nullable, required — The tags of the order
      - `orderMetadata` object, nullable — Key-value data to attach to Nash Jobs.
      - `pickupAddress` string, nullable — The pickup address of the order
      - `pickupPlaceId` string, nullable — Google place id for the pickup location.
      - `pickupAddressNumber` string, nullable — The number on a house.
      - `pickupAddressSecondarynumber` string, nullable — Secondary number on an address e.g. an apartment building.
      - `pickupAddressFormattedStreet` string, nullable — The street of the address.
      - `pickupAddressCity` string, nullable — The city of the pickup address.
      - `pickupAddressCounty` string, nullable — The county associated with the pickup address.
      - `pickupAddressState` string, nullable — The state of the pickup address.
      - `pickupAddressZip` string, nullable — The zip or postal code of the pickup address.
      - `pickupAddressCountry` string, nullable — The ISO 3166-1 alpha-2 country code of the pickup address.
      - `pickupLat` number, nullable — The pickup latitude coordinate.
      - `pickupLng` number, nullable — The pickup longitude coordinate.
      - `pickupPhoneNumber` string, nullable — The phone number to contact at the pickup location in the form: '+15555555555'
      - `pickupFirstName` string, nullable — First name of the person to pickup from. If unknown pass 'Manager'. Limited to 80 characters.
      - `pickupLastName` string, nullable — Last name of the person to pickup from. If unknown pass 'Manager'. Limited to 80 characters.
      - `pickupBusinessName` string, nullable — Pickup business name at the origin.
      - `pickupInstructions` string, nullable — Any special instructions for pickup.
      - `pickupStoreLocationId` string, nullable — A unique identifier for store location created in Nash.
      - `pickupExternalStoreLocationId` string, nullable — The external identifier used for your store.
      - `pickupZoneIds` string[], nullable — A list of zone IDs to consider for the Order. The pickup store location will be selected later via selected delivery window.
      - `pickupBarcodes` string[], nullable — Array containing barcode values that are required to be scanned at the pickup waypoint.
      - `pickupPayment` PickupPayment
        - `barcode` PickupPaymentBarcode
          - `type` string, nullable — The barcode symbology (e.g. CODE128, QR).
          - `value` string, nullable — The barcode value the courier should present at pickup.
        - `providerCard` boolean, nullable — If true, the courier pays for the order at pickup using a provider-issued card.
      - `dropoffAddress` string, nullable — The dropoff address of the order
      - `dropoffPlaceId` string, nullable — Google place id for the dropoff location.
      - `dropoffAddressNumber` string, nullable — The number on a house.
      - `dropoffAddressSecondarynumber` string, nullable — Secondary number on an address e.g. an apartment building.
      - `dropoffAddressFormattedStreet` string, nullable — The street of the address.
      - `dropoffAddressCity` string, nullable — The city of the dropoff address.
      - `dropoffAddressCounty` string, nullable — The county associated with the dropoff address.
      - `dropoffAddressState` string, nullable — The state of the dropoff address.
      - `dropoffAddressZip` string, nullable — The zip or postal code of the dropoff address.
      - `dropoffAddressCountry` string, nullable — The ISO 3166-1 alpha-2 country code of the dropoff address.
      - `dropoffLat` number, nullable — The dropoff latitude coordinate.
      - `dropoffLng` number, nullable — The dropoff longitude coordinate.
      - `dropoffPhoneNumber` string, nullable — The phone number to contact at the dropoff location in the form: '+15555555555'
      - `dropoffFirstName` string, nullable — First name of the contact at the destination.
      - `dropoffLastName` string, nullable — Last name of the contact at the destination.
      - `dropoffBusinessName` string, nullable — Dropoff business name at the destination.
      - `dropoffInstructions` string, nullable — Any special instructions for dropoff.
      - `dropoffStoreLocationId` string, nullable — A unique identifier for store location created in Nash.
      - `dropoffBarcodes` string[], nullable — Array containing barcode values that are required to be scanned at the dropoff waypoint.
      - `deliveryMode` string, nullable — The delivery mode of the order
      - `pickupStartTime` string, nullable — The start time of the pickup window.
      - `pickupEndTime` string, nullable — The end time of the pickup window.
      - `dropoffStartTime` string, nullable — The start time of the dropoff window.
      - `dropoffEndTime` string, nullable — The end time of the dropoff window.
      - `description` string, nullable — The description of the order
      - `itemsCount` string, nullable — The number of items in the order
      - `requirements` string[], nullable — The requirements of the order
      - `minimumVehicleSize` 'any' | 'bike' | 'motorbike' | 'cargobike' | 'sedan' | 'car' | 'suv' | 'pickup_truck' | 'pickup' | 'van' | 'large_van' | 'extra_large_van' | 'truck', nullable — The requested minimum vehicle size. Allowed values: ['any', 'bike', 'motorbike', 'cargobike', 'sedan', 'car', 'suv', 'pickup_truck', 'pickup', 'van', 'large_van', 'extra_large_van', 'truck']
      - `currency` string, nullable — The currency of the order
      - `valueCents` string, nullable — The value of the order in cents
      - `tipAmountCents` string, nullable — The tip amount of the order in cents
      - `width` string, nullable — The width of the order in cm
      - `depth` string, nullable — The depth of the order in cm
      - `height` string, nullable — The height of the order in cm
      - `volume` string, nullable — The volume of the order in cm^3
      - `weight` string, nullable — The weight of the order in kg
      - `items` ItemInput[], nullable — The items of the order
        - `id` string, nullable — The merchant ID of the item
        - `description` string, nullable — The description of the item
        - `count` integer, nullable — The quantity of the item
        - `dimensions` Dimensions
          - `height` union — The height of the item in centimeters (cm)
            - number
            - integer
          - `width` union — The width of the item in centimeters (cm)
            - number
            - integer
          - `depth` union — The depth of the item in centimeters (cm)
            - number
            - integer
        - `weight` union — The weight of the item in kilograms (kg)
          - number
          - integer
        - `valueCents` integer, nullable — The value of the item in cents
        - `requirements` string[], nullable — List of requirements for this item
        - `category` string, nullable — The category of the item
        - `barcode` string, nullable — Barcode value for this item.
        - `metadata` object, nullable — Key-value data to attach to this item.
        - `subItems` SubItemInput[], nullable — The nested sub-items
          - `id` string, nullable — The merchant ID of the item
          - `description` string, nullable — The description of the item
          - `count` integer, nullable — The quantity of the item
          - `dimensions` Dimensions
            - `height` union — The height of the item in centimeters (cm)
              - …
            - `width` union — The width of the item in centimeters (cm)
              - …
            - `depth` union — The depth of the item in centimeters (cm)
              - …
          - `weight` union — The weight of the item in kilograms (kg)
            - number
            - integer
          - `valueCents` integer, nullable — The value of the item in cents
          - `requirements` string[], nullable — List of requirements for this item
          - `category` string, nullable — The category of the item
          - `barcode` string, nullable — Barcode value for this item.
          - `metadata` object, nullable — Key-value data to attach to this item.
          - `sku` string, nullable — The SKU of the sub-item
          - `substitution` SubstitutionObject
            - `preference` string, nullable — Substitution preference: refund or substitute
            - `source` string, nullable — Source of substitution, e.g., merchant, customer
            - `substituteItems` SubstituteItemObject[], nullable — List of substitute items
              - …
          - `subItems` SubItemInput[], nullable — The nested sub-items
      - `dispatchStrategyId` string, nullable — The dispatch strategy id (or option group id) to be associated with the order. Note: It is the best practice to allow automations to control dispatch strategy and not send the dispatch strategy id in the request.
      - `maxDeliveryFeeCents` string, nullable — The max delivery fee of the order in cents
      - `documents` OrderDocumentOutput[], nullable — The documents of the order
        - `createdAt` string, date-time, required — The date and time when the document was created
        - `id` string, required — The id of the document
        - `type` 'shipping_label' | 'pickup_label' | 'manifest' | 'packing_slip_label' | 'proof_of_delivery', required
        - `contentType` string, required — The content type of the document
        - `url` string, nullable — The URL of the document
        - `data` string, nullable — The data of the document
      - `validationErrors` object, nullable — The validation errors of the order
      - `quotes` QuoteSerializer[], nullable — The quotes of the order
        - `id` string, required — Quote ID
        - `type` string, nullable — Quote type
        - `providerId` string, required — Provider ID
        - `providerName` string, required — Provider name
        - `providerLogo` string, nullable — Provider logo
        - `providerIsInternal` boolean, nullable — Is the provider internal
        - `createdTime` string, required — Created time
        - `expireTime` string, nullable — Expire time
        - `priceCents` integer, required — Price in cents
        - `taxAmountCents` integer, nullable — Tax amount in cents
        - `tollFeeCents` integer, nullable — Toll fee in cents
        - `nashFeeCents` integer, nullable — Nash fee in cents
        - `insuranceFeeCents` integer, nullable — Insurance fee in cents
        - `currency` string, nullable — Currency
        - `pickupWindow` string, nullable — Pickup window
        - `dropoffEta` string, nullable — Dropoff ETA
        - `tags` string[], nullable — Tags
        - `costSplitCustomerCents` integer, nullable — Cost split customer in cents
        - `costSplitBusinessCents` integer, nullable — Cost split business in cents
        - `totalPriceBreakdown` object, nullable — Total price breakdown
        - `totalPriceCents` integer, nullable — Total price in cents
        - `rank` integer, nullable — Quote rank for preferred provider ordering
        - `price` number, nullable — Price
        - `isSuccessful` boolean, nullable — Is successful
        - `errorMessage` string, nullable — Error message
      - `failedQuotes` string[], nullable — The failed quotes of the order
    - `errors` BulkUpsertError[], nullable — Failure details. Populated only when status is `failed`, null otherwise.
      - `code` string, required — Machine-readable error code (the API contract for client-side translation).
      - `message` string, required — Human-readable description of the failure.
  - `summary` BulkUpsertSummary, required — Counts of each outcome across the batch.
    - `success` integer, required — Number of rows upserted successfully.
    - `failed` integer, required — Number of rows that failed.

## Other responses

- `422` — Unprocessable Content

---

[API](https://skmtc.net/usenash/apis/nash-api.md) · [All operations](https://skmtc.net/usenash/apis/nash-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/usenash/nash-api/revisions/09a23a95889b/schema)