Admin API

# does the API answer? (a 405 or 401 means yes, a 404 means it is off or multistore blocks it)
curl -s -o /dev/null -w '%{http_code}\n' https://shop.example.test/admin-api/access_token

# turn the API off or on from the console
bin/console prestashop:config set PS_ENABLE_ADMIN_API --value=0
bin/console prestashop:config set PS_ENABLE_ADMIN_API --value=1

# local development shop only, debug mode on
bin/console prestashop:config set PS_ADMIN_API_FORCE_DEBUG_SECURED --value=0

# what a production shop answers over plain HTTP
curl -s -i -X POST http://shop.example.test/admin-api/access_token -d grant_type=client_credentials
# HTTP/1.1 401 Unauthorized
# "Use HTTPS protocol"

bin/console prestashop:api-client create pocket-coffee-erp \
  --name="Pocket Coffee ERP" \
  --description="Reads products and manages the Coffee Club group" \
  --scopes=product_read,customer_group_read,customer_group_write,api_client_read \
  --timeout=900

curl -s -X POST https://shop.example.test/admin-api/api-clients \
  -H "Authorization: Bearer ${PS_TOKEN}" -H 'Content-Type: application/json' \
  -d '{"clientId":"pocket-coffee-tmp","clientName":"Temporary","description":"Created through the Admin API",
       "enabled":true,"lifetime":600,"scopes":["product_read"]}'
# HTTP 201  {"apiClientId":6,"secret":"<shown once>"}

curl -s -H "Authorization: Bearer ${PS_TOKEN}" https://shop.example.test/admin-api/api-clients/6
# {"apiClientId":6,"clientId":"pocket-coffee-tmp","clientName":"Temporary","description":"Created through the Admin API",
#  "externalIssuer":null,"enabled":true,"lifetime":600,"scopes":["product_read"]}

curl -s -X PATCH -H "Authorization: Bearer ${PS_TOKEN}" -H 'Content-Type: application/json' \
  https://shop.example.test/admin-api/api-clients/6 -d '{"enabled":false}'     # HTTP 200, the client is now disabled
curl -s -X DELETE -H "Authorization: Bearer ${PS_TOKEN}" https://shop.example.test/admin-api/api-clients/6   # HTTP 204

curl -s -H "Authorization: Bearer ${PS_TOKEN}" https://shop.example.test/admin-api/api-clients/infos
# {"apiClientId":3,"clientId":"pocket-coffee-erp","clientName":"Pocket Coffee ERP",
#  "description":"Reads products and manages the Coffee Club group","externalIssuer":null,"enabled":true,"lifetime":900,
#  "scopes":["product_read","customer_group_read","customer_group_write","api_client_read"]}

curl -s -H "Authorization: Bearer ${PS_TOKEN}" \
  "https://shop.example.test/admin-api/products?limit=2&orderBy=productId&sortOrder=desc"
# {"totalItems":19,"orderBy":"productId","sortOrder":"desc","limit":2,"filters":[],
#  "items":[{"productId":19,"enabled":true,"name":"Customizable mug","quantity":300,
#            "priceTaxExcluded":13.9,"priceTaxIncluded":13.9,"category":"Home Accessories"}, ...]}

curl -s -g -H "Authorization: Bearer ${PS_TOKEN}" \
  "https://shop.example.test/admin-api/products?filters[name]=mug&limit=3&offset=0"
# {"totalItems":5,"orderBy":"productId","sortOrder":"asc","limit":3,"filters":{"name":"mug"},"items":[...]}

# create a product (type is one of standard, pack, virtual, combinations)
curl -s -X POST -H "Authorization: Bearer ${PS_TOKEN}" -H 'Content-Type: application/json' \
  https://shop.example.test/admin-api/products \
  -d '{"type":"standard","names":{"1":"Starter kit","2":"Kit de inicio"}}'
# HTTP 201 {"productId":21,"type":"standard","enabled":false,"names":{"en-US":"Starter kit","es-ES":"Kit de inicio"}, ...}

# change only some fields (PATCH, partial update)
curl -s -X PATCH -H "Authorization: Bearer ${PS_TOKEN}" -H 'Content-Type: application/json' \
  https://shop.example.test/admin-api/products/21 \
  -d '{"priceTaxExcluded":24.00,"reference":"PC-KIT-001","enabled":true,"weight":1.2}'
# HTTP 200, the whole product is returned: "enabled":true,"priceTaxExcluded":24.0,"reference":"PC-KIT-001","weight":1.2 ...

