Magento 2 Product Improvement Extensions

  1. Home
  2. Docs
  3. Magento 2 Product Improvement Extensions
  4. Magento 2 Gift Card
  5. API Support

API Support

We provide you lists of Restful API and GraphQL API that our Magento 2 Gift Card extension supports.

*Note: 

  • Restful API support is included in the main module package (from Gift Card v1.0.5).
  • GraphQL API support is included in the GraphQL package, acting as an add-on for anyone who needs to use GraphQL

1. Restful API

Please check the following Restful API supported by our modules:

With detailed tutorial:

    • GET /rest/V1/bssGiftCard/template/{:templateId}
      Get the template's information via template id.
    • GET /rest/V1/bssGiftCard/pattern/{:patternId}
      Get the pattern's information 
    • POST /rest/V1/bssGiftCard/checkCode
      Check gift card code
  •  

Detailed coming soon:  

    • DELETE /rest/V1/bssGiftCard/guest/remove/{:cartId}/{:giftCardQuoteId}
      Delele the gift card code that is applied in Quote
    • DELETE /rest/V1/bssGiftCard/mine/remove/{:giftCardQuoteId}
      delete the gift card code in the shopping cart of the logged-in customer
    • PUT /rest/V1/bssGiftCard/apply/{:cartId}/{:giftCardCode}
      Apply gift card code in the cart quote
    • PUT /rest/V1/bssGiftCard/mine/apply/{:giftCardCode}
      Apply the gift card code in the cart quote of logged-in customers

1.1 Get information about a template using template id

PATH: GET /rest/V1/bssGiftCard/template/{:templateId}

Header: Content-Type : application/json

Response detail:

template_id“template_id”: 1
Gift card template ID
name"name": "Test gift card"
Gift card template name
status"status": "1"
Enable/disable template
code_color"code_color": "ff00ff"
Gift card code color
message_color"message_color": "faf5fa"
Message color in Gift card
created_time"created_time": "2020-06-05 03:49:44"
Create time
updated_time"updated_time": "2020-06-05 03:49:44"
Update time
imagesimages: [
    {
        "id": "1",
        "position": "1",
        "url": "http:\/\/235-mage.bss.com\/pub\/media\/tmp\/bss\/giftcard\/image\
/700x560\/7\/2\/72394990_409978003041784_4233065152133464064_o.jpg", 
        "thumbnail":
"http:\/\/235-mage.bss.com\/pub\/media\/tmp\/bss\/giftcard\/image\
/148x111\/7\/2\/72394990_409978003041784_4233065152133464064_o.jpg",
        "alt": null
      }
]
List of images in the current template. Here is the image attributes, including: 
id: Image Id
position
url: Urls of main images
thumbnail: Url of thumbnail images
alt: alt tag s of images

Error:

400Bad request

Validation:

Template id needs to be pushed.

How to get the template's information?

GET /rest/V1//bssGiftCard/template/:templateId

Response:

{
    "template_id": "1",
    "name": "Test gift card",
    "status": "1",
    "code_color": "ff00ff",
    "message_color": "faf5fa",
    "created_time": "2020-06-05 03:49:44",
    "updated_time": "2020-06-05 03:49:44",
    "images": [
      {
        "id": "1",
 "position": "1",
        "url": "http:\/\/235-mage.bss.com\/pub\/media\/tmp\/bss\/giftcard\/image\/700x560\/7\/2\/72394990_409978003041784_4233065152133464064_o.jpg",
        "thumbnail": "http:\/\/235-mage.bss.com\/pub\/media\/tmp\/bss\/giftcard\/image\/148x111\/7\/2\/72394990_409978003041784_4233065152133464064_o.jpg",
        "alt": null
      },
      {
        "id": "2",
        "position": "2",
        "url": "http:\/\/235-mage.bss.com\/pub\/media\/tmp\/bss\/giftcard\/image\/700x560\/7\/2\/72374608_425146505059507_6066963719056441142_n.jpg",
        "thumbnail": "http:\/\/235-mage.bss.com\/pub\/media\/tmp\/bss\/giftcard\/image\/148x111\/7\/2\/72374608_425146505059507_6066963719056441142_n.jpg",
        "alt": null
      },
      {
        "id": "3",
        "position": "3",
        "url": "http:\/\/235-mage.bss.com\/pub\/media\/tmp\/bss\/giftcard\/image\/700x560\/7\/0\/70066944_119172596122773_1342264300332384256_o.jpg",
        "thumbnail": "http:\/\/235-mage.bss.com\/pub\/media\/tmp\/bss\/giftcard\/image\/148x111\/7\/0\/70066944_119172596122773_1342264300332384256_o.jpg",
        "alt": null
      },
      {
        "id": "4",
        "position": "4",
        "url": "http:\/\/235-mage.bss.com\/pub\/media\/tmp\/bss\/giftcard\/image\/700x560\/6\/9\/69529680_117463876293645_8838466387866288128_o.jpg",
        "thumbnail": "http:\/\/235-mage.bss.com\/pub\/media\/tmp\/bss\/giftcard\/image\/148x111\/6\/9\/69529680_117463876293645_8838466387866288128_o.jpg",
        "alt": null
      }
    ]
  }

