3/21/23, 1:12 PM Shiplify - Shiplify API v2 Documentation

You are currently viewing the latest version of the API documentation (v2). View the previous
version (v1) here. (/docs/api/v1)

Overview

Business Process Documentation

Use Cases

Process Implementation

Status

Tariff Item Codes

Dock Access

Forklift

Con dence Codes

Exemptions

Recommendations
When should I hit the API?

Which tariff items should I apply?

How will Shiplify send manually reviewed results back to me?

Optional: x and re-send

Technical Documentation

Overview
Authentication

Rate Limits

Request (HTTP) Headers

Tariff Items

Response (HTTP) Status Codes

Request Stubbing (with a "Test" API key)

Recommendations

The Create Shipment endpoint

Sample request

Parameters

Response body

https://tariffs.shiplify.com/docs/api/v2 1/33
3/21/23, 1:12 PM Shiplify - Shiplify API v2 Documentation

Expected response times

Error handling

Receiving updates via webhooks

The Search Shipments endpoint

Sample request

Parameters

Response body

Error handling

The Get Shipment endpoint

Sample request

Parameters

Response body

The Create Quote endpoint

Sample request

Parameters

Response body

Error handling

The Create Location endpoint

Sample request

Parameters

Response body

Error handling

Frequently Asked Questions

Support

Shiplify API Documentation (v2)

Overview
Shiplify’s API allows you to access our limited access, residential, dock access and forklift location
information in real-time and integrate it with your existing billing and operational processes.

https://tariffs.shiplify.com/docs/api/v2 2/33
3/21/23, 1:12 PM Shiplify - Shiplify API v2 Documentation

Business Process Documentation

Use Cases
We identify limited access and residential locations in real-time and return your corresponding
accessorial codes on a per shipment basis. We also return whether a location has a dock or forklift.
This information can be used to inprove billing for liftgate locations. Our goal is to help you invoice
accessorial fees correctly the rst time, every time.

Upon implementation of our API, you will receive the following bene ts:

Invoicing
Immediately identify accessorial revenue opportunities
Reduce disputes and rebilling
Operations
Schedule next-day residential delivery appointments
Load shipments onto properly-equipped trucks
Identify miskeyed bills before sending a bad address to your routing and scheduling
system

Process Implementation
You send a request with information about a single shipment (primarily shipper/consignee address
information). Then Shiplify returns the following information (for both the shipper and consignee) to
help you determine whether an accessorial fee should be applied.

Status
Based on the information you send to us, we will return one of two statuses:

Complete
In most cases, our API will return a complete status. This means that we have nished processing
the shipment, and you will not receive further updates for it. We recommend you make a nal decision
about which accessorials to apply at this time, based on Shiplify’s provided recommendations.

Processing
Sometimes, our API will return a processing status. This means we’ve enqueued the shipment for
manual review, and you should wait for an update from Shiplify before updating your freight bill.
When this happens, we include possible accessorials that may apply to the shipment, in case this
information is helpful in other parts of your process. Please see the Recommendations section below.

Tariff Item Codes

We return identi ed accessorial fees as a list of "tariff item" codes, derived from your published tariff
rules. To set up or change your tariffs (/providers/32/tariff-items), please contact us at
[email protected] (mailto:[email protected]).

Dock Access

https://tariffs.shiplify.com/docs/api/v2 3/33
3/21/23, 1:12 PM Shiplify - Shiplify API v2 Documentation

We return dock access information for both the shipper and consignee location. This value will be
'yes' or 'no' with a corresponding con dence code.

When we do not have dock access information for a location, we will return an empty json object
( {} ).

Forklift
We return forklift information for both the shipper and consignee location. This value will be 'yes' or
'no' with a corresponding con dence code.

We will only return forklift information if we believe the location does not have access to a loading
dock.

Confidence Codes
Shiplify returns a con dence code with each attribute we identify. These are two-character codes that
represent our con dence in the corresponding attribute. The rst character (A or U) indicates
whether we were able to con rm the location of the provided address. The second character (1-4)
indicates our relative level of con dence in the accuracy of the attribute.

Location Attribute Average

Con dence code veri ed? veri ed? accuracy Recommended action

A1   99.5% Finalize the bill

A2   76% Wait for update from Shiplify

A3   70% Wait for update from Shiplify

A4   76% * Wait for update from Shiplify

U1   89% Wait for update from Shiplify

U2   58% Wait for update from Shiplify

U3   33% Wait for update from Shiplify

U4   80% * Wait for update from Shiplify

Results that meet Shiplify's data quality standards

A1 results are those that we have con rmed both the location and applicable attribute, and for which
no further (manual) review is required. When an A1 result is returned, the tariff item is correct
approximately 99.5% of the time.

A blank result (an empty list of shipper or consignee tariff items) indicates that Shiplify is fully
con dent that no tariff items should be charged for the location in question.

Results that do not meet Shiplify's data quality standards

Any location that receives one of the following con dence codes will be manually reviewed by the
Shiplify team. Our updated results will be made available during the following business day.

https://tariffs.shiplify.com/docs/api/v2 4/33
3/21/23, 1:12 PM Shiplify - Shiplify API v2 Documentation

NOTE: If our team is unable to verify either the location of the address or the location type at that
address, the shipper/consignee will retain its current con dence code and the shipment will be
updated to a status of complete .

An "A" result ( A2 - A4 ) means that we have con rmed the location.

A2 results (correct approximately 76% of the time) have been location-veri ed, and we have a strong
reason to believe that the corresponding attribute is likely, but we have not fully veri ed whether the
attribute should be applied.

