Gift Cards API

Manage and validate gift cards in your store.

List Gift Cards

http

GET /api/external/v1/gift-cards

Query Parameters

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`per_page`	integer	Items per page (default: 15, max: 100)
`status`	string	Filter: `active`, `depleted`, `revoked`
`search`	string	Search by gift card code
`email`	string	Filter by recipient email

Example Request

bash

curl -X GET "https://yourstore.pixlpay.net/api/external/v1/gift-cards?status=active" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Response

json

{
  "success": true,
  "data": [
    {
      "id": 1,
      "code": "ABCD-EFGH-IJKL-MNOP",
      "initial_balance": "50.00",
      "balance": "35.50",
      "currency": "USD",
      "status": "active",
      "recipient_email": "customer@example.com",
      "recipient_name": "John Doe",
      "personal_message": "Happy Birthday!",
      "product": {
        "id": 10,
        "name": "$50 Gift Card"
      },
      "order": {
        "id": 42,
        "order_number": "ORD-2025-042"
      },
      "purchased_at": "2025-01-15T10:30:00Z",
      "first_used_at": "2025-01-20T14:15:00Z",
      "last_used_at": "2025-01-25T09:45:00Z",
      "expires_at": "2026-01-15T23:59:59Z",
      "created_at": "2025-01-15T10:30:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 3,
    "per_page": 15,
    "total": 42
  }
}

Get Single Gift Card

http

GET /api/external/v1/gift-cards/{id}

Example Request

bash

curl -X GET "https://yourstore.pixlpay.net/api/external/v1/gift-cards/1" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Response

json

{
  "success": true,
  "data": {
    "id": 1,
    "code": "ABCD-EFGH-IJKL-MNOP",
    "initial_balance": "50.00",
    "balance": "35.50",
    "currency": "USD",
    "status": "active",
    "recipient_email": "customer@example.com",
    "recipient_name": "John Doe",
    "personal_message": "Happy Birthday!",
    "product": {
      "id": 10,
      "name": "$50 Gift Card"
    },
    "order": {
      "id": 42,
      "order_number": "ORD-2025-042"
    },
    "redemptions": [
      {
        "id": 1,
        "amount": "14.50",
        "balance_before": "50.00",
        "balance_after": "35.50",
        "order": {
          "id": 55,
          "order_number": "ORD-2025-055"
        },
        "created_at": "2025-01-20T14:15:00Z"
      }
    ],
    "purchased_at": "2025-01-15T10:30:00Z",
    "first_used_at": "2025-01-20T14:15:00Z",
    "last_used_at": "2025-01-20T14:15:00Z",
    "expires_at": "2026-01-15T23:59:59Z",
    "created_at": "2025-01-15T10:30:00Z"
  }
}

Check Gift Card Balance

Validate a gift card code and check its remaining balance. This endpoint can be used during checkout to verify gift cards entered by customers.

http

POST /api/external/v1/gift-cards/validate

Request Body

Parameter	Type	Required	Description
`code`	string	Yes	Gift card code (dashes optional)

Example Request

bash

curl -X POST "https://yourstore.pixlpay.net/api/external/v1/gift-cards/validate" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"code": "ABCD-EFGH-IJKL-MNOP"}'

Success Response

json

{
  "success": true,
  "data": {
    "valid": true,
    "gift_card": {
      "id": 1,
      "code": "XXXX-XXXX-XXXX-MNOP",
      "balance": "35.50",
      "formatted_balance": "$35.50",
      "currency": "USD",
      "expires_at": "2026-01-15T23:59:59Z"
    }
  }
}

Invalid Card Response

json

{
  "success": false,
  "data": {
    "valid": false,
    "message": "Gift card has no remaining balance"
  }
}

Code Format

Gift card codes can be entered with or without dashes. Both ABCDEFGHIJKLMNOP and ABCD-EFGH-IJKL-MNOP are accepted.

Redeem Gift Card

Apply a gift card balance to reduce an order total.

http

POST /api/external/v1/gift-cards/{id}/redeem

Request Body

Parameter	Type	Required	Description
`amount`	number	Yes	Amount to redeem (max: remaining balance)
`order_id`	integer	No	Order to apply redemption to

Example Request

bash

curl -X POST "https://yourstore.pixlpay.net/api/external/v1/gift-cards/1/redeem" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"amount": 15.00, "order_id": 100}'

Response

json

{
  "success": true,
  "data": {
    "redemption": {
      "id": 5,
      "amount": "15.00",
      "balance_before": "35.50",
      "balance_after": "20.50",
      "order_id": 100,
      "created_at": "2025-01-25T16:30:00Z"
    },
    "gift_card": {
      "id": 1,
      "balance": "20.50",
      "status": "active"
    }
  },
  "message": "Gift card redeemed successfully"
}

Partial Redemption

If the requested amount exceeds the available balance, only the available balance will be redeemed. Check the amount in the response to confirm the actual redeemed amount.

Update Gift Card

Update recipient information or expiration date.

http

PUT /api/external/v1/gift-cards/{id}

Request Body

Parameter	Type	Required	Description
`recipient_email`	string	No	Recipient email address
`recipient_name`	string	No	Recipient name
`expires_at`	string	No	Expiration date (YYYY-MM-DD)

Example Request

bash

