README

Laravel package for the Meta Marketing API — complete multi-account catalog management: products, feeds, batch inventory updates, offers, diagnostics, localized catalogs and more.

Features

• Multi-account — multiple Meta Business Manager accounts, each with multiple catalogs
• Token encryption — app_id, app_secret, access_token encrypted at rest using Laravel's encrypt()
• Product Feeds — primary, supplementary, and localized feeds (language / country / language+country)
• Batch API — real-time inventory updates, create/update/delete items, localized batch
• Inventory history — immutable audit log of every stock change (meta_inventory_logs)
• Offers API — SALE, AUTOMATIC_AT_CHECKOUT, BUYER_APPLIED (coupons, Buy X Get Y, free shipping)
• Diagnostics — catalog errors, event source issues, pixel/app DA checks
• Event Stats — pixel and app event metrics per catalog
• Generic Feed Files API — promotions, shipping profiles, navigation menu, ratings & reviews
• Commerce Merchant Settings — checkout config, merchant status, Korea FTC compliance
• Page-Owned Catalogs — create and list catalogs owned by a Facebook Page
• Override Details API — inspect localized overrides per product item
• Best practices compliance — google_product_category, rich_text_description, product_type, internal_label
• 17-file Spanish documentation included

Requirements

Installation

composer require scriptdevelop/meta-catalog-manager

Run the install wizard

php artisan meta-catalog:install

The wizard will:

1. Publish the configuration file to config/meta-catalog.php
2. Optionally merge the meta-catalog log channel into your config/logging.php
3. Optionally run the package migrations

Publish manually

# Configuration
php artisan vendor:publish --tag=meta-catalog-config

# Migrations
php artisan vendor:publish --tag=meta-catalog-migrations

# Logging channel
php artisan vendor:publish --tag=meta-catalog-logging

Run migrations

php artisan migrate

Configuration

// config/meta-catalog.php

'api' => [
    'base_url'      => env('META_CATALOG_API_URL', 'https://graph.facebook.com'),
    'graph_version' => env('META_CATALOG_GRAPH_VERSION', 'v25.0'),
    'timeout'       => env('META_CATALOG_API_TIMEOUT', 30),
    'retries'       => env('META_CATALOG_API_RETRIES', 3),
],

Environment variables

META_CATALOG_API_URL=https://graph.facebook.com
META_CATALOG_GRAPH_VERSION=v25.0
META_CATALOG_API_TIMEOUT=30
META_CATALOG_API_RETRIES=3
META_CATALOG_AUTO_MIGRATIONS=true
META_CATALOG_LOG_CHANNEL=meta-catalog
META_CATALOG_APP_ID=
META_CATALOG_APP_SECRET=

Override models

You can swap any model for your own extended class:

// config/meta-catalog.php
'models' => [
    'meta_business_account' => \App\Models\MyMetaBusinessAccount::class,
    'meta_catalog'          => \App\Models\MyMetaCatalog::class,
    // ...
],

Quick Start

Facade

use ScriptDevelop\MetaCatalogManager\Facades\MetaCatalog;

// With context account
MetaCatalog::forAccount($account)->catalog()->syncFromApi();

// Direct access
MetaCatalog::account()->create([...]);
MetaCatalog::catalog()->syncFromApi($account);

Services

AccountService

// Manual flow (auto-fetches name + syncs catalogs)
$account = MetaCatalog::account()->create([
    'meta_business_id'   => '123456789',
    'access_token'       => 'EAABwz...',
]);

// Get the auto-fetched business name
echo $account->name; // "My Business Name" (from Meta API)

// Embedded Signup flow (WhatsApp OAuth)
$account = MetaCatalog::account()->createFromEmbeddedSignup([
    'business_id'       => '2729063490586005',
    'code'              => 'AQBhlXsctMxJYb...',
]);

// Find / list
$account = MetaCatalog::account()->find($ulid);
$account = MetaCatalog::account()->findByMetaBusinessId('123456789');
$accounts = MetaCatalog::account()->all();

CatalogService

// Sync catalogs from Meta API to local DB
$catalogs = MetaCatalog::catalog()->syncFromApi($account);

// Create a catalog
$catalog = MetaCatalog::catalog()->create($account, [
    'name'     => 'My Store Catalog',
    'vertical' => 'commerce',
]);

// Create a Page-Owned catalog
$catalog = MetaCatalog::catalog()->createForPage($account, $pageId, [
    'name' => 'Page Catalog',
]);

