Skip to main content

Manage Gift Cards

The Checkout APIs enable you to work with gift cards on an order just as you would any other line item. This page outlines how to add a gift card to an order, delete it, and check its balance.

note

If your store is on Magento 1 or Adobe Commerce, you cannot use Bold Checkout to add or configure gift cards. Gift cards are supported, but you must manage them through the Magento 1 or Adobe Commerce admin or a third-party integration.

Prerequisites​

Before you get started, complete the following steps:

  1. Follow the steps outlined in the Bold Checkout Getting Started guide.
  2. Visit the Bold Checkout admin, and verify that Gift cards are available under the Payment options section. If Gift cards is not there, please reach out to Customer Success and request that they enable this feature on your store.

Configure gift cards in the Bold Checkout admin​

Before you can use the API to add gift cards to an order, you must configure gift cards in the Bold Checkout admin. Follow the instructions in the Help Center for information on enabling Bold Gift Cards on your store and creating a gift card product.

Add gift card to order​

After you add a gift card to your product catalog, you can add a gift card to any order via the Add Line Item endpoint.

When calling this endpoint, include the following values in the properties portion of the request body:

  • recipient_name — The name of the gift card recipient.
  • recipient_email — The email of the gift card recipient.
  • message — A message to the gift card recipient. This value is converted to a merge field ([message]), which you can find in the Gift card email settings in the Bold Checkout admin.
  • custom_amount — The amount of the gift card, in base currency units (cents, for example). If this value is included, it overrides the price of the line item.

The following snippet shows an example call that adds a gift card to an order:

curl --request POST 'https://api.boldcommerce.com/checkout/storefront/{shop_identifier}/{public_order_id}/items' \
     --header 'Authorization: Bearer {JWT}' \
     --header 'Bold-API-Version-Date: 2022-05-01' \
     --header 'Content-Type: application/json' \
     --data '{
         "platform_id": "93851",
         "sku": "gift_card_100",
         "quantity": 1,
         "line_item_key": "ABC123",
         "properties": {
             "recipient_name": "Jane Doe",
             "recipient_email": "[email protected]",
             "message": "Happy Birthday!",
             "custom_amount": "1000"
         }
     }'

Edit or delete gift card​

You can edit or delete a gift card just as you would any other line item. Use the Update Line Item Quantity or Delete Line Item endpoints to do so.

If you need to make changes to the gift card (other than quantity), you must delete the gift card line item and re-add it with the updated information.

Check gift card balance​

Once an order with a gift card line item is processed, the gift card is considered issued. At this point, you can check the gift card balance either via the Bold Checkout admin, or via the Get Gift Card endpoint in the Checkout Admin specification.

You can check the gift card balance using the gift card's public_payment_method_id, as shown in the following snippet:

curl --request GET 'https://api.boldcommerce.com/checkout/shop/{shop_identifier}/gift_card?public_payment_method_id=i5uATT2QVKlozoDA2msg89w3mWAdPTIeLtED44R1SJYUVuI7jO4NqHdM8vjoqq7A7P' \
     --header 'Authorization: Bearer {access_token}' \
     --header 'Bold-API-Version-Date: 2022-05-01'

You can also check the balance with a combination of card_token and card_pin, as shown in the following snippet:

curl --request GET 'https://api.boldcommerce.com/checkout/shop/{shop_identifier}/gift_card?card_token=AJPG-TPOE-FNAA-MDEH&card_pin=937' \
     --header 'Authorization: Bearer {access_token}' \
     --header 'Bold-API-Version-Date: 2022-05-01'