=== AddToWallet for Sugar Calendar ===
Contributors: lakshayaddtowallet
Tags: sugar calendar, event tickets, wallet, apple wallet, google wallet
Requires at least: 5.8
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 2.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Turn every Sugar Calendar ticket into an Apple or Google Wallet pass, so attendees carry
their ticket on their phone.

== Description ==

Someone gets tickets to your event, and Sugar Calendar's ticket receipt offers them
**Add to Apple Wallet** and **Add to Google Wallet** buttons, right under their order.
Every ticket on the order gets its own pass, with the attendee's name, the event, the date,
time and location, and a barcode carrying the same ticket code Sugar Calendar prints on
the ticket and in the ticket email.

Works with free and paid tickets sold through Sugar Calendar's own event ticketing, in
Sugar Calendar Lite and Pro.

= Design the pass =

The *Pass design* tab is a visual editor with a live Apple Wallet and Google Wallet
preview, front and back, filled in with your latest ticket.

* Your business name, logo and colour.
* A header line, the pass title and up to three fields on the front.
* Sections on the back: text, links, phone numbers, email addresses and addresses.
* "+ Data Field" puts each ticket's details on the pass: the attendee's name, the event,
  ticket type, date, start and end time, venue or location and its address, event page,
  ticket code, ticket and order numbers, price paid and more.
* A hero image, with a different image per event if you like.
* The barcode format, and a Wallet reminder before the event.

= How it works =

* The buttons appear on Sugar Calendar's ticket receipt page, under the order. To place
  them yourself, put the `[atw_sc_wallet_passes]` shortcode on that page.
* An order for several tickets gets one pass per ticket, each labelled with the attendee's
  name, because each person needs their own barcode at the door.
* The passes are created on your server with your AddToWallet API key. The key never
  reaches your visitors' browsers.
* The browser sends only the receipt link Sugar Calendar itself gave the buyer, and the
  ticket details are read from Sugar Calendar, so nobody can create a pass for someone
  else's order or put made-up details on one. Like the receipt, it works for as long as
  Sugar Calendar keeps that link valid (72 hours, then it emails a fresh one).
* Reloading or sharing the receipt never creates a second pass for the same ticket.

= Refunds, deleted tickets and changes =

When an order is refunded or moved to the trash, when a ticket is trashed or deleted, or
when the event is deleted, the pass in the attendee's wallet is marked expired straight
away. When the event moves, changes location, or anything else on the pass changes, the
pass is updated to match, without using another credit. This all happens on your server,
from Sugar Calendar's own notifications, with a check every ten minutes for anything
changed some other way. You choose which of these expire a pass on the Settings tab.

= Requirements =

* Sugar Calendar (Lite or Pro) 3.12 or later, selling tickets, with a Payment Success Page
  set (Sugar Calendar › Settings › Payments). Sugar Calendar creates one when ticketing is
  first set up.
* An AddToWallet account and API key

= Coming from the 1.0 zip? =

AddToWallet for Sugar Calendar 1.0 (folder `sugar-calendar-addtowallet`) was handed out as
a download. This plugin installs into a new folder, so WordPress treats it as a separate
plugin. When you activate it, it copies your 1.0 settings and the record of every pass 1.0
issued, and from then on it creates, updates and expires the passes. Then deactivate and
delete the 1.0 plugin. Until you do, it stays switched off and you will see a reminder. A
receipt page using the 1.0 `[sugar_calendar_addtowallet]` shortcode keeps working.

== Frequently Asked Questions ==

= Which tickets get a pass? =

Every ticket on a Paid order, free tickets included: Sugar Calendar marks an order Paid
when checkout completes. You can also issue passes for orders you set to Pending, though
they may never be paid.

= No buttons appear. What should I check? =

* Sugar Calendar has no Payment Success Page (Sugar Calendar › Settings › Payments), so
  buyers never see a receipt. The Settings tab warns about this.
* You are out of AddToWallet credits.
* The order has a status you do not issue passes for.
* The receipt link is more than 72 hours old. Sugar Calendar emails the buyer a fresh one,
  and the buttons work there.

