Invoiced Shipping

Ship cards your users won through the Invoiced API. Same base URL and API key. Shipping is fulfilled by CollectorCrypt; the cost is billed on your monthly invoice.

What you must know

1. A card ships only after the buyback window, once GET /packs/{memo} shows in_vault.
2. A shipment is a quote until you call pay. pay is irreversible and bills the quoted cost. An unpaid quote expires after 14 days.
3. Addresses are not stored by the gacha. Send email and phoneNumber with every address write.
4. Shipping is DDU. The recipient pays any import duties.
5. The NFT stays in CollectorCrypt custody after the physical card ships.

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). Responses carry every field except email.

Shipments

1. POST /users/{playerRef}/shipments/estimate with { "memos": [...], "addressId": "…" } returns { "cost": 23.4, "costBreakdown": { "shippingCost": "20.00", "insuranceCost": "2.40", "feesCost": "1.00", "totalCost": "23.40" } }. Nothing is created.
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 is billed in the month you pay; paidRef and paidAmount are for your records.
4. Or POST /shipments/{id}/cancel while the quote is unpaid. The cards become shippable again.
5. Track with GET /shipments/{id} or GET /users/{playerRef}/shipments.

{
  "shipmentId": 12, "playerRef": "user-8431", "clientRef": "ship-551", "status": "awaiting_payment",
  "ccStatus": "Created", "cost": 23.4, "costBreakdown": { "…": "…" }, "paidAt": null,
  "expiresAt": "…", "cancelledAt": null, "tracking": { "trackingIds": [], "trackingUrls": [] },
  "memos": ["abcde-…"], "updatedAt": "…"
}

status	Meaning
creating	Being created; finishes on its own
awaiting_payment	Quote ready; pay or cancel
cancelling / cancelled	Cancel in progress / done; 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, or cancelled by CollectorCrypt after payment; the cost is credited

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	NOT_IN_VAULT	Not shippable yet; retry after the buyback window
409	SHIPMENT_PENDING, CANCEL_IN_PROGRESS	Retry shortly
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
503	SHIPPING_NOT_CONFIGURED	Contact us