# Card Purchase Supplements
> Additional information about a card purchase (e.g., settlement or refund), such as level 3 line item data.

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

## The Card Purchase Supplement object
### Example
```json
{
  "card_payment_id": "card_payment_nd3k2kacrqjli8482ave",
  "id": "card_purchase_supplement_ijuc45iym4jchnh2sfk3",
  "invoice": {
    "discount_amount": 100,
    "discount_currency": "USD",
    "discount_treatment_code": null,
    "duty_tax_amount": 200,
    "duty_tax_currency": "USD",
    "order_date": "2023-07-20",
    "shipping_amount": 300,
    "shipping_currency": "USD",
    "shipping_destination_country_code": "US",
    "shipping_destination_postal_code": "10045",
    "shipping_source_postal_code": "10045",
    "shipping_tax_amount": 400,
    "shipping_tax_currency": "USD",
    "shipping_tax_rate": "0.2",
    "tax_treatments": null,
    "unique_value_added_tax_invoice_reference": "12302"
  },
  "line_items": [
    {
      "detail_indicator": "normal",
      "discount_amount": null,
      "discount_currency": null,
      "discount_treatment_code": null,
      "id": "card_purchase_supplement_invoice_line_item_nf9760lz0apqy5retmqh",
      "item_commodity_code": "001",
      "item_descriptor": "Coffee",
      "item_quantity": "1.0",
      "product_code": "101",
      "sales_tax_amount": null,
      "sales_tax_currency": null,
      "sales_tax_rate": null,
      "total_amount": 500,
      "total_amount_currency": "USD",
      "unit_cost": "5.0",
      "unit_cost_currency": "USD",
      "unit_of_measure_code": "NMB"
    }
  ],
  "transaction_id": "transaction_uyrp7fld2ium70oa7oi",
  "type": "card_purchase_supplement"
}
```
### Attributes
- `card_payment_id` (string, nullable)
  The ID of the Card Payment this transaction belongs to.

- `id` (string)
  The Card Purchase Supplement identifier.

- `invoice` (dictionary, nullable)
  Invoice-level information about the payment.

  - `invoice.discount_amount` (integer, nullable)
    Discount given to cardholder.

  - `invoice.discount_currency` (string, nullable)
    The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) code for the discount.

  - `invoice.discount_treatment_code` (enum, nullable)
    Indicates how the merchant applied the discount.
    Cases:
    * `no_invoice_level_discount_provided` (No invoice level discount provided)
    * `tax_calculated_on_post_discount_invoice_total` (Tax calculated on post discount invoice total)
    * `tax_calculated_on_pre_discount_invoice_total` (Tax calculated on pre discount invoice total)

  - `invoice.duty_tax_amount` (integer, nullable)
    Amount of duty taxes.

  - `invoice.duty_tax_currency` (string, nullable)
    The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) code for the duty tax.

  - `invoice.order_date` (string, nullable)
    Date the order was taken.

  - `invoice.shipping_amount` (integer, nullable)
    The shipping cost.

  - `invoice.shipping_currency` (string, nullable)
    The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) code for the shipping cost.

  - `invoice.shipping_destination_country_code` (string, nullable)
    Country code of the shipping destination.

  - `invoice.shipping_destination_postal_code` (string, nullable)
    Postal code of the shipping destination.

  - `invoice.shipping_source_postal_code` (string, nullable)
    Postal code of the location being shipped from.

  - `invoice.shipping_tax_amount` (integer, nullable)
    Taxes paid for freight and shipping.

  - `invoice.shipping_tax_currency` (string, nullable)
    The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) code for the shipping tax.

  - `invoice.shipping_tax_rate` (string, nullable)
    Tax rate for freight and shipping.

  - `invoice.tax_treatments` (enum, nullable)
    Indicates how the merchant applied taxes.
    Cases:
    * `no_tax_applies` (No tax applies)
    * `net_price_line_item_level` (Net price line item level)
    * `net_price_invoice_level` (Net price invoice level)
    * `gross_price_line_item_level` (Gross price line item level)
    * `gross_price_invoice_level` (Gross price invoice level)

  - `invoice.unique_value_added_tax_invoice_reference` (string, nullable)
    Value added tax invoice reference number.