1.2. Get pattern information. Submit pattern id information.

Path: GET /rest/V1/bssGiftCard/pattern/{:patternId}

Header: Content-Type : application/json

pattern_id“pattern_id”: “1”
Pattern Id
name"name": "Testt pattern"
Name of pattern
pattern"pattern": "Vaduuu-{D}-{L}"
Maximum number of D (digit) and L (letter) to be added is 6. E.g. BIRTHDAY-{D}-{L} results in BIRTHDAY-8-A
pattern_code_qty“pattern_code_qty”: “17”
The code quantity of the pattern
pattern_code_unused"pattern_code_unused": "17"
The parttern code that is/ unsused
pattern_code_qty_max"pattern_code_qty_max": "191"
The max pattern code quantity that the pattern can generate.
Ex: pattern is “lucthanca-{D}-{L}”. Có 1 D -> maxCodeQty = 10^1, has 1 L -> maxCodeQty = maxCodeQty * (26^1) = 260. Multiply by 0.8 = 208. This value will decrease by eliminating the number that is generated by admin.
Case in point: admin generates 100 code the value of code qty max is 208-100=108. If the admin deletes the generated code then the value will not be returned or increased back.
created_time"created_time": "2020-06-05 03:52:21"
Create time
updated_time"updated_time": "2020-06-16 07:13:43"
Update time

Error:

400Bad request

Validation:

Pattern id must be pushed forward.

Response:

GET /rest/V1/bssGiftCard/pattern/{:patternId}
Response:
[{
    "pattern_id": "2",
    "name": "vadu",
    "pattern": "vadu_{L}_{D}",
    "pattern_code_qty": "100",
    "pattern_code_unused": "100",
    "pattern_code_qty_max": "108",
    "created_time": "2021-03-10 03:38:58",
    "updated_time": "2021-03-10 03:39:32"
}]

1.3. Check giftcard code

PATH: POST/rest/V1/bssGiftCard/checkCode

Header: Content-Type : application/json
Body:

code"code": "lucthanca-C-1"
Code is generated by pattern

Response:

  • Status:
"status": true

The status of request. Aim to check whether or not the code exist and/or where or not you can check the code.

  • Data:
"data": [
           {
               "label": "Code",
               "value": "lucthanca-C-1"
           },
           {
               "label": "Origin Value",
               "value": "99,00 US$"
           },
           {
               "label": "Current Value",
               "value": "99,00 US$"
           },
           {
               "label": "Status",
               "value": "Inactive"
           },
           {
               "label": "Expire At",
               "value": "11 thg 5, 2021"
           }
       ]

The detail information of the code. Definition of fields:

+ label: The lable of code.

+ value: The value of code.

Error:

400Bad request
404Not Found

Validation:

Pattern id must be pushed forward.

Response:

{
"code": "lucthanca-C-1"
}
Response
[
   {
       "status": true,
       "data": [
           {
               "label": "Code",
               "value": "lucthanca-C-1"
           },
           {
               "label": "Origin Value",
               "value": "99,00 US$"
           },
           {
               "label": "Current Value",
               "value": "99,00 US$"
           },
           {
               "label": "Status",
               "value": "Inactive"
           },
           {
               "label": "Expire At",
               "value": "11 thg 5, 2021"
           }
       ]
   }
]

2. GraphQl API

Please check the following GraphQL API supported by our modules:

Query:

With detailed tutorial:

+ bssGiftCardStoreConfig
Get Store Config của module.
Get giftcard information with query products of Magento default.
Get giftcard information in query cart.

Detail Coming Soon:


+ bssGiftCardTemplates
Get ALL gift card information within template.
+ bssGetListTimezone
Get the timezone list.
+ bssCustomerGiftCards
Get ordered gift card information of the customer.
+ bssPreviewGiftCard
Preview giftcard.

Mutation:

+ addGiftCardProductsToCart

Add gift card to cart.

2.1 Get store configuration of the module

Path: bssGiftCardStoreConfig

+ Arguments

ArgumentDescription
store_view (Int|Null) RequiredStore view Id. If null is given then it will get the value according to default.

+ Example

query {
  bssGiftCardStoreConfig(store_view: 1) {
    active
    active_to_sender
    day_before_notify_expire
    expire_day
    max_time_limit
    notify_to_recipient
    number_character
    replace_character
    sender_identity
    to_recipient
    to_sender
  }
}
 Response {
 "data": {
   "bssGiftCardStoreConfig": {
     "active": 1,
     "active_to_sender": 1,
     "day_before_notify_expire": null,
     "expire_day": null,
     "max_time_limit": null,
     "notify_to_recipient": "bss_giftcard_notify_to_recipient",
     "number_character": null,
     "replace_character": null,
     "sender_identity": "sales",
     "to_recipient": "bss_giftcard_to_recipient",
     "to_sender": "bss_giftcard_to_sender"
   }
 }
}

