TrellisDevelopers
API reference

Gift Cards

List gift cards

GET
/gift-card

Commerce7-style gift card records for retail and restaurant credit workflows. The API supports basic search by query string and full record retrieval.

Query Parameters

q?string
limit?integer
Range1 <= value <= 200

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

  • "hexclave"
x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Response Body

application/json

curl -X GET "https://example.com/gift-card" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123"
{  "giftCards": [    {      "id": "string",      "title": "string",      "type": "Virtual",      "status": "Inactive",      "giftCardNumber": 1,      "code": "string",      "initialAmount": 0,      "currentBalance": 0,      "valueAccountId": "string",      "originLocationId": "string",      "source": "sale",      "recipientName": "string",      "recipientPhone": "string",      "purchaserEmail": "string",      "purchaserPhone": "string",      "deliveryStatus": "not_applicable",      "deliveryScheduledAt": "2019-08-24T14:15:22Z",      "deliveryChannel": "email",      "deliveryDestination": "string",      "deliveryLastAttemptAt": "2019-08-24T14:15:22Z",      "deliveryFailureReason": "string",      "deliveryClaimedAt": "2019-08-24T14:15:22Z",      "mergedIntoGiftCardId": "string",      "expiryDate": "2019-08-24T14:15:22Z",      "recipientEmail": "string",      "fromName": "string",      "giftMessage": "string",      "notes": "string",      "productId": "string",      "purchasedOnOrderId": "string",      "purchasedOnOrderNumber": 0,      "purchasedOnOrderLineId": "string",      "notifyPurchaserWhenOpened": true,      "openedAt": "2019-08-24T14:15:22Z",      "customerId": "string",      "createdAt": "2019-08-24T14:15:22Z",      "updatedAt": "2019-08-24T14:15:22Z",      "customer": null    }  ],  "total": 0}

Create a gift card

POST
/gift-card

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

  • "hexclave"
x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

curl -X POST "https://example.com/gift-card" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123" \  -H "Content-Type: application/json" \  -d '{    "title": "string",    "type": "Virtual",    "code": "string",    "initialAmount": 0  }'
{  "id": "string",  "title": "string",  "type": "Virtual",  "status": "Inactive",  "giftCardNumber": 1,  "code": "string",  "initialAmount": 0,  "currentBalance": 0,  "valueAccountId": "string",  "originLocationId": "string",  "source": "sale",  "recipientName": "string",  "recipientPhone": "string",  "purchaserEmail": "string",  "purchaserPhone": "string",  "deliveryStatus": "not_applicable",  "deliveryScheduledAt": "2019-08-24T14:15:22Z",  "deliveryChannel": "email",  "deliveryDestination": "string",  "deliveryLastAttemptAt": "2019-08-24T14:15:22Z",  "deliveryFailureReason": "string",  "deliveryClaimedAt": "2019-08-24T14:15:22Z",  "mergedIntoGiftCardId": "string",  "expiryDate": "2019-08-24T14:15:22Z",  "recipientEmail": "string",  "fromName": "string",  "giftMessage": "string",  "notes": "string",  "productId": "string",  "purchasedOnOrderId": "string",  "purchasedOnOrderNumber": 0,  "purchasedOnOrderLineId": "string",  "notifyPurchaserWhenOpened": true,  "openedAt": "2019-08-24T14:15:22Z",  "customerId": "string",  "createdAt": "2019-08-24T14:15:22Z",  "updatedAt": "2019-08-24T14:15:22Z",  "customer": null}

Look up a gift card by its exact number or swipe value

GET
/gift-card/lookup

Query Parameters

code*string
Length1 <= length

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

  • "hexclave"
x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Response Body

application/json