- `line_items` (array of objects, nullable)
  Line item information, such as individual products purchased.

  - `line_items.detail_indicator` (enum, nullable)
    Indicates the type of line item.
    Cases:
    * `normal` (Normal)
    * `credit` (Credit)
    * `payment` (Purchase)

  - `line_items.discount_amount` (integer, nullable)
    Discount amount for this specific line item.

  - `line_items.discount_currency` (string, nullable)
    The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) code for the discount.

  - `line_items.discount_treatment_code` (enum, nullable)
    Indicates how the merchant applied the discount for this specific line item.
    Cases:
    * `no_line_item_level_discount_provided` (No line item level discount provided)
    * `tax_calculated_on_post_discount_line_item_total` (Tax calculated on post discount line item total)
    * `tax_calculated_on_pre_discount_line_item_total` (Tax calculated on pre discount line item total)

  - `line_items.id` (string)
    The Card Purchase Supplement Line Item identifier.

  - `line_items.item_commodity_code` (string, nullable)
    Code used to categorize the purchase item.

  - `line_items.item_descriptor` (string, nullable)
    Description of the purchase item.

  - `line_items.item_quantity` (string, nullable)
    The number of units of the product being purchased.

  - `line_items.product_code` (string, nullable)
    Code used to categorize the product being purchased.

  - `line_items.sales_tax_amount` (integer, nullable)
    Sales tax amount for this line item.

  - `line_items.sales_tax_currency` (string, nullable)
    The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) code for the sales tax assessed.

  - `line_items.sales_tax_rate` (string, nullable)
    Sales tax rate for this line item.

  - `line_items.total_amount` (integer, nullable)
    Total amount of all line items.

  - `line_items.total_amount_currency` (string, nullable)
    The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) code for the total amount.

  - `line_items.unit_cost` (string, nullable)
    Cost of line item per unit of measure, in major units.

  - `line_items.unit_cost_currency` (string, nullable)
    The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) code for the unit cost.

  - `line_items.unit_of_measure_code` (string, nullable)
    Code indicating unit of measure (gallons, etc.).

- `transaction_id` (string)
  The ID of the transaction.

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

## List Card Purchase Supplements
GET /card_purchase_supplements

### Example
```curl
curl \
  --url "${INCREASE_URL}/card_purchase_supplements?card_payment_id=card_payment_nd3k2kacrqjli8482ave" \
  -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_payment_id` (string, optional)
  Filter Card Purchase Supplements to ones belonging to the specified Card Payment.

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

### Returns a Card Purchase Supplement List object:
```json
{
  "data": [
    {
      "card_payment_id": "card_payment_nd3k2kacrqjli8482ave",
      "id": "card_purchase_supplement_ijuc45iym4jchnh2sfk3",
      "invoice": {
        "discount_amount": 100,
        "discount_currency": "USD",
        "discount_treatment_code": null,
        "duty_tax_amount": 200,
        "duty_tax_currency": "USD",
        "order_date": "2023-07-20",
        "shipping_amount": 300,
        "shipping_currency": "USD",
        "shipping_destination_country_code": "US",
        "shipping_destination_postal_code": "10045",
        "shipping_source_postal_code": "10045",
        "shipping_tax_amount": 400,
        "shipping_tax_currency": "USD",
        "shipping_tax_rate": "0.2",
        "tax_treatments": null,
        "unique_value_added_tax_invoice_reference": "12302"
      },
      "line_items": [
        {
          "detail_indicator": "normal",
          "discount_amount": null,
          "discount_currency": null,
          "discount_treatment_code": null,
          "id": "card_purchase_supplement_invoice_line_item_nf9760lz0apqy5retmqh",
          "item_commodity_code": "001",
          "item_descriptor": "Coffee",
          "item_quantity": "1.0",
          "product_code": "101",
          "sales_tax_amount": null,
          "sales_tax_currency": null,
          "sales_tax_rate": null,
          "total_amount": 500,
          "total_amount_currency": "USD",
          "unit_cost": "5.0",
          "unit_cost_currency": "USD",
          "unit_of_measure_code": "NMB"
        }
      ],
      "transaction_id": "transaction_uyrp7fld2ium70oa7oi",
      "type": "card_purchase_supplement"
    }
  ],
  "next_cursor": "v57w5d"
}
```

