Skip to content

Gift Cards

Overview

A Gift card represents a fixed amount that can be used to buy services and products. In relation to the tax rates two types of gift cards are supported in the system:

  • single-purpose gift card - linked to a non-zero tax rate
  • multi-purpose gift card - linked to zero tax rate

A single-purpose gift card is limited and can only be applied on products and services of the same tax rate. On the contrary, a multi-purpose gift card can be applied on sold items of any tax rate.

In terms of how the redeem code is provided we differentiate two types of gift cards as well:

  • Standard gift card - coreAPI generates the redeem code when the gift card is being sold.
  • Pre-coded gift card - the redeem code is provided by the user (merchant) during the gift card creation.

Redeem codes are considered as case-insensitive and unique per account (merchant).

CoreAPI also supports external gift cards, i.e., gift cards issued by other systems which can be imported in coreAPI and then redeemed by the end users. The external gift cards that require a redeem code only, without a pin or other types of additional code, are currently supported.

When redeeming gift cards, one or more gift cards are redeemed up to the full amount being paid or until the gift cards are fully redeemed. It is not possible to specify an amount that is to be redeemed. Partially redeemed gift cards can be used in other purchases, as long as they have not expired.

Workflow

Issue/Create Gift Card

  1. Create a gift card template, also known as gift card product.
  2. Create an order to sell gift card(s).
  3. Add payment for the gift card(s) and complete the checkout.
  4. Gift card(s) issued and redeemable

Redeeming Gift Card

  1. Create an order for selling products and/or services.
  2. Optionally, if not added in step 1, add redeemable gift card(s) to the order.
  3. Optionally, remove gift card(s) from the order.
  4. Add remaining (or zero) payment amount to the order and complete the checkout.

Importing Gift Cards

  1. Download Gift card import xlsx template.
  2. Add required external gift cards data to the template.
  3. Import the xlsx file.

Create Gift Card Product Template

POST /api/v2/giftcards/

Params

param type/format required sample value description
name string true "My Gift Card" Gift card name
tax_type integer true 7122 ID of an existing tax rate.
description string false "" Gift card description
quantity float false 100 Initial stock.
reorder_level float false 10 Stock level where the app will signal that you should reorder the goods. Default: 0.
safety_stock float false 5 Stock level where the app will signal that you're running out of stock. Default: 0
price float false 25.99 Net price, base for all calculations. gross_price = price + (price * tax_rate)
purchase_price float false 15.50 Wholesale price.
custom_price boolean false false With this option set to true, in POS app you can override the regular price. Default: false
product_code string false "112123" Gift card identifier of your choice.
ean string false "78687868" Gift card barcode.
type string true "gift_card" Required if is_giftcard not set.
is_giftcard boolean true true Required if type not set.

Gift card template params:

param type/format required sample value description
valid_until_unit string true "day" Gift card validity unit. Valid values are day, week, month and year. Required if valid_until_date is not set.
valid_until_value int true 100 Gift card validity period. Required if valid_until_date is not set.
valid_until_date string true "2023-07-21T23:59:59" Gift card expiration date. Required and has precedence over valid_until_unit and valid_until_value.
type string true "single-purpose" Gift card type, single-purpose or multi-purpose.
is_precoded boolean false true Set to true to create pre-coded gift cards.

Standard Gift Cards

Request

curl -X POST \
  curl --request POST --location 'https://app.inventorum.com/api/v2/giftcards/' \
--header 'Authorization: Token c0432454af85314b8c6331c97f71152cbade854c' \
--header 'X-Api-Version: 12' \
--header 'Content-Type: application/json' \
--data-raw '{
    "type": "gift_card",
    "is_giftcard": true,
    "name": "SP GC product",
    "tax_type": 67483,
    "price": "84.0336",
    "quantity": 10,
    "giftcard_template": {
        "valid_until_date": "2023-07-21T22:59:59",
        "type": "single-purpose"
    }
}'

Response

