Gift Cards

Gift cards can be purchased using the funds collected in a pot. They are added to orders to fulfill the purchase. On this page, we'll dive into the gift card endpoints you can use to manage gift cards programmatically.

The Gift Card model

The gift card model contains all the information about gift cards.

Monetary values are in the smallest currency unit. e.g. £1.50 would be represented as 150.

Properties

Name
id
Type
string
Description
Unique identifier for the gift card.
Name
active
Type
boolean
Description
Whether the gift card is currently available for purchase.
Name
images
Type
array
Description
A list of up to 8 URLs of images for this gift card, meant to be displayable to the customer.
Name
metadata
Type
hash
Description
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
Name
name
Type
string
Description
The brand name, meant to be displayable to the customer.
Name
description
Type
string
Description
The gift card description, meant to be displayable to the customer.
Name
currency
Type
string
Description
The currency of the gift card. Values can either be GBP or USD.
Name
price
Type
hash
Description
Details of the price of the object.
Name
price.type
Type
enum
Description
Determines whether the gift card is open value. Values can either be open_value or fixed.
Name
price.start_price
Type
integer
Description
The minimum amount that can be loaded onto a gift card.
Name
price.end_price
Type
integer
Description
The maximum amount that can be loaded onto a gift card.
Name
in_stock
Type
boolean
Description
Whether the gift card is in stock. Can be used to indicate to the customer whether the gift card is in stock.

GET/v1/gift-cards

List all gift cards

This endpoint allows you to retrieve a paginated list of all the gift cards. By default, a maximum of ten gift cards are shown per page.

Optional attributes

Name
limit
Type
integer
Description
Limit the number of results returned.
Name
page
Type
integer
Description
The page you wish to fetch.

Request

GET

/v1/gift-cards

curl -G https://api.collctiv.com/v1/gift-cards \
  -H "Authorization: Bearer {token}" \
  -d limit=3

Response

{
    "has_more": false,
    "data": [
        {
            "id": "999fe8d5-1615-414b-83fc-2740b3c4a899",
            "created_at": 692233200,
            "name": "John Lewis Gift Card",
            "description": "John Lewis & Partners began trading over 150 years ago in 1864 on London's Oxford Street, and is a leading omni-channel retailer in the UK with 34 John Lewis shops plus one outlet and online access through johnlewis.com. With an extensive range to choose from, John Lewis is an ideal destination for all your needs whether it be for a new sofa or for a gift for family or friend - there’s a huge range of brands available to suit your needs.",
            "currency": "GBP",
            "price": {
                "type": "open_value",
                "start_price": 500,
                "end_price": 25000
            },
            "in_stock": true,
            "active": true,
            "images": [
                "https://images.com/image.jpg"
            ],
            "metadata":{}
        },
        {
        "id": "3b241101-e2bb-4255-8caf-4136c566a962"
        // ...
        }
  ]
}

GET/v1/gift-cards/:id

Retrieve a gift card

This endpoint allows you to retrieve a gift card by providing the gift card id. Refer to the list at the top of this page to see which properties are included with gift card object.

Request

GET

/v1/gift-cards/999fe8d5-1615-414b-83fc-2740b3c4a899

curl https://api.collctiv.com/v1/gift-cards/999fe8d5-1615-414b-83fc-2740b3c4a899 \
  -H "Authorization: Bearer {token}"

Response

{
    "id": "999fe8d5-1615-414b-83fc-2740b3c4a899",
    "name": "John Lewis Gift Card",
    "description": "John Lewis & Partners began trading over 150 years ago in 1864 on London's Oxford Street, and is a leading omni-channel retailer in the UK with 34 John Lewis shops plus one outlet and online access through johnlewis.com. With an extensive range to choose from, John Lewis is an ideal destination for all your needs whether it be for a new sofa or for a gift for family or friend - there’s a huge range of brands available to suit your needs.",
    "currency": "GBP",
    "price": {
        "type": "open_value",
        "start_price": 500,
        "end_price": 25000
    },
    "in_stock": true,
    "active": true,
    "images": [
        "https://images.com/image.jpg"
    ],
    "metadata":{}
}