ProductService

// Sync all products (auto-pagination)
$count = MetaCatalog::product()->syncFromApi($catalog);

// Single product operations
MetaCatalog::product()->createSingle($catalog, [
    'retailer_id' => 'SKU-001',
    'name'       => 'Blue T-Shirt',
    'price'       => 1999,
    'currency'    => 'USD',
    'url'        => 'https://mystore.com/t-shirt',
    'image_url'  => 'https://mystore.com/t-shirt.jpg',
    'availability'=> 'in stock',
    'condition'   => 'new',
    'brand'       => 'MyBrand',
    'google_product_category' => 'Apparel & Accessories > Clothing > Shirts & Tops',
]);

// Get override details (localized data)
$overrides = MetaCatalog::product()->getOverrideDetails(
    $productItemId,
    $account,
    keys: ['US', 'es_XX'],
    type: FeedOverrideType::COUNTRY
);

FeedService

// Create a primary feed with daily schedule
$feed = MetaCatalog::feed()->create($catalog, [
    'name'     => 'Main Product Feed',
    'schedule' => [
        'interval' => 'DAILY',
        'url'      => 'https://mystore.com/feed.csv',
        'hour'     => 2,
    ],
]);

// Upload from URL (one-time)
MetaCatalog::feed()->uploadFromUrl($feed, 'https://mystore.com/feed.csv');

// Upload from local file
MetaCatalog::feed()->uploadFromFile($feed, '/path/to/feed.csv');

// Supplementary feed (updates without deleting items)
MetaCatalog::feed()->createSupplementaryFeed($catalog, [
    'name'            => 'Price Updates',
    'primary_feed_ids' => ['1234567890'],
    'schedule'        => ['interval' => 'HOURLY', 'url' => 'https://...'],
]);

// Localized feeds
MetaCatalog::feed()->createLanguageFeed($catalog, 'Language Feed ES/FR');
MetaCatalog::feed()->createCountryFeed($catalog, 'Country Feed US/UK');
MetaCatalog::feed()->createLanguageAndCountryFeed($catalog, 'Locale Feed fr|CA');

// Error reporting
$errors  = MetaCatalog::feed()->getUploadErrors($upload);
MetaCatalog::feed()->requestErrorReport($upload);
$report  = MetaCatalog::feed()->getErrorReport($upload);

BatchService

// Real-time inventory update (async)
$batch = MetaCatalog::batch()->updateItems($catalog, [
    ['retailer_id' => 'SKU-001', 'quantity_to_sell_on_facebook' => 50],
    ['retailer_id' => 'SKU-002', 'quantity_to_sell_on_facebook' => 0],
]);

// Check status
$status = MetaCatalog::batch()->checkStatus($catalog, $batch->handle);

// Create items
MetaCatalog::batch()->createItems($catalog, $items);

// Delete items
MetaCatalog::batch()->deleteItems($catalog, ['SKU-001', 'SKU-002']);

// Localized batch
MetaCatalog::batch()->sendLocalizedBatch($catalog, $localizedItems);

InventoryService

// Update a single item's stock
MetaCatalog::inventory()->updateSingle(
    $catalogItem,
    25,
    InventoryChangeSource::MANUAL,
    'Manual stock adjustment'
);

// Batch update via Meta Batch API
MetaCatalog::inventory()->updateBatch($catalog, [
    ['retailer_id' => 'SKU-001', 'quantity' => 10],
    ['retailer_id' => 'SKU-002', 'quantity' => 0],
]);

// History and reporting
$history  = MetaCatalog::inventory()->getHistory($catalogItem);
$last     = MetaCatalog::inventory()->getLastLog($catalogItem);
$lowStock = MetaCatalog::inventory()->getLowStock($catalog, threshold: 5);
$outOfStock = MetaCatalog::inventory()->getOutOfStock($catalog);

ProductSetService

$set = MetaCatalog::productSet()->create($catalog, [
    'name'   => 'Summer Sale',
    'filter' => ['availability' => ['eq' => 'in stock']],
]);

MetaCatalog::productSet()->syncFromApi($catalog);

DiagnosticsService

// Catalog-level diagnostics
$diagnostics = MetaCatalog::diagnostics()->fetchFromApi($catalog);
MetaCatalog::diagnostics()->syncFromApi($catalog);

// Event source issues
$issues = MetaCatalog::diagnostics()->getEventSourceIssues($catalog, $account);
$hasCritical = MetaCatalog::diagnostics()->hasCriticalEventSourceIssues($catalog, $account);

