Estimate a shipment

Live carrier rates for shipping cards you hold to a customer’s address. Charges nothing and stores nothing.

POST /api/partner/v1/shipments/estimate

cURL

curl -X POST https://catchbackcards.com/api/partner/v1/shipments/estimate \
  -H "Authorization: Bearer $CATCHBACK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "card_ids": ["0e94dc61-5a2f-4b1e-9c3d-7f8a1b2c3d4e"],
    "address": {
      "name": "Sam Rivera",
      "address1": "1 Example Way",
      "city": "Testville",
      "state": "CA",
      "zip": "94000",
      "country": "US"
    }
  }'

200

{
  "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 }
  ]
}

Scope: ship:cards, granted on request · MCP tool: estimate_shipment

Live carrier rates, at the full rate you’d pay. Send cover_amount to price insurance as well. It charges nothing and stores nothing: the address only goes to our carrier partner for the quote. Take the carrier and token of the rate you choose to Create a shipment. See Shipping cards for how shipping works.

card_ids · string[] · required

1–10 card ids from Get vault, each once. A listed card has to be delisted first.

address · object · required

Your customer’s address.

Show address

name · string · required

The recipient’s name. At most 100 characters.

address1 · string · required

At most 100 characters.

address2 · string

At most 100 characters.

city · string · required

At most 100 characters.

state · string

State or region, at most 100 characters. Required where the country has one and needs it, such as the US.

zip · string

Postal code, at most 20 characters. Required, and checked against the country’s format, where the country needs it, such as the US.

country · string · required

ISO 3166 alpha-2, e.g. US. Where you can ship.

phone · string

At most 20 characters. Required outside the US.

cover_amount · number

Optional. The dollars of insurance to price, with at most two decimals: from $100 up to the max_cover for these cards. It counts as two estimates. How insurance works.

Response

destination_country · string

The country you sent, in capitals.

package_type · string

The parcel we’d use, e.g. mailer.

order_value · number

Our valuation of the cards, in USD.

max_cover · number | null

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.

cover_amount · number

The amount you sent. Present only when you sent cover_amount.

rates · object[]

Cheapest first. Can be empty.

Show rate

carrier · string

e.g. USPS. Send it back as rate.carrier.

service · string

The service’s name, e.g. Priority Mail.

token · string

e.g. usps_priority. Send it back as rate.token.

amount · number

The full rate in USD, without any premium. Normally what you send as max_cost.

estimated_days · number | null

The carrier’s estimate, in days.

cover_available · boolean

Present when you sent cover_amount. false when no premium is quoted for this service.

insurance_premium · number | null

Present when you sent cover_amount. null when cover_available is false.

total · number | null

Present when you sent cover_amount: amount plus insurance_premium, which is what you send as max_cost to insure this rate. null when cover_available is false.

Errors

Status	Code	When
400		The body isn’t JSON, card_ids isn’t 1–10 card ids (or lists one twice), the address is invalid, or cover_amount isn’t a dollar amount with at most two decimals or is 0 or negative. An address error is "error": "Invalid address" with fields, which names each bad field and never repeats its value
400	COVER_NOT_ALLOWED	cover_amount is outside the range: from $100 up to the cards’ value, capped at $10,000. The body has order_value, min_cover and max_cover
400	COUNTRY_NOT_SUPPORTED	We don’t ship to this country. A country code we don’t recognize is a plain 400 ("Invalid address", with fields.country)
400	OVER_CUSTOMS_CAP	An international shipment worth over $2,500, or with a card we have no value for
400	PARTNER_GOODS	A partner’s own goods ship from that partner
403		The key lacks ship:cards or isn’t linked to an account, the account needs a verified phone number ("Phone verification required"), the account is deleted ("Partner account unavailable"), or it can’t request shipping
403	FEATURE_RESTRICTED	The account is restricted from the marketplace or from withdrawals (capability is marketplace or withdraw). Contact us
409	CARDS_NOT_SHIPPABLE	A card can’t ship. cards[] gives each refused card_id and its reason: what they mean
429	RATE_LIMITED	More than 60 estimates a minute on this key, where one with cover_amount counts as two. Wait retry_after_seconds, also sent as a Retry-After header
502		The carrier quote failed. Try again
503		We couldn’t check the account or the cards. Try again

cURL

curl -X POST https://catchbackcards.com/api/partner/v1/shipments/estimate \
  -H "Authorization: Bearer $CATCHBACK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "card_ids": ["0e94dc61-5a2f-4b1e-9c3d-7f8a1b2c3d4e"],
    "address": {
      "name": "Sam Rivera",
      "address1": "1 Example Way",
      "city": "Testville",
      "state": "CA",
      "zip": "94000",
      "country": "US"
    }
  }'

200

{
  "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 }
  ]
}