Gift Cards v3

How to use

This section covers the endpoints for this API and examples of how to use them.

Gift Card Terminology

For the Gift Card v1 and v3 APIs, here are definitions for some common terms:

• client: This is the business entity (and its administrator user) that manages the gift cards.
• operator: This is a sub-entity under a client. It represents a named individual (such as front-desk) who performs transactions.
• user: This generally refers to a user record, which has an assigned role, such as :front_desk or :client.
• customer: This is the consumer who receives and redeems gift cards.

GET client information #

Use this endpoint to get client information.

[GET] /api/v3/clients/get_client

Response in JSON

{
  "id": 3,
  "name": "dev",
  "address": "Techsembly development",
  "contact": "123456789",
  "created_at": "2025-11-27T09:14:47.868Z",
  "updated_at": "2026-06-19T11:00:45.787Z",
  "cancel_transaction_reason_id": 100,
  "message_body": "payment url {{link}}",
  "from_number": "+15618232994",
  "corporate_monetary_campaign_id": 243,
  "test_mode": false,
  "enable_request_id": false
}

▲ Back to top

PUT an update to client settings #

Use this endpoint to update client settings.

[PUT] /api/v3/clients/set_client_setting

The client settings that you are updating with this put request include details such as the cancel_transaction_reason_id, which tells the system which transaction reason to use when cancelling a gift card for that client.

Put Body Example

The following is an example of the body for this put request:

{
  "client": {
    "cancel_transaction_reason_id": "100",
    "from_number": "+15618232994",
    "message_body": "payment url {{link}}"
  },
  "user": {
    "enable_request_id": false
  }
}

Response in JSON

{
  "message": "Client Setting updated successfully."
}

▲ Back to top

PUT to send an SMS message #

Use this endpoint to send SMS messages.

[PUT] /api/v3/clients/send_sms

Put Body Parameters

The following table describes the parameters to include in your put request:

Put Body Example

The following is an example of the body for this put request:

{
  "to_number": "+923005322600",
  "payment_link": "payment_link"
}

Response in JSON

{
  "success": true
}

▲ Back to top

GET client experiences #

Use this endpoint to get the experiences of a client.

[GET] /api/v3/clients/experiences

Response in JSON

[
  {
    "id": 215,
    "sku": "new_experience",
    "title": "new experience ",
    "campaign_id": 61,
    "amount": "12.0",
    "currency": "USD",
    "monetary_campaign_id": null,
    "store_id": 11,
    "created_at": "2025-08-14T17:17:51.428Z",
    "updated_at": "2025-08-14T17:19:24.106Z",
    "soft_delete": false
  }
]

▲ Back to top

GET client departments #

Use this endpoint to get the departments of a client.

[GET] /api/v3/clients/departments

Response in JSON

[
  {
    "id": 52,
    "department_name": "department name for store 11",
    "department_description": "department description for store 11",
    "client_id": null,
    "created_at": "2025-12-27T07:49:27.785Z",
    "updated_at": "2025-12-27T07:49:27.785Z",
    "soft_delete": false,
    "store_id": 11
  }
]

▲ Back to top

POST to create monetary gift cards #

Use this endpoint to create a monetary type gift card.

[POST] /api/v3/gift_cards/create_monetary_card

Post Body Parameters

The following table describes the parameters to include in your post request:

Post Body Example

The following is an example of the body for this post request:

{
  "card_type": "monetary",
  "value": "1000",
  "currency": "USD",
  "delivery_mode": "digital",
  "campaign_code": "dev-1",
  "from_address": "wyfosykyp@mailinator.com",
  "invoice_id": "sk-123",
  "notes": "werwe",
  "product_name": "tesitng",
  "receipient_phone_number": "",
  "recipient_email": "wyfosykyp@mailinator.com",
  "recipient_first_name": "Darrel",
  "recipient_last_name": "Wiggins",
  "send_gift_card_via": "email",
  "skus": [],
  "message": "",
  "store_id": "11",
  "creator_attributes": {
    "creator_email": "dev@tsclient.com",
    "creator_role": "1234"
  },
  "request_id": "1234"
}
			

Response in JSON

