Create a gift card

Requires write_gift_card access scope.
For more info, refer to:
access permission.
POST https://{handle}.myshopline.com/admin/openapi/v20270301/gift_cards.json
handle : The store's unique identifier, which is the prefix of the store's domain name. For example, if a store's domain name is open001.myshopline.com , the store handle is open001 .
Create a gift card for the store.
Request Headers
  • Content-Type string required
    The field must be set to the fixed value application/json; charset=utf-8.
  • Authorization string required
    The access token for the API resource. Refer to App authorization to obtain the access token, and then pass the obtained token in the Bearer format.
    Example:
    Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhcHBJZCI6MCwiYXBwS2V5IjoiNzU2ZjI1NWE2NjdlZTcwNTk1MzM0ZjVjYzk4NzU5MzBmN2E3NGZjMSIsImV4cCI6MTg3OTQ4MjA3NiwiaXNzIjoieXNvdWwiLCJzZWxsZXJJZCI6IjIwMDAyMzQ4ODAiLCJzdG9yZUlkIjoiMTY3MjM2OTcyOTYwNiIsInRpbWVzdGFtcCI6MTc4NDc4NzY3NjY2MSwidmVyc2lvbiI6IlYyIn0.3ZzbGAH4cLU1QR2VPEvMOQInUDvus-C4amkINSQIPuNVlXsFKj0sAt1c0KnUy9MWUOFV9cHlkf7J90r2y1FzpA
Request Body
  • code string
    The gift card code. It must be 8-20 characters long and contain only lowercase letters (a-z) and numbers (0-9).
    Example: dbe95e7f02606fc4
  • customer_id string
    The ID of the customer who owns the gift card.
    Maximum length：64
    Example: 4200113946
  • expires_on string
    The expiration date and time of the gift card to be created. Format: ISO 8601. Passing null or omitting the field or an empty string "" sets the gift card to never expire.
    Example: 2023-08-16T23:59:59+08:00
  • initial_value string required
    The initial amount of the gift card. The value is rounded to two decimal places. The currency unit is the base unit of the store's current settlement currency.
    Example: 299.99
  • note string
    The note content of the gift card.
    Maximum length：500
    Example: This is a note
  • recipient_attributesobject
    The recipient information for the gift card.
  • email string
    Recipient email address for the gift card.
    Maximum length：50
    Example: demo@demo.com
  • message string
    Message for the gift card.
    Maximum length：255
    Example: This is a message
  • nickname string
    Recipient nickname for the gift card.
    Maximum length：255
    Example: nickname
  • send_around string
    The scheduled delivery date and time of the gift card. The maximum selectable date cannot exceed 90 days beyond the current time. Format: ISO 8601.
    Example: 2025-06-28T23:59:59+08:00
Status Codes
For the complete list of codes and messages, see Http status code.
Response Headers
  • traceId
    A globally unique identifier for the request. It is used to track the request flow throughout the system, allowing for easy location and debugging when issues arise.
Response Body
  • gift_cardobject
    Gift card information.
  • created_at string
    The date and time when the gift card was created. Format: ISO 8601.
    Example: 2023-08-16T23:59:59+08:00
  • currency string
    A three-letter currency code that follows the ISO 4217 standard.
    Example: USD
  • initial_value string
    The initial amount of the gift card. The value is rounded to two decimal places. The currency unit is the base unit of the store's current settlement currency.
    Example: 299.99
  • balance string
    The current balance of the gift card. The value is rounded to two decimal places. The currency unit is the base unit of the store's current settlement currency.
    Example: 299.99
  • code string
    The gift card code.
    Example: dbe95e7f02606fc4
  • line_item_id string
    The associated order line item ID.
    Example: 18060183094426803997483534
  • note string
    The note content of the gift card.
    Example: This is a note
  • order_id string
    The associated order ID.
    Example: 24060486231247568944830202
  • recipient_attributesobject
    The recipient information for the gift card.
  • email string
    Recipient email address for the gift card.
    Example: demo@demo.com
  • message string
    Message for the gift card.
    Example: This is a message
  • nickname string
    Recipient nickname for the gift card.
    Example: nickname
  • send_around string
    The scheduled delivery date and time of the gift card. Format: ISO 8601.
    Example: 2025-06-28T23:59:59+08:00
  • user_id string
    The ID of the SHOPLINE Admin user that performed the gift card creation.
    Example: 4214250478
  • api_client_id string
    The unique identifier for the calling API client.
    Example: 36d2bc4e97af056677b61c529d9e3a3f7396040d
  • customer_id string
    The ID of the customer who owns the gift card.
    Example: 4200113946
  • disabled_at string
    The date and time when the gift card was disabled. Format: ISO 8601.
    Example: 2023-08-16T23:59:59+08:00
  • expires_on string
    The current expiration date and time of the gift card. Format: ISO 8601. Returns null if the card never expires.
    Example: 2023-08-16T23:59:59+08:00
  • id string
    The unique identifier for the gift card.
    Example: 30157043359245339231360282
  • last_characters string
    The last four characters of the gift card code.
    Example: d246
  • updated_at string
    The date and time when the gift card was last updated. Format: ISO 8601.
    Example: 2023-08-16T23:59:59+08:00