curl -s -H "Authorization: Bearer ${PS_TOKEN}" https://shop.example.test/admin-api/products/21
curl -s -X DELETE -H "Authorization: Bearer ${PS_TOKEN}" https://shop.example.test/admin-api/products/21   # HTTP 204

curl -s -X POST -H "Authorization: Bearer ${PS_TOKEN}" -H 'Content-Type: application/json' \
  https://shop.example.test/admin-api/customers/groups \
  -d '{"localizedNames":{"1":"Coffee Club","2":"Club del Cafe"},"reductionPercent":10.0,
       "displayPriceTaxExcluded":false,"showPrice":true,"shopIds":[1]}'
# HTTP 201 {"customerGroupId":5,"localizedNames":{"en-US":"Coffee Club","es-ES":"Club del Cafe"},
#           "reductionPercent":10.0,"displayPriceTaxExcluded":false,"showPrice":true,"shopIds":[1]}

curl -s -X PUT -H "Authorization: Bearer ${PS_TOKEN}" -H 'Content-Type: application/json' \
  https://shop.example.test/admin-api/customers/groups/5 \
  -d '{"localizedNames":{"1":"Coffee Club","2":"Club del Cafe"},"reductionPercent":12.5,
       "displayPriceTaxExcluded":false,"showPrice":true,"shopIds":[1]}'
# HTTP 200 ... "reductionPercent":12.5 ...

curl -s -H "Authorization: Bearer ${PS_TOKEN}" "https://shop.example.test/admin-api/products/1/combinations?limit=2"
# {"totalItems":8,"orderBy":"id_product_attribute","sortOrder":"asc","limit":2,"filters":[],
#  "items":[{"productId":1,"combinationId":1,"name":"Size - S, Color - White","default":true,"reference":"demo_1",
#            "quantity":300,"attributes":[{"attributeGroupId":1,"attributeGroupName":"Size", ...}]}, ...]}

{
  "type": "https://tools.ietf.org/html/rfc2616#section-10",
  "title": "An error occurred",
  "status": 500,
  "detail": "Group #999 was not found",
  "class": "PrestaShop\\PrestaShop\\Core\\Domain\\Customer\\Group\\Exception\\GroupNotFoundException",
  "trace": []
}

bin/console prestashop:feature-flag list | grep admin_api
# | admin_api_multistore             | env,dotenv,[db]       | Disabled |
# | admin_api_experimental_endpoints | env,dotenv,[db]       | Disabled |

modules/pcfhapi/
  pcfhapi.php                      main class, creates and drops the table
  composer.json, vendor/           PSR-4 autoloader for PrestaShop\Module\Pcfhapi\
  config/services.yml              registers the handlers
  src/ApiPlatform/Resources/RoastDate.php
  src/Database/RoastDateInstaller.php
  src/Domain/RoastDate/Command/    SetRoastDateCommand, DeleteRoastDateCommand
  src/Domain/RoastDate/Query/      GetRoastDate, GetRoastDateList
  src/Domain/RoastDate/QueryResult/RoastDate.php
  src/Domain/RoastDate/Exception/  RoastDateNotFoundException, InvalidRoastDateException
  src/Infrastructure/Handler/      four handlers

<?php

declare(strict_types=1);

if (!defined('_PS_VERSION_')) {
    exit;
}

if (file_exists(__DIR__ . '/vendor/autoload.php')) {
    require_once __DIR__ . '/vendor/autoload.php';
}

use PrestaShop\Module\Pcfhapi\Database\RoastDateInstaller;

class Pcfhapi extends Module
{
    public function __construct()
    {
        $this->name = 'pcfhapi';
        $this->tab = 'administration';
        $this->version = '1.0.0';
        $this->author = 'Pocket Coffee';
        $this->need_instance = 0;
        $this->ps_versions_compliancy = ['min' => '9.0.0', 'max' => '9.99.99'];

        parent::__construct();

        $this->displayName = $this->trans('Pocket Coffee roast dates API', [], 'Modules.Pcfhapi.Admin');
        $this->description = $this->trans('Admin API resource that stores the roast date of each product.', [], 'Modules.Pcfhapi.Admin');
    }

    public function install(): bool
    {
        return parent::install() && RoastDateInstaller::createTable(Db::getInstance(), _DB_PREFIX_);
    }

    public function uninstall(): bool
    {
        return RoastDateInstaller::dropTable(Db::getInstance(), _DB_PREFIX_) && parent::uninstall();
    }

    public function isUsingNewTranslationSystem(): bool
    {
        return true;
    }
}

