> ## Documentation Index > Fetch the complete documentation index at: https://docs.reap.global/llms.txt > Use this file to discover all available pages before exploring further. # Submit shipment > 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. ## OpenAPI ````yaml /api-reference/openapi.json post /card-shipments/{id}/submit openapi: 3.1.0 info: title: Reap API version: 1.0.0 description: Reap platform API servers: - url: https://sandbox.api.reap.global description: Sandbox - url: https://prod.api.reap.global description: Production security: - bearerAuth: [] tags: - name: Accounts - name: Activities - name: Card Designs - name: Card Shipments - name: Card Transactions - name: Cards - name: Companies - name: Crypto Deposits - name: Policies - name: Simulation - name: Users - name: Virtual Asset Postings - name: Virtual Assets - name: Webhooks paths: /card-shipments/{id}/submit: post: tags: - Card Shipments summary: Submit shipment description: >- 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. operationId: submit_card-shipments parameters: - name: id in: path required: true schema: type: string format: uuid - name: Reap-Version in: header required: true schema: type: string enum: - '2025-02-14' description: API version (YYYY-MM-DD) example: '2025-02-14' - name: Idempotency-Key in: header required: true schema: type: string minLength: 1 maxLength: 255 description: >- 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). responses: '200': description: Response for status 200 content: application/json: schema: type: object properties: id: type: string format: uuid description: Unique shipment identifier status: type: string enum: - DRAFT - PLACED - IN_PRODUCTION - READY_TO_SHIP - IN_TRANSIT - OUT_FOR_DELIVERY - DELIVERED - DELIVERY_FAILED - EXCEPTION - CANCELED description: Shipment lifecycle status example: DRAFT destinationAddress: $ref: '#/components/schemas/CardShippingAddress' description: Box-level destination address recipient: $ref: '#/components/schemas/CardShipmentRecipient' courier: type: object properties: type: type: string enum: - POSTAL - COURIER description: Courier delivery method example: POSTAL name: anyOf: - type: string - type: 'null' description: Courier name required: - type - name description: Courier selection trackingNumber: anyOf: - type: string - type: 'null' description: Courier tracking number trackingUrl: anyOf: - type: string - type: 'null' description: Courier tracking URL cutoffDate: anyOf: - type: string - type: 'null' description: ISO 8601 cutoff date returned by the manufacturer createdAt: type: string description: ISO 8601 creation timestamp updatedAt: type: string description: ISO 8601 last update timestamp submittedAt: anyOf: - type: string - type: 'null' description: ISO 8601 timestamp when submitted to the manufacturer deliveredAt: anyOf: - type: string - type: 'null' description: ISO 8601 timestamp when all cards were delivered cards: type: array items: $ref: '#/components/schemas/CardShipmentMember' description: Cards included in this shipment required: - id - status - destinationAddress - recipient - courier - trackingNumber - trackingUrl - cutoffDate - createdAt - updatedAt - submittedAt - deliveredAt - cards '207': description: Response for status 207 content: application/json: schema: type: object properties: id: type: string format: uuid description: Unique shipment identifier status: type: string enum: - DRAFT - PLACED - IN_PRODUCTION - READY_TO_SHIP - IN_TRANSIT - OUT_FOR_DELIVERY - DELIVERED - DELIVERY_FAILED - EXCEPTION - CANCELED description: Shipment lifecycle status example: DRAFT destinationAddress: $ref: '#/components/schemas/CardShippingAddress' description: Box-level destination address recipient: $ref: '#/components/schemas/CardShipmentRecipient' courier: type: object properties: type: type: string enum: - POSTAL - COURIER description: Courier delivery method example: POSTAL name: anyOf: - type: string - type: 'null' description: Courier name required: - type - name description: Courier selection trackingNumber: anyOf: - type: string - type: 'null' description: Courier tracking number trackingUrl: anyOf: - type: string - type: 'null' description: Courier tracking URL cutoffDate: anyOf: - type: string - type: 'null' description: ISO 8601 cutoff date returned by the manufacturer createdAt: type: string description: ISO 8601 creation timestamp updatedAt: type: string description: ISO 8601 last update timestamp submittedAt: anyOf: - type: string - type: 'null' description: ISO 8601 timestamp when submitted to the manufacturer deliveredAt: anyOf: - type: string - type: 'null' description: ISO 8601 timestamp when all cards were delivered cards: type: array items: $ref: '#/components/schemas/CardShipmentMember' description: Cards included in this shipment required: - id - status - destinationAddress - recipient - courier - trackingNumber - trackingUrl - cutoffDate - createdAt - updatedAt - submittedAt - deliveredAt - cards '400': description: Response for status 400 content: application/json: schema: anyOf: - type: object properties: error: type: object properties: code: type: string const: CARD_NOT_PHYSICAL message: type: string detail: anyOf: - type: object additionalProperties: {} - type: 'null' required: - code - message - detail required: - error title: CardNotPhysicalError description: Card is not a physical card - type: object properties: error: type: object properties: code: type: string const: CARD_NOT_SHIPPABLE message: type: string detail: anyOf: - type: object additionalProperties: {} - type: 'null' required: - code - message - detail required: - error title: CardNotShippableError description: Card is not in a shippable status - type: object properties: error: type: object properties: code: type: string const: SHIPPING_NOT_ALLOWED_FOR_COUNTRY message: type: string detail: anyOf: - type: object additionalProperties: {} - type: 'null' required: - code - message - detail required: - error title: ShippingNotAllowedForCountryError description: Physical card shipping is not allowed for this country - type: object properties: error: type: object properties: code: type: string const: ZONE_REQUIRED message: type: string detail: anyOf: - type: object additionalProperties: {} - type: 'null' required: - code - message - detail required: - error title: ZoneRequiredError description: Zone (state/province) is required for this country - type: object properties: error: type: object properties: code: type: string const: INVALID_ZONE message: type: string detail: anyOf: - type: object additionalProperties: {} - type: 'null' required: - code - message - detail required: - error title: InvalidZoneError description: Zone must be a valid ISO code (1-3 characters) - type: object properties: error: type: object properties: code: type: string const: COURIER_NOT_SUPPORTED message: type: string detail: anyOf: - type: object additionalProperties: {} - type: 'null' required: - code - message - detail required: - error title: CourierNotSupportedError description: Courier is not supported for this country - type: object properties: error: type: object properties: code: type: string const: DUPLICATE_CARD_IN_SHIPMENT message: type: string detail: anyOf: - type: object additionalProperties: {} - type: 'null' required: - code - message - detail required: - error title: DuplicateCardInShipmentError description: Card appears more than once in the shipment - type: object properties: error: type: object properties: code: type: string const: SINGLE_CARD_SHIPMENT_ADDRESS_MISMATCH message: type: string detail: anyOf: - type: object additionalProperties: {} - type: 'null' required: - code - message - detail required: - error title: SingleCardShipmentAddressMismatchError description: >- For single-card shipments the destination address must match the card shipping address - type: object properties: error: type: object properties: code: type: string const: CARD_SHIPMENT_EMPTY message: type: string detail: anyOf: - type: object additionalProperties: {} - type: 'null' required: - code - message - detail required: - error title: CardShipmentEmptyError description: Card shipment must contain at least one card - type: object properties: error: type: object properties: code: type: string const: CARD_SHIPMENT_CARD_LIMIT_EXCEEDED message: type: string detail: anyOf: - type: object additionalProperties: {} - type: 'null' required: - code - message - detail required: - error title: CardShipmentCardLimitExceededError description: Card shipment exceeds the maximum card limit - type: object properties: error: type: object properties: code: type: string const: CARD_SHIPMENT_CARD_DESIGN_NOT_ACTIVE message: type: string detail: anyOf: - type: object additionalProperties: {} - type: 'null' required: - code - message - detail required: - error title: CardShipmentCardDesignNotActiveError description: Card design is no longer active - type: object properties: error: type: object properties: code: type: string const: CARD_SHIPMENT_CARD_DESIGN_NOT_PHYSICAL_CAPABLE message: type: string detail: anyOf: - type: object additionalProperties: {} - type: 'null' required: - code - message - detail required: - error title: CardShipmentCardDesignNotPhysicalCapableError description: Card design cannot be used for physical cards - type: object properties: error: type: object properties: code: type: string const: CARD_SHIPMENT_ALL_CARDS_FAILED message: type: string detail: anyOf: - type: object additionalProperties: {} - type: 'null' required: - code - message - detail required: - error title: CardShipmentAllCardsFailedError description: All cards in the shipment failed at the manufacturer - type: object properties: error: type: object properties: code: type: string const: CARD_RESTRICTED message: type: string detail: anyOf: - type: object additionalProperties: {} - type: 'null' required: - code - message - detail required: - error title: CardRestrictedError description: Card is restricted - type: object properties: error: type: object properties: code: type: string const: CARD_DESIGN_OUT_OF_STOCK message: type: string detail: anyOf: - type: object additionalProperties: {} - type: 'null' required: - code - message - detail required: - error title: CardDesignOutOfStockError description: Card design is out of stock - type: object properties: error: type: object properties: code: type: string const: CARD_SHIPPING_BLOCKED message: type: string detail: anyOf: - type: object additionalProperties: {} - type: 'null' required: - code - message - detail required: - error title: CardShippingBlockedError description: Card shipping is temporarily blocked - type: object properties: error: type: object properties: code: type: string const: SHIPPING_PHONE_INVALID message: type: string detail: anyOf: - type: object additionalProperties: {} - type: 'null' required: - code - message - detail required: - error title: ShippingPhoneInvalidError description: Recipient phone number is invalid - type: object properties: error: type: object properties: code: type: string const: SHIPPING_PHONE_DIAL_CODE_MISMATCH message: type: string detail: anyOf: - type: object additionalProperties: {} - type: 'null' required: - code - message - detail required: - error title: ShippingPhoneDialCodeMismatchError description: Phone dial code does not match the destination country '404': description: Response for status 404 content: application/json: schema: anyOf: - type: object properties: error: type: object properties: code: type: string const: CARD_SHIPMENT_CARD_NOT_FOUND message: type: string detail: anyOf: - type: object additionalProperties: {} - type: 'null' required: - code - message - detail required: - error title: CardShipmentCardNotFoundError description: Card not found - type: object properties: error: type: object properties: code: type: string const: CARD_SHIPMENT_CARD_DESIGN_NOT_FOUND message: type: string detail: anyOf: - type: object additionalProperties: {} - type: 'null' required: - code - message - detail required: - error title: CardShipmentCardDesignNotFoundError description: Card design not found - type: object properties: error: type: object properties: code: type: string const: CARD_SHIPMENT_NOT_FOUND message: type: string detail: anyOf: - type: object additionalProperties: {} - type: 'null' required: - code - message - detail required: - error title: CardShipmentNotFoundError description: Card shipment not found '409': description: Response for status 409 content: application/json: schema: anyOf: - type: object properties: error: type: object properties: code: type: string const: ACTIVE_CARD_SHIPMENT_EXISTS message: type: string detail: anyOf: - type: object additionalProperties: {} - type: 'null' required: - code - message - detail required: - error title: ActiveCardShipmentExistsError description: Card already belongs to an active shipment - type: object properties: error: type: object properties: code: type: string const: CARD_SHIPMENT_NOT_DRAFT message: type: string detail: anyOf: - type: object additionalProperties: {} - type: 'null' required: - code - message - detail required: - error title: CardShipmentNotDraftError description: Shipment is no longer in DRAFT status - type: object properties: error: type: object properties: code: type: string const: CARD_ALREADY_IN_PRODUCTION message: type: string detail: anyOf: - type: object additionalProperties: {} - type: 'null' required: - code - message - detail required: - error title: CardAlreadyInProductionError description: Card is already in production or shipped - type: object properties: error: type: object properties: code: type: string const: BULK_SHIP_CUTOFF_PASSED message: type: string detail: anyOf: - type: object additionalProperties: {} - type: 'null' required: - code - message - detail required: - error title: BulkShipCutoffPassedError description: Bulk ship cutoff date has passed '502': description: Card shipping provider error content: application/json: schema: type: object properties: error: type: object properties: code: type: string const: CARD_SHIPPING_PROVIDER_ERROR message: type: string detail: anyOf: - type: object additionalProperties: {} - type: 'null' required: - code - message - detail required: - error title: CardShippingProviderError components: schemas: CardShippingAddress: type: object properties: line1: type: string minLength: 1 description: Street address line 1 line2: anyOf: - type: string - type: 'null' description: Street address line 2 zone: anyOf: - type: string - type: 'null' description: State, province, or zone city: type: string minLength: 1 description: City postalCode: type: string minLength: 1 description: Postal code country: type: string minLength: 2 maxLength: 2 examples: - US - GB - DE description: ISO 3166-1 alpha-2 country code required: - line1 - line2 - zone - city - postalCode - country description: Shipping address CardShipmentRecipient: type: object properties: firstName: type: string minLength: 1 description: Recipient first name lastName: type: string minLength: 1 description: Recipient last name phoneNumber: type: string minLength: 1 description: Recipient phone number dialCode: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 description: Phone dial code email: type: string format: email pattern: >- ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$ description: Recipient email address required: - firstName - lastName - phoneNumber - dialCode - email description: Recipient details CardShipmentMember: type: object properties: id: type: string format: uuid description: Unique shipment member identifier cardId: type: string format: uuid description: ID of the card being shipped cardDesignId: type: string description: Card design identifier shippingAddress: $ref: '#/components/schemas/CardShippingAddress' description: Per-card final destination address productionStatus: type: string enum: - PENDING - REQUESTED - IN_PRODUCTION - COMPLETED - ACTIVATED - CANCELED - ON_HOLD - BULK_SHIP_REJECTED description: Per-card production status example: PENDING rejectedAt: anyOf: - type: string - type: 'null' description: >- ISO 8601 timestamp when this card was rejected and excluded from the shipment, or null if the card was accepted createdAt: type: string description: ISO 8601 creation timestamp updatedAt: type: string description: ISO 8601 last update timestamp required: - id - cardId - cardDesignId - shippingAddress - productionStatus - rejectedAt - createdAt - updatedAt securitySchemes: bearerAuth: type: http scheme: bearer description: API key as Bearer token ````