Shipping
curl --request POST \
--url https://win.oneshotagent.com/v1/tools/shipping/shipments \
--header 'Content-Type: application/json' \
--data '
{
"connection_id": "<string>",
"limit": 123,
"cursor": "<string>",
"from": "<string>",
"to": "<string>",
"status": "<string>",
"shipment_id": "<string>",
"carrier": "<string>",
"tracking_number": "<string>"
}
'import requests
url = "https://win.oneshotagent.com/v1/tools/shipping/shipments"
payload = {
"connection_id": "<string>",
"limit": 123,
"cursor": "<string>",
"from": "<string>",
"to": "<string>",
"status": "<string>",
"shipment_id": "<string>",
"carrier": "<string>",
"tracking_number": "<string>"
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
connection_id: '<string>',
limit: 123,
cursor: '<string>',
from: '<string>',
to: '<string>',
status: '<string>',
shipment_id: '<string>',
carrier: '<string>',
tracking_number: '<string>'
})
};
fetch('https://win.oneshotagent.com/v1/tools/shipping/shipments', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://win.oneshotagent.com/v1/tools/shipping/shipments",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'connection_id' => '<string>',
'limit' => 123,
'cursor' => '<string>',
'from' => '<string>',
'to' => '<string>',
'status' => '<string>',
'shipment_id' => '<string>',
'carrier' => '<string>',
'tracking_number' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://win.oneshotagent.com/v1/tools/shipping/shipments"
payload := strings.NewReader("{\n \"connection_id\": \"<string>\",\n \"limit\": 123,\n \"cursor\": \"<string>\",\n \"from\": \"<string>\",\n \"to\": \"<string>\",\n \"status\": \"<string>\",\n \"shipment_id\": \"<string>\",\n \"carrier\": \"<string>\",\n \"tracking_number\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://win.oneshotagent.com/v1/tools/shipping/shipments")
.header("Content-Type", "application/json")
.body("{\n \"connection_id\": \"<string>\",\n \"limit\": 123,\n \"cursor\": \"<string>\",\n \"from\": \"<string>\",\n \"to\": \"<string>\",\n \"status\": \"<string>\",\n \"shipment_id\": \"<string>\",\n \"carrier\": \"<string>\",\n \"tracking_number\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://win.oneshotagent.com/v1/tools/shipping/shipments")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"connection_id\": \"<string>\",\n \"limit\": 123,\n \"cursor\": \"<string>\",\n \"from\": \"<string>\",\n \"to\": \"<string>\",\n \"status\": \"<string>\",\n \"shipment_id\": \"<string>\",\n \"carrier\": \"<string>\",\n \"tracking_number\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"data.shipments": [
{}
],
"data.next_cursor": "<string>",
"data.status": "<string>",
"data.events": [
{}
],
"data.rates": [
{}
]
}Connections
Shipping
Read shipments, tracking and quoted rates from your connected shipping system
POST
/
v1
/
tools
/
shipping
/
shipments
Shipping
curl --request POST \
--url https://win.oneshotagent.com/v1/tools/shipping/shipments \
--header 'Content-Type: application/json' \
--data '
{
"connection_id": "<string>",
"limit": 123,
"cursor": "<string>",
"from": "<string>",
"to": "<string>",
"status": "<string>",
"shipment_id": "<string>",
"carrier": "<string>",
"tracking_number": "<string>"
}
'import requests
url = "https://win.oneshotagent.com/v1/tools/shipping/shipments"
payload = {
"connection_id": "<string>",
"limit": 123,
"cursor": "<string>",
"from": "<string>",
"to": "<string>",
"status": "<string>",
"shipment_id": "<string>",
"carrier": "<string>",
"tracking_number": "<string>"
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
connection_id: '<string>',
limit: 123,
cursor: '<string>',
from: '<string>',
to: '<string>',
status: '<string>',
shipment_id: '<string>',
carrier: '<string>',
tracking_number: '<string>'
})
};
fetch('https://win.oneshotagent.com/v1/tools/shipping/shipments', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://win.oneshotagent.com/v1/tools/shipping/shipments",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'connection_id' => '<string>',
'limit' => 123,
'cursor' => '<string>',
'from' => '<string>',
'to' => '<string>',
'status' => '<string>',
'shipment_id' => '<string>',
'carrier' => '<string>',
'tracking_number' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://win.oneshotagent.com/v1/tools/shipping/shipments"
payload := strings.NewReader("{\n \"connection_id\": \"<string>\",\n \"limit\": 123,\n \"cursor\": \"<string>\",\n \"from\": \"<string>\",\n \"to\": \"<string>\",\n \"status\": \"<string>\",\n \"shipment_id\": \"<string>\",\n \"carrier\": \"<string>\",\n \"tracking_number\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://win.oneshotagent.com/v1/tools/shipping/shipments")
.header("Content-Type", "application/json")
.body("{\n \"connection_id\": \"<string>\",\n \"limit\": 123,\n \"cursor\": \"<string>\",\n \"from\": \"<string>\",\n \"to\": \"<string>\",\n \"status\": \"<string>\",\n \"shipment_id\": \"<string>\",\n \"carrier\": \"<string>\",\n \"tracking_number\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://win.oneshotagent.com/v1/tools/shipping/shipments")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"connection_id\": \"<string>\",\n \"limit\": 123,\n \"cursor\": \"<string>\",\n \"from\": \"<string>\",\n \"to\": \"<string>\",\n \"status\": \"<string>\",\n \"shipment_id\": \"<string>\",\n \"carrier\": \"<string>\",\n \"tracking_number\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"data.shipments": [
{}
],
"data.next_cursor": "<string>",
"data.status": "<string>",
"data.events": [
{}
],
"data.rates": [
{}
]
}Overview
Read-only tools on a connected shipping system (Connections): ShipEngine or Shippo. Nothing is bought, quoted, created or cancelled; nothing fetched is kept.POST /v1/tools/shipping/shipments: shipments and labels.POST /v1/tools/shipping/tracking: one shipment’s tracking.POST /v1/tools/shipping/rates: rates already quoted on a shipment.
connection_id: list your connections (GET /v1/connections) and pick by system and account_label. No answer holds a street line or a recipient’s name.
Shippo: from, to and status filter each page, so a page can hold fewer than limit shipments.
Authentication
Requires x402 payment in thepayment-signature header. Refusals for the body, the connection or an unavailable system come before payment.
Shipments
POST /v1/tools/shipping/shipments
string
required
The connection to read.
integer
default:25
Shipments per page, 1 to 100.
string
The
next_cursor of the previous page.string
Shipments created on or after this day (
YYYY-MM-DD).string
Shipments created on or before this day (
YYYY-MM-DD).string
Only shipments in this status, as the system names it (for example
label_purchased).Response (200)
array
Each shipment:
id, created_at, carrier, service, tracking_number, status, from and to (city, region, country), label_cost (amount, currency, or null without a label) and source (system, id).string
Send as
cursor for the next page; null on the last page.Tracking
POST /v1/tools/shipping/tracking
string
required
The connection to read.
string
The shipment to track. Or send
carrier and tracking_number instead.string
The carrier code, with
tracking_number.string
The tracking number, with
carrier.Response (200)
string
pre_transit, in_transit, delivered, exception or unknown.array
Each event:
at, status, place (city, region, country) and description (the carrier’s text; a signer’s name reads “the recipient”). Also eta and source.Rates
POST /v1/tools/shipping/rates
string
required
The connection to read.
string
required
The existing shipment whose quoted rates to read.
Response (200)
array
Each rate:
carrier, service, amount (with surcharges), currency, estimated_days and source.{
"success": true,
"data": {
"rates": [
{ "carrier": "ups", "service": "ups_ground", "amount": 12, "currency": "USD", "estimated_days": 3, "source": { "system": "shipengine", "id": "se-rate-1" } }
]
}
}
Errors
| Status | Error | Meaning |
|---|---|---|
| 400 | invalid_request | The body is not valid. |
| 400 | unsupported_for_system | The system cannot serve this input (a foreign cursor). |
| 400 | connection_wrong_system | The connection is not on a shipping system. |
| 400 | not_supported | No label to track yet, or more labels (send a smaller limit) or rates than one read covers; a paid call is returned as account credit. |
| 404 | connection_not_found | No such connection for this agent. |
| 409 | connection_expired, connection_revoked, connection_not_active | Reconnect or start a new connection. |
| 503 | not_configured | The system is not available right now. |
| 503 | rate_limited, system_unavailable | The system is busy or did not answer; a paid call is returned as account credit. |