The *Tickets & passes* tab lists every ticket and whether it received a pass.

= Do RSVPs get a pass? =

Not in this version: passes are issued for tickets, free or paid.

= What does the barcode scan as? =

The ticket code Sugar Calendar prints on the ticket and in the ticket email, so staff can
compare the two at the door.

= Does expiring a pass refund the credit? =

No. Each pass costs one credit when it is created.

== External services ==

This plugin connects to the AddToWallet API at https://app.addtowallet.co to create,
update and expire Apple Wallet and Google Wallet passes. Without this service it cannot
issue passes.

* When you save an API key, the plugin checks it by reading your credit balance
  (`/api/payment/usage`), sending only the key. The balance is read again when you open the
  Settings tab.
* When an order's receipt page loads and the order qualifies, the plugin sends the details
  you put on each ticket's pass from your server to AddToWallet (`/api/card/create`). With
  the default design that is the attendee's name, the event name, ticket type, date and
  time, the event's location and its page address, the ticket code (as the barcode), your
  site name and the site's admin email address, and the logo, image and colors you
  configured. The attendee's email address, the purchaser's name or the price are only
  sent if you add them to the pass design.
* When an order is refunded or trashed, a ticket is trashed or deleted, or an event is
  deleted, it sends the pass id and your logo so the pass can be expired; when the event or
  the ticket changes, it sends the pass id with the updated pass details
  (`/api/card/edit`).
* The Help tab's contact form sends the name, email address and message you type, plus your
  site address and the plugin version, to AddToWallet support (`/api/admin/contactus`),
  only when you press Send.

Every request to `/api/card/*` and `/api/payment/usage` carries your API key to
authenticate it. Your API key is never sent to the attendee's browser.

The service is provided by AddToWallet: [Terms of Service](https://addtowallet.co/terms/),
[Privacy Policy](https://addtowallet.co/privacy-policy/).

== Screenshots ==

1. Sugar Calendar's ticket receipt with Add to Google Wallet and Add to Apple Wallet buttons for each ticket.
2. Pass design: brand, front, back and hero image, with a live Apple Wallet and Google Wallet preview.
3. Tickets & passes: every ticket, with whether its wallet pass was issued, expired or failed.
4. Settings: which orders issue passes and what expires them, and the account's credit balance.

== Changelog ==

= 2.0.0 =
* First release on WordPress.org. Replaces the 1.0 zip: settings and issued passes are copied over on activation.
* New admin screen, with Pass design, Tickets & passes, Settings and Help tabs.
* Pass design: a visual editor with a live Apple Wallet and Google Wallet preview, front and back.
* Choose the business name, header line, pass title and up to three front fields, using "+ Data Field" to add ticket details: attendee, event, ticket type, date and time, location, ticket code and more.
* Add sections to the back of the pass: text, links, phone numbers, email addresses and addresses. By default the back has the location (opens a map), the event page and your email address.
* Hero image variations per event.
* Passes are now also expired when a ticket is trashed or deleted and when an event is deleted, as well as when an order is refunded or trashed. You choose which on the Settings tab.
* When an event moves, changes location or its details change, the passes already in wallets are updated, without using another credit.
* Choose which order statuses issue passes (Paid, and optionally Pending).
* Times on the pass are in the event's own time zone, and all-day events show no times.
* The Wallet reminder before the event can be switched off.
* Passes are created as soon as the receipt loads. The 1.0 setting to wait for a click is gone.
* The API key is checked with AddToWallet before it is saved.
* Tickets & passes shows why a pass could not be created (for example, no credits left), and when a pass was updated, expired (and why) or failed to update or expire.

= 1.0.0 =
* First release: wallet buttons on the Sugar Calendar receipt, one pass per ticket, barcode carrying Sugar Calendar's own ticket code, expiry on refund and trash.

== Upgrade Notice ==

= 2.0.0 =
Replaces the AddToWallet for Sugar Calendar 1.0 zip. Activate this plugin, check your settings were copied over, then deactivate and delete the old plugin (folder sugar-calendar-addtowallet).
