Shipping cards

Ship cards you hold to your customers, paid from your balance: what you pay, which cards can ship, how we handle your customers’ addresses, and how to track a shipment.

You can ship cards in your vault to your customers, paid from your CatchCoins balance at the carrier’s full rate, plus a premium if you choose insurance. It takes the ship:cards scope, which we grant on request: contact us. The account needs a verified phone number.

1. Get rates

   Estimate a shipment with the card ids and your customer’s address. It returns live carrier rates and charges nothing. We store nothing: the address goes to our carrier services, normally Shippo, to get the rates.

2. Create the shipment

   Create a shipment with the same cards and address, the rate you chose and a max_cost, under your own id for the shipment. We quote again and charge the fresh amount, up to max_cost.

3. Track it

   List shipments and Get a shipment show its status and tracking. With a webhook, shipment.updated tells you when it moves.

What you pay

The carrier’s full rate for the service you pick, plus the premium if you choose insurance. There are no promo codes on a shipment, and no free or subsidized tier.

Without insurance, the only cover on a parcel is what the carrier includes automatically: up to $100 on USPS and UPS labels. Other carriers may include less or none. Keep that in mind before you ship a card worth more. There’s no signature option on a shipment.

Insurance

Insurance is optional, and you choose it per shipment. To price it, send cover_amount to Estimate a shipment. Each rate then adds cover_available, insurance_premium and total, the rate plus the premium. To buy it, send the same cover_amount to Create a shipment, with max_cost set to the total you saw:

{ "card_ids": ["0e94dc61-5a2f-4b1e-9c3d-7f8a1b2c3d4e"], "address": { "...": "..." }, "rate": { "carrier": "USPS", "token": "usps_priority" }, "cover_amount": 400, "max_cost": 18.01 }

• How much: any amount from $100 up to max_cover, which every estimate returns: the value of the cards, capped at $10,000. Outside that you get 400 COVER_NOT_ALLOWED. An order worth $100 or less can’t be insured, and its max_cover is null.
• Orders worth more than $10,000: cover stops at $10,000, and the rest of the order is uninsured.
• What it costs: the premium our insurer quotes for that service. max_cost applies to the rate and the premium together. A new quote above it is 409 PRICE_CHANGED, and a service with no premium quoted is 409 COVER_UNAVAILABLE. Nothing is charged in either case.
• What it pays: up to the amount you covered, and never more. You carry any loss above your cover, whether you chose less than the cards are worth or the order is over the cap.

If a parcel is lost or damaged

Contact us with the shipment id. You can’t claim from the insurer yourself, because the policy is tied to our sender details. We file the claim, and we credit your balance when it pays out.

The insurer’s deadlines are 60 days from shipping, or 15 days after a “delivered” scan for a parcel that never arrived. Report well before them, so we have time to file. We can’t file a claim after a deadline has passed.

Which cards can ship

Up to 10 cards per shipment, all to one address. A card has to be in your vault, and not:

reason in cards[]	Why it can’t ship	What to do
not_in_vault	It isn’t in your vault: not yours, not found, or not a kind of card Get vault lists, such as an energy or Steph Curry card	Check the id
listed	It’s listed on the marketplace	Delist it first
shipping	It’s already in a shipping request or on its way, or it’s otherwise unavailable	Read Get vault again
on_hold	It came from a pack that holds its cards	Sell it back
not_a_card	The id is a sealed pack	Sealed packs don’t ship through the API

Any refused card is a 409 CARDS_NOT_SHIPPABLE that lists every refused card. A partner’s own goods ship from that partner, not through this API (400 PARTNER_GOODS).

Where you can ship

GET https://catchbackcards.com/api/shipping-countries lists the countries we ship to, with no key. Elsewhere is a 400 COUNTRY_NOT_SUPPORTED.

Outside the US, the address needs a phone number, and a shipment worth more than $2,500 in total can’t ship through the API (400 OVER_CUSTOMS_CAP). Neither can one with a card we have no value for.

Customer addresses

Each shipment carries its customer’s address, because we hold no list of your customers.

• Where we keep it: only with the shipment’s order, which is what we buy the label from. It doesn’t go on your account or in your address book. We never ask for your customer’s email address.
• Who sees it: you, through Get a shipment (the list has no addresses, and no event carries any part of one), our staff who fulfill the order, and the carrier services we buy labels through, normally Shippo, which quote and label it.
• Logs: Our partner API doesn’t write the address to our logs.
• How long: we remove the address, phone number and label links 90 days after the shipment closes, or 180 days after it shipped if the carrier never reported an end. An order still waiting to ship keeps its address. After that, address is null and address_removed is true, and the order stays with its cards, cost and tracking. destination_country stays on the shipment. The carrier services keep their own copies under their own terms.
• Your customer hears nothing from us. We don’t email or text them, so tell them about their tracking yourself.

Status

status	Meaning
pending	We’ve taken the request and the order doesn’t exist yet
needs_review	We couldn’t confirm the charge: see below
processing	Charged and waiting for us to buy the label and send it
shipped	On its way. A parcel that bounces stays shipped until someone resolves it
delivered	Delivered
cancelled	We closed the order or removed it. Contact us if you didn’t expect this

New values can be added, so handle one you don’t know.

Limits

Limit	Set per key	When you go over
50 shipments per key per UTC day	No	429 DAILY_SHIPMENT_LIMIT_REACHED, with limit and resets_at
60 estimates per key per minute, where one with cover_amount counts as two	No	429 RATE_LIMITED, with retry_after_seconds and a Retry-After header
1–10 cards per request	No	400
max_cost up to $10,000	No	400

All of them: Rate limits. The address field limits are on Estimate a shipment.

Unconfirmed shipments

Rarely, we can’t tell whether a shipment’s charge went through. You get a 500 SHIPMENT_OUTCOME_UNKNOWN with needs_review: true and the shipment_id, and it’s with our team to check. Follow it with Get a shipment, which takes the shipment_id. No event tells you the outcome.

What you see	What it means	What to do
status: "needs_review" or "pending", or 409 IDEMPOTENCY_IN_PROGRESS with needs_review: true on a resend	We’re still checking	Wait. A resend with the same id can’t charge twice. Don’t resend it under a new id until you hear from us
processing, shipped, delivered or cancelled, or the shipment with idempotent_replay: true on a resend	It went through, and was charged once	Track it as usual
404 from Get a shipment	We found nothing was charged, and removed it	The id is free to send again. Check your balance before you do

Quote the shipment_id if you contact us.