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 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.

After the First Package, the Top-up API can be used to add another data package to an existing customer. Please note that Top Ups work only within the same Country Set.

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).

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.

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

Event	Act.Item Size	Act.Item ID	Balance Size	Total Balance
First Purchase	1GB	1	1GB	1GB
Topup	3GB	2	3GB	4GB
Usage of 0.5GB	-	1	0.5GB	3.5GB
Item Expiry	-	1	0.5GB	3GB
Usage of 0.7GB	-	2	2.3GB	2.3GB
Topup	5GB	3	5GB	7.3GB

Related eSIMs

When creating the customer through the First Package request, an eSIM is created for this customer. That is the first related eSIM for a customer.

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 section for details.