> ## Documentation Index
> Fetch the complete documentation index at: https://docs.madiad.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Boost

> Credits included with a paid plan, spent on raising engagement for your own posts and pages. Beta: not open to customers yet.

> [!WARNING]
>
> **Beta (Tính năng thử nghiệm).** Boost (*Hỗ trợ tương tác* in the dashboard) is **not open to customers yet**. This page describes how it works once it opens. Until then your dashboard has no Hỗ trợ tương tác page, and every `/v1/boost/*` path answers `404 not_found`, the same as a path that does not exist.

## What it is

*Beta, not open to customers yet.*

Boost is an **add-on feature included with a paid MADIAD Hub plan**. In every plan period, an account on an active paid plan receives an allowance of credits. You spend them on orders that raise engagement (for example likes) on your own posts or pages on social networks.

* **No charge beyond the plan price.** Credits come with the plan and cannot be exchanged for money.
* The feature is in a trial phase: an order's result can be late, off, or interrupted. Whatever an order did not deliver is refunded in credits (see [Order statuses](#order-statuses)).
* The feature's terms are in [section 3 of the Terms of Service](https://madiad.com/en/terms#interaction-support): what credits are worth, when they expire and how they are refunded. The Hỗ trợ tương tác page of the dashboard links to the same section.

This page does not state any plan's credit allowance. It is shown in the dashboard, correct for your own plan period, so read it there. The credits an order will use are shown in the form before you place it.

## Who gets credits

*Beta, not open to customers yet.*

| Account | Credits |
| - | - |
| Active paid plan | Yes, the plan's allowance, renewed every plan period |
| Trial, or a 0 VND plan period | No |
| Plan expired and not renewed | No (the remaining credits end together with the plan) |
| No paid plan period yet | No |

