Article

SMM Panel API: Handling Refills, Cancels & Partial Orders the Right Way

VOIKER.COM ← Back to Blog
// API Engineering
SMM Panel API: Handling Refills, Cancels & Partial Orders the Right Way
voiker.com·Updated 2026·6 min read
ORDER LIFECYCLE▲
Handle refills, cancels, and partial deliveries without silent failures.

Why Refills, Cancels, and Partial Orders Matter

When you build an app or panel on top of an SMM API, the happy path is easy: place an order, it completes, everyone is satisfied. The hard part is handling everything that goes wrong in between. Orders get partially delivered, customers request refills, and some orders need to be cancelled before they start.

Handling these edge cases correctly is what separates a reliable integration from one that quietly loses money. If you misread a response shape, you might tell a customer their order was refunded when it was not, or fail to detect a partial delivery and undercount your costs.

This guide walks through the three situations you will definitely encounter — refills, cancels, and partial orders — and how to handle them through the SMM panel API v2 contract.

The Status Values You Need to Know

Before automating anything, you must understand the exact status strings an order can return. The API uses specific, case-sensitive values, and getting them wrong is a common source of bugs.

The core status values are Pending, Processing, In progress, Completed, Partial, and Canceled. Notice that "In progress" contains a space, and "Canceled" is spelled with a single L. Some panels also return Refunded or Error in certain situations.

Do not hardcode a guessed spelling. Always map the values you actually receive, and treat unknown values as an error case rather than assuming they mean something specific.

Polling Order Status

The status action accepts either a single order id or a comma-separated list of up to 100 ids. When you query a single order, you get a flat object with fields like charge, start_count, status, remains, and currency.

When you query multiple orders, the response becomes an object keyed by order id. A bad id returns an error object for that key rather than failing the whole request.

One critical detail: the API usually returns errors with an HTTP 200 status. Always parse the response body to detect failure instead of trusting the HTTP code. This single habit prevents a whole class of silent failures.

Handling Partial Orders

A partial order is one where only some of the requested quantity was delivered. The status field reports Partial, and the remains field tells you how much is still outstanding.

When you see a Partial status, your first move should be to check whether the service supports refills. If it does, you can request a refill to recover the undelivered portion. If it does not, the undelivered remainder is typically handled according to the panel's refund rules.

Partial orders are also where start_count matters. Comparing start_count against the current count helps you understand whether the order is progressing, stalled, or rolling backwards — which can happen with some delivery methods.

Requesting a Refill

Refills exist because social signals can drop after delivery. A service that advertises refill support lets you re-request the missing quantity, usually within a defined window.

The refill action takes an order or orders parameter and returns a simple confirmation — a refill value of "1" indicates the request was accepted, or an array of results when you submit multiple orders.

Remember that a refill is a request, not a guarantee. The refill result confirms the request was accepted, but you should continue polling the order status to confirm the missing quantity actually returned.

Cancelling an Order

Cancellation is the trickiest action because its response shape is easy to misread. The cancel action uses the plural orders parameter and returns an array of per-order results.

Each element contains the order id and a cancel field. A successful cancel shows cancel with a value of 1, while a failure shows cancel containing an error object. This asymmetry — success is a number, failure is an object — trips up many integrations.

There is also an important constraint: cancellation is only possible while the order has not started and the service advertises cancel support. Once delivery has begun, a cancel request will typically fail.

The Refund Flow After Cancellation

When a cancellation succeeds, the remaining balance is typically refunded to the customer's account automatically. The confirmation comes through the status endpoint, where the order eventually reports a Canceled status.

Do not treat the cancel response itself as proof of refund. The cancel call only submits the request. You must continue polling status until the order reaches Canceled before you tell the customer their refund is complete.

This two-step flow — submit, then poll — is the same pattern used for refills and partials, and it is the most reliable way to keep your integration honest.

Common Integration Mistakes

Trusting HTTP Status Codes

As mentioned, errors often arrive with HTTP 200. Parse the body and check for an error object every time, on every action.

Hardcoding Response Shapes

The cancel response is an array, while status returns a flat object or a keyed object depending on how many ids you send. Write your parser to handle both shapes, not one assumed format.

Polling Too Aggressively

Status polling is necessary but should be throttled. Polling every few seconds for every order wastes quota and can trip rate limits. Use a sensible interval and back off when an order is clearly still processing.

Ignoring Unknown Status Values

New panels and service types can introduce status strings you have not seen. Log unknown values and fail safely rather than guessing their meaning.

Designing a Robust Automation Flow

A clean flow looks like this: place the order, poll status at a reasonable interval, and branch on the result. If the order is Partial and refillable, request a refill. If the customer cancels before start, submit a cancel and poll until Canceled. If the order completes, record the final count and close it out.

Wrap every branch in error handling that logs the raw response, so you can debug discrepancies later. The goal is an integration that degrades gracefully and never lies to the customer about the state of their order.

Conclusion

Refills, cancels, and partial orders are not edge cases you can ignore — they are a normal part of running on any SMM panel API. Understanding the exact status values and response shapes is the difference between an integration that works reliably and one that loses money through silent errors.

Take the time to map the contract carefully, poll responsibly, and always parse the body. With those habits in place, your automation will handle the messy parts of order management as smoothly as the happy path.

Frequently Asked Questions

What does a Partial order status mean?

It means only some of the requested quantity was delivered. The remains field shows how much is still outstanding, and you can request a refill if the service supports it.

How do I know if a cancel request succeeded?

The cancel response returns an array where a successful entry has a cancel value of 1, while a failure contains an error object. Poll status until the order reaches Canceled to confirm the refund.

Do API errors always come with a non-200 HTTP status?

No. The API often returns errors with HTTP 200, so always parse the response body and check for an error object instead of trusting the HTTP code.

Is a refill guaranteed to restore the missing quantity?

No. A refill is a request that gets accepted or rejected. Keep polling the order status to confirm the missing quantity actually returned.

Build on a Reliable API

Integrate Voiker's SMM panel API into your app or panel with confidence.

Order Now →

© 2026 Voiker.com — All rights reserved.