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 CodeTextDescription
200OKEverything is OK!
201CreatedA resource has been successfully created after a POST request.
400Bad RequestThe request is malformed and cannot be understood.
401UnauthorizedYou need to be signed-in to perform this action.
403ForbiddenYou are not allowed to perform this action.
404Not FoundThe resource or action does not exist.
406Not AcceptableThe media type specified by the Accept header is not acceptable.
409ConflictThe resource has already been modified, please reload before submitting again.
412Precondition FailedVersion specified in If-Match header does not match with database one. Please reload the resource.
422Unprocessable EntityThe request is not valid and cannot be processed, please check parameter requirements and format in the documentation.
429Too Many RequestsYou sent too many requests in a given amount of time.
500Internal Server ErrorAn 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 nameMessage
authentication_system_not_supportedThe authentication system provided to perform the redemption has not been activated in the promotion settings.
bad_requestThe request is malformed and cannot be understood.
conflictThe resource has already been modified, please reload before submitting again.
conflict_uniquenessThe resource does not satisfy a uniqueness constraint.
forbiddenYou are not allowed to perform this action.
invalid_requestThe request is not valid and cannot be processed, please check parameter requirements and format in the documentation.
invalid_tokenThe token provided to perform the redemption is not valid.
invalid_userThe user provided to perform the redemption is not valid.
not_acceptableThe media type specified by the Accept header is not acceptable.
not_foundThe resource or action does not exist.
operation_refusedThis operation is not allowed.
precondition_failedVersion specified in If-Match header does not match with database one. Please reload the resource.
sorting_limit_exceededThe number of returned rows exceeds the sorting limit (5000 rows). Please adjust the query parameters to reduce the size.
unauthorizedYou need to be signed-in to perform this action.
user_mismatchThe user provided to perform the redemption does not match the user associated to the redemption.
offer_mismatchThe order_id provided to perform the redemption is already used but on another reward.
no_user_linkedNo user provided to perform the redemption