Sell Through Polar as Merchant of Record

Selling digital downloads worldwide means collecting and filing sales tax and VAT in places you’ve never been. Most small stores either ignore it and hope, or pay an accountant more than the sales are worth.

Polar is a merchant of record: it sells to the buyer, works out the tax and remits it. The Polar module connects it to Easy Digital Downloads. Buyers pay on Polar’s hosted checkout, and the order, renewals, refunds and cancellations stay in step with EDD through signed webhooks.

Turn On the Gateway

1. Switch on the Polar module under Stackless → Dashboard.
2. Add your access token and webhook secret under Stackless → Settings → Polar and save.
3. Go to Downloads → Settings → Payments and switch on Polar (Stackless) under Active Gateways. Save.

Polar stays off the checkout until the current mode has an access token.

Add Your Access Tokens

Create an organization access token in Polar → Settings → General → Developers with these scopes:

products:read, products:write, checkouts:read, checkouts:write, orders:read, refunds:read, refunds:write, subscriptions:read, subscriptions:write, organizations:read

Then fill in:

• Sandbox: on by default. Uses the Polar sandbox, so no real money moves. Sandbox tokens come from sandbox.polar.sh with the same scopes. This switch is separate from EDD’s Enable Test Mode.
• Live access token and Live webhook secret
• Sandbox access token and Sandbox webhook secret

When you save, Stackless looks up the organization for each token and shows “Connected to [organization].” If you switch a token to a different organization, the Polar products remembered for that environment are cleared. With the gateway switched on, a missing token or webhook secret for the selected environment shows an error.

You can also set these as wp-config.php constants, which win over saved settings: STACKLESS_EDD_POLAR_LIVE_ACCESS_TOKEN, STACKLESS_EDD_POLAR_LIVE_WEBHOOK_SECRET, STACKLESS_EDD_POLAR_SANDBOX_ACCESS_TOKEN and STACKLESS_EDD_POLAR_SANDBOX_WEBHOOK_SECRET.

Connect the Webhook

In Polar, live and sandbox, open Settings → Webhooks and add an endpoint with the Raw format and this URL: https://yoursite.com/wp-json/stackless-edd/v1/polar/webhook. The settings screen shows your exact URL. Select these events:

order.paid
order.updated
order.refunded
refund.created
refund.updated
subscription.created
subscription.updated
subscription.active
subscription.canceled
subscription.uncanceled
subscription.revoked
subscription.past_due

Copy the endpoint secret into the matching webhook secret field. Webhooks confirm payments when a buyer closes the tab before coming back, record renewals, and bring refunds and cancellations made in Polar into EDD. Each delivery is signature-checked and applied once.

Set How Tax Works

Prices and tax has three options:

• Follow the buyer’s country (Polar default), which is the default
• Add tax on top of my prices
• My prices already include tax

Polar calculates sales tax and VAT itself. Turn off EDD taxes for downloads you sell through Polar, or buyers get taxed twice. The order note shows what Polar charged including tax.

What Buyers See

At checkout, Polar shows with the title “Card, Apple Pay or Google Pay (Polar)” and the description “You’ll finish paying on Polar’s secure checkout. Polar adds any sales tax or VAT for your location before you pay.” Both are editable. In sandbox mode, checkout adds “Sandbox mode: no real payment will be taken.”

Purchasing sends the buyer to Polar’s checkout with their email and name filled in. Polar discount codes are off, so Polar charges the EDD order total. After paying, the buyer comes back to your EDD success page.

Prices always come from EDD. If Polar reports a payment in a different currency or for a different amount, the order goes on hold with a note to check it in Polar.

Link Downloads to Polar

Editing a download shows a Polar products box. The download, or each price option when it has variable pricing, gets a Polar product (live) and a Polar product (sandbox) field with a Create in Polar button. A Polar billing choice sets what the button creates: One-time, Daily, Weekly, Monthly, Every 3 months, Every 6 months or Yearly.

You can leave the fields empty. Polar products are then created on the first sale and remembered per environment. A product you link by hand must use the same billing schedule as the download.

Subscriptions on Polar

Polar runs the renewal schedule for subscriptions it bills:

• Free trials work. The trial length is passed to Polar in days.
• When Polar charges a renewal, a paid EDD renewal order is created.
• The next payment date follows Polar’s current period.
• Polar statuses map to Stackless ones: trialing becomes Trial, past due becomes On hold, canceled and revoked become Cancelled, unpaid becomes Expired, and “cancel at period end” becomes Pending cancellation.
• After the last payment of a fixed-length plan, Stackless tells Polar to stop at the end of the period.

Cancelling from the EDD admin or the customer account cancels at Polar too, either at the end of the paid period or straight away. If Polar doesn’t confirm, the cancellation is refused.

A subscription with the Renewal mode “Manual only (customer pays each renewal invoice)” isn’t billed by Polar. Its first order goes through Polar as a one-time payment, and each renewal can be paid the same way. See Subscription Products for the renewal mode.

Refunds

Refund from the EDD order screen and the refund is made in Polar. The refund form gets a Refund transaction in Polar box, ticked by default. Untick it to record the refund in EDD only. Refunds made in the Polar dashboard are recorded on the EDD order through the webhook.

More Than One Polar Organization

Polar can be duplicated for a second organization, each copy with its own tokens, products, orders and webhook URL ending in /webhook/copy2 and so on. See Duplicate a Payment Gateway.

Limits

• Polar takes one subscription per checkout, with no other items in the cart. Carts with only one-time items can be any size, and show in Polar as one store order.
• Polar charges the same amount every cycle, so a subscription with a signup fee or a discounted first payment can’t use Polar.
• Polar isn’t offered for carts it can’t take, or for currencies it doesn’t support.
• Polar doesn’t save cards in EDD. Customers can’t renew early, resume a pending cancellation, switch renewal mode or change the payment method from their account, and you can’t change the next payment date.
• Turn on Debug log to write Polar activity to Downloads → Tools → Debug Log, tagged stackless-edd-polar_gateway, while EDD debug mode is on. Tokens are never logged.