{
"id": 28071,
"number": "935896188801023413",
"pin": "24429",
"currency": "USD",
"card_type": "monetary",
"expiry_date": "2025-10-14T00:00:00.000Z",
"value": "1000.0",
"skus": [],
"status": "active",
"user_id": 24,
"campaign_id": 61,
"created_at": "2024-08-18T06:38:49.603Z",
"updated_at": "2024-08-18T06:38:49.603Z",
"client_id": 3,
"product_name": "testing",
"delivery_mode": "digital",
"delivery_status": "delivered",
"is_redeemed": false,
"is_expired": false,
"recipient_first_name": "Darrel",
"recipient_last_name": "Wiggins",
"recipient_email": "wyfosykyp@mailinator.com",
"order_number": "",
"send_email": false,
"order_pay_load": "",
"notes": "werwe",
"invoice_id": "sk-123",
"from_address": "wyfosykyp@mailinator.com",
"store_name": null,
"customer_email": null,
"barcode_key": "UT764xIqPatTsAl0",
"qrcode_key": "ZemSYyRv6OAfQ9H1",
"spree_ts_giftcard_id": null,
"slug": "d4b46bb5-3666-4e54-954b-cae5bad470f0",
"receipient_phone_number": "",
"send_gift_card_via": "email",
"bonus": false,
"serial_number": "01023413",
"operator_id": null,
"customer_id": null,
"recipient_emails": "",
"store_id": null,
"generated_at": null,
"import_by": "ts_giftcards",
"transition_activation_date": "2024-08-18T06:38:50.960Z",
"message": "",
"order_placed_date": null,
"line_item_id": null,
"start_date": null,
"test_mode": false,
"request_id": "1234",
"campaign_body": "dev testing message body",
"image_url": "http://[UrlOfImage]/Img.jpg",
"campaign_response": {
"id": 61,
"name": "dev-1",
"start_date": "2023-01-27T00:00:00.000Z",
"end_date": "2026-12-27T00:00:00.000Z",
"client_id": 3,
"code": "dev-1",
"max_expiry_days": null,
"created_at": "2023-01-27T09:20:56.836Z",
"updated_at": "2024-08-13T11:32:17.940Z",
"date_specific_expiry": true,
"email_subject": "dev testing email template merhan",
"email_html": "dev testing email template merhan",
"specific_date": "2025-10-14T00:00:00.000Z",
"body": "dev testing message body",
"sms_html": "dev testing sms template",
"allow_password": false,
"ses_from_email": "zeeshan@techsembly.com",
"transaction_email_subject": "dev testing transaction email bisma",
"transaction_email_html": " {{#if trasaction.show_local_amount}}\n
{{trasaction.local_currency}} {{trasaction.local_amount}}\n {{/if}}",
"soft_delete": false,
"cc_transaction_email": "ahsan.chughtai@techsembly.com",
"remain_active": false,
"is_campaign_remained_active": false,
"is_gift_card_remained_active": false,
"transaction_email_receivers": "",
"test_mode": false
},
"initial_store_id": 11
}

▲ Back to top

PUT to check an experience gift card balance #

Use this endpoint to check the balance of an experience gift card.

[PUT] /api/v3/gift_cards/check_balance

Put Body Parameters

The following table describes the parameters to include in your put request:

Put Body Example

The following is an example of the body for this put request:

{
  "number": "791400114701023414",
  "pin": "69337"
}

Response in JSON

{
  "product_name": "Gift Card",
  "card_type": "experiences",
  "skus": "sad",
  "card_status": "Valid",
  "card_number": "791400114701023414",
  "balance": "Card is redeemable.",
  "expiry_date": "2025-10-14T00:00:00.000Z",
  "status": "active",
  "card_currency": "USD"
}

▲ Back to top

POST to bulk activate gift cards #

Use this endpoint to perform a bulk activation of gift cards.

[POST] /api/v3/gift_cards/bulk_activate

Post Body Parameters

The following table describes the parameters to include in your post request:

Post Body Example

The following is an example of the body for this post request:

{
  "bulk_activation_params": [
    {
      "gift_card": {
        "campaign_id": "61",
        "card_type": "monetary",
        "creator_attributes": {
          "creator_email": "",
          "creator_role": ""
        },
        "currency": "USD",
        "delivery_status": "pickUp",
        "gift_card_number": "456038848301023363",
        "invoice_id": 8,
        "notes": "hello",
        "order_number": "order#1",
        "product_name": "CARD",
        "recipient_first_name": "FN",
        "recipient_last_name": "LN",
        "shipping_address_attributes": {
          "address1": "address1",
          "address2": "address2",
          "city": "",
          "country": "",
          "firstName": "",
          "lastName": "",
          "state": "",
          "state_name": "",
          "zipcode": ""
        },
        "skus": [],
        "status": "active",
        "store_id": "11",
        "value": 55.5
      },
      "store_id": "11"
    }
  ]
}

Response in JSON

[
  {
    "card_number": "456038848301023363",
    "amount": "55.50",
    "balance": "55.50",
    "currency": "USD",
    "meta": null,
    "id": 30319
  }
]

▲ Back to top

PUT an update to a gift card's status #

Use this endpoint to update a gift card's status.

[PUT] /api/v3/gift_cards/update_status

Put Body Parameters

The following table describes the parameters to include in your put request:

Put Body Example

The following is an example of the body for this put request:

{
  "number": "456038848301023363",
  "pin": "52169",
  "status": "blocked",
  "store_id": 11,
  "transitions_attributes": [
    {
      "transition_state_name": "status",
      "notes": "blocked from frontdesk",
      "pervious_state": "active",
      "current_state": "blocked",
      "creator_attributes": {
        "creator_email": "client@google.com",
        "creator_role": "client"
      }
    }
  ]
}

Response in JSON

{
  "status": "lost",
  "value": "123.0",
  "id": 28072,
  "number": "791400114701023414",
  "pin": "69337",
  "currency": "AED",
  "card_type": "experiences",
  "expiry_date": "2025-10-14T00:00:00.000Z",
  "skus": [
    "sad"
  ],
  "user_id": 24,
  "campaign_id": 61,
  "created_at": "2024-08-18T15:25:19.074Z",
  "updated_at": "2024-08-18T15:44:07.695Z",
  "client_id": 3,
  "product_name": "Gift Card",
  "delivery_mode": "digital",
  "delivery_status": "delivered",
  "is_redeemed": false,
  "is_expired": false,
  "recipient_first_name": "Monetary",
  "recipient_last_name": "(Ifrah)",
  "recipient_email": "user@email.com",
  "order_number": "",
  "send_email": false,
  "order_pay_load": "",
  "notes": "ad",
  "invoice_id": "dsa",
  "from_address": "user@email.com",
  "store_name": null,
  "customer_email": null,
  "barcode_key": "3W9WxznsbsiXpkzo",
  "qrcode_key": "KOjnl79OQ8dy1jKW",
  "spree_ts_giftcard_id": null,
  "slug": "b807ce33-cfe1-4c55-95b5-ff675b5b63d5",
  "receipient_phone_number": "",
  "send_gift_card_via": "email",
  "bonus": false,
  "serial_number": "01023414",
  "operator_id": null,
  "customer_id": 752,
  "recipient_emails": "",
  "store_id": null,
  "generated_at": null,
  "import_by": "ts_giftcards",
  "transition_activation_date": "2024-08-18T15:25:20.266Z",
  "message": "dsa",
  "order_placed_date": null,
  "line_item_id": null,
  "start_date": null,
  "test_mode": false,
  "request_id": ""
}