Status 201 Created
{
    "giftcard_template": {
        "valid_until_value": null,
        "valid_until_unit": "month",
        "valid_until_date": "2023-07-21T22:59:59",
        "valid_products": null,
        "valid_categories": null,
        "accounts": null,
        "is_precoded": false,
        "type": "single-purpose"
    },
    "attributes": {},
    "name": "SP GC product",
    "id": 17518947,
    "quantity": "10.00",
    "reorder_level": "0.00",
    "safety_stock": "0.00",
    "price": "84.0336",
    "tax_type": 67483,
    "custom_price": false,
    "ebay_product_id": null,
    "ebay_url": null,
    "in_shop": false,
    "shop_url": null,
    "thumbnail": null,
    "variation_count": 0,
    "variations": [],
    "average_purchase_price": "0",
    "description": "",
    "product_code": null,
    "ean": null,
    "categories": [],
    "images": [],
    "custom_sale": false,
    "shipping_services": [],
    "is_favourite": false,
    "brand": "",
    "supplier": "",
    "meta": {},
    "is_giftcard": true,
    "gross_price": "100.00",
    "purchase_price": "0",
    "states": [],
    "attributes_str": "",
    "inv_id": "612897743064022725",
    "package_size_value": null,
    "package_size_unit": null,
    "base_price": null,
    "base_size_value": null,
    "base_size_unit": null,
    "recommended_price": null,
    "type": "gift_card",
    "source": null,
    "external_id": null
}

Error

Status 400 Bad Request
{
    "giftcard_template": [
        "This field is required."
    ]
}

Pre-coded Gift Cards

Create Gift Card Product/Template Request

curl --request POST --location 'https://app.inventorum.com/api/v2/giftcards/' \
--header 'Authorization: Token c0432454af85314b8c6331c97f71152cbade854c' \
--header 'X-Api-Version: 12' \
--header 'Content-Type: application/json' \
--data-raw '{
    "type": "gift_card",
    "is_giftcard": true,
    "name": "PGC_MP-",
    "tax_type": 67485,
    "gross_price": 100.00,
    "purchase_price": 0,
    "price": 100,
    "quantity": 0,
    "giftcard_template": {
        "valid_until_value": 100,
        "valid_until_unit": "day",
        "type": "multi-purpose",
        "is_precoded": true
    }
}'

Response

Status 201 Created
{
    "giftcard_template": {
        "valid_until_value": 100,
        "valid_until_unit": "day",
        "valid_until_date": null,
        "valid_products": null,
        "valid_categories": null,
        "accounts": null,
        "is_precoded": true,
        "type": "single-purpose"
    },
    "attributes": {},
    "name": "PGC_SP-",
    "id": 17518983,
    "quantity": "0.00",
    "reorder_level": "0.00",
    "safety_stock": "0.00",
    "price": "100",
    "tax_type": 67483,
    "custom_price": false,
    "ebay_product_id": null,
    "ebay_url": null,
    "in_shop": false,
    "shop_url": null,
    "thumbnail": null,
    "variation_count": 0,
    "variations": [],
    "average_purchase_price": "0",
    "description": "",
    "product_code": null,
    "ean": null,
    "categories": [],
    "images": [],
    "custom_sale": false,
    "shipping_services": [],
    "is_favourite": false,
    "brand": "",
    "supplier": "",
    "meta": {},
    "is_giftcard": true,
    "gross_price": "119.00",
    "purchase_price": "0",
    "states": [],
    "attributes_str": "",
    "inv_id": "612897750425816109",
    "package_size_value": null,
    "package_size_unit": null,
    "base_price": null,
    "base_size_value": null,
    "base_size_unit": null,
    "recommended_price": null,
    "type": "gift_card",
    "source": null,
    "external_id": null
}

Error

Status 400 Bad Request
{
    "quantity": [
        "For Precoded Cards quantity should be 0."
    ]
}

Add Pre-coded Gift Cards

POST /api/v2/giftcards/{{giftcard_product_id}}/pre_coded/

Pre-coded gift cards must be added before they can be sold, i.e., issued.

Params

param type/format required sample value description
redeem_code string true "1658-ABCD-7189" Gift card redeem code.
card_code string true "31273-jdha-13" Gift card card code.
product int true 17518983 Gift card product ID.

Request

curl --request POST --location 'https://app.inventorum.com/api/v2/giftcards/17518983/pre_coded/' \
--header 'Authorization: Token c0432454af85314b8c6331c97f71152cbade854c' \
--header 'X-Api-Version: 12' \
--header 'Content-Type: application/json' \
--data-raw '[
    {
        "redeem_code": "16587189",
        "card_code": "1669641141",
        "product": 17518983
    }
]'

Response

Status 200 OK
[
    {
        "id": 7591,
        "redeem_code": "xxxxxxxxxx",
        "card_code": "1669641141",
        "is_issued": false,
        "product": 17518983
    }
]

List Gift Cards Templates

GET /api/v2/giftcards/

Lists all Gift Cards products.

param type/format required sample value description
limit integer false 100 default value: 25
page integer false 10 page number
elide string false categories,giftcard_template Omit one or more fields from the response.
ordering string false quantity,-price Sort results by given fields. Valid values: name, time_added, time_modified, quantity, price
filters string false gross_price=100 Options: name, tax_type, product_code, ean, quantity, price, gross_price, categories.