## Retrieve a Card Purchase Supplement
GET /card_purchase_supplements/{card_purchase_supplement_id}

### Example
```curl
curl \
  --url "${INCREASE_URL}/card_purchase_supplements/card_purchase_supplement_ijuc45iym4jchnh2sfk3" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}"
```
### Path Parameters
- `card_purchase_supplement_id` (string, required)
  The identifier of the Card Purchase Supplement.

## Sandbox: Create a Card Purchase Supplement
POST /simulations/card_purchase_supplements
> Simulates the creation of a Card Purchase Supplement (Level 3 data) for a card settlement. This happens asynchronously in production when Visa sends enhanced transaction data about a purchase.
### Example
```curl
curl -X "POST" \
  --url "${INCREASE_URL}/simulations/card_purchase_supplements" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d $'{
    "invoice": {
      "discount_amount": 100,
      "duty_tax_amount": 200,
      "order_date": "2023-07-20",
      "shipping_amount": 300,
      "shipping_destination_country_code": "US",
      "shipping_destination_postal_code": "10045",
      "shipping_source_postal_code": "10045",
      "shipping_tax_amount": 400,
      "shipping_tax_rate": "0.2",
      "unique_value_added_tax_invoice_reference": "12302"
    },
    "line_items": [
      {
        "item_commodity_code": "001",
        "item_descriptor": "Coffee",
        "item_quantity": "1",
        "product_code": "101",
        "total_amount": 500,
        "unit_cost": "5",
        "unit_of_measure_code": "NMB"
      }
    ],
    "transaction_id": "transaction_uyrp7fld2ium70oa7oi"
  }'
```

### Body Parameters
- `invoice` (dictionary, optional)
  Invoice-level information about the payment.

  - `invoice.discount_amount` (integer, optional)
    Discount given to cardholder.

  - `invoice.duty_tax_amount` (integer, optional)
    Amount of duty taxes.

  - `invoice.order_date` (string, optional)
    Date the order was taken.

  - `invoice.shipping_amount` (integer, optional)
    The shipping cost.

  - `invoice.shipping_destination_country_code` (string, optional)
    Country code of the shipping destination.

  - `invoice.shipping_destination_postal_code` (string, optional)
    Postal code of the shipping destination.

  - `invoice.shipping_source_postal_code` (string, optional)
    Postal code of the location being shipped from.

  - `invoice.shipping_tax_amount` (integer, optional)
    Taxes paid for freight and shipping.

  - `invoice.shipping_tax_rate` (string, optional)
    Tax rate for freight and shipping.

  - `invoice.unique_value_added_tax_invoice_reference` (string, optional)
    Value added tax invoice reference number.

- `line_items` (array of objects, optional)
  Line item information, such as individual products purchased.

  - `line_items.discount_amount` (integer, optional)
    Discount amount for this specific line item.

  - `line_items.item_commodity_code` (string, optional)
    Code used to categorize the purchase item.

  - `line_items.item_descriptor` (string, optional)
    Description of the purchase item.

  - `line_items.item_quantity` (string, optional)
    The number of units of the product being purchased.

  - `line_items.product_code` (string, optional)
    Code used to categorize the product being purchased.

  - `line_items.sales_tax_amount` (integer, optional)
    Sales tax amount for this line item.

  - `line_items.sales_tax_rate` (string, optional)
    Sales tax rate for this line item.

  - `line_items.total_amount` (integer, optional)
    Total amount of all line items.

  - `line_items.unit_cost` (string, optional)
    Cost of line item per unit of measure, in major units.

  - `line_items.unit_of_measure_code` (string, optional)
    Code indicating unit of measure (gallons, etc.).

- `transaction_id` (string, required)
  The identifier of the Transaction to create a Card Purchase Supplement for. The Transaction must have a source of type `card_settlement`.