Selling Giftcards
est. reading time: 5 minutes.
You can sell giftcards through this API. You can only sell pre-created giftcards. This API does not allow you to create giftcards on demand and then sell those. We provide blanco giftcards for this purpose. Send us an email to support@zmyle.de if you are interested in selling giftcards (either your own or our community giftcards).
When you sell a giftcard, you are activating a blanco giftcard in our system. Thats why we sometimes use the terms "activate" and "sell" interchangeably.
Find a Giftcard
Before you can activate a giftcard you need to find the giftcard record within our API. You can find more info on how to find a giftcard in the API reference. Once you have a giftcard object, you can determine if and how you can activate that giftcard.
A possible scenario: imagine a customer grabs a giftcard off the stack in your store. During checkout, you'd want this giftcard to show up as an article with a price tag amongst your checkout items. With the help of our API, your cash register can find that "article" and the price tag and simply add it to the checkout items.
Eligibility to Sell
Once you found the giftcard object in our API, before you can activate, you need to check if you are even ok to activate this giftcard. There is two attributes in the giftcard object that tell you so:
expectedAction: this field should have a value of
activate. Otherwise this giftcard cannot be activated.authorizedActions: this is an array of strings. This array needs to contain the string
activate. Otherwise this giftcard cannot be activated by you.
You are always authorized to activate your own giftcards that you received from us that are only valid in your own store. But if you also want to activate community giftcards you need to be manually authorized to do so. Just get in touch with us at support@zmyle.de if you're interested.
Failure to check results in an error response from our API if you try to activate a giftcard but are not authorized to do so.
Activate a Giftcard
Fixed Amount Giftcards
Fixed amount giftcards are giftcards that have a predefined amount for activation. That amount is set and can't be changed. For example, if a giftcard has a fixed amount of 25,00 EUR then it is meant to be activated for 25,00 EUR only, not more not less.
You can see if the giftcard is a fixed amount giftcard by checking in activation.isDynamicAmount. If false, then this is a fixed amount giftcard. The fixed amount itself is found in activation.amount.
Remember that all our money values are given in cents as integers values.
To activate, you need to use the id and the accessToken from the giftcard object:
Dynamic Amount Giftcards
Dynamic amount giftcards are giftcards that set bounds for the activation amount, but you can activate those giftcards for any arbitrary amount within those bounds.
You can see if the giftcard is a dynamic amount giftcard by checking in activation.isDynamicAmount. If true, then this is a dynamic amount giftcard. The bounds for the amount are found in activation.minAmount and activation.maxAmount respectively.
To activate, you need to use the id and the accessToken from the giftcard object, and you need to define the amount for the activation in the request payload. For example to activate a dynamic amount giftcard with 50,00 EUR:
Giftcard Balance Boost Campaigns
Boost campaigns are multi-day events in our system where a sponsor can provide a balance-boost to giftcards of certain kinds. If you were to activate a giftcard that is eligible for a balance boost, then that giftcard would enjoy a higher balance then what you sold it for. If you'd activate a giftcard for 100,00 EUR, and there was a boost of 20%, then the giftcard balance after activation would be 120,00 EUR.
There is nothing you need to do for this boost, it is automatically applied during activation. There is absolutely no difference in how you activate such giftcards. But we think that it is worth knowing what will happen to the giftcard when activating. So we added a field campaignBoost that is only present when this giftcard is eligible for a balance boost upon activation. The Giftcard Campaign Boost Info object holds all important info about such a campaign event. Most importantly:
rateandfixed,whereas rate is a percentage and fixed is a money amount.maxBoostAmount,the maximum balance-boost amount.
From this the balance-boost amount (the amount that will be added to the balance) can be derived:
Multiply the activation amount by rate, then add fixed and you get the balance-boost amount .
We encourage you to display this balance boost amount info within your integration, before activating the giftcard.
Last updated