Buy a shipping label

This guide will walk you through shipping your first package

Overview

This guide describes how to buy a shipping label. Shipments provide an itemized list of rates/services available for a package between two points, which includes the cost, service level and delivery estimates. You can also use them as a tool to make quotations.

Registering your carrier's account

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

In order to buy a postage label in production you need to have a registered account with the carrier.

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 for Ruby and Python. You can also use GraphQL directly with our GraphQL Playground.

Create a Shipment

The origin/destination address and parcel are required for rating. The associated shipping rates are generated by Kublau and cannot be modified by the user.

The units used by the parcel are centimetres and grams.

When using Test API Keys we'll provide a test USPS account for development purposes. Thus only US addresses will return rates in test mode.

Here is an example of how to create a shipment object:

GraphQL

mutation shipmentCreate($input: ShipmentCreateInput!) {
  shipmentCreate(input: $input) {
    shipment {
      id
      rates {
        id
        amount
        carrier
        currency
        serviceLevel
        deliveryDays
        deliveryEstimateAt
        deliveryEstimateGuaranteed
      }
      suggestedRates {
        fastest {
          id
        }
        cheapest {
          id
        }
      }
    }
    shipmentUserErrors {
      code
      message
      field
    }
  }
}

GraphQL Query Variables

{
  "input": {
    "carriers": ["USPS"],
    "origin": {
      "line1": "417 MONTGOMERY ST",
      "city": "SAN FRANCISCO",
      "state": "CA",
      "postalCode": "94105",
      "country":"US",
      "name": "John Doe",
      "phone": "123 456 789 15"
    },
    "destination": {
      "line1": "532 Folsom St. 5",
      "line2": "Apartment 654",
      "city": "SAN FRANCISCO",
      "state": "CA",
      "postalCode": "94105",
      "country": "US",
      "name": "John Doe",
      "phone": "123 456 789 16"
    },
    "parcel":{
      "length": 20.0,
      "width": 20.0,
      "height": 20.0,
      "weight": 29.0
    }
  }
}

Node

Run Node example on online REPL.

Shipment Data reference

Field	Type	​Description
carriers	[Carrier!]!	A list of carriers to fetch rates for. Normally you will only include one.
origin	Address!	The origin address
destination	Address!	The destination address
parcel	Parcel!	The parcel's size and weight in centimeters and grams.
metafields	[Metafield!]!	Array of additional non-standard fields passed to the shipment for rate creation and label purchases.

Address Data reference

Field	Type	​Description
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.
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.
postal_code	String	The postal code or zip of the address.
name	String	The full name of the customer.
phone	String	A unique phone number for the customer. Formatted using E.164 standard. For example, [phone].

When you create a shipment, the API responds with a Shipmentobject that contains the rates for the carriers you’ve registered. These are the rates for shipping the parcel between the origin and destination addresses you’ve specified. An individual rate contains information about the carrier, the service level (eg 1 day, 2 day, Ground, etc), cost, the estimated number of days to delivery (when available), estimated delivery date and if the delivery date is guaranteed by an SLA.

{
  "data": {
    "shipmentCreate": {
      "shipment": {
        "id": "gid://kublau/Shipment/1251cc28-1d7f-496d-b704-1e092cf53b5d",
        "rates": [
          {
            "id": "gid://kublau/ShipmentRate/68b53fc1-41b3-4dbb-813f-9f82df4d72ed",
            "amount": 28.94,
            "carrier": "USPS",
            "currency": "USD",
            "serviceLevel": "ParcelSelect",
            "deliveryDays": 2,
            "deliveryEstimateAt": "2020-05-13T19:00:00-05:00",
            "deliveryEstimateGuaranteed": false
          },
          {
            "id": "gid://kublau/ShipmentRate/7ab1b999-a621-4992-b302-d3fe85e516e6",
            "amount": 29.04,
            "carrier": "USPS",
            "currency": "USD",
            "serviceLevel": "Priority",
            "deliveryDays": 1,
            "deliveryEstimateAt": null,
            "deliveryEstimateGuaranteed": false
          },
          {
            "id": "gid://kublau/ShipmentRate/0c40e646-8cf3-4969-86fc-8f57f4e95480",
            "amount": 113.2,
            "carrier": "USPS",
            "currency": "USD",
            "serviceLevel": "Express",
            "deliveryDays": null,
            "deliveryEstimateAt": null,
            "deliveryEstimateGuaranteed": false
          }
        ],
        "suggestedRates": {
          "fastest": {
            "id": "gid://kublau/ShipmentRate/0c40e646-8cf3-4969-86fc-8f57f4e95480"
          },
          "cheapest": {
            "id": "gid://kublau/ShipmentRate/68b53fc1-41b3-4dbb-813f-9f82df4d72ed"
          }
        }
      },
      "shipmentUserErrors": []
    }
  }
}

Passing non-standard fields

There are some carriers that use non-standard fields for rating shipments or purchasing a shipment label. These extra fields are exposed as the metafields array of MetaField objects and should be included as part of your API call when required by the carrier.

Carriers that require or allow using non-standard fields:

• Clicoh (Requires CLICH_ITEMS)

Reading carrier specific fields

We provide a metafields array which includes additional information about a rate given to us by the carrier. For these fields we can't provide a standardized interface, but provide them through this array.

For example:

