Create a purchase
curl --request POST \
--url https://api.kit.com/v4/purchases \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"purchase": {
"email_address": "pru.magoo@convertkit.dev",
"transaction_id": "796-92-4892",
"status": "paid",
"subtotal": 78.66,
"tax": 7.87,
"shipping": 0,
"discount": 5,
"total": 81.53,
"currency": "USD",
"transaction_time": "2023-02-17T11:43:55Z",
"products": [
{
"name": "Phantom Hourglass",
"pid": "804-02-4430",
"lid": "811-75-7900",
"quantity": 1,
"unit_price": 23.22,
"sku": "SM21-SH-M02-RD-S-001"
},
{
"name": "Twilight Princess",
"pid": "833-51-1151",
"lid": "766-49-1241",
"quantity": 1,
"unit_price": 32.22,
"sku": "WT21-JK-M03-BK-L-012"
},
{
"name": "Four Swords",
"pid": "217-99-4325",
"lid": "563-95-8878",
"quantity": 1,
"unit_price": 23.22,
"sku": "FL21-TS-M01-BL-M-020"
}
]
}
}
'require 'uri'
require 'net/http'
url = URI("https://api.kit.com/v4/purchases")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"purchase\": {\n \"email_address\": \"pru.magoo@convertkit.dev\",\n \"transaction_id\": \"796-92-4892\",\n \"status\": \"paid\",\n \"subtotal\": 78.66,\n \"tax\": 7.87,\n \"shipping\": 0,\n \"discount\": 5,\n \"total\": 81.53,\n \"currency\": \"USD\",\n \"transaction_time\": \"2023-02-17T11:43:55Z\",\n \"products\": [\n {\n \"name\": \"Phantom Hourglass\",\n \"pid\": \"804-02-4430\",\n \"lid\": \"811-75-7900\",\n \"quantity\": 1,\n \"unit_price\": 23.22,\n \"sku\": \"SM21-SH-M02-RD-S-001\"\n },\n {\n \"name\": \"Twilight Princess\",\n \"pid\": \"833-51-1151\",\n \"lid\": \"766-49-1241\",\n \"quantity\": 1,\n \"unit_price\": 32.22,\n \"sku\": \"WT21-JK-M03-BK-L-012\"\n },\n {\n \"name\": \"Four Swords\",\n \"pid\": \"217-99-4325\",\n \"lid\": \"563-95-8878\",\n \"quantity\": 1,\n \"unit_price\": 23.22,\n \"sku\": \"FL21-TS-M01-BL-M-020\"\n }\n ]\n }\n}"
response = http.request(request)
puts response.read_bodyconst options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
purchase: {
email_address: 'pru.magoo@convertkit.dev',
transaction_id: '796-92-4892',
status: 'paid',
subtotal: 78.66,
tax: 7.87,
shipping: 0,
discount: 5,
total: 81.53,
currency: 'USD',
transaction_time: '2023-02-17T11:43:55Z',
products: [
{
name: 'Phantom Hourglass',
pid: '804-02-4430',
lid: '811-75-7900',
quantity: 1,
unit_price: 23.22,
sku: 'SM21-SH-M02-RD-S-001'
},
{
name: 'Twilight Princess',
pid: '833-51-1151',
lid: '766-49-1241',
quantity: 1,
unit_price: 32.22,
sku: 'WT21-JK-M03-BK-L-012'
},
{
name: 'Four Swords',
pid: '217-99-4325',
lid: '563-95-8878',
quantity: 1,
unit_price: 23.22,
sku: 'FL21-TS-M01-BL-M-020'
}
]
}
})
};
fetch('https://api.kit.com/v4/purchases', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.kit.com/v4/purchases"
payload := strings.NewReader("{\n \"purchase\": {\n \"email_address\": \"pru.magoo@convertkit.dev\",\n \"transaction_id\": \"796-92-4892\",\n \"status\": \"paid\",\n \"subtotal\": 78.66,\n \"tax\": 7.87,\n \"shipping\": 0,\n \"discount\": 5,\n \"total\": 81.53,\n \"currency\": \"USD\",\n \"transaction_time\": \"2023-02-17T11:43:55Z\",\n \"products\": [\n {\n \"name\": \"Phantom Hourglass\",\n \"pid\": \"804-02-4430\",\n \"lid\": \"811-75-7900\",\n \"quantity\": 1,\n \"unit_price\": 23.22,\n \"sku\": \"SM21-SH-M02-RD-S-001\"\n },\n {\n \"name\": \"Twilight Princess\",\n \"pid\": \"833-51-1151\",\n \"lid\": \"766-49-1241\",\n \"quantity\": 1,\n \"unit_price\": 32.22,\n \"sku\": \"WT21-JK-M03-BK-L-012\"\n },\n {\n \"name\": \"Four Swords\",\n \"pid\": \"217-99-4325\",\n \"lid\": \"563-95-8878\",\n \"quantity\": 1,\n \"unit_price\": 23.22,\n \"sku\": \"FL21-TS-M01-BL-M-020\"\n }\n ]\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.kit.com/v4/purchases",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'purchase' => [
'email_address' => 'pru.magoo@convertkit.dev',
'transaction_id' => '796-92-4892',
'status' => 'paid',
'subtotal' => 78.66,
'tax' => 7.87,
'shipping' => 0,
'discount' => 5,
'total' => 81.53,
'currency' => 'USD',
'transaction_time' => '2023-02-17T11:43:55Z',
'products' => [
[
'name' => 'Phantom Hourglass',
'pid' => '804-02-4430',
'lid' => '811-75-7900',
'quantity' => 1,
'unit_price' => 23.22,
'sku' => 'SM21-SH-M02-RD-S-001'
],
[
'name' => 'Twilight Princess',
'pid' => '833-51-1151',
'lid' => '766-49-1241',
'quantity' => 1,
'unit_price' => 32.22,
'sku' => 'WT21-JK-M03-BK-L-012'
],
[
'name' => 'Four Swords',
'pid' => '217-99-4325',
'lid' => '563-95-8878',
'quantity' => 1,
'unit_price' => 23.22,
'sku' => 'FL21-TS-M01-BL-M-020'
]
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}import requests
url = "https://api.kit.com/v4/purchases"
payload = { "purchase": {
"email_address": "pru.magoo@convertkit.dev",
"transaction_id": "796-92-4892",
"status": "paid",
"subtotal": 78.66,
"tax": 7.87,
"shipping": 0,
"discount": 5,
"total": 81.53,
"currency": "USD",
"transaction_time": "2023-02-17T11:43:55Z",
"products": [
{
"name": "Phantom Hourglass",
"pid": "804-02-4430",
"lid": "811-75-7900",
"quantity": 1,
"unit_price": 23.22,
"sku": "SM21-SH-M02-RD-S-001"
},
{
"name": "Twilight Princess",
"pid": "833-51-1151",
"lid": "766-49-1241",
"quantity": 1,
"unit_price": 32.22,
"sku": "WT21-JK-M03-BK-L-012"
},
{
"name": "Four Swords",
"pid": "217-99-4325",
"lid": "563-95-8878",
"quantity": 1,
"unit_price": 23.22,
"sku": "FL21-TS-M01-BL-M-020"
}
]
} }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"purchase": {
"id": 22,
"transaction_id": "796-92-4892",
"subscriber_id": 42,
"status": "paid",
"email_address": "pru.magoo@convertkit.dev",
"currency": "USD",
"transaction_time": "2023-02-17T11:43:55Z",
"subtotal": 78.66,
"discount": 5,
"tax": 7.87,
"total": 81.53,
"products": [
{
"quantity": 1,
"lid": "811-75-7900",
"unit_price": 23.22,
"sku": "SM21-SH-M02-RD-S-001",
"name": "Phantom Hourglass",
"pid": "804-02-4430"
},
{
"quantity": 1,
"lid": "766-49-1241",
"unit_price": 32.22,
"sku": "WT21-JK-M03-BK-L-012",
"name": "Twilight Princess",
"pid": "833-51-1151"
},
{
"quantity": 1,
"lid": "563-95-8878",
"unit_price": 23.22,
"sku": "FL21-TS-M01-BL-M-020",
"name": "Four Swords",
"pid": "217-99-4325"
}
],
"source": "Fancy App 434"
}
}{
"errors": [
"The access token is invalid"
]
}{
"errors": [
"Transaction cannot be blank"
]
}Purchases
Create a purchase
Records a purchase against a subscriber, identified by email_address — use this to sync order data from your e-commerce platform into Kit so it appears on the subscriber’s profile and can drive purchase-based automations. If no subscriber with that email address exists, one is created (in the active state) as part of the request.
Provide the external transaction_id (required), monetary breakdown (subtotal, tax, shipping, discount, total), a 3-letter currency code (e.g. USD), transaction_time, and the purchased products — each product needs a pid (your platform’s product identifier); products that don’t exist yet are created automatically.
Note: purchases are matched on transaction_id, so submitting one that already exists updates the existing purchase instead of creating a duplicate. The products in your request are added to that purchase as additional line items — they don’t replace the ones already recorded — so resending the same products will duplicate the line items. Only include products you haven’t already synced for that transaction_id.
Returns 422 when required parameters are missing or invalid.
POST
/
v4
/
purchases
Create a purchase
curl --request POST \
--url https://api.kit.com/v4/purchases \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"purchase": {
"email_address": "pru.magoo@convertkit.dev",
"transaction_id": "796-92-4892",
"status": "paid",
"subtotal": 78.66,
"tax": 7.87,
"shipping": 0,
"discount": 5,
"total": 81.53,
"currency": "USD",
"transaction_time": "2023-02-17T11:43:55Z",
"products": [
{
"name": "Phantom Hourglass",
"pid": "804-02-4430",
"lid": "811-75-7900",
"quantity": 1,
"unit_price": 23.22,
"sku": "SM21-SH-M02-RD-S-001"
},
{
"name": "Twilight Princess",
"pid": "833-51-1151",
"lid": "766-49-1241",
"quantity": 1,
"unit_price": 32.22,
"sku": "WT21-JK-M03-BK-L-012"
},
{
"name": "Four Swords",
"pid": "217-99-4325",
"lid": "563-95-8878",
"quantity": 1,
"unit_price": 23.22,
"sku": "FL21-TS-M01-BL-M-020"
}
]
}
}
'require 'uri'
require 'net/http'
url = URI("https://api.kit.com/v4/purchases")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"purchase\": {\n \"email_address\": \"pru.magoo@convertkit.dev\",\n \"transaction_id\": \"796-92-4892\",\n \"status\": \"paid\",\n \"subtotal\": 78.66,\n \"tax\": 7.87,\n \"shipping\": 0,\n \"discount\": 5,\n \"total\": 81.53,\n \"currency\": \"USD\",\n \"transaction_time\": \"2023-02-17T11:43:55Z\",\n \"products\": [\n {\n \"name\": \"Phantom Hourglass\",\n \"pid\": \"804-02-4430\",\n \"lid\": \"811-75-7900\",\n \"quantity\": 1,\n \"unit_price\": 23.22,\n \"sku\": \"SM21-SH-M02-RD-S-001\"\n },\n {\n \"name\": \"Twilight Princess\",\n \"pid\": \"833-51-1151\",\n \"lid\": \"766-49-1241\",\n \"quantity\": 1,\n \"unit_price\": 32.22,\n \"sku\": \"WT21-JK-M03-BK-L-012\"\n },\n {\n \"name\": \"Four Swords\",\n \"pid\": \"217-99-4325\",\n \"lid\": \"563-95-8878\",\n \"quantity\": 1,\n \"unit_price\": 23.22,\n \"sku\": \"FL21-TS-M01-BL-M-020\"\n }\n ]\n }\n}"
response = http.request(request)
puts response.read_bodyconst options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
purchase: {
email_address: 'pru.magoo@convertkit.dev',
transaction_id: '796-92-4892',
status: 'paid',
subtotal: 78.66,
tax: 7.87,
shipping: 0,
discount: 5,
total: 81.53,
currency: 'USD',
transaction_time: '2023-02-17T11:43:55Z',
products: [
{
name: 'Phantom Hourglass',
pid: '804-02-4430',
lid: '811-75-7900',
quantity: 1,
unit_price: 23.22,
sku: 'SM21-SH-M02-RD-S-001'
},
{
name: 'Twilight Princess',
pid: '833-51-1151',
lid: '766-49-1241',
quantity: 1,
unit_price: 32.22,
sku: 'WT21-JK-M03-BK-L-012'
},
{
name: 'Four Swords',
pid: '217-99-4325',
lid: '563-95-8878',
quantity: 1,
unit_price: 23.22,
sku: 'FL21-TS-M01-BL-M-020'
}
]
}
})
};
fetch('https://api.kit.com/v4/purchases', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.kit.com/v4/purchases"
payload := strings.NewReader("{\n \"purchase\": {\n \"email_address\": \"pru.magoo@convertkit.dev\",\n \"transaction_id\": \"796-92-4892\",\n \"status\": \"paid\",\n \"subtotal\": 78.66,\n \"tax\": 7.87,\n \"shipping\": 0,\n \"discount\": 5,\n \"total\": 81.53,\n \"currency\": \"USD\",\n \"transaction_time\": \"2023-02-17T11:43:55Z\",\n \"products\": [\n {\n \"name\": \"Phantom Hourglass\",\n \"pid\": \"804-02-4430\",\n \"lid\": \"811-75-7900\",\n \"quantity\": 1,\n \"unit_price\": 23.22,\n \"sku\": \"SM21-SH-M02-RD-S-001\"\n },\n {\n \"name\": \"Twilight Princess\",\n \"pid\": \"833-51-1151\",\n \"lid\": \"766-49-1241\",\n \"quantity\": 1,\n \"unit_price\": 32.22,\n \"sku\": \"WT21-JK-M03-BK-L-012\"\n },\n {\n \"name\": \"Four Swords\",\n \"pid\": \"217-99-4325\",\n \"lid\": \"563-95-8878\",\n \"quantity\": 1,\n \"unit_price\": 23.22,\n \"sku\": \"FL21-TS-M01-BL-M-020\"\n }\n ]\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.kit.com/v4/purchases",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'purchase' => [
'email_address' => 'pru.magoo@convertkit.dev',
'transaction_id' => '796-92-4892',
'status' => 'paid',
'subtotal' => 78.66,
'tax' => 7.87,
'shipping' => 0,
'discount' => 5,
'total' => 81.53,
'currency' => 'USD',
'transaction_time' => '2023-02-17T11:43:55Z',
'products' => [
[
'name' => 'Phantom Hourglass',
'pid' => '804-02-4430',
'lid' => '811-75-7900',
'quantity' => 1,
'unit_price' => 23.22,
'sku' => 'SM21-SH-M02-RD-S-001'
],
[
'name' => 'Twilight Princess',
'pid' => '833-51-1151',
'lid' => '766-49-1241',
'quantity' => 1,
'unit_price' => 32.22,
'sku' => 'WT21-JK-M03-BK-L-012'
],
[
'name' => 'Four Swords',
'pid' => '217-99-4325',
'lid' => '563-95-8878',
'quantity' => 1,
'unit_price' => 23.22,
'sku' => 'FL21-TS-M01-BL-M-020'
]
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}import requests
url = "https://api.kit.com/v4/purchases"
payload = { "purchase": {
"email_address": "pru.magoo@convertkit.dev",
"transaction_id": "796-92-4892",
"status": "paid",
"subtotal": 78.66,
"tax": 7.87,
"shipping": 0,
"discount": 5,
"total": 81.53,
"currency": "USD",
"transaction_time": "2023-02-17T11:43:55Z",
"products": [
{
"name": "Phantom Hourglass",
"pid": "804-02-4430",
"lid": "811-75-7900",
"quantity": 1,
"unit_price": 23.22,
"sku": "SM21-SH-M02-RD-S-001"
},
{
"name": "Twilight Princess",
"pid": "833-51-1151",
"lid": "766-49-1241",
"quantity": 1,
"unit_price": 32.22,
"sku": "WT21-JK-M03-BK-L-012"
},
{
"name": "Four Swords",
"pid": "217-99-4325",
"lid": "563-95-8878",
"quantity": 1,
"unit_price": 23.22,
"sku": "FL21-TS-M01-BL-M-020"
}
]
} }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"purchase": {
"id": 22,
"transaction_id": "796-92-4892",
"subscriber_id": 42,
"status": "paid",
"email_address": "pru.magoo@convertkit.dev",
"currency": "USD",
"transaction_time": "2023-02-17T11:43:55Z",
"subtotal": 78.66,
"discount": 5,
"tax": 7.87,
"total": 81.53,
"products": [
{
"quantity": 1,
"lid": "811-75-7900",
"unit_price": 23.22,
"sku": "SM21-SH-M02-RD-S-001",
"name": "Phantom Hourglass",
"pid": "804-02-4430"
},
{
"quantity": 1,
"lid": "766-49-1241",
"unit_price": 32.22,
"sku": "WT21-JK-M03-BK-L-012",
"name": "Twilight Princess",
"pid": "833-51-1151"
},
{
"quantity": 1,
"lid": "563-95-8878",
"unit_price": 23.22,
"sku": "FL21-TS-M01-BL-M-020",
"name": "Four Swords",
"pid": "217-99-4325"
}
],
"source": "Fancy App 434"
}
}{
"errors": [
"The access token is invalid"
]
}{
"errors": [
"Transaction cannot be blank"
]
}Authorizations
Authenticate API requests via an OAuth token
FlowAuthorization Code
- Authorization URL
- https://api.kit.com/v4/oauth/authorize
- Token URL
- https://api.kit.com/v4/oauth/token
- Refresh URL
- https://api.kit.com/v4/oauth/token
Body
application/json
Show child attributes
Show child attributes
Response
Creates a purchase for the provided subscriber and returns its details. It also creates products if they don't exist.
Show child attributes
Show child attributes
Was this page helpful?