Buy packs
curl --request POST \
--url https://catchbackcards.com/api/partner/v1/packs/purchase \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"pack_type": "bronze",
"category": "pokemon",
"quantity": 2,
"risk_level": "standard"
}
'import requests
url = "https://catchbackcards.com/api/partner/v1/packs/purchase"
payload = {
"pack_type": "bronze",
"category": "pokemon",
"quantity": 2,
"risk_level": "standard"
}
headers = {
"Idempotency-Key": "<idempotency-key>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Idempotency-Key': '<idempotency-key>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({pack_type: 'bronze', category: 'pokemon', quantity: 2, risk_level: 'standard'})
};
fetch('https://catchbackcards.com/api/partner/v1/packs/purchase', 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/packs/purchase",
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([
'pack_type' => 'bronze',
'category' => 'pokemon',
'quantity' => 2,
'risk_level' => 'standard'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"Idempotency-Key: <idempotency-key>"
],
]);
$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/packs/purchase"
payload := strings.NewReader("{\n \"pack_type\": \"bronze\",\n \"category\": \"pokemon\",\n \"quantity\": 2,\n \"risk_level\": \"standard\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Idempotency-Key", "<idempotency-key>")
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/packs/purchase")
.header("Idempotency-Key", "<idempotency-key>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"pack_type\": \"bronze\",\n \"category\": \"pokemon\",\n \"quantity\": 2,\n \"risk_level\": \"standard\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://catchbackcards.com/api/partner/v1/packs/purchase")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"pack_type\": \"bronze\",\n \"category\": \"pokemon\",\n \"quantity\": 2,\n \"risk_level\": \"standard\"\n}"
response = http.request(request)
puts response.read_body{
"checkout_id": "c8baa66a-…",
"pack_type": "bronze",
"quantity": 2,
"total_charged": 50,
"remaining_balance": 189935,
"summary": {
"total_value": 32.62,
"catchback_now_total": 29.36,
"best_pull": {
"pull_id": "fe04349b-…",
"name": "Tyrunt",
"value": 20.62
}
},
"pulls": [
{
"pull_id": "fe04349b-…",
"kind": "card",
"item": {
"id": "2b814ce0-…",
"name": "Tyrunt",
"set": "Pokemon Japanese M3-Nullifying Zero",
"category": "pokemon",
"grading_company": "PSA",
"grading_rank": 10,
"slab_label": "2026 Japanese M3-Nullifying Zero Tyrunt Art Rare",
"language": "english",
"cert_number": "84512377",
"market_value": 20.62,
"front_image": "https://…/2b814ce0-….png",
"back_image": "https://…/2b814ce0-…-back.png",
"render_image": "https://…/2b814ce0-…-render.png",
"image_url": "https://…/2b814ce0-…-render.png"
},
"value": 20.62,
"hit": {
"rarity_tier": "starter",
"bucket": "P0",
"bucket_odds": 0.72,
"is_chase": false,
"chase_label": null
},
"catchback": {
"amount": 18.56,
"rate": 0.9,
"valid_until": "2026-09-29T20:24:55Z",
"after": {
"amount": 16.5,
"rate": 0.8,
"valid_until": "2026-10-06T20:19:55Z"
}
},
"proof": {
"seed": 4261688475,
"verification_hash": "9c4f1e…",
"seed_commit_hash": "2be07a…",
"timestamp": "2026-09-29T20:19:55.418Z",
"verify_path": "/api/verify-pull?transaction_id=fe04349b-…&card_source=pokemon"
}
}
]
}
Gacha
Buy packs
Scope: rip:packs (needs a linked account). Moves money.
Opens 1–10 packs with your CatchCoins at list price. No promo codes, add-ons or bonus balance apply. Cards land in your vault, and every hit comes back with its CatchBack offer and a proof you can check. A sealed product doesn’t land in your vault: it isn’t in Get vault, and the API can’t sell it back, list it or ship it. Don’t buy the Starter or a sealed mystery pack from an API-only flow.
All or nothing: if any pack fails to open, the whole order is refunded and none of its pulls stand.
Refused before any charge: a pack_type that List packs doesn’t offer this key is a 404; a pack with available: false is a 409 PACK_UNAVAILABLE, with the reason List packs shows; a risk_level outside the pack’s risk_levels is a 400. A refused order charges nothing, and its order id is free to use again.
needs_review: true on an error means the order may have been charged and we are settling it. Never place it again under a new key. Follow it with Get an order. See Idempotency and Rate limits.
POST
/
api
/
partner
/
v1
/
packs
/
purchase
Buy packs
curl --request POST \
--url https://catchbackcards.com/api/partner/v1/packs/purchase \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"pack_type": "bronze",
"category": "pokemon",
"quantity": 2,
"risk_level": "standard"
}
'import requests
url = "https://catchbackcards.com/api/partner/v1/packs/purchase"
payload = {
"pack_type": "bronze",
"category": "pokemon",
"quantity": 2,
"risk_level": "standard"
}
headers = {
"Idempotency-Key": "<idempotency-key>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Idempotency-Key': '<idempotency-key>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({pack_type: 'bronze', category: 'pokemon', quantity: 2, risk_level: 'standard'})
};
fetch('https://catchbackcards.com/api/partner/v1/packs/purchase', 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/packs/purchase",
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([
'pack_type' => 'bronze',
'category' => 'pokemon',
'quantity' => 2,
'risk_level' => 'standard'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"Idempotency-Key: <idempotency-key>"
],
]);
$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/packs/purchase"
payload := strings.NewReader("{\n \"pack_type\": \"bronze\",\n \"category\": \"pokemon\",\n \"quantity\": 2,\n \"risk_level\": \"standard\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Idempotency-Key", "<idempotency-key>")
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/packs/purchase")
.header("Idempotency-Key", "<idempotency-key>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"pack_type\": \"bronze\",\n \"category\": \"pokemon\",\n \"quantity\": 2,\n \"risk_level\": \"standard\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://catchbackcards.com/api/partner/v1/packs/purchase")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"pack_type\": \"bronze\",\n \"category\": \"pokemon\",\n \"quantity\": 2,\n \"risk_level\": \"standard\"\n}"
response = http.request(request)
puts response.read_body{
"checkout_id": "c8baa66a-…",
"pack_type": "bronze",
"quantity": 2,
"total_charged": 50,
"remaining_balance": 189935,
"summary": {
"total_value": 32.62,
"catchback_now_total": 29.36,
"best_pull": {
"pull_id": "fe04349b-…",
"name": "Tyrunt",
"value": 20.62
}
},
"pulls": [
{
"pull_id": "fe04349b-…",
"kind": "card",
"item": {
"id": "2b814ce0-…",
"name": "Tyrunt",
"set": "Pokemon Japanese M3-Nullifying Zero",
"category": "pokemon",
"grading_company": "PSA",
"grading_rank": 10,
"slab_label": "2026 Japanese M3-Nullifying Zero Tyrunt Art Rare",
"language": "english",
"cert_number": "84512377",
"market_value": 20.62,
"front_image": "https://…/2b814ce0-….png",
"back_image": "https://…/2b814ce0-…-back.png",
"render_image": "https://…/2b814ce0-…-render.png",
"image_url": "https://…/2b814ce0-…-render.png"
},
"value": 20.62,
"hit": {
"rarity_tier": "starter",
"bucket": "P0",
"bucket_odds": 0.72,
"is_chase": false,
"chase_label": null
},
"catchback": {
"amount": 18.56,
"rate": 0.9,
"valid_until": "2026-09-29T20:24:55Z",
"after": {
"amount": 16.5,
"rate": 0.8,
"valid_until": "2026-10-06T20:19:55Z"
}
},
"proof": {
"seed": 4261688475,
"verification_hash": "9c4f1e…",
"seed_commit_hash": "2be07a…",
"timestamp": "2026-09-29T20:19:55.418Z",
"verify_path": "/api/verify-pull?transaction_id=fe04349b-…&card_source=pokemon"
}
}
]
}
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.
Headers
Your order id, 8–128 characters of A-Za-z0-9_-, unique per account across pack and card orders. Reuse it to retry the same order safely, and use a new one for every new order.
Pattern:
^[A-Za-z0-9_-]{8,128}$Body
application/json
A pack_type from List packs.
Maximum string length:
100A catalog that has packs and listings.
Available options:
pokemon, onepiece, sports, riftbound, watches Up to the pack's max_quantity.
Required range:
1 <= x <= 10Available options:
chill, standard, aggressive Response
The order and every pull in it. A retry of a finished order returns the original body with idempotent_replay: true, and charges nothing. If we closed the order after its response was lost, the retry returns a shorter body with reconciled: true and no pulls, summary or remaining_balance: see Idempotency.
Our id for the order. Get an order takes it.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
This answers a retry of a finished order. Nothing was charged again.
Present and true on the shorter body we return when we closed the order after its response was lost. It has pull_ids and a message, and no pulls, summary or remaining_balance.
Present with reconciled. The pulls in the order
Present with reconciled.