Request

curl --request GET --location 'https://app.inventorum.com/api/v2/giftcards/' \
--header 'Authorization: Token c0432454af85314b8c6331c97f71152cbade854c' \
--header 'X-Api-Version: 12'

Response

Status 200 OK
{
    "count": 82,
    "next": "https://app.inventorum.com/api/v2/giftcards/?page=2",
    "previous": null,
    "results": [
        {
            "id": 17506537,
            "name": "PGC_SP-",
            "description": "",
            "quantity": "1.00",
            "price": "100.0000000000",
            "purchase_price": "0",
            "gross_price": "107.00",
            "custom_price": false,
            "tax_type": 67484,
            "product_code": null,
            "ean": null,
            "inv_id": 612875454796379892,
            "giftcard_template": {
                "valid_until_value": 100,
                "valid_until_unit": "day",
                "valid_until_date": null,
                "valid_products": null,
                "valid_categories": null,
                "accounts": null,
                "is_precoded": true,
                "type": "single-purpose"
            },
            "categories": [],
            "images": []
        },
        ...
        {
            "id": 17506839,
            "name": "GC_SP-",
            "description": "",
            "quantity": "1.00",
            "price": "100.0000000000",
            "purchase_price": "1E+2",
            "gross_price": "107.00",
            "custom_price": false,
            "tax_type": 67484,
            "product_code": null,
            "ean": null,
            "inv_id": 612877347525163995,
            "giftcard_template": {
                "valid_until_value": 100,
                "valid_until_unit": "day",
                "valid_until_date": "2022-12-13T21:59:59Z",
                "valid_products": null,
                "valid_categories": null,
                "accounts": null,
                "is_precoded": false,
                "type": "single-purpose"
            },
            "categories": [
                {
                    "id": 192056,
                    "hint": "feed category",
                    "name": "feed category"
                }
            ],
            "images": []
        },
    ]
}

Retrieve Specific Gift Card Template

GET /api/v2/giftcards/{{giftcard_product_id}}/

Retrieves a specific gift card product.

Request

curl --request GET --location 'https://app.inventorum.com/api/v2/giftcards/17518983/' \
--header 'Authorization: Token c0432454af85314b8c6331c97f71152cbade854c' \
--header 'X-Api-Version: 12'

Response

Status 200 OK
{
    "id": 17518983,
    "name": "PGC_SP-",
    "description": "",
    "quantity": "1.00",
    "price": "100.0000000000",
    "purchase_price": "0",
    "gross_price": "119.00",
    "custom_price": false,
    "tax_type": 67483,
    "product_code": null,
    "ean": null,
    "inv_id": 612897750425816109,
    "giftcard_template": {
        "valid_until_value": 100,
        "valid_until_unit": "day",
        "valid_until_date": null,
        "valid_products": null,
        "valid_categories": null,
        "accounts": null,
        "is_precoded": true,
        "type": "single-purpose"
    },
    "categories": [],
    "images": []
}

Retrieve Pre-Coded Gift Card

GET /api/v2/giftcards/{{giftcard_product_id}}/pre_coded/{{precoded_giftcard_id}}/

Retrieves a specific pre-coded Gift Card, issued or non-issued.

Request

curl --request GET --location 'https://app.inventorum.com/api/v2/giftcards/17518983/pre_coded/7591/' \
--header 'Authorization: Token c0432454af85314b8c6331c97f71152cbade854c' \
--header 'X-Api-Version: 12' 

Response

Status 200 OK
{
    "id": 7591,
    "redeem_code": "xxxxxxxxxx",
    "card_code": "1669641141",
    "is_issued": false,
    "product": 17518983
}

Update Gift Card Product

PUT/PATCH /api/v2/giftcards/{{giftcard_product_id}}/

Updates Gift Card product and template data using PUT or PATCH request.

Params

param type/format required sample value description
name string false "New Gift Card" Gift card name
description string false "19% Tax rate GC" Gift card description
price float false 25.99 Net price, base for all calculations. gross_price = price + (price * tax_rate)
purchase_price float false 15.50 Wholesale price.
custom_price boolean false false With this option set to true, in POS app you can override the regular price.
product_code string false "112123" Gift card identifier of your choice.
ean string false "78687868" Gift card barcode.
valid_until_unit string false "day" Gift card validity unit. Valid values are day, week, month and year.
valid_until_value int false 100 Gift card validity period.
valid_until_date string false "2023-07-21T23:59:59" Gift card expiration date.
categories object false "categories": [{"id": 12345}] List of existing categories you would like to assign the Gift Card to.
images object false images[{"id": 123, "new": true}] List of existing images that you would like to associate the Gift Card with.

