{ "openapi": "3.0.1", "paths": { "/fulfillment/v2/accounts/me": { "get": { "summary": "Get current account", "tags": [ "Accounts" ], "operationId": "getCurrentAccount", "description": "Use this function to get the details of your current account", "security": [ { "bearer_auth": [] }, { "api_key": [], "api_secret": [] } ], "responses": { "200": { "description": "The requested account details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/account" } } } } } } } } }, "/fulfillment/v2/clients/{client_id}/promotions": { "get": { "summary": "List all Promotions", "tags": [ "Promotions" ], "operationId": "listClientPromotions", "description": "Use this function to list all the promotions of a specific client", "security": [ { "bearer_auth": [] }, { "api_key": [], "api_secret": [] } ], "parameters": [ { "name": "client_id", "in": "path", "required": true, "description": "The client identifier", "schema": { "type": "string" } }, { "name": "page", "in": "query", "schema": { "$ref": "#/components/schemas/page_parameter" }, "required": false }, { "name": "per_page", "in": "query", "schema": { "$ref": "#/components/schemas/per_page_parameter" }, "required": false } ], "responses": { "200": { "description": "A list of promotions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/promotion_details" } }, "paging": { "type": "object", "properties": { "page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 20 }, "total": { "type": "integer", "example": 100 } } } } } } } }, "401": { "description": "Authentication credentials are missing or invalid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error_name": { "type": "string", "example": "unauthorized" }, "error_message": { "type": "string", "example": "Authentication credentials are missing or invalid.", "nullable": true } } } } } } } } }, "/fulfillment/v2/promotions/{promotion_id}": { "get": { "summary": "Get a promotion", "tags": [ "Promotions" ], "operationId": "getPromotionByID", "description": "Use this function to retrieve detailed information about a promotion and the list of the rewards available for delivery as part of this operation", "security": [ { "bearer_auth": [] }, { "api_key": [], "api_secret": [] } ], "parameters": [ { "name": "promotion_id", "in": "path", "required": true, "description": "The promotion identifier", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The requested promotion details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/promotion_details" } } } } } }, "401": { "description": "The authenticated user does not have permission to access this resource.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error_name": { "type": "string", "example": "forbidden" }, "error_message": { "type": "string", "example": "The authenticated user does not have permission to access this resource.", "nullable": true } } } } } }, "404": { "description": "The requested resource could not be found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error_name": { "type": "string", "example": "not_found" }, "error_message": { "type": "string", "example": "The requested resource could not be found.", "nullable": true } } } } } } } } }, "/fulfillment/v2/rewards": { "get": { "summary": "List all Rewards", "tags": [ "Rewards" ], "operationId": "listRewards", "description": "Use this function to list all the rewards from the Ifeelgoods Catalog", "security": [ { "bearer_auth": [] }, { "api_key": [], "api_secret": [] } ], "parameters": [ { "name": "sku", "in": "query", "schema": { "type": "string", "example": "sku1,sku2,sku3" }, "required": false, "description": "Comma-separated list of reward SKUs to filter by" }, { "name": "client_id", "in": "query", "required": false, "description": "Unique Client identifier (used to retrieve cost with discount)", "schema": { "type": "string" } }, { "name": "page", "in": "query", "schema": { "$ref": "#/components/schemas/page_parameter" }, "required": false }, { "name": "per_page", "in": "query", "schema": { "$ref": "#/components/schemas/per_page_parameter" }, "required": false } ], "responses": { "200": { "description": "A list of rewards.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/reward_details" } }, "paging": { "type": "object", "properties": { "page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 20 }, "total": { "type": "integer", "example": 100 } } } } } } } }, "401": { "description": "Authentication credentials are missing or invalid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error_name": { "type": "string", "example": "unauthorized" }, "error_message": { "type": "string", "example": "Authentication credentials are missing or invalid.", "nullable": true } } } } } } } } }, "/fulfillment/v2/rewards/{sku}": { "get": { "summary": "Get a Reward", "tags": [ "Rewards" ], "operationId": "getRewardBySKU", "description": "Use this function to retrieve detailed description about a reward", "security": [ { "bearer_auth": [] }, { "api_key": [], "api_secret": [] } ], "parameters": [ { "name": "sku", "in": "path", "required": true, "description": "The reward SKU", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The requested reward details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/reward_details" } } } } } }, "401": { "description": "The authenticated user does not have permission to access this resource.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error_name": { "type": "string", "example": "forbidden" }, "error_message": { "type": "string", "example": "The authenticated user does not have permission to access this resource.", "nullable": true } } } } } }, "404": { "description": "The requested resource could not be found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error_name": { "type": "string", "example": "not_found" }, "error_message": { "type": "string", "example": "The requested resource could not be found.", "nullable": true } } } } } } } } }, "/fulfillment/v2/promotions/{promotion_id}/redemptions": { "get": { "summary": "List all Redemptions", "tags": [ "Redemptions" ], "operationId": "listRedemptions", "description": "Use this function to list the status of all redemptions created as part of a promotion.", "security": [ { "bearer_auth": [] }, { "api_key": [], "api_secret": [] } ], "parameters": [ { "name": "promotion_id", "in": "path", "required": true, "description": "The promotion identifier", "schema": { "type": "string" } }, { "name": "reward_sku", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "email", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "order_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "state", "in": "query", "schema": { "type": "string", "enum": [ "pending", "booked", "redeemed", "denied", "failed", "refunded", "blocked", "canceled", "expired" ] }, "description": "Redemption state filter (eg. `pending`, `redeemed`, `canceled`, etc.)", "required": false }, { "name": "redeemed_datetime_start", "in": "query", "schema": { "type": "string", "format": "date-time" }, "required": false, "description": "Filter redemptions redeemed on or after this datetime (ISO 8601 format, e.g. `2024-01-01T00:00:00Z`)" }, { "name": "redeemed_datetime_end", "in": "query", "schema": { "type": "string", "format": "date-time" }, "required": false, "description": "Filter redemptions redeemed on or before this datetime (ISO 8601 format, e.g. `2024-01-31T23:59:59Z`)" }, { "name": "activation_datetime_start", "in": "query", "schema": { "type": "string", "format": "date-time" }, "required": false, "description": "Filter redemptions activated on or after this datetime (ISO 8601 format, e.g. `2024-01-01T00:00:00Z`)" }, { "name": "activation_datetime_end", "in": "query", "schema": { "type": "string", "format": "date-time" }, "required": false, "description": "Filter redemptions activated on or before this datetime (ISO 8601 format, e.g. `2024-01-31T23:59:59Z`)" }, { "name": "refund_datetime_start", "in": "query", "schema": { "type": "string", "format": "date-time" }, "required": false, "description": "Filter redemptions refunded on or after this datetime (ISO 8601 format, e.g. `2024-01-01T00:00:00Z`)" }, { "name": "refund_datetime_end", "in": "query", "schema": { "type": "string", "format": "date-time" }, "required": false, "description": "Filter redemptions refunded on or before this datetime (ISO 8601 format, e.g. `2024-01-31T23:59:59Z`)" }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "activation_datetime", "-activation_datetime", "updated_datetime", "-updated_datetime", "redeem_datetime", "-redeem_datetime", "refund_datetime", "-refund_datetime" ] }, "required": false, "description": "Field to sort by, prefixed with `-` for descending order (e.g. `activation_datetime` or `-activation_datetime`)" }, { "name": "page", "in": "query", "schema": { "$ref": "#/components/schemas/page_parameter" }, "required": false }, { "name": "per_page", "in": "query", "schema": { "$ref": "#/components/schemas/per_page_parameter" }, "required": false } ], "responses": { "200": { "description": "A list of redemptions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/redemption" } }, "paging": { "type": "object", "properties": { "page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 20 }, "total": { "type": "integer", "example": 100 } } } } } } } }, "401": { "description": "Authentication credentials are missing or invalid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error_name": { "type": "string", "example": "unauthorized" }, "error_message": { "type": "string", "example": "Authentication credentials are missing or invalid.", "nullable": true } } } } } } } }, "post": { "summary": "Create a redemption", "tags": [ "Redemptions" ], "operationId": "createRedemption", "description": "Use this function to create a redemption object and initiate a reward delivery.", "security": [ { "bearer_auth": [] }, { "api_key": [], "api_secret": [] } ], "parameters": [ { "name": "promotion_id", "in": "path", "required": true, "description": "The promotion identifier", "schema": { "type": "string" } } ], "responses": { "201": { "description": "The redemption was successfully created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/redemption" } } } }, "application/pdf": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/redemption" } } } } } }, "401": { "description": "Authentication credentials are missing or invalid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error_name": { "type": "string", "example": "unauthorized" }, "error_message": { "type": "string", "example": "Authentication credentials are missing or invalid.", "nullable": true } } } }, "application/pdf": { "schema": { "type": "object", "properties": { "error_name": { "type": "string", "example": "unauthorized" }, "error_message": { "type": "string", "example": "Authentication credentials are missing or invalid.", "nullable": true } } } } } }, "422": { "description": "Invalid Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error_name": { "type": "string", "example": "invalid_request" }, "error_message": { "type": "string", "example": null, "nullable": true } } } }, "application/pdf": { "schema": { "type": "object", "properties": { "error_name": { "type": "string", "example": "invalid_request" }, "error_message": { "type": "string", "example": null, "nullable": true } } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "order_id": { "type": "string", "description": "Must be unique for each redemption" }, "user": { "$ref": "#/components/schemas/user" }, "reward": { "type": "object", "properties": { "sku": { "type": "string", "example": "APP-ITC-10USD-US" } } }, "value": { "type": "object", "properties": { "amount": { "type": "string", "example": "10", "description": "optional - only needed for \"free value\" rewards" } } }, "customization": { "type": "object", "properties": { "pdf": { "type": "object", "properties": { "message": { "type": "string", "example": "I hope you enjoy this reward!" }, "sender_name": { "type": "string", "example": "Martina", "description": "The reward sender name to be printed on the PDF (if applicable)" } } } } } }, "required": [ "order_id", "user", "reward" ] } }, "required": [ "data" ] } } }, "required": true } } }, "/fulfillment/v2/redemptions/{redemption_id}": { "get": { "summary": "Get a redemption", "tags": [ "Redemptions" ], "operationId": "getRedemptionById", "description": "Use this function to retrieve detailed information about a redemption object.", "security": [ { "bearer_auth": [] }, { "api_key": [], "api_secret": [] } ], "parameters": [ { "name": "redemption_id", "in": "path", "required": true, "description": "The redemption identifier", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The requested redemption details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/redemption" } } } }, "application/pdf": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/redemption" } } } } } }, "401": { "description": "The authenticated user does not have permission to access this resource.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error_name": { "type": "string", "example": "forbidden" }, "error_message": { "type": "string", "example": "The authenticated user does not have permission to access this resource.", "nullable": true } } } }, "application/pdf": { "schema": { "type": "object", "properties": { "error_name": { "type": "string", "example": "forbidden" }, "error_message": { "type": "string", "example": "The authenticated user does not have permission to access this resource.", "nullable": true } } } } } }, "404": { "description": "The requested resource could not be found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error_name": { "type": "string", "example": "not_found" }, "error_message": { "type": "string", "example": "The requested resource could not be found.", "nullable": true } } } }, "application/pdf": { "schema": { "type": "object", "properties": { "error_name": { "type": "string", "example": "not_found" }, "error_message": { "type": "string", "example": "The requested resource could not be found.", "nullable": true } } } } } } } } }, "/fulfillment/v2/promotions/{promotion_id}/rewards/{reward_sku}/redemptions/redeem": { "post": { "summary": "Create and Redeem", "tags": [ "Redemptions" ], "operationId": "createAndRedeem", "description": "Use this function to create a redemption object and perform a reward delivery.\nCalling this endpoint on an existing order_id with the exact same parameters will return the existing order.\n", "security": [ { "bearer_auth": [] }, { "api_key": [], "api_secret": [] } ], "parameters": [ { "name": "promotion_id", "in": "path", "required": true, "description": "The promotion identifier", "schema": { "type": "string" } }, { "name": "reward_sku", "in": "path", "required": true, "description": "The reward SKU", "schema": { "type": "string" } } ], "responses": { "201": { "description": "The redemption was successfully created and redeemed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/redemption", "properties": { "state": { "type": "string", "example": "redeemed" }, "redeemed_datetime": { "type": "string", "format": "date-time", "nullable": true, "example": "2026-07-22T12:34:56Z" } }, "required": [ "id", "order_id", "state", "redeemed_datetime", "reward_codes" ] } } } }, "application/pdf": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/redemption", "properties": { "state": { "type": "string", "example": "redeemed" }, "redeemed_datetime": { "type": "string", "format": "date-time", "nullable": true, "example": "2026-07-22T12:34:56Z" } }, "required": [ "id", "order_id", "state", "redeemed_datetime", "reward_codes" ] } } } } } }, "401": { "description": "The authenticated user does not have permission to access this resource.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error_name": { "type": "string", "example": "forbidden" }, "error_message": { "type": "string", "example": "The authenticated user does not have permission to access this resource.", "nullable": true } } } }, "application/pdf": { "schema": { "type": "object", "properties": { "error_name": { "type": "string", "example": "forbidden" }, "error_message": { "type": "string", "example": "The authenticated user does not have permission to access this resource.", "nullable": true } } } } } }, "422": { "description": "Invalid Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error_name": { "type": "string", "example": "invalid_request" }, "error_message": { "type": "string", "example": null, "nullable": true } } } }, "application/pdf": { "schema": { "type": "object", "properties": { "error_name": { "type": "string", "example": "invalid_request" }, "error_message": { "type": "string", "example": null, "nullable": true } } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "order_id": { "type": "string" }, "user": { "$ref": "#/components/schemas/user" }, "value": { "type": "object", "properties": { "amount": { "type": "string", "example": "10", "description": "optional - only needed for \"free value\" rewards" } } }, "customization": { "type": "object", "properties": { "pdf": { "type": "object", "properties": { "message": { "type": "string", "example": "I hope you enjoy this reward!" }, "sender_name": { "type": "string", "example": "Martina", "description": "The reward sender name to be printed on the PDF (if applicable)" } } } } } } } }, "required": [ "data" ] } } } } } }, "/fulfillment/v2/promotions/{promotion_id}/rewards/{reward_sku}/redemptions/book": { "post": { "summary": "Book", "tags": [ "Redemptions" ], "operationId": "bookRedemption", "description": "Use this function to book a reward code before redeem it.\n\nThis action will do the same as in Create a Redemption API but will also book a reward code for a duration of 30 minutes.\n\nYou can then redeem the redemption using Create and Redeem or Redeem APIs using the same parameters (eg. same order_id and user email).\n", "security": [ { "bearer_auth": [] }, { "api_key": [], "api_secret": [] } ], "parameters": [ { "name": "promotion_id", "in": "path", "required": true, "description": "The promotion identifier", "schema": { "type": "string" } }, { "name": "reward_sku", "in": "path", "required": true, "description": "The reward SKU", "schema": { "type": "string" } } ], "responses": { "201": { "description": "The redemption was successfully booked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/redemption" } } } } } }, "401": { "description": "The authenticated user does not have permission to access this resource.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error_name": { "type": "string", "example": "forbidden" }, "error_message": { "type": "string", "example": "The authenticated user does not have permission to access this resource.", "nullable": true } } } } } }, "422": { "description": "Invalid Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error_name": { "type": "string", "example": "invalid_request" }, "error_message": { "type": "string", "example": null, "nullable": true } } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "order_id": { "type": "string" }, "user": { "$ref": "#/components/schemas/user" }, "value": { "type": "object", "properties": { "amount": { "type": "string", "example": "10", "description": "optional - only needed for \"free value\" rewards" } } }, "customization": { "type": "object", "properties": { "pdf": { "type": "object", "properties": { "message": { "type": "string", "example": "I hope you enjoy this reward!" }, "sender_name": { "type": "string", "example": "Martina", "description": "The reward sender name to be printed on the PDF (if applicable)" } } } } } } } }, "required": [ "data" ] } } } } } }, "/fulfillment/v2/redemptions/{redemption_id}/actions/activate": { "post": { "summary": "Activate", "tags": [ "Redemptions" ], "operationId": "activateRedemption", "description": "Use this function to perform an activation from an existing redemption object and retrieve a authenticated link (url key).", "security": [ { "bearer_auth": [] }, { "api_key": [], "api_secret": [] } ], "parameters": [ { "name": "redemption_id", "in": "path", "required": true, "description": "Unique Redemption identifier (eg. ZN7RS-9RNLY)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The redemption was successfully activated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/redemption" } } } }, "application/pdf": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/redemption" } } } } } }, "401": { "description": "The authenticated user does not have permission to access this resource.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error_name": { "type": "string", "example": "forbidden" }, "error_message": { "type": "string", "example": "The authenticated user does not have permission to access this resource.", "nullable": true } } } }, "application/pdf": { "schema": { "type": "object", "properties": { "error_name": { "type": "string", "example": "forbidden" }, "error_message": { "type": "string", "example": "The authenticated user does not have permission to access this resource.", "nullable": true } } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/user" } } } }, "required": [ "data" ] } } } } } }, "/fulfillment/v2/redemptions/{redemption_id}/actions/redeem": { "post": { "summary": "Redeem", "tags": [ "Redemptions" ], "operationId": "redeemRedemption", "description": "Use this function to perform a reward delivery from an existing redemption object.", "security": [ { "bearer_auth": [] }, { "api_key": [], "api_secret": [] } ], "parameters": [ { "name": "redemption_id", "in": "path", "required": true, "description": "Unique Redemption identifier (eg. ZN7RS-9RNLY)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The redemption was successfully redeemed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/redemption", "properties": { "state": { "type": "string", "example": "redeemed" }, "redeemed_datetime": { "type": "string", "format": "date-time", "nullable": true, "example": "2026-07-22T12:34:56Z" } }, "required": [ "id", "state", "redeemed_datetime", "reward_codes" ] } } } }, "application/pdf": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/redemption", "properties": { "state": { "type": "string", "example": "redeemed" }, "redeemed_datetime": { "type": "string", "format": "date-time", "nullable": true, "example": "2026-07-22T12:34:56Z" } }, "required": [ "id", "state", "redeemed_datetime", "reward_codes" ] } } } } } }, "401": { "description": "The authenticated user does not have permission to access this resource.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error_name": { "type": "string", "example": "forbidden" }, "error_message": { "type": "string", "example": "The authenticated user does not have permission to access this resource.", "nullable": true } } } }, "application/pdf": { "schema": { "type": "object", "properties": { "error_name": { "type": "string", "example": "forbidden" }, "error_message": { "type": "string", "example": "The authenticated user does not have permission to access this resource.", "nullable": true } } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/user" } } } }, "required": [ "data" ] } } } } } }, "/fulfillment/v2/redemptions/{redemption_id}/actions/cancel": { "post": { "summary": "Cancel", "tags": [ "Redemptions" ], "operationId": "cancelRedemption", "description": "Use this function to cancel a pending/failed redemption.", "security": [ { "bearer_auth": [] }, { "api_key": [], "api_secret": [] } ], "parameters": [ { "name": "redemption_id", "in": "path", "required": true, "description": "The redemption identifier", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The redemption was successfully cancelled.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/redemption" } } } } } }, "401": { "description": "The authenticated user does not have permission to access this resource.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error_name": { "type": "string", "example": "forbidden" }, "error_message": { "type": "string", "example": "The authenticated user does not have permission to access this resource.", "nullable": true } } } } } } } } }, "/fulfillment/v2/redemptions/{redemption_id}/actions/refund": { "post": { "summary": "Refund", "tags": [ "Redemptions" ], "operationId": "refundRedemption", "description": "Refunds a redemption if it is redeemed, or if debited = true and the state is booked, failed, or pending.\nOnly redemptions from the current month are refundable.\n", "security": [ { "bearer_auth": [] }, { "api_key": [], "api_secret": [] } ], "parameters": [ { "name": "redemption_id", "in": "path", "required": true, "description": "The redemption identifier", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Redemption refunded (or unchanged when not refundable)", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/redemption", "properties": { "state": { "type": "string", "example": "refunded" }, "refunded_datetime": { "type": "string", "format": "date-time", "nullable": true, "example": "2026-07-22T12:34:56Z" } }, "required": [ "id", "state" ] } } } }, "application/pdf": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/redemption", "properties": { "state": { "type": "string", "example": "refunded" }, "refunded_datetime": { "type": "string", "format": "date-time", "nullable": true, "example": "2026-07-22T12:34:56Z" } }, "required": [ "id", "state" ] } } } } } }, "401": { "description": "The authenticated user does not have permission to access this resource.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error_name": { "type": "string", "example": "forbidden" }, "error_message": { "type": "string", "example": "The authenticated user does not have permission to access this resource.", "nullable": true } } } }, "application/pdf": { "schema": { "type": "object", "properties": { "error_name": { "type": "string", "example": "forbidden" }, "error_message": { "type": "string", "example": "The authenticated user does not have permission to access this resource.", "nullable": true } } } } } } } } }, "/fulfillment/v2/redemptions/{redemption_id}/card_consult": { "get": { "summary": "Consult Card", "tags": [ "Redemptions" ], "operationId": "cardConsultRedemption", "description": "Use this function to retrieve card information (balance, currency) for a redemption when supported by the reward provider.", "security": [ { "bearer_auth": [] }, { "api_key": [], "api_secret": [] } ], "parameters": [ { "name": "redemption_id", "in": "path", "required": true, "description": "The redemption identifier", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Card details were successfully retrieved", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "card_balance": { "type": "number", "nullable": true }, "card_currency": { "type": "string", "nullable": true } } } } } } } }, "422": { "description": "Card consult is not available for this redemption", "content": { "application/json": { "schema": { "type": "object", "properties": { "error_name": { "type": "string", "example": "unprocessable_entity" }, "error_message": { "type": "string", "example": null, "nullable": true } } } } } }, "401": { "description": "The authenticated user does not have permission to access this resource.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error_name": { "type": "string", "example": "forbidden" }, "error_message": { "type": "string", "example": "The authenticated user does not have permission to access this resource.", "nullable": true } } } } } } } } }, "/fulfillment/v2/clients": { "get": { "summary": "List all Clients", "tags": [ "Clients" ], "operationId": "listClients", "description": "Use this function to list all the clients your account can manage", "security": [ { "bearer_auth": [] }, { "api_key": [], "api_secret": [] } ], "parameters": [ { "name": "page", "in": "query", "schema": { "$ref": "#/components/schemas/page_parameter" }, "required": false }, { "name": "per_page", "in": "query", "schema": { "$ref": "#/components/schemas/per_page_parameter" }, "required": false } ], "responses": { "200": { "description": "Clients listed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/client_summary" } }, "paging": { "type": "object", "properties": { "page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 20 }, "total": { "type": "integer", "example": 100 } } } } } } } }, "401": { "description": "Authentication credentials are missing or invalid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error_name": { "type": "string", "example": "unauthorized" }, "error_message": { "type": "string", "example": "Authentication credentials are missing or invalid.", "nullable": true } } } } } } } } }, "/fulfillment/v2/clients/{client_id}": { "get": { "summary": "Get a Client", "tags": [ "Clients" ], "operationId": "getClientById", "description": "Use this function to retrieve detailed information about a client", "security": [ { "bearer_auth": [] }, { "api_key": [], "api_secret": [] } ], "parameters": [ { "name": "client_id", "in": "path", "required": true, "description": "The client identifier", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Client found", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/client_details" } } } } } }, "401": { "description": "The authenticated user does not have permission to access this resource.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error_name": { "type": "string", "example": "forbidden" }, "error_message": { "type": "string", "example": "The authenticated user does not have permission to access this resource.", "nullable": true } } } } } }, "404": { "description": "Client not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error_name": { "type": "string", "example": "not_found" }, "error_message": { "type": "string", "example": "The requested resource could not be found.", "nullable": true } } } } } } } } }, "/fulfillment/v2/clients/{client_id}/budget/history": { "get": { "summary": "Get a Client budget history", "tags": [ "Clients" ], "operationId": "getClientBudgetHistory", "description": "Use this function to retrieve detailed budget history about a client", "security": [ { "bearer_auth": [] }, { "api_key": [], "api_secret": [] } ], "parameters": [ { "name": "client_id", "in": "path", "required": true, "description": "The client identifier", "schema": { "type": "string" } }, { "name": "page", "in": "query", "schema": { "$ref": "#/components/schemas/page_parameter" }, "required": false }, { "name": "per_page", "in": "query", "schema": { "$ref": "#/components/schemas/per_page_parameter" }, "required": false }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "creation_datetime", "-creation_datetime" ], "description": "Use minus (-) for a desc sort (eg. -creation_datetime)." }, "required": false }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "credit", "allocate", "deallocate", "debit" ], "description": "List of types to filter with (eg. debit,credit)" }, "required": false } ], "responses": { "200": { "description": "Budget history listed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/client_details" } }, "paging": { "type": "object", "properties": { "page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 20 }, "total": { "type": "integer", "example": 100 } } } } } } } }, "401": { "description": "The authenticated user does not have permission to access this resource.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error_name": { "type": "string", "example": "forbidden" }, "error_message": { "type": "string", "example": "The authenticated user does not have permission to access this resource.", "nullable": true } } } } } }, "404": { "description": "Client not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error_name": { "type": "string", "example": "not_found" }, "error_message": { "type": "string", "example": "The requested resource could not be found.", "nullable": true } } } } } } } } }, "/fulfillment/v2/clients/{client_id}/discounts": { "get": { "summary": "List all discounts", "tags": [ "Clients" ], "operationId": "listClientDiscounts", "description": "Use this function to list all the discounts of a specific client", "security": [ { "bearer_auth": [] }, { "api_key": [], "api_secret": [] } ], "parameters": [ { "name": "client_id", "in": "path", "required": true, "description": "The client identifier", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Discounts listed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/discount_summary" } }, "paging": { "type": "object", "properties": { "page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 20 }, "total": { "type": "integer", "example": 100 } } } } } } } }, "401": { "description": "The authenticated user does not have permission to access this resource.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error_name": { "type": "string", "example": "forbidden" }, "error_message": { "type": "string", "example": "The authenticated user does not have permission to access this resource.", "nullable": true } } } } } }, "404": { "description": "Client not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error_name": { "type": "string", "example": "not_found" }, "error_message": { "type": "string", "example": "The requested resource could not be found.", "nullable": true } } } } } } } } }, "/fulfillment/v2/clients/{client_id}/stats": { "get": { "summary": "Get Redemption Stats", "tags": [ "Stats" ], "operationId": "getRedemptionStats", "description": "Use this function to access data relative to the reward delivery activity for a specific client", "security": [ { "bearer_auth": [] }, { "api_key": [], "api_secret": [] } ], "parameters": [ { "name": "client_id", "in": "path", "required": true, "description": "The client identifier", "schema": { "type": "string" } }, { "name": "promotion_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "reward_sku", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "start_date", "in": "query", "schema": { "type": "string", "format": "date-time" }, "required": false, "description": "ISO-8601 String representing the start date for the date range for which activity stats are extracted" }, { "name": "end_date", "in": "query", "schema": { "type": "string", "format": "date-time" }, "required": false, "description": "ISO-8601 String representing the end date for the date range for which activity stats are extracted" }, { "name": "interval", "in": "query", "schema": { "type": "string", "enum": [ "daily", "monthly", "yearly" ] }, "required": false, "description": "Aggregation granularity - daily, monthly and yearly" }, { "name": "states", "in": "query", "schema": { "type": "string", "enum": [ "all", "redeemed" ] }, "required": false, "description": "Filter to specify the state of the redemptions to include in the stats" } ], "responses": { "200": { "description": "Stats retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/stats" } }, "paging": { "type": "object", "properties": { "page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 20 }, "total": { "type": "integer", "example": 100 } } } } } } } } } } }, "/fulfillment/v2/clients/{client_id}/vendor_places": { "get": { "summary": "List all vendor places", "tags": [ "Vendor Places" ], "operationId": "listClientVendorPlaces", "description": "Use this function to list vendor places for a specific client. This endpoint is available only to clients subscribed to Vendor Places API access.", "security": [ { "bearer_auth": [] }, { "api_key": [], "api_secret": [] } ], "parameters": [ { "name": "client_id", "in": "path", "required": true, "description": "The client identifier", "schema": { "type": "string" } }, { "name": "skus", "in": "query", "schema": { "type": "array", "items": { "type": "string" } }, "required": false, "description": "Filter by a list of brand SKUs" }, { "name": "zip_code", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "page", "in": "query", "schema": { "$ref": "#/components/schemas/page_parameter" }, "required": false }, { "name": "per_page", "in": "query", "schema": { "$ref": "#/components/schemas/per_page_parameter" }, "required": false } ], "responses": { "200": { "description": "Vendor places listed successfully when retailer has recent brand activity", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/vendor_place" } }, "paging": { "type": "object", "properties": { "page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 20 }, "total": { "type": "integer", "example": 100 } } } } } } } }, "403": { "description": "Client does not have vendor places API access", "content": { "application/json": { "schema": { "type": "object", "properties": { "error_name": { "type": "string", "example": "forbidden" }, "error_message": { "type": "string", "example": "The authenticated user does not have permission to access this resource.", "nullable": true } } } } } }, "404": { "description": "Client not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error_name": { "type": "string", "example": "not_found" }, "error_message": { "type": "string", "example": "The requested resource could not be found.", "nullable": true } } } } } }, "401": { "description": "The authenticated user does not have permission to access this resource.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error_name": { "type": "string", "example": "forbidden" }, "error_message": { "type": "string", "example": "The authenticated user does not have permission to access this resource.", "nullable": true } } } } } } } } } }, "components": { "securitySchemes": { "bearer_auth": { "type": "http", "scheme": "bearer" }, "api_key": { "type": "apiKey", "name": "Api-Key", "in": "header" }, "api_secret": { "type": "apiKey", "name": "Api-Secret", "in": "header" } }, "schemas": { "page_parameter": { "type": "integer", "minimum": 1, "default": 1, "nullable": true }, "per_page_parameter": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 20, "nullable": true }, "error_response": { "type": "object", "properties": { "error_name": { "type": "string" }, "error_message": { "type": "string", "nullable": true } } }, "account": { "type": "object", "properties": { "id": { "type": "integer", "example": 42 }, "login": { "type": "string", "example": "john.doe@example.com", "nullable": true }, "name": { "type": "string", "example": "John Doe", "nullable": true }, "email": { "type": "string", "format": "email", "example": "john.doe@example.com" }, "phone_number": { "type": "string", "example": "+33612345678", "nullable": true }, "roles": { "type": "array", "items": { "type": "string" }, "example": [ "fulfillment_api" ] }, "locale": { "type": "string", "example": "fr", "nullable": true }, "timezone": { "type": "string", "example": "Europe/Paris" }, "access_type": { "type": "string", "enum": [ "user", "service" ], "nullable": true, "example": "service" } } }, "address": { "type": "object", "properties": { "line_1": { "type": "string", "nullable": true, "example": "Ifeelgoods, Inc" }, "line_2": { "type": "string", "nullable": true, "example": "550 Hamilton Avenue" }, "line_3": { "type": "string", "nullable": true, "example": "Suite 226" }, "line_4": { "type": "string", "nullable": true }, "zipcode": { "type": "string", "nullable": true, "example": "94301" }, "city": { "type": "string", "nullable": true, "example": "Palo Alto" }, "state": { "type": "string", "nullable": true, "example": "California" }, "country": { "type": "string", "nullable": true, "example": "US", "description": "ISO-3166 country code (eg. US, FR, GB)" } } }, "brand_summary": { "type": "object", "properties": { "id": { "type": "string", "example": "APP", "description": "Unique identifier that represents the brand (eg. `APP`)." }, "name": { "type": "string", "example": "iTunes", "description": "Brand name (eg. `iTunes`)." }, "status": { "type": "string", "enum": [ "active", "deactivated" ] }, "url": { "type": "string", "format": "uri", "nullable": true, "description": "Brand URL (eg. `https://www.ifeelgoods.com`)." } } }, "budget_line_item": { "type": "object", "properties": { "id": { "type": "integer" }, "amount": { "type": "string" }, "type": { "type": "string", "enum": [ "credit", "allocate", "deallocate", "debit" ] }, "status": { "type": "string", "enum": [ "approved", "rejected", "pending" ] }, "external_id": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "creation_datetime": { "type": "string", "format": "date-time" } } }, "discount_summary": { "type": "object", "properties": { "id": { "type": "integer" }, "sku": { "type": "string" }, "label": { "type": "string", "nullable": true }, "discount": { "type": "number" }, "brand_sku": { "type": "string" }, "brand_name": { "type": "string", "nullable": true } }, "description": "A Discount represents how many percent of a reward face value is deducted when purchasing it" }, "client_summary": { "type": "object", "properties": { "id": { "type": "integer", "example": 237 }, "name": { "type": "string", "example": "Ifeelgoods, Inc." }, "ui_id": { "type": "string", "example": "ifeelgoods-inc" }, "status": { "type": "string", "enum": [ "enabled", "disabled" ], "example": "enabled" }, "billing_location": { "type": "string", "example": "US" }, "contact_email": { "type": "string", "format": "email", "example": "joe@ifeelgoods.com", "nullable": true }, "contact_phone": { "type": "string", "example": "+33612345678", "nullable": true }, "locale": { "type": "string", "example": "en" }, "logo_url": { "type": "string", "format": "uri", "example": "//cdn.ifeelgoods.com/media/a308a55a5b865ca43d4eda67dffa188a.png", "nullable": true }, "balance": { "type": "string", "example": "1000.00", "description": "Advertiser remaining budget" }, "balance_currency": { "type": "string", "example": "EUR", "description": "Advertiser remaining budget currency" }, "budget_alerts": { "type": "object", "nullable": true, "properties": { "alert_1": { "type": "integer", "nullable": true }, "alert_2": { "type": "integer", "nullable": true } }, "description": "Advertiser budget alerts thresholds" } }, "description": "A Client represents a customer account that will be either retrieving or delivering Rewards to end users.\n" }, "client_details": { "type": "object", "properties": { "id": { "type": "integer", "example": 237 }, "name": { "type": "string", "example": "Ifeelgoods, Inc." }, "ui_id": { "type": "string", "example": "ifeelgoods-inc" }, "status": { "type": "string", "enum": [ "enabled", "disabled" ], "example": "enabled" }, "billing_location": { "type": "string", "example": "US" }, "contact_email": { "type": "string", "format": "email", "example": "joe@ifeelgoods.com", "nullable": true }, "contact_phone": { "type": "string", "example": "+33612345678", "nullable": true }, "locale": { "type": "string", "example": "en" }, "logo_url": { "type": "string", "format": "uri", "example": "//cdn.ifeelgoods.com/media/a308a55a5b865ca43d4eda67dffa188a.png", "nullable": true }, "balance": { "type": "string", "example": "1000.00", "description": "Advertiser remaining budget" }, "balance_currency": { "type": "string", "example": "EUR", "description": "Advertiser remaining budget currency" }, "budget_alerts": { "type": "object", "nullable": true, "properties": { "alert_1": { "type": "integer", "nullable": true }, "alert_2": { "type": "integer", "nullable": true } }, "description": "Advertiser budget alerts thresholds" } }, "description": "A Client represents a customer account that will be either retrieving or delivering Rewards to end users.\n" }, "dimension": { "type": "object", "description": "Additional structured attributes associated with a reward. Each key represents a dimension label and its value is the dimension value for that reward. Not all dimensions are present on every reward — only the ones configured for that specific product will appear.", "properties": { "available_denominations_range": { "type": "string", "nullable": true, "description": "Indicates the range of values that can be used with open value reward (when free_value is true) (eg. 5..250).", "example": "5..250" }, "custom_offer": { "type": "string", "nullable": true, "description": "When a custom offer has been configured for this product (eg. buy one get one, $20 off the second article, etc.).", "example": "Buy one get one" }, "validity_period": { "type": "string", "nullable": true, "description": "Duration during which the reward code remains valid after delivery. Expressed as a number followed by a unit: d for days, m for months, y for years (eg. 30d for 30 days, 12m for 12 months, 1y for 1 year). Returns null if no validity period applies.", "example": "30d" }, "available_denominations": { "type": "string", "nullable": true, "description": "List of specific monetary amounts available for this reward." }, "breakable": { "type": "string", "nullable": true, "description": "Indicates whether the reward code can be broken into smaller values." }, "cumulable": { "type": "string", "nullable": true, "description": "Indicates whether multiple reward codes can be combined." }, "denomination": { "oneOf": [ { "type": "string", "example": "10" }, { "type": "number", "example": 10 } ], "nullable": true, "description": "Monetary amount of the reward (eg. 10€, $20, etc.).", "example": "10" }, "denomination_currency": { "type": "string", "nullable": true, "description": "Currency of the denomination amount (eg. EUR, USD, etc.).", "example": "EUR" }, "duration": { "type": "string", "nullable": true, "description": "Duration of a subscription or service (eg. 2 months).", "example": "2" }, "duration_unit": { "type": "string", "nullable": true, "description": "Unit of the duration dimension. Possible values: minute, hour, day, week, month, year, varying_duration.", "example": "month" }, "people": { "type": "string", "nullable": true, "description": "Number of people concerned by the reward.", "example": "2" }, "quantity": { "type": "string", "nullable": true, "description": "Virtual currency amount associated with the reward (eg. 300 points, 200 miles, etc.).", "example": "300" }, "quantity_unit": { "type": "string", "nullable": true, "description": "Unit of the quantity dimension. Possible values: points, miles, facebook_credits, minutes, movie, meal, e_magazine, e_ticket, song, lesson, box, subscription.", "example": "points" }, "redemption_channel": { "type": "array", "items": { "type": "string", "description": "Channel(s) through which the reward can be redeemed. Possible values: `online`, `in_store`.", "example": "online" }, "nullable": true } } }, "product_summary": { "type": "object", "properties": { "id": { "type": "string", "example": "APP-ITC", "description": "Unique identifier for the product (eg. `APP-ITC`)." }, "name": { "type": "string", "example": "iTunes Code", "description": "The product name (eg. `iTunes Code`)." }, "deliverable_as_pdf": { "type": "boolean", "description": "Indicates whether the product can be delivered as PDF or not." }, "vat_rate": { "type": "number", "example": 0.19, "description": "Indicates product VAT rate." }, "vat_rule": { "type": "string", "enum": [ "BUU", "BUM" ], "description": "Indicates product VAT rule (BUU or BUM)." } } }, "product_type": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "item", "gift_card", "media_content", "cash", "subscription", "coupon_and_promo_codes", "points_and_miles", "experience" ], "example": "gift_card", "description": "Unique identifier for the product type." }, "name": { "type": "string", "enum": [ "Item", "Gift Card", "Media Content", "Cash", "Subscription", "Coupon & Promo Codes", "Points & Miles", "Experience" ], "example": "Gift Card", "description": "The product type name." } } }, "promotion_details": { "type": "object", "properties": { "id": { "type": "integer" }, "ui_id": { "type": "string", "nullable": true, "deprecated": true }, "locale": { "type": "string", "nullable": true, "example": "en" }, "name": { "type": "string", "example": "Holiday Campaign", "description": "Campaign name." }, "start_datetime": { "type": "string", "format": "date-time" }, "end_datetime": { "type": "string", "format": "date-time", "nullable": true }, "client": { "type": "object", "properties": { "id": { "type": "integer", "example": 237 }, "name": { "type": "string", "example": "Ifeelgoods, Inc." } }, "description": "A Client represents a customer account that will be either retrieving or delivering Rewards to end users.\n" }, "status": { "type": "string", "enum": [ "enabled", "disabled", "paused", "completed" ] }, "state": { "type": "string", "enum": [ "ready", "pending", "ended", "legacy" ] }, "rewards": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "example": "Uggy Gift Card 10€", "description": "Uggy Gift Card 10€" }, "sku": { "type": "string", "example": "APP-ITC-10USD-US", "description": "Unique identifier that represents the reward (eg. `APP-ITC-10USD-US`). It must be used with the redeem APIs." }, "status": { "type": "string", "enum": [ "disabled", "enabled", "paused" ], "example": "enabled", "description": "Current lifecycle status of the offer (enabled, paused, disabled).\n Use this field to understand whether the offer is currently intended to be active for your program." }, "state": { "type": "string", "enum": [ "invalid_reward", "temporarily_unavailable", "invalid_reward_for_redemption_flow", "no_allocation", "ready" ], "example": "ready", "description": "Current availability outcome of the offer based on its setup and availability checks.\n This field explains why an offer can or cannot be used at the moment." }, "variable_value": { "type": "boolean", "description": "Indicates whether the reward should be redeemed with a value. Range can be found in dimensions.available_denominations_range." }, "usages": { "type": "array", "items": { "type": "string", "enum": [ "tracking", "security", "primary", "url", "security_url", "security_url_code" ] }, "example": [ "primary" ] } } } }, "fraud_level": { "type": "string", "enum": [ "standard", "strong" ] }, "redeem_frequency": { "type": "string", "enum": [ "unique", "multiple" ] }, "authentication_systems": { "type": "array", "items": { "type": "string" }, "example": [ "facebook_connect", "google", "email", "sms" ], "description": "List of authentication systems used for the campaign (eg. `[\"email\", \"sms\"]`)." }, "secured_order_ids": { "type": "boolean", "description": "Indicates whether the campaign stores secured order ids." }, "allow_pdf": { "type": "boolean" } }, "description": "A Promotion represents the settings of a campaign in which a Client distributes their Rewards to the end-users." }, "redemption": { "type": "object", "description": "A Redemption defines the status of a Reward delivery (user eligibility, reward selected, authentication settings, notification channels..)", "properties": { "id": { "type": "string", "example": "ABCDE-12345" }, "url": { "type": "string", "format": "uri", "nullable": true }, "state": { "type": "string", "enum": [ "pending", "booked", "redeemed", "denied", "failed", "refunded", "blocked", "canceled", "expired" ] }, "order_id": { "type": "string" }, "testing": { "type": "boolean" }, "cancelable": { "type": "boolean", "description": "When a redemption is redeemed, indicates whether the code is cancelable or not" }, "reversed": { "type": "boolean", "description": "When a redemption is refunded, indicates whether the code was reversed or not" }, "client": { "type": "object", "properties": { "id": { "type": "integer", "example": 237 }, "name": { "type": "string", "example": "Ifeelgoods, Inc." } }, "description": "A Client represents a customer account that will be either retrieving or delivering Rewards to end users.\n" }, "promotion": { "type": "object", "properties": { "id": { "type": "integer" }, "status": { "type": "string", "enum": [ "enabled", "disabled", "paused", "completed" ], "nullable": true }, "name": { "type": "string", "nullable": true }, "state": { "type": "string", "nullable": true } } }, "authentication_systems": { "type": "array", "items": { "type": "string" }, "example": [ "facebook_connect", "google", "email", "sms" ], "description": "List of authentication systems used for the campaign (eg. `[\"email\", \"sms\"]`)." }, "notification_channels": { "type": "array", "items": { "type": "string", "enum": [ "email", "sms" ] }, "example": [ "email", "sms" ], "nullable": true }, "activation_notification_channels": { "type": "array", "items": { "type": "string", "enum": [ "email", "sms" ] }, "example": [ "email", "sms" ], "nullable": true }, "can_consult": { "type": "boolean", "nullable": true }, "reward_format": { "type": "object", "properties": { "usages": { "type": "array", "items": { "type": "string", "enum": [ "tracking", "security", "primary", "url", "security_url", "security_url_code" ] } }, "barcode_type": { "type": "string", "enum": [ "none", "c128", "qrcode" ] } }, "nullable": true, "description": "Only available when redemption is redeemed" }, "reward_codes": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "unique_code", "multiple_codes" ], "example": "unique_code", "description": "Indicates whether the reward has a single code or multiple codes." }, "codes": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "example": "Primary Code", "description": "The human-readable label for this code (e.g., \"Primary Code\", \"Security Code\")." }, "format": { "type": "string", "enum": [ "string", "url" ], "example": "string", "description": "The format of the code value. \"string\" for text codes, \"url\" for links." }, "usage": { "type": "string", "enum": [ "tracking", "security", "primary", "url", "security_url", "security_url_code", "preauth_link", "preauth_short_link" ], "example": "primary", "description": "The usage category of this code (e.g., \"primary\", \"security\", \"url\")." }, "value": { "type": "string", "example": "ABC123-XYZ789", "description": "The actual code or link value to be redeemed." } } } }, "expiration_datetime": { "type": "string", "nullable": true, "format": "date-time", "description": "The expiration date of the reward code(s), if applicable." } }, "nullable": true, "description": "Only available when redemption is redeemed. Please refer to [FAQ](ref:faq#how-to-retrieve-redemption-code-format) for more information about `reward_codes` object." }, "reward": { "type": "object", "properties": { "name": { "type": "string", "example": "Uggy Gift Card 10€", "description": "Uggy Gift Card 10€" }, "sku": { "type": "string", "example": "APP-ITC-10USD-US", "description": "Unique identifier that represents the reward (eg. `APP-ITC-10USD-US`). It must be used with the redeem APIs." }, "status": { "type": "string", "enum": [ "disabled", "enabled", "paused" ], "example": "enabled", "description": "Current lifecycle status of the offer (enabled, paused, disabled).\n Use this field to understand whether the offer is currently intended to be active for your program." }, "state": { "type": "string", "enum": [ "invalid_reward", "temporarily_unavailable", "invalid_reward_for_redemption_flow", "no_allocation", "ready" ], "example": "ready", "description": "Current availability outcome of the offer based on its setup and availability checks.\n This field explains why an offer can or cannot be used at the moment." } } }, "value": { "type": "object", "nullable": true, "properties": { "amount": { "type": "number" }, "currency": { "type": "string", "nullable": true } } }, "user": { "type": "object", "nullable": true, "properties": { "id": { "type": "integer" } } }, "activation_datetime": { "type": "string", "format": "date-time" }, "expiration_datetime": { "type": "string", "nullable": true, "format": "date-time", "description": "Redemption expiration date (when the redemption is in pending state, it may have a date after which it is no longer redeemable)." }, "redeemed_datetime": { "type": "string", "nullable": true, "format": "date-time", "description": "Available when redemption has reached a redeemed state." }, "refunded_datetime": { "type": "string", "nullable": true, "format": "date-time", "description": "Available when redemption has reached a refunded state." }, "updated_datetime": { "type": "string", "format": "date-time" } } }, "reward_details": { "type": "object", "description": "A Reward (aka Product SKU) is a specific denomination of a Digital or Physical Gift that can be delivered to a User. \"iTunes Code 10$ (US)\" is a Reward.", "properties": { "name": { "type": "string", "example": "Uggy Gift Card 10€", "description": "Reward name (eg. `$10 iTunes® Code`)." }, "sku": { "type": "string", "example": "APP-ITC-10USD-US", "description": "Unique identifier that represents the reward (eg. `APP-ITC-10USD-US`). It must be used with the redeem APIs." }, "denomination": { "type": "string", "example": "10€", "description": "Reward formatted value with currency (eg. `$10`)." }, "display_value": { "type": "string" }, "free_value": { "type": "boolean", "description": "Indicates whether the reward should be redeemed with a value. Range can be found in dimensions.available_denominations_range." }, "cost": { "type": "number", "example": 9.0, "nullable": true, "description": "Reward cost for your account (eg. `9.0`). You need to query the API with the `client_id` parameter to retrieve the acutal cost, otherwise it will return `face_value`." }, "cost_currency": { "type": "string", "example": "EUR", "description": "Reward cost currency (eg. `USD`, `EUR`)." }, "face_value": { "type": "string", "example": "10.00", "description": "Reward face value, actual reward amount (e.g. `10.00`)." }, "face_value_currency": { "type": "string", "example": "EUR", "description": "Reward face value currency. (eg. `EUR`)." }, "in_stock": { "type": "boolean", "description": "Boolean that represent reward availability." }, "stock_quantity": { "type": "integer", "example": 100, "nullable": true, "description": "Stock quantity. Can be `null` (if `stock_quantity` is `null`, `in_stock` is always `true`)." }, "brand": { "type": "object", "properties": { "id": { "type": "string", "example": "APP", "description": "Unique identifier that represents the brand (eg. `APP`)." }, "name": { "type": "string", "example": "iTunes", "description": "Brand name (eg. `iTunes`)." }, "status": { "type": "string", "enum": [ "active", "deactivated" ] }, "url": { "type": "string", "format": "uri", "nullable": true, "description": "Brand URL (eg. `https://www.ifeelgoods.com`)." } }, "description": "Reward brand. In ifeelgoods data model, it's a kind of 'parent' for the product." }, "product": { "type": "object", "properties": { "id": { "type": "string", "example": "APP-ITC", "description": "Unique identifier for the product (eg. `APP-ITC`)." }, "name": { "type": "string", "example": "iTunes Code", "description": "The product name (eg. `iTunes Code`)." }, "deliverable_as_pdf": { "type": "boolean", "description": "Indicates whether the product can be delivered as PDF or not." }, "vat_rate": { "type": "number", "example": 0.19, "description": "Indicates product VAT rate." }, "vat_rule": { "type": "string", "enum": [ "BUU", "BUM" ], "description": "Indicates product VAT rule (BUU or BUM)." } } }, "product_type": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "item", "gift_card", "media_content", "cash", "subscription", "coupon_and_promo_codes", "points_and_miles", "experience" ], "example": "gift_card", "description": "Unique identifier for the product type." }, "name": { "type": "string", "enum": [ "Item", "Gift Card", "Media Content", "Cash", "Subscription", "Coupon & Promo Codes", "Points & Miles", "Experience" ], "example": "Gift Card", "description": "The product type name." } } }, "usages": { "type": "array", "items": { "type": "string", "enum": [ "tracking", "security", "primary", "url", "security_url", "security_url_code" ] }, "example": [ "primary" ], "description": "Reward code format" }, "expiration_date": { "type": "string", "example": "2023-03-31", "nullable": true, "description": "Expiration date (eg. `2023-03-31`)" }, "categories": { "type": "array", "items": { "type": "string" }, "example": [ "Sports" ], "description": "Reward categories (eg. `['Games & Entertainment', 'Sports']`) (not maintained)." }, "description": { "type": "string", "nullable": true, "description": "Reward description." }, "country": { "type": "array", "items": { "type": "string" }, "description": "Reward country list (eg. `[\"US\", \"CA\"]` or `[\"WW\"]` if worldwide). If the reward is not specific to a country, it will be considered as worldwide.", "example": [ "US", "CA" ] }, "conditions_of_sale": { "type": "string", "enum": [ "on_demand", "special_order_only" ], "nullable": true }, "dimensions": { "type": "object", "description": "Additional structured attributes associated with a reward. Each key represents a dimension label and its value is the dimension value for that reward. Not all dimensions are present on every reward — only the ones configured for that specific product will appear.", "properties": { "available_denominations_range": { "type": "string", "nullable": true, "description": "Indicates the range of values that can be used with open value reward (when free_value is true) (eg. 5..250).", "example": "5..250" }, "custom_offer": { "type": "string", "nullable": true, "description": "When a custom offer has been configured for this product (eg. buy one get one, $20 off the second article, etc.).", "example": "Buy one get one" }, "validity_period": { "type": "string", "nullable": true, "description": "Duration during which the reward code remains valid after delivery. Expressed as a number followed by a unit: d for days, m for months, y for years (eg. 30d for 30 days, 12m for 12 months, 1y for 1 year). Returns null if no validity period applies.", "example": "30d" }, "available_denominations": { "type": "string", "nullable": true, "description": "List of specific monetary amounts available for this reward." }, "breakable": { "type": "string", "nullable": true, "description": "Indicates whether the reward code can be broken into smaller values." }, "cumulable": { "type": "string", "nullable": true, "description": "Indicates whether multiple reward codes can be combined." }, "denomination": { "oneOf": [ { "type": "string", "example": "10" }, { "type": "number", "example": 10 } ], "nullable": true, "description": "Monetary amount of the reward (eg. 10€, $20, etc.).", "example": "10" }, "denomination_currency": { "type": "string", "nullable": true, "description": "Currency of the denomination amount (eg. EUR, USD, etc.).", "example": "EUR" }, "duration": { "type": "string", "nullable": true, "description": "Duration of a subscription or service (eg. 2 months).", "example": "2" }, "duration_unit": { "type": "string", "nullable": true, "description": "Unit of the duration dimension. Possible values: minute, hour, day, week, month, year, varying_duration.", "example": "month" }, "people": { "type": "string", "nullable": true, "description": "Number of people concerned by the reward.", "example": "2" }, "quantity": { "type": "string", "nullable": true, "description": "Virtual currency amount associated with the reward (eg. 300 points, 200 miles, etc.).", "example": "300" }, "quantity_unit": { "type": "string", "nullable": true, "description": "Unit of the quantity dimension. Possible values: points, miles, facebook_credits, minutes, movie, meal, e_magazine, e_ticket, song, lesson, box, subscription.", "example": "points" }, "redemption_channel": { "type": "array", "items": { "type": "string", "description": "Channel(s) through which the reward can be redeemed. Possible values: `online`, `in_store`.", "example": "online" }, "nullable": true } } }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Reward tags (not maintained).", "deprecated": true }, "targeting": { "type": "object", "properties": { "gender": { "type": "array", "items": { "type": "string", "example": "male" } }, "age_range": { "type": "array", "items": { "type": "string" }, "example": [ "18-24", "25-34" ] }, "reach": { "type": "string" } }, "description": "Marketing information (not maintained)", "deprecated": true }, "catalog_badge_url": { "type": "string", "format": "uri", "nullable": true, "example": "//cdn.ifeelgoods.com/image.png", "description": "Reward image, without scheme (eg. `//cdn.ifeelgoods.com/image.png`)." }, "catalog_card_url": { "type": "string", "format": "uri", "nullable": true, "example": "//cdn.ifeelgoods.com/image.png", "description": "(legacy) Reward image (same as catalog_badge_url).", "deprecated": true }, "logo_url": { "type": "string", "format": "uri", "nullable": true, "example": "//cdn.ifeelgoods.com/images/logo.png", "description": "Brand logo, without scheme (eg. `//cdn.ifeelgoods.com/logo.png`)." }, "terms_and_conditions_url": { "type": "string", "format": "uri", "nullable": true, "example": "https//ifeelgoods.com/terms_and_conditions", "description": "Reward 'Terms and Conditions' URL (when provided by brand, `null` otherwise)." }, "terms_and_conditions": { "type": "string", "nullable": true, "description": "Reward 'Terms and Conditions'." }, "how_to_use_instructions": { "type": "string", "nullable": true, "description": "Reward 'How to use' instructions." }, "important_instructions": { "type": "string", "nullable": true, "description": "Reward additional information." } } }, "reward_format": { "type": "object", "properties": { "usages": { "type": "array", "items": { "type": "string", "enum": [ "tracking", "security", "primary", "url", "security_url", "security_url_code" ] } }, "barcode_type": { "type": "string", "enum": [ "none", "c128", "qrcode" ] } } }, "stats": { "type": "object", "properties": { "timeframe": { "type": "object", "properties": { "start": { "type": "string", "format": "date-time" }, "end": { "type": "string", "format": "date-time" } } }, "values": { "type": "array", "items": { "type": "object", "properties": { "group_by": { "type": "array", "items": { "type": "object", "properties": { "resource_type": { "type": "string", "example": "product" }, "id": { "type": "string", "example": "GIF-GIFTCOOL" }, "name": { "type": "string", "example": "Gift Cool" }, "value": { "type": "number", "example": 40, "nullable": true }, "iso_code": { "type": "string", "example": "EUR", "nullable": true } }, "description": "Contains objects that represent the grouping criteria for the stats.Each object can have different properties depending on the grouping type (e.g., product, reward, etc.).The properties listed above are examples and may not be present in every object.", "additionalProperties": true }, "example": [] }, "states": { "type": "object", "properties": { "pending": { "type": "integer", "example": 1 }, "booked": { "type": "integer", "example": 1 }, "redeemed": { "type": "integer", "example": 1 }, "denied": { "type": "integer", "example": 1 }, "failed": { "type": "integer", "example": 1 }, "refunded": { "type": "integer", "example": 1 }, "blocked": { "type": "integer", "example": 1 }, "canceled": { "type": "integer", "example": 1 }, "expired": { "type": "integer", "example": 1 } } }, "selling_price": { "type": "number", "nullable": true, "example": 76 }, "total_face_value": { "type": "number", "nullable": true, "example": 80 } } } } } }, "user": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "nullable": true, "example": "james.brown@ifeelgoods.com" }, "phone_number": { "type": "string", "nullable": true, "description": "International format (eg. +336xxxxxxxx)", "example": "+33611111111" }, "first_name": { "type": "string", "nullable": true, "example": "James" }, "last_name": { "type": "string", "nullable": true, "example": "Brown" }, "address": { "$ref": "#/components/schemas/address" } } }, "vendor_place": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "nullable": true, "example": "Main Street Store" }, "_geoloc": { "type": "object", "properties": { "lat": { "type": "number", "example": 37.7749 }, "lng": { "type": "number", "example": -122.4194 } } }, "brand": { "type": "object", "nullable": true, "properties": { "sku": { "type": "string", "example": "BRAND-SKU" }, "name": { "type": "string", "nullable": true, "example": "Main Store" } }, "description": "Vendor placeable summary (brand or merchant)." }, "address": { "allOf": [ { "$ref": "#/components/schemas/address" } ], "nullable": true } } } } }, "servers": [ { "url": "https://{environment}.ifeelgoods.com", "variables": { "environment": { "default": "api-sandbox", "enum": [ "api-sandbox", "api" ], "description": "The environment to target. Use \"api-sandbox\" for testing" } } } ], "info": { "title": "Fulfillment API", "description": "Public API exposed to ifeelgoods customers.", "version": "v2", "x-sdk-version": "0.2.0" } }