Repeat Customer Insights API documentation

Overview

Repeat Customer Insights provides an application programming interface (API) to let you connect and use its data.

To make it easier on integrators and make use of existing tooling, the API is based on and conforms to JSON API v1.0 specification. Please report any deviations from the specification.

Beta

The API is currently in Beta (real beta and not Google-beta) and will be subject to change, including breaking changes at any time.

I'm happy to talk through the details of it and welcome any thoughts you have. You can use the support icon and links at bottom of the page to contact me.

Base Endpoint

Use this as the base endpoint for any requests.

https://repeat-customer-insights.littlestreamsoftware/api/v1/

Versioning

The API's major version is included used in the url.

New major versions will have new base endpoints but resources may keep their prior url endpoints. Older major API versions will be deprecated and removed after a notification period.

New minor versions will not modify the existing urls but may add additional resources.

Authentication

Each account has an API token which acts as a unique password for your account. This token will allow access to sensitive data.

Protect this token as you would a password and never release it publicly.

Each request made to the API must include the API token as part of the Authorization HTTP header using the Bearer type. For example:

Authorization: Bearer <token>

API tokens can be revoked and reset inside the app. Once a token is revoked, any API calls made with it will be unauthorized.

API limits

The API is throttled and limited to 60 requests per minute. Requests above that limit will return a HTTP 429 error.

It's recommended that your code handle that error by pausing (e.g. sleep) for long enough to replenish the limiter and then retrying. An exponential backoff is ideal.

Please be mindful of your usage of the API as it is shared by other people. Overuse or attempts to circumvent the limiter may result in the loss of API access.

Pagination

The API uses cursor-based pagination for responses with multiple resources.

The best way to use this is to use the url in the next field. These will be included in the links object when another page of data exists.

"links": {
  "first": "https://repeat-customer-insights.littlestreamsoftware.com/api/v1/customers",
  "next": "https://repeat-customer-insights.littlestreamsoftware.com/api/v1/customers?page%5Bcursor%5D=abc123"
}

You may also extract the page[cursor] value directly and use it. The cursor value should not be modified.

To request a specific page, send the cursor as the cursor field on the page object

Example

GET https://repeat-customer-insights.littlestreamsoftware/api/v1/customers?page%5Bcursor%5D=abc123

Attributes

cursor

(string) The cursor identifier to get a specific page (e.g. the next page)

Customers resource

Customers represent your store's customers. They include information about the customer as well as the individual analysis of the customer.

Attributes

Example customer

