First Leeward

Card Shipments

Submit shipment

POSThttps://api.firstleeward.com/v0/card-shipments/:id/submit

Transitions the shipment from DRAFT to PLACED. Single-card shipments hit the single-ship endpoint; multi-card shipments use the bulk-ship endpoint. On failure the shipment remains in DRAFT so the client can retry.

Returns the full shipment detail (including cards[]). When the manufacturer rejects a subset of cards on a multi-card submit, the response uses HTTP 207 Multi-Status: the surviving cards transition to PLACED upstream while each rejected card is returned with productionStatus = "BULK_SHIP_REJECTED" and a rejectedAt timestamp. A 200 indicates every card was accepted.

Authorizations

Authorizationstring · headerrequired

API key as Bearer token, e.g. Bearer YOUR_API_KEY

Headers

Leeward-Versionenum<string>required

API version (YYYY-MM-DD). Available option: 2026-09-18

Idempotency-Keystringrequired

Unique key for safely retrying this request. Up to 255 characters; we recommend a UUIDv4. The first request executes and its response is cached; subsequent requests with the same key replay the cached response (24h retention).

Path Parameters

idstring<uuid>required

Response

200Response for status 200
idstring<uuid>required

Unique shipment identifier

statusstringrequired

Shipment lifecycle status

Available options:DRAFTPLACEDIN_PRODUCTIONREADY_TO_SHIPIN_TRANSITOUT_FOR_DELIVERYDELIVEREDDELIVERY_FAILEDEXCEPTIONCANCELED
destinationAddressobjectrequired

Shipping address

Show child attributes
line1stringrequired

Street address line 1

line2string | nullrequired

Street address line 2

zonestring | nullrequired

State, province, or zone

citystringrequired

City

postalCodestringrequired

Postal code

countrystringrequired

ISO 3166-1 alpha-2 country code

recipientobjectrequired

Recipient details

Show child attributes
firstNamestringrequired

Recipient first name

lastNamestringrequired

Recipient last name

phoneNumberstringrequired

Recipient phone number

dialCodeintegerrequired

Phone dial code

emailstring<email>required

Recipient email address

courierobjectrequired

Courier on the shipment

Show child attributes
Option 1 · Postal
typestringrequired
Option 2 · Courier
typestringrequired
namestringrequired

Courier name. May be manufacturer-assigned after submit.

Available options:DHLFEDEXSFEXPRESS
trackingNumberstring | nullrequired

Courier tracking number

trackingUrlstring | nullrequired

Courier tracking URL

cutoffDatestring | nullrequired

ISO 8601 cutoff date returned by the manufacturer

createdAtstringrequired

ISO 8601 creation timestamp

updatedAtstringrequired

ISO 8601 last update timestamp

submittedAtstring | nullrequired

ISO 8601 timestamp when submitted to the manufacturer

deliveredAtstring | nullrequired

ISO 8601 timestamp when all cards were delivered

cardsobject[]required

Cards included in this shipment

Show child attributes
idstring<uuid>required

Unique shipment member identifier

cardIdstring<uuid>required

ID of the card being shipped

cardDesignIdstringrequired

Card design identifier

shippingAddressobjectrequired

Shipping address

Show child attributes
line1stringrequired

Street address line 1

line2string | nullrequired

Street address line 2

zonestring | nullrequired

State, province, or zone

citystringrequired

City

postalCodestringrequired

Postal code

countrystringrequired

ISO 3166-1 alpha-2 country code

productionStatusstringrequired

Per-card production status

Available options:PENDINGREQUESTEDIN_PRODUCTIONCOMPLETEDACTIVATEDCANCELEDON_HOLDBULK_SHIP_REJECTED
rejectedAtstring | nullrequired

ISO 8601 timestamp when this card was rejected and excluded from the shipment, or null if the card was accepted

createdAtstringrequired

ISO 8601 creation timestamp

updatedAtstringrequired

ISO 8601 last update timestamp

207Response for status 207
idstring<uuid>required

Unique shipment identifier

statusstringrequired

Shipment lifecycle status

Available options:DRAFTPLACEDIN_PRODUCTIONREADY_TO_SHIPIN_TRANSITOUT_FOR_DELIVERYDELIVEREDDELIVERY_FAILEDEXCEPTIONCANCELED
destinationAddressobjectrequired

Shipping address

Show child attributes
line1stringrequired

Street address line 1

line2string | nullrequired

Street address line 2

zonestring | nullrequired

State, province, or zone

citystringrequired

City

postalCodestringrequired

Postal code

countrystringrequired

ISO 3166-1 alpha-2 country code

recipientobjectrequired

Recipient details

Show child attributes
firstNamestringrequired

Recipient first name

lastNamestringrequired

Recipient last name

phoneNumberstringrequired

Recipient phone number

dialCodeintegerrequired

Phone dial code

emailstring<email>required

Recipient email address

courierobjectrequired

Courier on the shipment

Show child attributes
Option 1 · Postal
typestringrequired
Option 2 · Courier
typestringrequired
namestringrequired

Courier name. May be manufacturer-assigned after submit.

Available options:DHLFEDEXSFEXPRESS
trackingNumberstring | nullrequired

Courier tracking number

trackingUrlstring | nullrequired

Courier tracking URL

cutoffDatestring | nullrequired

ISO 8601 cutoff date returned by the manufacturer

createdAtstringrequired

ISO 8601 creation timestamp

updatedAtstringrequired