Request

curl --request PUT --location 'https://app.inventorum.com/api/v2/giftcards/17518947/' \
--header 'Authorization: Token c0432454af85314b8c6331c97f71152cbade854c' \
--header 'X-Api-Version: 12' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "SP GC updated",
    "description": "new description",
    "purchase_price": "89.99",
    "gross_price": "111.11",
    "valid_until_value": 12,
    "valid_until_unit": "month",
    "valid_until_date": "2101-01-01T00:00:00Z",
    "ean": "222333444",
    "product_code": "abcd1122",
    "custom_price": true,
    "categories": [
        {
            "id": 197652
        }
    ],
    "images": [
        {
            "id": 1020871,
            "new": true
        }
    ]
}'

Response

Status 200 OK
{
    "id": 17495597,
    "name": "SP GC updated",
    "description": "new description",
    "quantity": "1.00",
    "price": "93.36974789915966386554621849",
    "purchase_price": "89.99",
    "gross_price": "111.11",
    "custom_price": true,
    "tax_type": 65205,
    "product_code": "abcd1122",
    "ean": "222333444",
    "inv_id": 8683348309952876026,
    "giftcard_template": {
        "valid_until_value": 12,
        "valid_until_unit": "month",
        "valid_until_date": "2101-01-01T00:00:00Z",
        "valid_products": null,
        "valid_categories": null,
        "accounts": null,
        "is_precoded": false,
        "type": "single-purpose"
    },
    "categories": [
        {
            "id": 191284,
            "hint": "array category",
            "name": "array category"
        }
    ],
    "images": [
        {
            "ipad": "https://app.inventorum.com/uploads/22281/product/aa/31/49/e1/14/44/4b/24/06/8e/ab/9c/e5/2a/81/aa3149e114444b24068eab9ce52a8109.ipad.png",
            "thumb": "https://app.inventorum.com/uploads/22281/product/aa/31/49/e1/14/44/4b/24/06/8e/ab/9c/e5/2a/81/aa3149e114444b24068eab9ce52a8109.thumb.png",
            "image": "https://app.inventorum.com/uploads/22281/product/aa/31/49/e1/14/44/4b/24/06/8e/ab/9c/e5/2a/81/aa3149e114444b24068eab9ce52a8109.ipad.png",
            "ipad_retina": "https://app.inventorum.com/uploads/22281/product/aa/31/49/e1/14/44/4b/24/06/8e/ab/9c/e5/2a/81/aa3149e114444b24068eab9ce52a8109.ipad_retina.png",
            "ebay": "https://app.inventorum.com/uploads/22281/product/aa/31/49/e1/14/44/4b/24/06/8e/ab/9c/e5/2a/81/aa3149e114444b24068eab9ce52a8109.ebay.png",
            "thumb_retina": "https://app.inventorum.com/uploads/22281/product/aa/31/49/e1/14/44/4b/24/06/8e/ab/9c/e5/2a/81/aa3149e114444b24068eab9ce52a8109.thumb_retina.png",
            "original": "https://app.inventorum.com/uploads/22281/product/aa/31/49/e1/14/44/4b/24/06/8e/ab/9c/e5/2a/81/aa3149e114444b24068eab9ce52a8109.original.png",
            "new": true,
            "id": -1020871
        }
    ]
}

Update Pre-coded Gift Card

PUT /api/v2/giftcards/{{giftcard_product_id}}/pre_coded/{{precoded_giftcard_id}}/

Updates a pre-coded Gift Card.

Params

param type/format required sample value description
redeem_code string false "1658-ABCD-7189" Gift card redeem code.
card_code string false "31273-jdha-13" Gift card card code.
product int true 17518983 Gift card product to associate with.

Request

curl -request PUT --location 'https://app.inventorum.com/api/v2/giftcards/17519027/pre_coded/7591/' \
--header 'Authorization: Token e49edf23e8f7625b39ae7d64176aafca42d79037' \
--header 'X-Api-Version: 12' \
--header 'Content-Type: application/json' \
--data-raw '{
    "redeem_code": "91666595",
    "card_code": "1669671715",
    "product": 17519028
}'

Response

Status 200 OK
{
    "id": 7627,
    "redeem_code": "xxxxxxxxxx",
    "card_code": "1669672023",
    "is_issued": false,
    "product": 17519028
}

Delete Gift Card Template

DELETE /api/v2/giftcards/{giftcard_product_id}

Deletes a Gift Card product and template.