A3 results (correct approximately 70% of the time) have been location-veri ed, and we have some
reason to believe that the corresponding attribute is likely, but we have not fully veri ed whether the
attribute should be applied.

A4 results indicate that we were able to verify the location, but received con icting predictions
about which attribute should be applied. For example, if we received data from one source indicating
that the location was a school (limited access tariff) and from another source that it was a residence
(residential tariff), Shiplify would return the result with an A4 con dence code. When an A4 result is
returned, it is approximately 76% likely that one of the predicted attribute should be applied (but we
have not yet veri ed which one).

A "U" result ( U1 - U4 ) can happen when the provided address was either invalid or ambiguous. Other
times it is because the address cannot be located. Consider correcting the address and re-sending the
shipment.

U1 results (correct approximately 89% of the time) have not been location-veri ed, but we have a
strong reason to believe that the corresponding attribute is likely.

U2 results (correct approximately 58% of the time) have not been location-veri ed, but we have
reason to believe that the corresponding attribute is possible.

U3 results (correct approximately 33% of the time) have not been location-veri ed, but we have
some reason to believe that the corresponding attribute is possible.

U4 results indicate that we were unable to verify the location, and received con icting predictions
about which attribute should be applied. When a U4 result is returned, it is approximately 80% likely
that one of the predicted attribute should be applied.

Exemptions
Shiplify allows users to exempt locations or customer codes within our Carrier Portal. If a shipment is
going to a location or customer with an exemption, we will return an exempt ag via the API.

Recommendations

When should I hit the API?

We recommend that you hit the API during your freight bill entry process, as soon as all relevant
information is entered in the freight bill.

Which tariff items should I apply?

https://tariffs.shiplify.com/docs/api/v2 5/33
3/21/23, 1:12 PM Shiplify - Shiplify API v2 Documentation

We recommend that you apply a tariff item only when all of the following are true:

The shipment's status eld is complete and

The tariff item's confidence is A1 and
The tariff item's exempt ag is false

Many shipments with a status of complete will have no identi ed tariff items. This means that
Shiplify is fully con dent that no tariffs will apply to these shipments, and it's ok to nalize the freight
bill.

How will Shiplify send manually-reviewed results back to me?

For shipments with status of processing , we can send you updates in a few different ways:

real-time via webhooks (recommended),

via a delayed daily le uploaded to an FTP server, and
via your downloads page (/downloads).

To change how you receive updates, contact [email protected] (mailto:[email protected])

Optional: fix and re-send

"U" confidence codes

When we can't verify the location of an address, we assign a con dence code in the U1 - U4 range to
its tariff items. When this happens, we recommend prompting a user to check the address, then re-
submit it to the API.

Often, once you re-submit the correct address information, we can provide fully-veri ed information.
(Note: when you re-submit a shipment, you will see multiple entries with the same pro number in the
shipments interface.)

Identifying invalid or incomplete address information earlier can prevent various operational issues.
Integrating these steps in your process can help you prevent headaches down the line.

Updated information
Sometimes corrections need to be made to shipment information after it has already been sent to us.
We recommend you resend any updated shipments. (Note: when you re-submit a shipment, you will
see multiple entries with the same pro number in the shipments interface.)

