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

# PlaytoliaStore

> Item catalog and purchase flow management

### Methods

| Method                                            | Parameters                                                        | Returns           | Notes                          |
| ------------------------------------------------- | ----------------------------------------------------------------- | ----------------- | ------------------------------ |
| `GetItems()`                                      | —                                                                 | `List<StoreItem>` |                                |
| `SearchItems(query)`                              | `string`                                                          | `List<StoreItem>` | Matches name, description, SKU |
| `GetItemsByType(type)`                            | `string`                                                          | `List<StoreItem>` | See item types below           |
| `GetItemById(id)`                                 | `string`                                                          | `StoreItem?`      |                                |
| `GetItemBySku(sku)`                               | `string`                                                          | `StoreItem?`      |                                |
| `BeginPurchaseFlow(item, onSuccess?, onError?)`   | `StoreItem`, `Action<PurchaseReceipt>?`, `Action<PurchaseError>?` | `void`            | Callbacks are optional         |
| `BeginPurchaseFlow(itemId, onSuccess?, onError?)` | `string`, `Action<PurchaseReceipt>?`, `Action<PurchaseError>?`    | `void`            | Callbacks are optional         |
| `Refresh()`                                       | —                                                                 | `void`            |                                |
| `AddListener(listener)`                           | `Action`                                                          | `void`            |                                |
| `RemoveListener(listener)`                        | `Action`                                                          | `void`            |                                |

### Item types (for GetItemsByType)

`"Consumable"` · `"NonConsumable"` · `"Subscription"`

### StoreItem

| Field    | Type      | Notes                             |
| -------- | --------- | --------------------------------- |
| `Id`     | `string`  |                                   |
| `Name`   | `string`  |                                   |
| `Sku`    | `string`  | App Store / Play Store product ID |
| `Type`   | `string`  |                                   |
| `Grants` | `Grant[]` | Rewards granted on purchase       |

### Grant

| Field         | Type        | Notes                        |
| ------------- | ----------- | ---------------------------- |
| `GrantId`     | `string`    | Groups related grants        |
| `GrantType`   | `string`    |                              |
| `GrantAmount` | `long`      |                              |
| `Currency`    | `Currency?` | Non-null for currency grants |

### PurchaseReceipt

Returned in the `onSuccess` callback of `BeginPurchaseFlow`.

| Field       | Type        | Notes                                                                           |
| ----------- | ----------- | ------------------------------------------------------------------------------- |
| `Item`      | `StoreItem` | The purchased store item                                                        |
| `ReceiptId` | `string`    | Platform transaction ID (Google Play purchase token / App Store transaction ID) |
| `Store`     | `string`    | `"google_play"` or `"apple_app_store"`                                          |

### PurchaseError

Returned in the `onError` callback of `BeginPurchaseFlow`.

| Field       | Type      | Notes                                                                            |
| ----------- | --------- | -------------------------------------------------------------------------------- |
| `Code`      | `string`  | Machine-readable error code (see table below)                                    |
| `Message`   | `string`  | Human-readable description                                                       |
| `Stage`     | `string`  | Where in the flow the error occurred                                             |
| `ReceiptId` | `string?` | Set when the platform purchase succeeded but verification/acknowledgement failed |
| `ItemId`    | `string?` | Playtolia store item ID (if known)                                               |
| `ItemSku`   | `string?` | Platform SKU (if known)                                                          |

### Purchase error codes

| Code                     | Stage             | Description                                                   |
| ------------------------ | ----------------- | ------------------------------------------------------------- |
| `BILLING_UNAVAILABLE`    | `PURCHASE`        | Platform billing is not available on this device              |
| `ITEM_NOT_FOUND`         | `PURCHASE`        | Store item ID was not found in the SDK state                  |
| `USER_CANCELLED`         | `PURCHASE`        | The user dismissed the purchase dialog                        |
| `PURCHASE_FAILED`        | `PURCHASE`        | Platform billing returned an error                            |
| `VERIFICATION_FAILED`    | `VERIFICATION`    | Backend purchase verification failed                          |
| `ACKNOWLEDGEMENT_FAILED` | `ACKNOWLEDGEMENT` | Platform acknowledgement failed after successful verification |

<Tip>
  When `Stage` is `ACKNOWLEDGEMENT`, the user has already been charged. The SDK will automatically retry acknowledgement in the background on next app launch. You can reassure the player that their purchase is being processed.
</Tip>