logo logo
userLogin
Home Order Information

API Documentation

Integrate an automated purchasing system into your application. Fully support features: create orders, check status, view product lists, and much more.

API Version 1.0 - RESTful
Begin
Overview Authentication
Endpoints
Create an order POST Order status GET Order list GET Product GET Category GET Balance GET Account information GET
Reference
Error code

API Overview

Basic information about Shop API

Base URL https://caoshop.net/api/v1
API Key API Key Management
Content-Type application/json
Response JSON
API Key Management Access API Keys page To create, manage, and view your API usage history.

API authentication

How to authenticate requests to the API

All requests to the API must include the following headers:

Header Describe
X-API-Key Your API Key (40 characters, starting with sk_live_)
X-API-Secret Your API Secret (74 characters, starting with sk_secret_)
Content-Type application/json (cho POST request)
Example Headers
HTTP Headers 
X-API-Key: sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
X-API-Secret: sk_secret_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2
Content-Type: application/json
Security notice Keep your API Key and API Secret secure. Do not share or commit them to your source code. Use environment variables to store them.

Create an order

Create a new order and process the payment automatically.

POST https://caoshop.net/api/v1/orders/create
Request Body
Parameter Type Describe
items Obligatory array List of products to buy
items[].plan_id Obligatory integer Product package ID (taken from /products/list)
items[].quantity integer Quantity to purchase (default: 1)
items[].fields object Additional fields (if required by the plan)
coupon_code string Discount code (if any)
Sample code
PHP 
<?php
$apiKey = 'sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6';
$apiSecret = 'sk_secret_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2';

$data = [
    'items' => [
        ['plan_id' => 18, 'quantity' => 1, 'fields' => ['email_dang_nhap' => '[email protected]']]
    ],
    'coupon_code' => ''
];

$ch = curl_init('https://caoshop.net/api/v1/orders/create');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($data),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'X-API-Key: ' . $apiKey,
        'X-API-Secret: ' . $apiSecret
    ]
]);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);

print_r($response);
?>
Sample Response
Success Response 
{
  "success": true,
  "message": "Đơn hàng đã được tạo thành công",
  "data": {
    "orders": [{
      "trans_id": "ORD1703750400ABC",
      "product_name": "Sản phẩm Premium",
      "status": "completed",
      "total": 100000
    }],
    "summary": {
      "total_amount": 100000,
      "new_balance": 400000
    }
  }
}

Order status

Check the delivery status and contents.

GET https://caoshop.net/api/v1/orders/status?trans_id={trans_id}
Query Parameters
Parameter Type Describe
trans_id Obligatory string Mã giao dịch từ kết quả tạo đơn
Sample code
PHP 
<?php
$transId = 'ORD1703750400ABC';
$url = 'https://caoshop.net/api/v1/orders/status?trans_id=' . $transId;

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6',
        'X-API-Secret: sk_secret_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2'
    ]
]);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);
print_r($response);
?>
Sample Response
Success Response 
{
  "success": true,
  "timestamp": 1770020629,
  "request_id": "req_69805f15a5ed77.94324321",
  "data": {
    "order": {
      "id": 36,
      "trans_id": "PO8153690",
      "user_id": 1,
      "product": {
        "id": 21,
        "name": "Sản phẩm Figma",
        "slug": "san-pham-figma",
        "image": "https://example.com/product.jpg"
      },
      "plan": {
        "id": 19,
        "name": "Figma Edu 1 năm - Tài khoản",
        "is_instant": true
      },
      "quantity": 2,
      "total_price": 1600000,
      "sale_price": 400000,
      "discount_amount": 0,
      "coupon_code": null,
      "final_amount": 400000,
      "fields_data": [],
      "status": "completed",
      "payment_status": "paid",
      "order_source": "api",
      "created_at": "2026-02-02 15:23:14",
      "updated_at": "2026-02-02 15:23:14"
    },
    "delivery": {
      "items": ["Account: [email protected] | Pass: abc123", "Account: [email protected] | Pass: xyz789"],
      "delivered_count": 2,
      "expected_count": 2
    },
    "execution_time": 0.0238
  }
}

Order list

Get order list with pagination

GET https://caoshop.net/api/v1/orders/list
Query Parameters
Parameter Type Describe
page integer Number of pages (default: 1)
limit integer Number of pages (default: 20, max: 100)
status string Lọc: pending, processing, completed, cancelled
Sample code
cURL 
curl "https://caoshop.net/api/v1/orders/list?page=1&limit=20&status=completed" \
  -H "X-API-Key: sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -H "X-API-Secret: sk_secret_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2"
