Skip to main content
POST
/
v2
/
orders
/
upsert
/
bulk
Create or update orders by external identifier (v2)
curl --request POST \
  --url https://api.sandbox.usenash.com/v2/orders/upsert/bulk \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "orders": [
    {
      "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,
          "requirements": [
            "age_verification_on_delivery"
          ],
          "category": "<string>",
          "barcode": "0199312650999998913643M221872801002010908",
          "metadata": {
            "packaging_type": "CTN"
          },
          "subItems": [
            {
              "id": "abc-123",
              "description": "A box of books",
              "count": 2,
              "dimensions": {
                "depth": 14,
                "height": 10,
                "width": 12
              },
              "weight": 1.5,
              "valueCents": 1000,
              "requirements": [
                "age_verification_on_delivery"
              ],
              "category": "<string>",
              "barcode": "0199312650999998913643M221872801002010908",
              "metadata": {
                "packaging_type": "CTN"
              },
              "sku": "<string>",
              "substitution": {
                "preference": "<string>",
                "source": "<string>",
                "substituteItems": [
                  {
                    "id": "<string>",
                    "sku": "<string>",
                    "quantity": 123
                  }
                ]
              },
              "subItems": "<unknown>"
            }
          ]
        }
      ],
      "optimizationParameters": {
        "pickupDoorstepTimeSeconds": 90,
        "dropoffDoorstepTimeSeconds": 180,
        "costsByMetric": {
          "distance": 10,
          "weight": 200
        },
        "clusterLabel": "<string>",
        "mxLabel": "<string>",
        "assignmentPriority": 1,
        "sequencePriority": 249,
        "sequenceGroup": "<string>"
      },
      "pickupPayment": {
        "barcode": {
          "type": "CODE128",
          "value": "1234567890"
        },
        "providerCard": true
      },
      "reapplyAutomations": true,
      "maxDeliveryFeeCents": 123
    }
  ]
}
'
{
  "results": [
    {
      "status": "success",
      "externalId": "1234567890",
      "id": "ord_1234567890",
      "data": {
        "id": "ord_1234567890",
        "createdAt": "2023-08-29T19:17:46.264523",
        "portalUrl": "https://portal.dev.usenash.com/orders/ord_1234567890",
        "publicTrackingUrl": "https://tracking.dev.usenash.com/ord_1234567890",
        "status": "needs_attention",
        "tags": [
          "REST_API"
        ],
        "externalId": "1234567890",
        "externalGroupId": "1234567890",
        "referenceId": "1234567890",
        "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"
        ],
        "pickupPayment": {
          "barcode": {
            "type": "CODE128",
            "value": "1234567890"
          },
          "providerCard": false
        },
        "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,
            "requirements": [
              "age_verification_on_delivery"
            ],
            "category": "<string>",
            "barcode": "0199312650999998913643M221872801002010908",
            "metadata": {
              "packaging_type": "CTN"
            },
            "subItems": [
              {
                "id": "abc-123",
                "description": "A box of books",
                "count": 2,
                "dimensions": {
                  "depth": 14,
                  "height": 10,
                  "width": 12
                },
                "weight": 1.5,
                "valueCents": 1000,
                "requirements": [
                  "age_verification_on_delivery"
                ],
                "category": "<string>",
                "barcode": "0199312650999998913643M221872801002010908",
                "metadata": {
                  "packaging_type": "CTN"
                },
                "sku": "<string>",
                "substitution": {
                  "preference": "<string>",
                  "source": "<string>",
                  "substituteItems": [
                    {
                      "id": "<string>",
                      "sku": "<string>",
                      "quantity": 123
                    }
                  ]
                },
                "subItems": "<unknown>"
              }
            ]
          }
        ],
        "dispatchStrategyId": "dss_1234567890",
        "maxDeliveryFeeCents": "1000",
        "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"
        ]
      },
      "errors": [
        {
          "code": "ORDER_ALREADY_DISPATCHED",
          "message": "Order has already been dispatched and cannot be updated."
        }
      ]
    }
  ],
  "summary": {
    "success": 2,
    "failed": 1
  }
}
This endpoint allows you to create and/or update multiple orders by specifying external identifiers. This is useful for batch operations where you need to process multiple orders at once, such as importing orders from an external system or updating multiple orders based on their external IDs.
Create or Update Orders by External Identifier behavior: For each order with an external_id, Nash will check if an order with that external ID already exists. If it exists, the order will be updated; if not, a new order will be created. A hard failure on one order does not fail the batch; the rest still commit. The response returns a results array (one entry per input order, in the same order as the request) with success or failed status, plus a summary of the counts.
Updating archived orders will also unarchive them.
This endpoint is particularly useful for:
  • Bulk importing orders from external systems
  • Synchronizing order data between systems
  • Batch updating multiple orders based on external identifiers

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
orders
OrderInput · object[]
required

List of orders to create

Response

OK

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
BulkUpsertResult[BulkUpsertOrderData] · object[]
required

One entry per input row, in the same order as the request.

​
summary
BulkUpsertSummary · object
required

Aggregate counts of each outcome.