---
title: "Batch import stops"
method: POST
path: "/plans/{planId}/stops:liveImport"
tags: ["Live Stops"]
---

# Batch import stops

`POST /plans/{planId}/stops:liveImport`

## Request

- Base URL: `https://api.spoke.com/public/v1`
- URL: `https://api.spoke.com/public/v1/plans/{planId}/stops:liveImport`
- Auth: HTTP basic
- TypeScript: <https://skmtc.dev/spoke/apis/spoke-api/docs/plans/:planId/stops:liveImport/post.ts> (a function with typed inputs; its response is checked against the schema)

Import stops to live plans. When the plan is not writable, this endpoint starts an editing session and the action can be applied through a new optimization, or be discarded.

## Path parameters

- `planId` string, required

## Request body

- object[]: An array of stops to import in batch. Supports a maximum of 100 stops per request.
  - `address` object, required: Address of the stop, at least one of the fields is required. If the latitude and longitude fields are set they will override any of the others. The addressName field is not used for geocoding and is only for display purposes.
    - `addressName` string, nullable: The name of the address. This will not be used for geocoding, and is only for the final address display purposes.
    - `addressLineOne` string, nullable: The first line of the address.
    - `addressLineTwo` string, nullable: The second line of the address.
    - `city` string, nullable: The city of the address.
    - `state` string, nullable: The state of the address.
    - `zip` string, nullable: The zip code of the address.
    - `country` string, nullable: The country of the address.
    - `latitude` number, nullable: The latitude of the address in decimal degrees.
    - `longitude` number, nullable: The longitude of the address in decimal degrees.
  - `recipient` object, nullable: Recipient information for this stop
    - `externalId` string, nullable: External ID of the recipient, as defined by the API user
    - `email` string, email, nullable: The email address of the recipient. Multiple emails are not supported.
    - `phone` string, nullable: Phone number of the recipient
    - `name` string, nullable: Name of the recipient
  - `orderInfo` object, nullable: Order information for this stop
    - `products` string[]: Products in this stop
    - `invoiceNumber` string, nullable: Invoice number
    - `sellerOrderId` string, nullable: Seller order ID
    - `sellerName` string, nullable: Seller name
    - `sellerWebsite` string, nullable: Seller website
  - `paymentOnDelivery` object, nullable: Payment on delivery (also known as "Cash on Delivery") data for this stop
    - `amount` integer, nullable: Amount *in minor units* (e.g. cents) to be collected upon delivery
    - `currency` 'AED' | 'ARS' | 'AUD' | 'BRL' | 'CAD' | 'CHF' | 'CLP' | 'CNY' | 'COP' | 'DKK' | 'EGP' | 'EUR' | 'GBP' | 'HKD' | 'HUF' | 'ILS' | 'INR' | 'JPY' | 'KRW' | 'MYR' | 'MXN' | 'NOK' | 'NZD' | 'PEN' | 'RON' | 'RUB' | 'SAR' | 'SEK' | 'SGD' | 'TRY' | 'USD' | 'UYU' | 'ZAR', nullable: Currency of the payment. Defaults to the team's currency.
  - `proofOfAttemptRequirements` object, nullable: Proof of attempt requirement settings for this stop
    - `enabled` boolean, nullable: Whether proof of attempt is required for this stop
  - `allowedDrivers` string[], nullable: Driver IDs that are allowed to be assigned to this stop. These drivers must be configured as part of the plan to be valid.
  - `activity` 'delivery' | 'pickup', nullable: Activity type
  - `optimizationOrder` 'first' | 'last' | 'default', nullable: The preferred order of this stop in the optimized route. If not provided or `"default"`, the stop will be placed in the optimal order, decided by the optimization algorithm. Otherwise it will be placed either `"first"` or `"last"`.
  - `packageCount` number, nullable: Number of packages in the stop
  - `weight` object, nullable: Weight information for this stop.
    - `amount` number, required: The weight amount for this stop.
    - `unit` 'kilogram' | 'pound' | 'metric-ton', required: The weight unit in which the amount is specified.
  - `notes` string, nullable: Notes for the stop
  - `clientId` string, nullable: Client ID of the retailer in Spoke Connect
  - `barcodes` string[]: List of barcode IDs associated with this stop
  - `customProperties` object, nullable: Key-value pairs of custom stop properties for this stop. The keys must be unique and match a custom stop property defined in your team.
  - `serviceInfo` object, nullable: Service offering data for this stop. Combines the service identifier and SLA start time. On update, set the whole object to `null` to clear all service info.
    - `identifier` string, nullable: The identifier of a service offering to assign to this stop. Must match the identifier of a current, non-deleted service offering defined on your team. On update, set it to `null` to remove an assigned service; on create, omit it to leave the stop without a service.
    - `slaStartsAt` integer, nullable: The SLA start time for this stop, in seconds since Unix epoch. Allows backdating when the actual order time is known. Can be provided with or without a service identifier.
  - `timing` object, nullable
    - `timeWindows` object[]: Up to two ordered arrival windows for this stop. An empty array clears the windows. A single window may have one null bound; two windows must have both bounds set. Windows must not overlap or touch, and their total span must not exceed 24 hours.
      - `earliestAttemptTime` object, nullable, required: Time of day in hours and minutes. Use a 24 hour clock.
        - `hour` integer, required: Hour of the day
        - `minute` integer, required: Minute of the hour
      - `latestAttemptTime` object, nullable, required: Time of day in hours and minutes. Use a 24 hour clock.
        - `hour` integer, required: Hour of the day
        - `minute` integer, required: Minute of the hour
    - `earliestAttemptTime` object, nullable: Time of day in hours and minutes. Use a 24 hour clock.
      - `hour` integer, required: Hour of the day
      - `minute` integer, required: Minute of the hour
    - `latestAttemptTime` object, nullable: Time of day in hours and minutes. Use a 24 hour clock.
      - `hour` integer, required: Hour of the day
      - `minute` integer, required: Minute of the hour
    - `estimatedAttemptDuration` integer, nullable: Duration in seconds of the activity in this stop, only set if you want to override the default. This can be set up to 8 hours.