Sample Response
Success Response 
{
  "success": true,
  "data": {
    "orders": [{
      "id": 1234,
      "trans_id": "ORD-1705678901-ABC123",
      "product": {
        "id": 10,
        "name": "Windows 11 Pro Key",
        "slug": "windows-11-pro-key"
      },
      "plan": {
        "id": 5,
        "name": "Gói Retail - Vĩnh viễn"
      },
      "quantity": 2,
      "total_price": 1500000,
      "final_amount": 1350000,
      "status": "completed",
      "payment_status": "paid",
      "created_at": "2026-01-19 10:30:00"
    }],
    "pagination": {
      "current_page": 1,
      "per_page": 20,
      "total": 45,
      "total_pages": 3,
      "has_more": true
    },
    "execution_time": 0.0234
  }
}

Product list

Get a list of products and packages.

GET https://caoshop.net/api/v1/products/list
Query Parameters
Parameter Type Describe
page integer Number of pages (default: 1)
limit integer Số lượng/trang (mặc định: 10, tối đa: 100)
category_id integer Filter by category
search string Search by name
sort string Sắp xếp: newest, oldest, price_asc, price_desc, bestseller
Phân trang The API returns a maximum of 100 products per page. Use the <code>page</code> parameter and check <code>pagination.has_more</code> in the response to retrieve all products.
Sample code
PHP - Lấy tất cả sản phẩm (phân trang) 
<?php
$apiKey = 'sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6';
$apiSecret = 'sk_secret_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2';
$baseUrl = 'https://caoshop.net/api/v1';

$allProducts = [];
$page = 1;
$limit = 100; // Tối đa 100 sản phẩm/trang

do {
    $url = $baseUrl . '/products/list?page=' . $page . '&limit=' . $limit;

    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
            'X-API-Key: ' . $apiKey,
            'X-API-Secret: ' . $apiSecret
        ]
    ]);

    $response = json_decode(curl_exec($ch), true);
    curl_close($ch);

    if (!$response['success']) break;

    $products = $response['data']['products'] ?? [];
    $allProducts = array_merge($allProducts, $products);

    $hasMore = $response['data']['pagination']['has_more'] ?? false;
    $page++;
} while ($hasMore);

echo 'Tổng sản phẩm: ' . count($allProducts);
?>
Response Fields (Plan)
Field Type Describe
id integer ID của gói sản phẩm
name string Product package name
price float Original price
sale_price float Promotional price (if any)
final_price float Final price (preferably sale_price if available)
is_instant boolean Automated delivery
duration_type string Term type: <code>lifetime</code> (permanent), <code>days</code> (days), <code>months</code> (months), <code>years</code> (years)
duration_value integer|null The duration value (e.g., 30 days, 1 month). Null if duration_type = lifetime.
stock_count integer Inventory quantity (if is_instant = true)
in_stock boolean Is it still in stock?
fields array List of fields to enter when placing an order
Sample Response
Success Response 
{
  "success": true,
  "timestamp": 1769604661,
  "request_id": "req_697a063503ed57.32834148",
  "data": {
    "products": [{
      "id": 29,
      "name": "Key Adobe Creative Cloud All Apps",
      "slug": "key-adobe-creative-cloud-all-apps",
      "image": "https://example.com/product.jpg",
      "description": "<p>Mô tả sản phẩm...</p>",
      "category": {
        "id": 5,
        "name": "Học Tập",
        "slug": "hoc-tap",
        "image": "https://example.com/category.jpg"
      },
      "categories": [
        {"id": 5, "name": "Học Tập", "slug": "hoc-tap", "image": "https://example.com/category.jpg"},
        {"id": 14, "name": "Làm việc", "slug": "lam-viec", "image": null}
      ],
      "min_price": 375000,
      "max_price": 1650000,
      "sold": 24,
      "rating": 4.5,
      "plans": [{
        "id": 319,
        "name": "Tài khoản 1 tháng",
        "price": 375000,
        "sale_price": 0,
        "final_price": 375000,
        "is_instant": true,
        "duration_type": "month",
        "duration_value": 1,
        "stock_count": 50,
        "in_stock": true,
        "description": "",
        "fields": []
      }, {
        "id": 320,
        "name": "Nâng chính chủ 1 Tháng",
        "price": 1650000,
        "sale_price": 0,
        "final_price": 1650000,
        "is_instant": false,
        "duration_type": "month",
        "duration_value": 3,
        "stock_count": 0,
        "in_stock": true,
        "description": "",
        "fields": [
          {"key": "email", "label": "Email", "type": "email", "required": true},
          {"key": "mat_khau", "label": "Mật khẩu", "type": "password", "required": true}
        ]
      }]
    }],
    "pagination": {
      "current_page": 1,
      "per_page": 10,
      "total": 21,
      "total_pages": 3,
      "has_more": true
    },
    "execution_time": 0.0828
  }
}