▲ Back to top

GET an export file of gift cards for a campaign #

Use this endpoint to get a CSV export of a campaign's gift cards and send the CSV to specified users.

[GET] /api/v3/gift_cards/send_csv_for_gift_cards

Query Parameters

The following table describes the elements that you can include when you query this endpoint:

Response

The response you receive is a binary stream of the CSV file that looks like the following:

Product Name,Gift Card Delivery Type,Gift Card Type,Gift Card Created Date,
Gift Card Last Updated,Gift Card Valid Date,Gift Card Status,Recipient First Name,Recipient Last Name,
Recipient Email Address,Recipient Phone Number,Gift Card Number,Serial Number,Gift Card Associated Order Ref,
Gift Card Original Balance,Gift Card Balance,Campaign Code,Checkout Storefront,Ts Campaign Stores,Email,Role,Message
knkn,digital,monetary,
15-10-2025,
08: 04: 21 AM - 15 Oct 25,
11-07-2028,active,Asifa,dew,test@gmail.com,
"",
1686763562010432529,
010432529,
"",
1000.0,
1000.0,test-2024,
,
"TS-S1, TS-S1, abc, vcccvccc, abc, cnv, ffd",user@email.com,admin,fsdds

▲ Back to top

GET gift card transactions #

Use this endpoint to get the transactions of a specific gift card by gift card ID.

[GET] /api/v3/gift_cards/{gift_card_id}/transactions

Path Parameters

The following table describes the elements that you must include for this operation:

Response in JSON

{
  "transactions": [
    {
      "gift_card_number": "420646903701023412",
      "recipient_email": "",
      "order_number": "897703402801023370",
      "serial_number": "01023412",
      "store_code": "ali",
      "store_name": [
        "Ahsan",
        "Winifred Hickman",
        "qwer",
        "devtransaction store",
        "testing",
        "testing",
        "dev Front Desk",
        "Muhammad Mehran Javid",
        "Monetary (Ifrah)",
        "Monetary (Ifrah)",
        "Monetary (Ifrah)",
        "Monetary (Ifrah)",
        "wyfosy243234234kyp test",
        "wyfosy243234234kyp test",
        "wyfosy243234234kyp test",
        "dev-store-1"
      ],
      "currency": "AED",
      "amount": "10.0",
      "transaction_type": "Active",
      "store_currency": "AED",
      "trans_amount": "10.0",
      "service_fee": "",
      "exchange_rate": "",
      "card_balance": "10.0",
      "gift_card_status": "active",
      "operator_id": null,
      "operator_name": null,
      "department": null,
      "delivery_mode": "physical",
      "gift_card_type": "monetary",
      "action_date": "2025-08-13",
      "action_time": "08:10 am",
      "notes": "897703402801023370",
      "gift_card_store_name": "Ahsan",
      "campaign_code": "dev-1",
      "campaign_stores": "Ahsan,Winifred Hickman,qwer,devtransaction
					store,testing,testing,dev Front Desk,Muhammad Mehran Javid,Monetary
					(Ifrah),Monetary (Ifrah),Monetary (Ifrah),Monetary
					(Ifrah),wyfosy243234234kyp test,wyfosy243234234kyp
					test,wyfosy243234234kyp test,dev-store-1","creator_email": "navisi9055@secbuf.com",
      "creator_role": "admin",
      "message": ""
    }
  ],
  "count": 1
}

▲ Back to top

PUT an update to a gift card's details #

Use this endpoint to update the details of a gift card. You can update status, expiry, and delivery status.

[PUT] /api/v3/gift_cards/{gift_card_id}

Path Parameters

The following table describes the elements that you must include for this operation:

Put Body Parameters

The following table describes the parameters to include in your put request:

Put Body Example

The following is an example of the body for this put request:

{
  "gift_card": {
    "status": "blocked",
    "expiry_date": "2027-12-31T23:59:59.000Z",
    "start_date": "2026-01-01",
    "end_date": "2027-12-31T23:59:59.000Z",
    "delivery_status": "delivered",
    "transitions_attributes": [
      {
        "transition_state_name": "status",
        "notes": "dsa",
        "pervious_state": "active",
        "current_state": "blocked",
        "creator_attributes": {
          "creator_email": "dev@client.com",
          "creator_role": "client"
        }
      }
    ]
  }
}

Response in JSON

