Data formats

Date and time will be expressed as ISO8601 date and time in UTC (e.g., "2015-09-23T16:01:35Z").
Floats will be represented as Strings with decimals separated by a dot "." (e.g., "169.99").

Accepted Media Types

The Ifeelgoods API returns mainly JSON documents (application/json). However, the API has the ability to generate and return e-cards directly as PDF documents (application/pdf).

Here the list of all the accepted types:

application/json
application/json; pretty=true (not to use in production)
application/pdf

HTTP Status Codes

The Ifeelgoods API attempts to use appropriate conventional HTTP response codes. 2xx codes indicate succesfull requests, 4xx codes are intended for cases in which there is an error in the request and 5xx when the Ifeelgoods' servers are experiencing troubles (which is rare 😉).

Status Code	Text	Description
200	OK	Everything is OK!
201	Created	A resource has been successfully created after a POST request.
400	Bad Request	The request is malformed and cannot be understood.
401	Unauthorized	You need to be signed-in to perform this action.
403	Forbidden	You are not allowed to perform this action.
404	Not Found	The resource or action does not exist.
406	Not Acceptable	The media type specified by the Accept header is not acceptable.
409	Conflict	The resource has already been modified, please reload before submitting again.
412	Precondition Failed	Version specified in If-Match header does not match with database one. Please reload the resource.
422	Unprocessable Entity	The request is not valid and cannot be processed, please check parameter requirements and format in the documentation.
429	Too Many Requests	You sent too many requests in a given amount of time.
500	Internal Server Error	An unexpected error has happened.

Error handling best practice

In case of 5XX error, a good practice is to allow your system to retry the request (automatically or manually).
Sometimes, 504 errors can occur (usually due to a temporary server overload), it does not means that the code has not been created on our side, you will be billed accordingly. A retry is possible thanks to idempotency.
Please refer to the following section in the FAQ to understand the importance of order_id in case of 5XX errors.

Responses for successful requests

Single resource

Every responses including a single resource provide a data section which contains the detailled resource object. In addition, some resources contain a version top-level attribute that helps prevent simultaneous updates of a resource from overwriting each other. When a PUT request is sent, the value should match the one stored in order to be accepted.

{
  "data": {...},
  "version": 42
}

Resources collection & pagination

{
  "data": {...},
  "paging": {
    "page": 1,
    "per_page": 20,
    "total": 214
  }
}

Response for errors

When the Ifeelgoods API returns error messages, response looks like this:

{
  "error_name": "not_found",
  "error_message": "The resource or action does not exist."
}

Error types

Error name	Message
authentication_system_not_supported	The authentication system provided to perform the redemption has not been activated in the promotion settings.
bad_request	The request is malformed and cannot be understood.
conflict	The resource has already been modified, please reload before submitting again.
conflict_uniqueness	The resource does not satisfy a uniqueness constraint.
forbidden	You are not allowed to perform this action.
invalid_request	The request is not valid and cannot be processed, please check parameter requirements and format in the documentation.
invalid_token	The token provided to perform the redemption is not valid.
invalid_user	The user provided to perform the redemption is not valid.
not_acceptable	The media type specified by the Accept header is not acceptable.
not_found	The resource or action does not exist.
operation_refused	This operation is not allowed.
precondition_failed	Version specified in If-Match header does not match with database one. Please reload the resource.
sorting_limit_exceeded	The number of returned rows exceeds the sorting limit (5000 rows). Please adjust the query parameters to reduce the size.
unauthorized	You need to be signed-in to perform this action.
user_mismatch	The user provided to perform the redemption does not match the user associated to the redemption.
offer_mismatch	The `order_id` provided to perform the redemption is already used but on another reward.
no_user_linked	No user provided to perform the redemption