curl -X GET "https://example.com/gift-card/lookup?code=string" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123"
{  "id": "string",  "title": "string",  "type": "Virtual",  "status": "Inactive",  "giftCardNumber": 1,  "code": "string",  "initialAmount": 0,  "currentBalance": 0,  "valueAccountId": "string",  "originLocationId": "string",  "source": "sale",  "recipientName": "string",  "recipientPhone": "string",  "purchaserEmail": "string",  "purchaserPhone": "string",  "deliveryStatus": "not_applicable",  "deliveryScheduledAt": "2019-08-24T14:15:22Z",  "deliveryChannel": "email",  "deliveryDestination": "string",  "deliveryLastAttemptAt": "2019-08-24T14:15:22Z",  "deliveryFailureReason": "string",  "deliveryClaimedAt": "2019-08-24T14:15:22Z",  "mergedIntoGiftCardId": "string",  "expiryDate": "2019-08-24T14:15:22Z",  "recipientEmail": "string",  "fromName": "string",  "giftMessage": "string",  "notes": "string",  "productId": "string",  "purchasedOnOrderId": "string",  "purchasedOnOrderNumber": 0,  "purchasedOnOrderLineId": "string",  "notifyPurchaserWhenOpened": true,  "openedAt": "2019-08-24T14:15:22Z",  "customerId": "string",  "createdAt": "2019-08-24T14:15:22Z",  "updatedAt": "2019-08-24T14:15:22Z",  "customer": null}

Read gift-card sales, redemption, and cash-out settings

GET
/gift-card/settings

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

  • "hexclave"
x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Response Body

application/json

curl -X GET "https://example.com/gift-card/settings" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123"
{  "enabled": true,  "tipsEnabled": true,  "cashOutEnabled": true,  "cashOutThreshold": 0,  "cashOutPermission": "manager",  "allowDiscounts": true,  "allowOnlineRedemption": true,  "sharedAcrossLocations": true,  "minimumPurchaseAmount": 0,  "digitalPurchaseLimit": 0,  "physicalPurchaseLimit": 0}

Update gift-card sales, redemption, and cash-out settings

PUT
/gift-card/settings

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

  • "hexclave"
x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

curl -X PUT "https://example.com/gift-card/settings" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123" \  -H "Content-Type: application/json" \  -d '{    "enabled": true,    "tipsEnabled": true,    "cashOutEnabled": true,    "cashOutThreshold": 0,    "cashOutPermission": "manager",    "allowDiscounts": true,    "allowOnlineRedemption": true,    "sharedAcrossLocations": true,    "minimumPurchaseAmount": 0,    "digitalPurchaseLimit": 0,    "physicalPurchaseLimit": 0  }'
{  "enabled": true,  "tipsEnabled": true,  "cashOutEnabled": true,  "cashOutThreshold": 0,  "cashOutPermission": "manager",  "allowDiscounts": true,  "allowOnlineRedemption": true,  "sharedAcrossLocations": true,  "minimumPurchaseAmount": 0,  "digitalPurchaseLimit": 0,  "physicalPurchaseLimit": 0}

Report starting and ending gift-card liability and period activity

GET
/gift-card/reports/liability

Query Parameters

from*string
Length10 <= length
to*string
Length10 <= length
locationId?string

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

  • "hexclave"
x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Response Body

application/json

curl -X GET "https://example.com/gift-card/reports/liability?from=stringstri&to=stringstri" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123"
{  "range": {    "from": "string",    "to": "string",    "locationId": "string"  },  "startingLiability": 0,  "addedValue": 0,  "voidedAddedValue": 0,  "adjustments": 0,  "redemptions": 0,  "voidedRedemptions": 0,  "cashOuts": 0,  "netLiabilityChange": 0,  "endingLiability": 0,  "cardCounts": {    "physical": 0,    "digital": 0,    "imported": 0,    "inactive": 0,    "disabled": 0  }}

List gift-card sales, redemptions, voids, cash-outs, and adjustments

GET
/gift-card/reports/transactions

Query Parameters

from*string
Length10 <= length
to*string
Length10 <= length
locationId?string
q?string
limit?integer
Range1 <= value <= 500

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

  • "hexclave"
x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Response Body

application/json

