Summary

Understanding the importance of `order_id` in case of 5XX errors

Remember that our redemptions API is idempotent. This means that calling the Redeem or Create and Redeem endpoint with the same parameters multiple times will always lead to the same redemption.

In case of timeout (504) or failure, you can call Redeem or Create and Redeem on the same order again, it will retry the same order on our side. Note that a timeout does not means that the code has not been created on our side, you will be billed accordingly.
In case of success, calling the Redeem or Create and Redeem endpoint with the same parameters will always return the same redemption.

As noticed in the quickstart, order_id must be unique. It allows us to track your orders and can be used as well to reference your own client's orders.

Exemple:
Take an order of 3 giftcards (2x$20, 1x$10).order_id can start with the order identifier from your side (eg. ORD123), then the order line id ($20: L987, $10: L765), and finally an index (representing the quantity on your order line). You will finally obtain 3 differents order_ids: ORD123-L987-0, ORD123-L987-1 (for 2x$20) and ORD123-L765-0 (for 1x$10).

This way, you can easily rebuild the API request that came into error and ensure that you will be billed only for the code you retrieved.

How to cancel a redemption?

The redemption must not be redeemed, only pending or failed redemptions can be canceled.
You can cancel a redemption with the cancel action:

POST /fulfillment/v2/redemptions/{redemption_id}/actions/cancel

How to retrieve rewards stock information?

To retrieve stock information, you must use List all Rewards or Get a Reward APIs.
You will find two properties that will give you details on our stock: in_stock and stock_quantity.

in_stock is a boolean and will be true or false;
stock_quantity can be null or a number (eg. 5000). If it is null, it means that we are not managing a stock but a budget (in_stock will remain true as long as we have budget from our provider).

How to retrieve reward's "How to use" and "Important" instructions that are displayed in PDF?

This information describes the uses and limitations of gift cards. You can use this on your website to give your users insight into the rewards you sell.
For performance issue, it is only available in Get a Reward API in the following properties: how_to_use_instructions and important_instructions. This means that you will have to make an API call for each rewards.
This information is not often updated, you can retrieve it once a month.

You will also find description, terms_and_conditions, logo_url (brand logo) and catalog_card_url (gift card image).

How to retrieve discounts applied on my account?

You can retrieve discounts applied on your account using following API : List all Discounts. Here is an exemple of the JSON response from this API:

{
  "data": [
    ...
    {
      "id": 237,
      "sku": "ZAL-ZAL",
      "label": "E-carte cadeau Zalando",
      "discount": 5,
      "brand_sku": "ZAL",
      "brand_name": "Zalando"
    }
  ]
}

A discount applies to a product defined by a sku. You can also group discounts by brand_sku.

Please note that if a single brand has different products, each product may have its own discount.

How to retrieve barcode (when it's different from the primary code)?

Barcode is available in the JSON response of a redeemed redemption.

{
  "data": {
    ...
    "reward_codes": {
      "codes": {
        ...
        {
          "name": "Barcode",
          "value": "GAP-10USD-TEST-08-PIN-08",
          "format": "string",
          "usage": "barcode"
        }
      }
    }
  }
}

You also can find its format in the reward_format section.

"reward_format": {
  "barcode_type": "c128" // possible values: "none", "c128", "qrcode"
}

How to retrieve reward validity without making a redemption?

Reward validity is available in the expiration_date key from List all Rewards and Get a Reward APIs. This property is only available on rewards where we manage inventory.

How to retrieve my purchase cost on a reward?

You can retrieve the purchase cost of a reward (with the discount deducted from the original price) from List all Rewards and Get a Reward APIs, by adding the following query parameter: client_id.

client_id can be retrieved using following API: List all Clients.

GET /fulfillment/v2/rewards?client_id=123

Purchase cost can be found in the cost key.

How to retrieve redemption code format?

Redemption code format can be find in the reward_format.usages key in the redemption success response.
Possible values are ["primary"], ["primary", "security"], ["url"] and ["security_url", "security_url_code"].
When redeeming a redemption, you can have different codes in the reward_codes section. Refer to the usage key to match with possible usages.

    "reward_format": {
      "usages": ["primary", "security"] // possible values: ["primary"], ["primary", "security"], ["url"], ["security_url", "security_url_code"]
    },
    "reward_codes": {
      // Exhaustive list, it will change depending on the reward you used.
      // Pick the ones you need based on "reward_format.usages values".
      "codes": [
        // single code or code + pin
        {
          "name": "Gift Card Number",
          "value": "GAP-10USD-TEST-08",
          "format": "string",
          "usage": "primary"
        },
        // code + pin
        {
          "name": "PIN",
          "value": "PIN-08",
          "format": "string",
          "usage": "security"
        },
        // single link
        {
          "name": "Link",
          "value": "https://gift-card.partner.com/testifg21",
          "format": "url",
          "usage": "url"
        },
        // link + code
        {
          "name": "Security Url",
          "value": "https://secure-gift-card.partner.com/testifg21",
          "format": "url",
          "usage": "security_url"
        },
        // link + code
        {
          "name": "Security Url Code",
          "value": "12345",
          "format": "string",
          "usage": "security_url_code"
        },
        // PDF (if supported)
        {
          "name": "Printable document",
          "value": "https://app-sandbox.ifeelgoods.com/print/ecard/pczfj-e7yhg?o=1&t=148222f6aa913067d29502fd68f55ffa",
          "format": "url",
          "usage": "printable_document_url"
        },
        // barcode
        {
          "name": "Barcode",
          "value": "GAP-10USD-TEST-08-PIN-08",
          "format": "string",
          "usage": "barcode"
        }
      ]
    }

You can also find two optional additional usages: printable_document_url (a link to a PDF generated by Ifeelgoods) and barcode.

How to retrieve allowed range for free-value rewards?

Some rewards in our catalog allow free value. These rewards have a SKU ending with -VAR. You can also find them by checking the free_value key in List all Rewards or Get a Reward APIs.

Available range for these rewards is also available in the same APIs in the key dimensions. available_denominations_range.

Exemple:

        "dimensions": {
            "available_denominations_range": "5..250"
        },

You must split the value on ... Min value is the first one and max value the second one.

IMPORTANT: free-value rewards do not allow cents. Only values to the nearest euro are allowed.

How to retrieve advertiser's budget balance?

Advertiser's budget balance can be found in the balance key in List all Clients or Get a Client APIs. You can also retrieve the alert thresholds that has been configured for you on the platform via the budget_alerts key.