Skip to main content
POST
/
v1
/
orders
/
bulk
Create, update, upsert, or delete orders asynchronously in bulk
curl --request POST \
  --url https://api.sandbox.usenash.com/v1/orders/bulk \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
[
  {
    "action": "<string>",
    "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,
          "requirements": [
            "age_verification_on_delivery"
          ],
          "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"
              ],
              "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>"
      },
      "reapplyAutomations": true,
      "maxDeliveryFeeCents": 123
    }
  }
]
'
{
  "id": "act_1234567890",
  "status": "QUEUED"
}
The upsert (update or insert) action will update existing orders that match the provided externalId, and create new orders for those that don’t.The delete action will archive the order, akin to the Archive Order endpoint.Status field returned is for the bulk operation, not the individual orders and can be one of the following:
  • QUEUED: The request has been received and is waiting to be processed in the bulk operation queue
  • IN_PROGRESS: The request is currently being worked on
  • SUCCESS: The request was successfully processed without any errors to the overall async process (individual orders might have failed)
  • FAILED: The request encountered an error and could not be completed
  • CANCELLED: The request processing was manually cancelled or terminated before completion
  • SKIPPED: The request was intentionally not processed due to validation issues or business rules
  • SCHEDULED: The bulk action is set to be processed at a future specified time (n/a)
Bulk order actions are asynchronous operations. You can either poll the GET endpoint using the returned id, and/or opt-in to receive the results via webhook. The webhook event is order.bulk_operation.completed and will be sent once the bulk operation is complete.

Authorizations

​
Authorization
string
header
required

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

Body

application/json
​
action
string
required
Allowed value: "create"
​
data
OrderInput · object
required

Order input for creating an order.

Response

OK

​
id
string
required

The ID of the bulk operation

Example:

"act_1234567890"

​
status
enum<string>
required

The status of the bulk operation

Available options:
QUEUED,
IN_PROGRESS,
SUCCESS,
FAILED,
CANCELLED,
SKIPPED,
SCHEDULED
Example:

"QUEUED"