curl -X GET "https://example.com/gift-card/reports/transactions?from=stringstri&to=stringstri" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123"
{  "transactions": [    {      "id": "string",      "giftCardId": "string",      "accountId": "string",      "cardNumber": "string",      "cardLast4": "string",      "cardType": "string",      "entryType": "string",      "amountDelta": 0,      "balanceAfter": 0,      "orderId": "string",      "paymentIntentId": "string",      "reason": "string",      "originLocationId": "string",      "transactionLocationId": "string",      "occurredAt": "2019-08-24T14:15:22Z"    }  ]}

Report cross-location gift-card settlement obligations

GET
/gift-card/reports/liability-pooling

Query Parameters

from*string
Length10 <= length
to*string
Length10 <= length
locationId?string

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

  • "hexclave"
x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Response Body

application/json

curl -X GET "https://example.com/gift-card/reports/liability-pooling?from=stringstri&to=stringstri" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123"
{  "settlements": [    {      "originLocationId": "string",      "redemptionLocationId": "string",      "amountOwed": 0,      "redemptionCount": 1    }  ]}

List failed digital gift-card delivery attempts

GET
/gift-card/reports/failed-deliveries

Query Parameters

from*string
Length10 <= length
to*string
Length10 <= length
locationId?string

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

  • "hexclave"
x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Response Body

application/json

curl -X GET "https://example.com/gift-card/reports/failed-deliveries?from=stringstri&to=stringstri" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123"
{  "deliveries": [    {      "id": "string",      "giftCardId": "string",      "channel": "email",      "destination": "string",      "provider": "string",      "failureReason": "string",      "attemptedAt": "2019-08-24T14:15:22Z",      "cardAmount": 0,      "recipientName": "string",      "fromName": "string",      "originLocationId": "string"    }  ]}

Transfer or combine two gift-card balances

POST
/gift-card/transfer

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

  • "hexclave"
x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

curl -X POST "https://example.com/gift-card/transfer" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123" \  -H "Content-Type: application/json" \  -d '{    "sourceCode": "string",    "targetCode": "string",    "mode": "transfer_and_disable",    "idempotencyKey": "stringst"  }'
{  "source": {    "id": "string",    "title": "string",    "type": "Virtual",    "status": "Inactive",    "giftCardNumber": 1,    "code": "string",    "initialAmount": 0,    "currentBalance": 0,    "valueAccountId": "string",    "originLocationId": "string",    "source": "sale",    "recipientName": "string",    "recipientPhone": "string",    "purchaserEmail": "string",    "purchaserPhone": "string",    "deliveryStatus": "not_applicable",    "deliveryScheduledAt": "2019-08-24T14:15:22Z",    "deliveryChannel": "email",    "deliveryDestination": "string",    "deliveryLastAttemptAt": "2019-08-24T14:15:22Z",    "deliveryFailureReason": "string",    "deliveryClaimedAt": "2019-08-24T14:15:22Z",    "mergedIntoGiftCardId": "string",    "expiryDate": "2019-08-24T14:15:22Z",    "recipientEmail": "string",    "fromName": "string",    "giftMessage": "string",    "notes": "string",    "productId": "string",    "purchasedOnOrderId": "string",    "purchasedOnOrderNumber": 0,    "purchasedOnOrderLineId": "string",    "notifyPurchaserWhenOpened": true,    "openedAt": "2019-08-24T14:15:22Z",    "customerId": "string",    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z",    "customer": null  },  "target": {    "id": "string",    "title": "string",    "type": "Virtual",    "status": "Inactive",    "giftCardNumber": 1,    "code": "string",    "initialAmount": 0,    "currentBalance": 0,    "valueAccountId": "string",    "originLocationId": "string",    "source": "sale",    "recipientName": "string",    "recipientPhone": "string",    "purchaserEmail": "string",    "purchaserPhone": "string",    "deliveryStatus": "not_applicable",    "deliveryScheduledAt": "2019-08-24T14:15:22Z",    "deliveryChannel": "email",    "deliveryDestination": "string",    "deliveryLastAttemptAt": "2019-08-24T14:15:22Z",    "deliveryFailureReason": "string",    "deliveryClaimedAt": "2019-08-24T14:15:22Z",    "mergedIntoGiftCardId": "string",    "expiryDate": "2019-08-24T14:15:22Z",    "recipientEmail": "string",    "fromName": "string",    "giftMessage": "string",    "notes": "string",    "productId": "string",    "purchasedOnOrderId": "string",    "purchasedOnOrderNumber": 0,    "purchasedOnOrderLineId": "string",    "notifyPurchaserWhenOpened": true,    "openedAt": "2019-08-24T14:15:22Z",    "customerId": "string",    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z",    "customer": null  }}