EventStatsService

$stats = MetaCatalog::eventStats()->fetchFromApi($catalog);
MetaCatalog::eventStats()->syncFromApi($catalog);

OfferService

$offer = MetaCatalog::offer()->createOffer($catalog, [
    'offer_id'         => 'SUMMER20',
    'title'            => 'Summer Sale 20% Off',
    'application_type' => OfferApplicationType::SALE->value,
    'value_type'       => 'PERCENTAGE',
    'percent_off'      => 20,
    'start_date_time'  => '2025-06-01T00:00:00',
    'end_date_time'    => '2025-08-31T23:59:59',
]);

$activeSales   = MetaCatalog::offer()->getActiveSales($catalog);
$activeCoupons = MetaCatalog::offer()->getActiveCoupons($catalog);

GenericFeedService

// Upload shipping profiles
MetaCatalog::genericFeed()->uploadShippingProfiles(
    $account,
    $commercePartnerIntegrationId,
    '/path/to/shipping.csv'
);

// Upload promotions
MetaCatalog::genericFeed()->uploadPromotions(
    $account,
    $commercePartnerIntegrationId,
    '/path/to/promotions.csv'
);

// Upload ratings & reviews
MetaCatalog::genericFeed()->uploadRatingsAndReviews($catalog, '/path/to/reviews.csv');

MerchantSettingsService

$settings = MetaCatalog::merchantSettings()->get($account, $commerceMerchantSettingsId);

MetaCatalog::merchantSettings()->enable($account, $commerceMerchantSettingsId);

MetaCatalog::merchantSettings()->setCheckoutConfig(
    $account,
    $commerceMerchantSettingsId,
    checkoutUrl: 'https://mystore.com/checkout',
    countryCode: 'US'
);

Localized Catalogs

Support for language, country, and language+country override feeds:

use ScriptDevelop\MetaCatalogManager\Enums\FeedOverrideType;

// Language feed (translations: title, description)
MetaCatalog::feed()->createLanguageFeed($catalog, 'Language Feed ES/FR', [
    'interval' => 'DAILY',
    'url'      => 'https://mystore.com/feeds/languages.csv',
    'hour'     => 22,
]);

// Country feed (prices, availability, links by country)
MetaCatalog::feed()->createCountryFeed($catalog, 'Country Feed US/UK/AR', [
    'interval' => 'DAILY',
    'url'      => 'https://mystore.com/feeds/countries.csv',
    'hour'     => 3,
]);

// Language+country feed (advanced: fr_XX|CA, fr_XX|US)
MetaCatalog::feed()->createLanguageAndCountryFeed($catalog, 'Locale Feed', [
    'interval' => 'DAILY',
    'url'      => 'https://mystore.com/feeds/locales.tsv',
    'hour'     => 4,
]);

// Inspect overrides for a specific product
$overrides = MetaCatalog::product()->getOverrideDetails($productItemId, $account);

Priority order: language_and_country → language → country → main catalog.

Webhooks

The package exposes a webhook endpoint at POST /meta-catalog-webhook for receiving real-time notifications from Meta:

Customizing the Webhook Processor

// Implement your own processor
class MyWebhookProcessor implements \ScriptDevelop\MetaCatalogManager\Contracts\WebhookProcessorInterface
{
    public function handle(Request $request): Response|JsonResponse { ... }
    public function verifyWebhook(Request $request, string $verifyToken): Response { ... }
    public function processProductFeed(array $payload): void { ... }
    public function processItemsBatch(array $payload): void { ... }
}

// Set in .env
META_CATALOG_WEBHOOK_PROCESSOR=\\App\\Webhooks\\MyWebhookProcessor
META_CATALOG_WEBHOOK_VERIFY_TOKEN=your_secret_token

Database Schema

Available Enums

Documentation

Full Spanish documentation is available in documentation/es/:

1. Instalación
2. Configuración
3. Cuentas de Negocio
4. Catálogos
5. Productos
6. Inventario
7. Feeds
8. Batch API
9. Conjuntos de Productos
10. Diagnósticos
11. Ofertas
12. Diagnósticos Avanzados
13. Microdatos
14. Calificaciones y Opiniones
15. Feeds Genéricos
16. Merchant Settings
17. Catálogos Localizados

Changelog

See CHANGELOG.md for release history.

License

MIT © Wilfredo Perilla