NotPanel API v3 is the current API address for reseller integrations. It keeps the familiar form-encoded key and action requests and adds a documented way to discover services, recover uncertain submissions and explain order refunds. The /api/v1, /api/v2 and /api/v3 addresses behave identically; /api/v3 is the documented one.
For an existing integration, the useful question is which customer problem to improve first. A lost order response needs a safe recovery path. An ordering form needs the correct inputs for the selected service. A refund screen needs to distinguish money already credited from a settlement still in progress. This guide connects those tasks to the API features that handle them.
What changes, and what stays familiar?
New integrations should send requests to https://notpanel.com/api/v3. A version number in the URL does not create a separate Wallet or a different service catalog. Existing calls for listing services, adding an order, checking status and reading the balance keep their familiar purpose.
| Your existing workflow | Useful addition |
|---|---|
| A basic service list | services now includes each service's order fields, tags, drip-feed limits, availability and average start time; catalog still works for search and pagination. |
| Submit an order and wait | Keep a request_id so the same purchase can be recovered after a lost response. |
| Show an order status | Read can_cancel, can_refill and the refund fields to explain the next step, or use order_details for the full order. |
| Check every order repeatedly | Use signed notifications alongside periodic status reconciliation. |
These improvements arrived across several releases. The advanced catalog and refund quote were introduced during v2.x; v3 brings the extended contract under the canonical address. The October 2026 update (v3.2; responses carry the header X-NotPanel-API-Version: 2026-10) adds order_details, fixed error codes and one-event webhooks while every earlier action keeps working. The API changelog records that history and maps earlier error codes and webhook names to the current ones.
A few changes from that update matter for most order screens:
- Every error carries an
error_code, an HTTP status and aretryableflag. Branch on those instead of the message text. - Drip-feed still accepts
runswithinterval, or you can send the total quantity withdrip_feed_total_minutes. Either way the whole order finishes within 48 hours (2,880 minutes). - Telegram reactions use one
reactionsfield, either a mix or exact counts, checked before you are charged. cancelwithorderreturns one object; withordersit returns a list. Refill can be requested once every 6 hours per order on services that support it, with no end date.- Some services accept only one active order per link. A second order for the same link while the first is running returns
LINK_BUSY, which is retryable once the first order finishes.
Build a service selector that answers the customer's questions
The familiar action=services returns one object per service with your own rate, limits and the details a selector needs: tags, the extra inputs in fields, drip-feed limits, the quantity step, availability and the average start time. action=catalog still works when you want search, filters and pagination. A custom-comments service should ask for the comments, one per line, because the quantity is the number of comment lines.
Start-time evidence is particularly useful before a purchase. Avg. start estimates the wait from placement to first observed positive delivery; average_time_minutes is null when too few orders are known. Completion of the entire quantity is a different milestone.
If you request localized service names, keep the numeric service ID as your reference. Read canonical_name for the English name and name_language for the language actually returned, including an English fallback. The catalog is a snapshot for choosing a service; the committed order response confirms the purchase and its charge.
Recover one purchase after a timeout
Suppose your shop assigns shop-order-1042 to a purchase. NotPanel accepts it, but the response is lost. A timeout tells your integration that it did not receive the answer. It does not establish whether the order exists.
Save the request ID and order details before submitting. Retry that same logical request with the same request_id. If the order has committed, the API returns that order with replayed: true instead of charging for another purchase; if the first attempt never arrived, the retry places it once. You never need a fresh ID to get past a timeout. To look the order up without resending it, call order_details with the same request_id.
Changed order details under the same ID cause a conflict. The optional idempotency_key is a compatibility alias; request_id takes precedence when both are supplied. Neither value belongs in your social-media target URL or in a customer's public receipt.
The add-order reference defines the request contract; the timeout recovery guide walks through the uncertain-result case in more detail.
Explain an order's money as clearly as its status
A customer can see an order marked Canceled or Partially completed and still need to know whether the credit is available. Another customer may ask to cancel after dispatch. A balance total alone cannot answer either question.
The order status reply is read-only and carries the money: for a Canceled or Partially completed order it shows the net charge and the refund already credited to the Wallet, so no separate call is needed. Read those fields instead of assuming every order follows the same settlement process.
Every order can be canceled for a full refund during its first 15 seconds. After that, a cancel request is possible where the service supports it, and the undelivered part is refunded automatically when the cancel is confirmed. Seven-day unresolved-order protection uses the original placement time. Link the order refund guide where customers need the scope, and show credited amounts only when the response confirms the credit.
Use notifications to prompt a status check
Signed webhooks can bring order and refill changes to your integration, one signed event per message: for example order.completed, order.partial, order.canceled and the refill results. Verify the signature, handle repeated events without repeating business actions, and reconcile important outcomes through action=status. Delivery and arrival order are not guaranteed.
For example, receiving the same cancellation notification twice must not credit your own customer's account twice. A notification should update the recorded state of the original order. The webhook reference covers delivery and verification; the error reference explains errors and any supplied Retry-After instruction.
A practical adoption plan for an existing panel
- Map the current calls. Record which screens use services, add, status and balance. Check the request and response examples against the current reference.
- Implement purchase IDs first. Keep one ID and one saved payload per purchase, including the order mapping after a response arrives.
- Test failure handling without spending. Use mocked responses for a timeout, repeated notification and conflicting retry. Public examples are documentation, not a free order sandbox.
- Validate a small, deliberate live order. Choose an available service, review its requirements and charge, then follow its status and Wallet record. Live submissions can spend real balance.
- Add richer discovery and customer updates. Adopt the service fields, order details and notifications as the corresponding screens are ready.
Keep the API key on your server. The getting-started guide provides the request format and next references. You can improve one workflow at a time without presenting the URL change itself as a delivery-speed upgrade.
Questions about NotPanel API v3
Do I have to replace a working NotPanel v2 integration?
No. NotPanel's /api/v1, /api/v2 and /api/v3 addresses behave identically, and existing key and action calls remain supported. Use /api/v3 for new integrations, and test any optional actions or fields before enabling them in your customer workflow.
Can I deliberately submit two identical orders?
Yes. Give each intended purchase its own request_id. Reusing the same ID and order details recovers the first purchase. If you omit both request_id and idempotency_key, identical requests from the same account within the 60-second protection window also return the first order.
Does switching to v3 make a service deliver faster?
The endpoint version does not promise faster delivery. The service list helps you compare available services and their average start time. Delivery still follows the selected service and the order's actual progress.
Does reading an order's refund cancel it or move money?
No. Reading an order status is read-only. For a Canceled or Partially completed order it shows the net charge and the refund already credited. A cancellation response and the actual Wallet credit are separate things to confirm.
