Laravel Convertkit Laravel Package

Getting Started

• Install with Composer and let Laravel package discovery register the service provider/facade. If discovery is disabled, add the provider and alias manually per the README.
• Publish the package config first, then inspect it before writing code:

  php artisan vendor:publish --tag=convertkit-config
  

  The tag may differ; check the README if that tag is not registered.
• Set credentials in .env — typically CONVERTKIT_API_KEY and CONVERTKIT_API_SECRET — and confirm whether the package reads a dedicated config/convertkit.php or Laravel’s config/services.php.
• First places to look: config/convertkit.php, the service provider bindings, the facade alias, and the package tests/examples. The tests usually reveal the intended day-to-day API shape faster than the README.
• First use case: subscribe a user to a form and tag them for segmentation. The flow is usually: resolve the client, create/update the subscriber by email, then attach the form/tag.

  use ConvertKit\Facades\ConvertKit;
  
  $subscriber = ConvertKit::subscribers()->create([
      'email' => $user->email,
      'first_name' => $user->first_name,
  ]);
  
  ConvertKit::tags()->tag($subscriber['id'], $tagId);
  

  Method names and response shapes may differ; confirm against the package README before relying on the exact signature.
• Smoke-test with a non-production ConvertKit account and a real test email. Verify whether the form’s double opt-in settings are triggered by API subscriptions.

Implementation Patterns

• Inject the client into actions, jobs, and services rather than calling the facade from controllers or models. If the package binds a concrete client, wrap it behind your own small interface so vendor API changes stay contained.
• Queue write operations. Subscriber creation, tagging, sequence enrollment, and broadcast changes are external side effects; jobs give you retries, backoff, and observability without blocking requests.
• Normalize ConvertKit responses into your own DTOs or domain events. Do not leak vendor arrays throughout the app; store the remote subscriber ID and tag/form IDs in your own tables.
• Use tags for segmentation, forms for opt-in, and sequences for onboarding. Keep a mapping table such as users.convertkit_subscriber_id, convertkit_form_id, and convertkit_tag_id so repeated syncs are cheap and auditable.
• Treat broadcasts as an admin workflow, not a request-time action. Create or update a draft in one action, review it, then send/schedule through a separate command or queued job with an explicit approval gate.
• For imports and backfills, chunk records and throttle requests. Use LazyCollection, Bus::batch, or a scheduled command rather than looping over thousands of users in a single request.
• Make sync jobs idempotent where possible. Check for an existing subscriber by email or handle duplicate/conflict responses explicitly, then persist the remote ID.
• If you support multiple ConvertKit accounts, avoid relying on a single global singleton if the package allows per-call or per-tenant config. Otherwise isolate accounts at the application/service level.
• Test with HTTP fakes if the package uses Laravel’s HTTP client, or mock the client/facade otherwise. Assert that jobs are dispatched and that failures are logged without leaking API keys.

Gotchas and Tips

• Rate limits are the main operational risk. Handle 429 responses with backoff and do not blindly retry broadcast sends or other non-idempotent actions.
• Pagination differs by endpoint. Do not assume a single page/per_page pattern; use the package’s iterators if provided, or inspect response metadata before looping.
• ConvertKit errors commonly arrive as JSON with an errors array. Catch the package’s exception type, log the response body with secrets redacted, and map known errors to domain-level failures.
• API subscriptions may not trigger the same double opt-in flow as a native form. Test the form’s settings; if you need confirmation emails, subscribe through the form endpoint rather than only creating a subscriber.
• Sending a broadcast is effectively irreversible. Keep draft creation separate from send/schedule, require an explicit confirmation step, and double-check timezone handling.
• API keys are account-wide secrets. Store them in .env or a secret manager, never in version control, and never log request URLs if the key is passed as a query parameter.
• After changing .env or config values, run php artisan config:cache in deployment and clear config in tests. Stale cached config is a common source of “wrong account” bugs.
• Pin the package with ^1.0 and watch the changelog. As an initial 1.0.0 release, the surface area is new; confirm method signatures and response shapes against the README before broad adoption.
• The 1.0.0 release notes cover subscribers, forms, sequences, tags, and broadcasts but do not advertise webhook support. If you need event-driven sync, plan to poll or build your own webhook endpoint around ConvertKit’s capabilities.
• Useful extension points: publishable config, container bindings for the client, and package exceptions. Prefer binding your own wrapper over patching vendor code.