> ## 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.

# Managing card designs

> Where card designs are configured, which API key sees which designs, and how to activate or deactivate a design

## Overview

A card design is a look a customer can choose for their card. Each design has a name,
light and dark artwork, an orientation, partner-defined `categories` (for example
league or team), a loyalty tier requirement (`access_min_rank`), a `type`, and a
`status`.

Imprint creates card designs and their artwork. You can list them, retrieve one by ID,
and activate or deactivate them as your catalog changes, for example when a licensed
design becomes available or its licence ends.

Only `ACTIVE` designs can be selected by customers. `INACTIVE` designs are still
returned by the API, so you can find them and reactivate them later.

### Loyalty tier requirements

A design can be limited to customers at or above a tier in your loyalty program.

* `access_min_rank` is the minimum tier rank needed to select the design. `0` means
  every customer can select it.
* Your product's tiers each have a rank; a higher rank is a more premium tier. Imprint
  configures the tiers and each design's `access_min_rank` with you.
* A customer's tier comes from the loyalty data you share with Imprint for that
  product. A customer with no tier, or a tier Imprint does not recognize, is treated as
  rank `0`.
* A customer cannot select a design whose `access_min_rank` is above their tier, even
  if your app offers it.
* `loyalty_tier_name` is currently always omitted. Map `access_min_rank` to your own
  tier labels.

Because tiers are defined per product, filtering designs by customer always needs a
product. See [Listing card designs](#listing-card-designs).

## Where card designs are configured

Card designs are configured at one of two levels:

| Level | Applies to | Use it for |
| - | - | - |
| Partner | All of your products | One shared set of designs offered on every product |
| Product | One product | Designs exclusive to that product |

A product that has no designs of its own offers your partner-level designs. A product
with its own designs offers only those.

Each product has one `DEFAULT` design. It is issued when a customer does not choose a
design, and it cannot be deactivated.

## API key scopes

Which designs a request can see and change depends on the API key and on whether the
request sends an `x-imprint-merchant-key` header.

| API key | `x-imprint-merchant-key` | The request acts for |
| - | - | - |
| Partner-scoped | Not sent | Your partner, across all of your products |
| Partner-scoped | Sent | The product the merchant key identifies |
| Product-scoped | — | The product the key belongs to |

A partner-scoped key without a merchant key is accepted only by some endpoints,
including the card design endpoints on this page. Other endpoints return `401` and
require a merchant key.

Reading card designs needs no scope. Changing a design's status requires the
`CARD_DESIGN_WRITE` scope on the API key. Contact your Imprint team to have it added.

## Listing card designs

```
GET /v2/card_designs
```

| Request | Returns |
| - | - |
| Partner-scoped key, no merchant key | Your partner-level designs |
| Merchant key, or product-scoped key | The product's designs, or your partner-level designs if the product has none of its own |

Both `ACTIVE` and `INACTIVE` designs are returned. Check `status` before offering a
design to a customer.

| Parameter | In | Description |
| - | - | - |
| `customer_id` | query | Return only designs this customer's loyalty tier allows. Requires a merchant key or a product-scoped key; with a partner-scoped key alone it returns `400`. |
| `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.png",
      "dark_asset_url_path": "https://assets.imprint.co/brand-assets/card-designs/dark/midnight-black.png"
    }
  ],
  "has_more": false,
  "total": 1
}
```

Without `customer_id`, gated designs are included with their `access_min_rank`, so you
can show them as locked. With `customer_id`, designs above the customer's tier are left
out.

## Retrieving a card design

```
GET /v2/card_designs/{card_design_id}
```

Returns one design, `ACTIVE` or `INACTIVE`.

| Request | Partner-level design | Product design |
| - | - | - |
| Partner-scoped key, no merchant key | Returned | Returned for any of your products |
| Merchant key, or product-scoped key | `404` | Returned for that product only |

A design you cannot access returns the same `404` as a design that does not exist.

## Choosing the right request

| You want to | Send |
| - | - |
| Manage your whole catalog across products | A partner-scoped key without a merchant key |
| See what one product offers | That product's merchant key, or its product-scoped key |
| See what one customer can select | The product's merchant key or product-scoped key, plus `customer_id` |

## Activating and deactivating a design

```
PATCH /v2/card_designs/{card_design_id}
```

**Required scope:** `CARD_DESIGN_WRITE`

```json Request theme={null}
{ "status": "INACTIVE" }
```

`status` is the only field you can change, and it must be `ACTIVE` or `INACTIVE`. The
response is the updated design.

| Request | Partner-level design | Product design |
| - | - | - |
| Partner-scoped key, no merchant key | Can change | Can change for any of your products |
| Merchant key, or product-scoped key | `404` | Can change for that product only |

* Sending the status a design already has returns `200` and changes nothing.
* A product's `DEFAULT` design cannot be deactivated; the request returns `400`.
* Once a design is `INACTIVE`, customers can no longer select it.

## Errors

| Status | Body | When |
| - | - | - |
| `400` | `details` lists the problem | `status` is not `ACTIVE` or `INACTIVE`, the request would deactivate a `DEFAULT` design, or `customer_id` is sent with a partner-scoped key alone |
| `401` | `error.type` is `UNAUTHORIZED_ERROR` | A partner-scoped key without a merchant key called an endpoint that requires one |
| `403` | `error.type` is `FORBIDDEN_ERROR` | The API key is missing `CARD_DESIGN_WRITE` |
| `404` | `type` is `CARD_DESIGN_NOT_FOUND_ERROR` | The design does not exist, or the request cannot access it |

## Related

* [Application APIs: Card designs](https://docs.imprint.co/partner-application-card-designs) for selecting a
  design during an application
* [List card designs](https://docs.imprint.co/api-reference/card-designs/list-card-designs.md),
  [Retrieve a card design](https://docs.imprint.co/api-reference/card-designs/retrieve-a-card-design.md), and
  [Update a card design](https://docs.imprint.co/api-reference/card-designs/update-a-card-design.md) in the API
  reference


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