omnitrade/woocommerce API reference

Omnitrade\WooCommerce

Api class

final class Api Api.php:16

WooCommerce's REST API v3, with a consumer key and secret (HTTP basic authentication over HTTPS). Webhooks are signed with the webhook's own secret: base64 of the HMAC-SHA256 of the raw body, in X-WC-Webhook-Signature.

Api::__construct()

public function __construct(readonly HttpClientInterface $http, readonly string $url, readonly string $consumerKey, readonly string $consumerSecret, readonly ?string $webhookSecret = null, readonly int $timeout = 15)

Api::url()

public function url(): string

Api::call()

public function call(string $method, string $path, ?array $body = null, array $query = []): array

Returns

the JSON answer

Throws

ProviderException

Api::page()

public function page(string $path, array $query = []): array

A GET of a collection, with how many pages it has (X-WP-TotalPages; null when the shop does not say).

Throws

ProviderException

Api::all()

public function all(string $path, array $query = []): array

Every page of a collection, 100 at a time.

Throws

ProviderException

Api::canVerify()

public function canVerify(): bool

Api::verify()

public function verify(string $body, ?string $signature): void

Throws

InvalidNotificationException

Api::sign()

public static function sign(string $body, string $secret): string

The header WooCommerce would send for this body - used by the tests.

Orders class

final class Orders Orders.php:14

A WooCommerce order, as the REST API answers it, read as a Transaction or a PlatformOrder; and a Payment written as one.

const REFERENCE_KEY = 'omnitrade_reference'

Orders::status()

public static function status(array $order): Status

Orders::transaction()

public static function transaction(array $order): Transaction

Orders::platformOrder()

public static function platformOrder(array $order): PlatformOrder

Orders::create()

public static function create(Payment $payment): array

Returns

an order to create, unpaid: the buyer pays it on the shop's checkout

Products class

final class Products Products.php:20

A WooCommerce product, as REST v3 answers it (and a product webhook posts it), read as a Product: a simple product is its own only variant, a variable product's variations are its variants (fetched apart, from /products/<id>/variations). The attributes used for variations are the options, the others the attributes. Pure: arrays in, models out.

Products::product()

public static function product(array $product, array $variations, string $currency, string $weightUnit = 'kg'): Product

$product

a /products item

$variations

its /products/<id>/variations, for a variable product

$weightUnit

the store's (WooCommerce → Settings → Products): kg, g, lbs, oz

Products::stock()

public static function stock(array $item, ?array $parent = null): Stock