+ Return Fields

- active: on/off Module

- active_to_sender: Send email to the sender

- day_before_notify_expire: Send Notification Mail of Expiration before number of days

- expire_day: Expiry Day. 0 for unlimited usage day

- max_time_limit: Allowed Maximum Time (s) to Enter Gift Code Incorrectly

- notify_to_recipient: Notification Email Template of Expiration to Recipient

- number_character: Number of Characters Shown in Gift Code

- replace_character: Replace Hidden Character by

- sender_identity: Email Sender

- to_recipient: Email Template to Recipient- to_sender: Email Template to Sender

2.2 Giftcard details in products query

+ Arguments

Please refer to Magento's product query document here.

+ Example

query {
  products(
    filter: {
      sku: {eq: "anh-hung-thiep"}
    }
  ) {
    items {
      name
      __typename,
      ... on BssGiftCardProduct {
        giftcard_options {
          amount {
            id
            price
            value
            website
          }
          dynamic_price {
            enable
            max_value
            min_value
            percentage_price_type
            percentage_price_value
          }
          expires_at
          message
          type
          template {
            images {
              url
            }
          }
        }
      }
    }
  }
}
Response {
 "data": {
   "products": {
     "items": [
       {
         "name": "Anh Hùng Thiếp",
         "__typename": "BssGiftCardProduct",
         "giftcard_options": {
           "amount": [
             {
               "id": 2,
               "price": 200,
               "value": 200,
               "website": 0
             }
           ],
           "dynamic_price": {
             "enable": 1,
             "max_value": "200",
             "min_value": "150",
             "percentage_price_type": 1,
             "percentage_price_value": "100"
           },
           "expires_at": "0",
           "message": 1,
           "type": 1,
           "template": [
             {
               "images": [
                 {
                   "url": "http:\/\/242.vadu\/media\/tmp\/bss\/giftcard\/image\/700x560\/8\/0\/80900905_158038935546402_6445742220388597760_n.jpg"
                 },
                 {
                   "url": "http:\/\/242.vadu\/media\/tmp\/bss\/giftcard\/image\/700x560\/8\/0\/80900691_2673092382918470_8015297684673921024_o.jpg"
                 }
               ]
             }
           ]
         }
       }
     ]
   }
 }
}

3. Object Describe.

  • ProductInterface
    • Implementations
      • BssGiftCardProduct
  • BssGiftCardProduct
    • Fields
      • giftcard_options: GiftCardOptions
  • GiftCardOptions
    • Fields
      • amount: [AmountByWebsite]
        An array of linked card amount by website
      • dynamic_price: DynamicPrice
      • expires_at: String
        A number of days which specify the valid time to use the gift card. Gift codes which are automatically created after customers purchase Gift Cards have valid time auto following settings of this Expires After (days) section.
      • message: Int
        Allow the customer to attach a message for the receiver of the giftcard.
      • pattern: GiftCardPattern
        Linked pattern to allow code(s) to apply with the gift card
      • template: [GiftCardTemplate]
        An array of linked Card Template
      • type: Int
        Card type id.
        1 is Virtual
        2 is Physical
        3 is Combined
  • AmountByWebsite
    • Fields
      • id: Int
        Amount value id
      • price: Float
        Card Price
      • value: Float
        Card value
      • website: Int
        Apply in website id
  • DynamicPrice
    • Fields
      • enable: Int
        Is dynamic price
      • max_value: String
        Max card value
      • min_value: String
        Min card value
      • percentage_price_type: Int
        Percentage Price Type.
        0: Same as value
        1: Percentage of value
      • percentage_price_value: String
        Percentage Price Value
  • GiftCardPattern
    • Fields
      • codes: [Code]
        An array of linked codes
      • id: Int
        Pattern Id
      • name: String
        Pattern name
      • pattern: String
        Pattern string
      • qty: Int
        Code qty
      • qty_max: Int
        Max qty code
      • unused: Int
        Unused code
  • GiftCardTemplate
    • Fields
      • code_color: String
        Gift Code Color
      • images: [TemplateImage]
        An array of linked images
      • message_color: String
        Gift Card Message Text Color
      • name: String
        Template Name
      • status: Int
        Template status
      • template_id: Int
        Template Id
  • Code
    • Fields
      • code: String
      • code_id: Int
      • expiry_day: String
      • image_id: Int
      • message: String
      • order_id: Int
      • origin_value: Float
      • product_id: Int
      • recipient_email: String
      • recipient_name: String
      • send_at: String
      • sender_email: String
      • sender_name: String
      • sent: Int
      • sent_expire_notify: Int
        Was sent Notification Email about Expire code
      • status: Int
      • store_id: Int
      • value: Float
      • website_id: Int
  • TemplateImage
    • Fields
      • alt: String
        Image label
      • id: Int
        Image Id
      • position: Int
        Image position
      • thumbnail: String
        Image thumbnail
      • url: String
        Image full width
Was this article helpful to you? Yes No

How can we help?