Access the Polar SDK directly for advanced use

Use LaravelPolar::sdk() to call any Polar API endpoint not covered by the facade — wallets, OAuth2, file uploads, organization updates, and more.

The LaravelPolar facade wraps the most common Polar operations with Laravel-idiomatic helpers. It doesn’t wrap every endpoint that the Polar PHP SDK exposes. For anything not covered — customer portal wallets, file creation and deletion, OAuth2 flows, organization updates, and more — drop straight into the underlying SDK client via LaravelPolar::sdk().

This is the documented, supported escape hatch. The facade covers the common cases; sdk() covers the long tail.

When to use sdk() vs. the facade: Use the facade for day-to-day billing work (checkouts, subscriptions, license keys, refunds). Use sdk() when you need an endpoint the facade doesn’t expose, or when you need raw control over the request payload.

---

What sdk() returns

use Danestves\LaravelPolar\LaravelPolar;

$sdk = LaravelPolar::sdk(); // Polar\Polar

sdk() returns a Polar\Polar instance — the official Polar PHP SDK client. The package constructs and caches this instance the first time it is needed, using your polar.access_token and polar.server config values. Subsequent calls in the same request return the same instance.

sdk() throws a plain Exception with the message "Polar API key not set." if polar.access_token is empty. Make sure your access token is configured before calling any facade or SDK method.

---

When to use sdk() directly

Reach for sdk() when:

• You need an endpoint the LaravelPolar facade does not wrap (see examples below).
• You want finer-grained control over the raw request or response payload.
• You are building a one-off admin script or a non-standard integration.

For routine checkout, subscription, license key, and usage-billing work, prefer the facade methods — they handle error checking and surface strongly typed response objects.

---

Examples

Customer portal wallets

use Danestves\LaravelPolar\LaravelPolar;

$sdk = LaravelPolar::sdk();

$wallets = $sdk->customerPortal->wallets->list(
    // pass a customer session token minted with LaravelPolar::createCustomerSession()
);

Creating a file

The facade exposes listFiles() for reading, but file creation goes through the SDK directly:

$sdk = LaravelPolar::sdk();

$file = $sdk->files->create(
    // see the Polar PHP SDK docs for the full request shape
);

Updating an organization

$sdk = LaravelPolar::sdk();

$org = $sdk->organizations->update(
    id: 'org_xxx',
    // organizationUpdate payload
);

OAuth2 flows

$sdk = LaravelPolar::sdk();

// Access the full OAuth2 resource group:
$sdk->oauth2->...;

---

Using sdk() in a service class

A common pattern is to inject a service that calls LaravelPolar::sdk() internally, keeping SDK calls out of your controllers:

namespace App\Services;

use Danestves\LaravelPolar\LaravelPolar;
use Polar\Polar;

class PolarFileService
{
    private Polar $sdk;

    public function __construct()
    {
        $this->sdk = LaravelPolar::sdk();
    }

    public function uploadFile(string $name, string $path): mixed
    {
        return $this->sdk->files->create(
            // your file creation payload
        );
    }

    public function deleteFile(string $fileId): void
    {
        $this->sdk->files->delete(id: $fileId);
    }
}

---

Testing with a mock SDK

The package exposes two testing helpers so you can swap the SDK instance in tests without hitting the real API:

use Danestves\LaravelPolar\LaravelPolar;

// Inject a mock:
LaravelPolar::setSdk($mockSdk);

// Reset back to null so the next call re-builds from config:
LaravelPolar::resetSdk();

Use setSdk() in your test setUp to provide a pre-configured mock or fake, and resetSdk() in tearDown to clean up.

use Danestves\LaravelPolar\LaravelPolar;
use Tests\TestCase;

class PolarFileServiceTest extends TestCase
{
    protected function setUp(): void
    {
        parent::setUp();
        LaravelPolar::setSdk($this->createMock(\Polar\Polar::class));
    }

    protected function tearDown(): void
    {
        LaravelPolar::resetSdk();
        parent::tearDown();
    }

    public function test_it_uploads_a_file(): void
    {
        // your test assertions
    }
}

---

Further reading

• Polar PHP SDK on GitHub — full list of available namespaces, request types, and response shapes.
• LaravelPolar facade reference — all methods the facade wraps, so you know what is already covered.