Topics

Introduction

API endpoint

https://api.smile.io

The Smile API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. We support cross-origin resource sharing, allowing you to interact securely with our API from a client-side web application (though you should never expose your secret API key in any public website's client-side code). JSON is returned by all API responses, including errors.

We send information on new additions and changes to Smile's API to the email in your partners account. Be sure to keep that email up to date to stay informed. For merchants with private apps, we will email the app maintainer.

Authentication

Example request

curl "https://api.smile.io/v1/customers/1" \
  -X "GET" \
  -H "Authorization: Bearer test_cnzGMghxTmPzK1spPraT"

The curl utility uses the -H flag to pass headers and the -X flag to specify the request method.

A sample API key is included in all the examples on this page, so you can test any example right away. To test requests using your account, replace the sample API key with your actual API key.

Authenticate your account when using the API by including your secret API key in the request.

Merchants can find their secret keys in the Smile Admin. Partners developing public apps will need to use the access token that their app acquires after successfully completing the Smile OAuth flow. Your secret keys carry many privileges, so be sure to keep them a secret! Do not share your secret keys in publicly accessible areas such as GitHub, client-side code, and so forth.

Authentication to the API is performed via HTTP Bearer Auth. Use your secret key as the bearer value like this:

Authorization: Bearer test_cnzGMghxTmPzK1spPraT

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Errors

Example error response

{
  "error": {
    "message": "Invalid credentials."
  }
}

Smile.io uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a points transaction failed, etc.). Codes in the 5xx range indicate an error with Smile's servers (these are rare).

Attributes
message string	A human readable message indicating what went wrong.

HTTP status code summary

Error code	Description
200 - OK	Everything worked as expected.
400 - Bad Request	The request was unacceptable, often due to missing a required parameter.
401 - Unauthorized	No valid API key provided.
402 - Request Failed	The parameters were valid but the request failed.
404 - Not Found	The requested resource doesn't exist.
429 - Too Many Requests	Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500,502,503,504 - Server Errors	Something went wrong on Smile's end. (These are rare.)

Pagination

Sometimes it's useful to traverse through all items for a specific resource. A common example is retrieving all the customers in your rewards program, in order to sync their points balances with your system or send them to a third party system. The Smile API provides pagination parameters that can be used on any resource to do just this.

Cursor-based pagination

Example request

curl "https://api.smile.io/v1/customers" \
  -X "GET" \
  -H "Authorization: Bearer test_cnzGMghxTmPzK1spPraT" \
  -d "limit=2"

Example response

{
  "customers": [
    {
      "id": 10,
      "first_name": "Fred",
      "last_name": "Flinstone",
      "email": "fred@smile.io",
      "date_of_birth": "1988-07-24",
      "points_balance": 4700,
      "referral_url": "http://i.refs.cc/9qr5Pw",
      "vip_tier_id": null,
      "state": "member",
      "created_at": "2019-01-08T11:12:14.111Z",
      "updated_at": "2019-01-08T11:12:14.111Z"
    },
    {
      "id": 9,
      "first_name": "Arthur",
      "last_name": "Read",
      "email": "arthur@smile.io",
      "date_of_birth": "1999-02-14",
      "points_balance": 2300,
      "referral_url": "http://i.refs.cc/5ps3Pk",
      "vip_tier_id": null,
      "state": "member",
      "created_at": "2018-11-03T12:05:29.121Z",
      "updated_at": "2018-11-03T12:05:29.121Z"
    }
  ],
  "metadata": {
    "next_cursor": "aWQ6MixkaXJlY3Rpb246bmV4dA==",
    "previous_cursor": null
  }
}

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

Arguments
limit optional	A limit on the number of objects returned, between 1 and 250. Default is 50.
cursor optional	Cursor for the page to be retrieved.

Classic pagination

Example request

curl "https://api.smile.io/v1/customers" \
  -X "GET" \
  -H "Authorization: Bearer test_cnzGMghxTmPzK1spPraT" \
  -d "page_size=2"

Example response

