# Gift Card <div class="note"> <h4>Note</h4> <p>You need to contact Shopify Support to request the <code>write_gift_cards</code> and <code>read_gift_cards</code> <a href="/docs/admin-api/access-scopes">access scopes</a>.</p> </div> <p>A gift card is an alternative payment method. Each gift card has a unique code that is entered during checkout. Its balance can be redeemed over multiple checkouts. Optionally, a gift card can assigned to a specific customer. Gift card codes cannot be retrieved after they're created—only the last four characters can be retrieved.</p> <p>You can use the GiftCard resource to create, retrieve, and update gift cards for a store. After a gift card is created, only the expiry date, note, and template suffix can be updated.</p> <div class="note"> <h4>Note</h4> <p>You can't delete gift cards, but you can disable them. You can't enable gift cards that were previously disabled.</p> </div> ## Resource Properties ### Gift Card * api_client_id: The ID of the client that issued the gift card. * Type: x-string * Example: 431223487 * balance: The balance of the gift card. * Type: string * Example: "80.17" * code: The gift card code, which is a string of alphanumeric characters. For security reasons, this is available only upon creation of the gift card. (minimum: 8 characters, maximum: 20 characters) * Type: x-string * Example: "1234 4567 8901 2ABC" * created_at: The date and time (<a href="https://en.wikipedia.org/wiki/ISO_8601" target="_blank">ISO 8601</a> format) when the gift card was created. * Type: x-string * Example: "2008-12-31T19:00:00-05:00" * currency: The currency of the gift card. * Type: string * Example: "CAD" * customer_id: The ID of the customer associated with this gift card. * Type: x-string * Example: 368407052327 * disabled_at: The date and time (<a href="https://en.wikipedia.org/wiki/ISO_8601" target="_blank">ISO 8601</a> format) when the gift card was disabled. * Type: x-string * Example: "2009-01-31T19:00:00-05:00" * expires_on: The date (<code>YYYY-MM-DD</code> format) when the gift card expires. Returns <code>null</code> if the gift card doesn't have an expiration date. * Type: x-string * Example: "2020-01-31" * id: The ID of the gift card. * Type: x-string * Example: 989034056 * initial_value: The initial value of the gift card when it was created. * Type: string * Example: "100.00" * last_characters: The last four characters of the gift card code. Because gift cards are alternative payment methods, the full code cannot be retrieved. * Type: x-string * Example: "2ABC" * line_item_id: The ID of the line item that initiated the creation of this gift card, if it was created by an order. * Type: x-string * Example: 241253183 * note: An optional note that a merchant can attach to the gift card that isn't visible to customers. * Type: x-string * Example: "A note" * order_id: The ID of the order that initiated the creation of this gift card, if it was created by an order. * Type: x-string * Example: 241253183 * template_suffix: The suffix of the Liquid template that's used to render the gift card online. For example, if the value is <code>birthday</code>, then the gift card is rendered using the template <code>gift_card.birthday.liquid</code>. When the value is <code>null</code>, the default <code>gift_card.liquid</code> template is used. * Type: x-string * Example: "birthday" * user_id: The ID of the user that issued the gift card, if it was issued by a user. * Type: x-string * Example: 876543210 * updated_at: The date and time (<a href="https://en.wikipedia.org/wiki/ISO_8601" target="_blank">ISO 8601</a> format) when the gift card was last modified. * Type: x-string * Example: "2009-01-31T19:00:00-05:00" ## Retrieves a list of gift cards Retrieves a list of gift cards. <strong>Note:</strong> This endpoint implements pagination by using links that are provided in the response header. To learn more, refer to <a href='/api/usage/pagination-rest'>Make paginated requests to the REST Admin API</a>. ### Endpoint /admin/api/#{api_version}/gift_cards.json?status=enabled (GET) ### Parameters * api_version (required): * fields: Show only certain fields, specified by a comma-separated list of field names. * limit: The maximum number of results to show. * since_id: Restrict results to after the specified ID. * status: Retrieve gift cards with a given status. Valid values: ### Responses #### 200 Retrieves a list of gift cards Examples: ##### Retrieve a list of all enabled gift cards Request: ``` GET /admin/api/unstable/gift_cards.json ``` Response: ``` HTTP/1.1 200 OK {"gift_cards":[{"id":766118925,"balance":"25.00","created_at":"2025-01-02T11:09:43-05:00","updated_at":"2025-01-02T11:09:43-05:00","currency":"USD","initial_value":"50.00","disabled_at":null,"line_item_id":null,"api_client_id":null,"user_id":null,"customer_id":null,"note":null,"expires_on":"2024-01-02","template_suffix":null,"notify":true,"last_characters":"0e0e","order_id":null},{"id":10274553,"balance":"0.00","created_at":"2025-01-02T11:09:43-05:00","updated_at":"2025-01-02T11:09:43-05:00","currency":"USD","initial_value":"50.00","disabled_at":null,"line_item_id":null,"api_client_id":null,"user_id":null,"customer_id":null,"note":null,"expires_on":null,"template_suffix":null,"notify":true,"last_characters":"0y0y","order_id":null}]} ``` ##### Retrieve a list of all gift cards Request: ``` GET /admin/api/unstable/gift_cards.json ``` Response: ``` HTTP/1.1 200 OK {"gift_cards":[{"id":1035197676,"balance":"100.00","created_at":"2025-01-02T11:09:43-05:00","updated_at":"2025-01-02T11:09:43-05:00","currency":"USD","initial_value":"100.00","disabled_at":null,"line_item_id":null,"api_client_id":null,"user_id":null,"customer_id":null,"note":null,"expires_on":null,"template_suffix":null,"notify":true,"last_characters":"0d0d","order_id":null},{"id":766118925,"balance":"25.00","created_at":"2025-01-02T11:09:43-05:00","updated_at":"2025-01-02T11:09:43-05:00","currency":"USD","initial_value":"50.00","disabled_at":null,"line_item_id":null,"api_client_id":null,"user_id":null,"customer_id":null,"note":null,"expires_on":"2024-01-02","template_suffix":null,"notify":true,"last_characters":"0e0e","order_id":null},{"id":10274553,"balance":"0.00","created_at":"2025-01-02T11:09:43-05:00","updated_at":"2025-01-02T11:09:43-05:00","currency":"USD","initial_value":"50.00","disabled_at":null,"line_item_id":null,"api_client_id":null,"user_id":null,"customer_id":null,"note":null,"expires_on":null,"template_suffix":null,"notify":true,"last_characters":"0y0y","order_id":null}]} ``` ## Retrieves a single gift card Retrieves a single gift card by its ID ### Endpoint /admin/api/#{api_version}/gift_cards/{gift_card_id}.json (GET) ### Parameters * api_version (required): * gift_card_id (required): ### Responses #### 200 Retrieves a single gift card Examples: ##### Retrieve a single gift card Request: ``` GET /admin/api/2025-04/gift_cards/1035197676.json ``` Response: ``` HTTP/1.1 200 OK {"gift_card":{"id":1035197676,"balance":"100.00","created_at":"2025-01-02T11:09:43-05:00","updated_at":"2025-01-02T11:09:43-05:00","currency":"USD","initial_value":"100.00","disabled_at":null,"line_item_id":null,"api_client_id":null,"user_id":null,"customer_id":null,"note":null,"expires_on":null,"template_suffix":null,"last_characters":"0d0d","order_id":null}} ``` ## Updates an existing gift card <p>Updates an existing gift card.</p> <p>Expiry date, note, and template suffix properties of a gift card can be changed via the API.</p> <p>A customer ID can only be set if the current value is `null`.</p> ### Endpoint /admin/api/#{api_version}/gift_cards/{gift_card_id}.json (PUT) ### Parameters * api_version (required): * gift_card_id (required): ### Responses #### 200 Updates an existing gift card Examples: ##### Update the expiry date of a gift card Request: ``` PUT /admin/api/2025-04/gift_cards/1035197676.json {"gift_card":{"id":1035197676,"expires_on":"2020-01-01"}} ``` Response: ``` HTTP/1.1 200 OK {"gift_card":{"expires_on":"2020-01-01","template_suffix":null,"initial_value":"100.00","balance":"100.00","id":1035197676,"created_at":"2025-01-02T11:09:43-05:00","updated_at":"2025-01-02T11:10:56-05:00","currency":"USD","disabled_at":null,"line_item_id":null,"api_client_id":null,"user_id":null,"customer_id":null,"note":null,"last_characters":"0d0d","order_id":null}} ``` ##### Update the note of a gift card Request: ``` PUT /admin/api/2025-04/gift_cards/1035197676.json {"gift_card":{"id":1035197676,"note":"Updating with a new note"}} ``` Response: ``` HTTP/1.1 200 OK {"gift_card":{"note":"Updating with a new note","template_suffix":null,"initial_value":"100.00","balance":"100.00","id":1035197676,"created_at":"2025-01-02T11:09:43-05:00","updated_at":"2025-01-02T11:10:53-05:00","currency":"USD","disabled_at":null,"line_item_id":null,"api_client_id":null,"user_id":null,"customer_id":null,"expires_on":null,"last_characters":"0d0d","order_id":null}} ``` ## Retrieves a count of gift cards Retrieves a count of gift cards with a given status. ### Endpoint /admin/api/#{api_version}/gift_cards/count.json (GET) ### Parameters * api_version (required): * status: Count gift cards with a given status. Valid values: ### Responses #### 200 Retrieves a count of gift cards Examples: ##### Retrieve a count of all gift cards Request: ``` GET /admin/api/unstable/gift_cards/count.json ``` Response: ``` HTTP/1.1 200 OK {"count":3} ``` ##### Retrieve a count of enabled gift cards Request: ``` GET /admin/api/unstable/gift_cards/count.json ``` Response: ``` HTTP/1.1 200 OK {"count":3} ``` ## Creates a gift card <p>Creates a gift card.</p> <p>There are additional optional parameters that can be specified in the body of the request when creating a gift card:</p> ### Endpoint /admin/api/#{api_version}/gift_cards.json (POST) ### Parameters * api_version (required): * customer_id: The ID of the customer that purchased the gift card. * recipient_id: The ID of the intended recipient of the gift card. This property should be used if the recipientis different from the purchaser. The customer with this ID must have an email address. ### Responses #### 201 Creates a gift card Examples: ##### Create a gift card with a custom code Request: ``` POST /admin/api/2025-04/gift_cards.json {"gift_card":{"note":"This is a note","initial_value":"100.00","code":"ABCD EFGH IJKL MNOP","template_suffix":"gift_cards.birthday.liquid"}} ``` Response: ``` HTTP/1.1 201 Created {"gift_card":{"id":1063936320,"balance":"100.00","created_at":"2025-01-02T11:10:51-05:00","updated_at":"2025-01-02T11:10:51-05:00","currency":"USD","initial_value":"100.00","disabled_at":null,"line_item_id":null,"api_client_id":755357713,"user_id":null,"customer_id":null,"note":"This is a note","expires_on":null,"template_suffix":"gift_cards.birthday.liquid","last_characters":"mnop","order_id":null,"code":"abcdefghijklmnop"}} ``` ##### Create a gift card with an automatically generated code Request: ``` POST /admin/api/2025-04/gift_cards.json {"gift_card":{"initial_value":"25.00"}} ``` Response: ``` HTTP/1.1 201 Created {"gift_card":{"id":1063936322,"balance":"25.00","created_at":"2025-01-02T11:10:52-05:00","updated_at":"2025-01-02T11:10:52-05:00","currency":"USD","initial_value":"25.00","disabled_at":null,"line_item_id":null,"api_client_id":755357713,"user_id":null,"customer_id":null,"note":null,"expires_on":null,"template_suffix":null,"last_characters":"8g42","order_id":null,"code":"2f8e5fh6bag78g42"}} ``` ##### Create a scheduled gift card with a recipient and a message Request: ``` POST /admin/api/2025-04/gift_cards.json {"gift_card":{"initial_value":"100.00","recipient_id":207119551,"message":"Happy birthday!","send_on":"2023-12-31"}} ``` Response: ``` HTTP/1.1 201 Created {"gift_card":{"id":1063936318,"balance":"100.00","created_at":"2023-11-30T19:00:00-05:00","updated_at":"2023-11-30T19:00:00-05:00","currency":"USD","initial_value":"100.00","disabled_at":null,"line_item_id":null,"api_client_id":755357713,"user_id":null,"customer_id":null,"note":null,"expires_on":null,"template_suffix":null,"last_characters":"55h7","order_id":null,"code":"hf26he2f8gaf55h7"}} ``` ## Disables a gift card Disables a gift card. This action can't be undone. ### Endpoint /admin/api/#{api_version}/gift_cards/{gift_card_id}/disable.json (POST) ### Parameters * api_version (required): * gift_card_id (required): ### Responses #### 201 Disables a gift card Examples: ##### Disable a gift card Request: ``` POST /admin/api/2025-04/gift_cards/1035197676/disable.json {"gift_card":{"id":1035197676}} ``` Response: ``` HTTP/1.1 201 Created {"gift_card":{"disabled_at":"2025-01-02T11:10:54-05:00","template_suffix":null,"initial_value":"100.00","balance":"100.00","id":1035197676,"created_at":"2025-01-02T11:09:43-05:00","updated_at":"2025-01-02T11:10:54-05:00","currency":"USD","line_item_id":null,"api_client_id":null,"user_id":null,"customer_id":null,"note":null,"expires_on":null,"last_characters":"0d0d","order_id":null}} ``` ## Searches for gift cards <p>Searches for gift cards that match a supplied query. The following fields are indexed by search:</p> <ul> <li><code>created_at</code></li> <li><code>updated_at</code></li> <li><code>disabled_at</code></li> <li><code>balance</code></li> <li><code>initial_value</code></li> <li><code>amount_spent</code></li> <li><code>email</code></li> <li><code>last_characters</code></li> </ul> <p><strong>Note:</strong> This endpoint implements pagination by using links that are provided in the response header. To learn more, refer to <a href='/api/usage/pagination-rest'>Make paginated requests to the REST Admin API</a>.</p> ### Endpoint /admin/api/#{api_version}/gift_cards/search.json?query=last_characters:mnop (GET) ### Parameters * api_version (required): * created_at_max: Show gift cards created at or before date. * created_at_min: Show gift cards created at or after date. * fields: Show only certain fields, specified by a comma-separated list of field names. * limit: The maximum number of results to retrieve. * order: The field and direction to order results by. * query: The text to search for. * updated_at_max: Show gift cards last updated at or before date. * updated_at_min: Show gift cards last updated at or after date. ### Responses #### 200 Searches for gift cards Examples: ##### Retrieve all gift cards with the last characters "mnop" Request: ``` GET /admin/api/unstable/gift_cards/search.json ``` Response: ``` HTTP/1.1 200 OK {"gift_cards":[{"id":1063936316,"balance":"10.00","created_at":"2025-01-02T11:10:46-05:00","updated_at":"2025-01-02T11:10:46-05:00","currency":"USD","initial_value":"10.00","disabled_at":null,"line_item_id":null,"api_client_id":null,"user_id":null,"customer_id":null,"note":null,"expires_on":null,"template_suffix":null,"notify":true,"last_characters":"mnop","order_id":null}]} ```