English

简体中文

English

简体中文

Appearance

About Gift Card ​

Access scope

Multiple access scopes needed — refer to each endpoint for access scope requirements.

Gift Card is a crucial component of Genstore's payment solutions, enabling customers to purchase and use prepaid amounts, providing flexible payment options for online stores. Genstore offers a series of RESTful interfaces for comprehensive gift card management, including creation, update, invalidation, and query operations, allowing merchants to efficiently manage and track gift card usage.

Core Features

  • Basic Operations: Create gift card, update gift card, invalidate gift card
  • Information Query: Get gift card details, list gift cards, count gift cards

Use Cases

  • Gift Card Sales: .Store managers can launch digital gift card programs, customize card designs and denominations, and manage promotional rules through the API, expanding payment options while creating new revenue streams.
  • Gift Card Lifecycle Operations: Customer service teams can efficiently process gift card issuance, handle balance updates, and manage card status changes, ensuring secure and accurate gift card transactions.
  • Gift Card Analytics: Business analysts can track gift card performance metrics, generate usage reports, and analyze purchase patterns through the API, optimizing gift card programs and improving customer engagement.

Endpoints

POST /api/202412/gift_cards: Create gift cards

POST /api/202412/gift_cards/{giftCardId}/disable: Disable gift card

PUT /api/202412/gift_cards/{giftCardId}: Update gift card

GET /api/202412/gift_cards/search: Searches for gift cards

GET /api/202412/gift_cards/count: Query the number of gift cards

GET /api/202412/gift_cards/{giftCardId}: Query gift card details

Gift Card Object ​

The gift card object.

Properties ​

giftCardobject
Gift card information.
- Hide child properties
customerIdobject
Client id for customers assigned to present gift card.
idnumber
Gift card id.
codestring
Gift card encoding.
lastCharactersstring
The last four characters from code.
balancenumber
Gift card balance.
initialValuenumber
Initial amount of gift card.
orderIdobject
Associated order id.
lineItemIdobject
Associated order items.
currencystring
Gift card par currency.
noteobject
Note information for present gift card.
disableTimeobject
Gift card disable time.
expireTimestring
The expiration date of the current gift card , lol is never expired.
createTimestring
Gift card creation time.
updateTimestring
Gift card update time.
userIdobject
Administrator account id on the admin interface for users to create gift cards.
bash
{
  "giftCard": {
    "note": "this is gift card",
    "code": "fehjignfjeingx",
    "orderId": "300139485001998",
    "lineItemId": "300139485001998",
    "updateTime": "2024-12-16T17:04:38.004",
    "userId": "20000012584",
    "lastCharacters": "ingx",
    "expireTime": "2027-12-04",
    "balance": "100.00",
    "createTime": "2024-12-16T17:04:38.004",
    "customerId": "20000012619",
    "currency": "USD",
    "id": "201462124",
    "initialValue": "100.00",
    "disableTime": "2024-12-16T17:17:03.017"
  }
}

POST Create gift cards ​

Create gift cards.

Access scope

Requires ANY of the following access scopes: write_gift_card

Endpoint

POST /api/202412/gift_cards 

Request Params

giftCardobject
- Hide child properties
customerIdnumber
Client id for customers assigned to present gift card.
codestring
Gift card encoding.
initialValuenumber
Initial amount of gift card.
notestring
The note information of the current gift card , the number of characters limited to 500.
expireTimenumber
Expiration date on current gift card.

Response Data

giftCardobject
Gift card information.
- Hide child properties
customerIdobject
Client id for customers assigned to present gift card.
idnumber
Gift card id.
codestring
Gift card encoding.
lastCharactersstring
The last four characters from code.
balancenumber
Gift card balance.
initialValuenumber
Initial amount of gift card.
orderIdobject
Associated order id.
lineItemIdobject
Associated order items.
currencystring
Gift card par currency.
noteobject
Note information for present gift card.
disableTimeobject
Gift card disable time.
expireTimestring
The expiration date of the current gift card , lol is never expired.
createTimestring
Gift card creation time.
updateTimestring
Gift card update time.
userIdobject
Administrator account id on the admin interface for users to create gift cards.
bash
curl -X POST \ 
https://{shop}.genmystore.com/api/202412/gift_cards" \ 
-H "X-Genstore-Access-Token: {access_token}" \ 
-H "Content-Type: application/json" \ 
-d '{
	"giftCard":{
		"note":"this is gift card",
		"code":"fehjignfjeingx",
		"expireTime":"2027-12-04T21:20:50+08:00",
		"customerId":"20000012619",
		"initialValue":"100"
	}
}'
json
HTTP/1.1 200 OK
{
  "giftCard": {
    "note": "this is gift card",
    "code": "fehjignfjeingx",
    "orderId": "300139485001998",
    "lineItemId": "300139485001998",
    "updateTime": "2024-12-16T17:04:38.004",
    "userId": "20000012584",
    "lastCharacters": "ingx",
    "expireTime": "2027-12-04",
    "balance": "100.00",
    "createTime": "2024-12-16T17:04:38.004",
    "customerId": "20000012619",
    "currency": "USD",
    "id": "201462124",
    "initialValue": "100.00",
    "disableTime": "2024-12-16T17:17:03.017"
  }
}

