Managing card designs

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.

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

Response (200)

{
  "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

Request

{ "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

Application APIs: Card designs for selecting a design during an application
List card designs, Retrieve a card design, and Update a card design in the API reference

Getting Started

Applications

Cards

Transactions

Rewards

Account Linking

Webhook Event Notifications

API Keys

Servicing

Sandbox Testing

SDK Reference

Overview

Loyalty tier requirements

Where card designs are configured

API key scopes

Listing card designs

Retrieving a card design

Choosing the right request

Activating and deactivating a design

Errors

​Overview

​Loyalty tier requirements

​Where card designs are configured

​API key scopes

​Listing card designs

​Retrieving a card design

​Choosing the right request

​Activating and deactivating a design

​Errors

​Related

Overview

Loyalty tier requirements

Where card designs are configured

API key scopes

Listing card designs

Retrieving a card design

Choosing the right request

Activating and deactivating a design

Errors

Related