1. Documentation
  2. Plugins
  3. WooCommerce
  4. Extensions
  5. Gift Cards

REST API Reference

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 top

Gift 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-only

Returned 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-only

Returned 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-only

Returns 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-only

See 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-only
Returned 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 top

Create a gift card with meta data

Retrieve a gift card ↑ Back to top

Response

List all gift cards ↑ Back to top

Available 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 top

Update 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 key matches 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 top

Delete 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 top

Note: You can create, update or delete up to 100 objects.

Orders Endpoint ↑ Back to top

Gift 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/orders

Retrieve an order with gift cards ↑ Back to top

This 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 top

This 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 top

To delete a gift card from an order, set its amount attribute to 0.

Modify gift cards in an order ↑ Back to top

Sequential Order of Execution ↑ Back to top

Gift 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 top

Add 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-KKKK from the order, and
  • applies code EEEE-EEEE-EEEE-EEEE to 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 top

Have 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!

WooCommerce - the most customizable eCommerce platform for building your online business.

  • 30 day money back guarantee
  • Support teams across the world
  • Safe & Secure online payment