# About Updating Wallet Passes

Pass updates are an integral piece of your mobile wallet campaign strategy. Once a wallet pass is installed on a user's device, send content updates that make sense for the campaign's lifecycle.

## Updating Pass Information

After a user installs a pass, you can seamlessly update the pass as the user accrues loyalty points, uses some of their gift card balance, or event information changes, so that your users are always up to date.

<!-- update passes vs adaptive links? -->

By updating an already-installed pass, you help ensure that your customers never miss their gates, and that they take advantage of the loyalty programs that bring them back to your business.

When you update passes and adaptive links, you only need to provide the individual fields that you want to update.

**Update pass**

```http
PUT /v1/pass/12345/ HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json

{
  "fields": {
    "points": {
      "value": "98765"
    }
  }
}
```


### Update Passes After Updating a Template

<!-- is publish apple only? Do we auto/immediately publish new field/deleted field changes when you update a template? -->

If you change your template, you can "publish" an update to your template to update passes for all of your pass holders. This makes it easy to update the look and feel of your passes with a single operation. You can also update fields on your template when you publish changes, but you should take care when updating fields that might be personalized. If you update a field that has already been personalized for individual pass holders, you'll erase pass holders' personalized information when you publish changes to your template.

> **Note:** If you add or remove fields from a template, Airship automatically publishes your changes to relevant passes generated from a template


