Schedule a pickup for your shipments

Overview

This guide describes how to schedule a pickup for shipments.

The Pickup object allows you to schedule a pickup from a carrier to your place of business on a requested time window.

After a Pickup is successfully created, it will include a confirmationCode which serves as the carrier's unique identifier for the pickup.

Registering your carrier's account

You can skip this step if you are not in production.

In order to request pickups in production you need to have a registered account with the carrier with the required credentials for the Pickup service.

You need to enter your carrier specific credentials using the Kublau dashboard:

1. From your Kublau dashboard, go to Settings > Carrier Accounts.

2. Click on New Carrier Account.

3. Select the carrier and enter the corresponding credentials.

Get our GraphQL Playground running

To follow along the steps in this guide we'll provide an interactive environment with our GraphQL Playground.

Create a Pickup

You'll need to provide an address, an estimated amount of parcels, their average size, the requested time window and the contact details of the person responsible for the pickup.

Here is an example of how to create a pickup:

GraphQL

mutation pickupCreate($input: PickupCreateInput!) {
  pickupCreate(input: $input) {
    pickup {
      id
      confirmationCode
      carrier
      quantity
      requestedEndAt
      requestedStartAt
    }
    pickupUserErrors {
      code
      message
      field
    }
  }
}

GraphQL Query Variables

 {
   "input": {
    "carrier": "ESTAFETA",
    "quantity": 1,
    "requestedStartAt": "2022-04-20T22:03:40Z",
    "requestedEndAt": "2022-04-20T22:03:40Z",
    "address": {
      "line1": "El rebozo",
      "houseNumber": "714",
      "postalCode": "67155",
      "locality": "Alameda De La Hacienda",
      "city": "Guadalupe",
      "state": "Nuevo León",
      "country": "MX",
      "phone": "[phone]",
      "name": "Name of the person responsible for pickup",
      "email": "[e-mail]"
    },
    "parcel": {
      "length": 10.0,
      "width": 20.0,
      "height": 3.0,
      "weight": 100.0
    }
  }
}

PickupCreateInput Data reference

Field	Type	​Description
carrier	Carrier!	The carrier for which the pickup is being requested.
quantity	Integer!	The estimated amount of packages that will be picked up.
requestedStartAt	Time!	The earliest time at which the package is available for pick up. Represented in ISO 8601.
requestedEndAt	Time!	The latest time at which the package is available for pick up. Must be later than the requestedStartAt. Represented in ISO 8601.
address	AddressContactSegmentedInput!	The pickup address
parcel	Parcel!	The parcel's size and weight in centimeters and grams.

AddressContactSegmentedInput Data reference

line1	String!	The first line of the address. Typically the street address or PO Box number.
line2	String!	The second line of the address. Typically the number of the apartment, suite, or unit.
houseNumber	String!	External (street-facing) building number. In some countries this may be a compount, hyphenated number which also includes an apartment number, or a block number
city	String!	An apartment, unit, office, lot, or other secondary unit designation.
locality	String!	Usually an unofficial neighborhood name like "Harlem", "South Bronx", or "Crown Heights".
state	String!	The code for the region of the address, such as the state, province, or district. For example MEX for Estado de México, México.
country	String!	The two-letter code for the country of the address. For example, MX.
postalCode	String!	The postal code or zip of the address.
name	String!	The full name of the person responsible for the pickup.
phone	String!	A unique phone number for pickup contact details. Formatted using E.164 standard. For example, [phone].
email	String!	The pickup contact email where confirmation details and cancellation notices will be sent to.

When you request a pickup, the API responds again with a Pickup object that includes a carrier unique confirmationCode.

Make sure store the returned confirmationCodeas it is the pickup's unique identifier with the carrier. If you need to make changes or cancel the pickup the carrier will request for this confirmation number.

{
  "data": {
    "pickupCreate": {
      "pickup": {
        "id": "gid://kublau/Pickup/1fdc9c4e-c4ef-4f57-bf22-82d126fc0747",
        "confirmationCode": "1000395762",
        "quantity": 1,
        "requestedStartAt": "2022-04-20T17:03:40-05:00"
        "requestedEndAt": "2022-04-20T17:03:40-05:00"
      },
      "pickupUserErrors": []
    }
  }
}

Pickup Data reference

Field	Type	​Description
confirmationCode	String!	The confirmation number for a booked pickup with the carrier
carrier	Carrier!	A list of carriers to fetch rates for. Normally you will only include one.
quantity	Integer!	The earliest time at which the package is available to pick up
requestedStartAt	Time!	The earliest time at which the package is available for pick up. Represented in ISO 8601.
requestedEndAt	Time!	The latest time at which the package is available for pick up. Must be later than the requestedStartAt. Represented in ISO 8601.
address	Address!	The pickup address
parcel	Parcel!	The parcel's size and weight in centimeters and grams.

This is all that is required to request a pickup. The carrier should arrive at the specified address according to the requested pickup window.