curl -X PUT "https://yourstore.pixlpay.net/api/external/v1/gift-cards/1" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"recipient_email": "newemail@example.com", "recipient_name": "Jane Doe"}'

Response

json

{
  "success": true,
  "data": {
    "id": 1,
    "code": "ABCD-EFGH-IJKL-MNOP",
    "recipient_email": "newemail@example.com",
    "recipient_name": "Jane Doe",
    "balance": "35.50",
    "status": "active"
  },
  "message": "Gift card updated successfully"
}

Revoke Gift Card

Permanently deactivate a gift card. This action cannot be undone.

http

POST /api/external/v1/gift-cards/{id}/revoke

Example Request

bash

curl -X POST "https://yourstore.pixlpay.net/api/external/v1/gift-cards/1/revoke" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Response

json

{
  "success": true,
  "data": {
    "id": 1,
    "code": "ABCD-EFGH-IJKL-MNOP",
    "status": "revoked",
    "balance": "35.50"
  },
  "message": "Gift card revoked successfully"
}

Irreversible Action

Revoking a gift card is permanent. The remaining balance cannot be recovered or transferred. Use this only for fraud prevention or at customer request.

Get Gift Card Statistics

Retrieve aggregate statistics for all gift cards in your store.

http

GET /api/external/v1/gift-cards/statistics

Example Request

bash

curl -X GET "https://yourstore.pixlpay.net/api/external/v1/gift-cards/statistics" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Response

json

{
  "success": true,
  "data": {
    "total_issued": 150,
    "total_active": 85,
    "total_depleted": 52,
    "total_revoked": 13,
    "total_issued_value": "7500.00",
    "total_remaining_balance": "2450.00",
    "total_redeemed_value": "5050.00"
  }
}

Resend Gift Card Email

Resend the gift card email to the recipient.

http

POST /api/external/v1/gift-cards/{id}/resend-email

Example Request

bash

curl -X POST "https://yourstore.pixlpay.net/api/external/v1/gift-cards/1/resend-email" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Response

json

{
  "success": true,
  "message": "Gift card email sent successfully"
}

Gift Card Object

Field	Type	Description
`id`	integer	Unique identifier
`code`	string	Gift card code (format: XXXX-XXXX-XXXX-XXXX)
`initial_balance`	string	Original balance when purchased
`balance`	string	Current remaining balance
`currency`	string	Currency code (USD, EUR, GBP, etc.)
`status`	string	`active`, `depleted`, or `revoked`
`recipient_email`	string	Recipient email address
`recipient_name`	string	Recipient name
`personal_message`	string	Optional message from purchaser
`product`	object	Product this gift card was purchased as
`order`	object	Order that created this gift card
`redemptions`	array	History of redemptions
`purchased_at`	string	ISO 8601 timestamp of purchase
`first_used_at`	string	ISO 8601 timestamp of first use
`last_used_at`	string	ISO 8601 timestamp of last use
`expires_at`	string	ISO 8601 expiration timestamp (null = never)
`created_at`	string	ISO 8601 creation timestamp

Gift Card Redemption Object

Field	Type	Description
`id`	integer	Unique identifier
`amount`	string	Amount redeemed
`balance_before`	string	Balance before redemption
`balance_after`	string	Balance after redemption
`order`	object	Order that used this redemption
`created_at`	string	ISO 8601 timestamp

Gift Card Statuses

Status	Description
`active`	Gift card is valid and has remaining balance
`depleted`	Gift card balance has been fully used
`revoked`	Gift card has been manually deactivated

Errors

Status	Error	Description
400	Bad Request	Gift card already revoked or invalid operation
400	No Recipient	No recipient email set for resend
401	Unauthorized	Invalid or missing token
403	Forbidden	Token lacks `gift_cards:read` or `gift_cards:write` scope
404	Not Found	Gift card not found or invalid code
422	Unprocessable	Validation failed (invalid amount, expired card)

Required Scopes

Endpoint	Required Scope
List, Get, Validate, Statistics	`gift_cards:read`
Redeem, Update, Revoke, Resend Email	`gift_cards:write`

Gift Cards API ​

List Gift Cards ​

Query Parameters ​

Example Request ​

Response ​

Get Single Gift Card ​

Example Request ​

Response ​

Check Gift Card Balance ​

Request Body ​

Example Request ​

Success Response ​

Invalid Card Response ​

Redeem Gift Card ​

Request Body ​

Example Request ​

Response ​

Update Gift Card ​

Request Body ​

Example Request ​

Response ​

Revoke Gift Card ​

Example Request ​

Response ​

Get Gift Card Statistics ​

Example Request ​

Response ​

Resend Gift Card Email ​

Example Request ​

Response ​

Gift Card Object ​

Gift Card Redemption Object ​

Gift Card Statuses ​

Errors ​

Required Scopes ​

Gift Cards API

List Gift Cards

Query Parameters

Example Request

Response

Get Single Gift Card

Example Request

Response

Check Gift Card Balance

Request Body

Example Request

Success Response

Invalid Card Response

Redeem Gift Card

Request Body

Example Request

Response

Update Gift Card

Request Body

Example Request

Response

Revoke Gift Card

Example Request

Response

Get Gift Card Statistics

Example Request

Response

Resend Gift Card Email

Example Request

Response

Gift Card Object

Gift Card Redemption Object

Gift Card Statuses

Errors

Required Scopes