curl --request DELETE --location 'https://app.inventorum.com/api/v2/giftcards/17518947/' \
--header 'Authorization: Token e49edf23e8f7625b39ae7d64176aafca42d79037' \
--header 'X-Api-Version: 12' \
--data-raw ''
Status 204 No Content

Delete Pre-coded Gift Card

DELETE /api/v2/giftcards/{{giftcard_product_id}}/pre_coded/{{precoded_giftcard_id}}/

Deletes a pre-coded Gift Card.

curl --request DELETE --location 'https://app.inventorum.com/api/v2/giftcards/17519030/pre_coded/7628/' \
--header 'Authorization: Token e49edf23e8f7625b39ae7d64176aafca42d79037' \
--header 'X-Api-Version: 12' 
Status 200 OK

Sell/Issue Gift Cards

POST /api/basket/

A Gift Card can be redeemed only after it was previously sold, i.e., issued. For standard Gift Cards the redeem code is generated by the system when the Gift Card is issued. Pre-coded Gift Cards have user-defined redeem code.

Create a basket to sell Gift Cards as any other product.

curl --request POST --location 'https://app.inventorum.com/api/basket/' \
--header 'Authorization: Token 8e427c2c161317fe4f49b18eef7ddc3823b5f15c' \
--header 'X-Api-Version: 12' \
--header 'Content-Type: application/json' \
--data-raw '{
    "items": [
        {
            "price": 100.00,
            "product": 17519086,
            "quantity": 1
        },
        {
            "price": 50,
            "product": 17519087,
            "quantity": 1
        }
    ],
    "note_internal": "GC internal note - Convertible",
    "note_external": "GC external note - Branding"
}'
Status 200 OK
{
    "total": "150.00",
    "id": 15427641,
    "user": 31169,
    "customer": null,
    "basket": 15428412,
    "state": "01",
    "completed_at": "2022-11-29T11:44:52.430+01:00",
    "channel": 1,
    "shipment": null,
    "description": null,
    "external_id": null
}

Paying for Gift Cards

POST /api/basket/{{order_id}}/payment/

Add a payment and complete the checkout like for any other order.

curl --request POST --location 'https://app.inventorum.com/api/basket/15427641/payment/' \
--header 'Authorization: Token 8e427c2c161317fe4f49b18eef7ddc3823b5f15c' \
--header 'X-Api-Version: 12' \
--header 'Content-Type: application/json' \
--data-raw '{
    "rounded": "0",
    "amount": 150.00,
    "method": 0
}'
Status 200 OK
{
    "id": 15427641,
    "basket": {
        "note_internal": "GC internal note - lime",
        "note_external": "GC external note - context-sensitive",
        "items": [
            {
                "id": 30542489,
                "name": "SP GC- 674886243216",
                "discount": null,
                "original_quantity": "1.00",
                "price": "84.0336000000",
                "product": 17519086,
                "quantity": 1,
                "tax_rate": "19.000",
                "gross_price": "100.00",
                "type": "gift_card",
                "external_id": null,
                "unit_gross_price": "100.00",
                "product_code": null,
                "giftcard_id": 46473,
                "giftcard_type": "single-purpose",
                "info": null,
                "user": null,
                "employees": []
            },
            {
                "id": 30542490,
                "name": "GC_MP- 138628948516",
                "discount": null,
                "original_quantity": "1.00",
                "price": "50.0000000000",
                "product": 17519087,
                "quantity": 1,
                "tax_rate": "0.000",
                "gross_price": "50.00",
                "type": "gift_card",
                "external_id": null,
                "unit_gross_price": "50.00",
                "product_code": null,
                "giftcard_id": 46474,
                "giftcard_type": "multi-purpose",
                "info": null,
                "user": null,
                "employees": []
            }
        ],
        "discount": null,
        "receipt": {
            "pdf": "https://app.inventorum.com/uploads/invoices/23965/Moj-Lipi-Sop-75.pdf",
            "image_width": 1,
            "image_height": 1,
            "image": "https://app.inventorum.com/uploads/invoices/23965/Moj-Lipi-Sop-75.png"
        },
        "invoice_number": "75",
        "used_giftcards": []
    },
    "state": 360,
    "customer": null,
    "amount_paid": "150.0000000000",
    "payments": [
        {
            "id": 14504876,
            "payment_method": "0",
            "payment_amount": "150.0000000000",
            "date": "2022-11-29T10:45:16+00:00",
            "transaction_id": null,
            "transaction_duration": null,
            "paypal_invoice_id": null,
            "paypal_tab_id": null,
            "external_payment_method": null,
            "giftcard_id": null,
            "giftcard_type": null,
            "giftcard_discount": null,
            "state": {
                "name": "Accepted",
                "id": 0
            }
        }
    ],
    "shipment": null,
    "channel": "ipad",
    "time_added": "2022-11-29T10:44:52+00:00",
    "completed_at": "2022-11-29T10:45:17+00:00",
    "description": null,
    "user": 31169,
    "total": "150.00",
    "external_id": null,
    "delta_state": "updated",
    "user_id": 31169,
    "available_refund_types": [
        "0",
        "6",
        "1",
        "3",
        "2",
        "19",
        "20"
    ],
    "ksv_payloads": [],
    "printable": []
}