{
  "customers": [
    {
      "id": 1,
      "first_name": "Jane",
      "last_name": "Bond",
      "email": "jane@smile.io",
      "date_of_birth": "1967-10-29",
      "points_balance": 5000,
      "referral_url": "http://i.refs.cc/j2Fw55",
      "vip_tier_id": null,
      "state": "member",
      "created_at": "2017-04-04T15:10:42.030Z",
      "updated_at": "2017-04-04T15:10:42.030Z"
    },
    {
      "id": 2,
      "first_name": "Abe",
      "last_name": "Erb",
      "email": "abe@smile.io",
      "date_of_birth": "1967-10-29",
      "points_balance": 4200,
      "referral_url": "http://i.refs.cc/7vz3Rs",
      "vip_tier_id": null,
      "state": "member",
      "created_at": "2017-04-06T11:18:23.131Z",
      "updated_at": "2017-04-06T11:18:23.131Z"
    }
  ]
}

To move between pages of objects using classic pagination, you simply increment the page argument with each request. When you receive a response containing fewer than page_size objects, you know you've reached the last page.

Arguments
page_size optional	A limit on the number of objects returned, between 1 and 250. Default is 50.
page optional	The page of objects to return. Default is 1.

Rate Limits

To ensure platform stability and efficient processing for everyone, all of our API endpoints are rate limited. We use a leaky bucket algorithm and limit all API consumers to 10 requests per second. When you reach this limit, all requests will return an HTTP 429 - Too Many Requests error until your limit has been replenished.

We actively monitor for API consumers regularly exceeding their rate limit and encourage developers to use techniques like caching, limiting the number of requests being made, and intelligent retry/backoff behaviour.

API Resources

Activities

The activity object

Example activity object

{
  "id": 133577,
  "customer_id": 2812211,
  "token": "activity_f57a9b5a8d0ac5",
  "properties": {
    "grand_total": 115.0,
    "rewardable_total": 100.0,
    "payment_status": "paid",
    "discount_codes": [
      { "code": "5off-j2n5jduwjttj" }
    ]
  },
  "distinct_id": "212993",
  "created_on_origin_at": "2017-04-04T15:10:42.030Z",
  "updated_on_origin_at": "2017-04-04T15:10:42.030Z",
  "created_at": "2017-05-15T08:35:08.920Z",
  "updated_at": "2017-05-15T08:35:08.920Z"
}

Attributes
id integer	Unique identifier for the activity
customer_id integer	Unique identifier for the customer who performed this activity.
token string	A token identifying which activity was performed.
properties hash	Any properties related to the activity. Optional.
distinct_id string	If the activity has a unique record associated with it outside of Smile, this should be set. For example, an order ID
created_on_origin_at datetime	The date the activity was performed by the customer. This attribute is optional but useful for stateful activities that occurred before Smile was installed. By setting the value to when the activity was created, the customer will not be rewarded since Smile will know the activity took place before the program was active. If omitted, this will be set as the activity created date.
updated_on_origin_at datetime	The date the activity was last updated outside of Smile. This attribute is optional but highly recommended for activities that are updated, like orders. Smile will use this value to ensure if two updates happen very close together that the latest timestamp will be the one saved.
created_at datetime	Time at which the activity was created in Smile.
updated_at datetime	Time at which the activity was updated in Smile.

Create an activity

Definition

POST https://api.smile.io/v1/activities

Example request

curl "https://api.smile.io/v1/activities" \ 
  -X "POST" \ 
  -H "Authorization: Bearer test_cnzGMghxTmPzK1spPraT" \ 
  -H "Content-Type: application/json" \ 
  -d $'{
  "activity": {
    "customer_id": 2812211,
    "token": "activity_f57a9b5a8d0ac5"
  }
}'

This endpoint notifies Smile of an activity performed by a customer. This normally results in a reward being issued, such as points being given for placing an order.

Note that the response of this endpoint is not documented and as such, is apt to change. The activity record should not need to be stored on an external system anyway.

Arguments
activity required	The activity to be created. See the activity argument list below.

The provided activity object must comply with the following argument list.

Activity arguments
customer_id required	Unique identifier for the customer who performed this activity. This should be the ID of the customer in Smile, not the ID of the customer in your system.
token required	A token identifying which activity was performed.
properties optional	Any miscellaneous properties related to the activity.
distinct_id optional	A unique identifier for this activity in the external system (e.g. an order ID).
created_on_origin_at optional	The date the activity was performed by the customer. This attribute is useful for stateful activities that occurred before Smile was installed. By setting the value to when the activity was created, the customer will not be rewarded since Smile will know the activity took place before the program was active. If omitted, this will be set as the activity created date.
updated_on_origin_at optional	The date the activity was last updated outside of Smile. This attribute is highly recommended for activities that are updated, like orders. Smile will use this value to ensure if two updates happen very close together that the latest timestamp will be the one saved.

