# Smile.io Developer Documentation

> Documentation and guides for using Smile's full-stack developer tooling, including the REST API and JavaScript SDK.

## Docs

- [Authentication](https://dev.smile.io/api/authentication.md): Learn how to authenticate Smile REST API requests with an API key or OAuth access token.
- [Errors](https://dev.smile.io/api/errors.md): Learn how the Smile REST API uses HTTP response codes and error objects to report failed requests.
- [Introduction](https://dev.smile.io/api/introduction.md): An overview of the Smile REST API, including its conventions and base URL.
- [Classic pagination](https://dev.smile.io/api/pagination/classic-pagination.md): Learn how to page through Smile REST API results using page numbers.
- [Cursor pagination](https://dev.smile.io/api/pagination/cursor-pagination.md): Learn how to page through Smile REST API results using cursors.
- [Rate limits](https://dev.smile.io/api/rate-limits.md): Learn about Smile REST API rate limits and how to avoid HTTP 429 errors.
- [Activity object](https://dev.smile.io/api/resources/activities/activity-object.md): Reference for the activity object in the Smile REST API.
- [Create an activity](https://dev.smile.io/api/resources/activities/create-activity.md): Create an activity in the Smile REST API to record a customer action and trigger reward evaluation.
- [Create or update a customer identity](https://dev.smile.io/api/resources/customer-identities/create-or-update-identity.md): Create or update a customer identity in the Smile REST API to link an external system's records to Smile customers.
- [Customer Identity object](https://dev.smile.io/api/resources/customer-identities/customer-identity-object.md): Reference for the customer identity object in the Smile REST API.
- [Customer object](https://dev.smile.io/api/resources/customers/customer-object.md): Reference for the customer object in the Smile REST API.
- [List customers](https://dev.smile.io/api/resources/customers/list-customers.md): Retrieve a paginated list of customers in the Smile REST API, with optional lookup by email.
- [Retrieve a customer](https://dev.smile.io/api/resources/customers/retrieve-a-customer.md): Retrieve a single customer by ID in the Smile REST API.
- [Earning Rule object](https://dev.smile.io/api/resources/earning-rules/earning-rule-object.md): Reference for the earning rule object in the Smile REST API.
- [List earning rules](https://dev.smile.io/api/resources/earning-rules/list-earning-rules.md): Retrieve a list of earning rules in the Smile REST API.
- [List points products](https://dev.smile.io/api/resources/points-products/list-points-products.md): Retrieve a list of points products in the Smile REST API.
- [Points Product object](https://dev.smile.io/api/resources/points-products/points-product-object.md): Reference for the points product object in the Smile REST API.
- [Purchase a points product](https://dev.smile.io/api/resources/points-products/purchase-points-product.md): Purchase a points product on behalf of a customer in the Smile REST API.
- [Retrieve a points product](https://dev.smile.io/api/resources/points-products/retrieve-points-product.md): Retrieve a single points product by ID in the Smile REST API.
- [Points Purchase object](https://dev.smile.io/api/resources/points-purchases/points-purchase-object.md): Reference for the points purchase object in the Smile REST API.
- [Get points settings](https://dev.smile.io/api/resources/points-settings/get-points-settings.md): Retrieve an account's points program settings in the Smile REST API.
- [Points Settings object](https://dev.smile.io/api/resources/points-settings/points-settings-object.md): Reference for the points settings object in the Smile REST API.
- [Create a points transaction](https://dev.smile.io/api/resources/points-transactions/create-points-transaction.md): Create a points transaction to add or deduct points from a customer's points balance in the Smile REST API.
- [List points transactions](https://dev.smile.io/api/resources/points-transactions/list-points-transactions.md): Retrieve a list of points transactions in the Smile REST API, such as a customer's points earning history.
- [Points Transaction object](https://dev.smile.io/api/resources/points-transactions/points-transaction-object.md): Reference for the points transaction object in the Smile REST API.
- [Retrieve a points transaction](https://dev.smile.io/api/resources/points-transactions/retrieve-points-transaction.md): Retrieve a single points transaction by ID in the Smile REST API.
- [Referral object](https://dev.smile.io/api/resources/referrals/referral-object.md): Reference for the referral object in the Smile REST API.
- [List reward fulfillments](https://dev.smile.io/api/resources/reward-fulfillments/list-reward-fulfillments.md): Retrieve a list of reward fulfillments in the Smile REST API, such as a customer's discount codes.
- [Reward Fulfillment object](https://dev.smile.io/api/resources/reward-fulfillments/reward-fulfillment-object.md): Reference for the reward fulfillment object in the Smile REST API.
- [Reward object](https://dev.smile.io/api/resources/rewards/reward-object.md): Reference for the reward object in the Smile REST API.
- [VIP Tier Change object](https://dev.smile.io/api/resources/vip-tier-changes/vip-tier-change-object.md): Reference for the VIP tier change object in the Smile REST API.
- [List VIP tiers](https://dev.smile.io/api/resources/vip-tiers/list-vip-tiers.md): Retrieve a list of VIP tiers in the Smile REST API, sorted by milestone.
- [VIP Tier object](https://dev.smile.io/api/resources/vip-tiers/vip-tier-object.md): Reference for the VIP tier object in the Smile REST API.
- [Activities](https://dev.smile.io/guides/apps/activities.md): Learn how your app can define activity types and create activities so Smile rewards customers automatically.
- [Access scopes](https://dev.smile.io/guides/apps/auth/access-scopes.md): Learn how access scopes control which resources your app can read and write, and how to add new scopes.
- [OAuth errors](https://dev.smile.io/guides/apps/auth/oauth-errors.md): Understand the error codes returned during Smile's OAuth flow and what to do when they happen.
- [OAuth flow](https://dev.smile.io/guides/apps/auth/oauth-flow.md): Connect and authorize your app with Smile's OAuth 2.0 flow to get credentials for making API calls.
- [Client secret rotation](https://dev.smile.io/guides/apps/auth/oauth-rotation.md): Rotate your app's client secret with zero downtime if it's ever compromised or exposed.
- [App authorization](https://dev.smile.io/guides/apps/auth/overview.md): Learn how apps use OAuth to get authorized and make API calls on behalf of a merchant's Smile account.
- [Build an app](https://dev.smile.io/guides/apps/build.md): Learn how to build an app and get it launched.
- [Integration methods](https://dev.smile.io/guides/apps/integrate.md): Learn about the different ways to integrate with Smile.
- [Use merchant credentials](https://dev.smile.io/guides/apps/merchant-credentials.md): Learn how to use merchant credentials to integrate with Smile.
- [Migrate from API keys to OAuth](https://dev.smile.io/guides/apps/migrate-to-oauth.md): Migrate your legacy integration from using merchant credentials (API keys) to using modern OAuth instead.
- [App submission process](https://dev.smile.io/guides/apps/submission/process.md): Learn how to submit your app for review and get it listed in Smile Admin.
- [App requirements](https://dev.smile.io/guides/apps/submission/requirements.md): Review the requirements your app must meet to be listed and available for installation by merchants.
- [Webhooks](https://dev.smile.io/guides/apps/webhooks.md): Apps can subscribe to webhook topics to receive notifications when events occur within Smile.
- [Example usage](https://dev.smile.io/guides/deprecated/custom-html-emails/custom-email-examples.md): Example custom email templates that show how to use handlebar variables to create dynamic content.
- [Object reference](https://dev.smile.io/guides/deprecated/custom-html-emails/custom-email-objects.md): Reference for the objects available in Smile's custom HTML email notification templates.
- [Handlebar variables](https://dev.smile.io/guides/deprecated/custom-html-emails/custom-email-variables.md): Reference for the handlebar variables available in each of Smile's email notification types.
- [Overview](https://dev.smile.io/guides/deprecated/custom-html-emails/overview.md): Build custom HTML email templates with handlebar variables. Deprecated and maintained as a reference only.
- [Customer deleted](https://dev.smile.io/guides/deprecated/custom-platform/custom-backend-int/custom-customer-events/custom-customer-deleted.md): Send this event to Smile any time a customer is deleted in your ecommerce system.
- [Customer object](https://dev.smile.io/guides/deprecated/custom-platform/custom-backend-int/custom-customer-events/custom-customer-object.md): Reference for the fields used to represent a customer when sending customer events to Smile.
- [Customer updated](https://dev.smile.io/guides/deprecated/custom-platform/custom-backend-int/custom-customer-events/custom-customer-updated.md): Send this event to Smile any time a customer is created or updated in your ecommerce system.
- [Overview](https://dev.smile.io/guides/deprecated/custom-platform/custom-backend-int/custom-customer-events/overview.md): Learn how customer events keep Smile informed of changes to customer information in your ecommerce system.
- [Order deleted](https://dev.smile.io/guides/deprecated/custom-platform/custom-backend-int/custom-order-events/custom-order-deleted.md): Send this event to Smile any time an order is deleted in your ecommerce system.
- [Order object](https://dev.smile.io/guides/deprecated/custom-platform/custom-backend-int/custom-order-events/custom-order-object.md): Reference for the fields used to represent an order when sending order events to Smile.
- [Order updated](https://dev.smile.io/guides/deprecated/custom-platform/custom-backend-int/custom-order-events/custom-order-updated.md): Send this event to Smile any time an order is created or updated in your ecommerce system.
- [Overview](https://dev.smile.io/guides/deprecated/custom-platform/custom-backend-int/custom-order-events/overview.md): Learn how order events keep Smile informed of order activity within your ecommerce system.
- [Overview](https://dev.smile.io/guides/deprecated/custom-platform/custom-backend-int/overview.md): Send customer and order events to Smile from your backend so Smile can issue rewards.
- [FAQ](https://dev.smile.io/guides/deprecated/custom-platform/custom-faq.md): Answers to common questions about building a custom ecommerce platform integration with Smile.
- [Points at checkout](https://dev.smile.io/guides/deprecated/custom-platform/custom-frontend-int/custom-points-at-checkout.md): Add a points redemption dropdown to your custom platform checkout so customers can spend points seamlessly.
- [Overview](https://dev.smile.io/guides/deprecated/custom-platform/custom-frontend-int/overview.md): Add Smile to your custom platform website using the JavaScript SDK or Smile UI.
- [Overview](https://dev.smile.io/guides/deprecated/custom-platform/overview.md): Integrate a custom ecommerce platform with Smile using our API-based solution. Deprecated for new integrations.
- [Concepts & fundamentals](https://dev.smile.io/guides/fundamentals.md): Learn the core concepts and building blocks of Smile's system.
- [Introduction](https://dev.smile.io/guides/introduction.md): Smile's developer platform enables you to create custom loyalty solutions that meet the needs of merchants, regardless of industry or specialization.
- [Common use cases](https://dev.smile.io/guides/use-cases/common.md): Explore common implementation patterns and real-world examples to jump-start development.
- [Add Smile to your frontend](https://dev.smile.io/guides/use-cases/custom-frontend.md): Embed loyalty functionality into any website or custom storefront using Smile's JavaScript SDK, Smile UI, or both.
- [Headless / Single Page Applications](https://dev.smile.io/guides/use-cases/custom-frontend/headless.md): Add Smile to any headless or SPA frontend using the JavaScript SDK or Smile UI.
- [Shopify Hydrogen](https://dev.smile.io/guides/use-cases/custom-frontend/hydrogen.md): Add Smile to a Shopify Hydrogen storefront using the JavaScript SDK or Smile UI.
- [Migrate to the JavaScript SDK](https://dev.smile.io/guides/use-cases/custom-frontend/js-sdk-migration.md): Migrate to using the new JavaScript SDK instead of the old `Smile.*` methods bundled with Smile UI.
- [BigCommerce Stencil](https://dev.smile.io/guides/use-cases/landing-page/bigcommerce-stencil.md): Use Smile's explainer page template to add a loyalty landing page to a BigCommerce Stencil theme.
- [Overview](https://dev.smile.io/guides/use-cases/landing-page/overview.md): Create a loyalty landing page that explains your program and encourages customers to signup and participate.
- [BigCommerce dropdown](https://dev.smile.io/guides/use-cases/points-at-checkout/bigc-points-dropdown.md): Add a dropdown of redemption options to your BigCommerce checkout so customers can redeem points for rewards.
- [BigCommerce slider](https://dev.smile.io/guides/use-cases/points-at-checkout/bigc-points-slider.md): Add a points slider to your BigCommerce checkout so customers can redeem points for a discount in increments.
- [Overview](https://dev.smile.io/guides/use-cases/points-at-checkout/overview.md): Let customers redeem points directly at checkout with a dropdown or slider on Shopify or BigCommerce.
- [Reward for any action](https://dev.smile.io/guides/use-cases/rewarding-for-any-action.md): Reward customers for custom actions unique to your brand using custom activity types and the Smile API.
- [Home](https://dev.smile.io/index.md): Build custom loyalty experiences with Smile's REST API, JavaScript SDK, and Smile UI.
- [Customer tokens](https://dev.smile.io/js/concepts/customer-tokens.md): Learn how to generate the JWT customer tokens Smile.js uses to identify logged-in customers.
- [Error handling](https://dev.smile.io/js/concepts/error-handling.md): Learn how to detect and handle warnings, unexpected errors, and API errors thrown by the JavaScript SDK.
- [ApiError object](https://dev.smile.io/js/concepts/error-object.md): The error object thrown by the JavaScript SDK when a problem occurs while communicating with Smile's API.
- [Initialized event](https://dev.smile.io/js/concepts/initialized-event.md): `smile-js-initialized`
- [Lifecycle events](https://dev.smile.io/js/concepts/lifecycle-events.md): Learn about the events the JavaScript SDK dispatches during its setup, from script load to initialization.
- [Loaded event](https://dev.smile.io/js/concepts/loaded-event.md): `smile-js-loaded`
- [Preloading resources](https://dev.smile.io/js/concepts/preloading.md): Learn how to fetch and cache multiple Smile API resources in a single call for better performance.
- [Versioning](https://dev.smile.io/js/concepts/versioning.md): Learn how versioning works in the JavaScript SDK and when you need to update your integration.
- [Including Smile.js](https://dev.smile.io/js/including.md): Learn how to include the Smile JavaScript SDK on your site with a script tag or the npm package.
- [Introduction](https://dev.smile.io/js/introduction.md): Build fully custom rewards and loyalty experiences with Smile.js, Smile's frontend JavaScript SDK.
- [Create an activity](https://dev.smile.io/js/resources/activities/create.md): `Smile.activities.create(activityAttributes)`
- [Activity object](https://dev.smile.io/js/resources/activities/object.md): Reference for the activity object in the JavaScript SDK.
- [Get customer points products](https://dev.smile.io/js/resources/customer-points-products/get.md): `Smile.customerPointsProducts.get()`
- [Customer Points Product object](https://dev.smile.io/js/resources/customer-points-products/object.md): Reference for the customer points product object in the JavaScript SDK.
- [Preloaded customer points products](https://dev.smile.io/js/resources/customer-points-products/preloaded.md): `Smile.customerPointsProducts.preloaded()`
- [Get customer points wallet](https://dev.smile.io/js/resources/customer-points-wallet/get.md): `Smile.customerPointsWallet.get()`
- [Customer Points Wallet object](https://dev.smile.io/js/resources/customer-points-wallet/object.md): Reference for the customer points wallet object in the JavaScript SDK.
- [Preloaded customer points wallet](https://dev.smile.io/js/resources/customer-points-wallet/preloaded.md): `Smile.customerPointsWallet.preloaded()`
- [Get customer VIP status](https://dev.smile.io/js/resources/customer-vip-status/get.md): `Smile.customerVipStatus.get()`
- [Customer VIP Status object](https://dev.smile.io/js/resources/customer-vip-status/object.md): Reference for the customer VIP status object in the JavaScript SDK.
- [Preloaded customer VIP status](https://dev.smile.io/js/resources/customer-vip-status/preloaded.md): `Smile.customerVipStatus.preloaded()`
- [Get current customer](https://dev.smile.io/js/resources/customer/current.md): `Smile.customer.current()`
- [Login the customer](https://dev.smile.io/js/resources/customer/login.md): `Smile.customer.login(customerToken, options?)`
- [Logout the customer](https://dev.smile.io/js/resources/customer/logout.md): `Smile.customer.logout()`
- [Customer object](https://dev.smile.io/js/resources/customer/object.md): Reference for the customer object in the JavaScript SDK.
- [Get earning rules](https://dev.smile.io/js/resources/earning-rules/get.md): `Smile.earningRules.get()`
- [Earning Rule object](https://dev.smile.io/js/resources/earning-rules/object.md): Reference for the earning rule object in the JavaScript SDK.
- [Preloaded earning rules](https://dev.smile.io/js/resources/earning-rules/preloaded.md): `Smile.earningRules.preloaded()`
- [Get points products](https://dev.smile.io/js/resources/points-products/get.md): `Smile.pointsProducts.get()`
- [Get a points product](https://dev.smile.io/js/resources/points-products/get-by-id.md): `Smile.pointsProducts.getById(id)`
- [Points Product object](https://dev.smile.io/js/resources/points-products/object.md): Reference for the points product object in the JavaScript SDK.
- [Preloaded points products](https://dev.smile.io/js/resources/points-products/preloaded.md): `Smile.pointsProducts.preloaded()`
- [Purchase a points product](https://dev.smile.io/js/resources/points-products/purchase.md): `Smile.pointsProducts.purchase(id, options?)`
- [Points Purchase object](https://dev.smile.io/js/resources/points-purchases/object.md): Reference for the points purchase object in the JavaScript SDK.
- [Get points settings](https://dev.smile.io/js/resources/points-settings/get.md): `Smile.pointsSettings.get()`
- [Points Settings object](https://dev.smile.io/js/resources/points-settings/object.md): Reference for the points settings object in the JavaScript SDK.
- [Preloaded points settings](https://dev.smile.io/js/resources/points-settings/preloaded.md): `Smile.pointsSettings.preloaded()`
- [Get referral settings](https://dev.smile.io/js/resources/referral-settings/get.md): `Smile.referralSettings.get()`
- [Referral Settings object](https://dev.smile.io/js/resources/referral-settings/object.md): Reference for the referral settings object in the JavaScript SDK.
- [Preloaded referral settings](https://dev.smile.io/js/resources/referral-settings/preloaded.md): `Smile.referralSettings.preloaded()`
- [Get reward fulfillments](https://dev.smile.io/js/resources/reward-fulfillments/get.md): `Smile.rewardFulfillments.get()`
- [Reward Fulfillment object](https://dev.smile.io/js/resources/reward-fulfillments/object.md): Reference for the reward fulfillment object in the JavaScript SDK.
- [Preloaded reward fulfillments](https://dev.smile.io/js/resources/reward-fulfillments/preloaded.md): `Smile.rewardFulfillments.preloaded()`
- [Reward object](https://dev.smile.io/js/resources/rewards/object.md): Reference for the reward object in the JavaScript SDK.
- [Get VIP tiers](https://dev.smile.io/js/resources/vip-tiers/get.md): `Smile.vipTiers.get()`
- [Get a VIP tier](https://dev.smile.io/js/resources/vip-tiers/get-by-id.md): `Smile.vipTiers.getById(id)`
- [VIP Tier object](https://dev.smile.io/js/resources/vip-tiers/object.md): Reference for the VIP tier object in the JavaScript SDK.
- [Preloaded VIP tiers](https://dev.smile.io/js/resources/vip-tiers/preloaded.md): `Smile.vipTiers.preloaded()`
- [Format points](https://dev.smile.io/js/smile/format-points.md): `Smile.formatPoints(pointsAmount, options?)`
- [Initialize the SDK](https://dev.smile.io/js/smile/initialize.md): `Smile.initialize(options)`
- [Preload resources](https://dev.smile.io/js/smile/preload.md): `Smile.preload(resources)`
- [Reset the SDK](https://dev.smile.io/js/smile/reset.md): `Smile.reset()`
- [Customer tokens](https://dev.smile.io/ui/customer-tokens.md): Generate customer tokens (JWTs) to securely identify the logged-in customer when initializing Smile UI.
- [Customer ready method](https://dev.smile.io/ui/events/customer-ready.md): `SmileUI.customerReady()`
- [Loaded event](https://dev.smile.io/ui/events/ui-loaded.md): `window.SmileUI`
- [Ready method](https://dev.smile.io/ui/events/ui-ready.md): `SmileUI.ready()`
- [Including Smile UI](https://dev.smile.io/ui/including.md): Add the Smile UI script tag to your site to load the loyalty panel and launcher.
- [Initializing Smile UI](https://dev.smile.io/ui/initializing.md): `SmileUI.initialize(options)`
- [Introduction](https://dev.smile.io/ui/introduction.md): Smile UI is Smile's pre-built loyalty panel and launcher, giving customers access to your loyalty program.
- [Activity object](https://dev.smile.io/ui/objects/activity.md): An action performed by a customer in the loyalty program.
- [Customer object](https://dev.smile.io/ui/objects/customer.md): An individual in the loyalty program who can earn points and redeem them for rewards.
- [Customer points product object](https://dev.smile.io/ui/objects/customer-points-product.md): A version of a points product that is specific to the currently logged-in customer.
- [Points product object](https://dev.smile.io/ui/objects/points-product.md): A reward that customers can redeem their points for, with a fixed or variable value.
- [Points purchase object](https://dev.smile.io/ui/objects/points-purchase.md): A record representing when a customer spends points on a reward.
- [Reward object](https://dev.smile.io/ui/objects/reward.md): The configuration for a type of discount, benefit, or perk that can be issued to a customer.
- [Reward fulfillment object](https://dev.smile.io/ui/objects/reward-fulfillment.md): A reward that has been issued to a customer, commonly containing a unique discount code.
- [VIP Tier object](https://dev.smile.io/ui/objects/vip-tier.md): A status or level that a customer can achieve as they move through a VIP program.
- [Close panel](https://dev.smile.io/ui/panel/close.md): `SmileUI.closePanel()`
- [Deep links](https://dev.smile.io/ui/panel/deep-links.md): Open the loyalty panel to specific pages using links, HTML attributes, or JavaScript.
- [Open panel](https://dev.smile.io/ui/panel/open.md): `SmileUI.openPanel(options?)`
- [Create an activity](https://dev.smile.io/ui/smile/create-activity.md): `Smile.createActivity(activityAttributes)`
- [Customer ready](https://dev.smile.io/ui/smile/customer-ready.md): `Smile.customerReady()`
- [Load all customer points products](https://dev.smile.io/ui/smile/fetch-all-customer-points-products.md): `Smile.fetchAllCustomerPointsProducts()`
- [Load all points products](https://dev.smile.io/ui/smile/fetch-all-points-products.md): `Smile.fetchAllPointsProducts()`
- [Load all reward fulfillments](https://dev.smile.io/ui/smile/fetch-all-reward-fulfillments.md): `Smile.fetchAllRewardFulfillments()`
- [Reload the customer](https://dev.smile.io/ui/smile/fetch-customer.md): `Smile.fetchCustomer(options?)`
- [Load a points product](https://dev.smile.io/ui/smile/fetch-points-product.md): `Smile.fetchPointsProduct(id)`
- [Format points](https://dev.smile.io/ui/smile/format-points.md): `Smile.formatPoints(pointsAmount, options?)`
- [Purchase a points product](https://dev.smile.io/ui/smile/purchase-points-product.md): `Smile.purchasePointsProduct(id, options?)`
- [Ready method](https://dev.smile.io/ui/smile/ready.md): `Smile.ready()`

## OpenAPI Specs

- [js-sdk](https://dev.smile.io/schemas/js-sdk.json)
- [rest-api](https://dev.smile.io/schemas/rest-api.json)
- [smile-ui](https://dev.smile.io/schemas/smile-ui.json)
- [openapi](https://dev.smile.io/api-reference/openapi.json)