# 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](https://docs.giga.store/api/first-package "mention") 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](https://docs.giga.store/api/first-package "mention"), the [top-up](https://docs.giga.store/api/top-up "mention") 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](https://docs.giga.store/api/first-package "mention") 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](https://docs.giga.store/api/esim-profiles "mention") section for details.&#x20;