Allomancy
Developer API

Products

List, read, create, update, and deliver products in a store.

The products endpoints read and manage a store's catalog and deliver a product to a resident inworld. Every product field is described on the Object reference page.

List products

GET /v1/products

Returns a cursor-paginated list of the store's active products. Scope: products:read.

Query parameters: limit and cursor, both optional. See Pagination and errors for the envelope and cursor rules.

You can also narrow the list with optional filters:

  • listed (boolean): return only listed, or only unlisted, products.
  • bloggable (boolean): return only bloggable, or only non-bloggable, products.
  • category (UUID): return only products in a category. Pass a category's UUID from List categories, not its name.
  • search (string): return only products whose name or description contains the term. The match is case-insensitive and partial, and a product matches if the term appears in either field, so a product with no description is still found by its name. A % or _ in the term matches that character literally rather than as a wildcard, so searching 50% finds products whose text contains 50%, not 500. An omitted, empty, or whitespace-only term applies no search filter.

Filters are optional and combine with AND, so sending several narrows the list to products matching all of them. For example, GET /v1/products?search=crimson&listed=true&limit=50 returns up to 50 listed products whose name or description contains crimson.

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

response = requests.get(
    "https://integrations.allomancy.net/v1/products",
    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/products?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/products?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": "3a1f0c9b-7d2e-4c84-9a6f-1b5e8d0c2a37",
      "name": "Fancy hat",
      "price": 250,
      "activePrice": 225,
      "image": "0d4f8a11-9b2c-4e6d-8f1a-3c7b5d9e2f04",
      "bloggable": true,
      "active": true,
      "blockCredits": false,
      "item": "Fancy hat",
      "limited": false,
      "availableAmount": 0,
      "permissions": { "copy": true, "modify": false, "transfer": true },
      "discount": { "value": 10, "type": 0, "startDate": "2026-04-01T00:00:00Z", "endDate": "2026-05-01T00:00:00Z" },
      "description": "A very fancy hat.",
      "demoId": null,
      "mpListing": 4242,
      "profitShares": [
        { "userUuid": "b7c8d9e0-1f2a-4b3c-8d4e-5f6a7b8c9d0e", "percent": 10 }
      ]
    }
  ],
  "pagination": {
    "nextCursor": "Tjo3ZDJlNGM4NC05YTZmLTFiNWU4ZDBjMmEzNw",
    "previousCursor": null,
    "limit": 50
  }
}

Each row is a ProductResponse. Status: 200. A bad pagination parameter returns 400.

Get a product

GET /v1/products/{id}

Returns one product by its UUID. Scope: products:read.

Path parameter: id, the product's UUID.

curl --fail-with-body https://integrations.allomancy.net/v1/products/3a1f0c9b-7d2e-4c84-9a6f-1b5e8d0c2a37 \
  -H "X-API-Key: allo_live_8Kd2...zQ.Hk9...4w"
import requests

response = requests.get(
    "https://integrations.allomancy.net/v1/products/3a1f0c9b-7d2e-4c84-9a6f-1b5e8d0c2a37",
    headers={"X-API-Key": "allo_live_8Kd2...zQ.Hk9...4w"},
)
print(response.json())
const response = await fetch(
  "https://integrations.allomancy.net/v1/products/3a1f0c9b-7d2e-4c84-9a6f-1b5e8d0c2a37",
  {
    headers: { "X-API-Key": "allo_live_8Kd2...zQ.Hk9...4w" },
  },
);
console.log(await response.json());
<?php
$ch = curl_init("https://integrations.allomancy.net/v1/products/3a1f0c9b-7d2e-4c84-9a6f-1b5e8d0c2a37");
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;
{
  "id": "3a1f0c9b-7d2e-4c84-9a6f-1b5e8d0c2a37",
  "name": "Fancy hat",
  "price": 250,
  "activePrice": 225,
  "image": "0d4f8a11-9b2c-4e6d-8f1a-3c7b5d9e2f04",
  "bloggable": true,
  "active": true,
  "blockCredits": false,
  "item": "Fancy hat",
  "limited": false,
  "availableAmount": 0,
  "permissions": { "copy": true, "modify": false, "transfer": true },
  "discount": { "value": 10, "type": 0, "startDate": "2026-04-01T00:00:00Z", "endDate": "2026-05-01T00:00:00Z" },
  "description": "A very fancy hat.",
  "demoId": null,
  "mpListing": 4242,
  "profitShares": [
    { "userUuid": "b7c8d9e0-1f2a-4b3c-8d4e-5f6a7b8c9d0e", "percent": 10 }
  ]
}

The response is a ProductResponse. The discount.type field is an integer: see DiscountType. Status: 200, or 404 if no product matches.

Create a product

POST /v1/products

Creates a product. Scope: products:write. The body is a ProductUpsertRequest.

curl --fail-with-body https://integrations.allomancy.net/v1/products \
  -H "X-API-Key: allo_live_8Kd2...zQ.Hk9...4w" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Fancy hat",
    "price": 250,
    "image": "0d4f8a11-9b2c-4e6d-8f1a-3c7b5d9e2f04",
    "listed": true,
    "bloggable": true,
    "permissions": { "copy": true, "modify": false, "transfer": true },
    "discount": { "value": 10, "type": 0, "startDate": "2026-04-01T00:00:00Z", "endDate": "2026-05-01T00:00:00Z" },
    "availableAmount": 0,
    "limited": false,
    "item": "Fancy hat",
    "blockCredits": false,
    "description": "A very fancy hat.",
    "profitShares": [
      { "username": "partner.resident", "userUuid": "b7c8d9e0-1f2a-4b3c-8d4e-5f6a7b8c9d0e", "percent": 10 }
    ],
    "demoId": null,
    "active": true
  }'
import requests

response = requests.post(
    "https://integrations.allomancy.net/v1/products",
    headers={"X-API-Key": "allo_live_8Kd2...zQ.Hk9...4w"},
    json={
        "name": "Fancy hat",
        "price": 250,
        "image": "0d4f8a11-9b2c-4e6d-8f1a-3c7b5d9e2f04",
        "listed": True,
        "bloggable": True,
        "permissions": {"copy": True, "modify": False, "transfer": True},
        "discount": {
            "value": 10,
            "type": 0,
            "startDate": "2026-04-01T00:00:00Z",
            "endDate": "2026-05-01T00:00:00Z",
        },
        "availableAmount": 0,
        "limited": False,
        "item": "Fancy hat",
        "blockCredits": False,
        "description": "A very fancy hat.",
        "profitShares": [
            {
                "username": "partner.resident",
                "userUuid": "b7c8d9e0-1f2a-4b3c-8d4e-5f6a7b8c9d0e",
                "percent": 10,
            }
        ],
        "demoId": None,
        "active": True,
    },
)
print(response.json())
const response = await fetch("https://integrations.allomancy.net/v1/products", {
  method: "POST",
  headers: {
    "X-API-Key": "allo_live_8Kd2...zQ.Hk9...4w",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Fancy hat",
    price: 250,
    image: "0d4f8a11-9b2c-4e6d-8f1a-3c7b5d9e2f04",
    listed: true,
    bloggable: true,
    permissions: { copy: true, modify: false, transfer: true },
    discount: {
      value: 10,
      type: 0,
      startDate: "2026-04-01T00:00:00Z",
      endDate: "2026-05-01T00:00:00Z",
    },
    availableAmount: 0,
    limited: false,
    item: "Fancy hat",
    blockCredits: false,
    description: "A very fancy hat.",
    profitShares: [
      {
        username: "partner.resident",
        userUuid: "b7c8d9e0-1f2a-4b3c-8d4e-5f6a7b8c9d0e",
        percent: 10,
      },
    ],
    demoId: null,
    active: true,
  }),
});
console.log(await response.json());
<?php
$ch = curl_init("https://integrations.allomancy.net/v1/products");
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",
    "Content-Type: application/json",
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    "name" => "Fancy hat",
    "price" => 250,
    "image" => "0d4f8a11-9b2c-4e6d-8f1a-3c7b5d9e2f04",
    "listed" => true,
    "bloggable" => true,
    "permissions" => ["copy" => true, "modify" => false, "transfer" => true],
    "discount" => [
        "value" => 10,
        "type" => 0,
        "startDate" => "2026-04-01T00:00:00Z",
        "endDate" => "2026-05-01T00:00:00Z",
    ],
    "availableAmount" => 0,
    "limited" => false,
    "item" => "Fancy hat",
    "blockCredits" => false,
    "description" => "A very fancy hat.",
    "profitShares" => [
        [
            "username" => "partner.resident",
            "userUuid" => "b7c8d9e0-1f2a-4b3c-8d4e-5f6a7b8c9d0e",
            "percent" => 10,
        ],
    ],
    "demoId" => null,
    "active" => true,
]));
$response = curl_exec($ch);
curl_close($ch);
echo $response;

On success the response is 201 Created with a Location header pointing at the new product, and the body is the created ProductResponse. A missing or invalid body returns 400; a missing store returns 404.

Update a product

PUT /v1/products/{id}

Replaces a product's fields. Scope: products:write. The body is a ProductUpsertRequest.

curl --fail-with-body https://integrations.allomancy.net/v1/products/3a1f0c9b-7d2e-4c84-9a6f-1b5e8d0c2a37 \
  -X PUT \
  -H "X-API-Key: allo_live_8Kd2...zQ.Hk9...4w" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Fancy hat",
    "price": 300,
    "image": "0d4f8a11-9b2c-4e6d-8f1a-3c7b5d9e2f04",
    "listed": true,
    "bloggable": true,
    "permissions": { "copy": true, "modify": false, "transfer": true },
    "discount": { "value": 10, "type": 0, "startDate": "2026-04-01T00:00:00Z", "endDate": "2026-05-01T00:00:00Z" },
    "availableAmount": 0,
    "limited": false,
    "item": "Fancy hat",
    "blockCredits": false,
    "description": "A very fancy hat.",
    "profitShares": [
      { "username": "partner.resident", "userUuid": "b7c8d9e0-1f2a-4b3c-8d4e-5f6a7b8c9d0e", "percent": 10 }
    ],
    "demoId": null,
    "active": true
  }'
import requests

response = requests.put(
    "https://integrations.allomancy.net/v1/products/3a1f0c9b-7d2e-4c84-9a6f-1b5e8d0c2a37",
    headers={"X-API-Key": "allo_live_8Kd2...zQ.Hk9...4w"},
    json={
        "name": "Fancy hat",
        "price": 300,
        "image": "0d4f8a11-9b2c-4e6d-8f1a-3c7b5d9e2f04",
        "listed": True,
        "bloggable": True,
        "permissions": {"copy": True, "modify": False, "transfer": True},
        "discount": {
            "value": 10,
            "type": 0,
            "startDate": "2026-04-01T00:00:00Z",
            "endDate": "2026-05-01T00:00:00Z",
        },
        "availableAmount": 0,
        "limited": False,
        "item": "Fancy hat",
        "blockCredits": False,
        "description": "A very fancy hat.",
        "profitShares": [
            {
                "username": "partner.resident",
                "userUuid": "b7c8d9e0-1f2a-4b3c-8d4e-5f6a7b8c9d0e",
                "percent": 10,
            }
        ],
        "demoId": None,
        "active": True,
    },
)
print(response.json())
const response = await fetch(
  "https://integrations.allomancy.net/v1/products/3a1f0c9b-7d2e-4c84-9a6f-1b5e8d0c2a37",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "allo_live_8Kd2...zQ.Hk9...4w",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Fancy hat",
      price: 300,
      image: "0d4f8a11-9b2c-4e6d-8f1a-3c7b5d9e2f04",
      listed: true,
      bloggable: true,
      permissions: { copy: true, modify: false, transfer: true },
      discount: {
        value: 10,
        type: 0,
        startDate: "2026-04-01T00:00:00Z",
        endDate: "2026-05-01T00:00:00Z",
      },
      availableAmount: 0,
      limited: false,
      item: "Fancy hat",
      blockCredits: false,
      description: "A very fancy hat.",
      profitShares: [
        {
          username: "partner.resident",
          userUuid: "b7c8d9e0-1f2a-4b3c-8d4e-5f6a7b8c9d0e",
          percent: 10,
        },
      ],
      demoId: null,
      active: true,
    }),
  },
);
console.log(await response.json());
<?php
$ch = curl_init("https://integrations.allomancy.net/v1/products/3a1f0c9b-7d2e-4c84-9a6f-1b5e8d0c2a37");
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([
    "name" => "Fancy hat",
    "price" => 300,
    "image" => "0d4f8a11-9b2c-4e6d-8f1a-3c7b5d9e2f04",
    "listed" => true,
    "bloggable" => true,
    "permissions" => ["copy" => true, "modify" => false, "transfer" => true],
    "discount" => [
        "value" => 10,
        "type" => 0,
        "startDate" => "2026-04-01T00:00:00Z",
        "endDate" => "2026-05-01T00:00:00Z",
    ],
    "availableAmount" => 0,
    "limited" => false,
    "item" => "Fancy hat",
    "blockCredits" => false,
    "description" => "A very fancy hat.",
    "profitShares" => [
        [
            "username" => "partner.resident",
            "userUuid" => "b7c8d9e0-1f2a-4b3c-8d4e-5f6a7b8c9d0e",
            "percent" => 10,
        ],
    ],
    "demoId" => null,
    "active" => true,
]));
$response = curl_exec($ch);
curl_close($ch);
echo $response;

The response is the updated ProductResponse. Status: 200, 400 for an invalid body, or 404 if no product matches.

Deliver a product

POST /v1/products/{id}/actions/deliver

Delivers a product to a resident inworld. Scope: products:deliver. The body is a DeliverProductRequest, where recipientIdentifier is the resident's Second Life username or UUID, and message is an optional note delivered with the product.

The product must exist in the store and be active.

curl --fail-with-body https://integrations.allomancy.net/v1/products/3a1f0c9b-7d2e-4c84-9a6f-1b5e8d0c2a37/actions/deliver \
  -H "X-API-Key: allo_live_8Kd2...zQ.Hk9...4w" \
  -H "Content-Type: application/json" \
  -d '{
    "recipientIdentifier": "resident.username",
    "message": "Thanks for shopping with us."
  }'
import requests

response = requests.post(
    "https://integrations.allomancy.net/v1/products/3a1f0c9b-7d2e-4c84-9a6f-1b5e8d0c2a37/actions/deliver",
    headers={"X-API-Key": "allo_live_8Kd2...zQ.Hk9...4w"},
    json={
        "recipientIdentifier": "resident.username",
        "message": "Thanks for shopping with us.",
    },
)
print(response.json())
const response = await fetch(
  "https://integrations.allomancy.net/v1/products/3a1f0c9b-7d2e-4c84-9a6f-1b5e8d0c2a37/actions/deliver",
  {
    method: "POST",
    headers: {
      "X-API-Key": "allo_live_8Kd2...zQ.Hk9...4w",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      recipientIdentifier: "resident.username",
      message: "Thanks for shopping with us.",
    }),
  },
);
console.log(await response.json());
<?php
$ch = curl_init("https://integrations.allomancy.net/v1/products/3a1f0c9b-7d2e-4c84-9a6f-1b5e8d0c2a37/actions/deliver");
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",
    "Content-Type: application/json",
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    "recipientIdentifier" => "resident.username",
    "message" => "Thanks for shopping with us.",
]));
$response = curl_exec($ch);
curl_close($ch);
echo $response;
{
  "productId": "3a1f0c9b-7d2e-4c84-9a6f-1b5e8d0c2a37",
  "recipientUuid": "c7d8e9f0-1a2b-4c3d-9e4f-5a6b7c8d9e0f",
  "recipientUsername": "resident.username",
  "queued": true,
  "message": "Thanks for shopping with us."
}

Delivery is queued and happens asynchronously, so the response returns queued: true rather than waiting for the resident to receive the item. The response is a ProductDeliveryResponse. Status: 200, 400 for an invalid body or unresolvable recipient, or 404 if the product does not exist or is not active.

Object reference

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

Categories

Group products into categories and manage their membership.

Pagination and errors

The cursor envelope and the problem+json error format.

Pagination and errors

The cursor pagination envelope and the problem+json error format.

Customers

Read customers, adjust their store credit, grant gift cards, and ban or unban them.

On this page

List productsGet a productCreate a productUpdate a productDeliver a productRelated pages