{
  "status": "blocked",
  "value": "1000.0",
  "id": 28071,
  "number": "935896188801023413",
  "currency": "USD",
  "card_type": "monetary",
  "expiry_date": null,
  "skus": [],
  "user_id": 24,
  "campaign_id": 61,
  "created_at": "2025-08-18T06:38:49.603Z",
  "updated_at": "2025-08-18T12:41:48.628Z",
  "client_id": 3,
  "product_name": "tesitng",
  "delivery_mode": "digital",
  "delivery_status": "delivered",
  "is_redeemed": false,
  "is_expired": false,
  "recipient_first_name": "Darrel",
  "recipient_last_name": "Wiggins",
  "recipient_email": "wyfosykyp@mailinator.com",
  "order_number": "",
  "send_email": false,
  "order_pay_load": "",
  "notes": "werwe",
  "invoice_id": "sk-123",
  "from_address": "wyfosykyp@mailinator.com",
  "store_name": null,
  "customer_email": null,
  "barcode_key": "UT764xIqPatTsAl0",
  "qrcode_key": "ZemSYyRv6OAfQ9H1",
  "spree_ts_giftcard_id": null,
  "slug": "d4b46bb5-3666-4e54-954b-cae5bad470f0",
  "receipient_phone_number": "",
  "send_gift_card_via": "email",
  "bonus": false,
  "serial_number": "01023413",
  "operator_id": null,
  "customer_id": null,
  "recipient_emails": "",
  "store_id": null,
  "generated_at": null,
  "import_by": "ts_giftcards",
  "transition_activation_date": "2025-08-18T06:38:50.960Z",
  "message": "",
  "order_placed_date": null,
  "line_item_id": null,
  "start_date": null,
  "test_mode": false,
  "request_id": "1234"
}

▲ Back to top

POST to refund a gift card transaction #

Use this endpoint to refund a gift card transaction.

[POST] /api/v3/gift_cards/refund

Post Body Parameters

The following table describes the parameters to include in your post request:

Post Body Example

The following is an example of the body for this post request:

{
  "transaction_id": 30325,
  "notes": "refunding",
  "amount": "2",
  "creator_email": "navisi9055@secbuf.com",
  "creator_role": "client"
}

Response in JSON

{
  "id": 30330,
  "amount": "2",
  "currency": "USD",
  "transaction_type": "refund",
  "ip": "::1",
  "note": "",
  "refund_id": 30325,
  "gift_card_id": 28071,
  "user_id": 24,
  "sku": null,
  "created_at": "2025-08-19T07:43:53.799Z",
  "updated_at": "2025-08-19T07:43:53.799Z",
  "refunded": false,
  "external_invoice_id": null,
  "notes": "refunding",
  "card_balance": null,
  "store_id": 11,
  "meta": null,
  "transaction_reason_id": 12,
  "select_payment_methods": "cash",
  "operator_id": null,
  "gift_card_status": "active",
  "recipient_emails": "",
  "service_fee_id": null,
  "gift_card_balance_status": null
}

▲ Back to top

POST to activate gift cards #

Use this endpoint to activate gift cards.

[POST] /api/v3/gift_cards/activation

Post Body Parameters

The following table describes the parameters to include in your post request:

Post Body Example

The following is an example of the body for this post request:

{
  "store_name": "hong kong",
  "number": "663455564601023410",
  "store_id": 11,
  "amount": "20.00",
  "currency": "USD",
  "ts_payment_method": "cash",
  "sku": "nil",
  "gift_card": {
    "campaign_id": 61,
    "card_type": "monetary",
    "currency": "USD",
    "delivery_status": "pickUp",
    "gift_card_number": "663455564601023410",
    "pin": "15786",
    "notes": "dev activating",
    "product_name": "Gift Card",
    "select_payment_methods": "cash",
    "skus": [],
    "value": "20.00",
    "creator_attributes": {
      "creator_email": "mehran@techsembly.com",
      "creator_role": "front_desk"
    },
    "operator_id": 32,
    "order_number": "R548180153",
    "status": "active",
    "invoice_id": "1231234",
    "store_name": "hong kong"
  },
  "credential": {
    "ts_email": "mehrufd2.0@gmail.com",
    "ts_password": "bWVocnVmZDIuMEBnbWFpbC5jb20="
  },
  "creator_attributes": {
    "creator_email": "mehran@techsembly.com",
    "creator_role": "front_desk"
  }
}

Response in JSON

{
  "card_number": "614938924401023409",
  "amount": "20.00",
  "balance": "20.00",
  "currency": "USD",
  "meta":nil,
  "id": 30333
}

▲ Back to top

POST to find a gift card #

Use this endpoint to find a specific gift card.

[POST] /api/v3/gift_cards/find_gift_card

With this endpoint, you specify the card number, and you receive a response that includes the gift card's full details, such as balance, transactions, and expiration information.

Post Body Parameters

The following table describes the parameters to include in your post request:

Post Body Example

The following is an example of the body for this post request:

{
  "number": "420646903701023412",
  "check_status": true
}

Response in JSON

{
  "gift_card": {
    "id": 28070,
    "number": "420646903701023412",
    "pin": "17123",
    "currency": "AED",
    "card_type": "monetary",
    "expiry_date": "2025-10-14T00:00:00.000Z",
    "value": "10.0",
    "skus": [],
    "status": "active",
    "user_id": 24,
    "campaign_id": 61,
    "created_at": "2025-08-13T07:10:33.979Z",
    "updated_at": "2025-08-13T07:10:34.047Z",
    "client_id": 3,
    "product_name": "Gift Card",
    "delivery_mode": "physical",
    "delivery_status": "pickUp",
    "is_redeemed": false,
    "is_expired": false,
    "recipient_first_name": "mehran",
    "recipient_last_name": "javid",
    "recipient_email": "",
    "order_number": "897703402801023370",
    "send_email": false,
    "order_pay_load": "",
    "notes": "897703402801023370",
    "invoice_id": "897703402801023400",
    "from_address": "",
    "store_name": null,
    "customer_email": null,
    "barcode_key": "tFy383IBzMdLsgA6",
    "qrcode_key": "YGnTWj5Gh6h4XkEf",
    "spree_ts_giftcard_id": null,
    "slug": "ee96012c-5f0d-4951-a37b-499d2a3ee407",
    "receipient_phone_number": null,
    "send_gift_card_via": "email",
    "bonus": false,
    "serial_number": "01023412",
    "operator_id": null,
    "customer_id": null,
    "recipient_emails": "",
    "store_id": 227,
    "generated_at": null,
    "import_by": "ts_giftcards",
    "transition_activation_date": "2025-08-13T07:10:33.979Z",
    "message": "",
    "order_placed_date": null,
    "line_item_id": null,
    "start_date": null,
    "test_mode": false,
    "request_id": null
  },
  "balance": "10.0",
  "message": "Please update your app",
  "is_gift_card_expired": false,
  "expiry_date": "2025-10-14T00:00:00.000Z"
}