POST Disable gift card ​

Disable gift card.

Access scope

Requires ANY of the following access scopes: write_gift_card

Endpoint

POST /api/202412/gift_cards/{giftCardId}/disable 

Request Params

giftCardIdnumber
Gift card ID

Response Data

giftCardobject
Gift card information.
- Hide child properties
customerIdobject
Client id for customers assigned to present gift card.
idnumber
Gift card id.
codestring
Gift card encoding.
lastCharactersstring
The last four characters from code.
balancenumber
Gift card balance.
initialValuenumber
Initial amount of gift card.
orderIdobject
Associated order id.
lineItemIdobject
Associated order items.
currencystring
Gift card par currency.
noteobject
Note information for present gift card.
disableTimeobject
Gift card disable time.
expireTimestring
The expiration date of the current gift card , lol is never expired.
createTimestring
Gift card creation time.
updateTimestring
Gift card update time.
userIdobject
Administrator account id on the admin interface for users to create gift cards.
bash
curl -X POST \ 
https://{shop}.genmystore.com/api/202412/gift_cards/{giftCardId}/disable" \ 
-H "X-Genstore-Access-Token: {access_token}" \ 
-H "Content-Type: application/json" \ 
-d '{
	"giftCardId":""
}'
json
HTTP/1.1 200 OK
{
  "giftCard": {
    "note": "this is gift card",
    "code": "fehjignfjeingx",
    "orderId": "300139485001998",
    "lineItemId": "300139485001998",
    "updateTime": "2024-12-16T17:04:38.004",
    "userId": "20000012584",
    "lastCharacters": "ingx",
    "expireTime": "2027-12-04",
    "balance": "100.00",
    "createTime": "2024-12-16T17:04:38.004",
    "customerId": "20000012619",
    "currency": "USD",
    "id": "201462124",
    "initialValue": "100.00",
    "disableTime": "2024-12-16T17:17:03.017"
  }
}

PUT Update gift card ​

Update gift card.

Access scope

Requires ANY of the following access scopes: write_gift_card

Endpoint

PUT /api/202412/gift_cards/{giftCardId} 

Request Params

giftCardobject
- Hide child properties
balancenumber
Gift card balance.
notestring
The note information of the current gift card , the number of characters limited to 500.
expireTimenumber
Expiration date on current gift card.

Response Data

giftCardobject
Gift card information.
- Hide child properties
customerIdobject
Client id for customers assigned to present gift card.
idnumber
Gift card id.
codestring
Gift card encoding.
lastCharactersstring
The last four characters from code.
balancenumber
Gift card balance.
initialValuenumber
Initial amount of gift card.
orderIdobject
Associated order id.
lineItemIdobject
Associated order items.
currencystring
Gift card par currency.
noteobject
Note information for present gift card.
disableTimeobject
Gift card disable time.
expireTimestring
The expiration date of the current gift card , lol is never expired.
createTimestring
Gift card creation time.
updateTimestring
Gift card update time.
userIdobject
Administrator account id on the admin interface for users to create gift cards.
bash
curl -X PUT \ 
https://{shop}.genmystore.com/api/202412/gift_cards/{giftCardId}" \ 
-H "X-Genstore-Access-Token: {access_token}" \ 
-H "Content-Type: application/json" \ 
-d '{
	"giftCard":{
		"note":"this is gift card",
		"expireTime":"2024-12-16T16:33:12.033",
		"balance":"100"
	}
}'
json
HTTP/1.1 200 OK
{
  "giftCard": {
    "note": "this is gift card",
    "code": "fehjignfjeingx",
    "orderId": "300139485001998",
    "lineItemId": "300139485001998",
    "updateTime": "2024-12-16T17:04:38.004",
    "userId": "20000012584",
    "lastCharacters": "ingx",
    "expireTime": "2027-12-04",
    "balance": "100.00",
    "createTime": "2024-12-16T17:04:38.004",
    "customerId": "20000012619",
    "currency": "USD",
    "id": "201462124",
    "initialValue": "100.00",
    "disableTime": "2024-12-16T17:17:03.017"
  }
}

