Gift Cards
info
This feature was introduced in Saleor 3.1.
caution
This feature is currently in Feature Preview. This part of Saleor is not complete and subject to change but is available to experiment and provide feedback.
Introduction
Gift cards can be created by staff users or bought by customers as a standard product. They can have an expiry date set or can never expired. Gift cards are not assigned to any channel, they can be used in any channel whose currency is the same as the currency of the gift card. During the first gift card usage, the customer user is assigned to the gift card and then the card can be used only by this user.
Creating gift cards
Any staff user with the MANAGE_GIFT_CARD
permission can create gift cards either one at a time or in bulk.
The following example shows how a single gift card can be created.
If userEmail
is provided and the email plugin is configured for provided channel,
the gift card is sent to the customer and the SENT_TO_CUSTOMER
event is created.
In this example expiry date will be set, as expiryDate
value is provided,
If you want to create never expired card, do not provide expiryDate
value.
mutation {
giftCardCreate(
input: {
balance: { amount: 100, currency: "USD" }
userEmail: "test@example.com"
channel: "channel-USD"
expiryDate: "2050-10-10"
isActive: true
}
) {
giftCard {
id
code
last4CodeChars
isActive
expiryDate
initialBalance {
currency
amount
}
currentBalance {
currency
amount
}
events {
type
}
}
}
}
As a response, we get a newly created active gift card with initial and current balance, generated code, and two events:
ISSUED
which informs that gift card has been created by staff,SENT_TO_CUSTOMER
as theuserEmail
has been provided and gift card has been sent. Also the staff user that run mutation has been assigned ascreatedBy
user. As the card hasn't been used yet, the fieldusedByUser
is empty.
{
"data": {
"giftCardCreate": {
"giftCard": {
"id": "R2lmdENhcmQ6MTE=",
"code": "ABCD-EFGH-IJKL",
"last4CodeChars": "IJKL",
"isActive": true,
"expiryDate": "2050-10-10",
"initialBalance": {
"currency": "USD",
"amount": 100.0
},
"currentBalance": {
"currency": "USD",
"amount": 100.0
},
"events": [
{
"type": "ISSUED"
}
{
"type": "SENT_TO_CUSTOMER"
}
]
}
}
}
}
Creating gift cards in bulk is similar, but you need to specify the number of gift cards to create and the tag value, that will be assigned to all created gift cards.
mutation {
giftCardBulkCreate(
input: {
count: 5
tag: "example-tag"
isActive: true
balance: { amount: 200.0, currency: "USD" }
}
) {
giftCards {
id
code
isActive
tag
}
}
}
We get five new gift cards:
{
"data": {
"giftCardBulkCreate": {
"giftCards": [
{
"id": "R2lmdENhcmQ6MjU=",
"code": "B13F-5C78-A18F",
"isActive": true,
"tag": "example-tag"
},
{
"id": "R2lmdENhcmQ6MjY=",
"code": "2CF4-BA56-1A5E",
"isActive": true,
"tag": "example-tag"
},
{
"id": "R2lmdENhcmQ6Mjc=",
"code": "BA14-A867-943C",
"isActive": true,
"tag": "example-tag"
},
{
"id": "R2lmdENhcmQ6Mjg=",
"code": "FC4A-DD96-F21A",
"isActive": true,
"tag": "example-tag"
},
{
"id": "R2lmdENhcmQ6Mjk=",
"code": "413A-2ECE-7F5A",
"isActive": true,
"tag": "example-tag"
}
]
}
}
}
After creation, you can export gift card codes to CSV, you can find more information about that here.
Gift card resending
At any time after creation, you can resend the gift card to the customer.
If the userEmail
is not provided, the card is sent to the customer who already used the card,
or if the card hasn't been used yet, to the customer that created the card.
Channel is required to choose the correct email plugin to send the gift card.
mutation {
giftCardResend(
input: {
id: "R2lmdENhcmQ6MjU="
channel: "default-channel"
email: "saleor@example.com"
}
) {
giftCard {
id
code
events {
type
user {
email
}
app {
name
}
}
}
}
}
Updating gift card
After creation, the tag, expiry date, and balance amount can be updated.
note
Remember, only the balance amount can be updated, currency cannot be changed, and updating is equal to reset the current balance value. Both initial and current balance is set to the provided value, no matter if the card was already used or not.
The following example shows updating the expiry date, tag, and balance amount reset.
mutation {
giftCardUpdate(
id: "R2lmdENhcmQ6MjU=",
input: {
balanceAmount: 70,
expiryDate: "2040-10-10",
tag: "new-tag",
}
) {
giftCard {
id
expiryDate
initialBalance {
currency
amount
}
currentBalance {
currency
amount
}
events {
type
expiryDate
oldExpiryDate
oldTag
tag
balance {
initialBalance {
amount
currency
}
oldInitialBalance {
amount
currency
}
currentBalance {
amount
currency
}
oldCurrentBalance {
amount
currency
}
}
}
}
}
As a result we get the updated gift card with new events
BALANCE_RESET
, EXPIRY_DATE_UPDATED
and TAG_UPDATED
as balance, expiry date and tag has been changed.
{
"data": {
"giftCardUpdate": {
"giftCard": {
"id": "R2lmdENhcmQ6MjU=",
"expiryDate": "2040-10-10",
"initialBalance": {
"currency": "USD",
"amount": 70.0
},
"currentBalance": {
"currency": "USD",
"amount": 70.0
},
"events": [
{
"type": "ISSUED",
"expiryDate": null,
"oldExpiryDate": null,
"oldTag": null,
"tag": null,
"balance": {
"initialBalance": {
"amount": 200.0,
"currency": "USD"
},
"oldInitialBalance": null,
"currentBalance": {
"amount": 200.0,
"currency": "USD"
},
"oldCurrentBalance": null
}
},
{
"type": "BALANCE_RESET",
"expiryDate": null,
"oldExpiryDate": null,
"oldTag": null,
"tag": null,
"balance": {
"initialBalance": {
"amount": 70.0,
"currency": "USD"
},
"oldInitialBalance": {
"amount": 200.0,
"currency": "USD"
},
"currentBalance": {
"amount": 70.0,
"currency": "USD"
},
"oldCurrentBalance": {
"amount": 200.0,
"currency": "USD"
}
}
},
{
"type": "EXPIRY_DATE_UPDATED",
"expiryDate": "2040-10-10",
"oldExpiryDate": null,
"oldTag": null,
"tag": null,
"balance": null
}
{
"type": "TAG_UPDATED",
"expiryDate": null,
"oldExpiryDate": null,
"oldTag": "example-tag",
"tag": "new-tag",
"balance": null
}
]
}
}
}
}
Activation and deactivation
Cards could be activated and deactivated at any time. You can activate and deactivate a single card or a bunch of cards.
To deactivate gift card just provide id
of the card to deactivate.
mutation {
giftCardDeactivate(id: "R2lmdENhcmQ6MjY=") {
giftCard {
id
isActive
events {
type
}
}
}
}
The deactivated gift card has been return with DEACTIVATED
event.
{
"data": {
"giftCardDeactivate": {
"giftCard": {
"id": "R2lmdENhcmQ6MjY=",
"isActive": false,
"events": [
{
"type": "ISSUED"
},
{
"type": "DEACTIVATED"
}
]
}
}
}
}
And similar for activation:
mutation {
giftCardActivate(id: "R2lmdENhcmQ6MjY=") {
giftCard {
id
isActive
events {
type
}
}
}
}
And we get active gift card with new ACTIVATED
event:
{
"data": {
"giftCardActivate": {
"giftCard": {
"id": "R2lmdENhcmQ6MjY=",
"isActive": true,
"events": [
{
"type": "ISSUED"
},
{
"type": "DEACTIVATED"
},
{
"type": "ACTIVATED"
}
]
}
}
}
}
For bulk activation use giftCardBulkActivate and for bulk deactivation use giftCardBulkDeactivate mutation.
Creating gift card products
Allowing customers to buy gift cards in your shop is pretty simple,
you just need to create gift card products.
Firstly you have to create a product type with GIFT_CARD
kind (use productTypeCreate for that)
and then create a product (use productCreate mutation)
with this product type and that's it.
note
If you want to have an unlimited number of gift cards in your shop you should create stock n a chosen channel with at least one quantity and unset track inventory flag.
Buying gift cards
Order setting automaticallyFulfillNonShippableGiftCard
defines when the bought gift cards
will be created. If this flag is set to True
, a gift card will be created during checkout completing.
The fulfillment will be created automatically, a gift card will be generated and sent to the customer.
If this option is unset, the gift card will be created during order fulfillment, and after that also sent to the customer.
The value of this option can be changed with use of orderSettingsUpdate mutation.
The expiry date of created gift cart is set based on gift card settings. Gift card settings can be set to never expiry or expiry period, based on which the card expiry date is calculated.
The gift card settings are set as never expiry by default and can be changed with use of giftCardSettingsUpdate. In the following example the gif card settings are set to 12 months.
mutation {
giftCardSettingsUpdate(
input: {
expiryType: EXPIRY_PERIOD
expiryPeriod: { type: YEAR, amount: 12 }
}
) {
giftCardSettings {
expiryType
expiryPeriod {
type
amount
}
}
}
}
As a result we get updated expiry settings.
{
"data": {
"giftCardSettingsUpdate": {
"giftCardSettings": {
"expiryType": "EXPIRY_PERIOD",
"expiryPeriod": {
"type": "YEAR",
"amount": 12
}
}
}
}
}
Using gift card in checkout
To use gift card in checkout just run checkoutAddPromoCode mutation with gift card code. When the gift card is used for the first time, the checkout user will be assigned to this gift card. If the card was already used, the checkout user will be compared with the gift card user, when the users differ, a validation error is raised. Also, remember that the channel currency must be the same as the card currency.