Kit Developer Documentation

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

api_secret

string

required

Your API secret key

page

integer

The page of results being requested. Default value is 1. Each page of results will contain up to 50 purchases.

curl https://api.convertkit.com/v3/purchases?api_secret=<your_secret_api_key>

{
    "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)"
                }
            ]
        }
    ]
}

{
    "error":"Authorization Failed",
    "message":"You do not have sufficient permissions to access this resource"
}

Retrieve a specific purchase

Show specific purchase by ID.

Endpoint

GET /v3/purchases/#{purchase_id}

Parameters

api_secret

string

required

Your API secret key

purchase_id

integer

required

The ID of the purchase you want to retrieve

curl https://api.convertkit.com/v3/purchases/<purchase_id>?api_secret=<your_secret_api_key>

{
    "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)"
        }
    ]
}

{
    "error":"Authorization Failed",
    "message":"You do not have sufficient permissions to access this resource"
}

Create a purchase

Create a new purchase record for tracking customer transactions.

Endpoint

POST /v3/purchases

Parameters

api_secret

string

required

Your API secret key

purchase

object

required

Purchase object

Show purchase properties

purchase.transaction_id

string

required

A unique ID for the purchase

purchase.email_address

string

required

The subscriber email address that the purchase belongs to

purchase.currency

string

required

3 letter currency code (e.g. USD)

purchase.first_name

string

first name of the subscriber

purchase.subtotal

decimal

The subtotal of the purchase

purchase.tax

decimal

Tax applied to purchase

purchase.shipping

decimal

Shipping amount applied to purchase

purchase.discount

decimal

Discount amount applied to purchase

purchase.total

decimal

Total cost of the purchase

purchase.transaction_time

string

Date and time of purchase as ISO string. Default is current timestamp.

purchase.status

string

Purchase status. Currently supports paid.

purchase.products

array

required

Array of purchased products.

Show products properties

purchase.products.unit_price

decimal

required

Product price

purchase.products.quantity

integer

required

Product quantity

purchase.products.name

string

required

Product name

purchase.products.pid

string

required

Your identifier for a product. Variants of the same product should have the same pid

purchase.products.lid

string

required

Unique line item identifier for this purchase

purchase.products.sku

string

Product SKU

Required for Third Party Integrations

We no longer support new integrations with V3 of the API. Instead learn more about building apps with the Kit App Store here

purchase.integration

string

required

The name of your integration (e.g. eBay)

integration_key

string

required

A token for tracking integrations

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
                }]
           }
     }'

{
    "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)"
        }
    ]
}

{
    "error": "Your request is missing parameters",
    "message": "transaction_id can't be blank, Sku can't be blank for product: Floppy Disk (512k)"
}

Getting Started

Endpoints

Purchases

List purchases

Endpoint

Parameters

Retrieve a specific purchase

Endpoint

Parameters

Create a purchase

Endpoint

Parameters

Required for Third Party Integrations

​List purchases

​Endpoint

​Parameters

​Retrieve a specific purchase

​Endpoint

​Parameters

​Create a purchase

​Endpoint

​Parameters

​Required for Third Party Integrations

List purchases

Endpoint

Parameters

Retrieve a specific purchase

Endpoint

Parameters

Create a purchase

Endpoint

Parameters

Required for Third Party Integrations