# Apple Wallet

## Overview

The Apple Wallet Order Tracking integration is designed to work via direct API calls after an order is placed. When the correct identifiers and tracking data are sent, the Apple Wallet pass is automatically created and updated. This implementation provides a flexible setup for retailers that require API-first solutions (that is: headless integrations) for order tracking and customer notifications.

## Apple Wallet Order Tracking Integration

{% hint style="info" %}
For more information on the requirements for configuring this integration, see our [Apple Wallet Order Tracking documentation](/docs/platform/app-store/apple-wallet.md).
{% endhint %}

The following steps outline the process for the Apple Wallet Order Tracking integration.

{% stepper %}
{% step %}

### Order completed

* Customer completes checkout and pays.

{% hint style="info" %}
During Apple Pay completion, your shop system must call the `apple-wallet/order?orderNo=<orderNo>` endpoint to retrieve relevant data about the wallet pass.
{% endhint %}
{% endstep %}

{% step %}

### Send order data

* Retailer sends the required order metadata to the /apple-wallet/order endpoint.
  {% endstep %}

{% step %}

### Pass issued

* parcelLab creates or updates the Apple Wallet pass tied to the order.
  {% endstep %}

{% step %}

### Customer access

* The customer is notified via Apple Wallet and receives push updates as the order progresses.
  {% endstep %}
  {% endstepper %}

## Fetch Apple Wallet Order Data

Details of how the `apple-wallet/order?orderNo=<orderNo>` endpoint can be used to retrieve data with information for Apple Wallet order tracking are described below.

<details>

<summary><mark style="color:blue;">GET</mark> Fetch Apple Wallet Order Data</summary>

You can retrieve all relevant data to extend an Apple Wallet payment response with information for Apple Wallet order tracking with the `apple-wallet/order?orderNo=<orderNo>` endpoint.

{% hint style="warning" %}
You must set the `&orderNo=` URL search query parameter to your customer-facing order number.
{% endhint %}

#### API Details

<mark style="color:blue;">`GET`</mark> `https://api.parcellab.com/apple-wallet/order?orderNo=<orderNo>`

#### Header

| Name          | Value                                |
| ------------- | ------------------------------------ |
| user          | parcelLab account ID                 |
| token         | parcelLab API token with read access |
| content\_type | ‘application/json’                   |

#### Responses

* 200 - accepted

```json
{
    "orderTypeIdentifier": "<your specified id>",
    "orderIdentifier": "<account id:order number>",
    "webServiceURL": "https://api.parcellab.com/apple-wallet/status",
    "authenticationToken": "..."
}
```

* 400 - invalid request

```json
{
    "message": "Parameter &orderNo= is required",
    "code": "request.orderNo.invalid",
    "type": "invalid_request"
}
```

</details>

## Create or Update Apple Wallet Pass

Details of how the `apple-wallet/order` endpoint can be used to create or update an Apple Wallet pass for a given order are described below.

<details>

<summary><mark style="color:green;">POST</mark> Create or Update an Apple Wallet Pass</summary>

You can create or update a digital pass with the `apple-wallet/order` endpoint. Each call results in a new or updated pass being issued to the customer’s Apple Wallet.

The details of the Create or Update Apple Wallet Pass API are described in the following section.

#### API Details

<mark style="color:green;">`POST`</mark> `https://api.parcellab.com/apple-wallet/order`

#### Authentication

Authentication is handled via a signed token generated using your Apple private key.

{% hint style="warning" %}
You must sign the token using the private key associated with your Apple Developer certificate. For more information on getting started with the `apple-wallet/order` endpoint, please contact your parcelLab representative.
{% endhint %}

#### Request Body

| Name                | Type   | Description                                                                       |
| ------------------- | ------ | --------------------------------------------------------------------------------- |
| orderTypeIdentifier | string | Unique identifier for your order pass (for example: `order.com.yourbrand.store`). |
| orderIdentifier     | string | Unique identifier for the order (must match tracking events).                     |
| webServiceUrl       | string | Fixed endpoint: `https://api.parcellab.com/apple-wallet/order`.                   |
| authenticationToken | string | Signed JWT token using your Apple private key.                                    |

An example payload is displayed below to show the format for creating or updating an Apple Wallet pass for an order.

```json
{
"orderTypeIdentifier": "order.com.yourbrand.store",
"orderIdentifier": "123456",
"webServiceURL": https://api.parcellab.com/apple-wallet/order,
"authenticationToken": "<SIGNED_AUTH_TOKEN>"
}
```

#### Responses

* 200 - accepted

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.parcellab.com/docs/developers/v2/status-updates/apple-wallet.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.