[Learn how to publish changes to templates](https://www.airship.com/docs/guides/wallet/user-guide/updating-passes/publish/).

### Updating Flights and Events

You can manage flights and events independently of boarding passes and event tickets respectively, making it much easier to update pass holders when their flights or events change.

> **Note:** <p>For Google <a href="https://www.airship.com/docs/guides/wallet/user-guide/create-links/flights-boarding-passes/">Boarding Passes</a>, Google automatically notifies holders when departureGate, departureTerminal, departureTime, or boardingTime are updated. These are independent of any notifications you send through Airship.</p>


You can also use `passGroups` to update a group of flights or events — e.g. for a flight with multiple stops.

Airship recommends using the [FlightsAPI](https://www.airship.com/docs/developer/rest-api/wallet/operations/flights/) to perform updates to individual flights. The [Update endpoint](https://www.airship.com/docs/developer/rest-api/wallet/operations/flights/#updateflight) will update the flight and trigger the bulk pass update behavior if any details for the flight have changed. If flight details change frequently, Airship recommends batching these updates into periodic calls at regular, well-spaced intervals.

**Update a flight**

```http
PUT /v1/flights/project/<projectId>/<flightId> HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json

{
    "fields": {
        "departureGate": {
            "value": "21"
        },
        "boardingTime": {
            "value": "2018-07-30T09:20:00"
        },
        "departureTime": {
            "value": "2018-07-30T09:45:00"
        },
        "arrivalTime": {
            "value": "2018-07-30T11:45:00"
        },
        "passGroups": [
            "sfo-pdx-20180730"
        ]
    }
}
```


### Tags and Pass Organization

You can assign tags to passes, to organize groups of passes and pass holders. You can target tags in the wallet API to change a group of passes.

**Update passes by tag**

```http
PUT /v1/tag/tag-name/passes HTTP/1.1
Authorization: Basic <Base64 key>
Content-Type: application/json
Api-Revision: 1.2

{
    "fields": {
        "secondary1": {
            "value": "12/31/2013"
        },
        "primary1": {
            "value": "$2 Off"
        }
    }
}
```


### Recommended Use

After users install your pass, update the pass with values and notifications
relevant to where users are in the campaign's lifecycle.

#### Pass Type: Loyalty

**Scenario:** Tier Upgrade

| Step | Update the pass when... | New content for the pass |
|  --- |  --- |  --- |
| 1 | A user hits a new point tier. | Point balanceStrip imageNotification: New point balance and tier status |
| 2 | A user hits the next point tier — go back to step 1! |


#### Pass Type: Coupon

**Scenario:** Sale offers

| Step | Update the pass when... | New content for the pass |
|  --- |  --- |  --- |
| 1 | A sale starts | Validate the pass |
| 2 | Pass expiration is impending | Notification: Warning about expiration, which drives people to stores |
| 3 | A sale ends | Expire the passAdd image that tells the user to watch for new offers |
| 4 | You have a new offer — go back to step 1! |


#### Pass Type: Event Ticket

**Scenario:** Event details: session content, address, resources, contest results

Airship recommends using the [Events API](https://www.airship.com/docs/developer/rest-api/wallet/operations/events/) to perform updates to individual events. The [Update endpoint](https://www.airship.com/docs/developer/rest-api/wallet/operations/events/#updateevent) will update the event and trigger the bulk pass update behavior if any details for the event have changed. If event details change frequently, Airship recommends batching these updates into periodic calls at regular, well-spaced intervals.

| Step | Update the pass when... | New content for the pass |
|  --- |  --- |  --- |
| 1 | A user's next session is starting soon | Notification: Upcoming session time and location, and contest enrollment |
| 2 | A user's session ended | Notification: Attendance thank you, and contest results |
| 3 | Next session — go back to step 1! |
| 4 | You have an announcement | Notification: Festival news, or about events related to previously attended sessions |
| 5 | You have a VIP event | Invitation to VIP event |


### Use Cases

**Simple**

> * Loyalty: Upgraded tier
> * Coupon: Sales offer
> * Gift Card: Balance change
> * Member Card: Renewal reminder
> * Event Ticket: Seat assignment
> * Boarding Pass: Gate change

**Common**

> * Send alerts and additional information based on tags or location changes.
> * Modify values, with or without an alert.
> * Add generic locations or beacons to a pass via the UI (up to ten locations or beacons).

**Complex**

> * Personalize with user-specific location or beacons tied to the pass (not supported by all passes).
> * Add/remove segmentation properties for a pass.
> * Change barcode type and/or value.


### Considerations

Consider these three things for each update, and you'll know your pass holders
are getting the right changes.

1. **AUDIENCE:** Make sure you are updating via the appropriate endpoint.
   * [Update a single pass](https://www.airship.com/docs/developer/rest-api/wallet/operations/passes/#updatepass):
      `/v1/pass/{id}`.
   * [Update a single pass with external ID](https://www.airship.com/docs/developer/rest-api/wallet/operations/passes-with-external-ids/#updatepassexternalid):
      `/v1/pass/id/{externalId}`.
   * [Update a pass with external ID for a single template](https://www.airship.com/docs/developer/rest-api/wallet/operations/passes-with-external-ids/#updatepassfromtemplateexternalid):
      `/v1/pass/template/{templateId}/id/{passExternalId}`.
   * [Update passes with a specific tag](https://www.airship.com/docs/developer/rest-api/wallet/operations/tags/#updatepassesfortags):
      `/v1/tag/{tag}/passes`, where `tag` is a specific tag.
   * [Update passes by segment](https://www.airship.com/docs/developer/rest-api/wallet/operations/segments/#updatepassesbysegment):
      `/v1/segments/{projectId}/{segmentId}/passes`.
   * [Update all passes for a template (Bulk Update)](https://www.airship.com/docs/developer/rest-api/wallet/operations/templates/#updatepassesbytemplate):
      `v1/template/{templateId}/passes`, where `templateId` is the template ID
      for which the bulk update is being done. You may alternatively supply an
      external ID for the passes, `passExternalId`.
      Bulk update via the API is essentially the same as using
      [Publish](https://www.airship.com/docs/guides/wallet/user-guide/updating-passes/publish/) in the dashboard, but the API has
      more options.
   * [Update a pass with external ID that was created from an adaptive link](https://www.airship.com/docs/developer/rest-api/wallet/operations/adaptive-links-with-external-ids/#updatepassesexternalid):
      `v1/links/adaptive/{adaptiveLinkId}/passes/id/{passExternalId}`.
   * [Update a pass with external ID that was created from an adaptive link in a specific project](https://www.airship.com/docs/developer/rest-api/wallet/operations/adaptive-links-with-external-ids/#updatepassesfromadaptivelinkexternalid):
      `v1/links/adaptive/project/id/{projectExternalId}/id/{adaptiveLinkExternalId}/passes/id/{passExternalId}`. 
1. **GENERIC vs. PERSONALIZED**
   * Are you updating a *generic pass*, where all pass holders have the same content? Go for it.
   * Are you updating *personalized passes*? If so, make sure you aren't replacing values for *all pass holders* that are pass holder-specific.
1. **TEST:** Use a test template and confirm the changes before updating your users'
   passes. Already confident with test templates? You may want to use a test
   tag instead.

See
[API: Passes: Update Pass](https://www.airship.com/docs/developer/rest-api/wallet/operations/passes/#updatepass) for
the full documentation.