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.
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. |
[
{
"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.
{
"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.
[
{"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.
- 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.
{"error": "Rate limit exceeded — too many requests, please slow down."}
Last verified: