Pickups

List pickups

GET /v1/pickups

Pickups on the account, newest first. Filter by list (tab), status, dates or a search.

Query parameters

• tab string

  Which list: active, history, exceptions, cancelled, archived or draft.

• search string

  Free-text search.

• from date

  Ship-from address.

• to date

  Ship-to address.

• limit integer

  Most results to return.

• offset integer

  Results to skip, for paging.

• archived boolean

  true to archive (the default), false to bring it back.

Response in data

• items • Required array of objects
  Each item · 27

  • address • Required any
  • archived • Required boolean

    true to archive (the default), false to bring it back.

  • carrier • Required string

    Carrier code, as returned with each rate.

  • created_at • Required timestamp

    When it was created (ISO 8601, UTC).

  • currency • Required string

    Three-letter currency code, e.g. CAD.

  • dispatch_attempts • Required integer
  • fee_cents • Required integer
  • id • Required uuid
  • pickup_date • Required date

    Pickup day (YYYY-MM-DD).

  • pickup_number • Required string
  • shipment_ids • Required array of uuids

    Ids of purchased shipments.

  • status • Required string
  • tax_cents • Required integer

    Sales tax, in cents.

  • time_window_end • Required string

    Latest pickup time, local (HH:MM:SS).

  • time_window_start • Required string

    Earliest pickup time, local (HH:MM:SS).

  • total_cents • Required integer

    Total, in cents.

  • archived_at timestamp
  • building_type string

    Kind of building: Office, Warehouse, Residential or Other.

  • cancelled_at timestamp
  • carrier_pickup_id string
  • carrier_status string
  • confirmation_number string
  • instructions string

    Instructions for the driver.

  • last_dispatch_error string
  • last_synced_at timestamp
  • pickup_location string

    Where the parcels will be, e.g. front door, reception.

  • tax_jurisdiction string
• total • Required integer

Book a pickup

POST /v1/pickups

Books a carrier pickup for the given shipments and charges the wallet the pickup fee. Get the price with POST /v1/pickups/quote first.

Confirm with the account owner before calling it.

Request body

• address • Required any

  Pickup address: the same fields as an address book entry.

• carrier • Required string

  Carrier code, as returned with each rate.

• pickup_date • Required date

  Pickup day (YYYY-MM-DD).

• shipment_ids • Required array of uuids

  Ids of purchased shipments.

• time_window_end • Required string

  Latest pickup time, local (HH:MM:SS).

• time_window_start • Required string

  Earliest pickup time, local (HH:MM:SS).

• building_type string

  Kind of building: Office, Warehouse, Residential or Other.

• discount_code string

  A discount code to apply.

• instructions string

  Instructions for the driver.

• pickup_location string

  Where the parcels will be, e.g. front door, reception.

Response in data

• address • Required any
• archived • Required boolean

  true to archive (the default), false to bring it back.

• carrier • Required string

  Carrier code, as returned with each rate.

• created_at • Required timestamp

  When it was created (ISO 8601, UTC).

• currency • Required string

  Three-letter currency code, e.g. CAD.

• dispatch_attempts • Required integer
• fee_cents • Required integer
• id • Required uuid
• pickup_date • Required date

  Pickup day (YYYY-MM-DD).

• pickup_number • Required string
• shipment_ids • Required array of uuids

  Ids of purchased shipments.

• status • Required string
• tax_cents • Required integer

  Sales tax, in cents.

• time_window_end • Required string

  Latest pickup time, local (HH:MM:SS).

• time_window_start • Required string

  Earliest pickup time, local (HH:MM:SS).

• total_cents • Required integer

  Total, in cents.

• archived_at timestamp
• building_type string

  Kind of building: Office, Warehouse, Residential or Other.

• cancelled_at timestamp
• carrier_pickup_id string
• carrier_status string
• confirmation_number string
• instructions string

  Instructions for the driver.

• last_dispatch_error string
• last_synced_at timestamp
• pickup_location string

  Where the parcels will be, e.g. front door, reception.

• tax_jurisdiction string

Get a pickup

GET /v1/pickups/{id}

One pickup: carrier, date, time window, address, shipments, charges and status.

Path parameters

• id • Required string

Response in data

• address • Required any
• archived • Required boolean

  true to archive (the default), false to bring it back.

• carrier • Required string

  Carrier code, as returned with each rate.

• created_at • Required timestamp

  When it was created (ISO 8601, UTC).

• currency • Required string

  Three-letter currency code, e.g. CAD.

• dispatch_attempts • Required integer
• fee_cents • Required integer
• id • Required uuid
• pickup_date • Required date

  Pickup day (YYYY-MM-DD).

• pickup_number • Required string
• shipment_ids • Required array of uuids

  Ids of purchased shipments.

• status • Required string
• tax_cents • Required integer

  Sales tax, in cents.

• time_window_end • Required string

  Latest pickup time, local (HH:MM:SS).

• time_window_start • Required string

  Earliest pickup time, local (HH:MM:SS).

• total_cents • Required integer

  Total, in cents.

• archived_at timestamp
• building_type string

  Kind of building: Office, Warehouse, Residential or Other.

• cancelled_at timestamp
• carrier_pickup_id string
• carrier_status string
• confirmation_number string
• instructions string

  Instructions for the driver.

• last_dispatch_error string
• last_synced_at timestamp
• pickup_location string

  Where the parcels will be, e.g. front door, reception.

• tax_jurisdiction string

Delete a pickup draft

DELETE /v1/pickups/{id}

Deletes a pickup draft. A booked pickup is cancelled instead (POST /v1/pickups/{id}/cancel).

Path parameters

• id • Required string

Response in data

See the example on the right.

Archive a pickup

POST /v1/pickups/{id}/archive

Hides a finished pickup from the normal lists, or brings it back with archived: false.

Path parameters

• id • Required string

Request body

• archived boolean

  true to archive (the default), false to bring it back.

Response in data

• address • Required any
• archived • Required boolean

  true to archive (the default), false to bring it back.

• carrier • Required string

  Carrier code, as returned with each rate.

• created_at • Required timestamp

  When it was created (ISO 8601, UTC).

• currency • Required string

  Three-letter currency code, e.g. CAD.

• dispatch_attempts • Required integer
• fee_cents • Required integer
• id • Required uuid
• pickup_date • Required date

  Pickup day (YYYY-MM-DD).

• pickup_number • Required string
• shipment_ids • Required array of uuids

  Ids of purchased shipments.

• status • Required string
• tax_cents • Required integer

  Sales tax, in cents.

• time_window_end • Required string

  Latest pickup time, local (HH:MM:SS).

• time_window_start • Required string

  Earliest pickup time, local (HH:MM:SS).

• total_cents • Required integer

  Total, in cents.

• archived_at timestamp
• building_type string

  Kind of building: Office, Warehouse, Residential or Other.

• cancelled_at timestamp
• carrier_pickup_id string
• carrier_status string
• confirmation_number string
• instructions string

  Instructions for the driver.

• last_dispatch_error string
• last_synced_at timestamp
• pickup_location string

  Where the parcels will be, e.g. front door, reception.

• tax_jurisdiction string

Cancel a pickup

POST /v1/pickups/{id}/cancel

Cancels a booked pickup with the carrier and refunds its fee to the wallet.

Path parameters

• id • Required string

Response in data

• address • Required any
• archived • Required boolean

  true to archive (the default), false to bring it back.

• carrier • Required string

  Carrier code, as returned with each rate.

• created_at • Required timestamp

  When it was created (ISO 8601, UTC).

• currency • Required string

  Three-letter currency code, e.g. CAD.

• dispatch_attempts • Required integer
• fee_cents • Required integer
• id • Required uuid
• pickup_date • Required date

  Pickup day (YYYY-MM-DD).

• pickup_number • Required string
• shipment_ids • Required array of uuids

  Ids of purchased shipments.

• status • Required string
• tax_cents • Required integer

  Sales tax, in cents.

• time_window_end • Required string

  Latest pickup time, local (HH:MM:SS).

• time_window_start • Required string

  Earliest pickup time, local (HH:MM:SS).

• total_cents • Required integer

  Total, in cents.

• archived_at timestamp
• building_type string

  Kind of building: Office, Warehouse, Residential or Other.