Customers

The customer object

Example customer object

{
  "id": 1,
  "first_name": "Jane",
  "last_name": "Bond",
  "email": "jane@smile.io",
  "state": "member",
  "date_of_birth": "1967-10-29",
  "points_balance": 5000,
  "referral_url": "http://i.refs.cc/j2Fw55",
  "vip_tier_id": null,
  "created_at": "2017-04-04T15:10:42.030Z",
  "updated_at": "2017-04-04T15:10:42.030Z"
}

Attributes
id integer	Unique identifier for the customer.
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 rewards program. This value is always one of disabled, candidate, member.
date_of_birth date	The customer's birthday. Only exists if entered by the customer through the Smile panel. A year value of 1004 means only the customer's birth day and month was entered.
points_balance integer	Current points balance for the customer.
referral_url string	A unique URL for the customer. Used to share with friends as part of the referral program.
vip_tier_id integer	The ID of the customer's current VIP Tier.
created_at datetime	Time at which the customer was created.
updated_at datetime	Time at which the customer was updated.

Retrieve a customer

Definition

GET https://api.smile.io/v1/customers/{CUSTOMER_ID}

Example Request

curl "https://api.smile.io/v1/customers/1" \ 
  -X "GET" \ 
  -H "Authorization: Bearer test_cnzGMghxTmPzK1spPraT"

Example Response

{
  "customer": {
    "id": 1,
    "first_name": "Jane",
    "last_name": "Bond",
    "email": "jane@smile.io",
    "state": "member",
    "date_of_birth": "1967-10-29",
    "points_balance": 5000,
    "referral_url": "http://i.refs.cc/j2Fw55",
    "vip_tier_id": null,
    "created_at": "2017-04-04T15:10:42.030Z",
    "updated_at": "2017-04-04T15:10:42.030Z"
  }
}

Retrieves the details of an existing customer.

Arguments
id required	The identifier of the customer to be retrieved.
include optional	When provided as a query parameter with a value of vip_tier, this argument can be used to include the customer's VIP tier in the response body.

List all customers

Definition

GET https://api.smile.io/v1/customers

Example request

curl "https://api.smile.io/v1/customers" \ 
  -X "GET" \ 
  -H "Authorization: Bearer test_cnzGMghxTmPzK1spPraT"

Example response

{
  "customers": [
    {
      "id": 10,
      "first_name": "Fred",
      "last_name": "Flinstone",
      "email": "fred@smile.io",
      "date_of_birth": "1988-07-24",
      "points_balance": 4700,
      "referral_url": "http://i.refs.cc/9qr5Pw",
      "vip_tier_id": null,
      "state": "member",
      "created_at": "2019-01-08T11:12:14.111Z",
      "updated_at": "2019-01-08T11:12:14.111Z"
    },
    {
      "id": 9,
      "first_name": "Arthur",
      "last_name": "Read",
      "email": "arthur@smile.io",
      "date_of_birth": "1999-02-14",
      "points_balance": 2300,
      "referral_url": "http://i.refs.cc/5ps3Pk",
      "vip_tier_id": null,
      "state": "member",
      "created_at": "2018-11-03T12:05:29.121Z",
      "updated_at": "2018-11-03T12:05:29.121Z"
    },
    ...
  ],
  "metadata": {
    "next_cursor": "aWQ6MixkaXJlY3Rpb246bmV4dA==",
    "previous_cursor": null
  }
}

This endpoint lists all customers.

