Estimate a shipment
curl --request POST \
--url https://catchbackcards.com/api/partner/v1/shipments/estimate \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"card_ids": [
"0e94dc61-5a2f-4b1e-9c3d-7f8a1b2c3d4e"
],
"address": {
"name": "Sam Rivera",
"address1": "1 Example Way",
"city": "Testville",
"state": "CA",
"zip": "94000",
"country": "US"
}
}
'import requests
url = "https://catchbackcards.com/api/partner/v1/shipments/estimate"
payload = {
"card_ids": ["0e94dc61-5a2f-4b1e-9c3d-7f8a1b2c3d4e"],
"address": {
"name": "Sam Rivera",
"address1": "1 Example Way",
"city": "Testville",
"state": "CA",
"zip": "94000",
"country": "US"
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
card_ids: ['0e94dc61-5a2f-4b1e-9c3d-7f8a1b2c3d4e'],
address: {
name: 'Sam Rivera',
address1: '1 Example Way',
city: 'Testville',
state: 'CA',
zip: '94000',
country: 'US'
}
})
};
fetch('https://catchbackcards.com/api/partner/v1/shipments/estimate', 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://catchbackcards.com/api/partner/v1/shipments/estimate",
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([
'card_ids' => [
'0e94dc61-5a2f-4b1e-9c3d-7f8a1b2c3d4e'
],
'address' => [
'name' => 'Sam Rivera',
'address1' => '1 Example Way',
'city' => 'Testville',
'state' => 'CA',
'zip' => '94000',
'country' => 'US'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"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://catchbackcards.com/api/partner/v1/shipments/estimate"
payload := strings.NewReader("{\n \"card_ids\": [\n \"0e94dc61-5a2f-4b1e-9c3d-7f8a1b2c3d4e\"\n ],\n \"address\": {\n \"name\": \"Sam Rivera\",\n \"address1\": \"1 Example Way\",\n \"city\": \"Testville\",\n \"state\": \"CA\",\n \"zip\": \"94000\",\n \"country\": \"US\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
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://catchbackcards.com/api/partner/v1/shipments/estimate")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"card_ids\": [\n \"0e94dc61-5a2f-4b1e-9c3d-7f8a1b2c3d4e\"\n ],\n \"address\": {\n \"name\": \"Sam Rivera\",\n \"address1\": \"1 Example Way\",\n \"city\": \"Testville\",\n \"state\": \"CA\",\n \"zip\": \"94000\",\n \"country\": \"US\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://catchbackcards.com/api/partner/v1/shipments/estimate")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"card_ids\": [\n \"0e94dc61-5a2f-4b1e-9c3d-7f8a1b2c3d4e\"\n ],\n \"address\": {\n \"name\": \"Sam Rivera\",\n \"address1\": \"1 Example Way\",\n \"city\": \"Testville\",\n \"state\": \"CA\",\n \"zip\": \"94000\",\n \"country\": \"US\"\n }\n}"
response = http.request(request)
puts response.read_body{
"destination_country": "US",
"package_type": "mailer",
"order_value": 410,
"max_cover": 410,
"rates": [
{
"carrier": "USPS",
"service": "Ground Advantage",
"token": "usps_ground_advantage",
"amount": 5.4,
"estimated_days": 3
},
{
"carrier": "USPS",
"service": "Priority Mail",
"token": "usps_priority",
"amount": 12.85,
"estimated_days": 2
}
]
}{
"error": "Invalid address",
"fields": {
"phone": "Required for international shipments"
}
}{
"error": "Missing or malformed API key"
}{
"error": "<string>",
"code": "FEATURE_RESTRICTED",
"capability": "<string>"
}{
"error": "Some cards cannot ship.",
"code": "CARDS_NOT_SHIPPABLE",
"cards": [
{
"card_id": "0e94dc61-…",
"reason": "listed"
}
]
}{
"error": "Too many estimates. Slow down.",
"code": "RATE_LIMITED",
"retry_after_seconds": 12
}{
"error": "<string>",
"code": "<string>"
}{
"error": "<string>",
"code": "<string>"
}Shipping
Estimate a shipment
Scope: ship:cards, opt-in, granted on request (needs a linked account).
Live carrier rates for shipping cards you hold to a customer’s address, at the full rate you would pay. Send cover_amount to price insurance as well: each rate then adds its premium and total. It stores nothing on our side: the address goes to our carrier services, normally Shippo, to get the rates. It is a POST so the address never lands in a URL. Create a shipment takes the carrier and token of the rate you choose. The account needs a verified phone number. 60 estimates a minute per key. Read Shipping cards first.
POST
/
api
/
partner
/
v1
/
shipments
/
estimate
Estimate a shipment
curl --request POST \
--url https://catchbackcards.com/api/partner/v1/shipments/estimate \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"card_ids": [
"0e94dc61-5a2f-4b1e-9c3d-7f8a1b2c3d4e"
],
"address": {
"name": "Sam Rivera",
"address1": "1 Example Way",
"city": "Testville",
"state": "CA",
"zip": "94000",
"country": "US"
}
}
'import requests
url = "https://catchbackcards.com/api/partner/v1/shipments/estimate"
payload = {
"card_ids": ["0e94dc61-5a2f-4b1e-9c3d-7f8a1b2c3d4e"],
"address": {
"name": "Sam Rivera",
"address1": "1 Example Way",
"city": "Testville",
"state": "CA",
"zip": "94000",
"country": "US"
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
card_ids: ['0e94dc61-5a2f-4b1e-9c3d-7f8a1b2c3d4e'],
address: {
name: 'Sam Rivera',
address1: '1 Example Way',
city: 'Testville',
state: 'CA',
zip: '94000',
country: 'US'
}
})
};
fetch('https://catchbackcards.com/api/partner/v1/shipments/estimate', 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://catchbackcards.com/api/partner/v1/shipments/estimate",
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([
'card_ids' => [
'0e94dc61-5a2f-4b1e-9c3d-7f8a1b2c3d4e'
],
'address' => [
'name' => 'Sam Rivera',
'address1' => '1 Example Way',
'city' => 'Testville',
'state' => 'CA',
'zip' => '94000',
'country' => 'US'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"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://catchbackcards.com/api/partner/v1/shipments/estimate"
payload := strings.NewReader("{\n \"card_ids\": [\n \"0e94dc61-5a2f-4b1e-9c3d-7f8a1b2c3d4e\"\n ],\n \"address\": {\n \"name\": \"Sam Rivera\",\n \"address1\": \"1 Example Way\",\n \"city\": \"Testville\",\n \"state\": \"CA\",\n \"zip\": \"94000\",\n \"country\": \"US\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
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://catchbackcards.com/api/partner/v1/shipments/estimate")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"card_ids\": [\n \"0e94dc61-5a2f-4b1e-9c3d-7f8a1b2c3d4e\"\n ],\n \"address\": {\n \"name\": \"Sam Rivera\",\n \"address1\": \"1 Example Way\",\n \"city\": \"Testville\",\n \"state\": \"CA\",\n \"zip\": \"94000\",\n \"country\": \"US\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://catchbackcards.com/api/partner/v1/shipments/estimate")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"card_ids\": [\n \"0e94dc61-5a2f-4b1e-9c3d-7f8a1b2c3d4e\"\n ],\n \"address\": {\n \"name\": \"Sam Rivera\",\n \"address1\": \"1 Example Way\",\n \"city\": \"Testville\",\n \"state\": \"CA\",\n \"zip\": \"94000\",\n \"country\": \"US\"\n }\n}"
response = http.request(request)
puts response.read_body{
"destination_country": "US",
"package_type": "mailer",
"order_value": 410,
"max_cover": 410,
"rates": [
{
"carrier": "USPS",
"service": "Ground Advantage",
"token": "usps_ground_advantage",
"amount": 5.4,
"estimated_days": 3
},
{
"carrier": "USPS",
"service": "Priority Mail",
"token": "usps_priority",
"amount": 12.85,
"estimated_days": 2
}
]
}{
"error": "Invalid address",
"fields": {
"phone": "Required for international shipments"
}
}{
"error": "Missing or malformed API key"
}{
"error": "<string>",
"code": "FEATURE_RESTRICTED",
"capability": "<string>"
}{
"error": "Some cards cannot ship.",
"code": "CARDS_NOT_SHIPPABLE",
"cards": [
{
"card_id": "0e94dc61-…",
"reason": "listed"
}
]
}{
"error": "Too many estimates. Slow down.",
"code": "RATE_LIMITED",
"retry_after_seconds": 12
}{
"error": "<string>",
"code": "<string>"
}{
"error": "<string>",
"code": "<string>"
}Authorizations
Your API key, sent as a bearer token. Keep it on your server. See Authentication. A request from a location we refuse gets a 403 with Access denied, whether or not it has a valid key: where you can call from.
Body
application/json
Card ids from Get vault, cards you hold in the vault. A listed card has to be delisted first.
Required array length:
1 - 10 elementsYour customer's address. Stored only with a shipment, never in logs or on your account.
Show child attributes
Show child attributes
Optional insurance: the dollars of cover, with at most two decimals, from $100 up to max_cover from the estimate. Leave it out and the only cover is what the carrier includes automatically: up to $100 on USPS and UPS labels. Other carriers may include less or none. You carry any loss above your cover.
Required range:
100 <= x <= 10000Response
The rates.
e.g. mailer.
Our valuation of the cards
The most you can insure: order_value, capped at $10,000. null when the order is worth $100 or less, which can't be insured.
Show child attributes
Show child attributes
The amount you sent. Present only when you sent cover_amount.