"data": {
  "type": "customer",
  "id": "123456",
  "attributes": {
    "remote_created_at": "2016-04-13T18:31:51.000Z",
    "remote_updated_at": "2018-05-11T22:05:16.000Z",
    "first_name": "Eric",
    "last_name": "Davis",
    "email": "customer@example.com",
    "email_marketing_consent": true,
    "sms_marketing_consent": true,
    "created_at": "2016-11-14T22:26:48.601Z",
    "updated_at": "2022-01-26T17:36:14.440Z",
    "ltv_cents": 5700,
    "ltv_currency": "USD",
    "orders_count": 1,
    "recent_order_at": "2016-04-13T18:32:03.000Z",
    "recency_score": 4,
    "frequency_score": 1,
    "monetary_score": 1,
    "rfm": 411,
    "grade": "D",
    "acquisition_source": "web",
    "cohort": "2022-04",
    "segments": [
      "Average spender",
      "Promising new",
      "Recent low spender (RM)"
    ]
  },
  "links": {
    "self": "https://repeat-customer-insights.littlestreamsoftware.com/api/v1/customers/123456"
}

id

(string) The identifier for your customer, based on your customer's source. e.g. Shopify's customer id for Shopify accounts

type

(string) The type of this data.

remote_created_at

(ISO8601 timestamp, UTC time) When your customer's source created the customer originally.

remote_updated_at

(ISO8601 timestamp, UTC time) When your customer's source last updated the customer.

first_name

(string) Customer's first name.

last_name

(string) Customer's last name.

email

(string) Customer's email address.

email_marketing_consent

(boolean) Does this customer consent to email marketing?

sms_marketing_consent

(boolean) Does this customer consent to SMS marketing?

created_at

(ISO8601 timestamp, UTC time) When the customer was created in Repeat Customer Insights.

updated_at

(ISO8601 timestamp, UTC time) When the customer was last updated in Repeat Customer Insights.

ltv_cents

(integer) The total Lifetime Value for the customer, in cents.

ltv_currency

(string) The currency of the ltv_cents field (ISO 4217)

orders_count

(integer) The number of orders the customer has placed. Note: This can be 0 if the customer has cancelled orders or otherwise skipped orders.

recent_order_at

(ISO8601 timestamp, UTC time) When the last order for the customer was placed

recency_score

(integer) The RFM Recency score from 1 to 5.

frequency_score

(integer) The RFM Frequency score from 1 to 5.

monetary_score

(integer) The RFM Monetary score from 1 to 5.

rfm

(integer) The RFM score, combined from the recency_score, frequency_score, and monetary_score. Will range from 111 to 555.

grade

(string) The customer grade from A - F (skipping E).

acquisition_source

(string) The source of the customer's first order.

cohort

(string) The cohort name the customer belongs to, based on the year and month of their first order.

segments

(array of strings) The automatic segments assigned to the customer.

redacted_at

(ISO8601 timestamp, UTC time) When a customer's information was redacted, e.g. as part of a GDPR data deletion request.

Redacted customers

Redacted customers are customers who withdrew their consent for access or analysis of their data (e.g. GDPR data deletion request). Their PII will be redacted. Their data will not be processed in the analyses. The id is provided for you to cross-reference with your own data logs to determine what processing you are allowed to use.

Customers / List

To get lists of customers, make a GET request to the customers endpoint.

Endpoint

GET /api/v1/customers

Optional parameters

Example

GET https://repeat-customer-insights.littlestreamsoftware.com/api/v1/customers

Response:

{
  "links": {
    "first": "https://repeat-customer-insights.littlestreamsoftware.com/api/v1/customers",
    "next": "https://repeat-customer-insights.littlestreamsoftware.com/api/v1/customers?page%5Bcursor%5D=abc123"
  },
  "data": [
    {
      "type": "customer",
      "id": "123456",
      "attributes": {
        "remote_created_at": "2016-04-13T18:31:51.000Z",
        "remote_updated_at": "2018-05-11T22:05:16.000Z",
        "first_name": "Eric",
        "last_name": "Davis",
        "email": "customer@example.com",
        "email_marketing_consent": true,
        "sms_marketing_consent": true,
        "created_at": "2016-11-14T22:26:48.601Z",
        "updated_at": "2022-01-26T17:36:14.440Z",
        "ltv_cents": 5700,
        "ltv_currency": "USD",
        "orders_count": 1,
        "recent_order_at": "2016-04-13T18:32:03.000Z",
        "recency_score": 4,
        "frequency_score": 1,
        "monetary_score": 1,
        "rfm": 411,
        "grade": "D",
        "acquisition_source": "web",
        "cohort": "2022-04",
        "segments": [
          "Average spender",
          "Promising new",
          "Recent low spender (RM)"
        ]
      },
      "links": {
        "self": "https://repeat-customer-insights.littlestreamsoftware.com/api/v1/customers/123456"
      }
    },
    { <a second customer> }
  ],
  "jsonapi": {
    "version": "1.0"
  }
}

Customers / View a single Customer

To request a single customer, make a GET request to the customer's specific endpoint based on their id.

Endpoint

GET /api/v1/customers/<id>

Example

GET https://repeat-customer-insights.littlestreamsoftware.com/api/v1/customers/123456

Response

{
  "data": {
    "type": "customer",
    "id": "123456",
    "attributes": {
      "remote_created_at": "2016-04-13T18:31:51.000Z",
      "remote_updated_at": "2018-05-11T22:05:16.000Z",
      "first_name": "Eric",
      "last_name": "Davis",
      "email": "customer@example.com",
      "email_marketing_consent": true,
      "sms_marketing_consent": true,
      "created_at": "2016-11-14T22:26:48.601Z",
      "updated_at": "2022-01-26T17:36:14.440Z",
      "ltv_cents": 5700,
      "ltv_currency": "USD",
      "orders_count": 1,
      "recent_order_at": "2016-04-13T18:32:03.000Z",
      "recency_score": 4,
      "frequency_score": 1,
      "monetary_score": 1,
      "rfm": 411,
      "grade": "D",
      "acquisition_source": "web",
      "cohort": "2022-04",
      "segments": [
        "Average spender",
        "Promising new",
        "Recent low spender (RM)"
      ]
    },
    "links": {
      "self": "https://repeat-customer-insights.littlestreamsoftware.com/api/v1/customers/123456"
  },
  "jsonapi": {
    "version": "1.0"
  }
}

Errors

The API use standard HTTP error codes. Some codes come with additional information as follows.

401

The API request is unauthorized. Ensure you have set the Authentication header correctly and your account has access to the API.

404

The resource cannot be found in your account. Ensure you are using the correct id parameter. If you have multiple accounts, ensure you are using the correct Authentication for the resource.

422

The request has data formatted incorrectly. Check that all data is encoded and that there are no syntax errors in the data.

429

You have reached the limit of your API requests. See API limits section.

Further Help

If you need further help, more detailed articles are listed in the API section of the Knowledge Base.

Any API issues should be sent to app support, either using the support widget at the bottom of the page or emailed to the address listed on the Knowledge Base.

Do not send or include files with your API token in them. Remember, it's your API password and sending it could result in a data leak for your organization.

Changelog

Would you like a daily tip about Shopify?

Each tip includes a way to improve your store: customer analysis, analytics, customer acquisition, CRO... plus plenty of puns and amazing alliterations.