ISO 8601 last update timestamp

submittedAtstring | nullrequired

ISO 8601 timestamp when submitted to the manufacturer

deliveredAtstring | nullrequired

ISO 8601 timestamp when all cards were delivered

cardsobject[]required

Cards included in this shipment

Show child attributes
idstring<uuid>required

Unique shipment member identifier

cardIdstring<uuid>required

ID of the card being shipped

cardDesignIdstringrequired

Card design identifier

shippingAddressobjectrequired

Shipping address

Show child attributes
line1stringrequired

Street address line 1

line2string | nullrequired

Street address line 2

zonestring | nullrequired

State, province, or zone

citystringrequired

City

postalCodestringrequired

Postal code

countrystringrequired

ISO 3166-1 alpha-2 country code

productionStatusstringrequired

Per-card production status

Available options:PENDINGREQUESTEDIN_PRODUCTIONCOMPLETEDACTIVATEDCANCELEDON_HOLDBULK_SHIP_REJECTED
rejectedAtstring | nullrequired

ISO 8601 timestamp when this card was rejected and excluded from the shipment, or null if the card was accepted

createdAtstringrequired

ISO 8601 creation timestamp

updatedAtstringrequired

ISO 8601 last update timestamp

400Response for status 400
Option 1 · CardNotPhysicalError
errorobjectrequired
Show child attributes
codestringrequired
messagestringrequired
detailobject | nullrequired
Option 2 · CardNotShippableError
errorobjectrequired
Show child attributes
codestringrequired
messagestringrequired
detailobject | nullrequired
Option 3 · ShippingNotAllowedForCountryError
errorobjectrequired
Show child attributes
codestringrequired
messagestringrequired
detailobject | nullrequired
Option 4 · ZoneRequiredError
errorobjectrequired
Show child attributes
codestringrequired
messagestringrequired
detailobject | nullrequired
Option 5 · InvalidZoneError
errorobjectrequired
Show child attributes
codestringrequired
messagestringrequired
detailobject | nullrequired
Option 6 · ShippingEmailInvalidError
errorobjectrequired
Show child attributes
codestringrequired
messagestringrequired
detailobject | nullrequired
Option 7 · CourierNotSupportedError
errorobjectrequired
Show child attributes
codestringrequired
messagestringrequired
detailobject | nullrequired
Option 8 · DuplicateCardInShipmentError
errorobjectrequired
Show child attributes
codestringrequired
messagestringrequired
detailobject | nullrequired
Option 9 · SingleCardShipmentAddressMismatchError
errorobjectrequired
Show child attributes
codestringrequired
messagestringrequired
detailobject | nullrequired
Option 10 · CardShipmentEmptyError
errorobjectrequired
Show child attributes
codestringrequired
messagestringrequired
detailobject | nullrequired
Option 11 · CardShipmentCardLimitExceededError
errorobjectrequired
Show child attributes
codestringrequired
messagestringrequired
detailobject | nullrequired
Option 12 · CardShipmentCardDesignNotActiveError
errorobjectrequired
Show child attributes
codestringrequired
messagestringrequired
detailobject | nullrequired
Option 13 · CardShipmentCardDesignNotPhysicalCapableError
errorobjectrequired
Show child attributes
codestringrequired
messagestringrequired
detailobject | nullrequired
Option 14 · CardShipmentAllCardsFailedError
errorobjectrequired
Show child attributes
codestringrequired
messagestringrequired
detailobject | nullrequired
Option 15 · CardRestrictedError
errorobjectrequired
Show child attributes
codestringrequired
messagestringrequired
detailobject | nullrequired
Option 16 · CardDesignOutOfStockError
errorobjectrequired
Show child attributes
codestringrequired
messagestringrequired
detailobject | nullrequired
Option 17 · CardShippingBlockedError
errorobjectrequired
Show child attributes
codestringrequired
messagestringrequired
detailobject | nullrequired
Option 18 · ShippingPhoneInvalidError
errorobjectrequired
Show child attributes
codestringrequired
messagestringrequired
detailobject | nullrequired
Option 19 · ShippingPhoneDialCodeMismatchError
errorobjectrequired
Show child attributes
codestringrequired
messagestringrequired
detailobject | nullrequired
404Response for status 404
Option 1 · CardShipmentCardNotFoundError
errorobjectrequired
Show child attributes
codestringrequired
messagestringrequired
detailobject | nullrequired
Option 2 · CardShipmentCardDesignNotFoundError
errorobjectrequired
Show child attributes
codestringrequired
messagestringrequired
detailobject | nullrequired
Option 3 · CardShipmentNotFoundError
errorobjectrequired
Show child attributes
codestringrequired
messagestringrequired
detailobject | nullrequired
409Response for status 409
Option 1 · ActiveCardShipmentExistsError
errorobjectrequired
Show child attributes
codestringrequired
messagestringrequired
detailobject | nullrequired
Option 2 · CardShipmentNotDraftError
errorobjectrequired
Show child attributes
codestringrequired
messagestringrequired
detailobject | nullrequired
Option 3 · CardAlreadyInProductionError
errorobjectrequired
Show child attributes
codestringrequired
messagestringrequired
detailobject | nullrequired
Option 4 · BulkShipCutoffPassedError
errorobjectrequired
Show child attributes
codestringrequired
messagestringrequired
detailobject | nullrequired
502Card shipping provider error
errorobjectrequired
Show child attributes
codestringrequired
messagestringrequired
detailobject | nullrequired