Skip to content

Extend Gift Card Expiry
Alpha

Request

Push an active gift card's expiry date further out.

The new expiry must be later than the gift card's current expiry — this action only extends validity, it never shortens it. Only gift cards with status ACTIVE can be extended; a gift card that has already expired, been fully spent, or been voided is final.

Re-sending the gift card's current expiry date has no effect and returns the gift card unchanged, so a retried request is safe.

The change is recorded on the gift card's history and is visible to the company in Understory.

Security
OAuth2(Required scopes: gift-card.write)
Path
giftCardIdstringrequired

The unique identifier of the gift card.

Bodyapplication/jsonrequired
expires_atstring, (date-time)required

The new expiry timestamp. Must be later than the gift card's current expiry.

reasonstring, <= 500 characters

Why the gift card was extended. Shown alongside the change in the gift card's history.

curl -i -X POST \
  'https://api.understory.io/v1/gift-cards/{giftCardId}/extend-expiry' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "expires_at": "2019-08-24T14:15:22Z",
    "reason": "string"
  }'

Responses

OK

Bodyapplication/json
idstringrequired

The unique identifier of the gift card.

statusstring(GiftCardStatus)required

The current status of the gift card.

Enum:"ACTIVE""SPENT""EXPIRED""VOIDED""UNKNOWN"
currencystringrequired

The ISO 4217 currency code.

Example:"EUR"
initial_valueobject(Amount)required

The original value of the gift card.

balanceobject(Amount)required

The remaining balance of the gift card.

expires_atstring, (date-time)required

Timestamp of when the gift card expires.

created_atstring, (date-time)required

Timestamp of when the gift card was created.

updated_atstring, (date-time)required

Timestamp of the most recent change to this gift card.

order_idstring

ID of the purchase order that created this gift card.

sourcestring

Origin system (e.g. understory, truestory, fun-tours.com).

customerobject(PrivateCustomer)

The buyer/recipient associated with the gift card.

metadataobject(Metadata)

Key-value metadata.

Example:
{
  "key1": "value1",
  "key2": "value2"
}
Response
{
  "id": "string",
  "status": "ACTIVE",
  "order_id": "string",
  "currency": "EUR",
  "initial_value": {
    "currency": "EUR",
    "value": 2500,
    "exponent": 2
  },
  "balance": {
    "currency": "EUR",
    "value": 2500,
    "exponent": 2
  },
  "expires_at": "2019-08-24T14:15:22Z",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "source": "string",
  "customer": {
    "customer_type": "PRIVATE",
    "full_name": "string",
    "email": "user@example.com",
    "phone": "string",
    "address": { … }
  },
  "metadata": {
    "key1": "value1",
    "key2": "value2"
  }
}