BuyShazam Developer API
Automate orders with your BuyShazam wallet
Use the BuyShazam API to list services, place wallet-paid orders, and track status from your own app.
https://auto.buyshazam.com
The API Base URL is the server address your app sends API requests to. Add endpoint paths like /api/v1/services or /api/v1/orders after this URL.
Authentication
Every request must include your API key, a Unix timestamp, and an HMAC SHA256 signature.
signature = HMAC_SHA256(secret, method + "\n" + path + "\n" + timestamp + "\n" + body_sha256)
X-API-Key: your API key.X-Timestamp: current Unix timestamp. Requests are valid for 5 minutes.X-Signature: hex HMAC, optionally prefixed withsha256=.X-Idempotency-Key: required for order creation to prevent duplicate charges.
Generate a unique key for each new order and save it with the exact request body before sending. All examples below show a first submission. On retries, including after a timeout, reuse the saved key and body; refresh only the timestamp and signature. Never create a new key merely because the response was lost.
If payment is unconfirmed or the original order failed, was cancelled, or was refunded, contact support to reconcile the order and wallet before submitting a replacement. A retry must not trigger another wallet debit.
Endpoint overview
/api/v1/balance
Check wallet balance for the authenticated API account.
/api/v1/services
List available services, public service IDs, and public prices.
/api/v1/orders
Create a wallet-paid order.
/api/v1/orders/{id}
Check one API order.
/api/v1/orders
List recent API orders.
Endpoint details
GET /api/v1/balance
Returns the BuyShazam Wallet balance for the API account.
- Body
- None
- Response
balance,currency,woo_customer_id
GET /api/v1/services
Returns the services your account can order. Use the returned id as service_id when creating an order.
price_per_1000 is the public BuyShazam selling price per 1,000 units.
- Body
- None
- Response
services[].id,name,category,price_per_1000,price_per_unit,currency,min,max,type
POST /api/v1/orders
Creates a BuyShazam Wallet paid order. Include X-Idempotency-Key in the headers to prevent duplicate orders if your request is retried.
- Required
service_id,quantity,link- Optional
client_order_ref,custom_comments- Response
order.id,woo_order_number,status,charge
GET /api/v1/orders/{id}
Returns one API order by the API order ID, for example BSAPI-ABC123DEF456.
- Body
- None
- Response
order.status,smm_status,charge,currency
GET /api/v1/orders
Lists recent API orders. Supports page, limit, and status query parameters.
- Example
/api/v1/orders?page=1&limit=50- Response
orders[],page,limit,total
Create order payload
This payload is enough for standard services. For custom comment services, also send custom_comments. The service_id must come from GET /api/v1/services.
Estimated charge starts with price_per_1000 * quantity / 1000. The final amount is rounded at the store currency precision, never below provider cost plus the minimum profit guard, and never below the configured minimum line-item charge for a positive order. The confirmed charged amount is returned as order.charge.
{
"service_id": 123,
"quantity": 1000,
"link": "https://www.tiktok.com/@username/video/123",
"client_order_ref": "your-order-10001",
"custom_comments": "Great post!\nAmazing content!"
}
custom_comments is optional. Omit it for standard services.
Examples
PHP 7.4 example: create order
<?php
$baseUrl = 'https://auto.buyshazam.com';
$apiKey = 'bs_live_xxx';
$apiSecret = 'your_api_secret';
function uuidV4() {
$bytes = random_bytes(16);
$bytes[6] = chr((ord($bytes[6]) & 0x0f) | 0x40);
$bytes[8] = chr((ord($bytes[8]) & 0x3f) | 0x80);
$hex = bin2hex($bytes);
return substr($hex, 0, 8) . '-' . substr($hex, 8, 4) . '-' . substr($hex, 12, 4)
. '-' . substr($hex, 16, 4) . '-' . substr($hex, 20);
}
// Generate once for a NEW order. Persist this key and body before sending.
// For every retry, load the saved key/body instead of generating them again.
$idempotencyKey = 'order-' . uuidV4();
$method = 'POST';
$path = '/api/v1/orders';
$body = json_encode([
'service_id' => 123,
'quantity' => 1000,
'link' => 'https://www.tiktok.com/@username/video/123'
]);
$timestamp = time();
$bodyHash = hash('sha256', $body);
$message = implode("\n", [$method, $path, $timestamp, $bodyHash]);
$signature = hash_hmac('sha256', $message, $apiSecret);
$ch = curl_init($baseUrl . $path);
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
'X-API-Key: ' . $apiKey,
'X-Timestamp: ' . $timestamp,
'X-Signature: sha256=' . $signature,
'X-Idempotency-Key: ' . $idempotencyKey,
],
CURLOPT_POSTFIELDS => $body,
]);
echo curl_exec($ch);
Python example: create order
import hashlib
import hmac
import json
import time
import uuid
import requests
BASE_URL = "https://auto.buyshazam.com"
API_KEY = "bs_live_xxx"
API_SECRET = "your_api_secret"
method = "POST"
path = "/api/v1/orders"
body = json.dumps({
"service_id": 123,
"quantity": 1000,
"link": "https://www.tiktok.com/@username/video/123",
"client_order_ref": "your-order-10001",
}, separators=(",", ":"))
timestamp = str(int(time.time()))
body_hash = hashlib.sha256(body.encode("utf-8")).hexdigest()
message = "\n".join([method, path, timestamp, body_hash])
signature = hmac.new(
API_SECRET.encode("utf-8"),
message.encode("utf-8"),
hashlib.sha256,
).hexdigest()
response = requests.post(
BASE_URL + path,
data=body,
headers={
"Content-Type": "application/json",
"X-API-Key": API_KEY,
"X-Timestamp": timestamp,
"X-Signature": "sha256=" + signature,
"X-Idempotency-Key": "order-" + str(uuid.uuid4()),
},
timeout=30,
)
print(response.status_code)
print(response.json())
Rust example: create order
// Cargo.toml dependencies:
// hmac = "0.12"
// reqwest = { version = "0.12", features = ["blocking"] }
// serde_json = "1"
// sha2 = "0.10"
use hmac::{Hmac, Mac};
use reqwest::blocking::Client;
use serde_json::json;
use sha2::{Digest, Sha256};
use std::time::{SystemTime, UNIX_EPOCH};
type HmacSha256 = Hmac<Sha256>;
fn hex(bytes: &[u8]) -> String {
bytes.iter().map(|b| format!("{:02x}", b)).collect()
}
fn main() -> Result<(), Box<dyn std::error::Error>> {
let base_url = "https://auto.buyshazam.com";
let api_key = "bs_live_xxx";
let api_secret = "your_api_secret";
let method = "POST";
let path = "/api/v1/orders";
let body = json!({
"service_id": 123,
"quantity": 1000,
"link": "https://www.tiktok.com/@username/video/123",
"client_order_ref": "your-order-10001"
}).to_string();
let timestamp = SystemTime::now()
.duration_since(UNIX_EPOCH)?
.as_secs()
.to_string();
let body_hash = hex(&Sha256::digest(body.as_bytes()));
let message = format!("{}\n{}\n{}\n{}", method, path, timestamp, body_hash);
let mut mac = HmacSha256::new_from_slice(api_secret.as_bytes())?;
mac.update(message.as_bytes());
let signature = hex(&mac.finalize().into_bytes());
let response = Client::new()
.post(format!("{}{}", base_url, path))
.header("Content-Type", "application/json")
.header("X-API-Key", api_key)
.header("X-Timestamp", timestamp)
.header("X-Signature", format!("sha256={}", signature))
.header("X-Idempotency-Key", format!("order-{}", SystemTime::now().duration_since(UNIX_EPOCH)?.as_nanos()))
.body(body)
.send()?;
println!("{}", response.status());
println!("{}", response.text()?);
Ok(())
}
C# example: create order
using System;
using System.Net.Http;
using System.Security.Cryptography;
using System.Text;
using System.Threading.Tasks;
class Program
{
static async Task Main()
{
var baseUrl = "https://auto.buyshazam.com";
var apiKey = "bs_live_xxx";
var apiSecret = "your_api_secret";
var method = "POST";
var path = "/api/v1/orders";
var body = "{\"service_id\":123,\"quantity\":1000,\"link\":\"https://www.tiktok.com/@username/video/123\",\"client_order_ref\":\"your-order-10001\"}";
var timestamp = DateTimeOffset.UtcNow.ToUnixTimeSeconds().ToString();
var bodyHash = Sha256Hex(body);
var message = string.Join("\n", method, path, timestamp, bodyHash);
var signature = HmacSha256Hex(apiSecret, message);
using (var client = new HttpClient())
using (var request = new HttpRequestMessage(HttpMethod.Post, baseUrl + path))
{
request.Content = new StringContent(body, Encoding.UTF8, "application/json");
request.Headers.Add("X-API-Key", apiKey);
request.Headers.Add("X-Timestamp", timestamp);
request.Headers.Add("X-Signature", "sha256=" + signature);
request.Headers.Add("X-Idempotency-Key", "order-" + Guid.NewGuid().ToString("N"));
var response = await client.SendAsync(request);
Console.WriteLine((int)response.StatusCode);
Console.WriteLine(await response.Content.ReadAsStringAsync());
}
}
static string Sha256Hex(string value)
{
using (var sha256 = SHA256.Create())
{
return ToHex(sha256.ComputeHash(Encoding.UTF8.GetBytes(value)));
}
}
static string HmacSha256Hex(string secret, string value)
{
using (var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret)))
{
return ToHex(hmac.ComputeHash(Encoding.UTF8.GetBytes(value)));
}
}
static string ToHex(byte[] bytes)
{
return BitConverter.ToString(bytes).Replace("-", "").ToLowerInvariant();
}
}
Java example: create order
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.time.Instant;
import java.util.UUID;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
public class BuyShazamCreateOrder {
public static void main(String[] args) throws Exception {
String baseUrl = "https://auto.buyshazam.com";
String apiKey = "bs_live_xxx";
String apiSecret = "your_api_secret";
String method = "POST";
String path = "/api/v1/orders";
String body = "{\"service_id\":123,\"quantity\":1000,\"link\":\"https://www.tiktok.com/@username/video/123\",\"client_order_ref\":\"your-order-10001\"}";
String timestamp = String.valueOf(Instant.now().getEpochSecond());
String bodyHash = sha256Hex(body);
String message = String.join("\n", method, path, timestamp, bodyHash);
String signature = hmacSha256Hex(apiSecret, message);
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(baseUrl + path))
.header("Content-Type", "application/json")
.header("X-API-Key", apiKey)
.header("X-Timestamp", timestamp)
.header("X-Signature", "sha256=" + signature)
.header("X-Idempotency-Key", "order-" + UUID.randomUUID())
.POST(HttpRequest.BodyPublishers.ofString(body))
.build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.statusCode());
System.out.println(response.body());
}
static String sha256Hex(String value) throws Exception {
MessageDigest digest = MessageDigest.getInstance("SHA-256");
return hex(digest.digest(value.getBytes(StandardCharsets.UTF_8)));
}
static String hmacSha256Hex(String secret, String value) throws Exception {
Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
return hex(mac.doFinal(value.getBytes(StandardCharsets.UTF_8)));
}
static String hex(byte[] bytes) {
StringBuilder out = new StringBuilder();
for (byte b : bytes) {
out.append(String.format("%02x", b));
}
return out.toString();
}
}
Ruby example: create order
require "digest"
require "json"
require "net/http"
require "openssl"
require "securerandom"
require "time"
base_url = "https://auto.buyshazam.com"
api_key = "bs_live_xxx"
api_secret = "your_api_secret"
method = "POST"
path = "/api/v1/orders"
body = {
service_id: 123,
quantity: 1000,
link: "https://www.tiktok.com/@username/video/123",
client_order_ref: "your-order-10001"
}.to_json
timestamp = Time.now.to_i.to_s
body_hash = Digest::SHA256.hexdigest(body)
message = [method, path, timestamp, body_hash].join("\n")
signature = OpenSSL::HMAC.hexdigest("SHA256", api_secret, message)
uri = URI(base_url + path)
request = Net::HTTP::Post.new(uri)
request["Content-Type"] = "application/json"
request["X-API-Key"] = api_key
request["X-Timestamp"] = timestamp
request["X-Signature"] = "sha256=#{signature}"
request["X-Idempotency-Key"] = "order-#{SecureRandom.uuid}"
request.body = body
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
http.request(request)
end
puts response.code
puts response.body
Go example: create order
package main
import (
"bytes"
"crypto/hmac"
"crypto/sha256"
"encoding/hex"
"fmt"
"io"
"net/http"
"strings"
"time"
)
func main() {
baseURL := "https://auto.buyshazam.com"
apiKey := "bs_live_xxx"
apiSecret := "your_api_secret"
method := "POST"
path := "/api/v1/orders"
body := `{"service_id":123,"quantity":1000,"link":"https://www.tiktok.com/@username/video/123","client_order_ref":"your-order-10001"}`
timestamp := fmt.Sprintf("%d", time.Now().Unix())
bodyHash := sha256Hex(body)
message := strings.Join([]string{method, path, timestamp, bodyHash}, "\n")
signature := hmacSha256Hex(apiSecret, message)
req, err := http.NewRequest(method, baseURL+path, bytes.NewBufferString(body))
if err != nil {
panic(err)
}
req.Header.Set("Content-Type", "application/json")
req.Header.Set("X-API-Key", apiKey)
req.Header.Set("X-Timestamp", timestamp)
req.Header.Set("X-Signature", "sha256="+signature)
req.Header.Set("X-Idempotency-Key", fmt.Sprintf("order-%d", time.Now().UnixNano()))
resp, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
data, _ := io.ReadAll(resp.Body)
fmt.Println(resp.StatusCode)
fmt.Println(string(data))
}
func sha256Hex(value string) string {
sum := sha256.Sum256([]byte(value))
return hex.EncodeToString(sum[:])
}
func hmacSha256Hex(secret, value string) string {
mac := hmac.New(sha256.New, []byte(secret))
mac.Write([]byte(value))
return hex.EncodeToString(mac.Sum(nil))
}
Swift example: create order
import CryptoKit
import Foundation
let baseUrl = "https://auto.buyshazam.com"
let apiKey = "bs_live_xxx"
let apiSecret = "your_api_secret"
let method = "POST"
let path = "/api/v1/orders"
let body = #"{"service_id":123,"quantity":1000,"link":"https://www.tiktok.com/@username/video/123","client_order_ref":"your-order-10001"}"#
func hex<S: Sequence>(_ bytes: S) -> String where S.Element == UInt8 {
bytes.map { String(format: "%02x", $0) }.joined()
}
let timestamp = String(Int(Date().timeIntervalSince1970))
let bodyHash = hex(SHA256.hash(data: Data(body.utf8)))
let message = [method, path, timestamp, bodyHash].joined(separator: "\n")
let key = SymmetricKey(data: Data(apiSecret.utf8))
let signature = hex(HMAC<SHA256>.authenticationCode(for: Data(message.utf8), using: key))
var request = URLRequest(url: URL(string: baseUrl + path)!)
request.httpMethod = method
request.httpBody = Data(body.utf8)
request.setValue("application/json", forHTTPHeaderField: "Content-Type")
request.setValue(apiKey, forHTTPHeaderField: "X-API-Key")
request.setValue(timestamp, forHTTPHeaderField: "X-Timestamp")
request.setValue("sha256=\(signature)", forHTTPHeaderField: "X-Signature")
request.setValue("order-\(UUID().uuidString)", forHTTPHeaderField: "X-Idempotency-Key")
let task = URLSession.shared.dataTask(with: request) { data, response, error in
if let error = error {
print(error)
return
}
if let http = response as? HTTPURLResponse {
print(http.statusCode)
}
if let data = data, let text = String(data: data, encoding: .utf8) {
print(text)
}
}
task.resume()
RunLoop.main.run()
C++ example: create order
#include <curl/curl.h>
#include <openssl/hmac.h>
#include <openssl/sha.h>
#include <openssl/rand.h>
#include <ctime>
#include <iomanip>
#include <iostream>
#include <sstream>
#include <string>
#include <stdexcept>
std::string hex(const unsigned char* data, size_t len) {
std::ostringstream out;
for (size_t i = 0; i < len; ++i) {
out << std::hex << std::setw(2) << std::setfill('0') << static_cast<int>(data[i]);
}
return out.str();
}
std::string sha256Hex(const std::string& value) {
unsigned char hash[SHA256_DIGEST_LENGTH];
SHA256(reinterpret_cast<const unsigned char*>(value.c_str()), value.size(), hash);
return hex(hash, SHA256_DIGEST_LENGTH);
}
std::string uuidV4() {
unsigned char bytes[16];
if (RAND_bytes(bytes, sizeof(bytes)) != 1) {
throw std::runtime_error("Unable to generate an idempotency key");
}
bytes[6] = (bytes[6] & 0x0f) | 0x40;
bytes[8] = (bytes[8] & 0x3f) | 0x80;
std::string value = hex(bytes, sizeof(bytes));
return value.substr(0, 8) + "-" + value.substr(8, 4) + "-" + value.substr(12, 4)
+ "-" + value.substr(16, 4) + "-" + value.substr(20);
}
std::string hmacSha256Hex(const std::string& secret, const std::string& value) {
unsigned int len = SHA256_DIGEST_LENGTH;
unsigned char hash[SHA256_DIGEST_LENGTH];
HMAC(EVP_sha256(), secret.c_str(), static_cast<int>(secret.size()),
reinterpret_cast<const unsigned char*>(value.c_str()), value.size(), hash, &len);
return hex(hash, len);
}
int main() {
std::string baseUrl = "https://auto.buyshazam.com";
std::string apiKey = "bs_live_xxx";
std::string apiSecret = "your_api_secret";
std::string method = "POST";
std::string path = "/api/v1/orders";
std::string body = R"({"service_id":123,"quantity":1000,"link":"https://www.tiktok.com/@username/video/123","client_order_ref":"your-order-10001"})";
// Generate once for a NEW order. Persist this key and body before sending.
// For every retry, load the saved key/body instead of generating them again.
std::string idempotencyKey = "order-" + uuidV4();
std::string timestamp = std::to_string(std::time(nullptr));
std::string bodyHash = sha256Hex(body);
std::string message = method + "\n" + path + "\n" + timestamp + "\n" + bodyHash;
std::string signature = hmacSha256Hex(apiSecret, message);
CURL* curl = curl_easy_init();
if (!curl) {
return 1;
}
struct curl_slist* headers = nullptr;
headers = curl_slist_append(headers, "Content-Type: application/json");
headers = curl_slist_append(headers, ("X-API-Key: " + apiKey).c_str());
headers = curl_slist_append(headers, ("X-Timestamp: " + timestamp).c_str());
headers = curl_slist_append(headers, ("X-Signature: sha256=" + signature).c_str());
headers = curl_slist_append(headers, ("X-Idempotency-Key: " + idempotencyKey).c_str());
curl_easy_setopt(curl, CURLOPT_URL, (baseUrl + path).c_str());
curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
curl_easy_setopt(curl, CURLOPT_POSTFIELDS, body.c_str());
CURLcode result = curl_easy_perform(curl);
std::cout << "\nResult: " << result << std::endl;
curl_slist_free_all(headers);
curl_easy_cleanup(curl);
return 0;
}
cURL example: check wallet balance
curl -X GET "https://auto.buyshazam.com/api/v1/balance" \
-H "X-API-Key: bs_live_xxx" \
-H "X-Timestamp: 1710000000" \
-H "X-Signature: sha256=<hmac_sha256>"
cURL example: list services
curl -X GET "https://auto.buyshazam.com/api/v1/services" \
-H "X-API-Key: bs_live_xxx" \
-H "X-Timestamp: 1710000000" \
-H "X-Signature: sha256=<hmac_sha256>"
cURL example: check order status
curl -X GET "https://auto.buyshazam.com/api/v1/orders/BSAPI-ABC123DEF456" \
-H "X-API-Key: bs_live_xxx" \
-H "X-Timestamp: 1710000000" \
-H "X-Signature: sha256=<hmac_sha256>"
Error codes
API errors return success: false and an error code. Some validation errors also include useful fields such as min, max, balance, required, or details.
| Error | HTTP | Meaning |
|---|---|---|
missing_auth_headers | 401 | X-API-Key, X-Timestamp, or X-Signature is missing. |
invalid_api_key | 401 | The API key is invalid, disabled, revoked, or not active. |
invalid_timestamp | 401 | X-Timestamp is not a valid Unix timestamp. |
timestamp_out_of_range | 401 | The timestamp is older or newer than the allowed 5-minute window. |
invalid_signature | 401 | The HMAC signature is invalid for the method, path, timestamp, and body hash. |
ip_not_allowed | 403 | The request IP is not in the API key's allowed IP list. |
rate_limited | 429 | The API key exceeded its per-minute failed-request limit. Successful responses do not consume this limit. |
missing_idempotency_key | 400 | Order creation requires X-Idempotency-Key. |
invalid_service_or_quantity | 400 | service_id or quantity is missing or invalid. |
missing_link | 400 | The order link is required. |
service_not_found | 404 | The requested service ID does not exist or is not active. |
service_not_allowed | 403 | The API account is not allowed to order this service. |
quantity_below_minimum | 400 | The requested quantity is below the service minimum. Response includes min. |
quantity_above_maximum | 400 | The requested quantity is above the service maximum. Response includes max. |
duplicate_order | 409 | The idempotency key or client order reference conflicts with an existing order. |
idempotency_conflict | 409 | The key conflicts with the original order details or requires manual reconciliation. Do not retry with a new key to bypass this check. |
order_payment_unconfirmed | 409 | Payment is not confirmed. Wait and retry with the same key and body; contact support if this persists. |
order_not_active | 409 | The original order is failed, cancelled, or refunded. Contact support before placing a replacement order. |
order_not_found | 404 | The API order ID was not found for this API account. |
insufficient_wallet_balance | 402 | The BuyShazam Wallet does not have enough credit. Response includes balance, required, and currency. |
customer_wallet_locked | 409 | Another wallet-paid API order is being processed. Retry shortly with the same idempotency key. |
customer_not_found | 404 | The customer linked to the API key could not be found. |
product_not_found | 404 | The selected service is temporarily unavailable in the store. |
product_not_available | 404 | The matched store product is not published or available. |
invalid_price | 422 | The order price could not be calculated. |
terawallet_not_active | 503 | The wallet payment service is temporarily unavailable. |
wallet_debit_failed | 500 | The wallet debit failed while creating the order. |
wallet_debit_exception | 500 | The wallet debit process raised an unexpected error. |
wallet_debit_unavailable | 500 | No supported wallet debit method is available. |
order_create_failed | 500 | The order could not be created. |
service_pricing_unavailable | 502/503 | Public service pricing could not be loaded from the store. |
woo_not_configured | 503 | The BuyShazam API server cannot connect to the Woo store configuration. |
woo_not_active | 503 | Woo is temporarily unavailable on the store. |
internal_api_not_configured | 503 | The internal BuyShazam API connection is not configured. |
invalid_internal_signature | 401 | The internal BuyShazam API connection failed authentication. Contact support. |
internal_timestamp_out_of_range | 401 | The internal BuyShazam API server clocks are out of sync. Contact support. |
rest_forbidden | 403 | The internal store endpoint rejected the API request. Contact support. |
invalid_wallet_response | 502 | The wallet balance endpoint returned an invalid response. |
wallet_balance_failed | 502 | The wallet balance check failed. |
invalid_order_response | 502 | The order creation backend returned an invalid response. |
order_creation_failed | 502 | The order creation backend rejected the order without a more specific code. |
database_unavailable | 503 | The API database is temporarily unavailable. |
auth_error | 500 | An unexpected authentication error occurred. |