Arguments
email optional	A filter on the list based on the customer’s email. The value must be a string. Note: Email is not a unique field in Smile which means this filter may return more than one customer. The common case is email is a unique field for customers, but not always since it depends on what platforms the merchant has connected.
state optional	A filter on the list based on the customer’s state. The value must be one of disabled, candidate, or member.
updated_at_min optional	Show customers that were last updated after this date.
limit optional	A limit on the number of customers returned, between 1 and 250. Default is 50.
cursor optional	Cursor for the page to be retrieved.
page_size optional	A limit on the number of customers returned, between 1 and 250. Default is 50. This argument is deprecated. Use the limit and cursor arguments for pagination.
page optional	The page of customers to return. Default is 1. This argument is deprecated. Use the limit and cursor arguments for pagination.
include optional	When provided as a query parameter with a value of vip_tier, this argument can be used to include the customer's VIP tier in the response body.

Points Products

The points product object

Example points product object

{
  "id": 133577,
  "exchange_type": "fixed",
  "exchange_description": "500 Pins",
  "points_price": 500,
  "variable_points_step": null,
  "variable_points_step_reward_value": null,
  "variable_points_min": null,
  "variable_points_max": null,
  "reward": {
    "id": 228015,
    "name": "Free T-shirt",
    "description": null,
    "image_url": "https://platform-images.smilecdn.co/3755938.png",
    "created_at": "2017-12-07T20:15:27.881Z",
    "updated_at": "2017-12-07T20:15:27.881Z"
  },
  "created_at": "2017-12-07T20:15:27.893Z",
  "updated_at": "2017-12-07T20:15:27.893Z"
}

Attributes
id integer	Unique identifier for the points product.
exchange_type string	Indicates how points are exchanged for the reward. Either fixed or variable. If the customer must spend a fixed amount of points for a predetermined reward value, the exchange type is fixed. If the customer can spend a variable amount of points for a dynamic reward value, the exchange type is variable.
exchange_description string	A human readable description of how a customer spends points on this reward. It includes the points branding for the program. E.g. "500 Gold Points".
points_price integer	Number of points needed to purchase this reward. Only present when exchange_type is fixed.
variable_points_step integer	Imagine there's a points slider your customers can drag to spend more or less points on a reward. The variable_points_step represents the number of points between each notch on the slider. E.g. If this value is set to 100, it means customers can spend their points in increments of 100. They will drag the slider from 100, 200, 300, etc. Only present when exchange_type is variable.
variable_points_step_reward_value integer	Imagine there's a points slider your customers can drag to spend more or less points on a reward. The variable_points_step_reward_value represents the corresponding reward value for each step increment on the slider. E.g. if this value is set to 1, and the variable_points_step is set to 100, the customer will get $1 off for every 100 points they spend. Only present when exchange_type is variable.
variable_points_min integer	The minimum amount of points the customer must spend to get this reward. Normally the minimum value of the points slider. Only present when exchange_type is variable.
variable_points_max integer	The maximum amount of points the customer can spend on this reward. Normally the maximum value of the points slider. Only present when exchange_type is variable.
reward object	The reward given to the customer when they purchase the points product.
created_at datetime	Time at which the points product was created.
updated_at datetime	Time at which the points product was updated.

Retrieve a points product

Definition

GET https://api.smile.io/v1/points_products/{POINTS_PRODUCT_ID}

Example request

curl "https://api.smile.io/v1/points_products/1" \ 
  -X "GET" \ 
  -H "Authorization: Bearer test_cnzGMghxTmPzK1spPraT"

Example response

{
  "points_product": {
    "id": 133577,
    "exchange_type": "fixed",
    "exchange_description": "500 Pins",
    "points_price": 500,
    "variable_points_step": null,
    "variable_points_step_reward_value": null,
    "variable_points_min": null,
    "variable_points_max": null,
    "reward": {
      "id": 228015,
      "name": "Free T-shirt",
      "description": null,
      "image_url": "https://platform-images.smilecdn.co/3755938.png",
      "created_at": "2017-12-07T20:15:27.881Z",
      "updated_at": "2017-12-07T20:15:27.881Z"
    },
    "created_at": "2017-12-07T20:15:27.893Z",
    "updated_at": "2017-12-07T20:15:27.893Z"
  }
}

This endpoint is not available to public Smile apps.

Retrieves the details of an existing points product.

Arguments
id required	The identifier of the points product to be retrieved.

Purchase a points product

Definition

POST https://api.smile.io/v1/points_products/{POINTS_PRODUCT_ID}/purchase

Example request