• cancelled_at timestamp
• carrier_pickup_id string
• carrier_status string
• confirmation_number string
• instructions string

  Instructions for the driver.

• last_dispatch_error string
• last_synced_at timestamp
• pickup_location string

  Where the parcels will be, e.g. front door, reception.

• tax_jurisdiction string

Retry a failed pickup

POST /v1/pickups/{id}/retry

Sends a pickup whose booking failed to the carrier again. No new charge.

Path parameters

• id • Required string

Response in data

• address • Required any
• archived • Required boolean

  true to archive (the default), false to bring it back.

• carrier • Required string

  Carrier code, as returned with each rate.

• created_at • Required timestamp

  When it was created (ISO 8601, UTC).

• currency • Required string

  Three-letter currency code, e.g. CAD.

• dispatch_attempts • Required integer
• fee_cents • Required integer
• id • Required uuid
• pickup_date • Required date

  Pickup day (YYYY-MM-DD).

• pickup_number • Required string
• shipment_ids • Required array of uuids

  Ids of purchased shipments.

• status • Required string
• tax_cents • Required integer

  Sales tax, in cents.

• time_window_end • Required string

  Latest pickup time, local (HH:MM:SS).

• time_window_start • Required string

  Earliest pickup time, local (HH:MM:SS).

• total_cents • Required integer

  Total, in cents.

• archived_at timestamp
• building_type string

  Kind of building: Office, Warehouse, Residential or Other.

• cancelled_at timestamp
• carrier_pickup_id string
• carrier_status string
• confirmation_number string
• instructions string

  Instructions for the driver.

• last_dispatch_error string
• last_synced_at timestamp
• pickup_location string

  Where the parcels will be, e.g. front door, reception.

• tax_jurisdiction string

Add shipments to a pickup

POST /v1/pickups/{id}/shipments

Adds shipments to a booked pickup that has not been cancelled.

Path parameters

• id • Required string

Request body

• shipment_ids • Required array of uuids

  Ids of purchased shipments.

Response in data

• address • Required any
• archived • Required boolean

  true to archive (the default), false to bring it back.

• carrier • Required string

  Carrier code, as returned with each rate.

• created_at • Required timestamp

  When it was created (ISO 8601, UTC).

• currency • Required string

  Three-letter currency code, e.g. CAD.

• dispatch_attempts • Required integer
• fee_cents • Required integer
• id • Required uuid
• pickup_date • Required date

  Pickup day (YYYY-MM-DD).

• pickup_number • Required string
• shipment_ids • Required array of uuids

  Ids of purchased shipments.

• status • Required string
• tax_cents • Required integer

  Sales tax, in cents.

• time_window_end • Required string

  Latest pickup time, local (HH:MM:SS).

• time_window_start • Required string

  Earliest pickup time, local (HH:MM:SS).

• total_cents • Required integer

  Total, in cents.

• archived_at timestamp
• building_type string

  Kind of building: Office, Warehouse, Residential or Other.

• cancelled_at timestamp
• carrier_pickup_id string
• carrier_status string
• confirmation_number string
• instructions string

  Instructions for the driver.

• last_dispatch_error string
• last_synced_at timestamp
• pickup_location string

  Where the parcels will be, e.g. front door, reception.

• tax_jurisdiction string

Remove a shipment from a pickup

DELETE /v1/pickups/{id}/shipments/{shipment_id}

Takes one shipment off a pickup; the pickup stays booked. If it was the last shipment, the response says empty: true: cancel the pickup if it is no longer needed.

Path parameters

• id • Required string
• shipment_id • Required string

Response in data

