Invoiced Shipping
Ship cards your users won through the Invoiced API. Same base URL and API key. Shipping is
fulfilled by CollectorCrypt; the cost goes on your monthly invoice as shippingAmount.
What you must know
- A card can ship as soon as it is won. Once it is in a shipment it cannot be sold back (
409 ALREADY_SHIPPING). If an unpaid shipment is cancelled, expires or fails, the card is free again: shippable, and sellable back while its buyback window is open. Once a shipment is paid, its cards never come back. - A shipment is a quote until you call
pay.payis irreversible: it records the quotedcostand commits the cards to the shipment for good. An unpaid quote expires after 14 days. - Send
emailandphoneNumberwith every address write. - Import duties are prepaid. On a shipment outside the US, CollectorCrypt pays duties and import taxes to the
carrier, and they are in the quoted
costascostBreakdown.dutiesCost. If a quote has no duties, nothing is prepaid and the recipient pays any that apply. - CollectorCrypt does not contact your users about shipments; tell them yourself, using the status or
webhooks. The carrier's tracking emails go to the last
emailyou sent for that user.
Addresses
GET /users/{playerRef}/addresses | { "addresses": [ … ] } |
POST /users/{playerRef}/addresses | create; 201 { "address": { … } } |
GET /users/{playerRef}/addresses/{id} | { "address": { … } } |
PATCH /users/{playerRef}/addresses/{id} | update |
DELETE /users/{playerRef}/addresses/{id} | { "id": "…", "removed": true } |
Fields: fullName, streetAddress, apartment, city, state, zip, country, phoneNumber, email.
fullName, streetAddress, city, country and state are required on create (state may be "" where a
country has none). Longer values are cut: streetAddress to 256 characters, zip and phoneNumber to 32, every
other field to 128. Responses carry every field except email.
country is ISO 3166-1. Send the two-letter code (US). Also accepted: the three-letter code (USA), or the English
short name exactly as the iso-3166 package spells it in its name field
(United States of America). Case is ignored. Other spellings are not supported. A value that matches no country
is refused with 400 SHIPPING_REFUSED. Responses return
country as you sent it. List of two-letter codes. Libraries:
iso-3166 (JavaScript), pycountry (Python,
use alpha_2).
Shipments
POST /users/{playerRef}/shipments/estimatewith{ "memos": [...], "addressId": "…" }returns the cost. Nothing is created. Here and on create,memosis 1 to 50 of this user's pack memos.{ "cost": 23.4,
"costBreakdown": { "shippingCost": "20.00", "insuranceCost": "2.40", "feesCost": "1.00", "dutiesCost": null, "totalCost": "23.40",
"breakdown": { "declaredValue": 120, "lines": [ { "code": "…", "label": "…", "amount": 20 } ] } } }shippingCost,insuranceCost,feesCostandtotalCostare strings.dutiesCostis a string, ornullwhen no duties are prepaid.breakdown.lines[]itemizes the cost; render it generically.declaredValueis not a charge.POST /users/{playerRef}/shipmentswith{ "memos": [...], "addressId": "…", "clientRef": "ship-551" }creates the quote.clientRefis required; repeating it returns the same shipment with"replay": true.- Collect the cost from your user, then
POST /shipments/{id}/paywith{ "paidRef": "your-receipt", "paidAmount": 23.4 }. The quotedcostgoes on the invoice for the month you pay.paidRefandpaidAmountare optional, for your records. Repeatingpayreturns the shipment with"replay": true. - Or
POST /shipments/{id}/cancelwhile the quote is unpaid. - Track with
GET /shipments/{id}.GET /users/{playerRef}/shipments?limit=&cursor=returns{ shipments, nextCursor }, newest first, and can be minutes behind.
{
"shipmentId": 12, "ccShipmentId": "cm…", "playerRef": "user-8431", "clientRef": "ship-551",
"status": "awaiting_payment", "ccStatus": "Created", "cost": 23.4, "costBreakdown": { "…": "…" },
"paidAt": null, "expiresAt": "…", "cancelledAt": null, "tracking": null,
"memos": ["abcde-…"], "updatedAt": "…"
}
ccShipmentIdis the id webhooks use for this shipment.trackingisnullor{ "trackingIds": [...], "trackingUrls": [...] }; the ids appear once the card ships.- Use
status;ccStatusis for support.
status | Meaning |
|---|---|
creating | Being created; this can take 10 minutes or more. pay and cancel return SHIPMENT_PENDING until it is awaiting_payment |
awaiting_payment | Quote ready; pay or cancel |
cancelling / cancelled | Cancel in progress / done; once cancelled, the cards are shippable again |
paid | In the warehouse queue |
in_transit / delivered | Shipped / delivered, with tracking |
action_required | The warehouse needs something; CollectorCrypt support will follow up |
failed | Refused when created: nothing is billed and the cards are shippable again. Or stopped after you paid: the cards stay with the shipment and CollectorCrypt support contacts you |
Webhooks
CollectorCrypt can POST to your server when one of your shipments changes. Set the URL in the
partner panel under Shipping webhook, where you can also roll the
signing secret and send a test ping. The secret is shown once.
Delivery, signing and retries work as in the Shipping API v1; see its Webhooks. The
event is shipment.updated. What differs here:
data.shipmentis the Shipping API v1 shipment, not the objectGET /shipments/{id}returns. Matchdata.shipment.idto your shipment'sccShipmentId.data.customerExternalIdisnull.GET /shipments/{id}can trail an event by up to 30 seconds.
data.shipment.status maps to status:
data.shipment.status | status |
|---|---|
Created | awaiting_payment |
PaymentPending, PaymentReceived, Pending, Processing | paid |
Shipped | in_transit |
Delivered | delivered |
ActionRequired | action_required |
Cancelled | cancelled if unpaid; failed if you had paid and it had not shipped |
Once a shipment is in_transit, its status changes only to delivered.
Testing your webhook (development only)
In the development partner panel, the Shipping webhook tab has
Send test event. Pick a status and send: your webhook receives one signed shipment.updated with that status at once.
Nothing changes on any shipment, so you can send as many as you like.
data.shipmentis your newest shipment with the status you picked, or a sample shipment if you have none yet.- The event
idstarts withtest.. Signing and headers are the same as for real events. ShippedandDeliveredadd the UPS test tracking number1Z999AA10123456784when the shipment has no tracking.- Production has no test events.
Errors
| HTTP | code | What to do |
|---|---|---|
| 400 | INVALID_ADDRESS, INVALID_MEMOS, INVALID_CLIENT_REF, CONTACT_PHONE_REQUIRED, CONTACT_EMAIL_REQUIRED, SHIPPING_REFUSED | Fix the request |
| 404 | NOT_FOUND | Unknown address or shipment, or not yours |
| 409 | SHIPMENT_PENDING, CANCEL_IN_PROGRESS | Retry later |
| 409 | ALREADY_SHIPPING, NOT_HELD, SHIPMENT_EXPIRED, SHIPMENT_CANCELLED, SHIPMENT_FAILED, SHIPMENT_NOT_PAYABLE, CANCEL_VIA_CC | Final; create a new shipment or contact support |
| 409 | CARD_MISSING, CANCEL_REFUSED, ORDER_CONFLICT, CONTACT_EMAIL_VERIFIED | Contact us |
| 503 | CC_UNAVAILABLE, RAIL_PAUSED | Retry later |