Allomancy
Developer API

Gift cards

List a customer's gift cards, read one, update it, or disable it.

The gift cards endpoints read and manage individual gift cards. Field shapes are on the Object reference page.

There is no store-wide gift-card list and no standalone create endpoint. A gift card is created by granting it to a customer with POST /v1/customers/{identifier}/actions/grant-gift-card; the endpoints here read and manage a gift card once it exists.

List a customer's gift cards

GET /v1/customers/{identifier}/giftcards

Returns a cursor-paginated list of one customer's gift cards. Scope: giftcards:read. The {identifier} is the customer's Second Life username or avatar UUID. Query parameters limit and cursor are optional; see Pagination and errors.

You can also narrow the list with optional filters:

  • active (boolean): return only active, or only inactive, gift cards.
  • redeemed (boolean): return only redeemed, or only unredeemed, gift cards.

Filters are optional and combine with AND.

curl --fail-with-body "https://integrations.allomancy.net/v1/customers/resident.username/giftcards?limit=50" \
  -H "X-API-Key: allo_live_8Kd2...zQ.Hk9...4w"
import requests

response = requests.get(
    "https://integrations.allomancy.net/v1/customers/resident.username/giftcards",
    headers={"X-API-Key": "allo_live_8Kd2...zQ.Hk9...4w"},
    params={"limit": 50},
)
print(response.json())
const response = await fetch(
  "https://integrations.allomancy.net/v1/customers/resident.username/giftcards?limit=50",
  {
    headers: { "X-API-Key": "allo_live_8Kd2...zQ.Hk9...4w" },
  },
);
console.log(await response.json());
<?php
$ch = curl_init("https://integrations.allomancy.net/v1/customers/resident.username/giftcards?limit=50");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-API-Key: allo_live_8Kd2...zQ.Hk9...4w"]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
{
  "data": [
    {
      "id": "f1a2b3c4-5d6e-4f70-8a9b-0c1d2e3f4a5b",
      "ownerUuid": "c7d8e9f0-1a2b-4c3d-9e4f-5a6b7c8d9e0f",
      "ownerUsername": "resident.username",
      "credit": 500,
      "active": true,
      "redeemed": false,
      "transfer": false,
      "texture": null,
      "purchased": false
    }
  ],
  "pagination": { "nextCursor": null, "previousCursor": null, "limit": 50 }
}

Each row is a GiftCardResponse. Status: 200, 400, or 404 if the customer cannot be resolved.

Get a gift card

GET /v1/giftcards/{id}

Returns one gift card by its UUID. Scope: giftcards:read.

curl --fail-with-body https://integrations.allomancy.net/v1/giftcards/f1a2b3c4-5d6e-4f70-8a9b-0c1d2e3f4a5b \
  -H "X-API-Key: allo_live_8Kd2...zQ.Hk9...4w"
import requests

response = requests.get(
    "https://integrations.allomancy.net/v1/giftcards/f1a2b3c4-5d6e-4f70-8a9b-0c1d2e3f4a5b",
    headers={"X-API-Key": "allo_live_8Kd2...zQ.Hk9...4w"},
)
print(response.json())
const response = await fetch(
  "https://integrations.allomancy.net/v1/giftcards/f1a2b3c4-5d6e-4f70-8a9b-0c1d2e3f4a5b",
  {
    headers: { "X-API-Key": "allo_live_8Kd2...zQ.Hk9...4w" },
  },
);
console.log(await response.json());
<?php
$ch = curl_init("https://integrations.allomancy.net/v1/giftcards/f1a2b3c4-5d6e-4f70-8a9b-0c1d2e3f4a5b");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-API-Key: allo_live_8Kd2...zQ.Hk9...4w"]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

The response is a GiftCardResponse. Status: 200, or 404 if no gift card matches.

Update a gift card

PUT /v1/giftcards/{id}

Updates a gift card's balance, texture, transfer flag, and active state. Scope: giftcards:write. The body is an UpdateGiftCardRequest, and it replaces those fields: an omitted field is set to its default rather than left at its previous value.

curl --fail-with-body https://integrations.allomancy.net/v1/giftcards/f1a2b3c4-5d6e-4f70-8a9b-0c1d2e3f4a5b \
  -X PUT \
  -H "X-API-Key: allo_live_8Kd2...zQ.Hk9...4w" \
  -H "Content-Type: application/json" \
  -d '{ "credit": 600, "texture": null, "transfer": true, "active": true }'
import requests

response = requests.put(
    "https://integrations.allomancy.net/v1/giftcards/f1a2b3c4-5d6e-4f70-8a9b-0c1d2e3f4a5b",
    headers={"X-API-Key": "allo_live_8Kd2...zQ.Hk9...4w"},
    json={"credit": 600, "texture": None, "transfer": True, "active": True},
)
print(response.json())
const response = await fetch(
  "https://integrations.allomancy.net/v1/giftcards/f1a2b3c4-5d6e-4f70-8a9b-0c1d2e3f4a5b",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "allo_live_8Kd2...zQ.Hk9...4w",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      credit: 600,
      texture: null,
      transfer: true,
      active: true,
    }),
  },
);
console.log(await response.json());
<?php
$ch = curl_init("https://integrations.allomancy.net/v1/giftcards/f1a2b3c4-5d6e-4f70-8a9b-0c1d2e3f4a5b");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "X-API-Key: allo_live_8Kd2...zQ.Hk9...4w",
    "Content-Type: application/json",
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    "credit" => 600,
    "texture" => null,
    "transfer" => true,
    "active" => true,
]));
$response = curl_exec($ch);
curl_close($ch);
echo $response;

The response is the updated GiftCardResponse. Status: 200, 400, or 404.

Disable a gift card

POST /v1/giftcards/{id}/actions/disable

Disables a gift card. Scope: giftcards:write. The action takes no request body.

curl --fail-with-body https://integrations.allomancy.net/v1/giftcards/f1a2b3c4-5d6e-4f70-8a9b-0c1d2e3f4a5b/actions/disable \
  -X POST \
  -H "X-API-Key: allo_live_8Kd2...zQ.Hk9...4w"
import requests

response = requests.post(
    "https://integrations.allomancy.net/v1/giftcards/f1a2b3c4-5d6e-4f70-8a9b-0c1d2e3f4a5b/actions/disable",
    headers={"X-API-Key": "allo_live_8Kd2...zQ.Hk9...4w"},
)
print(response.json())
const response = await fetch(
  "https://integrations.allomancy.net/v1/giftcards/f1a2b3c4-5d6e-4f70-8a9b-0c1d2e3f4a5b/actions/disable",
  {
    method: "POST",
    headers: { "X-API-Key": "allo_live_8Kd2...zQ.Hk9...4w" },
  },
);
console.log(await response.json());
<?php
$ch = curl_init("https://integrations.allomancy.net/v1/giftcards/f1a2b3c4-5d6e-4f70-8a9b-0c1d2e3f4a5b/actions/disable");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-API-Key: allo_live_8Kd2...zQ.Hk9...4w"]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

The response is the updated GiftCardResponse, now with active set to false. Status: 200, 400, or 404.

Customers

Grant a gift card to a customer, the only way to create one through the API.

Object reference

Field-by-field schemas for the gift card request and response bodies.

Pagination and errors

The cursor envelope and the problem+json error format.

Coupons

List, read, create, and update store coupons.

Store and loyalty

Read store details and the store's loyalty tiers.

On this page

List a customer's gift cardsGet a gift cardUpdate a gift cardDisable a gift cardRelated pages