---
title: "Create Orders"
method: POST
path: "/v1/orders"
tags: ["Order"]
---

# Create Orders

`POST /v1/orders`

## Request

- Base URL: `https://api.sandbox.usenash.com`
- URL: `https://api.sandbox.usenash.com/v1/orders`
- Auth: none declared

Create multiple pre-dispatch orders in a single request. Each order is created independently with its own pickup and dropoff details.

## 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.
    - `dropoffStoreLocationId` string, nullable: A unique identifier for store location created in Nash.
    - `dropoffExternalStoreLocationId` string, nullable: The external identifier used for your store. Fills the dropoff address from that store; to link the order to the store, send dropoffStoreLocationId instead.
    - `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
    - `dueAmountCents` integer, nullable: Cash the driver must collect from the recipient on delivery, in cents. Set it to valueCents for a cash-on-delivery order and to 0 for a prepaid one; must not exceed valueCents. Omit when not applicable — providers then treat the order as prepaid. Forwarded to providers that support collect-on-delivery (currently Dash).
    - `requirements` union: Package requirements.
      - PackageRequirements[]
      - string[]
    - `minimumVehicleSize` 'any' | 'bike' | 'motorbike' | 'cargobike' | 'cargo_bike' | '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', 'cargo_bike', '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
    - `weightUnit` string, nullable: Unit for weight: 'kg' or 'lbs'. Defaults to 'kg'. Weight is always stored in kg; a weight provided in 'lbs' is converted on ingest.
    - `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
    - `volume` union: The total volume of the package in cubic centimeters (cm^3)
      - number
      - integer
    - `lengthUnit` string, nullable: Unit for height/width/depth and volume: 'cm' or 'in'. Defaults to 'cm'. Dimensions are always stored in cm (cm^3 for volume); values provided in 'in' (cubic inches for volume) are converted on ingest.
    - `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.
      - `volume` union: The volume of the item in cubic centimeters (cm^3)
        - number
        - integer
      - `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: What to do when this item can't be picked: `refund`, `substitute`, or `contact` (the shopper contacts the customer to agree a substitution).
          - `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
      - `pickupOnly` boolean, nullable: Whether optimization creates a pickup-only order and omits the dropoff stop
      - `alternativeDropoffTimeWindows` AlternativeDropoffTimeWindow[], nullable: Additional dropoff windows the optimizer may choose instead of the primary window
        - `start` string, required
        - `end` string, required
    - `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

- OrderOutputExample[]
  - `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'
  - `pickupEmail` string, nullable: The email of the contact at the pickup location.
  - `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'
  - `dropoffEmail` string, nullable: The email of the contact at the dropoff location.
  - `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' | 'cargo_bike' | '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', 'cargo_bike', '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
  - `dueAmountCents` string, nullable: Cash the driver must collect from the recipient on delivery, in cents. Null when not specified.
  - `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.
    - `volume` union: The volume of the item in cubic centimeters (cm^3)
      - number
      - integer
    - `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: What to do when this item can't be picked: `refund`, `substitute`, or `contact` (the shopper contacts the customer to agree a substitution).
        - `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
  - `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 document content when load_data=true: text documents such as ZPL as plain text, all others such as PDF as base64
  - `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
    - `errorCode` string, nullable: Machine-readable quote failure code
    - `errorDetails` object, nullable: Structured quote failure details
  - `failedQuotes` string[], nullable: The failed quotes of the order
  - `quoteFailure` object, nullable: Summary when every provider rejects the package requirements

## Other responses

- `422`: Unprocessable Content

---

[API](https://skmtc.dev/nash/apis/nash-api.md) - [All operations](https://skmtc.dev/nash/apis/nash-api/llms.txt) - [OpenAPI document](https://skmtc.dev/nash/apis/nash-api/revisions/e3713837c5c9?raw)