> ## 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. # Create shipment draft > Creates a new card shipment in `DRAFT` status. No manufacturer call is made until the draft is explicitly submitted. ## OpenAPI ````yaml /api-reference/openapi.json post /card-shipments/ 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/: post: tags: - Card Shipments summary: Create shipment draft description: >- Creates a new card shipment in `DRAFT` status. No manufacturer call is made until the draft is explicitly submitted. operationId: create_card-shipments parameters: - name: Reap-Version in: header required: true schema: type: string enum: - '2025-02-14' description: API version (YYYY-MM-DD) example: '2025-02-14' requestBody: description: Request body for creating a card shipment required: true content: application/json: schema: type: object properties: destinationAddress: 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 - city - postalCode - country description: Box-level destination address recipient: $ref: '#/components/schemas/CardShipmentRecipient' courier: oneOf: - type: object properties: type: type: string const: POSTAL name: anyOf: - type: 'null' - type: string const: '' title: '' required: - type title: Postal - type: object properties: type: type: string const: COURIER name: type: string enum: - DHL - FEDEX - SFEXPRESS example: DHL required: - type - name title: Courier description: Courier selection cards: minItems: 1 type: array items: type: object properties: cardId: description: ID of the card to ship type: string format: uuid cardDesignId: description: Card design identifier type: string minLength: 1 shippingAddress: 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 - city - postalCode - country description: Per-card final destination address required: - cardId - cardDesignId - shippingAddress description: One card entry in a shipment description: Cards to include in this shipment required: - destinationAddress - recipient - courier - cards application/x-www-form-urlencoded: schema: type: object properties: destinationAddress: 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 - city - postalCode - country description: Box-level destination address recipient: $ref: '#/components/schemas/CardShipmentRecipient' courier: oneOf: - type: object properties: type: type: string const: POSTAL name: anyOf: - type: 'null' - type: string const: '' title: '' required: - type title: Postal - type: object properties: type: type: string const: COURIER name: type: string enum: - DHL - FEDEX - SFEXPRESS example: DHL required: - type - name title: Courier description: Courier selection cards: minItems: 1 type: array items: type: object properties: cardId: description: ID of the card to ship type: string format: uuid cardDesignId: description: Card design identifier type: string minLength: 1 shippingAddress: 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 - city - postalCode - country description: Per-card final destination address required: - cardId - cardDesignId - shippingAddress description: One card entry in a shipment description: Cards to include in this shipment required: - destinationAddress - recipient - courier - cards multipart/form-data: schema: type: object properties: destinationAddress: 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 - city - postalCode - country description: Box-level destination address recipient: $ref: '#/components/schemas/CardShipmentRecipient' courier: oneOf: - type: object properties: type: type: string const: POSTAL name: anyOf: - type: 'null' - type: string const: '' title: '' required: - type title: Postal - type: object properties: type: type: string const: COURIER name: type: string enum: - DHL - FEDEX - SFEXPRESS example: DHL required: - type - name title: Courier description: Courier selection cards: minItems: 1 type: array items: type: object properties: cardId: description: ID of the card to ship type: string format: uuid cardDesignId: description: Card design identifier type: string minLength: 1 shippingAddress: 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 - city - postalCode - country description: Per-card final destination address required: - cardId - cardDesignId - shippingAddress description: One card entry in a shipment description: Cards to include in this shipment required: - destinationAddress - recipient - courier - cards responses: '200': description: Card shipment resource content: application/json: schema: $ref: '#/components/schemas/CardShipment' '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_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 '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 '409': description: Card already belongs to an active shipment content: application/json: schema: 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 components: schemas: 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 CardShipment: 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 required: - id - status - destinationAddress - recipient - courier - trackingNumber - trackingUrl - cutoffDate - createdAt - updatedAt - submittedAt - deliveredAt 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 securitySchemes: bearerAuth: type: http scheme: bearer description: API key as Bearer token ````