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¶
- Create a gift card template, also known as gift card product.
- Create an order to sell gift card(s).
- Add payment for the gift card(s) and complete the checkout.
- Gift card(s) issued and redeemable
Redeeming Gift Card¶
- Create an order for selling products and/or services.
- Optionally, if not added in step 1, add redeemable gift card(s) to the order.
- Optionally, remove gift card(s) from the order.
- Add remaining (or zero) payment amount to the order and complete the checkout.
Importing Gift Cards¶
- Download Gift card import xlsx template.
- Add required external gift cards data to the template.
- 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 --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.
Query Params
| 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 ''
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'
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.
List Issued Gift Cards¶
GET /api/giftcards/
Lists all issued Gift Cards.
Query Params
| param | type/format | required | sample value | description |
|---|---|---|---|---|
| limit | integer | false | 100 | default value: 25 |
| page | integer | false | 10 | page number |
Request
curl --request GET --location 'https://app.inventorum.com/api/giftcards/' \
--header 'Authorization: Token c0432454af85314b8c6331c97f71152cbade854c' \
--header 'X-Api-Version: 12'
Response
Status 200 OK
{
"count": 149,
"next": "https://app.inventorum.com/api/giftcards/?page=2",
"previous": null,
"results": [
{
"order_id": 15441320,
"invoice_number": "83",
"product_id": 17526023,
"user_id": 31169,
"tax_type": 67483,
"current_value": "100.00",
"created_at": "2023-01-24T21:36:51.261186+01:00",
"returned_at": "1970-01-01T01:00:00+01:00",
"redemption": [],
"valid_until": "2023-07-21T22:59:59+02:00",
"redeem_code": "842353433769",
"name": "SP GC-",
"amount": "100.00",
"is_valid": true
},
{
"order_id": 15441320,
"invoice_number": "83",
"product_id": 17526024,
"user_id": 31169,
"tax_type": 67485,
"current_value": "50.00",
"created_at": "2023-01-24T21:36:51.306430+01:00",
"returned_at": "1970-01-01T01:00:00+01:00",
"redemption": [],
"valid_until": "2023-05-04T22:36:51.296654+02:00",
"redeem_code": "205426401335",
"name": "GC_MP-",
"amount": "50.00",
"is_valid": true
},
...
]
}
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
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
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'
Query 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
}