Import active or inactive gift-card inventory and liability

POST
/gift-card/import

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

  • "hexclave"
x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

curl -X POST "https://example.com/gift-card/import" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123" \  -H "Content-Type: application/json" \  -d '{    "records": [      {        "code": "string",        "balance": 0      }    ]  }'
{  "imported": 1,  "giftCards": [    {      "id": "string",      "title": "string",      "type": "Virtual",      "status": "Inactive",      "giftCardNumber": 1,      "code": "string",      "initialAmount": 0,      "currentBalance": 0,      "valueAccountId": "string",      "originLocationId": "string",      "source": "sale",      "recipientName": "string",      "recipientPhone": "string",      "purchaserEmail": "string",      "purchaserPhone": "string",      "deliveryStatus": "not_applicable",      "deliveryScheduledAt": "2019-08-24T14:15:22Z",      "deliveryChannel": "email",      "deliveryDestination": "string",      "deliveryLastAttemptAt": "2019-08-24T14:15:22Z",      "deliveryFailureReason": "string",      "deliveryClaimedAt": "2019-08-24T14:15:22Z",      "mergedIntoGiftCardId": "string",      "expiryDate": "2019-08-24T14:15:22Z",      "recipientEmail": "string",      "fromName": "string",      "giftMessage": "string",      "notes": "string",      "productId": "string",      "purchasedOnOrderId": "string",      "purchasedOnOrderNumber": 0,      "purchasedOnOrderLineId": "string",      "notifyPurchaserWhenOpened": true,      "openedAt": "2019-08-24T14:15:22Z",      "customerId": "string",      "createdAt": "2019-08-24T14:15:22Z",      "updatedAt": "2019-08-24T14:15:22Z",      "customer": null    }  ]}

List gift-card balance activity

GET
/gift-card/{id}/transactions

Path Parameters

id*string
Length1 <= length

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

  • "hexclave"
x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Response Body

application/json

curl -X GET "https://example.com/gift-card/string/transactions" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123"
{  "transactions": [    {      "id": "string",      "entryType": "issue",      "amountDelta": 0,      "orderId": "string",      "paymentIntentId": "string",      "sourceEntryId": "string",      "reason": "string",      "occurredAt": "2019-08-24T14:15:22Z",      "createdAt": "2019-08-24T14:15:22Z"    }  ]}

Post an idempotent gift-card balance transaction

POST
/gift-card/{id}/transactions

Path Parameters

id*string
Length1 <= length

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

  • "hexclave"
x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

