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.
## Resource Properties ### Gift Card Adjustment * id: A unique numeric identifier for the adjustment. * Type: x-string * Example: 989034056 * number: A numeric sequence number for this adjustment with respect to the gift card. * Type: x-string * Example: 1 * amount: A number (signed) representing the value of the adjustment. * Type: x-string * Example: -20.0 * note: The text of an optional note that can be attached to the adjustment. This value is not visible to customers. * Type: x-string * Example: "External debit of gift card" * remote_transaction_ref: The text of an optional reference note that can be attached to the adjustment. This value is not visible to customers. * Type: x-string * Example: "external-ref-230923" * remote_transaction_url: An optional reference URL that can be attached to the adjustment. This value is not visible to customers. * Type: x-string * Example: "http://example.com/external-gift-card-app/external-ref-230923" * api_client_id: A unique numeric identifier of the application that issued the adjustment (if it was issued by an application). * Type: x-string * Example: 431223487 * user_id: A unique numeric identifier of the user that issued the adjustment (if it was issued by a user). * Type: x-string * Example: 241253183 * order_transaction_id: 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). * Type: x-string * Example: 203972033 * created_at: The date and time when the adjustment was created. The API returns this value in ISO 8601 format. * Type: x-string * Example: "2015-06-31T19:00:00-05:00" * processed_at: 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. * Type: x-string * Example: "2015-06-31T19:00:00-05:00" ## Receive a list of all Gift Card Adjustments ### Endpoint /admin/api/#{api_version}/gift_cards/{gift_card_id}/adjustments.json (GET) ### Parameters * api_version (required): * gift_card_id (required): ### Responses #### 200 Receive a list of all Gift Card Adjustments Examples: ##### Get a list of all adjustments made to a gift card Request: ``` GET /admin/api/unstable/gift_cards/1035197676/adjustments.json ``` Response: ``` HTTP/1.1 200 OK {"adjustments":[{"id":1064273908,"gift_card_id":1035197676,"api_client_id":null,"user_id":null,"order_transaction_id":null,"number":null,"amount":"10.00","processed_at":null,"created_at":"2025-01-02T11:09:43-05:00","updated_at":"2025-01-02T11:09:43-05:00","note":"Customer refilled gift card by $10","remote_transaction_ref":null,"remote_transaction_url":null}]} ``` ## Create a new Gift Card Adjustment ### Endpoint /admin/api/#{api_version}/gift_cards/{gift_card_id}/adjustments.json (POST) ### Parameters * api_version (required): * gift_card_id (required): ### Responses #### 201 Create a new Gift Card Adjustment Examples: ##### Create an adjustment that references an external transaction Request: ``` POST /admin/api/unstable/gift_cards/1035197676/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"}} ``` Response: ``` HTTP/1.1 201 Created {"adjustment":{"id":1064273910,"gift_card_id":1035197676,"api_client_id":755357713,"user_id":null,"order_transaction_id":null,"number":1,"amount":"10.00","processed_at":"2025-01-02T11:20:30-05:00","created_at":"2025-01-02T11:20:30-05:00","updated_at":"2025-01-02T11:20:30-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"}} ``` ##### Credit a gift card to increase the balance Request: ``` POST /admin/api/unstable/gift_cards/1035197676/adjustments.json {"adjustment":{"amount":10.0,"note":"Customer refilled gift card by $10"}} ``` Response: ``` HTTP/1.1 201 Created {"adjustment":{"id":1064273912,"gift_card_id":1035197676,"api_client_id":755357713,"user_id":null,"order_transaction_id":null,"number":1,"amount":"10.00","processed_at":"2025-01-02T11:20:32-05:00","created_at":"2025-01-02T11:20:32-05:00","updated_at":"2025-01-02T11:20:32-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 Request: ``` POST /admin/api/unstable/gift_cards/1035197676/adjustments.json {"adjustment":{"amount":-20.0,"note":"Customer spent $20 via external service"}} ``` Response: ``` HTTP/1.1 201 Created {"adjustment":{"id":1064273911,"gift_card_id":1035197676,"api_client_id":755357713,"user_id":null,"order_transaction_id":null,"number":1,"amount":"-20.00","processed_at":"2025-01-02T11:20:31-05:00","created_at":"2025-01-02T11:20:31-05:00","updated_at":"2025-01-02T11:20:31-05:00","note":"Customer spent $20 via external service","remote_transaction_ref":null,"remote_transaction_url":null}} ``` ##### Record a gift card adjustment as if it happened in the past Request: ``` POST /admin/api/unstable/gift_cards/1035197676/adjustments.json {"adjustment":{"amount":10.0,"processed_at":"2024-07-02T11:20:29-04:00"}} ``` Response: ``` HTTP/1.1 201 Created {"adjustment":{"id":1064273909,"gift_card_id":1035197676,"api_client_id":755357713,"user_id":null,"order_transaction_id":null,"number":1,"amount":"10.00","processed_at":"2024-07-02T11:20:29-04:00","created_at":"2025-01-02T11:20:29-05:00","updated_at":"2025-01-02T11:20:29-05:00","note":null,"remote_transaction_ref":null,"remote_transaction_url":null}} ``` ## Receive a single Gift Card Adjustment ### Endpoint /admin/api/#{api_version}/gift_cards/{gift_card_id}/adjustments/{adjustment_id}.json (GET) ### Parameters * adjustment_id (required): * api_version (required): * gift_card_id (required): ### Responses #### 200 Receive a single Gift Card Adjustment Examples: ##### Show the details of a particular adjustment Request: ``` GET /admin/api/unstable/gift_cards/1035197676/adjustments/1064273908.json ``` Response: ``` HTTP/1.1 200 OK {"adjustment":{"id":1064273908,"gift_card_id":1035197676,"api_client_id":null,"user_id":null,"order_transaction_id":null,"number":null,"amount":"10.00","processed_at":null,"created_at":"2025-01-02T11:09:43-05:00","updated_at":"2025-01-02T11:09:43-05:00","note":"Customer refilled gift card by $10","remote_transaction_ref":null,"remote_transaction_url":null}} ```