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

# Purchases

> Purchases v3 endpoints

Purchases allow you to track customer transactions and connect them to your subscribers for better segmentation and targeting.

## List purchases

Returns a list of all purchases for your account.

### Endpoint

`GET /v3/purchases`

### Parameters

<ParamField path="api_secret" type="string" required={true}>
  Your API secret key
</ParamField>

<ParamField path="page" type="integer">
  The page of results being requested. Default value is `1`. Each page of results will contain up to 50 purchases.
</ParamField>

<CodeGroup>
  ```shell Request theme={null}
  curl https://api.convertkit.com/v3/purchases?api_secret=<your_secret_api_key>
  ```

  ```json Response theme={null}
  {
      "total_purchases": 2,
      "page": 1,
      "total_pages": 1,
      "purchases": [
          {
              "id": 3,
              "transaction_id": "123-abcd-456-efgh",
              "status": "paid",
              "email_address": "x@example.com",
              "currency": "JPY",
              "transaction_time": "2018-03-17T11:28:04Z",
              "subtotal": 20.0,
              "shipping": 2.0,
              "discount": 3.0,
              "tax": 2.0,
              "total": 21.0,
              "products": [
                  {
                    "unit_price": 5.0,
                    "quantity": 2,
                    "sku": "7890-ijkl",
                    "name": "Floppy Disk (512k)"
                  },
                  {
                    "unit_price": 10.0,
                    "quantity": 1,
                    "sku":"mnop-1234",
                    "name":"Telephone Cord (data)"
                  }
              ]
          },
          {
              "id": 4,
              "transaction_id": "123-abcd-457-efgh",
              "status": "paid",
              "email_address": "x@example.com",
              "currency": "USD",
              "transaction_time": "2018-03-17T11:28:04Z",
              "subtotal": 20.0,
              "shipping": 2.0,
              "discount": 3.0,
              "tax": 2.0,
              "total": 21.0,
              "products": [
                  {
                      "unit_price": 5.0,
                      "quantity": 2,
                      "sku": "7890-ijkl",
                      "name": "Floppy Disk (512k)"
                  },
                  {
                      "unit_price": 10.0,
                      "quantity": 1,
                      "sku": "mnop-1234",
                      "name": "Telephone Cord (data)"
                  }
              ]
          }
      ]
  }
  ```

  ```json Error Response theme={null}
  {
      "error":"Authorization Failed",
      "message":"You do not have sufficient permissions to access this resource"
  }
  ```
</CodeGroup>

## Retrieve a specific purchase

Show specific purchase by ID.

### Endpoint

`GET /v3/purchases/#{purchase_id}`

### Parameters

<ParamField path="api_secret" type="string" required={true}>
  Your API secret key
</ParamField>

<ParamField path="purchase_id" type="integer" required={true}>
  The ID of the purchase you want to retrieve
</ParamField>

<CodeGroup>
  ```shell Request theme={null}
  curl https://api.convertkit.com/v3/purchases/<purchase_id>?api_secret=<your_secret_api_key>
  ```

  ```json Response theme={null}
  {
      "id": 8,
      "transaction_id": "123-abcd-456-efgh",
      "status": "paid",
      "email_address": "crashoverride@hackers.com",
      "currency": "JPY",
      "transaction_time": "2018-03-17T11:28:04Z",
      "subtotal": 20.0,
      "shipping": 2.0,
      "discount": 3.0,
      "tax": 2.0,
      "total": 21.0,
      "products": [
          {
              "unit_price": 5.0,
              "quantity": 2,
              "sku": "7890-ijkl",
              "name": "Floppy Disk (512k)"
          },
          {
              "unit_price": 10.0,
              "quantity": 1,
              "sku": "mnop-1234",
              "name": "Telephone Cord (data)"
          }
      ]
  }
  ```

  ```json Error Response theme={null}
  {
      "error":"Authorization Failed",
      "message":"You do not have sufficient permissions to access this resource"
  }
  ```
</CodeGroup>

## Create a purchase

Create a new purchase record for tracking customer transactions.

### Endpoint

`POST /v3/purchases`

### Parameters

<ParamField path="api_secret" type="string" required={true}>
  Your API secret key
</ParamField>

<ParamField path="purchase" type="object" required={true}>
  Purchase object
</ParamField>