Technical Documentation
Shiplify’s API is a REST (https://en.wikipedia.org/wiki/Representational_state_transfer) API, receiving
and returns data in JSON (https://en.wikipedia.org/wiki/JSON) format. It requires authentication and
requests are subject to rate limits.

https://tariffs.shiplify.com/docs/api/v2 6/33
3/21/23, 1:12 PM Shiplify - Shiplify API v2 Documentation

Overview

What's changed since V1

There are a few important differences to take note of when switching from version 1 to 2. The main
changes are listed below with an example response for each version.

1. shipper and consignee

The v1 API returns shipper and consignee as nested elds within tariff_items ,
dock_access and forklift . The v2 API returns shipper and consignee as top-level elds.

2. tariff_items contents
The v1 API returns tariff_items as an array of objects with the potential to have multiple
exemptions and con dence codes. The v2 API returns tariff_items as an object with the potential
to have multiple codes but only has 1 exemption and con dence code.

3. When no tariff items apply to the location...

The v1 API returns an empty array of tariff_items , with no con dence codes. The v2 API returns
an empty array of tariff_items.codes , with a con dence level and exemption information.

https://tariffs.shiplify.com/docs/api/v2 7/33
3/21/23, 1:12 PM Shiplify - Shiplify API v2 Documentation

V1
{
"id": "4c0ec684-47a8-4d61-8749-f71985a79504",
"pro_number": "1234567890",
"pickup_date": "2000-01-01",
"dock_access": {
"shipper": {
"value": "yes",
"confidence": "A1"
},
"consignee": {
"value": "no",
"confidence": "A1"
}
},
"forklift": {
"shipper": {},
"consignee": {
"value": "no",
"confidence": "A1"
}
},
"tariff_items": {
"shipper": [],
"consignee": [
{
"code": "RESD",
"confidence": "A1",
"exempt": false
}
]
},
"status": "complete"
}

https://tariffs.shiplify.com/docs/api/v2 8/33
3/21/23, 1:12 PM Shiplify - Shiplify API v2 Documentation

V2
{
"id": "4c0ec684-47a8-4d61-8749-f71985a79504",
"pro_number": "1234567890",
"pickup_date": "2000-01-01",
"shipper": {
"dock_access": {
"value": "yes",
"confidence": "A1"
},
"tariff_items": {
"codes": [],
"confidence": "A1",
"exempt": false
}
},
"consignee": {
"dock_access": {
"value": "no",
"confidence": "A1"
},
"forklift": {
"value": "no",
"confidence": "A1"
},
"tariff_items": {
"codes": ["RESD"],
"confidence": "A1",
"exempt": false
}
},
"status": "complete"
}

Authentication
All API requests require authentication via API key, sent as an X-Api-Token HTTP header. To
manage your API keys, please visit your dashboard.

Each key has a type of either Test or Live . Test keys allow you to test your API integration
without creating any shipment records. Responses for Test keys are samples only. When your
integration is fully tested, switch to a Live key to begin creating shipments and receiving live
responses.

Keys that have revoked status will receive a response of access denied.

https://tariffs.shiplify.com/docs/api/v2 9/33
3/21/23, 1:12 PM Shiplify - Shiplify API v2 Documentation

Keep all your API keys secure and do not share them. Shiplify recommends you generate a separate
API key for each system that will be making API requests. That way if you need to revoke a key, it will
only affect access for a single system.

When an invalid API key is supplied, the following error message will be returned with a 401
Unauthorized HTTP status code:

{
"errors": {
"api_key": [
"Invalid API key"
]
}
}

Rate limits
API requests are rate-limited across the total number of requests you send, including both test and
live requests. When your API access is set up, Shiplify will con gure per-second and per-day rate
limits. Both limits are calculated on a rolling basis; for example per-day usage is calculated as the
number of requests in the last 24 hours (not the number of requests since midnight).

You can view your current rate limits on your API keys page (/api-keys). Contact your account
manager or email [email protected] (mailto:[email protected]) if you would like either rate
limit increased.

When you have exceeded either your per-day or per-second rate limit, the following error message
will be returned with a 429 Too Many Requests HTTP status code:

{
"errors": {
"rate_limit": [
"limit of 10 requests per second exceeded"
]
}
}

Request (HTTP) Headers

All requests require certain HTTP headers:

Host: tariffs.shiplify.com
Tells Shiplify’s web server that the request is meant for the tariffs.shiplify.com service.

Content-Type: application/json
Tells Shiplify’s application server that you are sending your request in JSON format, as required by the
billing API.

Accept: application/json

https://tariffs.shiplify.com/docs/api/v2 10/33
3/21/23, 1:12 PM Shiplify - Shiplify API v2 Documentation

Tells Shiplify’s web server that you expect to receive your response in JSON format.

X-Api-Token: [your-api-token]
Provides your Test or Live API token, for authentication purposes.

Tariff items
Each API endpoint includes a list (array) of tariff_items for the shipper and consignee . The
tariff item code represents the tariff items that Shiplify is recommending. Each recommended tariff
item is returned with a two-character confidence_code .

Response (HTTP) status codes

All responses are returned with a numeric HTTP status header
(https://en.wikipedia.org/wiki/List_of_HTTP_status_codes).

A response with a 200 status means the request was valid and accepted by Shiplify.

Status codes in the 4XX range indicate a invalid request (an error by the requester). Codes in the
5XX range indicate that something failed on the server side (an error by Shiplify). 5XX requests can
(and should!) be re-tried at a later time.

Common HTTP status codes and their explanations are as follows:

200 OK
Everything worked.

400 Bad Request

The data you supplied could not be parsed as valid JSON. Please check the format and try again.

401 Unauthorized
The request could not be authorized. The API key was either provided incorrectly or did not match
any active API keys.

403 Forbidden
You do not have permission for the request you have attempted.

404 Not Found

The URL you are requesting was not found. Please correct the URL and try again.

408 Request Timeout

Your request timed out. Please try again.

422 Unprocessable Entity

The syntax of the request was incorrect or the request was missing a required parameter. This
typically indicates that there was an error while validating the presence or format of one or more
elds.

429 Too Many Requests

You have exceed either your per-day or per-second rate limit. Please wait or contact
[email protected] (mailto:[email protected]) to request a rate limit increase.

https://tariffs.shiplify.com/docs/api/v2 11/33
3/21/23, 1:12 PM Shiplify - Shiplify API v2 Documentation

500 Internal Server Error

The server encountered an error, and has noti ed the Shiplify team. We will x the issue as soon as
possible. We will post updates to our status page (https://status.shiplify.com) as they are available.

502 Bad Gateway

We are experiencing issues with an upstream infrastructure provider. We will post updates on our
status page (https://status.shiplify.com) as they are available.

503 Service Unavailable

The API is overloaded or down for maintenance. We will post updates on our status page
(https://status.shiplify.com) as they are available.

504 Gateway Timeout

We are experiencing issues with an upstream infrastructure provider. We will post updates on our
status page (https://status.shiplify.com) as they are available.

Request stubbing (with a Test API key)

When using a Test API key, it is possible to stub out various aspects of API responses by customizing
the pro_number eld. This is intended to make it easy to test various scenarios when integrating
with the API.

This functionality is available for the Create Shipment and Search Shipments API endpoints.

Stubbing shipper tariff items

In the pro_number eld, include "ST" followed by any alphanumeric tariff code. For example, setting
the pro_number to "XYZSTABC123" would result in a code of "ABC123" within
tariff_items.shipper .

Stubbing consignee tariff items

In the pro_number eld, include "CT" followed by any alphanumeric tariff code. For example, setting
the pro_number to "ZYXCTDEF456" would result in a code of "DEF456" within
tariff_items.consignee .

Stubbing a confidence level

A con dence level can be speci ed for any stubbed tariff item by appending a colon plus the
con dence level after the tariff item. For instance, if the pro_number contains "STABC123:U3", this
indicates that there should be a shipper tariff with code "ABC123" with a con dence code of "U3".
Any valid con dence code can be speci ed in this way.

Stubbing exempt status

Any stubbed tariff item can be stubbed as exempt by including "SX" (for shipper exempt) or "CX" (for
consignee exempt) in the pro_number eld. For instance, if the speci ed pro_number is
"XYZSTABC123_CX" then the results would include an entry in tariff_items.shipper with code
"ABC123" and exempt would be set to true for that tariff item.

Recommendations

https://tariffs.shiplify.com/docs/api/v2 12/33
3/21/23, 1:12 PM Shiplify - Shiplify API v2 Documentation

Shiplify recommends setting up requests to the API using a job queue. This simpli es the process of
retrying requests in the event of an outage, as well as complying with rate limits.

The Create Shipment endpoint

The Create Shipment API endpoint allows you to send information about a shipment to Shiplify, and
receive information about which location-based attributes apply to the shipper and consignee
locations.

Sample request
POST /api/v2/shipments
Host: tariffs.shiplify.com
Content-Type: application/json
Accept: application/json
X-Api-Token: [your-api-token]

{
"shipment": {
"pro_number": "1234567890",
"pickup_date": "2000-01-01",
"shipper_name": "SHIPLIFY",
"shipper_street_address": "1425 ELLSWORTH INDUSTRIAL BLVD",
"shipper_city": "ATLANTA",
"shipper_state": "GA",
"shipper_postal_code": "30318",
"shipper_customer_number": "8675309",
"shipper_requested_liftgate": 0,
"consignee_name": "VANDALEY INDUSTRIES",
"consignee_street_address": "129 W 81ST ST",
"consignee_city": "NEW YORK",
"consignee_state": "NY",
"consignee_postal_code": "10024",
"consignee_customer_number": "1675480",
"consignee_requested_liftgate": 1,
"include_dock_access": 1,
"include_tariff_items": 1,
"include_location_types": 0,
"weight": 500,
"transit_days": 1,
"pieces": 2
}
}

For your convenience, the above request can be made using cURL as follows. Add your Test API key
to this cURL request to test.

https://tariffs.shiplify.com/docs/api/v2 13/33
3/21/23, 1:12 PM Shiplify - Shiplify API v2 Documentation

curl "https://tariffs.shiplify.com/api/v2/shipments" \
-X POST \
-H "Host: tariffs.shiplify.com" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "X-Api-Token: [your-api-token]" \
-d '{"shipment":{"pro_number":"1234567890","pickup_date":"2000-01-01","sh
ipper_name":"SHIPLIFY","shipper_street_address":"1425 ELLSWORTH INDUSTRIAL
BLVD","shipper_city":"ATLANTA","shipper_state":"GA","shipper_postal_cod
e":"30318","shipper_customer_number":"8675309","shipper_requested_liftgat
e":0,"consignee_name":"VANDALEY INDUSTRIES","consignee_street_address":"129
W 81ST ST","consignee_city":"NEW YORK","consignee_state":"NY","consignee_po
stal_code":"10024","consignee_customer_number":"1675480","consignee_request
ed_liftgate": 1,"include_dock_access":1, "include_tariff_items":1,"weight":
500,"pieces":2,"transit_days":1}}'

Parameters
shipment.pro_number (required)
The pro number of the shipment

shipment.pickup_date (required)
The pickup date (YYYY-MM-DD)

shipment.shipper_name (required)
The shipper's name

shipment.shipper_street_address (required)
The shipper's street address (line 1)

shipment.shipper_street_address2
The shipper's street address (line 2)

shipment.shipper_city (required)
The shipper's city

shipment.shipper_state (required)
The shipper's state abbreviation

shipment.shipper_postal_code (required)
The shipper's postal code

shipment.shipper_customer_number
The shipper's customer number

shipment.shipper_terminal_code
The origin terminal code (pick-up terminal)

shipment.shipper_requested_liftgate

https://tariffs.shiplify.com/docs/api/v2 14/33
3/21/23, 1:12 PM Shiplify - Shiplify API v2 Documentation

The shipment origin requires a liftgate as requested by customer

shipment.consignee_name (required)
The consignee's name

shipment.consignee_street_address (required)
The consignee's street address (line 1)

shipment.consignee_street_address2
The consignee's street address (line 2)

shipment.consignee_city (required)
The consignee's city

shipment.consignee_state (required)
The consignee's state abbreviation

shipment.consignee_postal_code (required)
The consignee's postal code

shipment.consignee_customer_number
The consignee's customer number

shipment.consignee_terminal_code
The destination terminal code (delivery terminal)

shipment.consignee_requested_liftgate
The shipment destination requires a liftgate as requested by customer

shipment.include_dock_access (default: false)

Boolean eld to turn on dock access and forklift information. This is part of a (beta) add-on feature.
You must have authorization to access the dock access information. For more information, contact
[email protected] (mailto:[email protected])

shipment.include_tariff_items (default: true)

Boolean eld to turn on tariff item information

shipment.include_location_types (default: false)

Boolean eld to turn on location type information

shipment.weight
The weight of the freight (in pounds)

shipment.pieces
The number of pieces included in the freight

shipment.transit_days
The number of transit days

Response body
https://tariffs.shiplify.com/docs/api/v2 15/33
3/21/23, 1:12 PM Shiplify - Shiplify API v2 Documentation

Responses are returned in JSON format, with the following structure. (Dock access and forklift
information will only be returned for authorized users):

{
"id": "4c0ec684-47a8-4d61-8749-f71985a79504",
"pro_number": "1234567890",
"pickup_date": "2000-01-01",
"shipper": {
"dock_access": {
"value": "yes",
"confidence": "A1"
},
"tariff_items": {
"codes": [],
"confidence": "A1",
"exempt": false
}
},
"consignee": {
"dock_access": {
"value": "no",
"confidence": "A1"
},
"forklift": {
"value": "no",
"confidence": "A1"
},
"tariff_items": {
"codes": ["RESD"],
"confidence": "A1",
"exempt": false
}
},
"status": "complete"
}

Expected response times

Response times vary by request. In particular, Shiplify gathers data in real-time for many locations,
which can require more time to process the request.

In general, you can expect:

the median response time to be under 500ms

approximately 93% of requests to return within 1 second
approximately 98% of requests to return within 3 seconds

Error handling

https://tariffs.shiplify.com/docs/api/v2 16/33
3/21/23, 1:12 PM Shiplify - Shiplify API v2 Documentation

When invalid shipment data is supplied (for example, missing a required eld), one or more of the
following error messages will be included, with a 422 Unprocessable Entity HTTP status code:

{
"errors": {
"pro_number": [
"can't be blank",
"must be at least one character"
],
"shipper_name": [
"can't be blank"
],
"shipper_street_address": [
"can't be blank"
],
"shipper_city": [
"can't be blank"
],
"shipper_state": [
"can't be blank"
],
"shipper_postal_code": [
"can't be blank"
],
"consignee_name": [
"can't be blank"
],
"consignee_street_address": [
"can't be blank"
],
"consignee_city": [
"can't be blank"
],
"consignee_state": [
"can't be blank"
],
"consignee_postal_code": [
"can't be blank"
],
"pickup_date": [
"must be in YYYY-MM-DD format"
],
"webhook_url": [
"must start with https:// or http://"
]
}
}

https://tariffs.shiplify.com/docs/api/v2 17/33
3/21/23, 1:12 PM Shiplify - Shiplify API v2 Documentation

Receiving updates via webhooks

Shiplify is capable of notifying a webhook as soon as manual review of a shipment is complete. This
allows you to receive updated tariff information as soon as it is available, to speed up billing and
operations processes.

You can activate webhook noti cations for a shipment by specifying a webhook_url as part of your
API request.

Webhook noti cations are sent as soon as Shiplify completes manual review of the shipment--as soon
as the status eld changes from processing to complete . If the status of the initial API response
was complete , a webhook noti cation will not be sent.

When using a Test API key and supplying a webhook_url , we will attempt to send a webhook
within 5 minutes of your initial request. The body of the test webhook request will be the same as the
response to your initial API request. You can use request stubbing to customize this response, for
testing purposes. If you are having trouble receiving webhook responses, check your network and
rewall rules, then feel free to contact [email protected] (mailto:[email protected]).

Webhook request / response

When specifying https://www.example.com/path/to/webhook as the value for webhook_url ,
the following request would be sent once manual processing is complete.

The format of the body of the webhook request matches the format of the original API response (with
updated values within tariff_items.shipper and tariff_items.consignee ).

https://tariffs.shiplify.com/docs/api/v2 18/33
3/21/23, 1:12 PM Shiplify - Shiplify API v2 Documentation

POST https://www.example.com/path/to/webhook
Content-Type: application/json
Accept: application/json
X-Shiplify-Signature: sha1=[sample-signature]

{
"id": "4c0ec684-47a8-4d61-8749-f71985a79504",
"pro_number": "1234567890",
"pickup_date": "2000-01-01",
"shipper": {
"dock_access": {
"value": "yes",
"confidence": "A1"
},
"tariff_items": {
"codes": [],
"confidence": "A1",
"exempt": false
}
},
"consignee": {
"dock_access": {
"value": "no",
"confidence": "A1"
},
"forklift": {
"value": "no",
"confidence": "A1"
},
"tariff_items": {
"codes": ["RESD"],
"confidence": "A1",
"exempt": false
}
},
"status": "complete"
}

Checking signatures
In order to authenticate that a webhook noti cation you receive has in fact come from Shiplify
directly, Shiplify signs each webhook with a X-Shiplify-Signature header. This header is a hash of
the request body and your API Secret, found here (/api-keys). Note that your API Secret is the same
regardless of which API key you use to send requests.

To verify the signature of the request, you can compute the signature yourself as follows:

https://tariffs.shiplify.com/docs/api/v2 19/33
3/21/23, 1:12 PM Shiplify - Shiplify API v2 Documentation

def signatures_match?(signature_from_header, request_body)

api_secret = ENV['SHIPLIFY_API_SECRET']
digest = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha1'), api_secret,
request_body)
calculated_signature = 'sha1=' + digest
Rack::Utils.secure_compare(calculated_signature, signature_from_header)
end

Your language and implementation details may differ from this code. There are a couple important
things to note, though:

The hash you receive will begin with sha1= , and will require your API Secret and the request
body (as a string).
We recommend against using simple == comparison, and instead recommend using something
like Rack::Utils.secure_compare to avoid vulnerability to certain timing attacks.

Delivery attempts and retries

Shiplify attempts to deliver webhook noti cations until either we have received a successful response
(HTTP status code 2XX ), or we have exhausted a set number of retries. Each retry is delayed
exponentially, in order to prevent overloading customers' servers. The maximum number of retries is
exhausted approximately one day after the initial request was sent.

The Search Shipments endpoint

The Search Shipments endpoint is used to receive tariff information for a previously sent shipment.
Shiplify conducts a manual review for all shipments that are coded with a con dence level below A1 .
These shipments are reviewed throughout the day and checked for accuracy. Using a Search Shipments
request you can see the status of a review for all shipments matching the given pro_number and
pickup_date . Once the manual review is complete, the contents of tariff_items.shipper and
tariff_items.consignee may change.

This endpoint allows searching for shipments using a pro_number and pickup_date , in order to
retrieve up-to-date status information about matching shipments.

Below are instructions and examples of how to connect to the Shipments API including the endpoint,
required / optional parameters and the response format.

Sample request
GET /api/v2/shipments?shipment[pro_number]=1234567890&shipment[pickup_date]
=2000-01-01
Host: tariffs.shiplify.com
Accept: application/json
Content-Type: application/json
X-Api-Token: [sample-api-token]

For your convenience, the above request can be made using cURL as follows. Add your Test API key
to this cURL request to test.

https://tariffs.shiplify.com/docs/api/v2 20/33
3/21/23, 1:12 PM Shiplify - Shiplify API v2 Documentation

curl -g "tariffs.shiplify.com/api/v2/shipments?shipment[pro_number]=1234567
890&shipment[pickup_date]=2000-01-01" \
-X GET \
-H "Host: tariffs.shiplify.com" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "X-Api-Token: [sample-api-token]"

Parameters
shipment.pro_number (required)
The pro number to search for

shipment.pickup_date (required)
The pickup date to search for in YYYY-MM-DD format

Response body
This endpoint returns an array of search results, in JSON format. When no shipments match the given
parameters, an empty JSON array is returned, with an HTTP status code of 200 OK .

The structure of the response is as follows:

https://tariffs.shiplify.com/docs/api/v2 21/33
3/21/23, 1:12 PM Shiplify - Shiplify API v2 Documentation

[
{
"id": "4c0ec684-47a8-4d61-8749-f71985a79504",
"pro_number": "1234567890",
"pickup_date": "2000-01-01",
"shipper": {
"dock_access": {
"value": "yes",
"confidence": "A1"
},
"tariff_items": {
"codes": [],
"confidence": "A1",
"exempt": false
}
},
"consignee": {
"dock_access": {
"value": "no",
"confidence": "A1"
},
"forklift": {
"value": "no",
"confidence": "A1"
},
"tariff_items": {
"codes": ["RESD"],
"confidence": "A1",
"exempt": false
}
},
"status": "complete"
}
]

Error handling
When invalid request data is supplied (for example, missing a required eld), one or more of the
following error messages will be included, with a 422 Unprocessable Entity HTTP status code:

https://tariffs.shiplify.com/docs/api/v2 22/33
3/21/23, 1:12 PM Shiplify - Shiplify API v2 Documentation

{
"errors": {
"pro_number": [
"can't be blank",
"must be at least one character"
],
"pickup_date": [
"must be in YYYY-MM-DD format"
]
}
}

The Get Shipment endpoint

The Get Shipment API endpoint is used to receive tariff information for a single previously sent
shipment. Shiplify conducts a manual review for all shipments that are coded with a con dence level
below A1 . These shipments are reviewed throughout the day and checked for accuracy. Using a Get
Shipment request you can see the status of the review for a given shipment. Once the manual review is
complete, the contents of tariff_items.shipper and tariff_items.consignee may change.

This endpoint allows fetching info for a single shipment using the shipment's id , returned from the
original Create Shipment request where the shipment was created.

Sample request
The following is a sample request, assuming the id returned from the original Create Shipment
request was 4c0ec684-47a8-4d61-8749-f71985a79504 .

GET /api/v2/shipments/4c0ec684-47a8-4d61-8749-f71985a79504
Host: tariffs.shiplify.com
Accept: application/json
Content-Type: application/json
X-Api-Token: [sample-api-token]

For your convenience, the above request can be made using cURL as follows. Add your Test API key
to this cURL request to test.

curl -g "https://tariffs.shiplify.com/api/v2/shipments/4c0ec684-47a8-4d61-8
749-f71985a79504" \
-X GET \
-H "Host: tariffs.shiplify.com" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "X-Api-Token: [sample-api-token]"

Parameters

https://tariffs.shiplify.com/docs/api/v2 23/33
3/21/23, 1:12 PM Shiplify - Shiplify API v2 Documentation

The only parameter for this request is the id of the shipment, as returned from the Create Shipment
request. This parameter is included directly into the URL of the request (after
/api/v2/shipments/ ).

Response body
This endpoint returns a single result, in JSON format. The structure of the response is as follows:

{
"id": "4c0ec684-47a8-4d61-8749-f71985a79504",
"pro_number": "1234567890",
"pickup_date": "2000-01-01",
"shipper": {
"dock_access": {
"value": "yes",
"confidence": "A3"
},
"tariff_items": {
"codes": [],
"confidence": "A1",
"exempt": false
}
},
"consignee": {
"dock_access": {
"value": "no",
"confidence": "A2"
},
"forklift": {
"value": "no",
"confidence": "A2"
},
"tariff_items": {
"codes": ["RESD"],
"confidence": "A1",
"exempt": false
}
},
"status": "processing"
}

When no shipment matches the provided id, the response will have an HTTP status of 404 Not
Found , and the body will contain the following error message:

https://tariffs.shiplify.com/docs/api/v2 24/33
3/21/23, 1:12 PM Shiplify - Shiplify API v2 Documentation

{
"errors": [
{
"shipment": "not found"
}
]
}

The Create Quote endpoint

The Create Quote API endpoint allows you to send information about a quote to Shiplify, and receive
information about which location-based tariffs would be charged for the shipper and consignee.

Rate limits for the quote API are separate from the shipment APIs. You can view your current rate
limits on your API keys page (/api-keys). Contact your account manager or email [email protected]
(mailto:[email protected]) if you would like either rate limit increased.

Sample request
POST /api/v2/quotes
Host: tariffs.shiplify.com
Content-Type: application/json
Accept: application/json
X-Api-Token: [your-api-token]

{
"quote": {
"reference_id": "1234567890",
"pickup_date": "2000-01-01",
"shipper_name": "SHIPLIFY",
"shipper_street_address": "1425 ELLSWORTH INDUSTRIAL BLVD",
"shipper_city": "ATLANTA",
"shipper_state": "GA",
"shipper_postal_code": "30318",
"shipper_customer_number": "8675309",
"consignee_name": "VANDALEY INDUSTRIES",
"consignee_street_address": "129 W 81ST ST",
"consignee_city": "NEW YORK",
"consignee_state": "NY",
"consignee_postal_code": "10024",
"consignee_customer_number": "1675480",
"include_dock_access": 1
}
}

For your convenience, the above request can be made using cURL as follows. Add your Test API key
to this cURL request to test.

https://tariffs.shiplify.com/docs/api/v2 25/33
3/21/23, 1:12 PM Shiplify - Shiplify API v2 Documentation

curl "https://tariffs.shiplify.com/api/v2/quotes" \
-X POST \
-H "Host: tariffs.shiplify.com" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "X-Api-Token: [your-api-token]" \
-d '{"quote":{"shipper_name":"SHIPLIFY","shipper_street_address":"1425 EL
LSWORTH INDUSTRIAL BLVD","shipper_city":"ATLANTA","shipper_state":"GA","shi
pper_postal_code":"30318","consignee_name":"VANDALEY INDUSTRIES","consignee
_street_address":"129 W 81ST ST","consignee_city":"NEW YORK","consignee_sta
te":"NY","consignee_postal_code":"10024"}}'

Parameters
quote.reference_id
A reference identi er for the quote, for your internal tracking purposes -- can include numbers,
letters, spaces, underscores, and hyphens

quote.pickup_date
The pickup date (YYYY-MM-DD)

quote.shipper_name (required)
The shipper's name

quote.shipper_street_address (required)
The shipper's street address (line 1)

quote.shipper_street_address2
The shipper's street address (line 2)

quote.shipper_city (required)
The shipper's city

quote.shipper_state (required)
The shipper's state abbreviation

quote.shipper_postal_code (required)
The shipper's postal code

quote.shipper_customer_number
The shipper's customer number

quote.shipper_terminal_code
The origin terminal code (pick-up terminal)

quote.consignee_name (required)
The consignee's name

quote.consignee_street_address (required)

https://tariffs.shiplify.com/docs/api/v2 26/33
3/21/23, 1:12 PM Shiplify - Shiplify API v2 Documentation

The consignee's street address (line 1)

quote.consignee_street_address2
The consignee's street address (line 2)

quote.consignee_city (required)
The consignee's city

quote.consignee_state (required)
The consignee's state abbreviation

quote.consignee_postal_code (required)
The consignee's postal code

quote.consignee_customer_number
The consignee's customer number

quote.consignee_terminal_code
The destination terminal code (delivery terminal)

quote.include_dock_access (default: false)

Boolean eld to turn on dock access and forklift information. This part of a (beta) add-on feature. You
must have authorization to access the dock access information. For more information, contact
[email protected] (mailto:[email protected])

quote.include_tariff_items (default: true)

Boolean eld to turn on tariff item information

quote.include_location_types (default: false)

Boolean eld to turn on location types information

quote.weight
The weight of the freight (in pounds)

quote.pieces
The number of pieces included in the freight

quote.transit_days
The number of transit days

Response body
Responses are returned in JSON format, with the following structure:

https://tariffs.shiplify.com/docs/api/v2 27/33
3/21/23, 1:12 PM Shiplify - Shiplify API v2 Documentation

{
"id": "4c0ec684-47a8-4d61-8749-f71985a79504",
"reference_id": "123456",
"pickup_date": "2001-01-01",
"shipper": {
"dock_access": {
"value": "yes",
"confidence": "A1"
},
"tariff_items": {
"codes": [],
"confidence": "A1",
"exempt": false
}
},
"consignee": {
"dock_access": {
"value": "no",
"confidence": "A1"
},
"forklift": {
"value": "no",
"confidence": "A1"
},
"tariff_items": {
"codes": ["RESD"],
"confidence": "A1",
"exempt": false
}
}
}

Error handling
When invalid quote data is supplied (for example, missing a required eld), one or more of the
following error messages will be included, with a 422 Unprocessable Entity HTTP status code:

https://tariffs.shiplify.com/docs/api/v2 28/33
3/21/23, 1:12 PM Shiplify - Shiplify API v2 Documentation

{
"errors": {
"shipper_name": [
"can't be blank"
],
"shipper_street_address": [
"can't be blank"
],
"shipper_city": [
"can't be blank"
],
"shipper_state": [
"can't be blank"
],
"shipper_postal_code": [
"can't be blank"
],
"consignee_name": [
"can't be blank"
],
"consignee_street_address": [
"can't be blank"
],
"consignee_city": [
"can't be blank"
],
"consignee_state": [
"can't be blank"
],
"consignee_postal_code": [
"can't be blank"
],
"pickup_date": [
"must be in YYYY-MM-DD format"
],
}
}

The Create Location endpoint

The Create Location API endpoint allows you to send information about a single location to Shiplify,
and receive information about which location-based tariffs would be charged.

This API can optionally return location types, dock access and forklift information. You can turn this
feature on by passing a true ag in the include_location_types and include_dock_access
parameters. The include_dock_access parameter will also turn on the forklift information. The
forklift information will only return when the dock_access value is likely no .

https://tariffs.shiplify.com/docs/api/v2 29/33
3/21/23, 1:12 PM Shiplify - Shiplify API v2 Documentation

Rate limits for the location API are separate from the shipment and quote APIs. You can view your
current rate limits on your API keys page (/api-keys). Contact your account manager or email
[email protected] (mailto:[email protected]) if you would like either rate limit increased.

Sample request
POST /api/v2/locations
Host: tariffs.shiplify.com
Content-Type: application/json
Accept: application/json
X-Api-Token: [your-api-token]

{
"location": {
"name": "VANDALEY INDUSTRIES",
"street_address": "129 W 81ST ST",
"city": "NEW YORK",
"state": "NY",
"postal_code": "10024",
"include_dock_access": 1,
"include_tariff_items": 1,
"include_location_types": 1
}
}

For your convenience, the above request can be made using cURL as follows. Add your Test API key
to this cURL request to test.

curl "https://tariffs.shiplify.com/api/v2/locations" \
-X POST \
-H "Host: tariffs.shiplify.com" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "X-Api-Token: [your-api-token]" \
-d '{"location":{"name":"VANDALEY INDUSTRIES","street_address":"129 W 81S
T ST","city":"NEW YORK","state":"NY","postal_code":"10024","include_dock_ac
cess:"1","include_location_types:"1"}}'

Parameters
location.name (required)
The location's name

location.street_address (required)
The location's street address (line 1)

location.street_address2
The location's street address (line 2)

https://tariffs.shiplify.com/docs/api/v2 30/33
3/21/23, 1:12 PM Shiplify - Shiplify API v2 Documentation

location.city (required)
The location's city

location.state (required)
The location's state abbreviation

location.postal_code (required)
The location's postal code

location.include_dock_access (default: false)

Boolean eld to turn on dock access and forklift information. This part of a (beta) add-on feature. You
must have authorization to access the dock access information. For more information, contact
[email protected] (mailto:[email protected])

location.include_tariff_items (default: true)

Boolean eld to turn on tariff item information

location.include_location_types (default: false)

Boolean eld to turn on location types information

Response body
Responses are returned in JSON format, with the following structure:

{
"tariff_items": {
"confidence": 'A1',
"shipper": {
"codes": [ "LIMP" ]
},
"consignee":
"codes": [ "LIMD" ]
},
"exempt": false
},
"location_types": {
"values": [ "school" ],
"confidence": "A1"
},
"dock_access": {
"value": "no",
"confidence": "A1"
},
"forklift": {
"value": "no",
"confidence": "A1"
}
}

https://tariffs.shiplify.com/docs/api/v2 31/33
3/21/23, 1:12 PM Shiplify - Shiplify API v2 Documentation

Error handling
When invalid quote data is supplied (for example, missing a required eld), one or more of the
following error messages will be included, with a 422 Unprocessable Entity HTTP status code:

{
"errors": {
"name": [
"can't be blank"
],
"street_address": [
"can't be blank"
],
"city": [
"can't be blank"
],
"state": [
"can't be blank"
],
"postal_code": [
"can't be blank"
],
}
}

Frequently Asked Questions

When we get results back from the API, what is the minimum
confidence interval you would recommend using?
We recommend only applying the tariff codes with an A1 con dence. A blank con dence indicates
that Shiplify is fully con dent that no tariff items should be charged, and you should nalize the
freight bill.

For more information, see business process recommendations.

What is the average time it takes for a processing status to change to

complete ?
Our manual review process takes place from 8am-5pm Eastern. All locations will be processed within
one business day. They will be reviewed in the order they are received.

Does checking the status of a processing request count against rate

limiting?
Yes. All calls to the API, regardless of endpoint, count against the rate limit. If you are receiving rate
limit errors, please contact [email protected] (mailto:[email protected]) to request an
increase.

https://tariffs.shiplify.com/docs/api/v2 32/33
3/21/23, 1:12 PM Shiplify - Shiplify API v2 Documentation

What is the maximum level we could increase our rate limit to?
Please contact [email protected] (mailto:[email protected]) to discuss increasing rate limits.

I'm receiving an intermittent 503 Service Unavailable error response.

What should I do?
Intermittent errors can happen due to unforeseen issues with our servers or one of our data
providers. We try to limit these errors as much as possible, but they can still happen. We suggest
retrying the API call, and implementing a job queue to simplify error handling.

Some of my API responses timed out, what should I do?

Intermittent timeouts can happen. We suggest retrying the API call, and implementing a job queue to
simplify error handling.

Will shipments sent to the API affect our current FTP batch process?
No. Everything with your current batch process will remain the same. Shipments sent to the API will
not appear in the batch result les.

Can I use my "live" API key during a trial period?

Yes. Be aware that using a "live" API key will cause shipment records to be created in your account,
and they will be visible from the shipment search page (/shipments) within your customer portal.

Can I send the same shipment with duplicate pro numbers more than
once?
Yes.

Support
If you are experiencing issues with the API or other Shiplify services, rst check our support page
(https://status.shiplify.com) to see whether we are experiencing any known outages or planned
maintenance.

If your request is non-urgent, please email [email protected] (mailto:[email protected]). We

do our absolute best to respond to support requests within one business day; typically within a few
hours.

If you are experiencing an urgent outage and it is not reported on our support page
(https://status.shiplify.com), you may call 404-736-6551 (tel:+14047366551). Please only use this
phone number for urgent issues, for example to report a system outage that is holding up your billing
process.

© 2013-2023. All rights reserved. Shiplify is a registered trademark of winYOUship

Logistics.

https://tariffs.shiplify.com/docs/api/v2 33/33