When a period has no credits, the dashboard says why in one sentence, and the API returns a reason code in `reason` (see [Using the API](#using-the-api)).

## Plan periods and expiry

*Beta, not open to customers yet.*

* **A plan period is one month**, counted from your payment date in Vietnam time. 6- and 12-month plans also renew credits **every month**; they do not receive them once for the whole term.
* **Unused credits expire with the period.** They do not carry over.
* The last period of a plan ends exactly when the plan expires. The dashboard says when you are in it.
* Renewing early: a new plan period starts with that payment, with a full allowance. What was left of the old period can no longer be used.
* The current period's start and end are shown on the dashboard's Hỗ trợ tương tác page, in Vietnam time.

## Placing an order

*Beta, not open to customers yet.*

In the dashboard, **Hỗ trợ tương tác** (last item under Nội dung) shows what can be ordered this period, the credits left, the order form and the order history.

1. **Paste the link** to the post or page: one `https://` address, at most 2,048 characters. The form tells which platform it belongs to (Facebook, Instagram…).
2. **Pick the interaction type** for that platform, such as likes. The types on offer are listed in the dashboard. There is nothing else to choose: MADIAD runs the order.
3. **Enter a quantity** between the minimum and the maximum. The form shows the credits the order will use and what is left after it.
4. **Place the order.** The credits are reserved as soon as the order is taken. Orders usually go out within minutes, and the status updates in the order history.

For an interaction type that takes your own comments (when your period has one): one comment per line, **as many lines as the quantity**, each line non-empty and at most 500 characters. Comments pass a content filter before the order is taken. If a line does not pass, the order is refused, no credits are taken, and the dashboard names that line so you can fix it.

**Credits follow your plan period.** The credits an interaction type uses are set by the plan period you are in. If MADIAD lowers them mid-period, your orders use fewer credits at once. If MADIAD raises them, the new amount applies from your next plan period.

**No double orders.** If you press the order button on a shaky connection and cannot tell whether the order was taken, check the order history first. If the order is not there, press again: the form keeps the previous press's key, so the second press cannot create a second order.

## Order statuses

*Beta, not open to customers yet.*

| Status (API) | Dashboard label | Meaning | Credits |
| - | - | - | - |
| `queued` | Đang chờ gửi | Taken, waiting to be sent | Reserved |
| `processing` | Đang chạy | Sent and running | Reserved |
| `completed` | Hoàn thành | Delivered in full | Spent |
| `partial` | Hoàn thành một phần | Delivered in part | The undelivered part is refunded |
| `cancelled` | Đã huỷ | Cancelled, or never sent | The undelivered part is refunded (never sent: in full) |
| `rejected` | Bị từ chối | Refused when sent | Refunded in full |
| `expired` | Quá hạn chờ | Waited too long without being sent (for example during an interruption) | Refunded in full |
| `unknown` | Chưa rõ kết quả | Not yet confirmed whether the order ran | Reserved; refunded if it is confirmed the order did not run |
| `untracked` | Không theo dõi được | The order was created but its progress cannot be followed | Reserved |

For `unknown` the dashboard shows the fixed sentence "Chưa rõ kết quả, credits đang được giữ và sẽ được hoàn nếu xác nhận đơn không chạy." MADIAD refunds only on evidence that the order did not run, so this status can last longer than the others.

**Which period a refund goes to.** An order that was sent (delivered short, cancelled, refused, or unknown and then confirmed not run) is refunded into your **current plan period**, even if it was placed in an earlier one. An order that was never sent is refunded into **the period that reserved it**. There is no button to cancel or refund an order by hand: credits are refunded only from the order's real outcome.

## When the feature is interrupted, suspended or stopped

*Beta, not open to customers yet.*

The top of the Hỗ trợ tương tác page carries a banner whenever the feature is not running normally. When there is a public notice, the banner links it ("Xem thông báo").

| State | Dashboard says | New orders |
| - | - | - |
| Temporarily interrupted (technical incident, maintenance) | The feature is interrupted, your credits are kept | Not until it runs again |
| Suspended | The feature is suspended, new orders cannot be placed | No |
| Stopping from the next period | The feature stops from the next plan period; this period's credits stay usable to its end | Yes, to the end of the period |
| Stopped | The feature is no longer offered | No |

What happens to credits in each case follows the feature's terms of use.

## Using the API

*Beta, not open to customers yet.*

> [!NOTE]
>
> The paths below answer only once the feature is open to your account. Their API Reference pages are added when the feature opens. Every answer follows [Errors](https://docs.madiad.com/concepts/errors.md).

| Path | Does |
| - | - |
| `GET /v1/boost/services` | The interaction types you can order this period: `id`, `name`, `platform`, `requires_comments`, `min`, `max`. No price: an order's credits are in the answer when you place it (`price_credits`) |
| `POST /v1/boost/orders` | Place one order: `service_id` (the interaction type's `id`), `link`, `quantity`, and `comments` (only for a type that takes them). **`Idempotency-Key` header required**, one key per order. `202` while the order waits to be sent |
| `GET /v1/boost/orders` | Your orders, newest first. `?limit=1..100`. Next page: `?before=<next_before>&before_id=<next_before_id>` |
| `GET /v1/boost/orders/{id}` | One of your orders. Another account's id answers `404` |

Sending the same `Idempotency-Key` with the same body returns the same order and takes no more credits (see [Idempotency](https://docs.madiad.com/concepts/idempotency.md)). The same key with a different body answers `409 idempotency_conflict`. These paths read only the `Idempotency-Key` header (not `X-Idempotency-Key` or `X-Request-Id`), and a replay carries no `Idempotent-Replayed` header: the answer is the order itself, `202` while it is still queued, `200` otherwise.

Once the feature is open to your account, `GET /v1/usage` carries a `boost_credits` block:

| Field | Meaning |
| - | - |
| `limit`, `used`, `remaining` | The period's allowance, spent, left. `remaining` can exceed `limit` when credits are refunded into the period |
| `period_start`, `period_end` | Start and end of the current plan period |
| `is_last_period` | This period ends with the plan |
| `reason` | Why the period has no credits: `not_eligible`, `plan_inactive`, `no_paid_term`, `trial_or_zero`, `feature_stopped`, `period_forfeited`, `account_disabled`; `null` when it has credits |
| `feature_state` | `on`, `paused` (interrupted), `suspended`, `stopping` (stops from the next period), `stopped` |
| `notice_url` | The state's public notice, when there is one |
| `feature_name`, `terms_url` | Feature name, terms of use |

Error answers specific to these paths:

| HTTP | `code` | When |
| - | - | - |
| 400 | `invalid_request` | A missing or unknown field, a bad link, a quantity out of range, a comment count that differs from the quantity |
| 403 | `forbidden` | The period has no credits (with `reason`), the feature is switched off for the account, or the account is locked |
| 403 | `feature_suspended` | The feature is suspended (with `notice_url`) |
| 404 | `not_found` | The interaction type is not offered this period, or the order is not yours |
| 409 | `idempotency_conflict` | The `Idempotency-Key` was already used for a different order |
| 422 | `content_rejected` | A comment line did not pass the content filter (with `line`, `rule`) |
| 429 | `quota_exceeded` | Not enough credits for the order (with `remaining`, `renews_at`) |
| 503 | `feature_paused` | Temporarily interrupted, credits kept. Retry after `Retry-After` seconds |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.