{
  "data": {
    "shipmentCreate": {
      "shipment": {
        "id": "gid://kublau/Shipment/a48eb71c-e430-4a92-a538-9bb6ff121e5e",
        "rates": [
          {
            "id": "gid://kublau/ShipmentRate/388703c5-3fd6-4ee1-9ea9-788b9b3aa356",
            "amount": 48,
            "carrier": "MINUTOS99",
            "currency": "MXN",
            "serviceLevel": "NextDay",
            "deliveryDays": 1,
            "deliveryEstimateAt": null,
            "deliveryEstimateGuaranteed": false,
            "metafields": [
              {
                "key": "packageSize",
                "value": "s",
                "valueType": "STRING"
              }
            ]
          }
        ],
      },
      "shipmentUserErrors": []
    }
  }
}

You can read about each carrier's ShipmentRate metafields here.

How to best format the destination address

When generating the shipping label we will intelligently abbreviate and cut tokens from your destination line1 and line2 to fit them within the carrier's label constraints.

To aid with this process we recommend the following:

When including unit level identifiers such as interior number or apartment # use int. as a prefix.

• Avenida de los bosques 42 int. 4

• Calle 3 de mayo 78 int. edificio 12

Make sure to not include duplicated fields such as postal code, country, city or state.

Using lower level fields instead of line1 and line2

We provide an alternative way to specify the line1 and line2 fields of an address. You specify its lower level components called lineComponents.

We recommend providing these instead of line1 or line2 when possible as it will bypass our internal tokenizer. Avoiding edge-case parsing errors that might happen occasionally. This is specially useful for carriers that need such lower level fields as part of their API.

GraphQL Query Variables

{
  "input": {
    "carriers": ["USPS"],
    "origin": {
      "line1": "417 MONTGOMERY ST",
      "city": "SAN FRANCISCO",
      "state": "CA",
      "postalCode": "94105",
      "country":"US",
      "name": "John Doe",
      "phone": "123 456 789 15"
    },
    "destination": {
      "lineComponents": {
        "street": "Folsom St. 5",
        "houseNumber": "532",
        "unit": "Apartment 654"
      },
      "city": "SAN FRANCISCO",
      "state": "CA",
      "postalCode": "94105",
      "country": "US",
      "name": "John Doe",
      "phone": "123 456 789 16"
    },
    "parcel":{
      "length": 20.0,
      "width": 20.0,
      "height": 20.0,
      "weight": 29.0
    }
  }

LineComponents Data reference

Field	Type	​Description
street	String	Street name(s)
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.
unit	String	An apartment, unit, office, lot, or other secondary unit designator

Buy and Generate a Shipping Label

You're almost done. Now you're ready to buy the label so you can print it out and put it on your package. To do this, you need to tell us which rate you want to use.

GraphQL

 mutation buyShipment($input: ShipmentBuyInput!) {
    shipmentBuy(input: $input) {
      shipment {
        id
        trackingCode
        insurance
        note
        selectedRate {
          id
        }
        postageLabel {
          url
        }
      }
      shipmentUserErrors {
        code
        message
        field
      }
    }
  }

GraphQL Query variables

{
  "input": {
    "id": "gid://kublau/Shipment/246b2303-5800-4916-ba7b-5a5a938957b8",
    "rateId": "gid://kublau/ShipmentRate/2358146f-d916-481c-985e-94cdb787dd21",
    "insurance": 100.0,
    "note": "This is a note that gets added to the label"
  }
}

Node

Run Node example on online REPL.

Buy a shipment Data reference

Field	Type	​Description
id	ID!	Global ID for the shipment you will be buying a postal label for.
rateId	ID!	Global ID for the selected rate you will be buying a postal label for.
insurance	Float	The amount you want to insure your package for (if supported by carrier). Amount will have the same currency as source rate (eg. If rateId is in MXN, insurance will be in MXN as-well).
note	String	A note about the shipment. It is sent as a note to the carrier if it supports it. Kublau includes the note in a free space on the postal label when the carrier does not support it

When you buy a shipping label, the API responds again with a Shipment object that includes a URL to the postage label that you can download as PNG and print (postageLabel.url). It also now includes theselectedRate and the trackingCode which you can use to create a Tracker.

{
  "data": {
    "shipmentBuy": {
      "shipment": {
        "id": "gid://kublau/Shipment/1251cc28-1d7f-496d-b704-1e092cf53b5d",
        "trackingCode": "5759001581",
        "insurance": 100.0,
        "note": "This is a note that gets added to the label",
        "selectedRate": {
          "id": "gid://kublau/ShipmentRate/68b53fc1-41b3-4dbb-813f-9f82df4d72ed",
          "deliveryDays": 2,
          "deliveryEstimateAt": "2020-05-13T19:00:00-05:00",
          "deliveryEstimateGuaranteed": false
        },
        "postageLabel": {
          "url": "https://api.kublau.com/rails/active_storage/public_blobs/s2gn4jt9f0pqgxlce97f44uupsf9/files-shipments-6e656fcf-e46a-4189-9e78-e603a22f4ffb.png"
        }
      },
      "shipmentUserErrors": []
    }
  }
}

Tracking the shipment

A shipment with a bought postage label will include a tracking code for your package. You can use this to store on your side or pass to your customers. You can also follow tracking updates in real-time.