gift_card
Collection: gift_cards
Gift cards set the usage restrictions for gift card codes (which are the resources actually used by customers, and where individual balances are maintained). Each gift card can have one or more gift card codes associated with it. For most use cases, only one gift card would need to exist per store, but if you're selling in multiple currencies, or if you'd like to use gift cards as promotional items (more akin to coupons that can maintain balances), you may want to create multiple gift cards to allow for different settings per gift card.
If you create custom attributes for a gift card, they will automatically be included in the response as embedded resources without having to zoom in on them.
Notes
Creating Multiple Gift Card Codes: If you have a list of gift card codes you would like to add to this gift card, you can POST to the gift card's codes resource with an array of gift card codes like so:
{ "gift_card_codes": ["foo", "bar"], "current_balance": 100 }
Generating Gift Card Codes: To generate multiple gift card code variations, POST to the generate_codes link relationship with the following values:
- length: (optional) The length of the gift card code. Defaults to 6 characters.
- number_of_codes: (optional) The number of gift card code variations you would like. Defaults to 10.
- prefix: (optional) A prefix for all generated codes. Note: The length value is inclusive of this prefix, so a length of 10 with a prefix of "foo" would generate codes like "foo1234567".
- current_balance: (optional) Defaults to zero, but you may want to create codes with an initial balance.
Required Scopes
store_full_access gift_cards_read gift_cards_write Actions
Properties (8)
name String · Required · max 50 The name of this gift card. This will be displayed to the customer, such as "Gift Card" or "Store Credit".
currency_code String · Optional Currency code for this gift card. Note that gift cards are only usable if the cart's currency matches.
The 3 character ISO code for the currency.
expires_after String (nullable) · Optional This determines when the gift card will expire. The format is a number followed by a date type such as d (day), w (week), m (month), or y (year). You can also use .5m for twice a month, as with subscription frequency settings. Check with your local laws to ensure expiring gift cards is legal, according to your use case. The actual expiration date will be set on the gift_card_code resources when they are created, according to this setting.
If present, the format must be valid, such as 1m, 3w, 45d, etc.
product_code_restrictions String (nullable) · Optional · max 5000 If you want to limit which products can use this gift card, you can enter a comma separated list of product codes or partial product codes using * as a wild card at the beginning or end of the value. So abc123, fun_*, *-small would match abc123, fun_ and fun_times, and example-small.
sku String (nullable) · Optional · max 200 SKU used to add the gift card to the cart in order to buy it.
provisioning_config Object (nullable) · Optional · max 1000 Used for provisioning the gift card. It should contain the following data: allow_autoprovisioning (boolean), initial_balance_min (number), initial_balance_max (number).
date_created String (nullable) · Read-only The date this resource was created.
date_modified String (nullable) · Read-only The date this resource was last modified.
Link Relations (6)
self This Gift Card fx:generate_codes Generate random Gift Card Codes Zoomable Resources
Embed related resources using ?zoom=<resource>.
Filter with ?resource:property=value.
fx:gift_card on gift_card_code·fx:gift_card on gift_card_code_log_detail·fx:gift_card on gift_card_item_category Example Representation
{
"_links": {
"curies": [
{
"name": "fx",
"href": "https://api.foxycart.com/rels/{rel}",
"templated": true
}
],
"self": {
"href": "https://api.foxycart.com/gift_cards/123",
"title": "This Gift Card"
},
"fx:attributes": {
"href": "https://api.foxycart.com/gift_cards/123/attributes",
"title": "Attributes for This Gift Card"
},
"fx:store": {
"href": "https://api.foxycart.com/stores/456",
"title": "This Store"
},
"fx:generate_codes": {
"href": "https://api.foxycart.com/gift_cards/123/generate_codes",
"title": "Generate random Gift Card Codes"
},
"fx:gift_card_codes": {
"href": "https://api.foxycart.com/gift_cards/123/codes",
"title": "Gift Card Codes"
},
"fx:gift_card_item_categories": {
"href": "https://api.foxycart.com/gift_cards/123/item_categories",
"title": "Valid Item Categories for this Gift Card"
}
},
"name": "new test card",
"currency_code": "USD",
"expires_after": "1w",
"product_code_restrictions": null,
"sku": "test_card",
"provisioning_config": {
"allow_autoprovisioning": true,
"initial_balance_max": 12,
"initial_balance_min": 12
},
"date_created": "2021-11-08T09:03:17-0800",
"date_modified": "2021-11-10T17:04:52-0800"
}