### Install Dependencies with npm

Source: https://dev.smile.io/guides/use-cases/landing-page/bigcommerce-stencil

Installs project dependencies using npm. This command is typically run after downloading theme files and navigating to the theme's directory in the terminal.

```bash
sudo npm install
```

--------------------------------

### Cursor Pagination Response Example (JSON)

Source: https://dev.smile.io/api/pagination/cursor-pagination

An example of a JSON response demonstrating cursor pagination. It includes a list of items (e.g., 'customers') and a 'metadata' object containing 'next_cursor' and 'previous_cursor' values. These cursors are used to navigate through the collection.

```json
{
  "customers": [],
  "metadata": {
    "next_cursor": "aWQ6MixkaXJlY3Rpb246bmV4dA==",
    "previous_cursor": null
  }
}
```

--------------------------------

### API Key Authentication Example (Bash)

Source: https://dev.smile.io/api/authentication

This example demonstrates how to authenticate an API request using an API key with the `curl` command. The API key is provided in the `Authorization` header as a Bearer token. This method is typically used by merchants.

```bash
curl --location 'https://api.smile.io/v1/' \
    --header 'Authorization: Bearer api_cnzGMghxTmPzK1sp' \
  
```

--------------------------------

### OAuth Access Token Authentication Example (Bash)

Source: https://dev.smile.io/api/authentication

This example shows how to authenticate an API request using an OAuth Access Token with the `curl` command. The token is included in the `Authorization` header as a Bearer token. This method is used by apps after a merchant completes OAuth.

```bash
curl --location 'https://api.smile.io/v1/' \
    --header 'Authorization: Bearer oa2_qz8mD1JdFwMgDd4o' \
  
```

--------------------------------

### Bundle Theme Files with Stencil CLI

Source: https://dev.smile.io/guides/use-cases/landing-page/bigcommerce-stencil

Bundles the theme files for deployment. This command is used after merging explainer page assets and templates into the theme directory. It may require manual template adjustments if specific components are missing.

```bash
stencil bundle
```

--------------------------------

### Get Points Settings

Source: https://dev.smile.io/js/resources/points-settings/get

Retrieves the configuration for the account's points program. This method always makes an API call to fetch the latest data.

```APIDOC
## GET /points/settings

### Description
Retrieves the configuration for the account's points program. This method always makes an API call to fetch the latest data.

### Method
GET

### Endpoint
/points/settings

### Parameters
#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{
  "example": "No request body needed for this GET request."
}
```

### Response
#### Success Response (200)
- **pointsSettings** (object) - An object containing the points program configuration.

#### Response Example
```json
{
  "example": "{\"program_name\": \"Loyalty Points\", \"earning_rate\": 10, \"redemption_rate\": 100}"
}
```

#### Error Response
- **error** (object) - An error object if the request fails.
```

--------------------------------

### Replace Smile UI Script with Smile.js SDK (HTML & JavaScript)

Source: https://dev.smile.io/guides/use-cases/custom-frontend/js-sdk-migration

This example shows how to replace the old Smile UI script tag with the new Smile.js SDK script tag and update the initialization call from `SmileUI.initialize` to `Smile.initialize`. This is for custom storefronts that are no longer using the rewards panel and launcher.

```html
<script async src="https://js.smile.io/v1/smile-ui.js"></script> // [!code --]
<script async src="https://sdk.smile.io/smile-js/v1/smile.js"></script> // [!code ++]