• empty • Required boolean
• pickup • Required object
  Fields · 27

  • address • Required any
  • archived • Required boolean

    true to archive (the default), false to bring it back.

  • carrier • Required string

    Carrier code, as returned with each rate.

  • created_at • Required timestamp

    When it was created (ISO 8601, UTC).

  • currency • Required string

    Three-letter currency code, e.g. CAD.

  • dispatch_attempts • Required integer
  • fee_cents • Required integer
  • id • Required uuid
  • pickup_date • Required date

    Pickup day (YYYY-MM-DD).

  • pickup_number • Required string
  • shipment_ids • Required array of uuids

    Ids of purchased shipments.

  • status • Required string
  • tax_cents • Required integer

    Sales tax, in cents.

  • time_window_end • Required string

    Latest pickup time, local (HH:MM:SS).

  • time_window_start • Required string

    Earliest pickup time, local (HH:MM:SS).

  • total_cents • Required integer

    Total, in cents.

  • archived_at timestamp
  • building_type string

    Kind of building: Office, Warehouse, Residential or Other.

  • cancelled_at timestamp
  • carrier_pickup_id string
  • carrier_status string
  • confirmation_number string
  • instructions string

    Instructions for the driver.

  • last_dispatch_error string
  • last_synced_at timestamp
  • pickup_location string

    Where the parcels will be, e.g. front door, reception.

  • tax_jurisdiction string
• remaining_shipments • Required integer

Pickup timeline

GET /v1/pickups/{id}/timeline

Everything that happened to the pickup: booking, carrier confirmation, charges and changes.

Path parameters

• id • Required string

Response in data

• items • Required array of objects
  Each item · 4

  • created_at • Required timestamp

    When it was created (ISO 8601, UTC).

  • event_type • Required string
  • message • Required string
  • severity • Required string

Pickup carriers

GET /v1/pickups/carriers

Carriers this account can book a pickup with.

Response in data

• carrier • Required string

  Carrier code, as returned with each rate.

• display_name • Required string

Pickup counts

GET /v1/pickups/counts

How many pickups are in each list.

Response in data

• active • Required integer
• archived • Required integer

  true to archive (the default), false to bring it back.

• cancelled • Required integer
• draft • Required integer
• exceptions • Required integer
• history • Required integer

Pickup cutoff times

GET /v1/pickups/cutoffs

Each carrier's latest time to request a same-day pickup, for the pickup area.

Query parameters

• postal_code string

  Pickup postal code (cutoffs vary by area for some carriers).

• province string

  Pickup province.

• country string

  Two-letter country code, e.g. CA, US.

Response in data

• carrier • Required string

  Carrier code, as returned with each rate.

• display_name • Required string
• supports_pickup • Required boolean
• cutoff_time string
• note string
• source string

  Where the shipment came from. Leave out (it becomes manual) or name your integration, e.g. api.

Start a pickup draft

POST /v1/pickups/draft

Starts a pickup without booking it, for building one up in steps.

Request body

• carrier • Required string

  Carrier code, as returned with each rate.

• shipment_ids array of uuids

  Ids of purchased shipments.

Response in data

• address • Required any
• archived • Required boolean

  true to archive (the default), false to bring it back.

• carrier • Required string

  Carrier code, as returned with each rate.

• created_at • Required timestamp

  When it was created (ISO 8601, UTC).

• currency • Required string

  Three-letter currency code, e.g. CAD.

• dispatch_attempts • Required integer
• fee_cents • Required integer
• id • Required uuid
• pickup_date • Required date

  Pickup day (YYYY-MM-DD).

• pickup_number • Required string
• shipment_ids • Required array of uuids

  Ids of purchased shipments.

• status • Required string
• tax_cents • Required integer

  Sales tax, in cents.

• time_window_end • Required string

  Latest pickup time, local (HH:MM:SS).

• time_window_start • Required string

  Earliest pickup time, local (HH:MM:SS).

• total_cents • Required integer

  Total, in cents.

• archived_at timestamp
• building_type string

  Kind of building: Office, Warehouse, Residential or Other.

• cancelled_at timestamp
• carrier_pickup_id string
• carrier_status string
• confirmation_number string
• instructions string

  Instructions for the driver.

• last_dispatch_error string
• last_synced_at timestamp
• pickup_location string

  Where the parcels will be, e.g. front door, reception.

• tax_jurisdiction string

Update a pickup draft

PATCH /v1/pickups/draft/{id}

Sets the date, time window, address and shipments of a pickup draft.

Path parameters

• id • Required string

Request body

• address • Required any

  Pickup address: the same fields as an address book entry.

• carrier • Required string

  Carrier code, as returned with each rate.

