Skip to main content
Private preview, shared by direct link. Start at the Application APIs overview.
Choosing a card is part of applying. The physical card is issued only once a design is selected (see Card issuance), so if you own the application, you offer the design choice. GET /v2/card_designs is generally available and published in the REST API reference. It needs no private-preview enablement.

​
List card designs

Response (200)
If your program defines no designs of its own, you receive the designs configured for your partner. The list includes INACTIVE designs as well as ACTIVE ones. Only ACTIVE designs can be selected, so filter on status before offering a design. With a partner-scoped API key and no x-imprint-merchant-key header, the list returns the designs configured for your partner. customer_id is not supported without a merchant key and returns 400; send the merchant key of the customer’s product to filter by customer.
starting_after on this endpoint takes the opaque next_page_token from the previous response, not a card design id as other list endpoints do. Treat the token as opaque.

​
Tier-gated designs

access_min_rank is the minimum loyalty tier rank needed to select a design. 0 means available to everyone. Whether you pass customer_id decides which designs you receive: Gated designs are filtered out when you pass customer_id, not flagged. If you want to present locked designs, call without customer_id and compare access_min_rank against the customer’s tier yourself.
loyalty_tier_name is currently always omitted, so you cannot label a locked design with the tier name it requires. Map access_min_rank to your own tier copy.

​
Before and after the customer exists

During an application there is no customer_id until the offer is accepted, so the two calls above return different sets. Treat them as two separate fetches:
  1. Before the customer exists. Call GET /v2/card_designs with no customer_id. Every design, gated ones included.
  2. Once the customer exists. Call again with customer_id. Now scoped to what they can select.
Cache each response for as long as you are on that side of the boundary. Designs change when program configuration changes, not per request. Don’t reuse the pre-customer response once the customer exists. It can contain designs the customer is not eligible for, and selecting one of those will fail.

​
Selecting a design

Pass the chosen design’s id as card_design_id. There are three ways to set it, in order of precedence: Acceptance commits the design for that product offer. It is then immutable, comes back as the product offer’s card_design_id, and is the design printed on the card. A PATCH with card_design_id after acceptance returns 409. The card_design requirement (kind: SELECTION, blocks: OFFER_ACCEPTANCE) reads SATISFIED as soon as any of the three is set. See The card the customer is actually holding for reading back the design on the issued card.

​
Artwork assets

light_asset_url_path and dark_asset_url_path are absolute URLs, served from https://assets.imprint.co or https://app.imprint.co depending on where the artwork was uploaded. Use them as-is; don’t prepend a host. image_orientation (VERTICAL or HORIZONTAL) describes the artwork itself. categories carries partner-defined key/value labels for grouping designs. See Managing card designs for where designs are configured, which API key sees which designs, and how to activate or deactivate a design.