<script>
  SmileUI.initialize({ // [!code --]
  Smile.initialize({ // [!code ++]
    publishableKey: "pub_0987654321",
    customerToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  });
</script>
```

--------------------------------

### Customer Token Generation (Ruby & JavaScript)

Source: https://dev.smile.io/js/concepts/customer-tokens

Examples demonstrating how to generate a customer token (JWT) on the backend using Ruby and JavaScript. These snippets show the construction of the payload with dynamic customer information and expiration, and the subsequent encoding using a signing key and HS256 algorithm.

```ruby
# Generating a customer token from a Ruby backend
shopify_customer_id = '10733458'
signing_key = 'sig_a5b85911214932b56b360ac956ddb392'

payload = {
  aud: 'api.smile.io',
  sub: "ShopifyCustomer:#{shopify_customer_id}",
  exp: Time.now.to_i + 300 # Set expiry to 5 minutes
}

customer_token = JWT.encode(
  payload, signing_key, 'HS256', { typ: 'JWT' }
)
```

```javascript
// Generating a customer token from a JS backend
import jwt from 'jsonwebtoken';

const shopifyCustomerId = '10733458';
const signingKey = 'sig_a5b85911214932b56b360ac956ddb392';

const payload = {
  aud: 'api.smile.io',
  sub: `ShopifyCustomer:${shopifyCustomerId}`,
  exp: Math.floor(Date.now() / 1000) + 300 // 5 minutes from now
};

const customerToken = jwt.sign(
  payload,
  signingKey,
  { algorithm: 'HS256', header: { typ: 'JWT' } }
);
```

--------------------------------

### Example Customer Updated Webhook Data (JSON)

Source: https://dev.smile.io/guides/apps/webhooks

This JSON snippet illustrates the 'data' portion of a 'customer/updated' webhook. It includes a 'customer' object containing details about the updated customer.

```json
{
  "data": {
    "customer": {}
  }
}
```

--------------------------------

### Remove Missing Template Reference

Source: https://dev.smile.io/guides/use-cases/landing-page/bigcommerce-stencil

Removes a reference to a missing template component from an HTML file. This is a workaround for a common warning during the 'stencil bundle' process when the 'page-header' component is not found.

```html
{{> components/pages/page-header page_title=page.title}}
```

--------------------------------

### Fetch Points Settings using JavaScript

Source: https://dev.smile.io/js/resources/points-settings/get

The `Smile.pointsSettings.get()` method is an asynchronous function that retrieves the current configuration for the account's points program by making an API call. It returns a Promise that resolves with the points settings object on success or rejects with an error object on failure. For optimal performance, consider preloading settings.

```javascript
Smile.pointsSettings.get().then(
  (pointsSettings) => {
    // Handle the points settings object
  }
);
```

--------------------------------

### Get Customer Points Products

Source: https://dev.smile.io/js/resources/customer-points-products/get

Retrieves a list of available redemption options for the currently logged-in customer. This method always makes an API call to fetch the latest data.

```APIDOC
## GET /customerPointsProducts

### Description
Retrieves a list of available redemption options for the currently logged-in customer. This method always makes an API call to fetch the latest data.

### Method
GET

### Endpoint
/customerPointsProducts

### Parameters
#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{
  "example": "No request body needed for this GET request."
}
```

### Response
#### Success Response (200)
- **customerPointsProducts** (array) - An array of customer points product objects. If no points products are defined, the array will be empty.

#### Response Example
```json
{
  "customerPointsProducts": [
    {
      "id": "prod_123",
      "name": "Example Product",
      "points_required": 100,
      "description": "A sample product for redemption."
    }
  ]
}
```

#### Error Response
- **error** (object) - An error object if the method is improperly invoked (e.g., no customer currently logged in) or if an API error occurs.
```

--------------------------------

### Get Current Customer Object (JavaScript)

Source: https://dev.smile.io/js/resources/customer/current

Retrieves the currently logged-in customer object from the cache. This method does not make an API call. It returns a customer object if a customer is authenticated, otherwise it returns null.

```javascript
const customer = Smile.customer.current();

if (customer) {
  // Handle the customer object
} else {
  // No customer is currently logged in
}
```

--------------------------------

### Smile.customerReady() and Smile.ready() Migration

Source: https://dev.smile.io/guides/use-cases/custom-frontend/js-sdk-migration

Instead of calling `Smile.customerReady()` or `Smile.ready()`, listen for the `smile-js-initialized` event.

```APIDOC
## Event Listener for Smile JS Initialization

### Description
Listen for the `smile-js-initialized` event to know when the Smile JavaScript SDK is ready.

### Method
Event Listener

### Endpoint
N/A

### Parameters
#### Event
- **smile-js-initialized**: This event is dispatched when the SDK has finished initializing.

### Example Usage
```javascript
document.addEventListener('smile-js-initialized', function() {
  console.log('Smile JS SDK is initialized!');
  // Now you can safely use Smile SDK methods
});
```
```

--------------------------------

### Initialize the SDK

Source: https://dev.smile.io/js/smile/initialize

This asynchronous method initializes the SDK with loyalty program and customer information. It must be called before using other SDK methods.

```APIDOC
## Initialize the SDK

### Description
Initializes the Smile.io SDK with loyalty program and customer details. This method must be invoked before any other SDK interactions.

### Method
`Smile.initialize(options)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **options** (object) - Required - An object containing initialization options.
  - **publishableKey** (string) - Required - Your Smile.io publishable key.
  - **customerToken** (string) - Optional - A token identifying the logged-in customer. Omit or set to `null` if no customer is logged in.
  - **preload** (array) - Optional - An array of resource keys to preload.

### Request Example
```javascript
Smile.initialize({
  publishableKey: 'pub_0987654321',
  customerToken: 'eyJhbGciOiJIUzI1NiJ9.eyJjdXN0b21lcl9pZGVudGl0eSI6eyJkaXN0aW5jdF9pZCI6IjEwMCJ9LCJleHAiOjE1ODU1OTE1MzZ9.PGJhiM0NYRok5VGAlAOT6F-57gu7SCBaennQbt6YrqU',
  preload: ['pointsSettings']
});

// For asynchronous script loading:
document.addEventListener('smile-js-loaded', () => {
  Smile.initialize({
    publishableKey: 'pub_0987654321',
    customerToken: 'eyJhbGciOiJIUzI1NiJ9.eyJjdXN0b21lcl9pZGVudGl0eSI6eyJkaXN0aW5jdF9pZCI6IjEwMCJ9LCJleHAiOjE1ODU1OTE1MzZ9.PGJhiM0NYRok5VGAlAOT6F-57gu7SCBaennQbt6YrqU',
    preload: ['pointsSettings']
  });
});
```

### Response
#### Success Response (200)
Resolves to void, indicating the SDK is initialized and ready.

#### Response Example
(No specific response body for success, promise resolves)

#### Error Handling
Rejects with an error object if the method is improperly invoked (e.g., missing `publishableKey`).
```

--------------------------------

### Initialize Smile UI with ready() Method (JavaScript)

Source: https://dev.smile.io/ui/events/ui-ready

The SmileUI.ready() method detects when Smile UI and its dependencies are fully initialized. It returns a Promise that resolves with the initialized SmileUI instance on success or an error object on failure. This is useful for wrapping calls to other SmileUI methods.

```javascript
SmileUI.ready()
  .then((smileUiInstance) => {
    // Smile UI has been fully initialized
    // and is ready to be used. smileUiInstance
    // is an instance of the initialized
    // variable and is synonymous with
    // window.SmileUI
  })
  .catch((err) => {
    // An error has occurred while initializing
  });

```

--------------------------------

### Get Customer VIP Status using JavaScript

Source: https://dev.smile.io/js/resources/customer-vip-status/get

Retrieves the VIP status of the currently logged-in customer using the Smile.customerVipStatus.get() method. This method makes an API call and returns a Promise that resolves with the customer VIP status object or rejects with an error object.

```javascript
Smile.customerVipStatus.get().then(
  (customerVipStatus) => {
    // Handle the customer VIP
    // status object
  }
);
```

--------------------------------

### Enable resource preloading with Smile.initialize

Source: https://dev.smile.io/guides/use-cases/custom-frontend/js-sdk-migration

Demonstrates how to enable resource preloading during Smile SDK initialization by specifying resources in the `preload` array. This replaces separate API calls for each resource with instant access to preloaded data.

```javascript
await Smile.initialize({
  publishableKey: 'pub_0987654321',
  customerToken: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
  preload: ['pointsProducts', 'customerPointsWallet'] // [!code ++]
});

// Make separate API calls for each resource // [!code --:3]
const pointsProducts = await Smile.pointsProducts.get();
const pointsWallet = await Smile.customerPointsWallet.get();
// Access preloaded data instantly (no additional API calls) // [!code ++:3]
const pointsProducts = Smile.pointsProducts.preloaded();
const pointsWallet = Smile.customerPointsWallet.preloaded();
```

--------------------------------

### Get Customer Points Wallet (JavaScript)

Source: https://dev.smile.io/js/resources/customer-points-wallet/get

Asynchronously retrieves the points wallet of the currently logged-in customer. This method always makes an API call to fetch the latest data. It returns a Promise that resolves with a customer points wallet object on success or rejects with an error object on failure.

```javascript
Smile.customerPointsWallet.get().then(
  (customerPointsWallet) => {
    // Handle the customer points
    // wallet object
  }
);
```

--------------------------------

### Login Customer with Smile.js

Source: https://dev.smile.io/js/resources/customer/login

This JavaScript snippet demonstrates how to log in a customer using the Smile.customer.login method. It shows both a basic login and a login that preloads specific resources like 'rewardFulfillments'. The method returns a Promise that resolves on success or rejects with an error on failure.

```javascript
Smile.customer.login({
  customerToken: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
}).then(() => {
  // Customer logged in successfully
});

Smile.customer.login({
  customerToken: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
  preload: ['rewardFulfillments']
}).then(() => {
  // Customer logged in and preloaded resources successfully
});
```

--------------------------------

### Get Customer Points Products using JavaScript

Source: https://dev.smile.io/js/resources/customer-points-products/get

The `Smile.customerPointsProducts.get()` asynchronous method retrieves a list of available redemption options for the currently logged-in customer. It always makes an API call to fetch the latest data. The method returns a Promise that resolves with an array of customer points product objects or rejects with an error object.

```javascript
Smile.customerPointsProducts.get().then(
  (customerPointsProducts) => {
    // Handle the customer points product
    // collection
  }
);
```

--------------------------------

### GET /points_transactions/{id}

Source: https://dev.smile.io/api/resources/points-transactions/retrieve-points-transaction

Retrieves a single points transaction by its unique identifier. This endpoint is part of the Points Transactions API.

```APIDOC
## GET /points_transactions/{id}

### Description
Retrieves a single points transaction by ID.

### Method
GET

### Endpoint
/points_transactions/{id}

#### Path Parameters
- **id** (integer) - Required - ID of the points transaction to retrieve.

### Response
#### Success Response (200)
- **points_transaction** (object) - Contains details of the points transaction.
  - **id** (integer) - Unique identifier for the points transaction.
  - **customer_id** (integer) - The ID of the customer whose balance this points transaction applies to.
  - **points_change** (integer) - The number of points added or removed from the customer's points balance.
  - **description** (string) - A message visible to the customer that describes the reason for the points change.
  - **internal_note** (string) - A note that is visible to the merchant.
  - **created_at** (string) - The date and time when the points transaction was created.
  - **updated_at** (string) - The date and time when the points transaction was last updated.

#### Response Example
```json
{
  "points_transaction": {
    "id": 825673452,
    "customer_id": 304169228,
    "points_change": 100,
    "description": "Points correction",
    "internal_note": "Due to issue with order #6834",
    "created_at": "2024-12-07T20:15:27.893Z",
    "updated_at": "2024-12-07T20:15:27.893Z"
  }
}
```
```

--------------------------------

### Replace SmileUI.customerReady() for SmileUI methods

Source: https://dev.smile.io/guides/use-cases/custom-frontend/js-sdk-migration

Replaces the deprecated `SmileUI.customerReady()` method with `SmileUI.ready()` to ensure it's safe to call other `SmileUI.*` methods. This is typically used when programmatically opening the loyalty panel or launcher.

```javascript
SmileUI.customerReady().then(() => { // [!code --]
SmileUI.ready().then(() => { // [!code ++]
  // Safe to call SmileUI.* methods
});
```

--------------------------------

### Get Points Products

Source: https://dev.smile.io/js/resources/points-products/get

Retrieves a list of all available points products. This method makes an API call to fetch the most up-to-date information.

```APIDOC
## GET /points_products

### Description
Retrieves a list of all available points products. This method makes an API call to fetch the most up-to-date information.

### Method
GET

### Endpoint
/points_products

### Parameters
#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **pointsProducts** (array) - An array of points product objects. Returns an empty array if no points products are defined.

#### Response Example
```json
{
  "pointsProducts": [
    {
      "id": "prod_123",
      "name": "Basic Points Package",
      "points_value": 100,
      "price": {
        "amount": 10.00,
        "currency": "USD"
      }
    }
  ]
}
```

#### Error Response
- **error** (object) - An error object detailing the issue.

#### Error Response Example
```json
{
  "error": {
    "code": "API_ERROR",
    "message": "Failed to fetch points products."
  }
}
```
```

--------------------------------

### GET /earning_rules

Source: https://dev.smile.io/api/resources/earning-rules/list-earning-rules

Retrieves a list of enabled earning rules. This endpoint allows you to fetch earning rules with optional pagination.

```APIDOC
## GET /earning_rules

### Description
Retrieves a list of enabled earning rules. This endpoint allows you to fetch earning rules with optional pagination.

### Method
GET

### Endpoint
https://api.smile.io/v1/earning_rules

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - The maximum number of earning rules to retrieve. Defaults to 50. Minimum 1, Maximum 250.
- **cursor** (string) - Optional - Cursor for the page of earning rules to retrieve.

### Request Example
```json
{
  "example": "No request body for GET request"
}
```

### Response
#### Success Response (200)
- **earning_rules** (array) - A list of earning rule objects.
- **metadata** (object) - Pagination metadata.

##### EarningRule Object
- **id** (integer) - Unique identifier for the earning rule.
- **name** (string) - The display name of the earning rule.
- **image_url** (string) - The image of the earning rule.
- **action_text** (string) - The label for a clickable element (e.g. a call to action) that allows the customer to complete the rewardable action. When `null`, no clickable element should be displayed.
- **action_url** (string) - The destination URL for a clickable element (e.g. a call to action) that allows the customer to complete the rewardable action. When `null`, no clickable element should be displayed.
- **restricted_to_vip_tier_ids** (array) - A list of VIP tier IDs. When present, the earning rule only applies to customers who currently belong to at least one of the specified VIP tiers. If empty, the earning rule applies to all VIP tiers.
- **reward** (object) - The reward that will be issued to the customer when the rewardable action is completed.
  - **type** (string) - Enum: "points" - The type of reward that will be issued.
- **reward_value** (object) - The configuration for the reward's value.
  - **type** (string) - Enum: "variable", "fixed" - The way that the reward's value will be computed.
  - **variable** (object) - Configuration for variable reward value (e.g. points per dollar spent). Only present when type is `variable`.
    - **value** (number) - The amount of reward value issued per unit.
    - **per_amount** (number) - The amount of action needed to earn the specified value.
  - **fixed** (object) - Configuration for fixed reward value. Only present when type is `fixed`.
    - **value** (number) - The value of the reward that will be issued.

#### Response Example
```json
{
  "earning_rules": [
    {
      "id": 739246764,
      "name": "Place an order",
      "image_url": "https://platform.smile.io/images/earning/order-online.svg",
      "action_text": null,
      "action_url": null,
      "restricted_to_vip_tier_ids": [],
      "reward": {
        "type": "points"
      },
      "reward_value": {
        "type": "variable",
        "variable": {
          "value": 5.0,
          "per_amount": 1.0
        }
      }
    }
  ],
  "metadata": {
    "pagination": {
      "next_url": "https://api.smile.io/v1/earning_rules?limit=50&cursor=some_cursor_string"
    }
  }
}
```
```

--------------------------------

### Cursor Pagination Overview

Source: https://dev.smile.io/api/pagination/cursor-pagination

This section explains the concept of cursor-based pagination, how cursors work, and how to use them to navigate through collections. It details the structure of the metadata hash in responses, including `next_cursor` and `previous_cursor`.

```APIDOC
## Cursor Pagination

### Description

A cursor is an opaque string representing your current place within a collection. When making a request to an endpoint that supports cursor-based pagination, the response will include a `metadata` hash containing the cursors required to move forward or backward within the collection.

If a next page is available, the metadata hash will contain a non-null `next_cursor` value. If a previous page is available, the `metadata` hash will contain a non-null `previous_cursor` value. By passing either of these values as the `cursor` argument of a subsequent request, you can retrieve the next or previous page of objects.

**Note:** When paginating using cursors, results are always returned in reverse chronological order (with the most recently created first).

### Response Example (Pagination Metadata)

```json
{
  "customers": [],
  "metadata": {
    "next_cursor": "aWQ6MixkaXJlY3Rpb246bmV4dA==",
    "previous_cursor": null
  }
}
```

### Query Parameters (for paginated requests)

- **cursor** (string) - Optional - The cursor value obtained from a previous response to fetch the next or previous page of results.
```

--------------------------------

### GET /points_transactions

Source: https://dev.smile.io/api/resources/points-transactions/list-points-transactions

Retrieves a list of points transactions. This endpoint allows filtering by customer ID, update time, and pagination.

```APIDOC
## GET /points_transactions

### Description
Retrieves a list of points transactions. This endpoint allows filtering by customer ID, update time, and pagination.

### Method
GET

### Endpoint
https://api.smile.io/v1/points_transactions

### Parameters
#### Query Parameters
- **customer_id** (string) - Optional - Filter results to only points transactions with the provided Smile customer ID.
- **updated_at_min** (string) - Optional - Filter results to only points transactions updated at or after the provided date and time. (format: date-time)
- **limit** (integer) - Optional - The maximum number of points transactions to retrieve. (default: 50, min: 1, max: 250)
- **cursor** (string) - Optional - Cursor for the page of points transactions to retrieve.

### Request Example
```json
{
  "example": ""
}
```

### Response
#### Success Response (200)
- **points_transactions** (array) - A list of points transaction objects.
- **metadata** (object) - Pagination metadata including next and previous cursors.

#### Response Example
```json
{
  "points_transactions": [
    {
      "id": 825673452,
      "customer_id": 304169228,
      "points_change": 100,
      "description": "Points correction",
      "internal_note": "Due to issue with order #6834",
      "created_at": "2024-12-07T20:15:27.893Z",
      "updated_at": "2024-12-07T20:15:27.893Z"
    }
  ],
  "metadata": {
    "next_cursor": "aWQ6MixkaXJlY3Rpb246bmV4dA==",
    "previous_cursor": ""
  }
}
```
```

--------------------------------

### Initialize Smile UI with Customer Data (JavaScript)

Source: https://dev.smile.io/ui/initializing

Initializes Smile UI with store identification and customer details. This method is essential before using other Smile UI functionalities. It supports both synchronous and asynchronous script loading scenarios.

```javascript
SmileUI.initialize({
  publishableKey: "pub_0987654321",
  customerToken:
    "eyJhbGciOiJIUzI1NiJ9.eyJjdXN0b21lcl9pZGVudGl0eSI6eyJkaXN0aW5jdF9pZCI6IjEwMCJ9LCJleHAiOjE1ODU1OTE1MzZ9.PGJhiM0NYRok5VGAlAOT6F-57gu7SCBaennQbt6YrqU",
});
```

```javascript
document.addEventListener("smile-ui-loaded", () => {
  SmileUI.initialize({
    publishableKey: "pub_0987654321",
    customerToken:
      "eyJhbGciOiJIUzI1NiJ9.eyJjdXN0b21lcl9pZGVudGl0eSI6eyJkaXN0aW5jdF9pZCI6IjEwMCJ9LCJleHAiOjE1ODU1OTE1MzZ9.PGJhiM0NYRok5VGAlAOT6F-57gu7SCBaennQbt6YrqU",
  });
});
```

--------------------------------

### GET /customers/{id}

Source: https://dev.smile.io/api/resources/customers/retrieve-a-customer

Retrieves a single customer by their unique ID. You can optionally include related objects like VIP status in the response.

```APIDOC
## GET /customers/{id}

### Description
Retrieves a single customer by ID. Optionally include related objects like VIP status.

### Method
GET

### Endpoint
https://api.smile.io/v1/customers/{id}

### Parameters
#### Path Parameters
- **id** (integer) - Required - ID of the customer (in Smile) to retrieve.

#### Query Parameters
- **include** (string) - Optional - A comma-separated list of related objects to include in the response. Possible values: `vip_status`, `vip_status.vip_tier`, `vip_status.next_vip_tier`.

### Request Example
```json
{
  "example": "GET /v1/customers/304169228?include=vip_status"
}
```

### Response
#### Success Response (200)
- **customer** (object) - Contains the customer details.
  - **id** (integer) - Unique identifier for the customer in Smile.
  - **first_name** (string) - The customer's first name.
  - **last_name** (string) - The customer's last name.
  - **email** (string) - The customer's email address.
  - **state** (string) - The customer's state in the loyalty program (e.g., `candidate`, `member`, `disabled`).
  - **date_of_birth** (string) - The customer's birthday (format: `YYYY-MM-DD`).
  - **points_balance** (integer) - The customer's current points balance.
  - **referral_url** (string) - The customer's unique referral URL.
  - **vip_status** (object) - Information about the customer's VIP status.
    - **vip_tier_id** (integer) - The ID of the customer's current VIP tier.
    - **vip_tier_expires_at** (string) - The date the customer's current VIP tier expires (format: `date-time`).
    - **progress_value** (number) - The amount spent or earned within the current VIP period.
    - **current_vip_period_end** (string) - The end date for the current VIP period (format: `date-time`).
    - **delta_to_retain_vip_tier** (number) - Additional amount needed to retain VIP tier.
    - **next_vip_tier_id** (integer) - The ID of the next VIP tier.

#### Response Example
```json
{
  "example": {
    "customer": {
      "id": 304169228,
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "jane@doe.com",
      "state": "member",
      "date_of_birth": "1004-05-27",
      "points_balance": 300,
      "referral_url": "http://i.refs.cc/9qr5Pw",
      "vip_status": {
        "vip_tier_id": 426715794,
        "vip_tier_expires_at": "2026-12-31T23:59:59.999Z",
        "progress_value": 300,
        "current_vip_period_end": "2025-12-31T23:59:59.999Z",
        "delta_to_retain_vip_tier": null,
        "next_vip_tier_id": 426715799
      }
    }
  }
}
```
```

--------------------------------

### SmileUI.initialize()

Source: https://dev.smile.io/js/initializing/initialize-method

Initializes Smile UI with store and customer information. This method must be called before interacting with other Smile UI methods. It supports both synchronous and asynchronous script loading.

```APIDOC
## POST /initialize

### Description
Initializes Smile UI with information about the loyalty program to display and the currently logged in customer. This method must be called before you can interact with any other methods.

### Method
POST

### Endpoint
SmileUI.initialize(options)

### Parameters
#### Request Body
- **options** (object) - Required - Configuration options for initializing Smile UI.
  - **publishableKey** (string) - Required - Your Smile.io publishable key. This is used for identifying your store and can be made public.
  - **customerToken** (string) - Optional - A customer token identifying the currently logged-in customer. This should be `null` or omitted entirely if no customer is currently logged-in.
  - **includeSdk** (boolean) - Optional - Defaults to `false`. Whether to load and initialize Smile’s JavaScript SDK (Smile.js) alongside Smile UI.

### Request Example
```javascript
// Synchronous loading
SmileUI.initialize({
  publishableKey: "pub_0987654321",
  customerToken: "eyJhbGciOiJIUzI1NiJ9.eyJjdXN0b21lcl9pZGVudGl0eSI6eyJkaXN0aW5jdF9pZCI6IjEwMCJ9LCJleHAiOjE1ODU1OTE1MzZ9.PGJhiM0NYRok5VGAlAOT6F-57gu7SCBaennQbt6YrqU"
});

// Asynchronous loading
document.addEventListener("smile-ui-loaded", () => {
  SmileUI.initialize({
    publishableKey: "pub_0987654321",
    customerToken: "eyJhbGciOiJIUzI1NiJ9.eyJjdXN0b21lcl9pZGVudGl0eSI6eyJkaXN0aW5jdF9pZCI6IjEwMCJ9LCJleHAiOjE1ODU1OTE1MzZ9.PGJhiM0NYRok5VGAlAOT6F-57gu7SCBaennQbt6YrqU"
  });
});
```

### Response
#### Success Response (200)
This method does not return a value upon successful initialization.

#### Response Example
N/A
```

--------------------------------

### GET /points_products/{id}

Source: https://dev.smile.io/api/resources/points-products/retrieve-points-product

Retrieves a single points product by its unique identifier. This endpoint is useful for fetching detailed information about a specific points product configuration.

```APIDOC
## GET /points_products/{id}

### Description
Retrieves a single points product by ID.

### Method
GET

### Endpoint
/points_products/{id}

#### Path Parameters
- **id** (integer) - Required - ID of the points product to retrieve.

### Request Example
```json
{
  "example": "No request body needed for GET request."
}
```

### Response
#### Success Response (200)
- **points_product** (object) - Contains the details of the retrieved points product.
  - **id** (integer) - Unique identifier for the points product.
  - **exchange_type** (string) - How points are exchanged for the reward (fixed or variable).
  - **exchange_description** (string) - A human readable description of how a customer spends points on this reward.
  - **points_price** (integer) - Number of points needed to purchase this reward (only when `exchange_type` is `fixed`).
  - **variable_points_step** (integer) - The number of points between each notch on the slider (only when `exchange_type` is `variable`).
  - **variable_points_step_reward_value** (integer) - The corresponding reward value for each step increment on the slider (only when `exchange_type` is `variable`).
  - **variable_points_min** (integer) - The minimum amount of points the customer must spend (only when `exchange_type` is `variable`).
  - **variable_points_max** (integer) - The maximum amount of points the customer must spend (only when `exchange_type` is `variable`).
  - **reward** (object) - A nested Reward object representing the reward issued to the customer.
  - **created_at** (string) - The date and time when the points product was created.
  - **updated_at** (string) - The date and time when the points product was last updated.

#### Response Example
```json
{
  "points_product": {
    "id": 132456921,
    "exchange_type": "variable",
    "exchange_description": "100 Points = $1 off",
    "variable_points_step": 100,
    "variable_points_step_reward_value": 1,
    "variable_points_min": 100,
    "variable_points_max": 5000,
    "reward": {
      "id": 924565472,
      "name": "Order discount",
      "description": "",
      "image_url": "https://platform-images.smilecdn.co/3755938.png",
      "created_at": "2024-04-04T15:10:42.030Z"
    },
    "created_at": "2024-04-04T15:10:42.030Z",
    "updated_at": "2024-04-04T15:10:42.030Z"
  }
}
```
```

--------------------------------

### Smile.fetchAllCustomerPointsProducts() Migration

Source: https://dev.smile.io/guides/use-cases/custom-frontend/js-sdk-migration

Update calls from `Smile.fetchAllCustomerPointsProducts()` to `Smile.customerPointsProducts.get()`.

```APIDOC
## GET /js/resources/customer-points-products/get

### Description
Fetches all available points products for the customer.

### Method
GET

### Endpoint
/js/resources/customer-points-products/get

### Parameters
#### Query Parameters
- **customer_id** (string) - Optional - The ID of the customer. If not provided, the current customer is assumed.

### Response
#### Success Response (200)
- **products** (array) - A list of points products available to the customer.

#### Response Example
```json
{
  "products": [
    {
      "id": "pp_abc",
      "name": "100 Points",
      "points_required": 100
    }
  ]
}
```
```

--------------------------------

### GET /customers/{customerId}/vip-status

Source: https://dev.smile.io/api/resources/customers/list-customers

Retrieves the VIP status for a specific customer. This includes information about their current tier, progress towards the next tier, and expiration dates.

```APIDOC
## GET /customers/{customerId}/vip-status

### Description
Retrieves the VIP status for a specific customer. This includes information about their current tier, progress towards the next tier, and expiration dates.

### Method
GET

### Endpoint
/customers/{customerId}/vip-status

### Parameters
#### Path Parameters
- **customerId** (string) - Required - The unique identifier for the customer.

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **vip_status** (object) - An object containing details about the customer's status within the VIP program.
  - **current_vip_tier_expires_at** (string) - The date the customer's current VIP tier expires. For all-time VIP programs, this will be `null` because tiers do not expire.
  - **progress_value** (number) - The amount the customer has already spent or earned within the current VIP period.
  - **current_vip_period_end** (string) - The end date for the current VIP period. For calendar-year VIP programs, this will be the end of the current calendar year. For all-time VIP programs, this will be `null`.
  - **delta_to_retain_vip_tier** (number) - The additional amount the customer must spend or earn before the end of the current VIP period to retain their VIP tier until the end of the next VIP period. For all-time VIP programs or if the customer has already spent or earned enough this period to retain their current VIP tier, this will be `null`.
  - **next_vip_tier_id** (integer) - The ID of the next VIP tier that the customer will move into if they meet the minimum spending or earning requirement. If the customer is already in the highest tier, this will be `null`.
  - **delta_to_next_vip_tier** (number) - The amount the customer must spend or earn within the current VIP period to reach the next VIP tier. If the customer is already in the highest tier, this will be `null`.
- **created_at** (string) - The date and time when the customer was created.
- **updated_at** (string) - The date and time when the customer was last updated.

#### Response Example
```json
{
  "vip_status": {
    "current_vip_tier_expires_at": "2026-12-31T23:59:59.999Z",
    "progress_value": 300,
    "current_vip_period_end": "2025-12-31T23:59:59.999Z",
    "delta_to_retain_vip_tier": null,
    "next_vip_tier_id": 426715799,
    "delta_to_next_vip_tier": 200
  },
  "created_at": "2024-04-04T15:10:42.030Z",
  "updated_at": "2025-04-04T15:10:42.030Z"
}
```

#### Error Response (404)
- **message** (string) - "Customer not found."

#### Error Response (401)
- **message** (string) - "Unauthorized."
```

--------------------------------

### Initialize Smile.io SDK with Options (JavaScript)

Source: https://dev.smile.io/js/smile/initialize

Initializes the Smile.io SDK using the `Smile.initialize` method. This method requires a `publishableKey` and optionally accepts a `customerToken` and an array of resources to `preload`. It's crucial to ensure the SDK script is loaded before calling initialize, especially when loading asynchronously, by using a 'smile-js-loaded' event listener.

```javascript
Smile.initialize({
  publishableKey: 'pub_0987654321',
  customerToken: 'eyJhbGciOiJIUzI1NiJ9.eyJjdXN0b21lcl9pZGVudGl0eSI6eyJkaXN0aW5jdF9pZCI6IjEwMCJ9LCJleHAiOjE1ODU1OTE1MzZ9.PGJhiM0NYRok5VGAlAOT6F-57gu7SCBaennQbt6YrqU',
  preload: ['pointsSettings']
});

document.addEventListener('smile-js-loaded', () => {
  Smile.initialize({
    publishableKey: 'pub_0987654321',
    customerToken: 'eyJhbGciOiJIUzI1NiJ9.eyJjdXN0b21lcl9pZGVudGl0eSI6eyJkaXN0aW5jdF9pZCI6IjEwMCJ9LCJleHAiOjE1ODU1OTE1MzZ9.PGJhiM0NYRok5VGAlAOT6F-57gu7SCBaennQbt6YrqU',
    preload: ['pointsSettings']
  });
});
```

--------------------------------

### GET /customers

Source: https://dev.smile.io/api/resources/customers/list-customers

Retrieves a list of customers based on a set of provided filters. This endpoint allows for filtering by email, state, update time, and inclusion of related objects.

```APIDOC
## GET /customers

### Description
Retrieves a list of customers based on a set of provided filters.

### Method
GET

### Endpoint
/customers

### Parameters
#### Query Parameters
- **email** (string) - Optional - Filter results to only customers with the provided email address.
- **state** (string) - Optional - Filter results to only customers with the provided state. Allowed values: `candidate`, `member`, `disabled`.
- **updated_at_min** (string) - Optional - Filter results to only customers updated after the provided date and time. Format: `date-time`. Example: `2024-04-04T15:10:42.030Z`.
- **limit** (integer) - Optional - The maximum number of customers to retrieve. Minimum: 1, Maximum: 250, Default: 50.
- **cursor** (string) - Optional - Cursor for the page of customers to be retrieved.
- **include** (string) - Optional - A comma-separated list of related objects to include in the response. Allowed values: `vip_status`.

### Request Example
```json
{
  "example": "No request body for GET requests"
}
```

### Response
#### Success Response (200)
- **customers** (array) - A list of customer objects.
- **metadata** (object) - Pagination metadata.

#### Response Example
```json
{
  "customers": [
    {
      "id": 304169228,
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "jane@doe.com",
      "state": "member",
      "date_of_birth": "1004-05-27",
      "points_balance": 300,
      "referral_url": "http://i.refs.cc/9qr5Pw",
      "vip_tier_id": 426715794, 
      "vip_status": {
        "vip_tier_id": 426715794,
        "vip_tier_expires_at": "2025-12-31T23:59:59.000Z"
      }
    }
  ],
  "metadata": {
    "next_cursor": "some_cursor_string"
  }
}
```
```

--------------------------------

### Initialize Smile UI (JavaScript)

Source: https://dev.smile.io/js/initializing/initialize-method

Initializes Smile UI with provided options. Handles both synchronous and asynchronous script loading by using a `smile-ui-loaded` event listener for asynchronous loading. Requires a `publishableKey` and optionally accepts a `customerToken`.

```javascript
// If the script is loaded synchronously
SmileUI.initialize({
  publishableKey: "pub_0987654321",
  customerToken:
    "eyJhbGciOiJIUzI1NiJ9.eyJjdXN0b21lcl9pZGVudGl0eSI6eyJkaXN0aW5jdF9pZCI6IjEwMCJ9LCJleHAiOjE1ODU1OTE1MzZ9.PGJhiM0NYRok5VGAlAOT6F-57gu7SCBaennQbt6YrqU",
});

// If the script is loaded asynchronously
document.addEventListener("smile-ui-loaded", () => {
  SmileUI.initialize({
    publishableKey: "pub_0987654321",
    customerToken:
      "eyJhbGciOiJIUzI1NiJ9.eyJjdXN0b21lcl9pZGVudGl0eSI6eyJkaXN0aW5jdF9pZCI6IjEwMCJ9LCJleHAiOjE1ODU1OTE1MzZ9.PGJhiM0NYRok5VGAlAOT6F-57gu7SCBaennQbt6YrqU",
  });
});

```

--------------------------------

### Initialize Smile UI with SDK Inclusion (JavaScript)

Source: https://dev.smile.io/guides/use-cases/custom-frontend/js-sdk-migration

This code snippet demonstrates how to initialize the Smile UI with the `includeSdk: true` parameter, which is necessary for custom storefronts that want to continue using the rewards panel and launcher while integrating the new JavaScript SDK.

```javascript
SmileUI.initialize({
  publishableKey: "pub_0987654321",
  customerToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  includeSdk: true // [!code ++]
});
```