> ## Documentation Index
> Fetch the complete documentation index at: https://docs.imprint.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Application APIs: Card designs

> Listing card designs, loyalty-tier gating, and committing a design on accept

> [!NOTE]
>
> Private preview, shared by direct link. Start at the
> [Application APIs overview](https://docs.imprint.co/partner-application-apis).

Choosing a card is part of applying. The physical card is issued only once a
design is selected (see [Card issuance](https://docs.imprint.co/guide-unified-card-experience.md)), 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](https://docs.imprint.co/api-reference). It needs no private-preview enablement.

## List card designs

```
GET /v2/card_designs
```

| Parameter | In | Description |
| - | - | - |
| `customer_id` | query | Return only designs this customer can select, based on their loyalty tier. Omit it to receive every design the program offers. |
| `search_term` | query | Filter designs by name. |
| `starting_after` | query | Pagination cursor. Pass the previous response's `next_page_token`. |

```json Response (200) theme={null}
{
  "data": [
    {
      "id": "3b9c1f3e-52a0-44c1-b131-a7ab0099a214",
      "name": "Midnight Black",
      "access_min_rank": 0,
      "type": "REGULAR",
      "status": "ACTIVE",
      "image_orientation": "VERTICAL",
      "light_asset_url_path": "https://assets.imprint.co/brand-assets/card-designs/light/midnight-black.svg",
      "dark_asset_url_path": "https://assets.imprint.co/brand-assets/card-designs/dark/midnight-black.svg"
    }
  ],
  "has_more": false,
  "total": 1
}
```

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.

> [!NOTE]
>
> `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:

| Call | Returns | Use it for |
| - | - | - |
| `GET /v2/card_designs` | Every design, gated ones included, each with its `access_min_rank` | Presenting gated designs as locked, with the tier they need |
| `GET /v2/card_designs?customer_id=…` | Only designs this customer can select | Offering only designs the customer can select |

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.

> [!NOTE]
>
> `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:

| Where | When |
| - | - |
| `card_design_id` on `POST .../accept` | At acceptance |
| `card_design_id` on `PATCH /v2/applications/{id}` | Any time before acceptance; editable through `OFFERS_AVAILABLE` |
| `card_design.default_card_design_id` from the configuration | Used when neither of the above is set |

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](https://docs.imprint.co/guide-embedded-servicing.md#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](https://docs.imprint.co/managing-card-designs.md) for where designs are configured,
which API key sees which designs, and how to activate or deactivate a design.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.