التوثيق

List products

Lists products with search and filters. Supports: - Active filter (`active=true/false`) - Metadata filter (JSON string) - Search in `name`, `description`, and `unitLabel` fields - Pagination

GET
/products

Lists products with search and filters.

Supports:

  • Active filter (active=true/false)
  • Metadata filter (JSON string)
  • Search in name, description, and unitLabel fields
  • Pagination

Authorization

api-key
AuthorizationBearer <token>

API key for merchant integrations. Send as Authorization: Bearer <your key>.

In: header

Query Parameters

metadata?string

Metadata filter as JSON string (e.g., '{"category":"subscription"}')

search?string

Search in name, description, or unitLabel (supports comma-separated terms)

active?boolean

Filter by active status

limit?number

Number of items per page

page?number

Page number (1-based)

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/products"
{
  "data": [
    {
      "id": "prod_abc123",
      "name": "Premium Plan",
      "description": "Premium subscription plan",
      "image": "https://example.com/image.jpg",
      "unitLabel": "month",
      "active": true,
      "isSystemCreated": false,
      "metadata": {
        "category": "subscription"
      },
      "prices": [
        {}
      ],
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z"
    }
  ],
  "totalCount": 42,
  "page": 1,
  "limit": 20,
  "totalPages": 3
}
{
  "error": {
    "type": "authentication_error",
    "code": "authentication_required",
    "message": "No valid API key provided.",
    "doc_url": "https://docs.xpay.app/integrate/errors/api-error-codes#authentication_required"
  },
  "request_id": "req_abc123def456"
}
{
  "error": {
    "type": "invalid_request_error",
    "code": "permission_denied",
    "message": "The API key does not have permission to perform this action.",
    "doc_url": "https://docs.xpay.app/integrate/errors/api-error-codes#permission_denied"
  },
  "request_id": "req_abc123def456"
}
{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "An unexpected error occurred. Please try again or contact support.",
    "doc_url": "https://docs.xpay.app/integrate/errors/api-error-codes#internal_error"
  },
  "request_id": "req_abc123def456"
}

Delete product DELETE

Deletes a product and cascade-deletes all of its prices in one transaction. Fails if any of the product's prices have ever been referenced by a line item — in that case the product must be archived instead.

Create a product POST

Creates a new product. Optionally includes: - An image URL (use the `/upload-url` endpoint to get a one-time upload URL first) - A default price object which will be set as the default price for this product