Products Guide

Learn how to work with products via the Pixlpay API.

List Products

Retrieve all products with optional filtering and pagination.

curl "https://yourstore.pixlpay.net/api/external/v1/products" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Query Parameters

Parameter	Type	Description
search	string	Search by name or description
type	string	Filter by type: digital, physical, subscription
category_id	integer	Filter by category
is_active	boolean	Filter by active status
sort_by	string	Sort field: created_at, name, price
sort_order	string	asc or desc
page	integer	Page number
per_page	integer	Items per page (max 100)

Example with Filters

curl "https://yourstore.pixlpay.net/api/external/v1/products?type=digital&is_active=true&sort_by=price&sort_order=asc" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "VIP Rank",
      "description": "Access to VIP features and commands",
      "price": "9.99",
      "type": "digital",
      "is_active": true,
      "stock_quantity": null,
      "category": {
        "id": 1,
        "name": "Ranks"
      },
      "images": [
        {
          "id": 1,
          "url": "https://cdn.pixlpay.net/products/vip-rank.png",
          "is_primary": true
        }
      ],
      "created_at": "2025-01-15T10:00:00Z",
      "updated_at": "2025-01-15T10:00:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 3,
    "per_page": 15,
    "total": 42
  }
}

Get Single Product

Retrieve detailed information about a specific product.

curl "https://yourstore.pixlpay.net/api/external/v1/products/1" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response

{
  "success": true,
  "data": {
    "id": 1,
    "name": "VIP Rank",
    "description": "Access to VIP features and commands",
    "price": "9.99",
    "compare_at_price": "14.99",
    "type": "digital",
    "is_active": true,
    "is_featured": false,
    "stock_quantity": null,
    "sku": "VIP-001",
    "category": {
      "id": 1,
      "name": "Ranks"
    },
    "images": [
      {
        "id": 1,
        "url": "https://cdn.pixlpay.net/products/vip-rank.png",
        "is_primary": true
      }
    ],
    "metadata": {
      "discord_role_id": "123456789",
      "duration_days": 30
    },
    "created_at": "2025-01-15T10:00:00Z",
    "updated_at": "2025-01-15T10:00:00Z"
  }
}

Product Types

Type	Description
digital	Downloadable or virtual items (ranks, keys, etc.)
physical	Physical goods that require shipping
subscription	Recurring billing products

Pagination

All list endpoints return paginated results:

{
  "meta": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 15,
    "total": 72
  }
}

Iterating Through Pages

async function getAllProducts() {
  const products = [];
  let page = 1;
  let hasMore = true;

  while (hasMore) {
    const response = await fetch(
      `${BASE_URL}/products?page=${page}&per_page=100`,
      { headers: { Authorization: `Bearer ${token}` } }
    );
    const data = await response.json();

    products.push(...data.data);

    hasMore = page < data.meta.last_page;
    page++;
  }

  return products;
}

Common Use Cases

Sync Products to External System

async function syncProducts() {
  const products = await pixlpay.getProducts();

  for (const product of products) {
    await externalSystem.upsert({
      external_id: product.id,
      name: product.name,
      price: product.price,
      active: product.is_active,
    });
  }
}

Display Products by Category

async function getProductsByCategory(categoryId) {
  const response = await fetch(
    `${BASE_URL}/products?category_id=${categoryId}&is_active=true`,
    { headers: { Authorization: `Bearer ${token}` } }
  );
  return response.json();
}

Search Products

async function searchProducts(query) {
  const response = await fetch(
    `${BASE_URL}/products?search=${encodeURIComponent(query)}`,
    { headers: { Authorization: `Bearer ${token}` } }
  );
  return response.json();
}

Required Scopes

Endpoint	Required Scope
GET /products	products:read
GET /products/:id	products:read