Type Definitions
# Address
The Address Object
Properties:
Name | Type | Description |
---|---|---|
street_number |
String | |
state |
String | |
city |
String | |
street_name |
String | |
state_name |
String | The same as state |
postal_code |
String | the same as zip code but more common name in other countires |
timezone |
String | |
street_suffix |
String | the street suffix such as "Dr" of "St" |
state_abbreviation |
String | |
address_line1 |
String | |
address_line2 |
String | null | |
zipcode |
String | |
verified |
Boolean | If this address has been verified by USPS |
formatted_address |
String | The full string of the address |
textarea |
String | The formatted address with "\r" breaks for it to be formatted nicely if you render it into a textarea |
place_name |
String | The same as the city field |
# Delivery
The Delivery object. Any of the properties could have null values if the delivery is not purchased.
Properties:
Name | Type | Description |
---|---|---|
id |
string | The delivery ID |
amount |
integer | The price of this rate as an integer with discount applied. (e.g., $15.76 would be represented as 1576). |
billed_amount |
integer | The price of this rate as an integer without discounts applied. (e.g., $15.76 would be represented as 1576). This is the total amount that Dispatch charged your payment information in file. |
sender_discount |
integer | The discount for this rate as an integer that you have specified. (e.g., $15.76 would be represented as 1576). This gets calculated based on your settings on the Dispatch dashboard. |
branding |
Object | Specified the branding for this delivery. |
email |
integer | If an email will be sent by Dispatch, this determines which logo will be on the email. |
label |
integer | Which logo should be placed on the label. |
courier |
Object | The courier object if the delivery is on demand. This will be deprecated in the future as the same data is found in the Provider object that is attached to the Rate. |
created_at |
integer | Epoch time in seconds when this delivery was created. |
estimated_delivery |
string | A human readable string value for the estimated delivery date and time. |
grace_period |
Object | The grace period that an on_demand courier will wait for a delivery. If the sender is not ready, the grace period object explains the fees that will be incurred. |
billed_amount |
integer | The amount as an integer that this delivery was billed for in the event of a grace period violation. |
fee |
integer | The grace period fee as an integer This it the fee that is charged per minute. |
minutes |
integer | The amount of minutes that the grace period is good for. |
payment_status |
string | null | This specifies the status of the payment that was collected |
wait_seconds |
integer | null | This is the duration in seconds that the courier waited for the delivery. |
intent_status |
string | The status of the delivery intent. An intent can be "created" when rates were generated but not purchased yet, "expired" if the intent was not captured within 15 mins, "captured" which means that the intent was paid for, and "deleted" which is when the intent was removed from the database. |
label_name |
string | The name of the shipping label as saved in the storage bucket. @deprecated This property will be removed. |
label_url |
string | The url from which you can download your label. This URL, can be accessed for 48 hours until it expires. Each time that you retrieve a delivery, a new label url is generated for you. |
lead_time_hours |
integer | The amount of lead time that was required for this delivery before an on_demand courier can pick it up. |
live_location |
Array | The lat and lon coordinates of the the current location of the delivery. Not every courier supports this. |
metadata |
Object | Key-value pairs of data that you have added to the delivery. When creating or purchasing a delivery, metadata can be passed in the options. You should never store sensitive information in key value pairs. Good uses for metadata would be to store an order ID or a customer ID from your database. |
on_demand |
Boolean | If this delivery is for an on_demand courier. |
paid |
Boolean | If this delivery was paid for. |
parcels |
Array.<Parcel> | An array of parcel objects, which are the boxes and items that were being transported. |
purchased_rate |
Object.<Rate> | The rate that was purchased by the customer. |
qr_code_url |
string | If the label has a QR Code, this will be the url that is encoded on it. |
rates |
Array.<Rate> | An array of rates that are returned when the delivery intent was created. |
recipient |
Object.<Entity> | The recipient object. This is the person who is getting the package. |
refund_status |
string | The refund status if one was requested. Funds will be credited back to the account after the refund status is approved by the carrier. Dispatch couriers refunds are immediate. |
sender |
Object.<Entity> | The object representing the sender, which is the entity that initially sent that package. |
shipment_date |
integer | The time in seconds from Epoch in seconds of the shipment date. |
status |
string | The tracking status for the delivery. For a complete list see the github readme. |
substatus |
string | The tracking substatus for the delivery. This gives much more detail about the package whereabouts. For a complete list see the github readme. |
test |
boolean | If this was a test delivery. |
tracking_notifications |
boolean | Indicates if dispatch will send update emails for the delivery. This value is set on your dashboard https://app.getdispatch.app/settings/company/branding. |
tracking_number |
string | The tracking number for the delivery. |
tracking_status |
Object.<Tracker> | The current tracking status for this delivery. |
tracking_updates |
Array.<Tracker> | An array of all of the tracking updates for this delivery including the current one. |
type |
string | The type of delivery this is: "traditional" or "marketplace". |
updated_at |
integer | Epoch time in seconds. |
value |
integer | The declared value of this delivery. |
- To Do:
-
- {Object} customs_declaration - Any customs declarations for international shipping.
- {Object} insurance - The object representing the insurance.
# Entity
The Entity object, which describes a company or person
Properties:
Name | Type | Description |
---|---|---|
id |
string | The entity ID |
address |
Object | The address details of this entity. |
address_line1 |
string | |
address_line2 |
string | |
city |
string | |
formatted_address |
string | The combined address string including city, state, and zipcode. |
place_name |
string | In most cases this is the same as the city. For U.S. shipment, just ignore this. |
state |
string | The full string of the the state such as "California or New York". |
state_abbreviation |
string | The abbreviation of the the state such as "CA or "NY". |
state_name |
string | @deprecated This is now just called state. |
street_name |
string | The name of the street from address_line1. |
street_number |
string | The number of the street from address_line1. |
street_suffix |
string | Will we the last part of the street name like "St" or "Ln". |
textarea |
string | If you will pre-fill an html textarea with the string, this includes the return values for the address to format into multiple lines. |
timezone |
string | The tz format for this addresses timezone. https://en.wikipedia.org/wiki/Tz_database |
verified |
boolean | If this address was verified with USPS. |
zipcode |
string | The address zipcode. This is the same value as postal_code. |
email |
string | The email address to contact this entity. |
name |
string | The name of this entity. |
phone |
string | null | The phone number to contact this entity. |
logo_url |
string | null | The source for the logo. The image is a 256 x 256 square png. |
logo_url_trimmed |
string | null | This logo is trimmed by us to remove the white space. Best used in emails. One of the sides is 256px, depending on the logo's shape. |
# Item
The Item Object. This is optional but allows you to specify what the items are that are packaged in your box. In the future, this will be used to help facilitate one-click returns.
Properties:
Name | Type | Attributes | Description |
---|---|---|---|
name |
string |
<optional> |
The name of this item. |
sku |
string |
<optional> |
The item sku. |
price |
integer |
<optional> |
The item's price as an integer. |
value |
integer |
<optional> |
The item's declared values as an integer. |
product_id |
string |
<optional> |
The id used to identify this product on your inventory system. |
variant_id |
string |
<optional> |
If this is a specific variant of a product id. |
length |
integer |
<optional> |
The length of the item in inches. Can use this for cheaper return labels if we know the box can be smaller. |
width |
integer |
<optional> |
The width of the item in inches. Can use this for cheaper return labels if we know the box can be smaller. |
height |
integer |
<optional> |
The height of the item in inches. Can use this for cheaper return labels if we know the box can be smaller. |
weight |
integer |
<optional> |
The weight of the item in pounds. Can use this for cheaper return labels if we know the box can be lighter. |
# NewAddress
The New Address Object. When creating a new address, you can either send the address as a string value or an object. If you're choosing an object, below are the properties you need to provide.
Properties:
Name | Type | Attributes | Description |
---|---|---|---|
address_line1 |
string | The street address for this delivery. |
|
address_line2 |
string |
<optional> |
The second line of the street address if needed. |
city |
string | The name of the city. |
|
state |
string | The state. This can be the full state name like California or an abbreviation like NY. |
|
zipcode |
string | The zipcode. Technically this is optional but highly recommended you add this because it makes the address parser much more accurate. |
# Parcel
The Parcel Object. When you create a parcel or retrieve a delivery, you'll always be referencing an array of parcels
Properties:
Name | Type | Attributes | Description |
---|---|---|---|
package_type |
String |
<optional> |
The type of box you're sending the items in. If you are using a box provided by a carrier, you'll only recieve rates from that carrier plus any on-demand couriers, if avaible. |
length |
integer | The length of the parcel in inches. |
|
width |
integer | The width of the parcel in inches. |
|
height |
integer | The height of the parcel in inches. |
|
weight |
integer | The weight of the parcel in pounds. |
|
special_handling |
string |
<optional> |
Any special handling instructions that will be placed on the label. Limited to 12 characters. If you add more than 12 characters, we'll just use the first 12 instead of returning an error. The reason for the limit is that this is the most amount of characters that we can fit within the bounds of the current label. |
item_description |
string |
<optional> |
A description of what you're sending like "Coffee". This can prove useful for basic analytics later on and is a nice touch for the tracking email that can let the recipient know what is in the box. |
items |
Array.<Item> |
<optional> |
you can optionally include items that are in the box. This can be used for one click returns and custom disposition codes in the future. |
# Profile
The Profile Object. This describes the profile of the sender who owns the API key
Properties:
Name | Type | Description |
---|---|---|
id |
String | The ID for this sender |
branding |
Object | This describes how branding is used by the user |
emails |
Boolean | If this sender has their logo displayed on email. Requires a Pro plan |
labels |
Boolean | If this sender has their logo displayed on shipping labels. Requires a Pro plan |
tracking_notifications |
Boolean | If this sender wants dispatch to send tracking updates to recipients |
lead_time_hours |
Integer | The lead time this sender requires for deliveries |
carrier_rate_card |
Array.<Object> | An array of objects that describe the rate cards this user has |
carrier_rate_card[].carrier_id |
String | The ID of the carrier this rate card is for |
carrier_rate_card[].active |
Boolean | If this rate card is currently active |
carrier_rate_card[].rate_card_id |
String | null | The ID of the rate card. The value is null if this rate card is for a Dispatch provided rate card |
logo_url |
String | the logo url for the sender |
logo_url_trimmed |
String | the logo url for the sender with the wight space trimmed |
requirements |
Object | Shows which requirements are needed for this sender. Some features may be unavaible if there are outstanding requirements |
required_now |
Array.<String> | A list of all of the requirements that are due now. No deliveries can be created if there are requirements due |
pending_verification |
Array.<String> | A list of requirements that are pending verification. These are normally resolved within 24 hours |
errors |
Array.<String> | These are errors that the account has. Accounts with errors could result in features of the account being disabled, such as the ability to purchase shipping labels |
required_later |
Array.<String> | These are items that will be due in the future. |
profile |
Object | = An object that reflects the profile information for this sender |
support_phone |
String | The phone number for this sender to be contacted for support |
support_email |
String | The email for this sender to be contacted for support |
name |
String | The name of this sender |
website |
String | The website for this sender |
address |
Object.<Address> | The headquarters address for the sender. |
created_at |
Integer | The time in seconds from Epoch that this sender was created |
updated_at |
Integer | The time in seconds from Epoch that this sender was last updated |
labels |
Object | The preferences this user has for shipping labels |
format |
String | The format the labels will come in for the sender. |
# Rate
The Rate object
Properties:
Name | Type | Description |
---|---|---|
amount |
integer | The price of this rate as an integer with discount applied. (e.g., $15.76 would be represented as 1576). |
billed_amount |
integer | The price of this rate as an integer without discounts applied. (e.g., $15.76 would be represented as 1576). This is the total amount that Dispatch charged your payment information in file. |
sender_discount |
integer | The discount for this rate as an integer that you have specified. (e.g., $15.76 would be represented as 1576). This gets calculated based on your settings on the Dispatch dashboard. |
carrier_account |
string | null | The carrier account / custom rate card that was used to price this rate. |
checkout_total |
integer | The total cart/checkout value you submitted as an integer (e.g., $15.76 would be represented as 1576). This value is used to determine the free shipping tier that you can set up on the Dispatch dashboard. |
created_at |
integer | Epoch time in seconds. |
currency |
string | The currency of this rate card as lowercase ISO 4217 format https://en.wikipedia.org/wiki/ISO_4217 |
dispatch |
boolean | If this rate was originated by dispatch APIs. |
service_level |
Object | Describes how long the delivery will take. |
id |
string | The ID of the service level. Something like "dispatch_same_day". |
name |
string | The human readable name of the service level. Something like "Same Day" or "USPS Overnight". |
arrives_by |
integer | Epoch time seconds when this delivery is expected to arrive at its destination. |
days |
integer | The amount of days that this delivery is estimated to take. |
guaranteed |
boolean | If this delivery is guaranteed by the |
pickup_at |
integer | null | Epoch time in seconds when this order will be picked up. |
terms |
string | The human readable string for the delivery date and time. For example: "Today by 9pm". |
grace_period |
Object | The grace period that an on_demand courier will wait for and the fees for going over it. |
billed_amount |
integer | The amount that you were charged for going over a courier's grace period. |
fee |
integer | null | The amount that you were charged for going over a courier's grace period. |
minutes |
integer | null | The amount of minutes that the grace period is good for. |
payment_status |
integer | null | The status of your payment. |
wait_seconds |
integer | null | The amount of seconds the courier waited for. |
id |
string | the id of this rate. This id will be passed to dispatch to purchase the rate. |
invoice |
Object | null | If the rate is generated by an on demand courier from dispatch, this will be a breakdown of the total cost. Otherwise will be null. |
additional_items_fee |
integer | The cost for additional items if the order contained multiple packages and the courier changes this fee. |
dropoff_fee |
integer | The fixed dropoff fee that this courier charges. |
dropoff_rate |
integer | The rate this courier charges for the distance from pickup location to dropoff location. |
local_fee |
integer | If there are any local fees that are charged in the pickup or dropoff city. |
pickup_fee |
integer | The fixed pickup fee that this courier charges. |
pickup_rate |
integer | The rate this courier charges for the distance from to get to the pickup location. |
rate_card |
string | null | The id of the rate card that was used for this invoice. |
subtotal |
integer | The total before taxes. |
tax |
integer | The tax charged for this delivery. |
toll |
integer | Any tolls that were charged for this delivery. |
total |
integer | The final total for this invoice. This number is the same as the "amount". |
lead_time_hours |
integer | The amount of hours that are needed in advance before the courier can get the the pickup destination. |
on_demand |
boolean | If this rate is an on demand courier. |
pickup_at |
integer | @deprecated Epoch time in seconds when this order will be picked up. Same as service_level.pickup_at. |
provider |
Object | The provider is the courier or carrier that will be conducting the delivery. |
id |
string | The ID of this provider. |
logo_url |
string | The logo that of this provider. |
name |
string | The name of this provider. |
support_email |
string | The email that can be used to contact this provider. |
support_phone |
string | null | The support phone number that can be used to contact this provider. |
support_url |
string | null | The url that this provider has for support. |
test |
boolean | If this was a test delivery or not. |
# Response
The Response Object. Every dispatch response will always have the same object that is returned.
Properties:
Name | Type | Description |
---|---|---|
message |
string | The message that could be displayed to an end user if the response is successful or ends in an error. |
data |
Object | Array | The data that was requested if any. If requesting lots of data like deliveries, the data will be formatted an an Array. If you're just pulling one item by an ID like a specific delivery, the response will be an Object. |
status |
integer | The html status code for the response. |
errors |
Array | If there were errors, the array will be filled with the property names that caused the error. |
error_code |
string | null | The server error code. |
pagination |
Object | null | when pulling multiple object like many deliveries, the pagination will let you know if there are more items that can be pulled from the database. |
limit |
integer | the limit that was applied to the pagination. The default is 15 and the max is 100. |
current_page |
integer | The current page this pagination is on. If the limit is 15 and the current_page is 3, you know you're looking at items 30 - 45. |
has_more |
integer | Lets you know when you can paginate further. |
count |
integer | The amount of items that were returned. |
# Tracker
The Tracker Object. This describes a tracking update.
Properties:
Name | Type | Description |
---|---|---|
address |
Object | This is a basic address field that gives the general location of the item. |
address_line1 |
String | null | The street address. Many carriers do not support this field and it can often be null. |
city |
String | Name of the city. |
state |
String | Name of the state, not abbreviated. |
zipcode |
String | The zipcode. |
comment |
String | null | If the courier added a comment for this update it will be here. These comments are not filtered by Dispatch at the moment, so it's safer to use the |
message |
String | The human readable message about this status given by Dispatch. |
status |
String | The status string. |
substatus |
String | The sub_status string. |
images |
Array.<(String)> | An array that includes any images that were added to this tracker. If there are no images, the array will be empty. |