curl -X POST "https://example.com/gift-card/string/transactions" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123" \  -H "Content-Type: application/json" \  -d '{    "entryType": "load",    "amountDelta": 0,    "idempotencyKey": "stringst"  }'
{  "giftCard": {    "id": "string",    "title": "string",    "type": "Virtual",    "status": "Inactive",    "giftCardNumber": 1,    "code": "string",    "initialAmount": 0,    "currentBalance": 0,    "valueAccountId": "string",    "originLocationId": "string",    "source": "sale",    "recipientName": "string",    "recipientPhone": "string",    "purchaserEmail": "string",    "purchaserPhone": "string",    "deliveryStatus": "not_applicable",    "deliveryScheduledAt": "2019-08-24T14:15:22Z",    "deliveryChannel": "email",    "deliveryDestination": "string",    "deliveryLastAttemptAt": "2019-08-24T14:15:22Z",    "deliveryFailureReason": "string",    "deliveryClaimedAt": "2019-08-24T14:15:22Z",    "mergedIntoGiftCardId": "string",    "expiryDate": "2019-08-24T14:15:22Z",    "recipientEmail": "string",    "fromName": "string",    "giftMessage": "string",    "notes": "string",    "productId": "string",    "purchasedOnOrderId": "string",    "purchasedOnOrderNumber": 0,    "purchasedOnOrderLineId": "string",    "notifyPurchaserWhenOpened": true,    "openedAt": "2019-08-24T14:15:22Z",    "customerId": "string",    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z",    "customer": null  },  "transactionId": "string",  "replayed": true}

Retrieve a gift card

GET
/gift-card/{id}

Path Parameters

id*string
Length1 <= length

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

  • "hexclave"
x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Response Body

application/json

curl -X GET "https://example.com/gift-card/string" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123"
{  "id": "string",  "title": "string",  "type": "Virtual",  "status": "Inactive",  "giftCardNumber": 1,  "code": "string",  "initialAmount": 0,  "currentBalance": 0,  "valueAccountId": "string",  "originLocationId": "string",  "source": "sale",  "recipientName": "string",  "recipientPhone": "string",  "purchaserEmail": "string",  "purchaserPhone": "string",  "deliveryStatus": "not_applicable",  "deliveryScheduledAt": "2019-08-24T14:15:22Z",  "deliveryChannel": "email",  "deliveryDestination": "string",  "deliveryLastAttemptAt": "2019-08-24T14:15:22Z",  "deliveryFailureReason": "string",  "deliveryClaimedAt": "2019-08-24T14:15:22Z",  "mergedIntoGiftCardId": "string",  "expiryDate": "2019-08-24T14:15:22Z",  "recipientEmail": "string",  "fromName": "string",  "giftMessage": "string",  "notes": "string",  "productId": "string",  "purchasedOnOrderId": "string",  "purchasedOnOrderNumber": 0,  "purchasedOnOrderLineId": "string",  "notifyPurchaserWhenOpened": true,  "openedAt": "2019-08-24T14:15:22Z",  "customerId": "string",  "createdAt": "2019-08-24T14:15:22Z",  "updatedAt": "2019-08-24T14:15:22Z",  "customer": null}

Delete a gift card

DELETE
/gift-card/{id}

Path Parameters

id*string
Length1 <= length

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

  • "hexclave"
x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Response Body

curl -X DELETE "https://example.com/gift-card/string" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123"
Empty

Update a gift card

PUT
/gift-card/{id}

Path Parameters

id*string
Length1 <= length

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

  • "hexclave"
x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

curl -X PUT "https://example.com/gift-card/string" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123" \  -H "Content-Type: application/json" \  -d '{}'
{  "id": "string",  "title": "string",  "type": "Virtual",  "status": "Inactive",  "giftCardNumber": 1,  "code": "string",  "initialAmount": 0,  "currentBalance": 0,  "valueAccountId": "string",  "originLocationId": "string",  "source": "sale",  "recipientName": "string",  "recipientPhone": "string",  "purchaserEmail": "string",  "purchaserPhone": "string",  "deliveryStatus": "not_applicable",  "deliveryScheduledAt": "2019-08-24T14:15:22Z",  "deliveryChannel": "email",  "deliveryDestination": "string",  "deliveryLastAttemptAt": "2019-08-24T14:15:22Z",  "deliveryFailureReason": "string",  "deliveryClaimedAt": "2019-08-24T14:15:22Z",  "mergedIntoGiftCardId": "string",  "expiryDate": "2019-08-24T14:15:22Z",  "recipientEmail": "string",  "fromName": "string",  "giftMessage": "string",  "notes": "string",  "productId": "string",  "purchasedOnOrderId": "string",  "purchasedOnOrderNumber": 0,  "purchasedOnOrderLineId": "string",  "notifyPurchaserWhenOpened": true,  "openedAt": "2019-08-24T14:15:22Z",  "customerId": "string",  "createdAt": "2019-08-24T14:15:22Z",  "updatedAt": "2019-08-24T14:15:22Z",  "customer": null}

Send or resend a digital gift card by email or SMS

POST
/gift-card/{id}/deliver

Path Parameters

id*string
Length1 <= length

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

  • "hexclave"
x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

curl -X POST "https://example.com/gift-card/string/deliver" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123" \  -H "Content-Type: application/json" \  -d '{}'
{  "giftCard": {    "id": "string",    "title": "string",    "type": "Virtual",    "status": "Inactive",    "giftCardNumber": 1,    "code": "string",    "initialAmount": 0,    "currentBalance": 0,    "valueAccountId": "string",    "originLocationId": "string",    "source": "sale",    "recipientName": "string",    "recipientPhone": "string",    "purchaserEmail": "string",    "purchaserPhone": "string",    "deliveryStatus": "not_applicable",    "deliveryScheduledAt": "2019-08-24T14:15:22Z",    "deliveryChannel": "email",    "deliveryDestination": "string",    "deliveryLastAttemptAt": "2019-08-24T14:15:22Z",    "deliveryFailureReason": "string",    "deliveryClaimedAt": "2019-08-24T14:15:22Z",    "mergedIntoGiftCardId": "string",    "expiryDate": "2019-08-24T14:15:22Z",    "recipientEmail": "string",    "fromName": "string",    "giftMessage": "string",    "notes": "string",    "productId": "string",    "purchasedOnOrderId": "string",    "purchasedOnOrderNumber": 0,    "purchasedOnOrderLineId": "string",    "notifyPurchaserWhenOpened": true,    "openedAt": "2019-08-24T14:15:22Z",    "customerId": "string",    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z",    "customer": null  },  "delivery": {    "channel": "email",    "destination": "string",    "provider": "string",    "providerMessageId": "string",    "status": "sent",    "failureReason": "string"  }}

Cash out a qualifying small gift-card balance from an open drawer

POST
/gift-card/{id}/cash-out

Path Parameters

id*string
Length1 <= length

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

  • "hexclave"
x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

curl -X POST "https://example.com/gift-card/string/cash-out" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123" \  -H "Content-Type: application/json" \  -d '{    "drawerId": "string",    "locationId": "string",    "idempotencyKey": "stringst"  }'
{  "giftCard": {    "id": "string",    "title": "string",    "type": "Virtual",    "status": "Inactive",    "giftCardNumber": 1,    "code": "string",    "initialAmount": 0,    "currentBalance": 0,    "valueAccountId": "string",    "originLocationId": "string",    "source": "sale",    "recipientName": "string",    "recipientPhone": "string",    "purchaserEmail": "string",    "purchaserPhone": "string",    "deliveryStatus": "not_applicable",    "deliveryScheduledAt": "2019-08-24T14:15:22Z",    "deliveryChannel": "email",    "deliveryDestination": "string",    "deliveryLastAttemptAt": "2019-08-24T14:15:22Z",    "deliveryFailureReason": "string",    "deliveryClaimedAt": "2019-08-24T14:15:22Z",    "mergedIntoGiftCardId": "string",    "expiryDate": "2019-08-24T14:15:22Z",    "recipientEmail": "string",    "fromName": "string",    "giftMessage": "string",    "notes": "string",    "productId": "string",    "purchasedOnOrderId": "string",    "purchasedOnOrderNumber": 0,    "purchasedOnOrderLineId": "string",    "notifyPurchaserWhenOpened": true,    "openedAt": "2019-08-24T14:15:22Z",    "customerId": "string",    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z",    "customer": null  },  "amount": 1,  "cashDrawerEntryId": "string"}

Fulfillment

Previous Page

Inventory

Next Page