Getting Started

Although we encourage our users to self-host, the quickest way to get started and get a feel for RocketShipIt is to use the cloud API.

Login to RocketShipIt My Account page and grab your RocketShipIt Cloud API Key. It should be a long string with random looking characters.

You are now ready to make your first API call. The RocketShipIt API is a single HTTPS endpoint that accepts JSON and returns JSON in its response. Authentication is done by setting the x-api-key HTTP header.

Here is a cURL example:

curl -X POST \
  https://api.rocketship.it/v1 \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_RS_API_KEY' \
  -d 'YOUR JSON REQUEST GOES HERE'

Notice the x-api-key header here. This will be your RocketShipIt Cloud API Key you got from the My Account page. The body of the request will be the RocketShipIt JSON request. You can find hundreds of examples at: https://docs.rocketshipit.com/2-0/examples/#examples

A PHP script might look something like:

<?php

// Define the URL and your API key
$url = "https://api.rocketship.it/v1";
$apiKey = "YOUR_RS_API_KEY";
$jsonData = 'YOUR JSON REQUEST GOES HERE'; // Replace with your JSON request data

// Initialize cURL
$ch = curl_init($url);

// Set the cURL options
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Cache-Control: no-cache',
    'Content-Type: application/json',
    'x-api-key: ' . $apiKey
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonData);

// Execute the request and capture the response
$response = curl_exec($ch);

// Check for cURL errors
if (curl_errno($ch)) {
    echo 'cURL error: ' . curl_error($ch);
} else {
    // Print the response
    echo $response;
}

// Close the cURL session
curl_close($ch);

Now that you know how to send requests, it is time to try some various shipping scenarios like get rates, track packages or create labels.

Next, we encourage you to check out the API Explorer. It is kind of like Postman but specific to RocketShipIt and can do things like automatically show base64 encoded PDF / label images from the carrier response.

Get started self-hosting

Download RocketShipIt from the My Account page and extract it somewhere in your local development environment.

For macOS and Linux you can extract by doing tar -xf rocketshipit2-*.tar.gz

Next, download the license.lic file from the My Account page and place it in the same directory.

The contents should be organized like this:

.
├── CHANGES.md
├── clients
│   ├── nodejs
│   │   ├── example.js
│   │   └── rocketshipit.js
│   ├── perl
│   │   ├── example.pl
│   │   └── RocketShipIt.pm
│   ├── php
│   │   ├── example.php
│   │   ├── README.md
│   │   └── RocketShipIt.php
│   ├── python
│   │   ├── example.py
│   │   └── rocketshipit.py
│   ├── README.md
│   └── ruby
│       ├── example.rb
│       └── rocketshipit.rb
├── license.lic
├── LICENSE.txt
├── README.txt
└── RocketShipIt

The clients folder contains the RocketShipIt client libraries for each officially supported programming language. Next, navigate to your targeted language. For this guide we will be using php.

cd clients/php

Open example.php in your favorite text editor.

Then uncomment the following line and fill it in with your RocketShipIt API key which can be found in the My Account page:

$rs->apiKey = 'ADD YOUR RocketShipIt API KEY HERE';

This will instruct the RocketShipIt PHP client to connect to RocketShipIt in the cloud as this is the easiest way to get started; however, the preferred way is to self-host the RocketShipIt API.

Now run php example.php. You should get something like:

php example.php
Array
(
    [meta] => Array
        (
            [code] => 200
            [error_message] => 
        )

    [data] => Array
        (
            [errors] => Array
                (
                    [0] => Array
                        (
                            [code] => 1000
                            [description] => Authentication Failed
                            [type] => ERROR
                        )

                )

            [rates] => 
        )

)

In this case, the Authentication Failed error is actually coming from the shipping carrier. If your RocketShipIt API key was invalid you would see an error in the meta.error_message field. For more information about errors see: Errors

Once you fill in your carrier credentials in example.php you should get a successful response:

Array
(
    [meta] => Array
        (
            [code] => 200
            [error_message] => 
        )

    [data] => Array
        (
            [errors] => 
            [rates] => Array
                (
                    [0] => Array
                        (
                            [desc] => UPS Next Day Air Early AM
                            [rate] => 118.95
                            [negotiated_rate] => 117.76
                            [currency] => USD
                            [service_code] => 14
                            [est_delivery_time] => 2018-02-26T08:30:00-00:00
                            [delivery_days] => 1
                            [package_type] =>
                            ...

If things are not going as planned set the debug parameter to true to see what RocketShipIt is doing behind the scenes. For more information about debug, please see: troubleshooting

Next, we encourage you to check out the API Explorer.

See also: self-host

← Supported Shipping CarriersAPI Explorer →