▲ Back to top

POST to find active gift cards #

Use this endpoint to find active gift cards.

[POST] /api/v3/gift_cards/find_activation_gift_card

With this endpoint, you specify the card number, and the system checks whether the card is in Initiated status. The response will include just the card object.

Post Body Parameters

The following table describes the parameters to include in your post request:

Post Body Example

The following is an example of the body for this post request:

{
  "number": "488809720401023411"
}

Response in JSON

{
  "gift_card": {
    "id": 28069,
    "number": "488809720401023411",
    "pin": "54423",
    "currency": "",
    "card_type": null,
    "expiry_date": "2025-10-14T00:00:00.000Z",
    "value": "0.0",
    "skus": [],
    "status": "initiated",
    "user_id": 24,
    "campaign_id": 61,
    "created_at": "2025-08-12T15:00:20.147Z",
    "updated_at": "2025-08-12T15:00:20.147Z",
    "client_id": 3,
    "product_name": null,
    "delivery_mode": "physical",
    "delivery_status": "printing",
    "is_redeemed": false,
    "is_expired": false,
    "recipient_first_name": "",
    "recipient_last_name": "",
    "recipient_email": "",
    "order_number": "",
    "send_email": false,
    "order_pay_load": "",
    "notes": null,
    "invoice_id": null,
    "from_address": "",
    "store_name": null,
    "customer_email": null,
    "barcode_key": "ma3ANSp4hK6b1mE0",
    "qrcode_key": "oqbtPvkWSH3fQoGy",
    "spree_ts_giftcard_id": null,
    "slug": "d7db2893-367c-4e82-9ec3-cf4317005d58",
    "receipient_phone_number": null,
    "send_gift_card_via": "email",
    "bonus": false,
    "serial_number": "01023411",
    "operator_id": null,
    "customer_id": null,
    "recipient_emails": "",
    "store_id": null,
    "generated_at": null,
    "import_by": "ts_giftcards",
    "transition_activation_date": "2025-08-12T15:00:20.448Z",
    "message": "",
    "order_placed_date": null,
    "line_item_id": null,
    "start_date": null,
    "test_mode": false,
    "request_id": null
  }
}

▲ Back to top

PUT to send a gift card transaction email #

Use this endpoint to send a gift card transaction email.

[PUT] /api/v3/gift_cards/send_email

Put Body Parameters

The following table describes the parameters to include in your put request:

Put Body Example

The following is an example of the body for this put request:

{
  "transaction_id": 30334,
  "recipient_emails": "mehran@techsembly.com"
}

Response in JSON

{
  "success": true
}

▲ Back to top

GET gift card transitions #

Use this endpoint to get the gift card transitions.

[GET] /api/v3/gift_cards/gift_card_transition

Transitions are audit log entries that record status changes on a gift card.

When you call this endpoint, the response is a JSON-encoded string (not a native JSON array). Each element represents a status change audit log entry with optional nested creator. Consumers must JSON parse this value.

Query Parameters

The following table describes the elements that you can include when you query this endpoint:

Response in JSON

{
"gift_card_transition": "[\n {\n \"id\": 1,\n \"notes\": \"Card blocked due to suspected fraud\",\n
\"transition_state_name\": \"blocked\",\n \"pervious_state\": \"active\",\n \"current_state\": \"blocked\",\n
\"transition_id\": 28071,\n \"transition_type\": \"GiftCard\",\n \"created_at\": \"2024-08-18T10:30:00.000Z\",\n
\"updated_at\": \"2024-08-18T10:30:00.000Z\",\n \"creator\": {\n \"id\": 1,\n \"creator_email\":
\"admin@example.com\",\n \"creator_role\": \"client\"\n }\n },\n {\n \"id\": 2,\n \"notes\": \"Card reactivated after
verification\",\n \"transition_state_name\": \"active\"\n }\n]"
}

▲ Back to top

POST to perform transactions on gift cards #

Use this endpoint to perform transactions on gift cards that have the experiences card_type. You must also add a transaction reason.

[POST] /api/v3/gift_cards/transaction

Post Body Parameters

The following table describes the parameters to include in your post request:

Note: An experience gift card never allows you to perform a transaction reason with transaction type of credit, because an experience gift card can't be credited.

Post Body Example

The following is an example of the body for this post request:

{
  "type": "experiences",
  "number": "791400114701023414",
  "pin": "69337",
  "amount": "",
  "store_id": 11,
  "sku": "swim",
  "transaction_reason": "Redeem",
  "external_invoice_id": "",
  "payment_method": "",
  "notes": "redeeming experience",
  "currency": "AED",
  "creator_attributes": {
    "creator_email": "mehran@techsembly.com",
    "creator_role": "front_desk"
  },
  "operator": {
    "operator_name": "op 1 (25967)",
    "operator_pin": "25967",
    "id": 32
  }
}