curl "https://api.smile.io/v1/points_products/1/purchase" \
  -X "POST" \
  -H "Authorization: Bearer test_cnzGMghxTmPzK1spPraT" \
  -H "Content-Type: application/json" \
  -d $'{
    "customer_id": 1,
    "points_to_spend": 500
  }'

Example response

{
  "points_purchase": {
    "id": 81,
    "customer_id": 2,
    "points_product_id": 21,
    "points_spent": 500,
    "reward_fulfillment": {
      "id": 137,
      "name": "$5 off",
      "code": "discount-e26d02e39149",
      "created_at": "2017-05-15T08:35:08.883Z",
      "updated_at": "2017-05-15T08:35:08.883Z"
    },
    "created_at": "2017-05-15T08:35:08.920Z",
    "updated_at": "2017-05-15T08:35:08.920Z"
  }
}

This endpoint is not available to public Smile apps.

This endpoint spends a customers points on a points product to create a points purchase containing their reward.

Arguments
id required	The identifier of the points product to be purchased.
customer_id required	The unique id of the customer spending points.
points_to_spend conditional	The number of points that will be spent on behalf of the customer. Only applies when purchasing a points product with a variable exchange type.

List all points products

Definition

GET https://api.smile.io/v1/points_products

Example request

curl "https://api.smile.io/v1/points_products" \ 
  -X "GET" \ 
  -H "Authorization: Bearer test_cnzGMghxTmPzK1spPraT"

Example response

{
  "points_products": [
    {
      "id": 133577,
      "exchange_type": "fixed",
      "exchange_description": "500 Pins",
      "points_price": 500,
      "variable_points_step": null,
      "variable_points_step_reward_value": null,
      "variable_points_min": null,
      "variable_points_max": null,
      "reward": {
        "id": 228015,
        "name": "Free T-shirt",
        "description": null,
        "image_url": "https://platform-images.smilecdn.co/3755938.png",
        "created_at": "2017-12-07T20:15:27.881Z",
        "updated_at": "2017-12-07T20:15:27.881Z"
      },
      "created_at": "2017-12-07T20:15:27.893Z",
      "updated_at": "2017-12-07T20:15:27.893Z"
    },
    {
      "id": 113700,
      "exchange_type": "fixed",
      "points_price": 1000,
      "variable_points_step": null,
      "variable_points_step_reward_value": null,
      "variable_points_min": null,
      "variable_points_max": null,
      "exchange_description": "1000 Pins",
      "reward": {
        "id": 162070,
        "name": "Free Blue Sunglasses",
        "description": null,
        "image_url": "https://platform-images.smilecdn.co/3755938.png",
        "created_at": "2017-08-16T16:51:54.736Z",
        "updated_at": "2017-08-16T16:51:54.736Z"
      },
      "created_at": "2017-08-16T16:51:54.748Z",
      "updated_at": "2017-09-08T00:11:19.000Z"
    }
  ]
}

This endpoint is not available to public Smile apps.

This endpoint lists all points products.

Arguments
exchange_type optional	Filter by exchange type. This is useful for listing all points products that can be purchased with a fixed amount and rendering them with a 'Buy with points' button.
page_size optional	A limit on the number of points products returned, between 1 and 250. Default is 50.
page optional	The page of points products to return. Default is 1.

Points Purchases

The points purchase object

Example points purchase object

{
  "id": 133577,
  "customer_id": 1,
  "points_product_id": 33845,
  "points_spent": 2500,
  "reward_fulfillment": {
    "id": 211231,
    "name": "Free shipping coupon",
    "code": "freeship-e26d02e39149",
    "image_url": "https://cdn.smile.io/assets/rewards/icon-9283449.png",
    "action_text": null,
    "action_url": null,
    "usage_instructions": "Use this discount code on your next order for free shipping!",
    "terms_and_conditions": "Reward expires on June 7, 2018. Reward can only be used when shipping costs are less than or equal to $20.",
    "expires_at": "2018-06-07T23:59:59.999Z",
    "used_at": "2018-05-17T11:27:16.123Z",
    "created_at": "2017-12-07T20:15:27.893Z",
    "updated_at": "2017-12-07T20:15:27.893Z"
  },
  "created_at": "2017-12-07T20:15:27.893Z",
  "updated_at": "2017-12-07T20:15:27.893Z"
}

A points purchase is a record representing when a customer spends points on a reward. Much like spending money on a product results in an order, spending points on a points product results in a points purchase.

