Gift Card Adjustment

Shopify Plus

The Gift Card Adjustment resource is available to Shopify Plus merchants only. Contact your Merchant Success Manager to enable this API resource for your store.

A gift card adjustment is a way to adjust the balance of a gift card. Balances cannot be adjusted to below $0. Balances are updated as soon as you receive a successful response.

When creating a gift card adjustment, you may also set note, remote_transaction_ref, and remote_transaction_url.

What you can do with Gift Card Adjustment

The Shopify API lets you do the following with the Gift Card Adjustment resource. More detailed versions of these general actions may be available:

Gift Card Adjustment properties

id
"id": 989034056

A unique numeric identifier for the adjustment.

number
"number": 1

A numeric sequence number for this adjustment with respect to the gift card.

amount
"amount": -20.0

A number (signed) representing the value of the adjustment.

note
"note": "External debit of gift card"

The text of an optional note that can be attached to the adjustment. This value is not visible to customers.

remote_transaction_ref
"remote_transaction_ref": "external-ref-230923"

The text of an optional reference note that can be attached to the adjustment. This value is not visible to customers.

remote_transaction_url
"remote_transaction_url": "http://example.com/external-gift-card-app/external-ref-230923"

An optional reference URL that can be attached to the adjustment. This value is not visible to customers.

api_client_id
"api_client_id": 431223487

A unique numeric identifier of the application that issued the adjustment (if it was issued by an application).

user_id
"user_id": 241253183

A unique numeric identifier of the user that issued the adjustment (if it was issued by a user).

order_transaction_id
"order_transaction_id": 203972033

A unique numeric identifier of the order transaction that issued the adjustment (if it was caused by an application of a gift card to an order).

created_at
"created_at": "2015-06-31T19:00:00-05:00"

The date and time when the adjustment was created. The API returns this value in ISO 8601 format.

processed_at
"processed_at": "2015-06-31T19:00:00-05:00"

The date and time when the adjustment was imported, in ISO 8601 format. This value can be set to dates in the past when importing from other systems. If no value is provided, it will be auto-generated.

Endpoints

GET /admin/gift_cards/48394658/adjustments.json

Get a list of all adjustments made to a gift card

GET /admin/gift_cards/#{id}/adjustments.json
View Response
HTTP/1.1 200 OK
{
  "adjustments": [
    {
      "id": 1,
      "gift_card_id": 48394658,
      "api_client_id": 755357713,
      "user_id": 0,
      "order_transaction_id": null,
      "number": 1,
      "amount": "10.00",
      "processed_at": "2018-01-29T09:05:04-05:00",
      "created_at": "2018-01-29T09:05:04-05:00",
      "updated_at": "2018-01-29T09:05:04-05:00",
      "note": "Customer refilled gift card by $10",
      "remote_transaction_ref": null,
      "remote_transaction_url": null
    }
  ]
}
GET /admin/gift_cards/48394658/adjustments/2.json

Show the details of a particular adjustment

GET /admin/gift_cards/#{id}/adjustments/2.json
View Response
HTTP/1.1 200 OK
{
  "adjustment": {
    "id": 2,
    "gift_card_id": 48394658,
    "api_client_id": 755357713,
    "user_id": 0,
    "order_transaction_id": null,
    "number": 1,
    "amount": "10.00",
    "processed_at": "2018-01-29T09:05:05-05:00",
    "created_at": "2018-01-29T09:05:05-05:00",
    "updated_at": "2018-01-29T09:05:05-05:00",
    "note": "Customer refilled gift card by $10",
    "remote_transaction_ref": null,
    "remote_transaction_url": null
  }
}
POST /admin/gift_cards/48394658/adjustments.json

Credit a gift card to increase the balance

POST /admin/gift_cards/#{id}/adjustments.json
{
  "adjustment": {
    "amount": 10.0,
    "note": "Customer refilled gift card by $10"
  }
}
View Response
HTTP/1.1 201 Created
{
  "adjustment": {
    "id": 3,
    "gift_card_id": 48394658,
    "api_client_id": 755357713,
    "user_id": 0,
    "order_transaction_id": null,
    "number": 1,
    "amount": "10.00",
    "processed_at": "2018-01-29T09:05:06-05:00",
    "created_at": "2018-01-29T09:05:06-05:00",
    "updated_at": "2018-01-29T09:05:06-05:00",
    "note": "Customer refilled gift card by $10",
    "remote_transaction_ref": null,
    "remote_transaction_url": null
  }
}

Debit a gift card to decrease the balance

POST /admin/gift_cards/#{id}/adjustments.json
{
  "adjustment": {
    "amount": -20.0,
    "note": "Customer spent $20 via external service"
  }
}
View Response
HTTP/1.1 201 Created
{
  "adjustment": {
    "id": 4,
    "gift_card_id": 48394658,
    "api_client_id": 755357713,
    "user_id": 0,
    "order_transaction_id": null,
    "number": 1,
    "amount": "-20.00",
    "processed_at": "2018-01-29T09:05:07-05:00",
    "created_at": "2018-01-29T09:05:07-05:00",
    "updated_at": "2018-01-29T09:05:07-05:00",
    "note": "Customer spent $20 via external service",
    "remote_transaction_ref": null,
    "remote_transaction_url": null
  }
}

Create an adjustment that references an external transaction

POST /admin/gift_cards/#{id}/adjustments.json
{
  "adjustment": {
    "amount": 10.0,
    "remote_transaction_ref": "gift_card_app_transaction_193402",
    "remote_transaction_url": "http://example.com/my-gift-card-app/gift_card_adjustments/193402"
  }
}
View Response
HTTP/1.1 201 Created
{
  "adjustment": {
    "id": 5,
    "gift_card_id": 48394658,
    "api_client_id": 755357713,
    "user_id": 0,
    "order_transaction_id": null,
    "number": 1,
    "amount": "10.00",
    "processed_at": "2018-01-29T09:05:07-05:00",
    "created_at": "2018-01-29T09:05:07-05:00",
    "updated_at": "2018-01-29T09:05:07-05:00",
    "note": null,
    "remote_transaction_ref": "gift_card_app_transaction_193402",
    "remote_transaction_url": "http://example.com/my-gift-card-app/gift_card_adjustments/193402"
  }
}

Record a gift card adjustment as if it happened in the past

POST /admin/gift_cards/#{id}/adjustments.json
{
  "adjustment": {
    "amount": 10.0,
    "processed_at": "2017-07-29T09:05:07.731-04:00"
  }
}
View Response
HTTP/1.1 201 Created
{
  "adjustment": {
    "id": 6,
    "gift_card_id": 48394658,
    "api_client_id": 755357713,
    "user_id": 0,
    "order_transaction_id": null,
    "number": 1,
    "amount": "10.00",
    "processed_at": "2017-07-29T09:05:07-04:00",
    "created_at": "2018-01-29T09:05:07-05:00",
    "updated_at": "2018-01-29T09:05:07-05:00",
    "note": null,
    "remote_transaction_ref": null,
    "remote_transaction_url": null
  }
}