This document is written for WooCommerce developers looking to extend or customize WooCommerce Gift Cards. It requires an advanced understanding of the WooCommerce REST API.
Gift Cards Endpoint
↑ Back to topGift Cards introduces a new /gift_cards/ endpoint that allows you to create, read, update, and delete gift card codes.
List of Properties
↑ Back to top| Attribute | Type | Description | Usage |
|---|---|---|---|
id |
integer |
Gift card ID | Read-only |
code |
string |
Gift card code | Read-only in update context. Required in update context. A code is generated automatically on creation. |
recipient |
string |
Recipient’s email address | Required in create context. Validated as e-mail address. |
sender |
string |
Sender’s name | Required in create context. |
sender_email |
string |
Sender’s email address | Validated as e-mail address. |
message |
string |
Message to include in the email sent to the recipient | — |
balance |
number |
Issued gift card balance | Read-only in update context. Required in create context. |
remaining |
number |
Remaining gift card balance | Read-only |
order_id |
integer |
Associated order ID | — |
order_item_id |
integer |
Associated order item ID | — |
create_date |
string |
Gift card creation date | Read-onlyReturned as date in ISO8601 format Y-m-d H:i:s.Generated automatically on creation. |
deliver_date |
string |
Gift card delivery date | Validated as date in ISO8601 format Y-m-d H:i:s.Updating the deliver_date of an alredy delivered gift card is not possible. |
expire_date |
string |
Gift card expiration date | Validated as date in ISO8601 format Y-m-d H:i:s.Setting an expire_date that precedes the create_date is not possible. |
redeem_date |
string |
Gift card redeemed date | Read-onlyReturned as date in ISO8601 format Y-m-d H:i:s. |
redeemed_by |
integer |
Gift card redeemed by user (ID | If greater than zero then redeem_date is set automatically.An error is thrown when attempting to redeem a disabled, expired, or redeemed gift card – or one with no remaining balance. Requires redeeming to be enabled store-wide. |
delivered |
string |
Delivery status | Read-onlyReturns the user_id of the recipient, or no if undelivered. |
is_active |
string / enum |
Active status | Values on (default) or off.Changing the status of an expired gift card is not possible. |
activities |
array |
Logged activity entries | Read-onlySee Gift Card Activity Properties |
meta_data |
array |
List of metadata | See Gift Card Meta Properties |
Gift Card Activity Properties
| Attribute | Type | Description | Usage |
|---|---|---|---|
id |
integer |
Activity ID | Read-only |
type |
string |
Activity Type | Read-only |
user_id |
integer |
Activity User ID | Read-only |
user_email |
string |
Activity User Email | Read-only |
object_id |
integer |
Activity Order ID or Order Item ID | Read-only |
gc_id |
integer |
Gift Card ID | Read-only |
gc_code |
string |
Gift Card Code | Read-only |
amount |
number |
Activity Amount | Read-only |
date |
string |
Activity Date | Read-onlyReturned as date in ISO8601 format Y-m-d H:i:s. |
note |
string |
Activity Note | Read-only |
Gift Card Meta Properties
| Attribute | Type | Description | Usage |
|---|---|---|---|
id |
integer |
Meta ID | Read-only |
key |
string |
Meta ID | Required |
value |
mixed |
Meta value | Empty string is allowed. In update context, meta is deleted if not passed. |
Create a gift card
↑ Back to topCreate a gift card with meta data
Retrieve a gift card
↑ Back to topResponse
List all gift cards
↑ Back to topAvailable Parameters
| Parameter | Type | Description |
|---|---|---|
context |
string | Scope under which the request is made; determines fields present in response. Options: view and edit. Default is view. |
page |
integer | Current page of the collection. Default is 1. |
per_page |
integer | Maximum number of items to be returned in result set. Default is 10. |
orderby |
string | Sort collection by object attribute. Options: id, create_date, deliver_date, balance, remaining, order_id . Default is id. |
order |
string | Order sort attribute ascending or descending. Options: asc and desc. Default is desc. |
Response
Update a gift card
↑ Back to topUpdate a gift card meta key/value pair
In order to update a key/value pair in the meta_data array, pass an existing key .
- If they
keymatches with an existing one, it will be updated. - If it doesn’t match, it will be created.
To update an existing key in the meta_data array with a new value, pass an existing key with a new value pair.
Delete a gift card
↑ Back to topDelete a gift card meta key/value pair
In order to delete a key/value pair in the meta_data array, pass an existing key but ommit the value.
Batch update gift cards
↑ Back to topNote: You can create, update or delete up to 100 objects.
Orders Endpoint
↑ Back to topGift Cards extends the /orders/ endpoint responses with the gift_cards property, which lists all gift card codes used to pay for an order, along with the amount used from each.
List of properties
↑ Back to top| Attribute | Type | Description | Usage |
|---|---|---|---|
gift_cards |
array |
List of gift cards used to pay for an order | Read Write |
Gift Card Properties
| Attribute | Type | Description | Usage |
|---|---|---|---|
id |
integer |
Gift card ID | Read |
code |
string |
Gift card code | Read Write |
amount |
number |
Gift card amount used to pay for the order | Read Write Optional in Write context. |
Create an order with gift cards
↑ Back to top_POST_ /wp-json/wc/v3/ordersRetrieve an order with gift cards
↑ Back to topThis API lets you retrieve and view a specific order by ID.
_GET_ `/wp-json/wc/v3/orders/<id>`Response
Apply gift cards to an order
↑ Back to topThis API enables you to apply multiple gift cards to an unpaid order.
Gift cards with specified amounts will be applied only if the remaining order total exceeds the specified amount.
If you do not specify an amount, the API will attempt to pay for as much of the remaining order total as possible using the available gift card balance.
Delete gift cards in an order
↑ Back to topTo delete a gift card from an order, set its amount attribute to 0.
Modify gift cards in an order
↑ Back to topSequential Order of Execution
↑ Back to topGift cards specified in the gift_cards array are applied sequentially.
If any of the gift card codes you provide is invalid, does not have the specified balance, or cannot be utilized, then your request will fail.
Working with Orders: Examples
↑ Back to topAdd multiple gift cards to order
The following example demonstrates how to successfully apply multiple gift card codes to an order with a total of $100. The applied gift card codes cover $90 of the $100 order total.
Here’s an example of an unsuccessful API call:
Remove a gift card and add another
Let’s make some more changes to the same order. The following request:
- removes gift card code
KKKK-KKKK-KKKK-KKKKfrom the order, and - applies code
EEEE-EEEE-EEEE-EEEEto it.
Remember that the API validates changes in the order specified in the gift cards array. If the elements of the array had been reversed, the previous request would have failed:
Questions & Support
↑ Back to topHave a question before you buy? Please fill out this pre-sales form.
Already purchased and need assistance? Get in touch with us via the Help Desk!