GET Searches for gift cards ​

Gift card search capability.

Access scope

Requires ANY of the following access scopes: read_gift_card write_gift_card

Endpoint

GET /api/202412/gift_cards/search 

Request Params

limitnumber
Page count limit, default limit is 50.
sinceIdstring
Starting resource ID, mainly used for querying pagination starting from sinceId on the homepage.
statusstring
Gift card status. Enum: enabled, disabled, expired.
pageTokenstring
The cursor representing a specific page will, by default, return the homepage data.
lastCharactersstring
The last four characters of the code.

Response Data

giftCardsarray
Gift card information.
- Hide child properties
customerIdnumber
Client id for customers assigned to present gift card.
idnumber
Gift card id.
codestring
Gift card encoding.
lastCharactersstring
The last four characters from code
balancenumber
Gift card balance.
initialValuenumber
Initial face value of gift card.
orderIdstring
Associated order id.
lineItemIdobject
Associated order items.
currencyobject
Gift card par currency.
noteobject
Note information for present gift card.
disableTimeobject
Gift card disable time.
expireTimeobject
Expiration date for present gift card, “null” means never expired.
createTimestring
Gift card creation time.
updateTimestring
Gift card update time.
userIdnumber
Administrator account id on the admin interface for users to create gift cards.
bash
curl -X GET \ 
https://{shop}.genmystore.com/api/202412/gift_cards/search" \ 
-H "X-Genstore-Access-Token: {access_token}" \
json
HTTP/1.1 200 OK
{
  "giftCards": [
    {
      "note": "this is gift card",
      "code": "fehjignfjeingx",
      "orderId": "300139485001998",
      "lineItemId": "300139485001998",
      "updateTime": "2024-12-16T17:04:38.004",
      "userId": "20000012584",
      "lastCharacters": "ingx",
      "expireTime": "2027-12-04",
      "balance": "100.00",
      "createTime": "2024-12-16T17:04:38.004",
      "customerId": "20000012619",
      "currency": "USD",
      "id": "201462125",
      "initialValue": "100.00",
      "disableTime": "2024-12-16T17:17:03.017"
    }
  ]
}

GET Query the number of gift cards ​

Query the total number of gift cards.

Access scope

Requires ANY of the following access scopes: read_gift_card write_gift_card

Endpoint

GET /api/202412/gift_cards/count 

Request Params

{}

Response Data

countnumber
Total count of gift cards.
bash
curl -X GET \ 
https://{shop}.genmystore.com/api/202412/gift_cards/count" \ 
-H "X-Genstore-Access-Token: {access_token}" \
json
HTTP/1.1 200 OK
{
  "count": "44"
}

GET Query gift card details ​

Query the details of a single gift card.

Access scope

Requires ANY of the following access scopes: read_gift_card write_gift_card

Endpoint

GET /api/202412/gift_cards/{giftCardId} 

Request Params

{}

Response Data

giftCardobject
Gift card information.
- Hide child properties
customerIdobject
Client id for customers assigned to present gift card.
idnumber
Gift card id.
codestring
Gift card encoding.
lastCharactersstring
The last four characters from code.
balancenumber
Gift card balance.
initialValuenumber
Initial amount of gift card.
orderIdobject
Associated order id.
lineItemIdobject
Associated order items.
currencystring
Gift card par currency.
noteobject
Note information for present gift card.
disableTimeobject
Gift card disable time.
expireTimestring
The expiration date of the current gift card , lol is never expired.
createTimestring
Gift card creation time.
updateTimestring
Gift card update time.
userIdobject
Administrator account id on the admin interface for users to create gift cards.
bash
curl -X GET \ 
https://{shop}.genmystore.com/api/202412/gift_cards/{giftCardId}" \ 
-H "X-Genstore-Access-Token: {access_token}" \
json
HTTP/1.1 200 OK
{
  "giftCard": {
    "note": "this is gift card",
    "code": "fehjignfjeingx",
    "orderId": "300139485001998",
    "lineItemId": "300139485001998",
    "updateTime": "2024-12-16T17:04:38.004",
    "userId": "20000012584",
    "lastCharacters": "ingx",
    "expireTime": "2027-12-04",
    "balance": "100.00",
    "createTime": "2024-12-16T17:04:38.004",
    "customerId": "20000012619",
    "currency": "USD",
    "id": "201462124",
    "initialValue": "100.00",
    "disableTime": "2024-12-16T17:17:03.017"
  }
}