Gift cards API

Gift cards with a code, a balance, an expiry date and a full history.

Module code gift_cards · 11 actions · 3 data models · 7 events. A key or token never does more here than the person behind it can; row-level security applies exactly as in the app. Scopes: gift_cards (everything), gift_cards:read (read only) or gift_cards:<capability>.

Resources

Lists take limit (up to 200), cursor, order (e.g. -created_at), fields and q; every other query parameter is a column filter: ?status=paid, ?total[gte]=100, ?id[in]=a,b, ?x=null.

Actions

gift_cards.add_note

Add a note — A line in the card’s history.

Needs gift_cards:write · changes data

• Canonical address: POST /api/v1/actions/gift_cards.add_note

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: gift_cards.updated

What it writes: gift_card_event (insert) — Records the note

curl -X POST https://app.getera.io/api/v1/gift_card_events/actions/add_note \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"id":"GIFT_CARD_ID","message":"Note"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "gift_cards.updated"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.giftCardEvents.addNote({
  id: "GIFT_CARD_ID",
  message: "Note"
})

era gift_card_events add_note \
  --id "GIFT_CARD_ID" \
  --message "Note"

{
  "name": "era__gift_cards__add_note",
  "arguments": {
    "id": "GIFT_CARD_ID",
    "message": "Note"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold gift_cards:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 gift_card_not_found · 429 slow down

gift_cards.bulk_issue

Issue gift cards in bulk — Many cards with the same balance and expiry, each with its own code.

Needs gift_cards:write · changes data

• Canonical address: POST /api/v1/actions/gift_cards.bulk_issue

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: gift_cards.issued

What it writes: gift_card (insert) — Issues the cards; gift_card_event (insert) — Records each issue

curl -X POST https://app.getera.io/api/v1/gift_cards/actions/bulk_issue \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"count":1,"amount":1}'

{
  "ok": true,
  "result": "…",
  "events": [
    "gift_cards.issued"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.giftCards.bulkIssue({
  count: 1,
  amount: 1
})

era gift_cards bulk_issue \
  --count 1 \
  --amount 1

{
  "name": "era__gift_cards__bulk_issue",
  "arguments": {
    "count": 1,
    "amount": 1
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold gift_cards:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 invalid_gift_card_count, gift_card_amount_not_positive, invalid_currency, gift_card_expiry_in_past · 429 slow down

gift_cards.expire_due

Deactivate expired cards — Closes every active card whose expiry date has passed.

Needs gift_cards:manage · changes data

• Canonical address: POST /api/v1/actions/gift_cards.expire_due

Input

Events it publishes: gift_cards.status_changed

What it writes: gift_card (update) — Deactivates it; gift_card_event (insert) — Records why

curl -X POST https://app.getera.io/api/v1/gift_card_events/actions/expire_due \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"asOf":"2026-11-02"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "gift_cards.status_changed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.giftCardEvents.expireDue({
  asOf: "2026-11-02"
})

era gift_card_events expire_due \
  --as-of "2026-11-02"

{
  "name": "era__gift_cards__expire_due",
  "arguments": {
    "asOf": "2026-11-02"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold gift_cards:manage · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 429 slow down

gift_cards.issue

Issue a gift card — A new card with a balance, a code and an optional expiry.

Needs gift_cards:write · changes data

• Canonical address: POST /api/v1/actions/gift_cards.issue

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: gift_cards.issued

What it writes: gift_card (insert) — Issues the card; gift_card_event (insert) — Records the issue

curl -X POST https://app.getera.io/api/v1/gift_cards/actions/issue \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"amount":1}'

{
  "ok": true,
  "result": "…",
  "events": [
    "gift_cards.issued"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.giftCards.issue({
  amount: 1
})

era gift_cards issue \
  --amount 1

{
  "name": "era__gift_cards__issue",
  "arguments": {
    "amount": 1
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold gift_cards:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 gift_card_amount_not_positive, invalid_currency, invalid_gift_card_code, gift_card_expiry_in_past, gift_card_code_taken · 429 slow down

gift_cards.redeem

Redeem a gift card — Spends from the balance. Idempotent: a retried redemption spends nothing twice.

Needs gift_cards:write · changes data

• Canonical address: POST /api/v1/actions/gift_cards.redeem

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: gift_cards.redeemed

What it writes: gift_card (update) — Lowers the balance; gift_card_event (insert) — Records the redemption

curl -X POST https://app.getera.io/api/v1/gift_cards/GIFT_CARD_ID/actions/redeem \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"amount":1,"currency":"Currency"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "gift_cards.redeemed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.giftCards.redeem("GIFT_CARD_ID", {
  amount: 1,
  currency: "Currency"
})

era gift_cards redeem GIFT_CARD_ID \
  --amount 1 \
  --currency "Currency"

{
  "name": "era__gift_cards__redeem",
  "arguments": {
    "giftCardId": "GIFT_CARD_ID",
    "amount": 1,
    "currency": "Currency"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold gift_cards:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 gift_card_not_found, gift_card_inactive, gift_card_expired, gift_card_currency_mismatch, gift_card_insufficient_balance · 429 slow down

gift_cards.refund

Refund onto a gift card — Puts money that was spent from the card back onto it.

Needs gift_cards:manage · removes or cannot be undone · asks a person to confirm when Era runs it

• Canonical address: POST /api/v1/actions/gift_cards.refund

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: gift_cards.refunded

What it writes: gift_card (update) — Raises the balance; gift_card_event (insert) — Records the refund

curl -X POST https://app.getera.io/api/v1/gift_cards/GIFT_CARD_ID/actions/refund \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"amount":1}'

{
  "ok": true,
  "result": "…",
  "events": [
    "gift_cards.refunded"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.giftCards.refund("GIFT_CARD_ID", {
  amount: 1
})

era gift_cards refund GIFT_CARD_ID \
  --amount 1

{
  "name": "era__gift_cards__refund",
  "arguments": {
    "id": "GIFT_CARD_ID",
    "amount": 1
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold gift_cards:manage · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 gift_card_not_found, gift_card_refund_exceeds_spent · 429 slow down

gift_cards.reset_balance

Correct the balance — Sets the balance by hand, with the reason on the card’s history.

Needs gift_cards:manage · reaches outside (sends, publishes or charges) · asks a person to confirm when Era runs it

• Canonical address: POST /api/v1/actions/gift_cards.reset_balance

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: gift_cards.updated

What it writes: gift_card (update) — Writes the balance; gift_card_event (insert) — Records the correction

curl -X POST https://app.getera.io/api/v1/gift_cards/GIFT_CARD_ID/actions/reset_balance \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"balance":1,"reason":"Reason"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "gift_cards.updated"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.giftCards.resetBalance("GIFT_CARD_ID", {
  balance: 1,
  reason: "Reason"
})

era gift_cards reset_balance GIFT_CARD_ID \
  --balance 1 \
  --reason "Reason"

{
  "name": "era__gift_cards__reset_balance",
  "arguments": {
    "id": "GIFT_CARD_ID",
    "balance": 1,
    "reason": "Reason"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold gift_cards:manage · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 gift_card_not_found, gift_card_amount_not_positive · 429 slow down

gift_cards.send

Send to customer — Emails the card through the notifications module; the card shows whether it went.

Needs gift_cards:write · reaches outside (sends, publishes or charges) · asks a person to confirm when Era runs it

• Canonical address: POST /api/v1/actions/gift_cards.send

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: gift_cards.send_requested

What it writes: gift_card_event (insert) — Records who it was sent to

curl -X POST https://app.getera.io/api/v1/gift_card_events/actions/send \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"id":"GIFT_CARD_ID"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "gift_cards.send_requested"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.giftCardEvents.send({
  id: "GIFT_CARD_ID"
})

era gift_card_events send \
  --id "GIFT_CARD_ID"

{
  "name": "era__gift_cards__send",
  "arguments": {
    "id": "GIFT_CARD_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold gift_cards:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 gift_card_not_found, gift_card_inactive, gift_card_expired, gift_card_recipient_missing · 429 slow down

gift_cards.set_active

Activate or deactivate — A deactivated card keeps its balance and cannot be spent.

Needs gift_cards:manage · changes data

• Canonical address: POST /api/v1/actions/gift_cards.set_active

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: gift_cards.status_changed

What it writes: gift_card (update) — Flips the card; gift_card_event (insert) — Records it

curl -X POST https://app.getera.io/api/v1/gift_cards/GIFT_CARD_ID/actions/set_active \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"active":true}'

{
  "ok": true,
  "result": "…",
  "events": [
    "gift_cards.status_changed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.giftCards.setActive("GIFT_CARD_ID", {
  active: true
})

era gift_cards set_active GIFT_CARD_ID \
  --active true

{
  "name": "era__gift_cards__set_active",
  "arguments": {
    "id": "GIFT_CARD_ID",
    "active": true
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold gift_cards:manage · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 gift_card_not_found · 429 slow down

gift_cards.set_expiry

Change the expiry — Moves or removes the expiry date.

Needs gift_cards:manage · changes data

• Canonical address: POST /api/v1/actions/gift_cards.set_expiry

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: gift_cards.updated

What it writes: gift_card (update) — Writes the expiry; gift_card_event (insert) — Records the change

curl -X POST https://app.getera.io/api/v1/gift_cards/GIFT_CARD_ID/actions/set_expiry \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"expiryDate":"2026-11-02"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "gift_cards.updated"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.giftCards.setExpiry("GIFT_CARD_ID", {
  expiryDate: "2026-11-02"
})

era gift_cards set_expiry GIFT_CARD_ID \
  --expiry-date "2026-11-02"

{
  "name": "era__gift_cards__set_expiry",
  "arguments": {
    "id": "GIFT_CARD_ID",
    "expiryDate": "2026-11-02"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold gift_cards:manage · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 gift_card_not_found, gift_card_expiry_in_past · 429 slow down

gift_cards.site_apply

Use a gift card (site) — A visitor puts a gift card on their checkout or payment link: the part of what is due its balance covers is held for fifteen minutes and paid from the card at the pay step. An empty code takes it off.

Needs gift_cards:write · changes data · Also callable from a published site (visitor)

• Canonical address: POST /api/v1/actions/gift_cards.site_apply

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: gift_cards.hold_changed

What it writes: gift_card_hold (insert) — Holds the part of the card that pays; gift_card_hold (update) — Lets go of an earlier hold on the same checkout

Errors: 401 no or expired credential · 403 the credential does not hold gift_cards:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 basket_not_found, pay_link_invalid, nothing_due, gift_card_not_found, gift_card_inactive, gift_card_expired, gift_card_currency_mismatch, gift_card_insufficient_balance · 429 slow down

Data models

GiftCardEvent

Table gift_card_event · Resource gift_card_events

• GET /api/v1/gift_card_events
• GET /api/v1/gift_card_events/{id}

Primary key: id

Checks:

• CHECK ((balance_after >= 0))
• CHECK ((currency ~ '^[A-Z]{3}$'::text))

GiftCardHold

Table gift_card_hold · Resource gift_card_holds

• GET /api/v1/gift_card_holds
• GET /api/v1/gift_card_holds/{id}

Primary key: id

Checks:

• CHECK ((amount > 0))
• CHECK ((NOT ((redeemed_at IS NOT NULL) AND (released_at IS NOT NULL))))

GiftCard

Table gift_card · Resource gift_cards

• GET /api/v1/gift_cards
• GET /api/v1/gift_cards/{id}

Primary key: id

Checks:

• CHECK (((length(code) >= 8) AND (length(code) <= 16)))
• CHECK ((currency ~ '^[A-Z]{3}$'::text))
• CHECK ((current_balance_amount >= 0))
• CHECK ((initial_balance_amount >= 0))

Events

Workflows and webhooks react to these events.