After completing the checkout the redeem code is added to the basket item name, for standard Gift Cards. For pre-coded Gift Cards the card code is added instead.

Redeem Gift Cards

To redeem a Gift Card v2 it needs to be added to an order when the basket is created or afterwards when the order is in state Draft or Pending. The Gift Card is redeemed just before the payment is processed.

POST /api/basket/

Note: Gift Cards v2 are not and cannot be used as a payment method, unlike the old, v1, Gift Cards.

Add Gift Cards during the basket creation:

curl --request POST --location 'https://app.inventorum.com/api/basket/' \
--header 'Authorization: Token 023a2ad4d77e01934059cc51310665c129485ef1' \
--header 'X-Api-Version: 12' \
--header 'Content-Type: application/json' \
--data-raw '{
    "items": [
        {
            "name": "Pants",
            "price": 95.62,
            "product": 17519104,
            "quantity": 1
        },
        {
            "name": "Keyboard",
            "price": 10.00,
            "product": 17519100,
            "quantity": 1
        },
        {
            "name": "Shirt",
            "price": 25.76,
            "product": 17519103,
            "quantity": 1
        }
    ],
    "redeem_code": [
        674886243216,
        138628948516
    ]
}'
Status 200 OK
{
    "total": "0.00",
    "id": 15427672,
    "user": 31169,
    "customer": null,
    "basket": 15428443,
    "state": "01",
    "completed_at": "2022-11-29T15:54:38.429+01:00",
    "channel": 1,
    "shipment": null,
    "description": null,
    "external_id": null
}

Apply Gift Cards to Order

POST /api/basket/{{order_id}}/add_giftcard
To add one or more Gift Cards to an order after the basket is created use the following request.

curl --request POST --location 'https://app.inventorum.com/api/orders/15427672/add_giftcard' \
--header 'Authorization: Token 023a2ad4d77e01934059cc51310665c129485ef1' \
--header 'X-Api-Version: 12' \
--header 'Content-Type: application/json' \
--data-raw '{
    "redeem_code": [
        "674886243216",
        "138628948516"
    ]
}'
Status 201 Created

Remove Gift Cards from Order

DELETE /api/basket/{{order_id}}/add_giftcard
Similarly, one or more Gift Cards can be removed from an order.

curl --request DELETE --location 'https://app.inventorum.com/api/orders/15427672/add_giftcard' \
--header 'Authorization: Token 023a2ad4d77e01934059cc51310665c129485ef1' \
--header 'X-Api-Version: 12' \
--header 'Content-Type: application/json' \
--data-raw '{
    "redeem_code": [
        "674886243216",
        "138628948516"
    ]
}'
Status 204 No Content

Paying Remaining Amount

POST /api/basket/{{order_id}}/payment/

Complete the checkout to redeem the Gift Cards. Remaining amount must be specified to complete the order, or 0 amount, if the total amount redeemed by the gift cards is sufficient.