A product's or a variation's stock: stock_quantity when it manages its stock (a variation saying "parent" counts on its product's), else a null quantity.

$parent

the variation's product, for "parent"

Products::status()

public static function status(mixed $status): string

publish → active; draft, pending, private, future → draft; trash → archived.

WooCommerceGatewayFactory class

final class WooCommerceGatewayFactory extends GatewayFactory WooCommerceGatewayFactory.php:34

WooCommerce, a commerce platform: a sale paid on the shop's own checkout (an order created unpaid, with its payment URL), the shop's orders and their payment state, refunds, the enabled payment gateways, the catalogue (products, variations, stock) and webhooks.

options: url: '%env(WOOCOMMERCE_URL)%' # https://shop.example consumer_key: '%env(WOOCOMMERCE_KEY)%' # ck_..., a REST API key with read/write consumer_secret: '%env(WOOCOMMERCE_SECRET)%' # cs_... webhook_secret: '%env(WOOCOMMERCE_WEBHOOK_SECRET)%' # the webhook's secret, for notify() timeout: 15 currency: EUR # the catalogue's prices' currency (the store's) weight_unit: kg # the store's weight unit: kg, g, lbs, oz product_status: any # the products fetchProducts() lists: any, or publish

Options

Omnitrade\WooCommerce\Action

FetchInventoryAction class

final class FetchInventoryAction implements ActionInterface, ApiAwareInterface FetchInventoryAction.php:21

What is left: stock_quantity where manage_stock is on (a null quantity elsewhere), for simple products and variations - the variants. The ids given are read through GET /products?include= (a variable product's id gives its variations), the ones left - variations - one by one through GET /products/<id>; none given, every product and variation of the shop.

FetchInventoryAction::__construct()

public function __construct()

FetchInventoryAction::supports()

public function supports(Request $request): bool

FetchInventoryAction::execute()

public function execute(Request $request): void

FetchOrderAction class

final class FetchOrderAction implements ActionInterface, ApiAwareInterface FetchOrderAction.php:14

A shop order, whole.

FetchOrderAction::__construct()

public function __construct()

FetchOrderAction::supports()

public function supports(Request $request): bool

FetchOrderAction::execute()

public function execute(Request $request): void

FetchProductAction class

final class FetchProductAction implements ActionInterface, ApiAwareInterface FetchProductAction.php:21

One product: by its id (GET /products/<id>), its slug, or the address of its page - the slug is the last segment of /product/<slug>/, an address with ?p=<id> names the id (GET /products?slug=<slug>). A variation's id answers its product. Null when the shop has no such product.

FetchProductAction::__construct()

public function __construct(readonly string $currency = 'EUR', readonly string $weightUnit = 'kg')

FetchProductAction::supports()

public function supports(Request $request): bool

FetchProductAction::execute()

public function execute(Request $request): void

FetchProductAction::target()

public static function target(Reference $reference): array

Returns

the id, or the slug

FetchProductsAction class

final class FetchProductsAction implements ActionInterface, ApiAwareInterface FetchProductsAction.php:21

A page of the shop's products, GET /products by id: the cursor is the page's number (X-WP-TotalPages says whether there is another), updatedSince is modified_after (in GMT), the query WooCommerce's search.

A variable product's variations are read with it (one call each). Pass the same updatedSince and query with the cursor.

FetchProductsAction::__construct()

public function __construct(readonly string $currency = 'EUR', readonly string $weightUnit = 'kg', readonly string $status = 'any')

FetchProductsAction::supports()

public function supports(Request $request): bool

FetchProductsAction::execute()

public function execute(Request $request): void

FetchTransactionAction class

final class FetchTransactionAction implements ActionInterface, ApiAwareInterface FetchTransactionAction.php:14

The order's payment state as the shop has it now.

FetchTransactionAction::__construct()

public function __construct()

FetchTransactionAction::supports()

public function supports(Request $request): bool

FetchTransactionAction::execute()

public function execute(Request $request): void

GetPaymentMethodsAction class

final class GetPaymentMethodsAction implements ActionInterface, ApiAwareInterface GetPaymentMethodsAction.php:14

The shop's payment gateways switched on (GET payment_gateways).

GetPaymentMethodsAction::__construct()

public function __construct()

GetPaymentMethodsAction::supports()

public function supports(Request $request): bool

GetPaymentMethodsAction::execute()

public function execute(Request $request): void

NotifyAction class

final class NotifyAction implements ActionInterface, ApiAwareInterface NotifyAction.php:26

A WooCommerce webhook, its signature checked: an order topic (order.created, order.updated, order.deleted) carries the order, read as what its status means; any other topic is handed back with no status.

A product topic carries the catalogue: product.created, product.updated and product.restored the Product (a variable product's variations read along, one call; a variation's payload read as its whole product), product.deleted the product's id alone.

NotifyAction::__construct()

public function __construct(readonly string $currency = 'EUR', readonly string $weightUnit = 'kg')

NotifyAction::supports()

public function supports(Request $request): bool

NotifyAction::execute()

public function execute(Request $request): void

PurchaseAction class

final class PurchaseAction implements ActionInterface, ApiAwareInterface PurchaseAction.php:20

An order created unpaid on the shop: the buyer is sent to its payment URL (PENDING), where the shop's own payment gateways take the money; fetch() or the order.updated webhook says when they did. WooCommerce brings nobody back: returnUrl is not used.

PurchaseAction::__construct()

public function __construct()

PurchaseAction::supports()

public function supports(Request $request): bool

PurchaseAction::execute()

public function execute(Request $request): void

RefundAction class

final class RefundAction implements ActionInterface, ApiAwareInterface RefundAction.php:17

A refund on an order, through the shop's payment gateway when it can (api_refund).

RefundAction::__construct()

public function __construct()

RefundAction::supports()

public function supports(Request $request): bool

RefundAction::execute()

public function execute(Request $request): void