API Explorer
https://openapiceshidianpu.myshopline.com/admin/openapi/v20270301

ParamOptions

— header required

Body

required
{
  "recipient_attributes": {
    "email": "demo@demo.com",
    "message": "This is a message",
    "nickname": "nickname",
    "send_around": "2025-06-28T23:59:59+08:00"
  },
  "code": "dbe95e7f02606fc4",
  "customer_id": "4200113946",
  "expires_on": "2023-08-16T23:59:59+08:00",
  "initial_value": "299.99",
  "note": "This is a note"
}

Language

curl --request POST \
     --url https://openapiceshidianpu.myshopline.com/admin/openapi/v20270301/gift_cards.json \
     --header 'Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhcHBJZCI6MCwiYXBwS2V5IjoiNzU2ZjI1NWE2NjdlZTcwNTk1MzM0ZjVjYzk4NzU5MzBmN2E3NGZjMSIsImV4cCI6MTg3OTQ4MjA3NiwiaXNzIjoieXNvdWwiLCJzZWxsZXJJZCI6IjIwMDAyMzQ4ODAiLCJzdG9yZUlkIjoiMTY3MjM2OTcyOTYwNiIsInRpbWVzdGFtcCI6MTc4NDc4NzY3NjY2MSwidmVyc2lvbiI6IlYyIn0.3ZzbGAH4cLU1QR2VPEvMOQInUDvus-C4amkINSQIPuNVlXsFKj0sAt1c0KnUy9MWUOFV9cHlkf7J90r2y1FzpA' \
     --header 'Content-Type: application/json; charset=utf-8' \
     --header 'accept: application/json'
Examples
Create a gift card
Request
{
  "recipient_attributes": {
    "email": "giftcarttest@shopline.com",
    "message": "This is a message",
    "nickname": "giftcarttest",
    "send_around": "2026-06-28T23:59:59+08:00"
  },
  "code": "testgiftcart260611",
  "customer_id": "2605118091",
  "expires_on": "2026-08-16T23:59:59+08:00",
  "initial_value": "199.99",
  "note": "This is a note"
}
Response
{
  "gift_card": {
    "disabled_at": null,
    "user_id": null,
    "balance": "199.99",
    "code": "testgiftcart260611",
    "created_at": "2026-06-14T03:32:28-11:00",
    "customer_id": "2605118091",
    "initial_value": "200.00",
    "order_id": null,
    "api_client_id": "1133d7c99428f83aa3c8d155e0efbb6f71e198c9",
    "currency": "USD",
    "expires_on": "2026-08-16T23:59:59-11:00",
    "id": "30175685282753764489900045",
    "recipient_attributes": {
      "email": "giftcarttest@shopline.com",
      "message": "This is a message",
      "nickname": "giftcarttest",
      "send_around": "2026-06-28T04:59:59-11:00"
    },
    "updated_at": "2026-06-14T03:32:28-11:00",
    "last_characters": "0611",
    "line_item_id": null,
    "note": "This is a note"
  }
}
Was this article helpful to you?
SHOPLINE
SHOPLINE
SHOPLINE Enterprise
Legal
Privacy
Terms
Developer Agreement
LinkedInEmail
LinkedInEmail
© Copyright 2013-2026 SHOPLINE Limited.