{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"609882d7-e68a-4f93-91ae-6ae29b7de80c","name":"Loyalty Member/Partner API v24.8.7","description":"# **Overview**\n\nThe IRT Third Party Partner API is a robust HTTP API employing RPC (Remote Procedure Call) technology rather than REST, and it is designed to deliver JSON format responses. This API empowers our Third Party Partners of IRT to seamlessly integrate and automate interactions with their respective programs. It is widely adopted by our partners for incorporating a range of cardholder services - such as enrollment, updating enrollment data, and balance inquiries - directly into their digital platforms, including websites, kiosks, and mobile applications. While these are its primary applications, the IRT Third Party Partner API also offers extensive functionalities that extend well beyond the basic cardholder services. Detailed documentation for each API call is available.\n\n# Using the Postman collection\n\nYou can [view collection in your workspace](https://elements.getpostman.com/redirect?entityId=20512336-40331596-cd3c-4a63-ace1-69512ce7cb91&entityType=collection&workspaceId=21566a39-75f5-4c5d-adfc-a33fbb3862d6) and interact with the api directly by creating your own environment which allows you to set the 'user' and 'pass' variables or you can [fork the collection in to your workspace](https://god.gw.postman.com/run-collection/20512336-40331596-cd3c-4a63-ace1-69512ce7cb91?action=collection%2Ffork&source=rip_markdown&collection-url=entityId%3D20512336-40331596-cd3c-4a63-ace1-69512ce7cb91%26entityType%3Dcollection%26workspaceId%3D21566a39-75f5-4c5d-adfc-a33fbb3862d6).\n\nIgnite Retail Technology advises developers and patners to keep an eye on this collection for new updates by clicking the 'eyeball' icon (\"watch\") located [at the top right corner of the collection on our workspace](https://www.postman.com/igniteretail/workspace/irt-public/collection/20512336-40331596-cd3c-4a63-ace1-69512ce7cb91).\n\n# Setup\n\nTo initiate the use of the API, IRT will create a unique set of credentials (\"user\" and \"pass) specific to your loyalty program. These credentials are essential for authorizing many of the API calls you will be making. In case you haven't received your username and password, please reach open a [helpdesk ticket](https://customer.support.ignite-retail.com/) at [support.ignite-retail.com](https://support.ignite-retail.com/) to acquire them.\n\n# Authentication\n\nFor backend-to-backend API integrations, authentication is streamlined through the provision of a basic username and password in the data fields of the API call. Additionally, there are scenarios where customers have already established their identity through the login API. In these instances, a JWT (JSON Web Token) is issued. This token should be included in future API requests within the 'Authorization: Bearer' header. Utilizing the JWT is a more secure alternative to repeatedly sending the API password in subsequent calls.\n\nLooking ahead, IRT is set to enhance its authentication processes in 2024 and 2025. This advancement involves the transition to an OAuth 2.0 framework, which will be implemented for both loyalty member authentication and backend-to-backend system verifications. This new system will employ Machine-to-Machine (M2M) OAuth credentials, significantly elevating the security and efficiency of our API interactions.\n\n# Safeguard Your Customer Data!\n\nTo ensure the utmost security of your customers' private information, it is crucial to always interact with the IRT Third Party Partner API exclusively via a secure HTTPS connection. This practice not only protects sensitive customer data but also ensures that your API username and password are encrypted during transmission across the network.\n\nFor secure API interactions, use the following URL: [https://www.rewardsbutler.com/api/](https://www.rewardsbutler.com/api/).  \nNever use the insecure http:// version.\n\nSecurity Modes\n\nThe Third Party Partner API has multiple security modes: high, medium and low. This changes what calls are available. For example, you may not want certain vendors of yours to be able to export customer data or receive certain PII fields. At the time of your WDK Integration and development process, IRT Staff will inform you of the mode the system is in.\n\nIf your API integration is set up in high security mode, certain API calls will require additional parameters. Parameters that are required in high security mode will be labelled accordingly.\n\n# API Implementation Details\n\nFor all API interactions, the consistent endpoint URL is: [https://www.rewardsbutler.com/api/](https://www.rewardsbutler.com/api/). This API is configured to exclusively handle POST requests.\n\nEvery response from the API is structured as a valid JSON object. When making a POST request, authentication credentials, call specifiers, and other parameters should be included in the body as key=value pairs. This format is known as 'x-www-form-urlencoded' not unlike a HTTP form post. It is important to note that all these POST body parameters are sensitive to case differences (for example, 'Email' and 'email' are treated as distinct parameters).\n\nRegarding HTTP status codes, the API responds with just two: 200 and 500. The 500 status code indicates an irrecoverable internal server error, while the 200 status code is used for all other responses, including those involving errors in the request. Further details on handling these responses are provided in the following section.\n\n# Status Codes\n\nIrrespective of the outcome, our server will consistently return an HTTP status code of 200 for all scenarios, except for 500 errors which denote internal server issues. To ascertain the result (success or failure) of an API call, you should refer to the JSON response object, rather than relying on varying HTTP status codes.\n\nEach JSON response contains a minimum of two key elements: `status` and `message`. The `status` key indicates the outcome of the call, represented by an integer ranging from 0 to 5, where each number corresponds to a specific condition. The `message` key provides a human-readable explanation of the result, whether it's a success or a failure.\n\nHere's a breakdown of the status codes:\n\n- 0: Success\n    \n- 1: Invalid card\n    \n- 2: Already enrolled\n    \n- 4: Fatal error\n    \n- 5: Not enrolled\n    \n- 6: Phone already used\n    \n- 7: Phone verification required\n    \n- 8: Invalid account\n    \n- 401: Unauthorized\n    \n- 422: Invalid idempotency key (HTTP Unprocessable entity)\n    \n- 409: Idempotency key hash mismatch (HTTP 409 Conflict)\n    \n\n**Example Responses:**\n\n- Success Case: `{\"status\": 0, \"message\": \"Member Registered Successfully.\"}`\n    \n- Failure Case: `{\"status\": 4, \"message\": \"Invalid API request.\"}`\n    \n\n# Getting Help\n\nTo ask questions or receive support as you integrate with our API, please email [wdk-requests@ignite-retail.com](https://mailto:wdk-requests@ignite-retail.com) _**or**_ open a WDK Request service desk ticket at [support.ignite-retail.com](https://support.ignite-retail.com/).\n\nIf there are questions on how to implement desired functionality or if unexpected errors occur please send an email to [wdk-requests@kickbackpoints.com](https://mailto:wdk-requests@kickbackpoints.com) This will create an autoamted ticket that is entered into our support queue. This queue is monitored and resonded to by the developers who work on this API.\n\n# Interactive API Documentation Overview\n\nhis documentation is uniquely interactive, crafted as a Postman API collection, enabling you to actively test each API call we offer and instantly view the corresponding responses.\n\nSetting Up:\n\n- Begin by entering your credentials: simply input your username and password once into the collection variables. Select \"IRT Third Party Partner API vx.xx\", and then enter your values for \"user\" and \"pass\".\n    \n- The API calls are conveniently organized into categories. You can expand or collapse these categories to explore the specific calls you're interested in.\n    \n\nTesting API Calls:\n\n- To test an API call, fill in all the required parameters and click 'Send'. You'll shortly receive a comprehensive breakdown of the response from the IRT Third Party Partner API.\n    \n\nCurl Command Examples:\n\n- For added convenience, each API call includes a sample Curl command. These commands dynamically update as you input data for each call, and are formatted for easy copy-and-paste into your terminal.\n    \n\nExample Responses:\n\n- Included in the documentation are sample responses for each call. These examples are meant to illustrate common responses and do not encompass every possible outcome from the API call.\n    \n\n**Important Warning:**\n\n- The API credentials provided by IRT are linked to your production account and loyalty program database. Therefore, treat this interactive documentation as a live production integration. Any changes made to cards through this platform will have permanent effects on your program. For testing purposes, IRT can supply test card numbers upon request.\n    \n\n# Handling Optional Fields\n\nFields not explicitly labeled as 'required' offer flexibility in how they can be handled in the POST request. These optional fields can be approached in two ways:\n\n1. Omit the field entirely from the POST body. Doing this leaves the corresponding field's value in the database unchanged.\n    \n2. Include the field in the POST body but without assigning any value. This action will result in the clearing of that field's data in the database.\n    \n\nFor better understanding, here's an example of how to clear a field using a POST request. In this scenario, we're removing a cardholder's email address from their account:\n\n``` bash\ncall=update\nuser=example\npass=123456789\ncardnumber=1234567812345678\nPIN=1234\nEmail=\n\n ```\n\n**Important Note:**  \nIn this documentation, both the example Curl commands and the 'Try it!' feature are configured to transmit blank optional fields without any value. Consequently, any optional fields you leave unfilled when executing API calls through this documentation will result in the clearing of those fields in the database. Please exercise caution and intentionality when leaving optional fields blank.\n\n# Common Use Case Examples & Best Practices\n\nThis section is designed to help you understand which API calls to use in common scenarios.\n\n## Checking Point Balance\n\n- **Step 1:** Your application requests the user's card number.\n    \n- **Step 2:** The application executes the `getbalance` API call using the card number.\n    \n- **Step 3:** Actions based on the `getbalance` call result:\n    \n    - **Success Case** (status 0): Display the `data.balance` value to the user.\n        \n    - **Invalid Card Case** (status 1): Show the `message` key to the user and prompt them to retry.\n        \n\n## Enrolling a New Card\n\n- **Step 1:** Your application requests the user's card number.\n    \n- **Step 2:** The application uses the `check_registered` API call with the card number.\n    \n- **Step 3:** Actions based on the `check_registered` call result:\n    \n    - **Already Enrolled Case** (status 0): Inform the user that the card is already registered and direct them to log in.\n        \n    - **Not Enrolled Case** (status 5): Display an enrollment form to the cardholder.\n        \n    - **Cancelled Card Case** (status 1): Notify the user that the card cannot be enrolled and advise contacting customer support.\n        \n- **Step 4:** For non-enrolled cards, users complete the enrollment form. The form data should be submitted using the `register` API call. Ensure client-side validation of required fields for immediate user feedback.\n    \n    - **Successful Registration** (status 0): Display a confirmation message and optionally the current point balance using `getbalance`.\n        \n    - **Registration Error** (non-zero status): Show the error message and allow the user to correct and resubmit the form.\n        \n\n## Updating Cardholder Information\n\n- **Step 1:** Your application requests the user's card number and PIN.\n    \n- **Step 2:** The application uses the `getinfo` API call with these details.\n    \n- **Step 3:** Actions based on the `getinfo` call result:\n    \n    - **Success Case** (status 0): Use response data to populate and display a user info update form.\n        \n    - **Not Enrolled Case** (status 5): Inform the user about the need to enroll and ideally redirect to the enrollment form.\n        \n    - **Fatal Error Case** (status 4): Show the error message and prompt the user to re-enter card number and PIN.\n        \n- **Step 4:** For successful `getinfo` calls, users update their details in the form. Submit these updates using the `update` API call.\n    \n    - **Update Success** (status 0): Show a confirmation message.\n        \n    - **Update Error** (non-zero status): Display the error message and allow the user to correct and resubmit the form.\n        \n\n# Change log\n\n| **Version** | **Notes** |\n| --- | --- |\n| v24.6.27 | **Release Date:** \\[6/27/24\\]**Version:** \\[24.6.27\\]  <br>  <br>**New API Calls  <br>**\\- ListStoredValuePrograms  <br>\\- AdjustStoredValuePrograms  <br>\\- Hearbeat (system status)  <br>  <br>**Enhancements:**  <br>\\- Added pointType to issuepoints and redeem api calls to enable the issuance and redemption from Annual and Spendable Points.  <br>\\- The GetIssues API call returns four new field:  <br>\\- pos_transaction_number  <br>\\- loyalty_transaction_number  <br>\\- name - Name of the store as configured in the loyalty host  <br>\\- store_number - Number of the store as configured in the loyalty host  <br>\\- Added employee_number and employee_store_number to all card enrollment **API calls:**  <br>\\- Register,  <br>\\- Update,  <br>\\- NewCustomerAccount,  <br>\\- GetCustomerAccountInfo,  <br>\\- MergeCustomerAccount  <br>  <br>\\- Improved opt-in-preferences settings as we move to deprecate 'flag1'  <br>  <br>\\- **idempotencyKey field** added to Redeem, IssuePoints, and RedeemReward API calls.  <br>  <br>_Without an idempotencyKey: If you omit the idempotencyKey, the system will treat each API call as a new, separate transaction.  <br>_  <br>_With an idempotencyKey: If you include the idempotencyKey in the API call, the system will check if it's a duplicate request. If the request is identical to a previous one (down to the idempotencyKey and data values matching the prior request), then the response from the initial successful call will be returned, without executing the operation again. However, if the system identifies a call with the same idempotencyKey but different data values, it returns an error message to prevent misused operations:  <br>_{  <br>\"status\": 409,  <br>\"message\": \"IDEMPOTENCY_KEY_HASH_MISMATCH: Request has changed since the original request on 2022-03-05T21:12:38+00:00\"  <br>} |\n| v24.6.12 | **Release Date:** \\[6/12/24\\]**Version:** \\[24.6.12\\]  <br>  <br>**New API Calls  <br>****\\- NewCustomerAccount  <br>\\- GetCustomerAccountInfo  <br>\\- MergeCustomerAccount |","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":true,"owner":"20512336","team":3354874,"collectionId":"609882d7-e68a-4f93-91ae-6ae29b7de80c","publishedId":"2s9YythLiG","public":true,"publicUrl":"https://documenter-api.postman.tech/view/20512336/2s9YythLiG","privateUrl":"https://go.postman.co/documentation/20512336-609882d7-e68a-4f93-91ae-6ae29b7de80c","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"documentationLayout":"classic-double-column","customisation":{"metaTags":[{"name":"description","value":""},{"name":"title","value":""}],"appearance":{"default":"light","themes":[{"name":"dark","logo":"https://content.pstmn.io/30df0357-61c1-4c63-927f-8b5683e30d4d/SWduaXRlIFNwYXJrIGxvZ28gZ3JhZGllbnQgb24gYmxhY2sgSFoucG5n","colors":{"top-bar":"212121","right-sidebar":"303030","highlight":"FF6C37"}},{"name":"light","logo":"https://content.pstmn.io/9c7db768-fd84-4a7b-9671-11b144c6baf8/SWduaXRlIFNwYXJrIGxvZ28gc29saWQgSFoucG5n","colors":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"}}]}},"version":"8.10.0","publishDate":"2024-01-31T22:28:47.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{"title":"","description":""},"logos":{"logoLight":"https://content.pstmn.io/9c7db768-fd84-4a7b-9671-11b144c6baf8/SWduaXRlIFNwYXJrIGxvZ28gc29saWQgSFoucG5n","logoDark":"https://content.pstmn.io/30df0357-61c1-4c63-927f-8b5683e30d4d/SWduaXRlIFNwYXJrIGxvZ28gZ3JhZGllbnQgb24gYmxhY2sgSFoucG5n"}},"statusCode":200},"environments":[{"name":"IRT Third Party Partner API Environment","id":"50ce6740-7ec5-4317-a7c0-2ffecc787521","owner":"20512336","values":[{"key":"baseUrl","value":"https://www.rewardsbutler.com/api/","enabled":true,"type":"default"},{"key":"user","value":"","enabled":true,"type":"secret"},{"key":"pass","value":"","enabled":true,"type":"secret"}],"published":true}],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/1e8f27feda1c18e5980639d5ae93e42fe69a8095226f3e1c359ab13336548a1c","favicon":"https://res.cloudinary.com/postman/image/upload/v1767995174/team/4a78d8df4c10f02e574dd4b5e99933fe.ico"},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"},{"label":"IRT Third Party Partner API Environment","value":"20512336-50ce6740-7ec5-4317-a7c0-2ffecc787521"}],"canonicalUrl":"https://documenter.gw.postman.com/view/metadata/2s9YythLiG"}