Record a custom customer activity so it can earn points via a matching earning rule - the programmatic way to reward behavior that happens outside Smile's built-in triggers. Endpoint - POST /activities.
# Smile.io REST API - grounded on the published spec at https://dev.smile.io/schemas/rest-api.json
openapi: 3.1.0
info:
title: Smile.io REST API
description: A RESTful interface for interacting with Smile.io loyalty programs - customers and customer
identities, points transactions and settings, points products and purchases, earning rules, rewards
and reward fulfillments, VIP tiers, and activities. Resource-oriented URLs return JSON and use standard
HTTP status codes. Authenticated with an HTTP Bearer token (a merchant API key, or an app OAuth access
token). REST API access is available on the Plus and Enterprise plans.
version: 1.0.0
contact:
name: Smile.io Developer Support
url: https://dev.smile.io
license:
name: Proprietary
url: https://smile.io/terms-of-service
servers:
- url: https://api.smile.io/v1
description: Smile.io REST API
paths:
/activities:
post:
summary: Create an activity
operationId: post__activities
tags:
- Activities
responses:
'201':
description: The activity was successfully created.
content:
application/json:
schema:
type: object
properties:
activity:
$ref: '#/components/schemas/Activity'
description: Creates a record of a customer having performed a given action.
requestBody:
content:
application/json:
schema:
type: object
properties:
activity:
type: object
properties:
token:
type: string
description: A token identifying the activity that was performed.
example: activity_f57a9b5a8d0ac5
distinct_id:
type: string
description: A unique identifier for the activity in the external system (e.g. the
order number).
example: '212993'
created_on_origin_at:
type: string
description: The date and time the activity was performed by the customer in the
external system (e.g. when the action actually occurred, which is often earlier
than when the activity is created in Smile).
format: date-time
example: '2024-04-04T15:10:42.030Z'
required:
- token
oneOf:
- title: With customer ID
properties:
customer_id:
type: integer
example: 304169228
description: The ID of the customer who performed the activity. Required if `customer_email`
is not provided.
required:
- customer_id
- title: With customer email
properties:
customer_email:
type: string
example: jane@doe.com
description: The email of the customer who performed the activity. Required if
`customer_id` is not provided.
format: email
required:
- customer_email
required:
- activity
/earning_rules:
get:
summary: List earning rules
operationId: get__earning_rules
tags:
- Earning Rules
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
earning_rules:
type: array
items:
$ref: '#/components/schemas/EarningRule'
metadata:
$ref: '#/components/schemas/PaginationMetadata'
description: Retrieves a list of enabled earning rules.
parameters:
- name: limit
in: query
required: false
schema:
type: integer
description: The maximum number of earning rules to retrieve.
minimum: 1
maximum: 250
default: 50
description: The maximum number of earning rules to retrieve.
- name: cursor
in: query
required: false
schema:
type: string
description: Cursor for the page of earning rules to retrieve.
description: Cursor for the page of earning rules to retrieve.
/reward_fulfillments:
get:
summary: List reward fulfillments
operationId: get__reward_fulfillments
tags:
- Reward Fulfillments
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
reward_fulfillments:
type: array
items:
$ref: '#/components/schemas/RewardFulfillment'
metadata:
$ref: '#/components/schemas/PaginationMetadata'
description: Retrieves a list of reward fulfillments.
parameters:
- name: customer_id
in: query
required: false
schema:
type: integer
description: Filter results to only reward fulfillments with the provided Smile customer ID.
description: Filter results to only reward fulfillments with the provided Smile customer ID.
- name: fulfillment_status
in: query
required: false
schema:
type: string
description: Filter results to only reward fulfillments whose fulfillment status matches the
provided value.
enum:
- pending
- issued
- cancelled
- failed
description: Filter results to only reward fulfillments whose fulfillment status matches the provided
value.
- name: usage_status
in: query
required: false
schema:
type: string
description: Filter results to only reward fulfillments whose usage status matches the provided
values.
enum:
- used
- unused
- untracked
description: Filter results to only reward fulfillments whose usage status matches the provided
values.
- name: updated_at_min
in: query
required: false
schema:
type: string
description: Filter results to only reward fulfillments updated after the provided date and
time.
format: date-time
description: Filter results to only reward fulfillments updated after the provided date and time.
- name: limit
in: query
required: false
schema:
type: integer
description: The maximum number of reward fulfillments to retrieve.
example: 1
minimum: 1
maximum: 250
default: 50
description: The maximum number of reward fulfillments to retrieve.
- name: cursor
in: query
required: false
schema:
type: string
description: Cursor for the page of reward fulfillments to retrieve.
description: Cursor for the page of reward fulfillments to retrieve.
/customer_identities/create_or_update:
post:
summary: Create or update a customer identity
operationId: post__customer_identities_create_or_update
tags:
- Customer Identities
responses:
'200':
description: Customer identity successfully updated.
content:
application/json:
schema:
type: object
properties:
customer_identity:
$ref: '#/components/schemas/CustomerIdentity'
'201':
description: Customer identity successfully created.
content:
application/json:
schema:
type: object
properties:
customer_identity:
$ref: '#/components/schemas/CustomerIdentity'
description: Creates a new customer identity or updates an existing one.
requestBody:
content:
application/json:
schema:
type: object
properties:
customer_identity:
type: object
properties:
first_name:
type: string
description: The first name of the customer in the external system.
example: Jane
last_name:
type: string
description: The last name of the customer in the external system.
example: Doe
email:
type: string
description: The email of the customer in the external system.
format: email
example: jane@doe.com
distinct_id:
type: string
description: The unique identifier for the customer in the external system.
example: cust_19238475
properties:
type: object
description: A restricted hash of additional attributes for the customer identity.
Keys are allowlisted on a per-integration basis.
required:
- email
- distinct_id
required:
- customer_identity
/points_products/{id}/purchase:
post:
summary: Purchase a points product
operationId: post__points_products_id_purchase
tags:
- Points Products
responses:
'201':
description: The points product was successfully purchased.
content:
application/json:
schema:
type: object
properties:
points_purchase:
$ref: '#/components/schemas/PointsPurchase'
description: Exchanges a customer's points for a reward by purchasing a points product.
parameters:
- name: id
in: path
required: true
schema:
type: integer
description: ID of the points product to purchase.
example: 132456921
description: ID of the points product to purchase.
requestBody:
content:
application/json:
schema:
type: object
properties:
customer_id:
type: integer
description: ID of the customer who is purchasing the points product.
example: 304169228
points_to_spend:
type: integer
description: The number of points that will be spent on behalf of the customer. Only
applies when purchasing a points product whose `exchange_type` is `variable`, otherwise
should be left blank.
example: 500
required:
- customer_id
/points_products:
get:
summary: List points products
operationId: get__points_products
tags:
- Points Products
responses:
'200':
description: The points products were successfully retrieved.
content:
application/json:
schema:
type: object
properties:
points_products:
type: array
items:
$ref: '#/components/schemas/PointsProduct'
description: Retrieves a list of points products based on the specified filters.
parameters:
- name: exchange_type
in: query
required: false
schema:
type: string
description: Filter results to only points products with the provided `exchange_type`.
enum:
- fixed
- variable
example: variable
description: Filter results to only points products with the provided `exchange_type`.
- name: page_size
in: query
required: false
schema:
type: integer
description: The maximum number of points products to retrieve.
minimum: 1
maximum: 250
default: 50
description: The maximum number of points products to retrieve.
- name: page
in: query
required: false
schema:
type: integer
description: The page of points products to retrieve.
default: 1
description: The page of points products to retrieve.
/points_products/{id}:
get:
summary: Retrieve a points product
operationId: get__points_products_id
tags:
- Points Products
responses:
'200':
description: The points product was successfully retrieved.
content:
application/json:
schema:
type: object
properties:
points_product:
$ref: '#/components/schemas/PointsProduct'
description: Retrieves a single points product by ID.
parameters:
- name: id
in: path
required: true
schema:
type: integer
description: ID of the points product to retrieve.
description: ID of the points product to retrieve.
/points_transactions:
post:
summary: Create a points transaction
operationId: post__points_transactions
tags:
- Points Transactions
responses:
'201':
description: The points transaction was successfully created.
content:
application/json:
schema:
type: object
properties:
points_transaction:
$ref: '#/components/schemas/PointsTransaction'
description: Add or remove points from a customer's points balance by creating a points transaction.
requestBody:
content:
application/json:
schema:
type: object
properties:
points_transaction:
type: object
properties:
customer_id:
type: integer
description: The ID of the customer whose balance this points transaction applies
to.
example: 304169228
points_change:
type: integer
description: The number of points added or removed from the customer's points balance.
The value is positive if points were added to the customer's balance and negative
if points were deducted.
example: 100
description:
type: string
description: A message visible to the customer that describes the reason for the
points change.
example: Points correction
internal_note:
type: string
description: A note that is visible to the merchant. This note should never be visible
to customers.
example: 'Due to issue with order #6834'
required:
- customer_id
- points_change
required:
- points_transaction
get:
summary: List points transactions
operationId: get__points_transactions
tags:
- Points Transactions
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
points_transactions:
type: array
items:
$ref: '#/components/schemas/PointsTransaction'
metadata:
$ref: '#/components/schemas/PaginationMetadata'
description: Retrieves a list of points transactions.
parameters:
- name: customer_id
in: query
required: false
schema:
type: integer
description: Filter results to only points transactions with the provided Smile customer ID.
description: Filter results to only points transactions with the provided Smile customer ID.
- name: updated_at_min
in: query
required: false
schema:
type: string
description: Filter results to only points transactions updated at or after the provided date
and time.
format: date-time
description: Filter results to only points transactions updated at or after the provided date
and time.
- name: limit
in: query
required: false
schema:
type: integer
description: The maximum number of points transactions to retrieve.
example: 1
minimum: 1
maximum: 250
default: 50
description: The maximum number of points transactions to retrieve.
- name: cursor
in: query
required: false
schema:
type: string
description: Cursor for the page of points transactions to retrieve.
description: Cursor for the page of points transactions to retrieve.
/points_transactions/{id}:
get:
summary: Retrieve a points transaction
operationId: get__points_transactions_id
tags:
- Points Transactions
responses:
'200':
description: The points transaction was successfully retrieved.
content:
application/json:
schema:
type: object
properties:
points_transaction:
$ref: '#/components/schemas/PointsTransaction'
description: Retrieves a single points transaction by ID.
parameters:
- name: id
in: path
required: true
schema:
type: integer
description: ID of the points transaction to retrieve.
description: ID of the points transaction to retrieve.
/vip_tiers:
get:
summary: List VIP tiers
operationId: get__vip_tiers
tags:
- VIP Tiers
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
vip_tiers:
type: array
items:
$ref: '#/components/schemas/VipTier'
description: Retrieves a list of VIP tiers.
parameters:
- name: include
in: query
required: false
schema:
type: string
description: A comma-separated list of nested objects to include in the response.
enum:
- perks
- entry_rewards
description: A comma-separated list of nested objects to include in the response.
/points_settings:
get:
summary: Get points settings
operationId: get__points_settings
tags:
- Points Settings
responses:
'200':
description: The points settings were successfully retrieved.
content:
application/json:
schema:
type: object
properties:
points_settings:
$ref: '#/components/schemas/PointsSettings'
description: Retrieves the configuration for the account's points program.
/customers/{id}:
get:
summary: Retrieve a customer
operationId: get__customers_id
tags:
- Customers
responses:
'200':
description: The customer was successfully retrieved.
content:
application/json:
schema:
type: object
properties:
customer:
$ref: '#/components/schemas/Customer'
description: Retrieves a single customer by ID.
parameters:
- name: include
in: query
required: false
schema:
type: string
description: A comma-separated list of related objects to include in the response.
enum:
- vip_status
- vip_status.vip_tier
- vip_status.next_vip_tier
description: A comma-separated list of related objects to include in the response.
- name: id
in: path
required: true
schema:
type: integer
description: ID of the customer (in Smile) to retrieve.
description: ID of the customer (in Smile) to retrieve.
/customers:
get:
summary: List customers
operationId: get__customers
tags:
- Customers
responses:
'200':
description: The customers were successfully retrieved.
content:
application/json:
schema:
type: object
properties:
customers:
type: array
items:
$ref: '#/components/schemas/Customer'
metadata:
$ref: '#/components/schemas/PaginationMetadata'
description: Retrieves a list of customers based on a set of provided filters.
parameters:
- name: email
in: query
required: false
schema:
type: string
description: Filter results to only customers with the provided email address.
description: Filter results to only customers with the provided email address.
- name: state
in: query
required: false
schema:
type: string
description: Filter results to only customers with the provided state.
enum:
- candidate
- member
- disabled
description: Filter results to only customers with the provided state.
- name: updated_at_min
in: query
required: false
schema:
type: string
description: Filter results to only customers updated after the provided date and time.
format: date-time
example: '2024-04-04T15:10:42.030Z'
description: Filter results to only customers updated after the provided date and time.
- name: limit
in: query
required: false
schema:
type: integer
description: The maximum number of customers to retrieve.
example: 1
minimum: 1
maximum: 250
default: 50
description: The maximum number of customers to retrieve.
- name: cursor
in: query
required: false
schema:
type: string
description: Cursor for the page of customers to retrieve.
description: Cursor for the page of customers to retrieve.
- name: include
in: query
required: false
schema:
type: string
description: A comma-separated list of related objects to include in the response.
enum:
- vip_status
description: A comma-separated list of related objects to include in the response.
components:
schemas:
PaginationMetadata:
type: object
properties:
next_cursor:
type:
- string
- 'null'
example: aWQ6MixkaXJlY3Rpb246bmV4dA==
description: A cursor value that when present, can be used to retrieve the next page of results.
previous_cursor:
type:
- string
- 'null'
example: ''
description: A cursor value that when present, can be used to retrieve the previous page of
results.
Customer:
type: object
properties:
id:
type: integer
example: 304169228
description: Unique identifier for the customer in Smile.
first_name:
type:
- string
- 'null'
example: Jane
description: The customer's first name.
last_name:
type:
- string
- 'null'
example: Doe
description: The customer's last name.
email:
type: string
example: jane@doe.com
description: The customer's email address.
state:
type: string
enum:
- candidate
- member
- disabled
example: member
description: The customer's state in the loyalty program.
date_of_birth:
type:
- string
- 'null'
format: date
example: '1004-05-27'
description: The customer's birthday. A year value of `1004` means only the customer's birth
day and month was entered.
points_balance:
type: integer
example: 300
description: The customer's current points balance.
referral_url:
type: string
example: http://i.refs.cc/9qr5Pw
description: The customer's unique referral URL. Used to share with friends as part of the referral
program.
vip_tier_id:
type:
- integer
- 'null'
example: 426715794
deprecated: true
description: The ID of the customer's current VIP tier. This field is now deprecated, use the
nested `vip_status.vip_tier_id` instead.
vip_status:
type: object
properties:
vip_tier_id:
type:
- integer
- 'null'
example: 426715794
description: The ID of the customer's current VIP tier.
vip_tier_expires_at:
type:
- string
- 'null'
format: date-time
example: '2026-12-31T23:59:59.999Z'
description: 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:
type:
- number
- 'null'
format: float
example: 300
description: The amount the customer has already spent or earned within the current VIP
period.
current_vip_period_end:
type:
- string
- 'null'
format: date-time
example: '2025-12-31T23:59:59.999Z'
description: 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:
type:
- number
- 'null'
format: float
description: 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:
type:
- integer
- 'null'
example: 426715799
description: 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:
type:
- number
- 'null'
format: float
example: 200
description: 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`.
description: An object containing details about the customer's status within the VIP program.
created_at:
type: string
format: date-time
example: '2024-04-04T15:10:42.030Z'
description: The date and time when the customer was created.
updated_at:
type: string
format: date-time
example: '2025-04-04T15:10:42.030Z'
description: The date and time when the customer was last updated.
VipTier:
type: object
properties:
id:
type: integer
example: 426715799
description: Unique identifier for the VIP tier.
name:
type: string
example: Gold
description: The display name of the VIP tier.
image_url:
type: string
example: https://platform.smile.io/v1/images/vip_tiers/vip-tier-3.svg
description: The image of the VIP tier.
milestone:
type: number
format: float
example: 500
description: The threshold that a customer must reach to be eligible for the VIP tier. Represents
either an amount of points or a dollar amount, depending on the loyalty program's configuration.
perks:
type: array
items:
type: object
properties:
name:
type: string
example: Early access to new product releases
description: A description of the benefit.
description: A set of nested objects representing the ongoing benefits a customer is entitled
to when they are in the VIP tier.
entry_rewards:
type: array
items:
$ref: '#/components/schemas/Reward'
description: A set of nested Reward objects representing the rewards that are issued to a customer
when they enter the VIP tier.
PointsTransaction:
type: object
properties:
id:
type: integer
example: 825673452
description: Unique identifier for the points transaction.
customer_id:
type: integer
example: 304169228
description: The ID of the customer whose balance this points transaction applies to.
points_change:
type: integer
example: 100
description: The number of points added or removed from the customer's points balance. The value
is positive if points were added to the customer's balance and negative if points were deducted.
description:
type: string
example: Points correction
description: A message visible to the customer that describes the reason for the points change.
internal_note:
type:
- string
- 'null'
example: 'Due to issue with order #6834'
description: A note that is visible to the merchant. This note should never be visible to customers.
created_at:
type: string
format: date-time
example: '2024-12-07T20:15:27.893Z'
description: The date and time when the points transaction was created.
updated_at:
type: string
format: date-time
example: '2024-12-07T20:15:27.893Z'
description: The date and time when the points transaction was last updated.
PointsProduct:
type: object
properties:
id:
type: integer
example: 132456921
description: Unique identifier for the points product.
exchange_type:
type: string
enum:
- fixed
- variable
example: variable
description: How points are exchanged for the reward.
exchange_description:
type: string
example: 100 Points = $1 off
description: A human readable description of how a custome
# --- truncated at 32 KB (54 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/smile-io/refs/heads/main/openapi/smile-io-openapi.yml