Attributes
id integer	Unique identifier for the points purchase.
customer_id integer	The customer who's balance this points purchase applies to.
points_product_id integer	The unique identifier of the points product that was purchased.
points_spent integer	The total points spent by the customer.
reward_fulfillment object	The reward fulfillment received by the customer as part of this purchase.
created_at datetime	Time at which the points purchase was created.
updated_at datetime	Time at which the points purchase was updated.

Create a points purchase

Points purchases cannot be created directly. They can only be created via the purchase of a points product (see the section on purchasing a points product). The result of this call will be a new points purchase object.

Points Transactions

The points transaction object

Example points transaction object

{
  "id": 133577,
  "customer_id": 1,
  "points_change": 500,
  "description": "Placed an order",
  "internal_note": null,
  "created_at": "2017-12-07T20:15:27.893Z",
  "updated_at": "2017-12-07T20:15:27.893Z"
}

Attributes
id integer	Unique identifier for the points transaction.
customer_id integer	The unique identifier 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. The value is positive if points were added to the customer's balance and negative if points were deducted. E.g. 500 or -100.
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. This note should never be visible to customers.
created_at datetime	Time at which the points transaction was created.
updated_at datetime	Time at which the points transaction was updated. Note: The points_change value cannot be updated. A new transaction must be created to adjust any customer's points balance.

Create a points transaction

Definition

POST https://api.smile.io/v1/points_transactions

Example request

curl "https://api.smile.io/v1/points_transactions" \ 
  -X "POST" \ 
  -H "Authorization: Bearer 1dDdzcKNsp84bpAUr8aj9wzk" \ 
  -H "Content-Type: application/json" \ 
  -d $'{
  "points_transaction": {
    "customer_id": 1,
    "points_change": 1000,
    "description": "Thanks for being such a great customer this year :)",
    "internal_note": "This customer makes a purchase at least once a month and is always so cheery on support. Sending them a little token of appreciation.",
  }
}'

Example response

{
  "points_transaction": {
    "id": 133577,
    "customer_id": 1,
    "points_change": 1000,
    "description": "Thanks for being such a great customer this year :)",
    "internal_note": "This customer makes a purchase at least once a month and is always so cheery on support. Sending them a little token of appreciation.",
    "created_at": "2017-12-07T20:15:27.893Z",
    "updated_at": "2017-12-07T20:15:27.893Z"
  }
}

This endpoint is not available to public Smile apps.

This endpoint allows for the adjustment of a customer's points balance.

Arguments
points_transaction required	The points transaction object to be created. See the points transaction arguments list below for details.

The provided points transaction object must comply with the following structure.

Points transaction arguments
customer_id required	The unique identifier of the customer whose balance is being adjusted.
points_change required	The number of points to adjust the customer's balance by. Can be a positive number to give points, or a negative number to deduct points. Cannot be zero.
description required	A message visible to the customer that describes the reason for the points change.
internal_note optional	A note that is visible to the merchant. This note should never be visible to customers.

Retrieve a points transaction

Definition

GET https://api.smile.io/v1/points_transactions/{POINTS_TRANSACTION_ID}

Example request

curl "https://api.smile.io/v1/points_transactions/1" \ 
  -X "GET" \ 
  -H "Authorization: Bearer test_cnzGMghxTmPzK1spPraT"

Example response

{
  "points_transaction": {
    "id": 133577,
    "customer_id": 1,
    "points_change": 500,
    "description": "Placed an order",
    "internal_note": null,
    "created_at": "2017-12-07T20:15:27.893Z",
    "updated_at": "2017-12-07T20:15:27.893Z"
  }
}

This endpoint is not available to public Smile apps.

Retrieves the details of an existing points transaction.

Arguments
id required	The identifier of the points transaction to be retrieved.

List all points transactions

Definition

GET https://api.smile.io/v1/points_transactions

Example request

curl "https://api.smile.io/v1/points_transactions" \ 
  -X "GET" \ 
  -H "Authorization: Bearer test_cnzGMghxTmPzK1spPraT"

Example response

