Skip to main content

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​

  1. 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.
  2. A shipment is a quote until you call pay. pay is irreversible: it records the quoted cost and commits the cards to the shipment for good. An unpaid quote expires after 14 days.
  3. Send email and phoneNumber with every address write.
  4. 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 cost as costBreakdown.dutiesCost. If a quote has no duties, nothing is prepaid and the recipient pays any that apply.
  5. 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 email you sent for that user.

Addresses​

GET /users/{playerRef}/addresses{ "addresses": [ … ] }
POST /users/{playerRef}/addressescreate; 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​

  1. POST /users/{playerRef}/shipments/estimate with { "memos": [...], "addressId": "…" } returns the cost. Nothing is created. Here and on create, memos is 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, feesCost and totalCost are strings. dutiesCost is a string, or null when no duties are prepaid. breakdown.lines[] itemizes the cost; render it generically. declaredValue is not a charge.
  2. POST /users/{playerRef}/shipments with { "memos": [...], "addressId": "…", "clientRef": "ship-551" } creates the quote. clientRef is required; repeating it returns the same shipment with "replay": true.
  3. Collect the cost from your user, then POST /shipments/{id}/pay with { "paidRef": "your-receipt", "paidAmount": 23.4 }. The quoted cost goes on the invoice for the month you pay. paidRef and paidAmount are optional, for your records. Repeating pay returns the shipment with "replay": true.
  4. Or POST /shipments/{id}/cancel while the quote is unpaid.
  5. 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": "…"
}
  • ccShipmentId is the id webhooks use for this shipment.
  • tracking is null or { "trackingIds": [...], "trackingUrls": [...] }; the ids appear once the card ships.
  • Use status; ccStatus is for support.
statusMeaning
creatingBeing created; this can take 10 minutes or more. pay and cancel return SHIPMENT_PENDING until it is awaiting_payment
awaiting_paymentQuote ready; pay or cancel
cancelling / cancelledCancel in progress / done; once cancelled, the cards are shippable again
paidIn the warehouse queue
in_transit / deliveredShipped / delivered, with tracking
action_requiredThe warehouse needs something; CollectorCrypt support will follow up
failedRefused 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.shipment is the Shipping API v1 shipment, not the object GET /shipments/{id} returns. Match data.shipment.id to your shipment's ccShipmentId.
  • data.customerExternalId is null.
  • GET /shipments/{id} can trail an event by up to 30 seconds.

data.shipment.status maps to status:

data.shipment.statusstatus
Createdawaiting_payment
PaymentPending, PaymentReceived, Pending, Processingpaid
Shippedin_transit
Delivereddelivered
ActionRequiredaction_required
Cancelledcancelled 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.shipment is your newest shipment with the status you picked, or a sample shipment if you have none yet.
  • The event id starts with test.. Signing and headers are the same as for real events.
  • Shipped and Delivered add the UPS test tracking number 1Z999AA10123456784 when the shipment has no tracking.
  • Production has no test events.

Errors​

HTTPcodeWhat to do
400INVALID_ADDRESS, INVALID_MEMOS, INVALID_CLIENT_REF, CONTACT_PHONE_REQUIRED, CONTACT_EMAIL_REQUIRED, SHIPPING_REFUSEDFix the request
404NOT_FOUNDUnknown address or shipment, or not yours
409SHIPMENT_PENDING, CANCEL_IN_PROGRESSRetry later
409ALREADY_SHIPPING, NOT_HELD, SHIPMENT_EXPIRED, SHIPMENT_CANCELLED, SHIPMENT_FAILED, SHIPMENT_NOT_PAYABLE, CANCEL_VIA_CCFinal; create a new shipment or contact support
409CARD_MISSING, CANCEL_REFUSED, ORDER_CONFLICT, CONTACT_EMAIL_VERIFIEDContact us
503CC_UNAVAILABLE, RAIL_PAUSEDRetry later