Endpoints
Transactions
Upload transaction records to the Cobi Data API.
Transactions
curl --request POST \
--url https://api.example.com/v1/data/transactions \
--header 'Content-Type: application/json' \
--data '
{
"records": [
{
"transaction_id": {},
"shop_id": {},
"region": "<string>",
"savings": {},
"amount": {},
"student_id": {},
"offer_id": {},
"branch_id": {},
"source": "<string>",
"created": {},
"updated": {},
"is_deleted": true,
"discount_name": "<string>",
"discount_type": "<string>",
"discount_value": {}
}
]
}
'import requests
url = "https://api.example.com/v1/data/transactions"
payload = { "records": [
{
"transaction_id": {},
"shop_id": {},
"region": "<string>",
"savings": {},
"amount": {},
"student_id": {},
"offer_id": {},
"branch_id": {},
"source": "<string>",
"created": {},
"updated": {},
"is_deleted": True,
"discount_name": "<string>",
"discount_type": "<string>",
"discount_value": {}
}
] }
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
records: [
{
transaction_id: {},
shop_id: {},
region: '<string>',
savings: {},
amount: {},
student_id: {},
offer_id: {},
branch_id: {},
source: '<string>',
created: {},
updated: {},
is_deleted: true,
discount_name: '<string>',
discount_type: '<string>',
discount_value: {}
}
]
})
};
fetch('https://api.example.com/v1/data/transactions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/v1/data/transactions",
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([
'records' => [
[
'transaction_id' => [
],
'shop_id' => [
],
'region' => '<string>',
'savings' => [
],
'amount' => [
],
'student_id' => [
],
'offer_id' => [
],
'branch_id' => [
],
'source' => '<string>',
'created' => [
],
'updated' => [
],
'is_deleted' => true,
'discount_name' => '<string>',
'discount_type' => '<string>',
'discount_value' => [
]
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/v1/data/transactions"
payload := strings.NewReader("{\n \"records\": [\n {\n \"transaction_id\": {},\n \"shop_id\": {},\n \"region\": \"<string>\",\n \"savings\": {},\n \"amount\": {},\n \"student_id\": {},\n \"offer_id\": {},\n \"branch_id\": {},\n \"source\": \"<string>\",\n \"created\": {},\n \"updated\": {},\n \"is_deleted\": true,\n \"discount_name\": \"<string>\",\n \"discount_type\": \"<string>\",\n \"discount_value\": {}\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
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))
}HttpResponse<String> response = Unirest.post("https://api.example.com/v1/data/transactions")
.header("Content-Type", "application/json")
.body("{\n \"records\": [\n {\n \"transaction_id\": {},\n \"shop_id\": {},\n \"region\": \"<string>\",\n \"savings\": {},\n \"amount\": {},\n \"student_id\": {},\n \"offer_id\": {},\n \"branch_id\": {},\n \"source\": \"<string>\",\n \"created\": {},\n \"updated\": {},\n \"is_deleted\": true,\n \"discount_name\": \"<string>\",\n \"discount_type\": \"<string>\",\n \"discount_value\": {}\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/v1/data/transactions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"records\": [\n {\n \"transaction_id\": {},\n \"shop_id\": {},\n \"region\": \"<string>\",\n \"savings\": {},\n \"amount\": {},\n \"student_id\": {},\n \"offer_id\": {},\n \"branch_id\": {},\n \"source\": \"<string>\",\n \"created\": {},\n \"updated\": {},\n \"is_deleted\": true,\n \"discount_name\": \"<string>\",\n \"discount_type\": \"<string>\",\n \"discount_value\": {}\n }\n ]\n}"
response = http.request(request)
puts response.read_bodyImportant: Transaction records have a dependency on shops. The system
validates the
shop_id field against existing records in the database. You
should upload shops before uploading transactions to ensure proper data
validation.Authentication Required
This endpoint requires API key authentication via Bearer token in the Authorization header.Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
About the Data API
This endpoint is part of the Cobi Data API (/v1/data/:type), which provides a consistent interface for uploading different types of structured data.
Request Body
array
required
An array of transaction records (up to 5000)
Show Transaction Record
Show Transaction Record
string (UUID)
required
Unique identifier for the transaction
string (UUID)
required
ID of the shop where the transaction occurred (must reference an existing
shop)
string
required
Geographic region (2-letter country code, e.g., “CA” for Canada)
number (float)
required
Amount saved in the transaction (must be a non-negative number)
number (float)
required
Total transaction amount (must be a positive number)
string (UUID)
ID of the student making the purchase
string (UUID)
ID of the offer used
string (UUID)
ID of the branch location
string
Source of the transaction (e.g., “online”, “in-store”)
string (date-time)
Timestamp when the record was created
string (date-time)
Timestamp when the record was last updated
boolean
Flag indicating if the record is marked as deleted
string
Name of the discount applied
string
Type of discount (e.g., “percentage”, “fixed”)
number (float)
Value of the discount
Response
The API returns a JSON response with the following fields:{
"request_id": "string", // Unique ID for the overall request
"type": "transactions", // Type of data being processed
"batches": [
{
"batch": 1, // Sequential batch number
"status": 200, // HTTP-like status code (200, 207, 400, 500)
"data": {
"status": "success", // "success", "partial", or "error"
"type": "transactions", // Matches the top-level type
"message": "Records uploaded successfully", // Summary message
"request_id": "string",
"batch_id": "string",
"error": "" // Optional — empty or null on success; contains error details otherwise
}
}
]
}
| Field | Type | Description |
|---|---|---|
request_id | string | Unique ID for the overall request |
type | string | Type of data being processed (e.g., “transactions”) |
batches | array | Array of batch results |
batches[].batch | int | Sequential batch number |
batches[].status | int | HTTP-like status code (200, 207, 400, 500) |
batches[].data | object | Batch result details |
batches[].data.status | string | ”success”, “partial”, or “error” |
batches[].data.type | string | Matches the top-level type |
batches[].data.message | string | Summary message of the batch result |
batches[].data.request_id | string | Unique request ID for the batch |
batches[].data.batch_id | string | Unique batch ID |
batches[].data.error | string | Error details (empty or null on success) |
Error Codes
| Status Code | Description | data.status value |
|---|---|---|
| 200 | All records processed successfully | success |
| 207 | Some records failed, others succeeded | partial |
| 400 | Validation or dependency error | error |
| 500 | Internal or unexpected server error | error |
| 401 | Unauthorized - Invalid or missing API key | error |
Example
curl -X POST https://api.hellocobi.com/v1/data/transactions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"records": [
{
"transaction_id": "550e8400-e29b-41d4-a716-446655440000",
"shop_id": "550e8400-e29b-41d4-a716-446655440002",
"region": "CA",
"savings": 10.50,
"amount": 100.00,
"source": "online",
"student_id": "550e8400-e29b-41d4-a716-446655440001",
"created": "2023-01-15T14:30:00Z",
"updated": "2023-06-22T09:15:30Z",
"discount_name": "Student Discount",
"discount_type": "percentage",
"discount_value": 10
}
]
}'
Best Practices
- Upload Order: Upload shops before transactions to ensure references exist
- Batch Size: Upload up to 5000 records at a time for optimal performance
- Data Validation: Ensure all required fields are present and properly formatted
- Error Handling: Implement proper error handling for failed requests
- Rate Limiting: Be mindful of API rate limits
Was this page helpful?
⌘I