{
  "points_transactions": [
    {
      "id": 133578,
      "customer_id": 1,
      "points_change": -500,
      "description": "Spent points on reward - $5 off",
      "internal_note": null,
      "created_at": "2017-12-07T20:15:27.893Z",
      "updated_at": "2017-12-07T20:15:27.893Z"
    },
    {
      "id": 133577,
      "customer_id": 1,
      "points_change": 500,
      "description": "Placed an order",
      "internal_note": null,
      "created_at": "2017-12-07T20:15:27.893Z",
      "updated_at": "2017-12-07T20:15:27.893Z"
    },
    ...
  ],
  "metadata": {
    "next_cursor": "aWQ6MixkaXJlY3Rpb246bmV4dA==",
    "previous_cursor": null
  }
}

This endpoint is not available to public Smile apps.

This endpoint lists all points transactions.

Arguments
customer_id optional	List points transactions for a specific customer.
updated_at_min optional	Show points transactions that were last updated after this date.
limit optional	A limit on the number of points transactions returned, between 1 and 250. Default is 50.
cursor optional	Cursor for the page to be retrieved.
page_size optional	A limit on the number of points transactions returned, between 1 and 250. Default is 50. This argument is deprecated. Use the limit and cursor arguments for pagination.
page optional	The page of points transactions to return. Default is 1. This argument is deprecated. Use the limit and cursor arguments for pagination.

Referrals

The referral object

Example referral object

{
  "id": 133577,
  "receiver_customer": {
    "id": 2,
    "first_name": "Carmen",
    "last_name": "Sandiego",
    "email": "carmen@smile.io",
    "state": "member",
    "date_of_birth": "1988-05-15",
    "points_balance": 100,
    "referral_url": "http://i.refs.cc/j2Fw66",
    "vip_tier_id": null,
    "created_at": "2017-04-05T12:11:22.040Z",
    "updated_at": "2017-04-05T12:11:22.040Z"
  },
  "receiver_customer_email": "carmen@smile.io",
  "receiver_reward_fulfillment": {
    "id": 1,
    "name": "Free shipping coupon",
    "code": "freeship-e26d02e39149",
    "image_url": "https://platform-images.smilecdn.co/9283449.png",
    "action_text": null,
    "action_url": null,
    "usage_instructions": "Use this discount code on your next order for free shipping!",
    "terms_and_conditions": "Reward expires on October 4, 2017. Reward can only be used when shipping costs are less than or equal to $20.",
    "expires_at": "2017-10-04T23:59:59.999Z",
    "used_at": null,
    "created_at": "2017-04-04T20:15:27.893Z",
    "updated_at": "2017-04-04T20:15:27.893Z"
  },
  "sender_customer": {
    "id": 1,
    "first_name": "Jane",
    "last_name": "Bond",
    "email": "jane@smile.io",
    "state": "member",
    "date_of_birth": "1967-10-29",
    "points_balance": 5000,
    "referral_url": "http://i.refs.cc/j2Fw55",
    "vip_tier_id": null,
    "created_at": "2017-01-04T15:10:42.030Z",
    "updated_at": "2017-04-02T16:05:21.300Z"
  },
  "sender_reward_fulfillment": {
    "id": 133578,
    "name": "$25 off coupon",
    "code": "25off-e26d02e39149",
    "image_url": "https://platform-images.smilecdn.co/9283449.png",
    "action_text": null,
    "action_url": null,
    "usage_instructions": "Use this discount code on your next order!",
    "terms_and_conditions": "Reward expires on October 5, 2018. Reward can only be used on purchases of $50 or more.",
    "expires_at": "2017-10-05T23:59:59.999Z",
    "used_at": null,
    "created_at": "2017-04-05T12:15:22.040Z",
    "updated_at": "2017-04-05T12:15:22.040Z"
  },
  "created_at": "2017-04-04T20:15:27.893Z",
  "updated_at": "2017-04-05T12:15:22.040Z"
}

A referral is a record of a customer encouraging someone else to shop with the merchant, where both the customer and the other individual are rewarded for their actions.

Attributes
id integer	Unique identifier for the referral.
receiver_customer object	The customer who is being referred. Only present after an order is placed using the referral coupon.
receiver_customer_email string	The email address of the individual being referred.
receiver_reward_fulfillment object	The reward fulfillment issued to the individual who is being referred.
sender_customer object	The customer whose referral link was used to initiate the referral.
sender_reward_fulfillment object	The reward fulfillment issued to the customer whose referral link was used to initiate the referral. Only present after the individual being referred places an order.
created_at datetime	Time at which the referral was created.
updated_at datetime	Time at which the referral was updated.