Category list

Get the product category list

GET https://caoshop.net/api/v1/categories/list
Query Parameters
Parameter Type Describe
parent_id integer Filter by parent category
include_children boolean Includes subcategory (0 or 1)
include_products boolean Includes the quantity of products (0 or 1)
Sample code
cURL 
curl "https://caoshop.net/api/v1/categories/list?include_children=1" \
  -H "X-API-Key: sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -H "X-API-Secret: sk_secret_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2"
Sample Response
Success Response 
{
  "success": true,
  "timestamp": 1770022554,
  "request_id": "req_6980669a4793d9.70486853",
  "data": {
    "categories": [{
      "id": 3,
      "name": "Giải Trí",
      "slug": "giai-tri",
      "description": "",
      "image": "https://example.com/category/DOQ4.png",
      "parent_id": 1,
      "sort_order": 9
    }, {
      "id": 5,
      "name": "Học Tập",
      "slug": "hoc-tap",
      "description": "",
      "image": "https://example.com/category/9IRK.png",
      "parent_id": 1,
      "sort_order": 4
    }, {
      "id": 1,
      "name": "Tiện Ích",
      "slug": "tien-ich",
      "description": "",
      "image": "https://example.com/category/EIT3.png",
      "parent_id": 0,
      "sort_order": 0
    }],
    "total": 15,
    "execution_time": 0.0341
  }
}

Check balance

Check the current account balance.

GET https://caoshop.net/api/v1/account/balance
Sample code
cURL 
curl "https://caoshop.net/api/v1/account/balance" \
  -H "X-API-Key: sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -H "X-API-Secret: sk_secret_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2"
Sample Response
Success Response 
{
  "success": true,
  "timestamp": 1770022345,
  "request_id": "req_698065c9694a56.14017855",
  "data": {
    "user": {
      "id": 1,
      "username": "admin",
      "email": "[email protected]"
    },
    "balance": {
      "current": 93537500,
      "total_deposited": 100000000,
      "currency": "VND",
      "formatted": "93.537.500đ"
    },
    "execution_time": 0.0258
  }
}

Account information

Retrieve user account information

GET https://caoshop.net/api/v1/account/info
Sample code
cURL 
curl "https://caoshop.net/api/v1/account/info" \
  -H "X-API-Key: sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -H "X-API-Secret: sk_secret_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2"
Sample Response
Success Response 
{
  "success": true,
  "timestamp": 1770022432,
  "request_id": "req_69806620805ae3.29218122",
  "data": {
    "user": {
      "id": 1,
      "username": "admin",
      "email": "[email protected]",
      "phone": "",
      "balance": 93537500,
      "total_deposited": 100000000,
      "created_at": null
    },
    "api_key": {
      "name": "API Key",
      "permissions": [
        "orders.create",
        "orders.list",
        "orders.status",
        "products.list",
        "account.balance",
        "account.info"
      ],
      "rate_limit": 60,
      "daily_limit": 10000,
      "expires_at": null,
      "created_at": "2026-02-02 14:53:35"
    },
    "orders_summary": {
      "total": 12,
      "pending": 3,
      "completed": 8
    },
    "api_usage_today": {
      "period": "day",
      "start_time": "2026-02-02 00:00:00",
      "total_requests": 5,
      "success_requests": 5,
      "failed_requests": 0,
      "success_rate": 100
    },
    "execution_time": 0.0449
  }
}

Error code

List of possible error codes

Error code HTTP Describe
INVALID_API_KEY 401 Invalid API Key
INVALID_API_SECRET 401 API Secret is incorrect
DISABLED_API_KEY 401 The API key has been disabled.
RATE_LIMIT_EXCEEDED 429 Exceeding request limits
IP_NOT_ALLOWED 403 IP address is not allowed to access.
PERMISSION_DENIED 403 No right to perform
INSUFFICIENT_BALANCE 400 Insufficient balance
PRODUCT_NOT_FOUND 404 The product does not exist.
OUT_OF_STOCK 400 The product is out of stock.
Error Response Format
Error Response 
{
  "success": false,
  "message": "Số dư không đủ để thanh toán",
  "data": {
    "error_code": "INSUFFICIENT_BALANCE"
  }
}