gift_card : Foxy hAPI

gift_card

Description

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 code associated with the gift card resource. 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.

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) The number of gift card code variations you would like to generate. For example, if you would like all the gift card code variations to have a "summer_special" prefix, set that here. 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 may want to create codes with an initial balance.

Interact with this resource

To interact with this resource and see it in the context of the API, you can utilise Postman or your Terminal/Console to perform requests. If you have a Foxy store, you can also use the API browser in the admin to interact with resources connected to your store.

Actions

GET: View a gift_card
PATCH: Update a gift_card (send only the properties you want to modify)
PUT: Replace a gift_card (send the entire representation)
DELETE: Delete a gift_card
HEAD: Get just the header response
OPTIONS: Get a response explaining which HTTP methods are supported

Properties

Property	Description	Type	Constraints
name	The name of this gift card. This will be displayed to the customer, such as "Gift Card" or "Store Credit".	String	Required. 50 characters or less.
currency_code	Currency code for this gift card. Note that gift cards are only usable if the cart's currency matches.	String	Optional. The 3 character ISO code for the currency.
expires_after	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.	String	Optional. If present, the format must be valid, such as 1m, 3w, 45d, etc.
product_code_restrictions	If you want to limit which products can use this gift card, you can enter a comma separated listed 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`. It wouldn't match `abc12`, `abc1234`, `fun`, or `good-smalls`.	String	Optional. 5000 characters or less.
sku	SKU used to add the gift card to the cart in order to buy it	String	Optional. 200 characters or less.
provisioning_config	Used for provisioning the gift card. It should contain the following data: `allow_autoprovisioning`, `initial_balance_min` `initial_balance_max`	JSON	Optional. 1000 characters or less.
date_created	The date this resource was created.	Date	Read only
date_modified	The date this resource was last modified.	Date	Read only

Example Representation

{
    "_links": {
        "curies": [
            {
                "name": "fx",
                "href": "https://api.foxycart.com/rels/{rel}",
                "templated": true
            }
        ],
        "self": {
            "href": "https://api.foxycart.com/gift_cards/6",
            "title": "test_gift_card_2"
        },
        "fx:attributes": {
            "href": "https://api.foxycart.test/gift_cards/6/attributes",
            "title": "Attributes for This Gift Card"
        },
        "fx:store": {
            "href": "https://api.foxycart.com/stores/40075",
            "title": "This Store"
        },
        "fx:generate_codes": {
            "href": "https://api.foxycart.com/gift_cards/6/generate_codes",
            "title": "Generate random Gift Cards Codes"
        },
        "fx:gift_card_codes": {
            "href": "https://api.foxycart.com/gift_cards/6/codes",
            "title": "Gift Card Codes"
        },
        "fx:gift_card_item_categories": {
            "href": "https://api.foxycart.com/gift_cards/6/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"
}

<?xml version="1.0" encoding="UTF-8"?>
<resource href="https://api.foxycart.com/gift_cards/6" rel="https://api.foxycart.com/rels/gift_card">
    <link rel="self" href="https://api.foxycart.com/gift_cards/6" title="test_gift_card_2"/>
    <link rel="https://api.foxycart.com/rels/store" href="https://api.foxycart.com/stores/40075" title="This Store"/>
    <link rel="https://api.foxycart.com/rels/generate_codes" href="https://api.foxycart.com/gift_cards/6/generate_codes" title="Generate random Gift Cards Codes"/>
    <link rel="https://api.foxycart.com/rels/gift_card_codes" href="https://api.foxycart.com/gift_cards/6/codes" title="Gift Card Codes"/>
    <link rel="https://api.foxycart.com/rels/gift_card_item_categories" href="https://api.foxycart.com/gift_cards/6/item_categories" title="Valid Item Categories for this Gift Card"/>
    <name>test_gift_card_2</name>
    <currency_code>USD</currency_code>
    <expires_after>1d</expires_after>
    <product_code_restrictions></product_code_restrictions>
    <date_created>2021-11-08T09:03:17-0800</date_created>
    <date_modified>2021-11-10T17:04:52-0800</date_modified>
</resource>

{
    "class": [
        "gift_card"
    ],
    "properties": {
        "name": "test_gift_card_2",
        "currency_code": "USD",
        "expires_after": "1d",
        "product_code_restrictions": null,
        "date_created": "2021-11-08T09:03:17-0800",
        "date_modified": "2021-11-10T17:04:52-0800"
    },
    "links": [
        {
            "rel": [
                "self"
            ],
            "href": "https://api.foxycart.com/gift_cards/6"
        },
        {
            "rel": [
                "https://api.foxycart.com/rels/store"
            ],
            "href": "https://api.foxycart.com/stores/40075"
        },
        {
            "rel": [
                "https://api.foxycart.com/rels/generate_codes"
            ],
            "href": "https://api.foxycart.com/gift_cards/6/generate_codes"
        },
        {
            "rel": [
                "https://api.foxycart.com/rels/gift_card_codes"
            ],
            "href": "https://api.foxycart.com/gift_cards/6/codes"
        },
        {
            "rel": [
                "https://api.foxycart.com/rels/gift_card_item_categories"
            ],
            "href": "https://api.foxycart.com/gift_cards/6/item_categories"
        }
    ],
    "actions": [
        {
            "name": "self",
            "title": "Update Gift Card",
            "method": "PATCH",
            "href": "https://api.foxycart.com/gift_cards/6",
            "type": "application/x-www-form-urlencoded",
            "fields": [
                {
                    "name": "name",
                    "title": "Name",
                    "type": "text",
                    "value": "test_gift_card_2"
                },
                {
                    "name": "currency_code",
                    "title": "Currency Code",
                    "type": "text",
                    "value": "USD"
                },
                {
                    "name": "expires_after",
                    "title": "Expires After",
                    "type": "text",
                    "value": "1d"
                },
                {
                    "name": "product_code_restrictions",
                    "title": "Product Code Restrictions",
                    "type": "text",
                    "value": null
                }
            ]
        },
        {
            "name": "generate_codes",
            "title": "Generate Codes",
            "method": "POST",
            "href": "https://api.foxycart.com/gift_cards/6/generate_codes",
            "type": "application/x-www-form-urlencoded",
            "fields": [
                {
                    "name": "length",
                    "title": "Length Of Code",
                    "type": "number",
                    "value": 6
                },
                {
                    "name": "number_of_codes",
                    "title": "Nubmer Of Codes",
                    "type": "number",
                    "value": 10
                },
                {
                    "name": "prefix",
                    "title": "Code Prefix",
                    "type": "text"
                }
            ]
        },
        {
            "name": "gift_card_codes",
            "title": "Create Gift Card Code",
            "method": "POST",
            "href": "https://api.foxycart.com/gift_cards/6/codes",
            "type": "application/x-www-form-urlencoded",
            "fields": [
                {
                    "name": "code",
                    "title": "Code",
                    "type": "text"
                },
                {
                    "name": "current_balance",
                    "title": "Current Balance",
                    "type": "text"
                },
                {
                    "name": "end_date",
                    "title": "End Date",
                    "type": "datetime"
                }
            ]
        }
    ]
}

Zoomable Resources

The following related resources can be embedded within this resource by including a ?zoom=<child_resource> parameter. You can also filter by child resources by ?child_resource:property=<property_value>

gift_card_codes
gift_card_item_categories