<?php

declare(strict_types=1);

namespace PrestaShop\Module\Pcfhapi\Domain\RoastDate\Command;

class SetRoastDateCommand
{
    public function __construct(
        public readonly int $productId,
        public readonly string $roastDate,
        public readonly string $batch = '',
    ) {
    }
}

<?php

declare(strict_types=1);

namespace PrestaShop\Module\Pcfhapi\Domain\RoastDate\Query;

class GetRoastDate
{
    public function __construct(public readonly int $productId)
    {
    }
}

<?php

declare(strict_types=1);

namespace PrestaShop\Module\Pcfhapi\Domain\RoastDate\QueryResult;

class RoastDate
{
    public function __construct(
        private readonly int $productId,
        private readonly string $roastDate,
        private readonly string $batch,
    ) {
    }

    public function getProductId(): int
    {
        return $this->productId;
    }

    public function getRoastDate(): string
    {
        return $this->roastDate;
    }

    public function getBatch(): string
    {
        return $this->batch;
    }
}

<?php

declare(strict_types=1);

namespace PrestaShop\Module\Pcfhapi\Infrastructure\Handler;

use DateTimeImmutable;
use Doctrine\DBAL\Connection;
use PrestaShop\Module\Pcfhapi\Domain\RoastDate\Command\SetRoastDateCommand;
use PrestaShop\Module\Pcfhapi\Domain\RoastDate\Exception\InvalidRoastDateException;
use PrestaShop\PrestaShop\Core\CommandBus\Attributes\AsCommandHandler;

#[AsCommandHandler]
final class SetRoastDateHandler
{
    public function __construct(private readonly Connection $connection, private readonly string $dbPrefix)
    {
    }

    public function handle(SetRoastDateCommand $command): void
    {
        $date = DateTimeImmutable::createFromFormat('!Y-m-d', $command->roastDate);
        if (false === $date || $date->format('Y-m-d') !== $command->roastDate) {
            throw new InvalidRoastDateException(sprintf('"%s" is not a valid Y-m-d date', $command->roastDate));
        }

        $this->connection->executeStatement(
            'REPLACE INTO ' . $this->dbPrefix . 'pcfhapi_roast_date (id_product, roast_date, batch) VALUES (:id, :date, :batch)',
            ['id' => $command->productId, 'date' => $command->roastDate, 'batch' => $command->batch]
        );
    }
}

services:
  _defaults:
    autowire: true
    autoconfigure: true
    public: false
    bind:
      string $dbPrefix: '%database_prefix%'

  PrestaShop\Module\Pcfhapi\Infrastructure\Handler\:
    resource: '../src/Infrastructure/Handler/*'
    exclude: '../src/Infrastructure/Handler/index.php'

  PrestaShop\Module\Pcfhapi\Database\RoastDateInstaller: ~

<?php

declare(strict_types=1);

namespace PrestaShop\Module\Pcfhapi\ApiPlatform\Resources;

use ApiPlatform\Metadata\ApiProperty;
use ApiPlatform\Metadata\ApiResource;
use PrestaShop\Module\Pcfhapi\Domain\RoastDate\Command\DeleteRoastDateCommand;
use PrestaShop\Module\Pcfhapi\Domain\RoastDate\Command\SetRoastDateCommand;
use PrestaShop\Module\Pcfhapi\Domain\RoastDate\Exception\InvalidRoastDateException;
use PrestaShop\Module\Pcfhapi\Domain\RoastDate\Exception\RoastDateNotFoundException;
use PrestaShop\Module\Pcfhapi\Domain\RoastDate\Query\GetRoastDate;
use PrestaShop\Module\Pcfhapi\Domain\RoastDate\Query\GetRoastDateList;
use PrestaShopBundle\ApiPlatform\Metadata\CQRSDelete;
use PrestaShopBundle\ApiPlatform\Metadata\CQRSGet;
use PrestaShopBundle\ApiPlatform\Metadata\CQRSGetCollection;
use PrestaShopBundle\ApiPlatform\Metadata\CQRSPartialUpdate;
use Symfony\Component\HttpFoundation\Response;