• pickup_date • Required date

  Pickup day (YYYY-MM-DD).

• time_window_end • Required string

  Latest pickup time, local (HH:MM:SS).

• time_window_start • Required string

  Earliest pickup time, local (HH:MM:SS).

• building_type string

  Kind of building: Office, Warehouse, Residential or Other.

• instructions string

  Instructions for the driver.

• pickup_location string

  Where the parcels will be, e.g. front door, reception.

• shipment_ids array of uuids

  Ids of purchased shipments.

Response in data

• address • Required any
• archived • Required boolean

  true to archive (the default), false to bring it back.

• carrier • Required string

  Carrier code, as returned with each rate.

• created_at • Required timestamp

  When it was created (ISO 8601, UTC).

• currency • Required string

  Three-letter currency code, e.g. CAD.

• dispatch_attempts • Required integer
• fee_cents • Required integer
• id • Required uuid
• pickup_date • Required date

  Pickup day (YYYY-MM-DD).

• pickup_number • Required string
• shipment_ids • Required array of uuids

  Ids of purchased shipments.

• status • Required string
• tax_cents • Required integer

  Sales tax, in cents.

• time_window_end • Required string

  Latest pickup time, local (HH:MM:SS).

• time_window_start • Required string

  Earliest pickup time, local (HH:MM:SS).

• total_cents • Required integer

  Total, in cents.

• archived_at timestamp
• building_type string

  Kind of building: Office, Warehouse, Residential or Other.

• cancelled_at timestamp
• carrier_pickup_id string
• carrier_status string
• confirmation_number string
• instructions string

  Instructions for the driver.

• last_dispatch_error string
• last_synced_at timestamp
• pickup_location string

  Where the parcels will be, e.g. front door, reception.

• tax_jurisdiction string

Book a pickup draft

POST /v1/pickups/draft/{id}/confirm

Books the pickup draft with the carrier and charges the wallet the pickup fee.

Confirm with the account owner before calling it.

Path parameters

• id • Required string

Request body

• discount_code string

  A discount code to apply.

Response in data

• address • Required any
• archived • Required boolean

  true to archive (the default), false to bring it back.

• carrier • Required string

  Carrier code, as returned with each rate.

• created_at • Required timestamp

  When it was created (ISO 8601, UTC).

• currency • Required string

  Three-letter currency code, e.g. CAD.

• dispatch_attempts • Required integer
• fee_cents • Required integer
• id • Required uuid
• pickup_date • Required date

  Pickup day (YYYY-MM-DD).

• pickup_number • Required string
• shipment_ids • Required array of uuids

  Ids of purchased shipments.

• status • Required string
• tax_cents • Required integer

  Sales tax, in cents.

• time_window_end • Required string

  Latest pickup time, local (HH:MM:SS).

• time_window_start • Required string

  Earliest pickup time, local (HH:MM:SS).

• total_cents • Required integer

  Total, in cents.

• archived_at timestamp
• building_type string

  Kind of building: Office, Warehouse, Residential or Other.

• cancelled_at timestamp
• carrier_pickup_id string
• carrier_status string
• confirmation_number string
• instructions string

  Instructions for the driver.

• last_dispatch_error string
• last_synced_at timestamp
• pickup_location string

  Where the parcels will be, e.g. front door, reception.

• tax_jurisdiction string

Pickup scheduling options

GET /v1/pickups/options

Whether same-day pickups can be booked right now, and the same-day cutoff hour.

Response in data

• allow_same_day • Required boolean
• same_day_cutoff_hour • Required integer

Quote a pickup

POST /v1/pickups/quote

The pickup fee, discount and tax for a carrier, date and address. Nothing is booked or charged.

Request body

• address • Required any

  Pickup address: the same fields as an address book entry.

• carrier • Required string

  Carrier code, as returned with each rate.

• pickup_date • Required date

  Pickup day (YYYY-MM-DD).

• discount_code string

  A discount code to apply.

Response in data

• currency • Required string

  Three-letter currency code, e.g. CAD.

• discountCents • Required integer
• feeCents • Required integer
• taxCents • Required integer
• taxJurisdiction • Required string
• totalCents • Required integer