## Response `200`

Success

- object: Success
  - `success` string[], required: The ids of the successfully imported stops
  - `failed` object[], required: The failed stops
    - `error` object, required
      - `message` string, required: The error that occurred during import
      - `code` string: Stable error code
      - `param` string: Invalid request parameter
    - `stop` object, required: The stop that failed to import
      - `address` object, required: The address of the stop that failed to import
        - `addressName` string, nullable, required: The name of the address. This will not be used for geocoding, and is only for the final address display purposes.
        - `addressLineOne` string, nullable, required: The first line of the address.
        - `addressLineTwo` string, nullable, required: The second line of the address.
        - `city` string, nullable, required: The city of the address.
        - `state` string, nullable, required: The state of the address.
        - `zip` string, nullable, required: The zip code of the address.
        - `country` string, nullable, required: The country of the address.
        - `latitude` number, nullable, required: The latitude of the address in decimal degrees.
        - `longitude` number, nullable, required: The longitude of the address in decimal degrees.
      - `recipient` object, nullable, required: The recipient of the stop that failed to import
        - `externalId` string, nullable, required: External ID of the recipient, as defined by the API user
        - `email` string, email, nullable, required: The email address of the recipient. Multiple emails are not supported.
        - `phone` string, nullable, required: Phone number of the recipient
        - `name` string, nullable, required: Name of the recipient
  - `pending` boolean, required

## Other responses

- `400`: The request has errors. Either syntactic or semantic
- `401`: Unauthorized
- `403`: The plan is no longer accessible or one or more stops contain fields that require upgrading your team subscription.
- `404`: A plan or a driver was not found
- `409`: The plan's optimization is in progress.
- `410`: Failed to create stop
- `422`: The stop is unprocessable.
- `500`: An internal server error occurred
- `default`: The default error model

---

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