Gift card account API

The gift card account REST endpoints provide programmatic management of gift card accounts at the account level, not the cart or quote level. Use this API to create, retrieve, update, and delete gift card accounts, or to provision gift card accounts in bulk through the JSON import endpoint.

These endpoints are designed for:

• Administrators managing gift card programs
• Third-party integrations provisioning gift cards from external systems, such as ERP, CRM, and marketing platforms
• Automated workflows for bulk gift card creation

Authentication

All endpoints require an admin or integration bearer token. The token must be associated with a role that includes the Magento_GiftCardAccount::giftcardaccount Access Control List (ACL) resource.

For bulk import operations, the role must also include the Magento_ImportExport::import_api ACL resource.

Website and store context

Website and store view values are resolved from HTTP request headers, not from the request body. Pass one of the following headers with each request:

• Store: <store_view_code>
• Magento-Website-Code: <website_code>

The API resolves the website automatically from these headers. Do not include website_id in the REST request payload.

REST API reference

The API exposes the following operations under /V1/giftcardaccounts, all secured by the Magento_GiftCardAccount::giftcardaccount ACL resource:

Field reference

Create a gift card account

Creates a new gift card account with duplicate code detection.

Request body:

Copy
{
  "giftcardAccount": {
    "code": "GIFT-1234-ABCD",
    "balance": 100.00,
    "status": 1,
    "state": 0,
    "is_redeemable": 1,
    "date_expires": "2027-12-31"
  }
}
Copied to your clipboard
{
  "giftcardAccount": {
    "code": "GIFT-1234-ABCD",
    "balance": 100.00,
    "status": 1,
    "state": 0,
    "is_redeemable": 1,
    "date_expires": "2027-12-31"
  }
}

Response (200):

Copy
{
  "account_id": 42,
  "code": "GIFT-1234-ABCD",
  "balance": 100,
  "status": 1,
  "state": 0,
  "is_redeemable": 1,
  "date_expires": "2027-12-31",
  "date_created": "2026-03-12"
}
Copied to your clipboard
{
  "account_id": 42,
  "code": "GIFT-1234-ABCD",
  "balance": 100,
  "status": 1,
  "state": 0,
  "is_redeemable": 1,
  "date_expires": "2027-12-31",
  "date_created": "2026-03-12"
}

Retrieve a gift card account by ID

Response (200):

Returns a single gift card account object.

Retrieve a gift card account by code

Response (200):

Returns a single gift card account object.

List gift card accounts with search criteria

Pass search criteria as query parameters. The following example returns gift card accounts where status equals 1 (enabled):

Copy
GET /V1/giftcardaccounts?searchCriteria[filterGroups][0][filters][0][field]=status&searchCriteria[filterGroups][0][filters][0][value]=1&searchCriteria[pageSize]=10&searchCriteria[currentPage]=1
Copied to your clipboard
GET /V1/giftcardaccounts?searchCriteria[filterGroups][0][filters][0][field]=status&searchCriteria[filterGroups][0][filters][0][value]=1&searchCriteria[pageSize]=10&searchCriteria[currentPage]=1

Response (200):

Copy
{
  "items": [
    {
      "account_id": 42,
      "code": "GIFT-1234-ABCD",
      "balance": 100,
      "status": 1,
      "state": 0,
      "is_redeemable": 1,
      "date_expires": "2027-12-31",
      "date_created": "2026-03-12"
    }
  ],
  "search_criteria": { },
  "total_count": 1
}
Copied to your clipboard
{
  "items": [
    {
      "account_id": 42,
      "code": "GIFT-1234-ABCD",
      "balance": 100,
      "status": 1,
      "state": 0,
      "is_redeemable": 1,
      "date_expires": "2027-12-31",
      "date_created": "2026-03-12"
    }
  ],
  "search_criteria": { },
  "total_count": 1
}

Update a gift card account

Updates an existing gift card account using merge semantics. Only non-null fields in the request are applied. The code field is immutable. Passing a different code returns a validation error.

Request body:

Copy
{
  "giftcardAccount": {
    "balance": 75.00,
    "status": 1
  }
}
Copied to your clipboard
{
  "giftcardAccount": {
    "balance": 75.00,
    "status": 1
  }
}

Response (200):

Returns the updated gift card account object.

Delete a gift card account

Response (200):

Copy
true
Copied to your clipboard
true

Bulk import via JSON

Gift card accounts can be provisioned in bulk using POST /V1/import/json with entity type giftcardaccount. This endpoint requires the Magento_ImportJsonApi::import_api Access Control List (ACL) resource in addition to the gift card account ACL.

Supported behaviors

Request example

Copy
{
  "source": {
    "entity": "giftcardaccount",
    "behavior": "append",
    "validation_strategy": "validation-stop-on-errors",
    "allowed_error_count": "10",
    "items": [
      {
        "code": "BULK-001",
        "balance": 50.00,
        "website_id": 1,
        "status": 1,
        "state": 0,
        "is_redeemable": 1,
        "date_expires": "2027-06-30"
      },
      {
        "code": "BULK-002",
        "balance": 25.00,
        "website_id": 1
      }
    ]
  }
}
Copied to your clipboard
{
  "source": {
    "entity": "giftcardaccount",
    "behavior": "append",
    "validation_strategy": "validation-stop-on-errors",
    "allowed_error_count": "10",
    "items": [
      {
        "code": "BULK-001",
        "balance": 50.00,
        "website_id": 1,
        "status": 1,
        "state": 0,
        "is_redeemable": 1,
        "date_expires": "2027-06-30"
      },
      {
        "code": "BULK-002",
        "balance": 25.00,
        "website_id": 1
      }
    ]
  }
}

Import behavior details

• Each row in the import payload requires an explicit website_id, unlike REST endpoints which infer the website from request headers.
• Each row is validated independently. Invalid rows produce per-row errors without affecting valid rows in the same batch.
• Duplicate codes within the same batch are detected and reported as per-row errors rather than causing a transaction rollback.
• Import writes directly to the database for performance and bypasses the vendor model's save lifecycle. Balance-change history entries are not created during import.
• REST create operations reject past expiration dates. Import accepts past expiration dates by design, to support historical data migration.

Error handling

The API returns standard HTTP status codes:

Input validation covers required fields, value ranges (status must be 0 or 1, state must be 0-3, balance must be non-negative), date format, and type safety. Non-numeric values for numeric fields are rejected.