curl --request POST --location 'https://app.inventorum.com/api/basket/15427672/payment/' \
--header 'Authorization: Token 023a2ad4d77e01934059cc51310665c129485ef1' \
--header 'X-Api-Version: 12' \
--header 'Content-Type: application/json' \
--data-raw '{
    "amount": "0",
    "method": 0,
    "rounded": "0"
}'
Status 200 OK
{
    "id": 15427672,
    "basket": {
        "note_internal": null,
        "note_external": null,
        "items": [
            {
                "id": 30542523,
                "name": "Pants",
                "discount": null,
                "original_quantity": "1.00",
                "price": "80.3500000000",
                "product": 17519104,
                "quantity": 1,
                "tax_rate": "19.000",
                "gross_price": "95.62",
                "type": "product",
                "external_id": null,
                "unit_gross_price": "95.62",
                "product_code": null,
                "giftcard_id": null,
                "giftcard_type": null,
                "info": null,
                "user": null,
                "employees": []
            },
            {
                "id": 30542524,
                "name": "Keyboard",
                "discount": null,
                "original_quantity": "1.00",
                "price": "9.3460000000",
                "product": 17519100,
                "quantity": 1,
                "tax_rate": "7.000",
                "gross_price": "10.00",
                "type": "product",
                "external_id": null,
                "unit_gross_price": "10.00",
                "product_code": null,
                "giftcard_id": null,
                "giftcard_type": null,
                "info": null,
                "user": null,
                "employees": []
            },
            {
                "id": 30542525,
                "name": "Shirt",
                "discount": null,
                "original_quantity": "1.00",
                "price": "25.7600000000",
                "product": 17519103,
                "quantity": 1,
                "tax_rate": "0.000",
                "gross_price": "25.76",
                "type": "product",
                "external_id": null,
                "unit_gross_price": "25.76",
                "product_code": null,
                "giftcard_id": null,
                "giftcard_type": null,
                "info": null,
                "user": null,
                "employees": []
            }
        ],
        "discount": null,
        "receipt": {
            "pdf": "https://app.inventorum.com/uploads/invoices/23965/Moj-Lipi-Sop-76.pdf",
            "image_width": 1,
            "image_height": 1,
            "image": "https://app.inventorum.com/uploads/invoices/23965/Moj-Lipi-Sop-76.png"
        },
        "invoice_number": "76",
        "used_giftcards": [
            {
                "tax_rate": "19.0000000000",
                "type": "single-purpose",
                "redeem_code": "674886243216",
                "amount_applied": "-95.62",
                "id": 46473
            },
            {
                "type": "multi-purpose",
                "redeem_code": "138628948516",
                "amount_applied": "-35.76",
                "id": 46474
            }
        ]
    },
    "state": 360,
    "customer": null,
    "amount_paid": "0E-10",
    "payments": [
        {
            "id": 14504922,
            "payment_method": "0",
            "payment_amount": "0E-10",
            "date": "2022-11-29T15:12:32+00:00",
            "transaction_id": null,
            "transaction_duration": null,
            "paypal_invoice_id": null,
            "paypal_tab_id": null,
            "external_payment_method": null,
            "giftcard_id": null,
            "giftcard_type": null,
            "giftcard_discount": null,
            "state": {
                "name": "Accepted",
                "id": 0
            }
        }
    ],
    "shipment": null,
    "channel": "ipad",
    "time_added": "2022-11-29T14:54:38+00:00",
    "completed_at": "2022-11-29T15:12:32+00:00",
    "description": null,
    "user": 31169,
    "total": "-0.00",
    "external_id": null,
    "delta_state": "updated",
    "user_id": 31169,
    "available_refund_types": [
        "0",
        "6",
        "1",
        "3",
        "2",
        "19",
        "20"
    ],
    "ksv_payloads": [],
    "printable": []
}

Validate Gift Card

GET /api/v2/giftcards/{redeem_code}/validate

Request

curl --request GET --location 'https://app.inventorum.com/api/v2/giftcards/{{redeem_code}}/validate' \
--header 'Authorization: Token e49edf23e8f7625b39ae7d64176aafca42d79037' \
--header 'X-Api-Version: 12'

Response

Status 200 OK
{
    "name": "SP GC-",
    "original_amount": "100.00",
    "remaining_value": "4.38",
    "was_used": true,
    "tax_rate": "19.0000000000",
    "type": "single-purpose",
    "valid_until": "2023-07-21T20:59:59Z"
}

Adjusting Inventory for Pre-coded Gift Cards

To adjust inventory for pre-coded Gift Cards please refer to product inventory adjustment endpoint here.

Gift Card Import

External gift cards that were created and sold by other systems can be imported and used as standard gift card in coreAPI.

Retrieve Template File

GET /api/v2/giftcards/import/template.xlsx?language=de
curl --location 'https://app.inventorum.com/api/v2/giftcards/import/template.xlsx?language=de' \
--header 'Authorization: Token 25a8cbea8aaa8fc49a3c0a5731a87e07ee809ca0' \
--header 'X-Api-Version: 12' 

Params

param type/format required valid values description
language string false en,de or es Language of the template headers

Create Gift Card Import

POST /api/v2/giftcards/import
curl --request POST --location 'https://app.inventorum.com/api/v2/giftcards/import' \
--header 'Authorization: Token 25a8cbea8aaa8fc49a3c0a5731a87e07ee809ca0' \
--header 'X-Api-Version: 12' \
--form 'source_file=@"/Users/Me/Downloads/template_en.xlsx"'

Response

Status 200 OK
{
  "job_id": 1420,
  "_links": {
    "status": {
      "href": "https://app.inventorum.com/api/v2/giftcards/import/1420"
    }
  }
}

