Create shipments and labels, track deliveries, find pickup points, and receive signed webhooks — across all ShipOS carriers, behind a single versioned contract.
# 1. Find your carrier account
curl --location 'https://app.shipos.co.il/api/v2/licenses' \
--header 'X-Client-Id: {client_id}' \
--header 'X-Client-Secret: {client_secret}' \
--header 'Accept: application/json'
# 2. Create the shipment
curl --location 'https://app.shipos.co.il/api/v2/shipments' \
--header 'X-Client-Id: {client_id}' \
--header 'X-Client-Secret: {client_secret}' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: order-10052-attempt-1' \
--data '{
"license_key": "{license_key}",
"ship_data": {
"contact_name": "Israel Israeli",
"contact_phone": "0501234567",
"street": "Herzl",
"number": "12",
"city": "Tel Aviv",
"type": "1",
"return": "1",
"packages": 1
},
"order": {
"id": "10052",
"shipping": { "first_name": "Israel", "last_name": "Israeli" },
"order_items": []
}
}'// Node.js 18+ / browsers — no dependencies
const baseUrl = 'https://app.shipos.co.il/api/v2'
const auth = {
'X-Client-Id': process.env.SHIPOS_CLIENT_ID,
'X-Client-Secret': process.env.SHIPOS_CLIENT_SECRET,
}
// 1. Find your carrier account
const licensesRes = await fetch(`${baseUrl}/licenses`, {
headers: { ...auth, Accept: 'application/json' },
})
const { data: licenses } = await licensesRes.json()
// 2. Create the shipment
const shipmentRes = await fetch(`${baseUrl}/shipments`, {
method: 'POST',
headers: {
...auth,
'Content-Type': 'application/json',
'Idempotency-Key': 'order-10052-attempt-1',
},
body: JSON.stringify({
license_key: licenses[0].key,
ship_data: {
contact_name: 'Israel Israeli', contact_phone: '0501234567',
street: 'Herzl', number: '12', city: 'Tel Aviv',
type: '1', return: '1', packages: 1,
},
order: {
id: '10052',
shipping: { first_name: 'Israel', last_name: 'Israeli' },
order_items: [],
},
}),
})
const { data: shipment } = await shipmentRes.json()
console.log(shipment.uuid, shipment.tracking_code)<?php
// composer require guzzlehttp/guzzle
$client = new \GuzzleHttp\Client([
'base_uri' => 'https://app.shipos.co.il/api/v2/',
'headers' => [
'X-Client-Id' => getenv('SHIPOS_CLIENT_ID'),
'X-Client-Secret' => getenv('SHIPOS_CLIENT_SECRET'),
'Accept' => 'application/json',
],
]);
// 1. Find your carrier account
$licenses = json_decode($client->get('licenses')->getBody()->getContents(), true)['data'];
// 2. Create the shipment
$response = $client->post('shipments', [
'headers' => ['Idempotency-Key' => 'order-10052-attempt-1'],
'json' => [
'license_key' => $licenses[0]['key'],
'ship_data' => [
'contact_name' => 'Israel Israeli', 'contact_phone' => '0501234567',
'street' => 'Herzl', 'number' => '12', 'city' => 'Tel Aviv',
'type' => '1', 'return' => '1', 'packages' => 1,
],
'order' => [
'id' => '10052',
'shipping' => ['first_name' => 'Israel', 'last_name' => 'Israeli'],
'order_items' => [],
],
],
]);
$shipment = json_decode($response->getBody()->getContents(), true)['data'];
echo $shipment['uuid'], ' ', $shipment['tracking_code'], PHP_EOL;<?php
use Illuminate\Support\Facades\Http;
$shipos = Http::withHeaders([
'X-Client-Id' => config('services.shipos.client_id'),
'X-Client-Secret' => config('services.shipos.client_secret'),
])->acceptJson()->baseUrl('https://app.shipos.co.il/api/v2');
// 1. Find your carrier account
$licenses = $shipos->get('licenses')->throw()->json('data');
// 2. Create the shipment
$shipment = $shipos->withHeaders(['Idempotency-Key' => 'order-10052-attempt-1'])
->post('shipments', [
'license_key' => $licenses[0]['key'],
'ship_data' => [
'contact_name' => 'Israel Israeli', 'contact_phone' => '0501234567',
'street' => 'Herzl', 'number' => '12', 'city' => 'Tel Aviv',
'type' => '1', 'return' => '1', 'packages' => 1,
],
'order' => [
'id' => '10052',
'shipping' => ['first_name' => 'Israel', 'last_name' => 'Israeli'],
'order_items' => [],
],
])
->throw()
->json('data');
logger()->info($shipment['uuid'].' '.$shipment['tracking_code']);# pip install httpx
import os
import httpx
client = httpx.Client(
base_url="https://app.shipos.co.il/api/v2",
headers={
"X-Client-Id": os.environ["SHIPOS_CLIENT_ID"],
"X-Client-Secret": os.environ["SHIPOS_CLIENT_SECRET"],
"Accept": "application/json",
},
)
# 1. Find your carrier account
licenses = client.get("/licenses").raise_for_status().json()["data"]
# 2. Create the shipment
response = client.post(
"/shipments",
headers={"Idempotency-Key": "order-10052-attempt-1"},
json={
"license_key": licenses[0]["key"],
"ship_data": {
"contact_name": "Israel Israeli", "contact_phone": "0501234567",
"street": "Herzl", "number": "12", "city": "Tel Aviv",
"type": "1", "return": "1", "packages": 1,
},
"order": {
"id": "10052",
"shipping": {"first_name": "Israel", "last_name": "Israeli"},
"order_items": [],
},
},
)
shipment = response.raise_for_status().json()["data"]
print(shipment["uuid"], shipment["tracking_code"])package main
import (
"bytes"
"encoding/json"
"fmt"
"net/http"
"os"
)
const baseURL = "https://app.shipos.co.il/api/v2"
func call(method, path string, body []byte, extra map[string]string) map[string]any {
req, _ := http.NewRequest(method, baseURL+path, bytes.NewReader(body))
req.Header.Set("X-Client-Id", os.Getenv("SHIPOS_CLIENT_ID"))
req.Header.Set("X-Client-Secret", os.Getenv("SHIPOS_CLIENT_SECRET"))
req.Header.Set("Accept", "application/json")
for name, value := range extra {
req.Header.Set(name, value)
}
res, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer res.Body.Close()
var payload map[string]any
if err := json.NewDecoder(res.Body).Decode(&payload); err != nil {
panic(err)
}
return payload
}
func main() {
// 1. Find your carrier account
licenses := call("GET", "/licenses", nil, nil)["data"].([]any)
licenseKey := licenses[0].(map[string]any)["key"]
// 2. Create the shipment
body, _ := json.Marshal(map[string]any{
"license_key": licenseKey,
"ship_data": map[string]any{
"contact_name": "Israel Israeli", "contact_phone": "0501234567",
"street": "Herzl", "number": "12", "city": "Tel Aviv",
"type": "1", "return": "1", "packages": 1,
},
"order": map[string]any{
"id": "10052",
"shipping": map[string]any{"first_name": "Israel", "last_name": "Israeli"},
"order_items": []any{},
},
})
shipment := call("POST", "/shipments", body, map[string]string{
"Content-Type": "application/json",
"Idempotency-Key": "order-10052-attempt-1",
})["data"].(map[string]any)
fmt.Println(shipment["uuid"], shipment["tracking_code"])
}// Java 17+ — java.net.http, no dependencies (parse with Jackson/Gson)
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class ShipOsFirstLabel {
static final String BASE = "https://app.shipos.co.il/api/v2";
static final HttpClient CLIENT = HttpClient.newHttpClient();
static HttpRequest.Builder request(String path) {
return HttpRequest.newBuilder(URI.create(BASE + path))
.header("X-Client-Id", System.getenv("SHIPOS_CLIENT_ID"))
.header("X-Client-Secret", System.getenv("SHIPOS_CLIENT_SECRET"))
.header("Accept", "application/json");
}
public static void main(String[] args) throws Exception {
// 1. Find your carrier account
HttpResponse<String> licenses = CLIENT.send(
request("/licenses").build(), HttpResponse.BodyHandlers.ofString());
System.out.println(licenses.body()); // take a "key" from {"data":[...]}
// 2. Create the shipment
String body = """
{
"license_key": "{license_key}",
"ship_data": {
"contact_name": "Israel Israeli", "contact_phone": "0501234567",
"street": "Herzl", "number": "12", "city": "Tel Aviv",
"type": "1", "return": "1", "packages": 1
},
"order": {
"id": "10052",
"shipping": { "first_name": "Israel", "last_name": "Israeli" },
"order_items": []
}
}""";
HttpResponse<String> shipment = CLIENT.send(
request("/shipments")
.header("Content-Type", "application/json")
.header("Idempotency-Key", "order-10052-attempt-1")
.POST(HttpRequest.BodyPublishers.ofString(body))
.build(),
HttpResponse.BodyHandlers.ofString());
System.out.println(shipment.body()); // {"data":{"uuid":...,"tracking_code":...}}
}
}// .NET 8+ — System.Net.Http.Json
using System.Net.Http.Json;
using System.Text.Json;
using var http = new HttpClient
{
BaseAddress = new Uri("https://app.shipos.co.il/api/v2/"),
};
http.DefaultRequestHeaders.Add("X-Client-Id",
Environment.GetEnvironmentVariable("SHIPOS_CLIENT_ID"));
http.DefaultRequestHeaders.Add("X-Client-Secret",
Environment.GetEnvironmentVariable("SHIPOS_CLIENT_SECRET"));
http.DefaultRequestHeaders.Add("Accept", "application/json");
// 1. Find your carrier account
var licenses = (await http.GetFromJsonAsync<JsonDocument>("licenses"))!
.RootElement.GetProperty("data");
// 2. Create the shipment
var payload = new
{
license_key = licenses[0].GetProperty("key").GetString(),
ship_data = new
{
contact_name = "Israel Israeli", contact_phone = "0501234567",
street = "Herzl", number = "12", city = "Tel Aviv",
type = "1", @return = "1", packages = 1,
},
order = new
{
id = "10052",
shipping = new { first_name = "Israel", last_name = "Israeli" },
order_items = Array.Empty<object>(),
},
};
using var request = new HttpRequestMessage(HttpMethod.Post, "shipments")
{
Content = JsonContent.Create(payload),
};
request.Headers.Add("Idempotency-Key", "order-10052-attempt-1");
var response = await http.SendAsync(request);
response.EnsureSuccessStatusCode();
var shipment = (await response.Content.ReadFromJsonAsync<JsonDocument>())!
.RootElement.GetProperty("data");
Console.WriteLine($"{shipment.GetProperty("uuid").GetString()} " +
$"{shipment.GetProperty("tracking_code").GetString()}");require "net/http"
require "json"
auth = {
"X-Client-Id" => ENV.fetch("SHIPOS_CLIENT_ID"),
"X-Client-Secret" => ENV.fetch("SHIPOS_CLIENT_SECRET"),
"Accept" => "application/json",
}
http = Net::HTTP.new("app.shipos.co.il", 443)
http.use_ssl = true
# 1. Find your carrier account
licenses = JSON.parse(
http.request(Net::HTTP::Get.new("/api/v2/licenses", auth)).body
).fetch("data")
# 2. Create the shipment
post = Net::HTTP::Post.new("/api/v2/shipments", auth.merge(
"Content-Type" => "application/json",
"Idempotency-Key" => "order-10052-attempt-1",
))
post.body = JSON.dump(
license_key: licenses.first["key"],
ship_data: {
contact_name: "Israel Israeli", contact_phone: "0501234567",
street: "Herzl", number: "12", city: "Tel Aviv",
type: "1", return: "1", packages: 1,
},
order: {
id: "10052",
shipping: { first_name: "Israel", last_name: "Israeli" },
order_items: [],
},
)
shipment = JSON.parse(http.request(post).body).fetch("data")
puts "#{shipment["uuid"]} #{shipment["tracking_code"]}"// [dependencies]
// reqwest = { version = "0.12", features = ["json"] }
// tokio = { version = "1", features = ["full"] }
// serde_json = "1"
use serde_json::{json, Value};
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let client = reqwest::Client::new();
let id = std::env::var("SHIPOS_CLIENT_ID")?;
let secret = std::env::var("SHIPOS_CLIENT_SECRET")?;
// 1. Find your carrier account
let licenses: Value = client
.get("https://app.shipos.co.il/api/v2/licenses")
.header("X-Client-Id", &id)
.header("X-Client-Secret", &secret)
.header("Accept", "application/json")
.send()
.await?
.error_for_status()?
.json()
.await?;
// 2. Create the shipment
let shipment: Value = client
.post("https://app.shipos.co.il/api/v2/shipments")
.header("X-Client-Id", &id)
.header("X-Client-Secret", &secret)
.header("Accept", "application/json")
.header("Idempotency-Key", "order-10052-attempt-1")
.json(&json!({
"license_key": licenses["data"][0]["key"],
"ship_data": {
"contact_name": "Israel Israeli", "contact_phone": "0501234567",
"street": "Herzl", "number": "12", "city": "Tel Aviv",
"type": "1", "return": "1", "packages": 1
},
"order": {
"id": "10052",
"shipping": { "first_name": "Israel", "last_name": "Israeli" },
"order_items": []
}
}))
.send()
.await?
.error_for_status()?
.json()
.await?;
println!(
"{} {}",
shipment["data"]["uuid"], shipment["data"]["tracking_code"]
);
Ok(())
}The response includes the shipment uuid, the carrier tracking code, and a label you can print. Walk through the full flow — including labels, tracking and error handling — in Create your first shipment.