NAV Navbar

Hero

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.

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:

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.