Rewards

The reward object

Example reward object

{
  "id": 228015,
  "name": "$5 off",
  "description": null,
  "image_url": "https://platform-images.smilecdn.co/3755938.png",
  "created_at": "2017-12-07T20:15:27.881Z",
  "updated_at": "2017-12-07T20:15:27.881Z"
}

Attributes
id integer	Unique identifier for the reward.
name string	The name of the reward.
description string	An optional description of the reward.
image_url string	An image for the reward.
created_at datetime	Time at which the reward was created.
updated_at datetime	Time at which the reward was updated.

Reward Fulfillments

The reward fulfillment object

Example reward fulfillment object

{
  "id": 133577,
  "name": "$25 off coupon",
  "code": "25off-e26d02e39149",
  "image_url": "https://platform-images.smilecdn.co/9283449.png",
  "action_text": null,
  "action_url": null,
  "usage_instructions": "Use this discount code on your next order!",
  "terms_and_conditions": "Reward expires on June 7, 2018. Reward can only be used on purchases of $50 or more. Reward can only be used on select product collections.",
  "expires_at": "2018-06-07T23:59:59.999Z",
  "used_at": null,
  "created_at": "2017-12-07T20:15:27.893Z",
  "updated_at": "2017-12-07T20:15:27.893Z"
}

A reward fulfillment is a reward that has been issued to a customer. It commonly contains a unique discount code for customers to apply at checkout on their next order.

Attributes
id integer	Unique identifier for the reward fulfillment.
name string	The reward fulfillment's name.
code string	A unique code for the customer to use. This is commonly a discount code the customer applies at checkout on their next order, but it can be a unique code they use for other purposes like accessing an exclusive page on the merchant's website.
image_url string	The reward fulfillment's image.
action_text string	A short "call to action" style text, appropriate for use in buttons or links, guiding the customer on how to use the reward. This field may sometimes be blank.
action_url string	A URL destination guiding the customer on how to use the reward, often paired with the `action_text` for use in buttons or links. This field may sometimes be blank.
usage_instructions string	A description of how the customer can use the reward.
terms_and_conditions string	A description of the reward's limitations or restrictions. When the reward is a discount code, this commonly includes expiry date, minimum order amounts, or applicability to specific product collections.
expires_at datetime	Time at which the reward fulfillment expires.
used_at datetime	Time at which the reward fulfillment was used by the customer.
created_at datetime	Time at which the reward fulfillment was created.
updated_at datetime	Time at which the reward fulfillment was updated.

Create a reward fulfillment

A reward fulfillment cannot be created directly.

Reward fulfillments are created as a result of any of the following events:

• A customer spending points on a points product (points product reward is fulfilled)
• A customer entering a VIP tier (entry rewards are fulfilled)
• A customer sending a referral to a friend (sender reward is fulfilled)
• A customer receiving a referral from a friend (receiver reward is fulfilled)

VIP Tiers

The VIP tier object

Example VIP tier object

{
  "id": 133577,
  "name": "Gold",
  "image_url": "https://platform-images.smilecdn.co/582j2kd82k2j.png"
}

Attributes
id integer	Unique identifier for the VIP tier.
name string	Display name of the VIP tier.
image_url string	VIP tier's image.

VIP Tier Changes

The VIP tier change object

Example VIP tier change object

{
  "id": 133577,
  "previous_vip_tier": {
    "id": 8576,
    "name": "Silver",
    "image_url":"https://platform-images.smilecdn.co/582j2kd82k2j.png"
  },
  "current_vip_tier": {
    "id": 9378,
    "name": "Gold",
    "image_url":"https://platform-images.smilecdn.co/582j2kd82k2j.png"
  },
  "description":"Achieved Gold"
}

A VIP tier change is a record of a customer moving from one VIP tier to another.

Attributes
id integer	Unique identifier for the VIP tier change.
previous_vip_tier object	The VIP tier the customer was in before the change occurred.
current_vip_tier object	The VIP tier the customer moved to as a result of the change.
description string	A description of the change that occurred.