# Customers

To provide connectivity to your customers, you need to create at least one Gigastore Customer on the Gigastore API.

A Gigastore Customer is an entity to which eSIM profiles and data packages are attached. Each Gigastore Customer belongs to a specific `countrySet` type used during registration. As a result, a request to activate a data package with a different country set will generate an error.

To create a Gigastore Customer via API, you need to activate the [First Package](/api/first-package.md) and provide an email of the user. The API returns a `uid` that is used by API calls to top-up additional data packages to the Gigastore customer account.

You can link several Gigastore Customers to a single customer if you wish to provide that individual with an eSIM featuring a different  `countrySet` than what was originally registered. To do so, associate the Gigastore Customer UIDs to your customer directly in your platform.\
Remember that one Customer UID means one  `countrySet`.

This model enables you to offer eSIMs and data to your customers, while also monitoring their eSIM usage by country.

### Get all customers

You can use the `/gigastore/activations/customers` endpoint to retrieve a list of all customers on your account. Each customer comes with details like `email` and `uid`, a `totalAvailableBalance`, a list of `activatedItems` and a list of `relatedEsims`.

```
GET /gigastore/activations/customers

Response:
[
    "customer": {
                "email": null,
                "uid": "261ef0b4-b054-4a0f-9e06-ba9193b5c0a5",
                ...
            },
            "totalAvailableBalance": {
                "sizeValue": 2,
                "sizeUnit": "GB"
            },
            "activatedItems": [
                {
                    "uid": "0b35b82f-ae46-4717-96be-12345676789",
                    "balance": {
                        "activatedAt": "2024-03-23T10:53:47Z",
                        "expiresAt": "2024-04-23T10:53:47Z",
                        ... },
                },
                {
                    "uid": "2342bc23-ae46-4717-96be-12345676789",
                    "balance": {
                        "activatedAt": "2024-04-23T10:53:47Z",
                        "expiresAt": "2024-05-23T10:53:47Z",
                        ... },
                },
                
            ],
            "relatedEsims": [
                {
                    "iccid": "891234567891234567890",
                    "imsi": "260123456789012",
                    "activationCode": "LPA:1$domain.tld$CODE123456789",
                    "uid": "12345-abcdef-56789" // can be used as input for SDK
                    ...
                }
            ]
        },
    ...
]
```

### Get specific customers

To get a specific customer, you can use different methods: 

* Fetch the customer by UID by using the `gigastore/activations/customers/<uid>` endpoint
* Search for a customer by using the `gigastore/activations/search-customers` endpoint

### Activated Items

Gigastore supports the purchase/activation of multiple packages per customer.&#x20;

After the [First Package](/api/first-package.md), the [Top-up](/api/top-up.md) API can be used to add another data package to an existing customer. <mark style="color:red;">Please note that Top Ups work only within the same Country Set.</mark>

The customer object contains a list of all activated packages (`activatedItems`). Each entry contains a balance object, including the date and time of purchase, the package size (e.g. 3GB), and the currently available balance (e.g. 1,3 GB).&#x20;

### Total Balance

This value sums up the customer's current available balance. Gigastore handles different events internally and provides a convenient method to get the current balance.&#x20;

This value is recommended for showing your users in the UI.

<table><thead><tr><th width="168">Event</th><th width="183">Act.Item Size</th><th data-type="number">Act.Item ID</th><th>Balance Size</th><th>Total Balance</th></tr></thead><tbody><tr><td>First Purchase</td><td>1GB</td><td>1</td><td>1GB</td><td>1GB</td></tr><tr><td>Topup</td><td>3GB</td><td>2</td><td>3GB</td><td>4GB</td></tr><tr><td>Usage of 0.5GB</td><td>-</td><td>1</td><td>0.5GB</td><td>3.5GB</td></tr><tr><td>Item Expiry</td><td>-</td><td>1</td><td>0.5GB</td><td>3GB</td></tr><tr><td>Usage of 0.7GB</td><td>-</td><td>2</td><td>2.3GB</td><td>2.3GB</td></tr><tr><td>Topup</td><td>5GB</td><td>3</td><td>5GB</td><td>7.3GB</td></tr></tbody></table>

### Related eSIMs

When creating the customer through the [First Package](/api/first-package.md) request, an eSIM is created for this customer. <mark style="color:red;">That is the first related eSIM for a customer.</mark>

In case a customer lost its device, an additional eSIM can be issued (e.g. through a support request on your side) and added to the customer. In this case, multiple related eSIMs can be returned by the API.

The uid of the eSIM can be transported to your app and used with the SDK to install the eSIM directly on the device.

Please see the [eSIM Profiles](/api/esim-profiles.md) section for details.&#x20;


---

# 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/customers.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.