Response in JSON

{
  "card_number": "791400114701023414",
  "amount": "Card is redeemed",
  "balance": 123,
  "currency": "AED",
  "id": 30343
}

Note: The id in the response represents the transaction_id for each transaction, such as top-up and debit.

▲ Back to top

DELETE an operator #

Use this endpoint to delete an operator by operator ID.

[DELETE] /api/v3/operators/{id}

Path Parameters

The following table describes the elements that you must include for this operation:

Response in JSON

{
  "message": "Operator deleted"
}

▲ Back to top

GET all transaction reasons #

Use this endpoint to get all the transactions reasons for the client of the signed in user.

[GET] /api/v3/transaction_reasons

To use this endpoint, you need to get the authorization token of the client API from a request header of a client API call. Then you add that token to your request header for this endpoint call. Optionally, you can also add a transaction reason name and a transaction reason type.

Query Parameters

The following table describes the elements that you can include when you query this endpoint:

How to Format This GET Request

This endpoint allows you to add optional q filter parameters to your request. The q filter is logically an object, but technically a string. Therefore, you must follow these steps:

1. Construct your q filter as a JSON object.

The following is an example of a JSON object for this request. (This example shows q as the outer object to illustrate the full structure of the filter. Steps 2 and 3 explain why you can't use this exact format in your HTTP request.)

{
  "q": {
    "transaction_reason_cont": "test",
    "transaction_type_eq": "2"
  }
}

2. Serialize and URL-encode your q JSON object.

You will typically do this programmatically (for example, using curl). Conceptually, this involves two steps:

• Serialize the q JSON object into a JSON string.
• URL-encode that JSON string so that it can be safely sent as a query parameter.

The following generic example illustrates what serialization looks like:

{"object1":{"object2":{"array1":[{"string1":"value1"}]}}}

And here is that same generic example in URL-encoded form:

%7B%22object1%22%3A%7B%22object2%22%3A%7B%22array1%22%3A%5B%7B%22string1%22%3A%22value1%22%7D%5D%7D%7D%7D

3. Send your GET request that includes the q parameter as a pre-encoded query string, or as raw JSON that your HTTP client (such as curl) will URL-encode for you.

Here is an example of a full GET request that uses curl to URL-encode the q parameter:

curl -X GET \
  "https://<ts_server_url>/api/v3/transaction_reasons" \
  -u email@example.com:password \
  --data-urlencode 'page=1' \
  --data-urlencode 'per_page=25' \
  --data-urlencode 'q={
    "transaction_reason_cont": "test",
    "transaction_type_eq": "2"
  }'

Response in JSON

{
  "transaction_reasons": [
    {
      "id": 124,
      "transaction_reason": "Cancel",
      "transaction_type": "debit",
      "client_id": 1,
      "created_at": "2025-03-24T07:34:57.738Z",
      "updated_at": "2025-03-24T07:34:57.738Z",
      "soft_delete": false,
      "store_id": null
    },
    {
      "id": 111,
      "transaction_reason": "tesitng234245234",
      "transaction_type": "credit",
      "client_id": 1,
      "created_at": "2025-03-13T20:04:51.212Z",
      "updated_at": "2025-03-13T20:04:51.212Z",
      "soft_delete": false,
      "store_id": null
    },
    {
      "id": 107,
      "transaction_reason": "testing321123",
      "transaction_type": "debit",
      "client_id": 1,
      "created_at": "2025-03-03T12:07:39.506Z",
      "updated_at": "2025-03-03T12:07:39.506Z",
      "soft_delete": false,
      "store_id": null
    },
    {
      "id": 104,
      "transaction_reason": "testing98088567432145678",
      "transaction_type": "debit",
      "client_id": 1,
      "created_at": "2025-02-23T22:24:32.056Z",
      "updated_at": "2025-02-23T22:24:32.056Z",
      "soft_delete": false,
      "store_id": null
    },
    {
      "id": 103,
      "transaction_reason": "testingLabel",
      "transaction_type": "debit",
      "client_id": 1,
      "created_at": "2025-02-23T19:45:09.341Z",
      "updated_at": "2025-02-23T19:45:09.341Z",
      "soft_delete": false,
      "store_id": 98
    }
  ],
  "total_count": 68
}

▲ Back to top

POST to create transaction reasons #

Use this endpoint to create a new transaction reason.

[POST] /api/v3/transaction_reasons

Post Body Parameters

The following table describes the parameters to include in your post request:

Post Body Example

The following is an example of the body for this post request:

{
  "transaction_reason": {
    "transaction_reason": "Cash Back",
    "transaction_type": "credit"
  }
}

Response in JSON

{
  "id": 232,
  "transaction_reason": "Cash Back",
  "transaction_type": "credit",
  "client_id": 1,
  "created_at": "2025-04-27T08:30:27.504Z",
  "updated_at": "2025-04-27T08:30:27.504Z",
  "soft_delete": false,
  "store_id": {}
}

▲ Back to top

GET a transaction reason by transaction reason ID #

Use this endpoint to get a specific transaction reason by transaction reason ID.

[GET] /api/v3/transaction_reasons/{transaction_reason_id}

Path Parameters

The following table describes the elements that you must include for this operation:

Response in JSON

{
  "id": 231,
  "transaction_reason": "AddOn",
  "transaction_type": "credit",
  "client_id": 1,
  "created_at": "2025-04-27T08:28:13.091Z",
  "updated_at": "2025-04-27T08:28:13.091Z",
  "soft_delete": false,
  "store_id": {}
}