#[ApiResource(
    operations: [
        new CQRSGet(
            uriTemplate: '/pocket-coffee/roast-dates/{productId}',
            requirements: ['productId' => '\d+'],
            CQRSQuery: GetRoastDate::class,
            scopes: ['pcfhapi_roast_date_read'],
        ),
        new CQRSGetCollection(
            uriTemplate: '/pocket-coffee/roast-dates',
            CQRSQuery: GetRoastDateList::class,
            scopes: ['pcfhapi_roast_date_read'],
        ),
        new CQRSPartialUpdate(
            uriTemplate: '/pocket-coffee/roast-dates/{productId}',
            requirements: ['productId' => '\d+'],
            read: false,
            CQRSCommand: SetRoastDateCommand::class,
            CQRSQuery: GetRoastDate::class,
            scopes: ['pcfhapi_roast_date_write'],
        ),
        new CQRSDelete(
            uriTemplate: '/pocket-coffee/roast-dates/{productId}',
            requirements: ['productId' => '\d+'],
            output: false,
            CQRSCommand: DeleteRoastDateCommand::class,
            scopes: ['pcfhapi_roast_date_write'],
        ),
    ],
    exceptionToStatus: [
        RoastDateNotFoundException::class => Response::HTTP_NOT_FOUND,
        InvalidRoastDateException::class => Response::HTTP_UNPROCESSABLE_ENTITY,
    ],
)]
class RoastDate
{
    #[ApiProperty(identifier: true)]
    public int $productId;

    public string $roastDate;

    public string $batch = '';
}

bin/console prestashop:module install pcfhapi
bin/console cache:clear --app-id=admin-api
bin/console debug:router --app-id=admin-api | grep roast
# _api_/pocket-coffee/roast-dates/{productId}_get      GET     /pocket-coffee/roast-dates/{productId}
# _api_/pocket-coffee/roast-dates_get_collection       GET     /pocket-coffee/roast-dates
# _api_/pocket-coffee/roast-dates/{productId}_patch    PATCH   /pocket-coffee/roast-dates/{productId}
# _api_/pocket-coffee/roast-dates/{productId}_delete   DELETE  /pocket-coffee/roast-dates/{productId}

bin/console prestashop:api-client create pocket-coffee-roastery --name="Roastery" \
  --scopes=pcfhapi_roast_date_read,pcfhapi_roast_date_write --secret-only

TOKEN=$(curl -s -X POST https://shop.example.test/admin-api/access_token \
  -d grant_type=client_credentials -d client_id=pocket-coffee-roastery -d client_secret="${PS_CLIENT_SECRET}" \
  -d scope="pcfhapi_roast_date_read pcfhapi_roast_date_write" | jq -r .access_token)

curl -s -X PATCH -H "Authorization: Bearer ${TOKEN}" -H 'Content-Type: application/json' \
  https://shop.example.test/admin-api/pocket-coffee/roast-dates/1 -d '{"roastDate":"2026-10-26","batch":"ETH-2610"}'
# HTTP 200 {"productId":1,"roastDate":"2026-10-26","batch":"ETH-2610"}

curl -s -H "Authorization: Bearer ${TOKEN}" https://shop.example.test/admin-api/pocket-coffee/roast-dates
# HTTP 200 [{"productId":1,"roastDate":"2026-10-26","batch":"ETH-2610"},{"productId":2,"roastDate":"2026-10-20","batch":"COL-2610"}]

curl -s -X DELETE -H "Authorization: Bearer ${TOKEN}" https://shop.example.test/admin-api/pocket-coffee/roast-dates/2   # HTTP 204

new PaginatedList(
    uriTemplate: '/api-clients',
    scopes: ['api_client_read'],
    ApiResourceMapping: [
        '[id_api_client]' => '[apiClientId]',
        '[client_id]' => '[clientId]',
        '[client_name]' => '[clientName]',
        '[external_issuer]' => '[externalIssuer]',
    ],
    gridDataFactory: 'prestashop.core.grid.data_factory.api_client',
    filtersClass: ApiClientFilters::class,
    filtersMapping: [
        '[apiClientId]' => '[id_api_client]',
        '[clientId]' => '[client_id]',
        '[clientName]' => '[client_name]',
        '[externalIssuer]' => '[external_issuer]',
    ],
),

bin/console debug:router --app-id=admin-api | grep pocket-coffee      # are the routes registered?
bin/console debug:api-resource 'PrestaShop\Module\Pcfhapi\ApiPlatform\Resources\RoastDate' --app-id=admin-api
bin/console prestashop:list:commands-and-queries -d RoastDate           # CQRS classes of a domain, with their API route

#[ApiResource(
    provider: HorseProvider::class,
    processor: HorseProcessor::class
)]
class Horse
{
    #[ApiProperty(identifier: true)]
    public ?int $id = null;

    #[Assert\NotBlank]
    #[Assert\Type('string')]
    public ?string $name = null;
    // ...
}