Gift Card Orders

The Gift Card Orders endpoint retrieves a list of all gift cards purchased by customers within the partner's platform. Partners can filter results by archive status to distinguish between active and historical orders, and use pagination parameters to manage large datasets efficiently. This endpoint is essential for displaying gift card purchase history and managing gift card lifecycle states.

Endpoint

GET /api/giftCards/orders

Authentication

Bearer token required. Obtain via:

POST https://api.banking.netevia.dev/api/auth/v2

Include in header: Authorization: Bearer {token}
Token lifetime: 10 minutes. Refresh via POST /api/auth/refresh.

When to use

Use this endpoint to display a customer's gift card purchase history in your application. It supports paginated retrieval of both active and archived gift card orders, making it suitable for building gift card management dashboards or transaction history views. This endpoint is relevant for business customers who earn and redeem rewards via gift cards.

Query Parameters

Response

200 OK

Returns an array of gift card order objects.

[
  {
    "id": "gc-order-001abc",
    "brandId": "brand-amazon-001",
    "brandName": "Amazon",
    "logoUrl": "https://cdn.example.com/logos/amazon.png",
    "url": "https://www.amazon.com/gc/redeem?claimCode=XXXX-XXXX-XXXX",
    "currency": "USD",
    "faceAmount": 5000,
    "amount": 4750,
    "discount": 0.05,
    "expirationDate": "2027-06-08T00:00:00Z",
    "createdDate": "2026-06-08T14:23:11Z",
    "cancelDate": null,
    "issueTransactionId": "txn-issue-7890xyz",
    "cancelTransactionId": null,
    "status": "Issued",
    "userName": "Jane Smith",
    "userId": 10042
  },
  {
    "id": "gc-order-002def",
    "brandId": "brand-target-002",
    "brandName": "Target",
    "logoUrl": "https://cdn.example.com/logos/target.png",
    "url": "https://www.target.com/gc/redeem?code=XXXX-XXXX-XXXX",
    "currency": "USD",
    "faceAmount": 2500,
    "amount": 2500,
    "discount": 0.0,
    "expirationDate": null,
    "createdDate": "2026-05-15T09:10:00Z",
    "cancelDate": "2026-05-20T11:00:00Z",
    "issueTransactionId": "txn-issue-1122aab",
    "cancelTransactionId": "txn-cancel-3344ccd",
    "status": "Canceled",
    "userName": "Jane Smith",
    "userId": 10042
  }
]

Error Codes

Common Mistakes

• Omitting the Authorization header or providing an expired token will result in a 401 error; ensure the token is refreshed every 10 minutes.
• Setting archive: false (the default) will not return canceled or expired gift cards — set archive: true to retrieve historical orders.
• The faceAmount and amount fields are returned in the smallest currency unit (cents for USD); divide by 100 to display dollar amounts.
• When paginating, increment skip by the value of limit for each subsequent page (e.g., first page: skip=0&limit=10, second page: skip=10&limit=10).
• The status field is an enum with only two values ("Issued" or "Canceled"); do not assume other status strings are valid.

Related Endpoints

• POST /api/giftCards/order — Place a new gift card order for a customer
• GET /api/giftCards/brands — Retrieve available gift card brands and denominations
• POST /api/rewards/redeem — Redeem rewards points toward a gift card purchase

Example

Retrieve the first 10 active (non-archived) gift card orders:

curl -X GET "https://api.banking.netevia.dev/api/giftCards/orders?archive=false&skip=0&limit=10" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"

Retrieve the next page (records 11–20):

curl -X GET "https://api.banking.netevia.dev/api/giftCards/orders?archive=false&skip=10&limit=10" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"

Retrieve archived (canceled/expired) gift card orders:

curl -X GET "https://api.banking.netevia.dev/api/giftCards/orders?archive=true&skip=0&limit=50" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"