POST
/
v1
/
order
/
external-identifier
/
{externalId}
curl --request POST \
  --url https://api.sandbox.usenash.com/v1/order/external-identifier/{externalId} \
  --header 'Content-Type: application/json' \
  --data '{
  "externalId": "<string>",
  "pickupAddress": "<string>",
  "pickupPlaceId": "<string>",
  "pickupPhoneNumber": "<string>",
  "pickupBusinessName": "<string>",
  "pickupFirstName": "<string>",
  "pickupLastName": "<string>",
  "pickupInstructions": "<string>",
  "pickupStoreLocationId": "<string>",
  "pickupExternalStoreLocationId": "<string>",
  "pickupStoreLocationIds": [
    "<string>"
  ],
  "pickupZoneIds": [
    "<string>"
  ],
  "pickupBarcodes": [
    "<string>"
  ],
  "pickupEmail": "<string>",
  "dropoffAddress": "<string>",
  "dropoffPlaceId": "<string>",
  "dropoffPhoneNumber": "<string>",
  "dropoffBusinessName": "<string>",
  "dropoffFirstName": "<string>",
  "dropoffLastName": "<string>",
  "dropoffInstructions": "<string>",
  "dropoffBarcodes": [
    "<string>"
  ],
  "dropoffEmail": "<string>",
  "deliveryMode": "<string>",
  "pickupStartTime": "2023-11-07T05:31:56Z",
  "pickupEndTime": "2023-11-07T05:31:56Z",
  "dropoffStartTime": "2023-11-07T05:31:56Z",
  "dropoffEndTime": "2023-11-07T05:31:56Z",
  "deliveryWindowId": "<string>",
  "description": "<string>",
  "itemsCount": 123,
  "currency": "<string>",
  "valueCents": 123,
  "tipAmountCents": 123,
  "requirements": [
    "photo_proof_of_delivery",
    "age_verification_on_delivery"
  ],
  "minimumVehicleSize": "car",
  "dispatchStrategyId": "<string>",
  "orderMetadata": {},
  "tags": [
    "<string>"
  ],
  "referenceId": "<string>",
  "pickupAddressNumber": "<string>",
  "pickupAddressSecondarynumber": "<string>",
  "pickupAddressFormattedStreet": "<string>",
  "pickupAddressCity": "<string>",
  "pickupAddressCounty": "<string>",
  "pickupAddressState": "<string>",
  "pickupAddressZip": "<string>",
  "pickupAddressCountry": "<string>",
  "pickupLat": 123,
  "pickupLng": 123,
  "dropoffAddressNumber": "<string>",
  "dropoffAddressSecondarynumber": "<string>",
  "dropoffAddressFormattedStreet": "<string>",
  "dropoffAddressCity": "<string>",
  "dropoffAddressCounty": "<string>",
  "dropoffAddressState": "<string>",
  "dropoffAddressZip": "<string>",
  "dropoffAddressCountry": "<string>",
  "dropoffLat": 123,
  "dropoffLng": 123,
  "weight": 123,
  "height": 123,
  "width": 123,
  "depth": 123,
  "items": [
    {
      "id": "abc-123",
      "description": "A box of books",
      "count": 2,
      "dimensions": {
        "depth": 14,
        "height": 10,
        "width": 12
      },
      "weight": 1.5,
      "valueCents": 1000,
      "subItems": [
        {}
      ]
    }
  ],
  "optimizationParameters": {
    "pickupDoorstepTimeSeconds": 90,
    "dropoffDoorstepTimeSeconds": 180,
    "costsByMetric": {
      "distance": 10,
      "weight": 200
    },
    "clusterLabel": "<string>",
    "assignmentPriority": 1,
    "sequencePriority": 249,
    "sequenceGroup": "<string>"
  },
  "reapplyAutomations": true,
  "returnFirstQuoteApiOnly": true
}'
{
  "id": "ord_1234567890",
  "createdAt": "2023-08-29T19:17:46.264523",
  "externalId": "1234567890",
  "referenceId": "1234567890",
  "portalUrl": "https://portal.dev.usenash.com/orders/ord_1234567890",
  "publicTrackingUrl": "https://tracking.dev.usenash.com/ord_1234567890",
  "status": "needs_attention",
  "tags": [
    "REST_API"
  ],
  "orderMetadata": {
    "key": "value"
  },
  "pickupAddress": "185 University Ave, Palo Alto, CA 94301",
  "pickupPlaceId": "ChIJd8BlQJq3t4kRUKhH43CQ",
  "pickupAddressNumber": "185",
  "pickupAddressSecondarynumber": "<string>",
  "pickupAddressFormattedStreet": "University Ave",
  "pickupAddressCity": "Palo Alto",
  "pickupAddressCounty": "Santa Clara",
  "pickupAddressState": "CA",
  "pickupAddressZip": "94301",
  "pickupAddressCountry": "US",
  "pickupLat": 37.422222,
  "pickupLng": -122.139776,
  "pickupPhoneNumber": "+15555555555",
  "pickupFirstName": "Manager",
  "pickupLastName": "Manager",
  "pickupBusinessName": "Store ABC",
  "pickupInstructions": "Leave at the front door",
  "pickupStoreLocationId": "stl_VwpoPJaaqWiPGnXEhWfX",
  "pickupExternalStoreLocationId": "0021112",
  "pickupZoneIds": [
    "<string>"
  ],
  "pickupBarcodes": [
    "1234567890",
    "0987654321"
  ],
  "dropoffAddress": "401 San Antonio Rd, Mountain View, CA 94040",
  "dropoffPlaceId": "ChIJd8BlQJq3t4kRUKhH43CQ",
  "dropoffAddressNumber": "401",
  "dropoffAddressSecondarynumber": "<string>",
  "dropoffAddressFormattedStreet": "San Antonio Rd",
  "dropoffAddressCity": "Mountain View",
  "dropoffAddressCounty": "Santa Clara",
  "dropoffAddressState": "CA",
  "dropoffAddressZip": "94040",
  "dropoffAddressCountry": "US",
  "dropoffLat": 37.422222,
  "dropoffLng": -122.139776,
  "dropoffPhoneNumber": "+15555555556",
  "dropoffFirstName": "Quote",
  "dropoffLastName": "Request",
  "dropoffBusinessName": "<string>",
  "dropoffInstructions": "Leave at the front door",
  "dropoffStoreLocationId": "<string>",
  "dropoffBarcodes": [
    "<string>"
  ],
  "deliveryMode": "scheduled",
  "pickupStartTime": "2024-08-22T23:54:08Z",
  "pickupEndTime": "2024-08-22T23:54:08Z",
  "dropoffStartTime": "2024-08-22T23:54:08Z",
  "dropoffEndTime": "2024-08-22T23:54:08Z",
  "description": "Order description",
  "itemsCount": "1",
  "requirements": [
    "photo_proof_of_delivery"
  ],
  "minimumVehicleSize": "car",
  "currency": "USD",
  "valueCents": "10000",
  "tipAmountCents": "1000",
  "width": "100",
  "depth": "100",
  "height": "100",
  "volume": "<string>",
  "weight": "100",
  "items": [
    {
      "id": "abc-123",
      "description": "A box of books",
      "count": 2,
      "dimensions": {
        "depth": 14,
        "height": 10,
        "width": 12
      },
      "weight": 1.5,
      "valueCents": 1000,
      "subItems": [
        {}
      ]
    }
  ],
  "dispatchStrategyId": "dss_1234567890",
  "documents": [
    {
      "contentType": "application/pdf",
      "data": "SGVsbG8gd29ybGQ=",
      "id": "doc_1234567890",
      "type": "shipping_label",
      "url": "https://example.com/document.pdf"
    }
  ],
  "validationErrors": {
    "pickupStartTime": "Time is in the past"
  },
  "quotes": [
    {
      "costSplitBusinessCents": null,
      "costSplitCustomerCents": null,
      "createdTime": "2024-09-03T20:43:45.899094",
      "currency": "USD",
      "dropoffEta": "2024-09-03T22:20:47.569000",
      "expireTime": "2024-09-03T21:43:45.899102",
      "id": "qot_2oWASjGxMtucwGgu6A7BYC",
      "insuranceFeeCents": 0,
      "nashFeeCents": 300,
      "pickupWindow": null,
      "priceCents": 100,
      "providerId": "dispatch_partner",
      "providerIsInternal": false,
      "providerLogo": "https://nash-provider-logos.s3.amazonaws.com/dispatchit-logo.jpg",
      "providerName": "Dispatch",
      "tags": null,
      "taxAmountCents": null,
      "tollFeeCents": 0,
      "totalPriceBreakdown": {
        "priceCents": 100
      },
      "totalPriceCents": 100,
      "type": "LOCAL"
    }
  ],
  "failedQuotes": [
    "quote_1234567890",
    "quote_0987654321"
  ]
}

This endpoint allows you to create and/or update an order by specifying an ID. Using this endpoint is relevant for checkout workflows, where you can create an order based on the customers cart / order ID and then update it once the customer completes the checkout.

Create or Update Order by External Identifier behavior: If two requests with the same external_id are received, Nash will block the second request until the first request has been committed to the db and the response has been sent to the client. After that, the second request will be processed as an update since the order has already been created by the first request. This ensures that only one order is created per external_id, even when multiple requests are made simultaneously.

Updating an archived order will also unarchive it.

Path Parameters

​
externalId
string
required

The external id of the order to update

Example:

"1234567890"

Body

application/json

Order input for creating an order.

Response

200
application/json
OK

The response is of type object.