Base URL: https://api.shopaikey.com/seller
Introduction
The Seller API is exclusively for ShopAIKey Sellers (Resellers). Through this API, sellers can automate credit management, create and distribute API keys to their end customers.
With the Seller API, you can:
- Check your seller account credit balance.
- Create new API keys (single or bulk) for customers and deduct the corresponding credit.
- Top up, deduct, or delete keys to refund credit back to your seller account.
- Manage key status and names.
- Top up credit to your seller account via bank transfer.
- View usage statistics and transaction history.
- Integrate into your sales system, Telegram bot, or own website for 24/7 automated operation.
Note: This API is not for end users. Only accounts granted Seller permission can use the endpoints below.
Authentication
All requests require the seller's secret key in the header:
Authorization: Bearer sk-xxx
or:
x-secret-key: sk-xxx
Security warning: The seller's secret key grants direct access to credit balance operations. Never share it, never commit it to git, and never embed it directly in client code.
Quick Start Guide
1. Check seller account info
curl -X GET https://api.shopaikey.com/seller \
-H "Authorization: Bearer sk-your-seller-secret-key"
2. Create a new API key for a customer
curl -X POST https://api.shopaikey.com/seller/keys \
-H "Authorization: Bearer sk-your-seller-secret-key" \
-H "Content-Type: application/json" \
-d '{"amount": 10, "type": "cheap", "name": "Key for Customer A"}'
3. List issued keys
curl -X GET https://api.shopaikey.com/seller/keys \
-H "Authorization: Bearer sk-your-seller-secret-key"
Endpoints
1. Get Seller Info
Endpoint: GET /seller
Description: Returns seller account information, including email and current credit balance.
Response:
{
"id": 1,
"email": "[email protected]",
"credit": 100.5
}
2. List Keys Issued by Seller
Endpoint: GET /seller/keys
Query params:
Response:
{
"keys": [
{
"id": 1,
"key": "sk-abc123...",
"name": "Key for Customer A",
"type": "cheap",
"balance": 50,
"status": "active",
"created_at": "2024-01-01T00:00:00.000Z",
"refundable": true,
"used": 10,
"remain": 40
}
]
}
3. Create New Key
Endpoint: POST /seller/keys
Body:
Response:
{
"key": "sk-generated-key...",
"balance": 10,
"id": 1
}
4. Bulk Create Keys
Endpoint: POST /seller/keys/bulk-create
Body:
Response: Array of created keys.
5. Top Up Key Credit
Endpoint: POST /seller/keys/:key_id/topup
Body:
Response:
{
"balance": 30
}
6. Deduct Credit from Key (Revoke)
Endpoint: POST /seller/keys/:key_id/deduct
Body:
Response:
{
"keyBalance": 40,
"userCredit": 110
}
7. Update Key Status
Endpoint: PUT /seller/keys/:key_id/status
Body:
Response:
{
"success": true,
"status": "inactive"
}
8. Rename Key
Endpoint: PUT /seller/keys/:key_id/name
Body:
Response:
{
"success": true
}
9. Delete Key and Refund Credit
Endpoint: DELETE /seller/keys/:key_id
Response:
{
"refunded": 25.5
}
Note: Deleted keys cannot be recovered. Customers currently using the key will lose access immediately.
10. Bulk Delete Keys
Endpoint: DELETE /seller/keys/bulk
Body:
Response:
{
"deleted": 3,
"refunded": 75.0,
"failures": []
}
11. Create Seller Top-up Order
Endpoint: POST /seller/topup
Description: Create a credit top-up order for the seller account via bank transfer. Minimum amount 500,000 VND, in multiples of 1,000 VND.
Body:
Response:
{
"order_id": 123,
"transfer_content": "NP123",
"amount": 208,
"price_vnd": 1000000,
"qrUrl": "https://...",
"bank_info": { ... }
}
12. Get Top-up Order Info
Endpoint: GET /seller/topup/:order_id
Response: Similar to POST /seller/topup response, with an additional status field.
13. Top-up History
Endpoint: GET /seller/topup-history
Query params:
14. Cancel Order
Endpoint: PUT /seller/orders/:id
Body:
15. Bulk Cancel Orders
Endpoint: PUT /seller/orders/bulk
Body:
16. Usage Statistics
Endpoint: GET /seller/stats
Query params:
Response:
{
"totalSpent": 5000000,
"totalOrders": 10,
"totalRequests": 12500,
"totalTokenUsed": 3200000,
"spending": [
{ "date": "2026-04-28", "total": 500000, "count": 1 }
],
"topModels": [
{ "modelName": "claude-3-5-sonnet", "requests": 5000, "tokenUsed": 1200000 }
]
}
17. Transaction History
Endpoint: GET /seller/transactions
Query params:
Error Responses
{
"error": "Insufficient credit"
}
Example Seller Workflow
Scenario: a seller sells a 50-credit key to a customer, then the customer buys an additional 30 credits.
# 1. Check seller credit
curl -X GET https://api.shopaikey.com/seller \
-H "Authorization: Bearer sk-your-seller-secret-key"
# 2. Create a 50-credit key for the customer
curl -X POST https://api.shopaikey.com/seller/keys \
-H "Authorization: Bearer sk-your-seller-secret-key" \
-H "Content-Type: application/json" \
-d '{"amount": 50, "type": "cheap", "name": "Customer_NguyenVanA"}'
# 3. Customer buys 30 more credits
curl -X POST https://api.shopaikey.com/seller/keys/1/topup \
-H "Authorization: Bearer sk-your-seller-secret-key" \
-H "Content-Type: application/json" \
-d '{"amount": 30}'
# 4. Customer stops using; delete key and recover remaining credit
curl -X DELETE https://api.shopaikey.com/seller/keys/1 \
-H "Authorization: Bearer sk-your-seller-secret-key"
Security Notes for Sellers
- Do not share your secret key with customers or third parties.
- Do not commit your secret key to a git repository.
- Always use HTTPS when calling the API in production environments.
- Rotate your secret key periodically or immediately if you suspect a leak.
- Use meaningful key names (e.g.,
customer_abc_2025_01) for easy reconciliation with customers. - Log all transactions on your seller system's side for cross-referencing with ShopAIKey when needed.