Skip to content

Every parameter, field and error message

A lookup table. New to the API? Start with the developer overview, or open the code samples. Only five actions exist; any other value, refill included, gets Invalid action.

Last updated

POSThttps://smmvia.com/api/v2

Ground rules for every call

Item Detail
Address smmvia.com/api/v2 (call it with the https scheme)
HTTP method POST is recommended; GET also works. Any other method is answered with HTTP 405.
Input Form fields or a JSON body with the same names. Replies are JSON.
Always send key (from Account & API) and action (lower case).
Error shape {"error": "..."} with HTTP 200. Other codes: 429 (rate limit), 405 (method), 404 (path).
Number formats Amounts are strings: rate has 4 decimals, balance and charge 4 to 8. IDs and counts are integers.

action=balance

No extra fields. The reply says how much you can spend.

Field Type What it holds
balance string Money available on your account.
currency string Unit for all amounts in the API; USD today.

action=services

No extra fields. One entry per orderable service. Rates are personal: custom rates and discounts apply, so accounts can differ.

Field Type What it holds
service integer The number you pass to add.
name string Catalogue name, may include extra tags. Match on service, not on name.
type string Type label. Currently Default for every service.
category string Name of the catalogue group.
rate string Your price per 1,000 units.
min, max integer Allowed quantity range for one order.
dripfeed, refill boolean Compatibility flags. refill is false on every current service; dripfeed is true on a few, but the add action takes no drip-feed fields.
cancel boolean true if orders of this service may be canceled.
JSONSample reply (one made-up entry)
[
  {
    "service": 205,
    "name": "Sample name from the catalogue",
    "type": "Default",
    "category": "Sample category",
    "rate": "0.1000",
    "min": 10,
    "max": 3000,
    "dripfeed": false,
    "refill": false,
    "cancel": true
  }
]

action=add

Creates one order and debits its price from your balance at once. Success reply: {"order": 80412} (made-up number).

Parameter Type Rule
service integer Required. A service number from the services list.
link string Required. Channel, group or post link; 2048 characters at most.
quantity integer Required. A whole number between the min and max of that service.

action=status

Pass order with one ID, or orders with up to 100 IDs separated by commas. When both are present, orders is used. IDs beyond the first 100 are dropped.

Field Type What it holds
charge string Price minus refunds: 0.0000 when fully refunded, the delivered share when Partial.
start_count integer Counter value recorded before delivery, passed on as is; may be 0.
status string One of the statuses in the table further down.
remains integer Units not delivered; 0 when Completed.
currency string Unit of charge.

With order: one object, or {"error":"Incorrect order ID"} for an unknown or foreign ID. With orders: an object keyed by order ID; unknown or foreign IDs are skipped, and an empty list comes back if none match.

JSONSample reply for orders=80412,80413 (made-up values)
{
  "80412": {"charge": "0.0500", "start_count": 2140, "status": "In progress", "remains": 180, "currency": "USD"},
  "80413": {"charge": "0.0000", "start_count": 0, "status": "Canceled", "remains": 500, "currency": "USD"}
}

action=cancel

Pass orders with up to 100 comma-separated IDs (or a single order). The reply has one row per ID, in your sequence. "cancel": 1 means stopped, undelivered part already on your balance; the order ends Canceled (nothing arrived) or Partial. A single order gets {"order": ID, "cancel": 1} or an error object.

JSONSample reply for orders=80412,80413,99999 (made-up values)
[
  {"order": 80412, "cancel": 1},
  {"order": 80413, "cancel": {"error": "Cancel is not available for this order"}},
  {"order": 99999, "cancel": {"error": "Incorrect order ID"}}
]
  • Only Pending, Processing or In progress orders of a service with cancel true.
  • The cancel must be confirmed; if that is not possible right now, nothing changes and you retry.
  • An already Canceled order returns 1 again, so a retry after a timeout is harmless.
  • If the order turns out to have finished already, it becomes Completed with no refund and an error row.
  • A request works for at most 20 seconds; rows not reached ask you to retry them.
Worked exampleCancel arithmetic (made-up numbers)
Quantity ordered
500
Price paid
0.0500
Undelivered (recorded)
180
Back to balance
0.0500 x 180 / 500 = 0.0180
Order afterwards
Partial, charge 0.0320, remains 180

The refunded share follows the undelivered count the system records, exactly as for orders placed on the website. Full rules: refund policy.

Status values

Status Final? Meaning for your script
Pending no Paid, not yet in processing. If never started, it is canceled and refunded after about 15 minutes.
Processing no In processing; no units counted yet.
In progress no Units are arriving; remains is going down.
Completed yes Full quantity delivered, remains 0.
Partial yes Some units delivered; the rest is refunded to the balance.
Canceled yes once charge is 0.0000 Nothing delivered, money returned. An order awaiting a retry to start processing also shows Canceled, with its full charge.
Refunded yes Whole price returned without a cancel request, e.g. by an automatic safety check.

Error texts

The error field carries one of these strings, word for word. Validation reports only the first problem it finds.

Error string Cause and what to do
Invalid API key Missing, wrong or replaced key, or a suspended account.
Invalid action action is empty, misspelled or not one of the five.
The service field is required. add without service; link and quantity get the same sentence.
The selected service is invalid. The service number does not exist.
This service is currently unavailable. The service is switched off. Reload the services list.
The quantity field must be an integer. Not a whole number. Below 1: "must be at least 1".
Quantity must be between N and M. quantity is outside the min and max of the service.
The link field must not be greater than 2048 characters. Shorten the link.
Your balance is not enough. Please top up your account. The order costs more than your balance. Nothing was charged.
Incorrect order ID status or cancel: the ID is missing, unknown or not yours.
Too many orders: send at most 100 IDs per request Split the cancel list into batches of 100.
Cancel is not available for this order No cancel on this service, or the order is final. Do not retry.
The order is still being sent for processing, please retry in a few seconds Hand-over in progress. Retry shortly.
The order cannot be canceled right now, please retry shortly The cancel could not be confirmed yet. Retry.
Request took too long, please retry this order The 20-second budget ran out before this ID. Resend it.
Server error An unexpected fault on our side. For add, check your Orders page before you resend.

Rate limit details

One key may make 300 calls per minute, any action, failed calls included. Normal replies carry X-RateLimit-Limit and X-RateLimit-Remaining headers. Past the limit: HTTP 429 with the body below and no Retry-After header; pause until the next minute. The rejected call has no effect.

HTTP 429 body
{"error": "Rate limit exceeded — too many requests, please slow down."}

Last verified: