Allomancy
Developer API

Categories

List, read, create, update, and delete categories, and manage their products.

The categories endpoints manage a store's product categories and the products inside them. Field shapes are on the Object reference page.

List categories

GET /v1/categories

Returns a cursor-paginated list of the store's categories. Scope: categories:read. Query parameters limit and cursor are optional; see Pagination and errors.

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

response = requests.get(
    "https://integrations.allomancy.net/v1/categories",
    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/categories?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/categories?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": "b4e1d7a2-3c8f-4d6e-9a1b-2c3d4e5f6a7b", "name": "Hats", "productCount": 12 }
  ],
  "pagination": { "nextCursor": null, "previousCursor": null, "limit": 50 }
}

Each row is a CategoryResponse. Status: 200, or 400 for a bad pagination parameter.

Get a category

GET /v1/categories/{id}

Returns one category by its UUID. Scope: categories:read.

curl --fail-with-body https://integrations.allomancy.net/v1/categories/b4e1d7a2-3c8f-4d6e-9a1b-2c3d4e5f6a7b \
  -H "X-API-Key: allo_live_8Kd2...zQ.Hk9...4w"
import requests

response = requests.get(
    "https://integrations.allomancy.net/v1/categories/b4e1d7a2-3c8f-4d6e-9a1b-2c3d4e5f6a7b",
    headers={"X-API-Key": "allo_live_8Kd2...zQ.Hk9...4w"},
)
print(response.json())
const response = await fetch(
  "https://integrations.allomancy.net/v1/categories/b4e1d7a2-3c8f-4d6e-9a1b-2c3d4e5f6a7b",
  {
    headers: { "X-API-Key": "allo_live_8Kd2...zQ.Hk9...4w" },
  },
);
console.log(await response.json());
<?php
$ch = curl_init("https://integrations.allomancy.net/v1/categories/b4e1d7a2-3c8f-4d6e-9a1b-2c3d4e5f6a7b");
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 CategoryResponse. Status: 200, or 404 if no category matches.

Create a category

POST /v1/categories

Creates a category. Scope: categories:write. The body is a CreateCategoryRequest.

curl --fail-with-body https://integrations.allomancy.net/v1/categories \
  -H "X-API-Key: allo_live_8Kd2...zQ.Hk9...4w" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Hats" }'
import requests

response = requests.post(
    "https://integrations.allomancy.net/v1/categories",
    headers={"X-API-Key": "allo_live_8Kd2...zQ.Hk9...4w"},
    json={"name": "Hats"},
)
print(response.json())
const response = await fetch("https://integrations.allomancy.net/v1/categories", {
  method: "POST",
  headers: {
    "X-API-Key": "allo_live_8Kd2...zQ.Hk9...4w",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "Hats" }),
});
console.log(await response.json());
<?php
$ch = curl_init("https://integrations.allomancy.net/v1/categories");
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" => "Hats"]));
$response = curl_exec($ch);
curl_close($ch);
echo $response;

On success the response is 201 Created with a Location header pointing at the new category, and the body is the created CategoryResponse. Status: 201, 400, or 404.

Update a category

PUT /v1/categories/{id}

Renames a category. Scope: categories:write. The body is an UpdateCategoryRequest.

curl --fail-with-body https://integrations.allomancy.net/v1/categories/b4e1d7a2-3c8f-4d6e-9a1b-2c3d4e5f6a7b \
  -X PUT \
  -H "X-API-Key: allo_live_8Kd2...zQ.Hk9...4w" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Fancy hats" }'
import requests

response = requests.put(
    "https://integrations.allomancy.net/v1/categories/b4e1d7a2-3c8f-4d6e-9a1b-2c3d4e5f6a7b",
    headers={"X-API-Key": "allo_live_8Kd2...zQ.Hk9...4w"},
    json={"name": "Fancy hats"},
)
print(response.json())
const response = await fetch(
  "https://integrations.allomancy.net/v1/categories/b4e1d7a2-3c8f-4d6e-9a1b-2c3d4e5f6a7b",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "allo_live_8Kd2...zQ.Hk9...4w",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ name: "Fancy hats" }),
  },
);
console.log(await response.json());
<?php
$ch = curl_init("https://integrations.allomancy.net/v1/categories/b4e1d7a2-3c8f-4d6e-9a1b-2c3d4e5f6a7b");
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 hats"]));
$response = curl_exec($ch);
curl_close($ch);
echo $response;

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

Delete a category

DELETE /v1/categories/{id}

Deletes a category. Scope: categories:write.

curl --fail-with-body https://integrations.allomancy.net/v1/categories/b4e1d7a2-3c8f-4d6e-9a1b-2c3d4e5f6a7b \
  -X DELETE \
  -H "X-API-Key: allo_live_8Kd2...zQ.Hk9...4w"
import requests

response = requests.delete(
    "https://integrations.allomancy.net/v1/categories/b4e1d7a2-3c8f-4d6e-9a1b-2c3d4e5f6a7b",
    headers={"X-API-Key": "allo_live_8Kd2...zQ.Hk9...4w"},
)
print(response.status_code)
const response = await fetch(
  "https://integrations.allomancy.net/v1/categories/b4e1d7a2-3c8f-4d6e-9a1b-2c3d4e5f6a7b",
  {
    method: "DELETE",
    headers: { "X-API-Key": "allo_live_8Kd2...zQ.Hk9...4w" },
  },
);
console.log(response.status);
<?php
$ch = curl_init("https://integrations.allomancy.net/v1/categories/b4e1d7a2-3c8f-4d6e-9a1b-2c3d4e5f6a7b");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");
curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-API-Key: allo_live_8Kd2...zQ.Hk9...4w"]);
curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

On success the response is 204 No Content. Status: 204, 400, or 404.

Managing products in a category

Two endpoints add or remove a single product. Both take no request body, both use categories:write, and both return 204 No Content.

POST /v1/categories/{id}/products/{productId}
DELETE /v1/categories/{id}/products/{productId}

The id path parameter is the category's UUID and productId is the product's UUID.

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

response = requests.post(
    "https://integrations.allomancy.net/v1/categories/b4e1d7a2-3c8f-4d6e-9a1b-2c3d4e5f6a7b/products/3a1f0c9b-7d2e-4c84-9a6f-1b5e8d0c2a37",
    headers={"X-API-Key": "allo_live_8Kd2...zQ.Hk9...4w"},
)
print(response.status_code)
const response = await fetch(
  "https://integrations.allomancy.net/v1/categories/b4e1d7a2-3c8f-4d6e-9a1b-2c3d4e5f6a7b/products/3a1f0c9b-7d2e-4c84-9a6f-1b5e8d0c2a37",
  {
    method: "POST",
    headers: { "X-API-Key": "allo_live_8Kd2...zQ.Hk9...4w" },
  },
);
console.log(response.status);
<?php
$ch = curl_init("https://integrations.allomancy.net/v1/categories/b4e1d7a2-3c8f-4d6e-9a1b-2c3d4e5f6a7b/products/3a1f0c9b-7d2e-4c84-9a6f-1b5e8d0c2a37");
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"]);
curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

Send a DELETE to the same path to remove the product from the category. Status for both: 204, 400, or 404.

Products

List, read, create, update, and deliver the products you group here.

Object reference

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

Pagination and errors

The cursor envelope and the problem+json error format.

Customers

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

Coupons

List, read, create, and update store coupons.

On this page

List categoriesGet a categoryCreate a categoryUpdate a categoryDelete a categoryManaging products in a categoryRelated pages