Create Custom Card

Creates a custom card using previously uploaded images and configuration. Use dimension_id to select the card size and format — see /cards/listDimensions for available options. Flat cards (e.g. dimension_id 1) have a front and back surface. Foldable cards (e.g. dimension_id 3) have four surfaces: front, back, inside top (main), and inside bottom (header/footer).

Instead of a custom uploaded cover, a preset cover can be used via preset_cover_id — see /cards/listPresetCovers for available presets.

To update an existing custom card, pass is_update: true along with the existing card_id.

The returned card_id can be used in orders like any other card.

Request Body
card_id integer Required when updating an existing custom card (is_update: true). The ID of the card to update.
name string — REQUIRED The name of the custom card.
dimension_id integer Card size and format. See /cards/listDimensions for available options.
is_update boolean Set to true to update an existing custom card. Must be combined with card_id.
cover_id integer ID of the uploaded cover image (type: cover) to use as the front of the card.
preset_cover_id integer ID of a preset cover to use instead of a custom uploaded image. See /cards/listPresetCovers.
cover_size_percent integer
header_type string Possible values: [text, logo] Whether the header uses text or a logo image. Foldable cards only.
header_text string Header text. Used when header_type is 'text'.
header_font_size integer
header_font_color string Hex color code.
header_font_id integer Font ID for the header text. See /fonts/listForCustomizer.
header_align string Possible values: [left, center, right]
header_logo_id integer ID of the logo image (type: logo) for the header. Used when header_type is 'logo'.
header_logo_size_percent integer
footer_type string Possible values: [text, logo] Whether the footer uses text or a logo image.
footer_text string Footer text. Used when footer_type is 'text'.
footer_font_size integer
footer_font_color string Hex color code.
footer_font_id integer Font ID for the footer text. See /fonts/listForCustomizer.
footer_align string Possible values: [left, center, right]
footer_logo_id integer ID of the logo image (type: logo) for the footer. Used when footer_type is 'logo'.
footer_logo_size_percent integer
main_type string Possible values: [text, logo] Content type for the inside top surface. Foldable cards only.
main_text string Inside top text. Used when main_type is 'text'.
main_font_size integer
main_font_color string Hex color code.
main_font_id integer Font ID for the inside top text. See /fonts/listForCustomizer.
main_align string Possible values: [left, center, right]
main_logo_id integer ID of the logo image (type: logo) for the inside top. Used when main_type is 'logo'.
main_logo_size_percent integer
back_type string Possible values: [text, logo] Content type for the back surface.
back_text string Back text. Used when back_type is 'text'.
back_font_size integer
back_font_color string Hex color code.
back_font_id integer Font ID for the back text. See /fonts/listForCustomizer.
back_align string Possible values: [left, center, right]
back_vertical_align string Possible values: [top, center, bottom]
back_logo_id integer ID of the logo image (type: logo) for the back. Used when back_type is 'logo'.
back_size_percent integer
back_cover_id integer ID of an uploaded cover image (type: cover) for the back surface.
preset_back_cover_id integer ID of a preset cover for the back surface. See /cards/listPresetCovers.
qr_code_id integer ID of the QR code to include. See /qrCode for available QR codes.
qr_code_size_percent integer
qr_code_align string Possible values: [left, center, right]
qr_code_location string Possible values: [header, footer]
qr_code_frame_id integer ID of the QR code frame. See /qrCode/frames for available frames.

Responses
200 OK Schema — OPTIONAL httpCode integer — OPTIONAL status string — OPTIONAL card_id integer — OPTIONAL category_id integer — OPTIONAL Always 27 — all custom cards are placed in the user's private Custom Cards category.