Getting Started

This guide will walk you through creating new shipment and getting tracking link with TrackMage.

---

Step 0: Obtain API Credentials and Authorization TOKEN

See Authorization for instructions on obtaining store API credentials and TOKEN.

In API calls, include obtained authorization token or api credentials.

Step 1: Create client

note

Skip this step if you use cURL, Postman or HTTP Client in your IDE

PHP

use TrackMage\Client\TrackMageClient;

// Create Client using Client ID and Client Secret
$clientId = 'CLIENT_ID';
$clientSecret = 'CLIENT_SECRET';
$client = new TrackMageClient($clientId, $clientSecret);

// --- or ----
// Create client using obtained authorization token
$client = new TrackMageClient();
$client->setAccessToken('YOUR_TOKEN');

Step 2: Create a shipment with tracking number

cURL

curl 'https://api.trackmage.com/shipments' \
  -H 'accept: application/ld+json' \
  -H 'content-type: application/ld+json' \
  -H 'authorization: Bearer YOUR_TOKEN' \
  --data-binary '{"trackingNumber":"TRACKING_NUMBER","originCarrier":"ORIGIN_CARRIER_CODE","email":"CUSTOMER_EMAIL","workspace":"/workspaces/WORKSPACE_ID"}'

PHP

use GuzzleHttp\Exception\ClientException;

...

$workspaceId = 'WORKSPACE_ID'; // a desired workspace UUID
$data = [
    'workspace' => "/workspaces/{$workspaceId}",
    'trackingNumber' => 'TRACKING_NUMBER',
    'originCarrier' => 'ORIGIN_CARRIER_CODE', // optionally
    'email' => 'CUSTOMER_EMAIL' // optionally
];
try {
    $response = $client->post('/shipments', [
        'json' => $data
    ]);
    $shipment = TrackMageClient::item($response);
    echo $shipment['id'];
} catch (ClientException $e) {
    printf('An client exception occurred: %d %s', $e->getCode(), TrackMageClient::error($e);
} catch (\Exception $e) {
    printf('An error occurred: %d %s', $e->getCode(), $e->getMessage());
}

Step 3: Receive tracking page link for created shipment

cURL

curl 'https://api.trackmage.com/generate_tracking_page_link' \
  -H 'accept: application/ld+json' \
  -H 'content-type: application/ld+json' \
  -H 'authorization: Bearer YOUR_TOKEN' \
  --data-binary '{"trackingPageId":"TRACKING_PAGE_ID","filter":{"id":"SHIPMENT_ID"}}'

PHP

try {
     $response = $client->post('/generate_tracking_page_link', [
         'json' => [
             'trackingPageId' => 'TRACKING_PAGE_ID',
             'filter' => [
                'id' => $shipmentId
             ]
         ]
     ]);
     $trackingPageLink = TrackMageClient::item($response);
     echo $trackingPageLink['link'];
} catch (ClientException $e) {
    printf('An client exception occurred: %d %s', $e->getCode(), TrackMageClient::error($e);
} catch (\Exception $e) {
    printf('An error occurred: %d %s', $e->getCode(), $e->getMessage());
}