Sending Form Params

param type/format required sample values description
source_file string true template_en.xlsx` Path to the import file

Import File Structure

column type/format required samle values description
redeem code string true 0DFC4265-3787-45F5-B0AB-4E3AFFC666B8 Minimum 8 characters including letters, digits or - and treated as case insensitive.
name string true Welcome Gift Card Gift card name
valid until date false 31.12.2027 Gift card expiration date in format DD.MM.YYYY. Set to 3 years, if not provided.
current amount decimal true 50 Redeemable amount. Must be greater than zero.
tax rate decimal true 19 (without % sign) Must match the accont tax rates. For example German account tax rates 19, 7, 0 are valid.

Retrieve Gift Card Import Status

GET /api/v2/giftcards/import/{{import_job_id}}
curl --location 'https://app.inventorum.com/api/v2/giftcards/import/1421' \
--header 'Authorization: Token cb8b7ca6558149fb19f1843d0f3a0321e797e460' \
--header 'X-Api-Version: 12'

{
  "id": 1421,
  "source_file": "https://app.inventorum.com/uploads/23965/giftcard_import/gc_template_en_23965_2024_09_25_11_24_11.xlsx",
  "status_code": 0,
  "status_details": {
    "num_imported": 1
  },
  "last_status_change": "2024-09-25T11:24:11.912226+02:00",
  "completed_at": "2024-09-25T11:24:11.912268+02:00",
  "time_added": "2024-09-25T11:24:11.087537+02:00"
}
Status 200 OK

List Gift Card Imports

GET /api/v2/giftcards/import

curl --location 'https://app.inventorum.com/api/v2/giftcards/import' \
--header 'Authorization: Token cb8b7ca6558149fb19f1843d0f3a0321e797e460' \
--header 'X-Api-Version: 12'
Status 200 OK
{
  "data": [
    {
      "id": 1421,
      "source_file": "https://app.inventorum.com/uploads/23965/giftcard_import/gc_template_en_23965_2024_09_25_11_24_11.xlsx",
      "status_code": 0,
      "status_details": {
        "num_imported": 1
      },
      "last_status_change": "2024-09-25T11:24:11.912226+02:00",
      "completed_at": "2024-09-25T11:24:11.912268+02:00",
      "time_added": "2024-09-25T11:24:11.087537+02:00"
    },
    {
      "id": 1420,
      "source_file": "https://app.inventorum.com/uploads/23965/giftcard_import/gc_template_en_23965_2024_09_25_11_17_49.xlsx",
      "status_code": 12,
      "status_details": {
        "key": "giftcard.import.import_error",
        "fields": {
          "C2": "Not a valid string."
        },
        "description": "Message: \nErrors:\nC2: Not a valid string."
      },
      "last_status_change": "2024-09-25T11:17:50.732774+02:00",
      "completed_at": null,
      "time_added": "2024-09-25T11:17:49.982047+02:00"
    },
    {
      "id": 1130,
      "source_file": "https://app.inventorum.com/uploads/23965/giftcard_import/template_DE_imp_23965_2024_04_22_19_27_40.xlsx",
      "status_code": 12,
      "status_details": {
        "key": "giftcard.import.import_error",
        "fields": {
          "redeem_code": "Duplicate redeem codes ['0DFC4265-3787-45F5-B0AB-4E3AFFC666B8']."
        },
        "description": "Message: \nErrors:\nredeem_code: Duplicate redeem codes ['0DFC4265-3787-45F5-B0AB-4E3AFFC666B8']."
      },
      "last_status_change": "2024-04-22T19:27:41.253862+02:00",
      "completed_at": null,
      "time_added": "2024-04-22T19:27:40.929994+02:00"
    },
    {
      "id": 1031,
      "source_file": "https://app.inventorum.com/uploads/23965/giftcard_import/giftcards-template_DE_23965_2024_04_16_18_10_48.xlsx",
      "status_code": 12,
      "status_details": {
        "key": "giftcard.import.import_error",
        "fields": {
          "A2": "Redeem code contains invalid characters",
          "C2": "time data 'TT.MM.JJJJ' does not match format '%d.%m.%Y'"
        },
        "description": "Message: \nErrors:\nA2: Redeem code contains invalid characters\nC2: time data 'TT.MM.JJJJ' does not match format '%d.%m.%Y'"
      },
      "last_status_change": "2024-04-16T18:10:49.054788+02:00",
      "completed_at": null,
      "time_added": "2024-04-16T18:10:48.709754+02:00"
    }
  ],
  "total": 4
}