Categories

`GET /api/v1/categories`

Returns all active product categories. Requires the vouchers feature to be enabled.

Request

curl {{host}}/api/v1/categories \
  -H "Authorization: Bearer <token>"

package main

import (
    "encoding/json"
    "fmt"
    "net/http"
)

type Category struct {
    ID   int    `json:"id"`
    Name string `json:"name"`
}

func main() {
    req, _ := http.NewRequest("GET", "{{host}}/api/v1/categories", nil)
    req.Header.Set("Authorization", "Bearer <token>")

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    var categories []Category
    json.NewDecoder(resp.Body).Decode(&categories)

    for _, c := range categories {
        fmt.Printf("%d: %s\n", c.ID, c.Name)
    }
}

No query parameters.

Response

[
  {
    "id": 1,
    "name": "Gaming"
  },
  {
    "id": 2,
    "name": "Mobile Top-Ups"
  }
]

Response Fields

Key	Type	Description
`id`	integer	Unique category identifier
`name`	string	Category name

Only active categories are returned.

Errors

400 Bad Request — Vouchers feature is not enabled for your client.

{
  "error": {
    "name": "BadRequestError",
    "code": "INVALID_FEATURE",
    "message": "The requested feature is not enabled for this client"
  }
}

401 Unauthorized — Missing or invalid JWT token.

{
  "error": {
    "name": "UnauthorizedError",
    "code": "UNAUTHORIZED",
    "message": "Authorization header required"
  }
}

403 Forbidden — Request IP not in whitelist.

{
  "error": {
    "name": "ForbiddenError",
    "code": "FORBIDDEN",
    "message": "IP address not authorized"
  }
}

500 Internal Server Error — Database query failed.

{
  "error": {
    "name": "InternalServerError",
    "code": "INTERNAL_SERVER_ERROR",
    "message": "Failed to retrieve categories"
  }
}

`GET /api/v1/categories/:id`

Returns a single category by its ID. Requires the vouchers feature.

Request

curl {{host}}/api/v1/categories/1 \
  -H "Authorization: Bearer <token>"

req, _ := http.NewRequest("GET", "{{host}}/api/v1/categories/1", nil)
req.Header.Set("Authorization", "Bearer <token>")

resp, err := http.DefaultClient.Do(req)
if err != nil {
    panic(err)
}
defer resp.Body.Close()

var category Category
json.NewDecoder(resp.Body).Decode(&category)

fmt.Printf("%d: %s\n", category.ID, category.Name)

Request Parameters

Key	Type	Required	Description
`id`	integer	Yes	Category ID (path parameter)

Response

{
  "id": 1,
  "name": "Gaming"
}

Response fields are identical to the list endpoint above.

Errors

400 Bad Request — Vouchers feature is not enabled for your client.

{
  "error": {
    "name": "BadRequestError",
    "code": "INVALID_FEATURE",
    "message": "The requested feature is not enabled for this client"
  }
}

404 Not Found — No active category exists with this ID.

{
  "error": {
    "name": "NotFoundError",
    "code": "NOT_FOUND",
    "message": "Category not found"
  }
}

Returned when the ID is invalid, the category does not exist, or the category is inactive.

401 Unauthorized — Missing or invalid JWT token.

{
  "error": {
    "name": "UnauthorizedError",
    "code": "UNAUTHORIZED",
    "message": "Authorization header required"
  }
}

403 Forbidden — Request IP not in whitelist.

{
  "error": {
    "name": "ForbiddenError",
    "code": "FORBIDDEN",
    "message": "IP address not authorized"
  }
}

On this page