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
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:
From your Kublau dashboard, go to Settings > Carrier Accounts.
Click on New Carrier Account.
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:
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
}
}
}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, +525529785632.
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.
{
"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.
mutation buyShipment($input: ShipmentBuyInput!) {
shipmentBuy(input: $input) {
shipment {
id
trackingCode
insurance
note
selectedRate {
id
}
postageLabel {
url
}
}
shipmentUserErrors {
code
message
field
}
}
}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.
Last updated
Was this helpful?