# Top-up

Once the [First Package](/api/first-package.md) has been activated, you can add more balance to your Gigastore Customer via the `/gigastore/activations/top-up` endpoint.\
Please note that Top-ups can only be activated for existing Gigastore Customer and must match the `CountrySet` during the initial activation.

{% hint style="info" %}
The activation will use your credit balance on Gigastore and deduct the purchase value from your credit. You can check for the history of activations here: <https://dent.giga.store/#/your-store/history>.
{% endhint %}

#### To activate a top-up, you need:

* **inventoryItemId** - see [Offering Packages](/api/offering-packages.md)
* **metatag**, e.g. an internal transaction id (will be stored and can be retrieved via API)
* **customerUid** - the uid of your customer as returned during registration
* **expectedPrice** - the retail price of the package (optional)
* **activationMode -** type of package activations (optional) see [Activation Modes](/api/activation-modes.md)

#### Top-up behavior

* Top-ups are consumed in order of shortest remaining validity.
* Inactive FIRST\_USE top-ups will not be used until all active package(s) are empty or expired.
* Multiple inactive FIRST\_USE top-ups activate in order of the closest `expiresAt` date, usually matching the purchase order.
* ON-DEMAND top-ups can be stacked and will remain inactive until manually triggered via API.
* Top-ups activate and take priority for usage automatically based on coverage area, even if other plans are active.

```
POST /gigastore/activations/top-up

Request:
{
    "inventoryItemId": "00e3e46e-faa5-465a-9321-1234567890",
    "metatag": "Comment for reseller...",
    "customerUid": "123234345-234-cbd2-9321-1234567890",
    "expectedPrice":{
            "sortIndex": 0,
            "priceValue": 4.99,
            "currencyCode": "USD"
    },
    "activationMode": "NOW"
}

Response:
{
    "status": "success",
    "activatedItem": {
        "balance": {
            "activatedAt": "2024-04-30T10:41:03.14304Z",
            "expiresAt": "2025-04-30T10:41:03Z",
            "activationMode": "NOW",
            "name": "eSIM Worldwide 50 MB",
            "size": {
                "sizeValue": 50,
                "sizeUnit": "MB"
            },
            "availableBalance": {
                "sizeValue": 0.05,
                "sizeUnit": "GB"
            },
            "validitySize": 365,
            "validityUnit": "days"
        },
        "uid": "4f1eec1b-61dc-47df-91a6-....",
        "metatag": "Comment for reseller...",
        ...
    },
    "customer": {
        "email": null,
        "uid": "123234345-234-cbd2-9321-1234567890",
        "profileUrl": "<url>"
    },
    "esimProfile": null
}
```

The request will return a newly created **activatedItem**.&#x20;

The customer's total balance will be updated immediately. See [Customers](/api/customers.md) for more details.

{% hint style="info" %}
The top-up is instantly usable by your user; no additional eSIM needs to be installed.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.giga.store/api/top-up.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.