1. Home
  2. For Developers
  3. REST API for Purchase Nudges

REST API for Purchase Nudges

Nudgify’s REST API allows you to show the data you want in your Purchase Nudges without having to rely on any third party integration. Our API makes it easy for developers to turn purchases into Social Proof.

This documentation describes how to successfully call the Nudgify API to show you order data in Nudges. Are you looking to show sign-ups or other conversions that do not include line item information? Go to our API documentation for sign-ups.

Before you start

For the Purchase Nudges, requests are made to: https://app.nudgify.com/api/purchases

You will need access to the following:
– Your Nudgify Site Key
– Your Nudgify API Key

You can find the Site and API Keys for each site in your Nudgify account on your Sites page.

api social proof

Authentication

The Nudgify API uses HTTP Bearer Authentication to authenticate requests. This allows you to protect the URLs on your web server so that only you and Nudgify can access them.

You use your Nudgify API key as the bearer token. You can find your API Key in your Nudgify account settings. Use: Authorization: Bearer <API key>

Be sure to keep your API Key secure. Do not share your API key in publicly accessible areas such as GitHub, client-side code, and so forth.

All requests must be secure, i.e. https, not http.

Required headers

accept: application/json
content-type: application/json

Parameters

You can use the parameters below to push your orders into your Purchase Nudges.

Field Type Required? Description
site_key uuid required The id we use to identify your site
orders array or null required
We use this to identify the type of Nudge we send the data to, in this case: the Purchase Nudge
order_id integer required The order-id we use to identify which items are part of the same order
date date (follow the format Y-m-d H:i:s) required The date we use to show in the Nudge how long ago the conversion took place. We use UTC for the timezone, so make sure you send your date in UTC for accurate time on your Nudges
email email required The email address of the user to identify that there has been a new conversion
first_name string or null optional The first name of the user, to show in the Nudge
last_name string or null optional The last name of the user, to show in the Nudge
ip string or null optional The ip address of the user, to show the location in case city/state/country are not available
city string or null optional The city of the user, to show in the Nudge
state string or null optional The state of the user, to show in the Nudge
country string (Max characters 2 e.g: GB or US) optional The Country of the user, to show in the Nudge
line_items array or null optional We use this to identify that what follows is part of line item information
item_id string or null optional The id we use to identify the item that was ordered
item_variation_id string or null optional The id we use to identify the variation (colour, size etc.) of the item that was ordered
item_name string or null optional The name of the item that was ordered, to show in the Nudge
item_link url or null optional The product page that we link to from the item name in the Nudge
image_url url or null optional The product image that we show in the Nudge

Example request body

{
  "site_key": "510eeb08-814e-456a-b5c1-8c7c70cc4c00",
  "orders": 
  [{
    "order_id": "1111",
    "date": "2021-04-15 04:29:42",
    "email": "john0934@gmail.com",
    "first_name": "Leon",
    "last_name" : "Gomes",
    "ip": "92.21.8.106",
    "city": "Los Angeles",
    "state": "California",
    "country": "US",
    "line_items": 
    [{
      "item_id": "786",
      "item_variation_id": "SKU-786",
      "item_name": "LCD Display (Upgrade)",
      "item_link": "https://stroem.com/product/lcd",
      "image_url": "https://stroem.com/wp-content/LCD.png"
      },
      {
      "item_id": "777",
      "item_variation_id": "SKU-777",
      "item_name": "Throttle",
      "item_link": "https://stroem.com/product/upg",
      "image_url": "https://stroem.com/wp-content/Upg.png"
    }]
  }]
}

Example request

curl --request POST \
--url https://app.nudgify.com/api/purchases \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'authorization: Bearer 
IqJ4GRuODEsFBamKJb3LYXfEf456rVXWeRAkFnvCtXmlbq' \
--data '{
  "site_key":"510eeb08-814e-456a-b5c1-8c7c70cc4c00",
  "orders":[{
    "order_id":"1111","date":"2021-04-15 04:29:42",
    "email":"john0934@gmail.com",
    "first_name":"Leon",
    "last_name":"Gomes",
    "ip":"92.21.8.106",
    "city":"Los Angeles",
    "state":"California",
    "country":"US",
    "line_items":[{
      "item_id":"786",
      "item_variation_id":"SKU-786",
      "item_name":"LCD Display (Upgrade)",
      "item_link":"https://stroem.com/product/lcd",
      "image_url":"https://stroem.com/wp-content/LCD.png"
    }]
  }]
}'

Success response

If your API request has been successful, you get a success response like the one below.

Response type: Json

{ 
  "message": "Request successfully saved.", 
  "data": [ "142" ] 
}
Field Type Description
message string Indicates that the request has been successful
data array In case of success shows the ids of all the records saved in our database
errors array In case of an error shows the possible error messages

If your request has been successful, you can find the order data that has been sent through in the Purchases tab of your Nudgify Data Feeds.

Error response

If your API request has failed, you get an error response like the one below.

Response type: Json

{
  "message": "Bad Request.",
  "errors": {
    "orders.0.email": [
    "Email is required."
    ],
    "orders.1.date": [
    "Date is required."
    ]
  }
}

Possible errors

To help you identify why your API request has failed and what you need to adjust to get a success response, we have made an overview of the possible error messages and what they mean.

HTTP Status Code Summary 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
403 – Forbidden
The API key doesn’t have permissions to perform the request
404 – Not Found
The requested resource doesn’t exist
409 – Conflict
The request conflicts with another request
429 – Too Many Requests
Too many requests hit the API too quickly
500, 502, 503, 504 – Server Errors
Something went wrong on Nudgify’s end

 

Error Message Description
Expected Field Validation Error Messages
Bad Request In case of any field validation error the bad request message is displayed
Site key is required
No Site key has been provided, please provide your Site key. You can find it in your Nudgify account
Site key must be valid
The Site key you provided does not follow the format of our Site keys. You can find your Site key in your Nudgify account
Email is required No email address has been provided, please provide an email address
Email does not match the required format yourname@example.com Please provide an email address that follows the format yourname@example.com
Date is required No date has been provided, please provide a date
Date does not match the required UTC format
Please provide a date that follows the format Y-m-d H:i:s, e.g. 2021-04-15 04:29:42
Country can only contain letters
The country name your provided contains other characters than letters. Please enter the country name in ISO 3166-1 alpha-2 format
Country may not be greater than 2 characters
The country name your provided contains more than 2 characters. Please enter the country name in ISO 3166-1 alpha-2 format
Order id is required No order id has been provided, please enter and order id
Order id must be an integer The order id you provided is not an integer, please enter an integer for the order id
Other Validation Messages
Unauthenticated
The Bearer token is not correct. It should follow this format: Bearer {API key}. It most likely means that the API key you provided does not match your Nudgify account. You can find your API key in your Nudgify account.
Authorization Failure, Invalid Site Key
The Site key you provided does not match your Nudgify account. You can find your Site key in your Nudgify account
Forbidden, REST API integration is not enabled
Nudgify has not enabled the API for its users. Please contact Nudgify support to inquire about this
Please configure the REST API to the nudges in order to use this data
You have not enabled the REST API feature in your Nudge set-up. In your Nudgify account, go to a Sign-up or Purchase Nudge> Configure REST API > I’ve done it
REST API integration is disabled on your site. Please contact support
The API integration has been disabled on your site. Please contact Nudgify support so we can investigate
Upgrade your plan to use the REST API REST API feature is not available in the Lite plan. Please upgrade to use it

If you have any questions or comments about our API, please don’t hesitate to get in touch via our support chat.

Updated on April 23, 2021

Was this article helpful?

Related Articles