▲ Back to top

PUT an update to a transaction reason #

Use this endpoint to update a transaction reason by transaction reason ID.

[PUT] /api/v3/transaction_reasons/{transaction_reason_id}

Path Parameters

The following table describes the elements that you must include for this operation:

Put Body Parameters

The following table describes the parameters to include in your put request:

Put Body Example

The following is an example of the body for this put request:

{
  "transaction_reason": {
    "transaction_reason": "Add",
    "transaction_type": "credit"
  }
}

Response in JSON

{
  "transaction_reason": {
    "transaction_reason": "Add",
    "transaction_type": "credit"
  }
}

▲ Back to top

DELETE a transaction reason #

Use this endpoint to delete a transaction reason by transaction reason ID.

[DELETE] /api/v3/transaction_reasons/{transaction_reason_id}

Path Parameters

The following table describes the elements that you must include for this operation:

Response in JSON

{
  "message": "Transaction Reason deleted"
}

▲ Back to top

POST to find an operator #

Use this endpoint to find an operator.

[POST] /api/v3/users/find_operator

Post Body Parameters

The following table describes the parameters to include in your post request:

Post Body Example

The following is an example of the body for this post request:

{
  "operator_name": "op 1 (25967)",
  "pin": "25967",
  "email": "mehrufd2.0@gmail.com"
}

Response in JSON

[
  {
    "id": 32,
    "operator_name": "op 1 (25967)",
    "pin": "25967",
    "user_id": 60,
    "created_at": "2025-02-27T09:18:56.905Z",
    "updated_at": "2025-07-13T07:24:37.943Z",
    "soft_delete": false
  }
]

▲ Back to top

POST to find a user profile #

Use this endpoint to retrieve a user's profile (by the user's email address).

[POST] /api/v3/users/profile

Post Body Parameters

The following table describes the parameters to include in your post request:

Post Body Example

The following is an example of the body for this post request:

{
  "email": "mehrufd2.0@gmail.com"
}

Response in JSON

{
  "id": 60,
  "email": "mehrufd2.0@gmail.com",
  "name": "mehruFD",
  "store_id": null,
  "client_id": 3,
  "created_at": "2025-02-27T08:28:44.272Z",
  "updated_at": "2025-08-14T19:13:40.652Z",
  "payment_methods": {
    "pos": true,
    "cash": true,
    "credit_card": true
  },
  "department_id": 52,
  "is_operator_enabled": true,
  "is_top_up_show": true,
  "menu_access": {
    "top_up": true,
    "activation": true,
    "other_transaction": false
  },
  "first_name": null,
  "last_name": null,
  "phone_number": null,
  "cell_number": null,
  "terms_and_conditions": false,
  "enable_promotions": false,
  "title": null,
  "soft_delete": false,
  "store_filter_id": 11,
  "provider": "email",
  "uid": "60440f4d516a2d74a538e79289c335",
  "tokens": null,
  "enable_request_id": false,
  "operators": [
    {
      "id": 32,
      "operator_name": "op 1 (25967)",
      "pin": "25967",
      "user_id": 60,
      "created_at": "2025-02-27T09:18:56.905Z",
      "updated_at": "2025-07-13T07:24:37.943Z",
      "soft_delete": false
    }
  ],
  "store": {
    "id": 11,
    "name": "dev-store-1",
    "code": "dev-1",
    "url": "",
    "client_id": 3,
    "created_at": "2025-01-27T09:19:35.641Z",
    "updated_at": "2025-06-21T07:22:08.578Z",
    "fx_fees": 4,
    "fx_label": "mehru",
    "fx_enable": true,
    "monetary_campaign_id": 61,
    "store_front_link": "https://testing-admin.techsembly.com",
    "soft_delete": false,
    "activation_payment_link": "http://localhost:3000/card_activation?sku=005672",
    "top_up_payment_link": "http://localhost:3000/card_topup?sku=005672",
    "max_value": 100,
    "min_value": 10,
    "gift_card_values": "5,10,15,20, 19.11111",
    "experiences": [
      {
        "id": 1,
        "sku": "die",
        "title": "sky dive",
        "campaign_id": 61,
        "amount": "1600.0",
        "currency": "AED",
        "monetary_campaign_id": null,
        "store_id": 11,
        "created_at": "2025-02-27T08:52:55.355Z",
        "updated_at": "2025-02-27T08:52:55.355Z",
        "soft_delete": false
      }
    ]
  }
}

▲ Back to top

POST to create store experiences #

Use this endpoint to create experiences for a store.

[POST] /api/v3/stores/{storeId}/experiences

Path Parameters

The following table describes the elements that you must include for this operation:

Post Body Parameters

The following table describes the parameters to include in your post request:

Post Body Example

The following is an example of the body for this post request:

{
  "experience": {
    "sku": "new_experience",
    "title": "new experience",
    "currency": "USD",
    "amount": 12,
    "campaign_id": "61"
  }
}

Response in JSON

{
  "id": 214,
  "sku": "new_experience",
  "title": "new experience",
  "campaign_id": 61,
  "amount": "12.0",
  "currency": "USD",
  "monetary_campaign_id": null,
  "store_id": 11,
  "created_at": "2025-08-14T09:55:55.716Z",
  "updated_at": "2025-08-14T09:55:55.716Z",
  "soft_delete": false
}

▲ Back to top

GET store experiences by store ID #

Use this endpoint to list experiences for a store.

