gift_cards

Description

This link relationship returns a collection of resources. You can easily paginate through this collection using the hypermedia links provided and the link relationships of first, prev, next, and last. Scroll down to view a representation of a single resource embedded within this collection.

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 list of gift_cards
POST
Create a new gift_card
HEAD
Get just the header response
OPTIONS
Get a response explaining which HTTP methods are supported

Example Representation

{
  "_links": {
    "curies": [
      {
        "name": "fx",
        "href": "https://api.foxycart.com/rels/{rel}",
        "templated": true
      }
    ],
    "self": {
      "href": "...",
      "title": "This Collection"
    },
    "first": {
      "href": "...?offset=0",
      "title": "First Page of this Collection"
    },
    "prev": {
      "href": "...?offset=0",
      "title": "Previous Page of this Collection"
    },
    "next": {
      "href": "...?offset=0",
      "title": "Next Page of this Collection"
    },
    "last": {
      "href": "...?offset=0",
      "title": "Last Page of this Collection"
    }
  },
  "_embedded": {
    "fx:gift_cards": [...]
  },
  "total_items": "5",
  "returned_items": 5,
  "limit": 20,
  "offset": 0
}

<?xml version="1.0" encoding="UTF-8"?>
<resource href="...">
  <link rel="self" href="..." title="This Collection"/>
  <link rel="first" href="...?offset=0" title="First Page of this Collection"/>
  <link rel="prev" href="...?offset=0" title="Previous Page of this Collection"/>
  <link rel="next" href="...?offset=0" title="Next Page of this Collection"/>
  <link rel="last" href="...?offset=0" title="Last Page of this Collection"/>
  <resource href="..." rel="https://api.foxycart.com/rels/gift_card">
  ...
  </resource>
  <total_items>5</total_items>
  <returned_items>5</returned_items>
  <limit>20</limit>
  <offset>0</offset>
</resource>

{
    "properties": {
        "total_items": "5",
        "returned_items": 5,
        "limit": 20,
        "offset": 0
    },
    "entities": [...],
    "links": [
        {
            "rel": [
                "self"
            ],
            "href": "..."
        },
        {
            "rel": [
                "first"
            ],
            "href": "...?offset=0"
        },
        {
            "rel": [
                "prev"
            ],
            "href": "...?offset=0"
        },
        {
            "rel": [
                "next"
            ],
            "href": "...?offset=0"
        },
        {
            "rel": [
                "last"
            ],
            "href": "...?offset=0"
        }
    ],
    "actions": [
    ]
}

Embedded Resource: 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