# Physical Cards
> Custom physical Visa cards that are shipped to your customers. The artwork is configurable by a connected [Card Profile](/documentation/api#card-profiles). The same Card can be used for multiple Physical Cards. Printing cards incurs a fee. Please contact [support@increase.com](mailto:support@increase.com) for pricing!

[Events](https://increase.com/documentation/events.md) will be generated for this resource. The possible event categories are: `physical_card.created` and `physical_card.updated`.

## The Physical Card object
### Example
```json
{
  "card_id": "card_oubs0hwk5rn6knuecxg2",
  "cardholder": {
    "first_name": "Ian",
    "last_name": "Crease"
  },
  "created_at": "2020-01-31T23:59:59Z",
  "id": "physical_card_ode8duyq5v2ynhjoharl",
  "idempotency_key": null,
  "physical_card_profile_id": "physical_card_profile_m534d5rn9qyy9ufqxoec",
  "shipment": {
    "address": {
      "city": "New York",
      "country": "US",
      "line1": "33 Liberty Street",
      "line2": "Unit 2",
      "line3": null,
      "name": "Ian Crease",
      "postal_code": "10045",
      "state": "NY"
    },
    "method": "usps",
    "schedule": "next_day",
    "status": "shipped",
    "tracking": {
      "number": "9400110200881234567890",
      "return_number": null,
      "return_reason": null,
      "shipped_at": "2020-01-31T23:59:59Z",
      "updates": [
        {
          "carrier_estimated_delivery_at": null,
          "category": "delivered",
          "city": null,
          "created_at": "2020-01-31T23:59:59Z",
          "postal_code": "10001",
          "state": null
        }
      ]
    }
  },
  "status": "active",
  "type": "physical_card"
}
```
### Attributes
- `card_id` (string)
  The identifier for the Card this Physical Card represents.

- `cardholder` (dictionary)
  Details about the cardholder, as it appears on the printed card.

  - `cardholder.first_name` (string)
    The cardholder's first name.

  - `cardholder.last_name` (string)
    The cardholder's last name.

- `created_at` (string)
  The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time at which the Physical Card was created.

- `id` (string)
  The physical card identifier.

- `idempotency_key` (string, nullable)
  The idempotency key you chose for this object. This value is unique across Increase and is used to ensure that a request is only processed once. Learn more about [idempotency](https://increase.com/documentation/idempotency-keys).

- `physical_card_profile_id` (string, nullable)
  The Physical Card Profile used for this Physical Card.

- `shipment` (dictionary)
  The details used to ship this physical card.

  - `shipment.address` (dictionary)
    The location to where the card's packing label is addressed.

      - `shipment.address.city` (string)
        The city of the shipping address.

      - `shipment.address.country` (string)
        The country of the shipping address.

      - `shipment.address.line1` (string)
        The first line of the shipping address.

      - `shipment.address.line2` (string, nullable)
        The second line of the shipping address.

      - `shipment.address.line3` (string, nullable)
        The third line of the shipping address.

      - `shipment.address.name` (string)
        The name of the recipient.

      - `shipment.address.postal_code` (string)
        The postal code of the shipping address.

      - `shipment.address.state` (string)
        The state of the shipping address.

  - `shipment.method` (enum)
    The shipping method.
    Cases:
    * `usps` (USPS Post.)
    * `fedex_priority_overnight` (FedEx Priority Overnight, no signature.)
    * `fedex_2_day` (FedEx 2-day.)
    * `dhl_worldwide_express` (DHL Worldwide Express, international shipping only.)

  - `shipment.schedule` (enum)
    When this physical card should be produced by the card printer. The default timeline is the day after the card printer receives the order, except for `FEDEX_PRIORITY_OVERNIGHT` cards, which default to `SAME_DAY`. To use faster production methods, please reach out to [support@increase.com](mailto:support@increase.com).
    Cases:
    * `next_day` (The physical card will be shipped one business day after the order is received by the card printer. A card that is submitted to Increase on a Monday evening (Pacific Time) will ship out on Wednesday.)
    * `same_day` (The physical card will be shipped on the same business day that the order is received by the card printer. A card that is submitted to Increase on a Monday evening (Pacific Time) will ship out on Tuesday.)

  - `shipment.status` (enum)
    The status of this shipment.
    Cases:
    * `pending` (The physical card has not yet been shipped.)
    * `canceled` (The physical card shipment was canceled prior to submission.)
    * `submitted` (The physical card shipment has been submitted to the card fulfillment provider.)
    * `acknowledged` (The physical card shipment has been acknowledged by the card fulfillment provider and will be processed in their next batch.)
    * `rejected` (The physical card shipment was rejected by the card printer due to an error.)
    * `shipped` (The physical card has been shipped.)
    * `returned` (The physical card shipment was returned to the sender and destroyed by the production facility.)
    * `requires_attention` (The physical card shipment requires attention from Increase before progressing.)

  - `shipment.tracking` (dictionary, nullable)
    Tracking details for the shipment.

      - `shipment.tracking.number` (string, nullable)
        The tracking number. Not available for USPS shipments.

      - `shipment.tracking.return_number` (string, nullable)
        For returned shipments, the tracking number of the return shipment.

      - `shipment.tracking.return_reason` (string, nullable)
        For returned shipments, this describes why the package was returned.

      - `shipment.tracking.shipped_at` (string)
        The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time at which the fulfillment provider marked the card as ready for pick-up by the shipment carrier.

      - `shipment.tracking.updates` (array of objects)
        Tracking updates relating to the physical card's delivery.

            - `shipment.tracking.updates.carrier_estimated_delivery_at` (string, nullable)
              The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time when the carrier expects the card to be delivered.

            - `shipment.tracking.updates.category` (enum)
              The type of tracking event.
              Cases:
              * `in_transit` (The physical card is in transit.)
              * `processed_for_delivery` (The physical card has been processed for delivery.)
              * `delivered` (The physical card has been delivered.)
              * `delivery_issue` (There is an issue preventing delivery. The delivery will be attempted again if possible. If the issue cannot be resolved, the physical card will be returned to sender.)
              * `returned_to_sender` (Delivery failed and the physical card was returned to sender.)

            - `shipment.tracking.updates.city` (string, nullable)
              The city where the event took place.

            - `shipment.tracking.updates.created_at` (string)
              The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time at which the tracking event took place.

            - `shipment.tracking.updates.postal_code` (string, nullable)
              The postal code where the event took place.

            - `shipment.tracking.updates.state` (string, nullable)
              The state where the event took place.

- `status` (enum)
  The status of the Physical Card.
  Cases:
  * `active` (The physical card is active.)
  * `disabled` (The physical card is temporarily disabled.)
  * `canceled` (The physical card is permanently canceled.)

- `type` (string)
  A constant representing the object's type. For this resource it will always be `physical_card`.

## List Physical Cards
GET /physical_cards

### Example
```curl
curl \
  --url "${INCREASE_URL}/physical_cards?card_id=card_oubs0hwk5rn6knuecxg2" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}"
```

### Query Parameters
- `cursor` (string, optional)
  Return the page of entries after this one.

- `limit` (integer, optional)
  Limit the size of the list that is returned. The default (and maximum) is 100 objects.

- `card_id` (string, optional)
  Filter Physical Cards to ones belonging to the specified Card.

- `created_at.after` (string, optional)
  Return results after this [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp.

- `created_at.before` (string, optional)
  Return results before this [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp.

- `created_at.on_or_after` (string, optional)
  Return results on or after this [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp.

- `created_at.on_or_before` (string, optional)
  Return results on or before this [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp.

- `idempotency_key` (string, optional)
  Filter records to the one with the specified `idempotency_key` you chose for that object. This value is unique across Increase and is used to ensure that a request is only processed once. Learn more about [idempotency](https://increase.com/documentation/idempotency-keys).

### Returns a Physical Card List object:
```json
{
  "data": [
    {
      "card_id": "card_oubs0hwk5rn6knuecxg2",
      "cardholder": {
        "first_name": "Ian",
        "last_name": "Crease"
      },
      "created_at": "2020-01-31T23:59:59Z",
      "id": "physical_card_ode8duyq5v2ynhjoharl",
      "idempotency_key": null,
      "physical_card_profile_id": "physical_card_profile_m534d5rn9qyy9ufqxoec",
      "shipment": {
        "address": {
          "city": "New York",
          "country": "US",
          "line1": "33 Liberty Street",
          "line2": "Unit 2",
          "line3": null,
          "name": "Ian Crease",
          "postal_code": "10045",
          "state": "NY"
        },
        "method": "usps",
        "schedule": "next_day",
        "status": "shipped",
        "tracking": {
          "number": "9400110200881234567890",
          "return_number": null,
          "return_reason": null,
          "shipped_at": "2020-01-31T23:59:59Z",
          "updates": [
            {
              "carrier_estimated_delivery_at": null,
              "category": "delivered",
              "city": null,
              "created_at": "2020-01-31T23:59:59Z",
              "postal_code": "10001",
              "state": null
            }
          ]
        }
      },
      "status": "active",
      "type": "physical_card"
    }
  ],
  "next_cursor": "v57w5d"
}
```

## Create a Physical Card
POST /physical_cards

### Example
```curl
curl -X "POST" \
  --url "${INCREASE_URL}/physical_cards" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d $'{
    "card_id": "card_oubs0hwk5rn6knuecxg2",
    "cardholder": {
      "first_name": "Ian",
      "last_name": "Crease"
    },
    "shipment": {
      "address": {
        "city": "New York",
        "line1": "33 Liberty Street",
        "line2": "Unit 2",
        "name": "Ian Crease",
        "postal_code": "10045",
        "state": "NY"
      },
      "method": "usps"
    }
  }'
```

### Body Parameters
- `card_id` (string, required)
  The underlying card representing this physical card.

- `cardholder` (dictionary, required)
  Details about the cardholder, as it will appear on the physical card.

  - `cardholder.first_name` (string, required)
    The cardholder's first name.

  - `cardholder.last_name` (string, required)
    The cardholder's last name.

- `physical_card_profile_id` (string, optional)
  The physical card profile to use for this physical card. The latest default physical card profile will be used if not provided.

- `shipment` (dictionary, required)
  The details used to ship this physical card.

  - `shipment.address` (dictionary, required)
    The address to where the card should be shipped.

      - `shipment.address.city` (string, required)
        The city of the shipping address.

      - `shipment.address.country` (string, optional)
        The two-character ISO 3166-1 code of the country where the card should be shipped (e.g., `US`). Please reach out to [support@increase.com](mailto:support@increase.com) to ship cards internationally.

      - `shipment.address.line1` (string, required)
        The first line of the shipping address.

      - `shipment.address.line2` (string, optional)
        The second line of the shipping address.

      - `shipment.address.line3` (string, optional)
        The third line of the shipping address.

      - `shipment.address.name` (string, required)
        The name of the recipient.

      - `shipment.address.phone_number` (string, optional)
        The phone number of the recipient.

      - `shipment.address.postal_code` (string, required)
        The postal code of the shipping address.

      - `shipment.address.state` (string, required)
        The state of the shipping address.

  - `shipment.method` (enum, required)
    The shipping method to use.
    Cases:
    * `usps` (USPS Post.)
    * `fedex_priority_overnight` (FedEx Priority Overnight, no signature.)
    * `fedex_2_day` (FedEx 2-day.)
    * `dhl_worldwide_express` (DHL Worldwide Express, international shipping only.)

  - `shipment.schedule` (enum, optional)
    When this physical card should be produced by the card printer. The default timeline is the day after the card printer receives the order, except for `FEDEX_PRIORITY_OVERNIGHT` cards, which default to `SAME_DAY`. To use faster production methods, please reach out to [support@increase.com](mailto:support@increase.com).
    Cases:
    * `next_day` (The physical card will be shipped one business day after the order is received by the card printer. A card that is submitted to Increase on a Monday evening (Pacific Time) will ship out on Wednesday.)
    * `same_day` (The physical card will be shipped on the same business day that the order is received by the card printer. A card that is submitted to Increase on a Monday evening (Pacific Time) will ship out on Tuesday.)

## Retrieve a Physical Card
GET /physical_cards/{physical_card_id}

### Example
```curl
curl \
  --url "${INCREASE_URL}/physical_cards/physical_card_ode8duyq5v2ynhjoharl" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}"
```
### Path Parameters
- `physical_card_id` (string, required)
  The identifier of the Physical Card.

## Update a Physical Card
PATCH /physical_cards/{physical_card_id}

### Example
```curl
curl -X "PATCH" \
  --url "${INCREASE_URL}/physical_cards/physical_card_ode8duyq5v2ynhjoharl" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d $'{
    "status": "disabled"
  }'
```
### Path Parameters
- `physical_card_id` (string, required)
  The Physical Card identifier.

### Body Parameters
- `status` (enum, required)
  The status to update the Physical Card to.
  Cases:
  * `active` (The physical card is active.)
  * `disabled` (The physical card is temporarily disabled.)
  * `canceled` (The physical card is permanently canceled.)

## Sandbox: Advance the shipment status of a Physical Card
POST /simulations/physical_cards/{physical_card_id}/advance_shipment
> This endpoint allows you to simulate advancing the shipment status of a Physical Card, to simulate e.g., that a physical card was attempted shipped but then failed delivery.
### Example
```curl
curl -X "POST" \
  --url "${INCREASE_URL}/simulations/physical_cards/physical_card_ode8duyq5v2ynhjoharl/advance_shipment" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d $'{
    "shipment_status": "shipped"
  }'
```
### Path Parameters
- `physical_card_id` (string, required)
  The Physical Card you would like to action.

### Body Parameters
- `shipment_status` (enum, required)
  The shipment status to move the Physical Card to.
  Cases:
  * `pending` (The physical card has not yet been shipped.)
  * `canceled` (The physical card shipment was canceled prior to submission.)
  * `submitted` (The physical card shipment has been submitted to the card fulfillment provider.)
  * `acknowledged` (The physical card shipment has been acknowledged by the card fulfillment provider and will be processed in their next batch.)
  * `rejected` (The physical card shipment was rejected by the card printer due to an error.)
  * `shipped` (The physical card has been shipped.)
  * `returned` (The physical card shipment was returned to the sender and destroyed by the production facility.)
  * `requires_attention` (The physical card shipment requires attention from Increase before progressing.)

## Sandbox: Create a Physical Card Shipment Tracking Update
POST /simulations/physical_cards/{physical_card_id}/tracking_updates
> This endpoint allows you to simulate receiving a tracking update for a Physical Card, to simulate the progress of a shipment.
### Example
```curl
curl -X "POST" \
  --url "${INCREASE_URL}/simulations/physical_cards/physical_card_ode8duyq5v2ynhjoharl/tracking_updates" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d $'{
    "category": "delivered",
    "city": "New York",
    "postal_code": "10045",
    "state": "NY"
  }'
```
### Path Parameters
- `physical_card_id` (string, required)
  The Physical Card you would like to action.

### Body Parameters
- `carrier_estimated_delivery_at` (string, optional)
  The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time when the carrier expects the card to be delivered.

- `category` (enum, required)
  The type of tracking event.
  Cases:
  * `in_transit` (The physical card is in transit.)
  * `processed_for_delivery` (The physical card has been processed for delivery.)
  * `delivered` (The physical card has been delivered.)
  * `delivery_issue` (There is an issue preventing delivery. The delivery will be attempted again if possible. If the issue cannot be resolved, the physical card will be returned to sender.)
  * `returned_to_sender` (Delivery failed and the physical card was returned to sender.)

- `city` (string, optional)
  The city where the event took place.

- `postal_code` (string, optional)
  The postal code where the event took place.

- `state` (string, optional)
  The state where the event took place.