[GET] /api/v3/stores/{storeId}/experiences

Path Parameters

The following table describes the elements that you must include for this operation:

Query Parameters

The following table describes the elements that you can include when you query this endpoint:

Response in JSON

[
  {
    "id": 214,
    "sku": "new_experience",
    "title": "new experience",
    "campaign_id": 61,
    "amount": "12.0",
    "currency": "USD",
    "monetary_campaign_id": null,
    "store_id": 11,
    "created_at": "2025-08-14T09:55:55.716Z",
    "updated_at": "2025-08-14T09:55:55.716Z",
    "soft_delete": false
  }
]

▲ Back to top

GET a store experience #

Use this endpoint to get an experience for a store by store ID and experience ID.

[GET] /api/v3/stores/{storeId}/experiences/{experienceID}

Path Parameters

The following table describes the elements that you must include for this operation:

Response in JSON

{
  "id": 214,
  "sku": "new_experience",
  "title": "new experience",
  "campaign_id": 61,
  "amount": "12.0",
  "currency": "USD",
  "monetary_campaign_id": null,
  "store_id": 11,
  "created_at": "2025-08-14T09:55:55.716Z",
  "updated_at": "2025-08-14T09:55:55.716Z",
  "soft_delete": false
}

▲ Back to top

PUT an update to a store experience #

Use this endpoint to update an experience for a store by store ID and experience ID.

[PUT] /api/v3/stores/{storeId}/experiences/{experienceID}

Path Parameters

The following table describes the elements that you must include for this operation:

Put Body Parameters

The following table describes the parameters to include in your put request:

Put Body Example

The following is an example of the body for this put request:

{
  "experience": {
    "sku": "new_experience",
    "title": "new experience ",
    "currency": "USD",
    "amount": "12.00",
    "campaign_id": "61"
  }
}

Response in JSON

{
  "store_id": 11,
  "sku": "new_experience",
  "title": "new experience ",
  "campaign_id": 61,
  "amount": "12.0",
  "currency": "USD",
  "id": 215,
  "monetary_campaign_id": null,
  "created_at": "2025-08-14T17:17:51.428Z",
  "updated_at": "2025-08-14T17:19:24.106Z",
  "soft_delete": false
}

▲ Back to top

DELETE a store experience #

Use this endpoint to delete an experience for a store by store ID and experience ID.

[DELETE] /api/v3/stores/{storeId}/experiences/{experienceID}

Path Parameters

The following table describes the elements that you must include for this operation:

Response in JSON

{
  "message": "Experience deleted"
}

▲ Back to top

POST to create store departments #

Use this endpoint to create departments for a store.

[POST] /api/v3/stores/{storeId}/departments

Path Parameters

The following table describes the elements that you must include for this operation:

Post Body Parameters

The following table describes the parameters to include in your post request:

Post Body Example

The following is an example of the body for this post request:

{
  "department": {
    "department_name": "department",
    "department_description": "temp department"
  }
}

Response in JSON

{
  "id": 199,
  "department_name": "deparment",
  "department_description": "temp deparment",
  "client_id": null,
  "created_at": "2024-08-13T12:02:41.473Z",
  "updated_at": "2024-08-13T12:02:41.473Z",
  "soft_delete": false,
  "store_id": 11
}

▲ Back to top

GET departments by store ID #

Use this endpoint to list departments for a store.

[GET] /api/v3/stores/{storeId}/departments

Path Parameters

The following table describes the elements that you must include for this operation:

Query Parameters

The following table describes the elements that you can include when you query this endpoint:

Response in JSON

[
  {
    "id": 52,
    "department_name": "department name for store 11",
    "department_description": "department description for store 11",
    "client_id": null,
    "created_at": "2023-02-27T07:49:27.785Z",
    "updated_at": "2023-02-27T07:49:27.785Z",
    "soft_delete": false,
    "store_id": 11
  }
]

▲ Back to top

GET a department #

Use this endpoint to get one department for a store, by store ID and department ID.

[GET] /api/v3/stores/{storeId}/departments/{departmentId}

Path Parameters

The following table describes the elements that you must include for this operation:

Response in JSON

{
  "id": 52,
  "department_name": "department name for store 11",
  "department_description": "department description for store 11",
  "client_id": null,
  "created_at": "2023-02-27T07:49:27.785Z",
  "updated_at": "2023-02-27T07:49:27.785Z",
  "soft_delete": false,
  "store_id": 11
}

▲ Back to top

DELETE store departments #

Use this endpoint to delete a department for a store. You must specify a store ID and a department ID for the store department you want to delete.

[DELETE] /api/v3/stores/{storeId}/departments/{departmentId}

Path Parameters

The following table describes the elements that you must include for this operation:

Response in JSON

{
  "message": "Department deleted"
}

▲ Back to top

PUT an update to a store department #

Use this endpoint to update a department for a store. You must specify a store ID and a department ID for the store department you want to update.

[PUT] /api/v3/stores/{storeId}/departments/{departmentId}

Path Parameters

The following table describes the elements that you must include for this operation:

Put Body Parameters

The following table describes the parameters to include in your put request:

Put Body Example

The following is an example of the body for this put request:

{
  "department": {
    "department_name": "department",
    "department_description": "temp department"
  }
}

Response in JSON

{
  "store_id": 11,
  "department_name": "new department name",
  "department_description": "new department description",
  "id": 200,
  "client_id": null,
  "created_at": "2024-08-13T13:59:50.386Z",
  "updated_at": "2024-08-13T14:00:00.962Z",
  "soft_delete": false
}

▲ Back to top