<Expandable title="purchase properties">
  <ParamField path="purchase.transaction_id" type="string" required={true}>
    A unique ID for the purchase
  </ParamField>

  <ParamField path="purchase.email_address" type="string" required={true}>
    The subscriber email address that the purchase belongs to
  </ParamField>

  <ParamField path="purchase.currency" type="string" required={true}>
    3 letter currency code (e.g. `USD`)
  </ParamField>

  <ParamField path="purchase.first_name" type="string">
    first name of the subscriber
  </ParamField>

  <ParamField path="purchase.subtotal" type="decimal">
    The subtotal of the purchase
  </ParamField>

  <ParamField path="purchase.tax" type="decimal">
    Tax applied to purchase
  </ParamField>

  <ParamField path="purchase.shipping" type="decimal">
    Shipping amount applied to purchase
  </ParamField>

  <ParamField path="purchase.discount" type="decimal">
    Discount amount applied to purchase
  </ParamField>

  <ParamField path="purchase.total" type="decimal">
    Total cost of the purchase
  </ParamField>

  <ParamField path="purchase.transaction_time" type="string">
    Date and time of purchase as ISO string. Default is current timestamp.
  </ParamField>

  <ParamField path="purchase.status" type="string">
    Purchase status. Currently supports `paid`.
  </ParamField>

  <ParamField path="purchase.products" type="array" required={true}>
    Array of purchased products.
  </ParamField>

  <Expandable title="products properties">
    <ParamField path="purchase.products.unit_price" type="decimal" required={true}>
      Product price
    </ParamField>

    <ParamField path="purchase.products.quantity" type="integer" required={true}>
      Product quantity
    </ParamField>

    <ParamField path="purchase.products.name" type="string" required={true}>
      Product name
    </ParamField>

    <ParamField path="purchase.products.pid" type="string" required={true}>
      Your identifier for a product. Variants of the same product should have the same pid
    </ParamField>

    <ParamField path="purchase.products.lid" type="string" required={true}>
      Unique line item identifier for this purchase
    </ParamField>

    <ParamField path="purchase.products.sku" type="string">
      Product SKU
    </ParamField>
  </Expandable>
</Expandable>

### Required for Third Party Integrations

<Warning>We no longer support new integrations with V3 of the API. Instead learn more about [building apps with the Kit App Store here](/kit-app-store/overview)</Warning>

<ParamField path="purchase.integration" type="string" required={true}>
  The name of your integration (e.g. eBay)
</ParamField>

<ParamField path="integration_key" type="string" required={true}>
  A token for tracking integrations
</ParamField>

<CodeGroup>
  ```shell Request theme={null}
  curl -X POST https://api.convertkit.com/v3/purchases \
       -H 'Content-Type: application/json' \
       -d '{ "api_secret": "<your_secret_api_key>",
             "purchase": {
                  "transaction_id": "123-abcd-456-efgh",
                  "email_address": "john@example.com",
                  "first_name": "John",
                  "currency": "jpy",
                  "transaction_time": "2018-03-17 11:28:04",
                  "subtotal": 20.00,
                  "tax": 2.00,
                  "shipping": 2.00,
                  "discount": 3.00,
                  "total": 21.00,
                  "status": "paid",
                  "products": [{
                      "pid": 9999,
                      "lid": 7777,
                      "name": "Floppy Disk (512k)",
                      "sku": "7890-ijkl",
                      "unit_price": 5.00,
                      "quantity": 2
                  }, {
                      "pid": 5555,
                      "lid": 7778,
                      "name": "Telephone Cord (data)",
                      "sku": "mnop-1234",
                      "unit_price": 10.00,
                      "quantity": 1
                  }]
             }
       }'
  ```

  ```json Response theme={null}
  {
      "id": 8,
      "transaction_id": "123-abcd-456-efgh",
      "status": "paid",
      "email_address": "crashoverride@hackers.com",
      "currency": "JPY",
      "transaction_time": "2018-03-17T11:28:04Z",
      "subtotal": 20.0,
      "discount": 3.0,
      "tax": 2.0,
      "shipping": 2.00,
      "total": 21.0,
      "products": [
          {
              "unit_price": 5.0,
              "quantity": 2,
              "sku": "7890-ijkl",
              "name": "Floppy Disk (512k)"
          },
          {
              "unit_price": 10.0,
              "quantity": 1,
              "sku": "mnop-1234",
              "name": "Telephone Cord (data)"
          }
      ]
  }
  ```

  ```json Error Response theme={null}
  {
      "error": "Your request is missing parameters",
      "message": "transaction_id can't be blank, Sku can't be blank for product: Floppy Disk (512k)"
  }
  ```
</CodeGroup>