Introduction

The CherryPie API allows even more automation and integration of passes into your system. Use these tools to create and update your mobile wallet campaigns, templates, and passes. If you cannot find a method to achieve your objective or are struggling to use the API, please contact our support team with any questions you may have.

This documentation currently only provides information on how to use the API in shell. Let us know which language you would like us to provide SDKs and documentation for next.

Authorization

JSON Web Tokens

Your JWT token needs to conform to this structure:

{
    "Header": {
        "alg": "HS256",
        "typ": "JWT"
    },
    "Payload": {
        "key": "your_api_key",
        "exp": 1437523200
    }
}

The token must be signed with your API secret

CherryPie uses JSON web tokens (JWT) to authorize your requests. A number of libraries to help generate your JWT, as well as a JWT debugging tool, can be found at jwt.io.

The JWT needs to be encrypted with the HS256 algorithm (which should be noted in the token headers) and it must be signed with your API secret.

The JWT payload required in CherryPie’s API is:

• key - This is your API key
• exp - This the token’s expiry time

It is important that the expiry time must be in the Unix time format and no more than one minute in the future, otherwise it will not be accepted it as a valid authorization. You can check the format for generating a JWT for authorization with this helper tool.

Authorizing Requests

To authorize, use this code:

# With shell, you need to provide a valid JSON web token with each request

curl "api_endpoint_here"
  -H "Authorization: PKAuth json_web_token"

Make sure to replace json_web_token with your generated token.

All of the requests to via the API need to be authorized. This means that you will need to generate a new JWT with each request.

Once the token is generated it needs to be added as a header with the prefix PKAuth.

The full http header looks like:

Authorization: PKAuth json_web_token

Campaigns

Campaigns are an important new feature of CherryPie. They allow for much more flexibility in the relationship between passes and templates. Before you can create templates and passes, you must create a campaign to link them all together.

Create a Campaign

curl https://api-pass.passkit.net/v2/campaigns
  -X POST
  -H "Authorization:PKAuth json_web_token"
  -H "Content-Type: application/json"
  -d '{
    "name": "campaignName",
    "passbookCertId": "Poxgb4dEJa",
    "status": "ACTIVE",
    "displayName": "Campaign Name",
    "description": "Campaign Description",
    "startDate": "2016-01-01T00:00:00Z",
    "maxIssue": 0
  }'

On success the api will respond with the Campaign Name in JSON format:

{
  "name": "campaignName"
}

HTTP Request

POST https://api-pass.passkit.net/v2/campaigns

JSON Body Parameters

Parameter	Data Type	Description
name	string	This is the reference name for your campaign, this will be used when referencing your campaign with the API in the future. The name must be alpha-numeric and cannot contain spaces. Note that this cannot be changed after the campaign is created, and each campaign must have a unique campaign name.
passbookCertId	string	This is the Certificate ID that you get when you upload a certificate, you can check which certificates you have uploaded with the list certificates endpoint. Note that the certificate cannot be changed after the campaign is created.
status	string	The value must be either ACTIVE, FROZEN, or INVALID. The campaign status controls whether passes can be issued or not. An ACTIVE campaign allows passes to be issued, both FROZEN and INVALID campaigns will not allow any passes to be issued. A FROZEN campaign can be set to ACTIVE again, however you cannot update an INVALID campaign.
displayName optional	string	This is the human friendly version of your campaign name, this will be displayed to customers when they are looking to download their pass.
description optional	string	This is the description of your campaign, this will be displayed to customers when they are looking to download their pass. Try to detail what all the templates in the campaign will offer to the customer.
startDate	ISO8601 datetime	This is the start date of your campaign. Before this time customers will not be able to download a pass for the campaign. Although this is a required parameter, you can always set the start date to be in the past. When submitting in json format, the value should be given as a string in the ISO8601 datetime format.
endDate (optional)	ISO8601 datetime	This is the end date of your campaign. After this time customers will not be able to download a pass for the campaign and all existing passes will be invalidated. When submitting in json format, the value should be given as a string in the ISO8601 datetime format.
maxIssue	integer	This is the maximum number of passes allowed to be issued within this campaign, this is used to help limit the number of passes created. If you do not want to limit number of passes within the campaign, simply set the value to 0.

Update a Campaign

curl https://api-pass.passkit.net/v2/campaigns/campaignName
  -X PUT
  -H "Authorization:PKAuth json_web_token"
  -H "Content-Type: application/json"
  -d '{
    "displayName": "New Display Name",
    "description": "New Campaign Description",
    "startDate": "2016-01-01T00:00:00Z",
    "endDate": "2017-01-01T00:00:00Z",
    "maxIssue": 0
  }'

On success the api will respond with the Campaign Name in JSON format:

{
  "name": "campaignName"
}

HTTP Request

PUT https://api-pass.passkit.net/v2/campaigns/{campaignName}

URL Parameters

Parameter	Data Type	Description
campaignName	string	This is the reference name that you chose to give your campaign when you created it.

JSON Body Parameters

Parameter	Data Type	Description
status	string	The value must be either ACTIVE, FROZEN, or INVALID. The campaign status controls whether passes can be issued or not. An ACTIVE campaign allows passes to be issued, both FROZEN and INVALID campaigns will not allow any passes to be issued. A FROZEN campaign can be set to ACTIVE again, however you cannot update an INVALID campaign.
displayName optional	string	This is the human friendly version of your campaign name, this will be displayed to customers when they are looking to download their pass.
description optional	string	This is the description of your campaign, this will be displayed to customers when they are looking to download their pass. Try to detail what all the templates in the campaign will offer to the customer.
startDate	ISO8601 datetime	This is the start date of your campaign. Before this time customers will not be able to download a pass for the campaign. Although this is a required parameter, you can always set the start date to be in the past. When submitting in json format, the value should be given as a string in the ISO8601 datetime format.
endDate (optional)	ISO8601 datetime	This is the end date of your campaign. After this time customers will not be able to download a pass for the campaign and all existing passes will be invalidated. When submitting in json format, the value should be given as a string in the ISO8601 datetime format.
maxIssue	integer	This is the maximum number of passes allowed to be issued within this campaign, this is used to help limit the number of passes created. If you do not want to limit number of passes within the campaign, simply set the value to 0.

Retrieve a Campaign

To retrieve a campaign, a GET HTTP request is needed

curl https://api-pass.passkit.net/v2/campaigns/campaignName
  -X GET
  -H "Authorization:PKAuth json_web_token"

Example of server response:

{
    "index": "OABd6Q4X",
    "name": "campaignName",
    "passbookCertId": "Poxgb4dEJa",
    "status": "ACTIVE",
    "startDate": "2016-01-01T00:00:00Z",
    "endDate": "2017-01-01T00:00:00Z",
    "createdAt": "2016-03-09T06:31:02.792548789Z",
    "updatedAt": "2016-03-09T07:10:49.350777006Z",
    "displayName": "Campaign Name",
    "description": "Campaign Description",
    "whiteLabel": {},
    "maxIssue": 0,
    "issued": 0
}

HTTP Request

GET https://api-pass.passkit.net/v2/campaigns/{campaignName}

URL Parameters

Parameter	Data Type	Description
campaignName	string	This is the reference name that you chose to give your campaign when you created it.

JSON Response

Parameter	Data Type	Description
index	string	This is the index reference of your campaign.
name	string	This is the reference name that you chose to give your campaign when you created it.
passbookCertId	string	This is the Certificate ID of the certificate chosen for this campaign, you can check the specific certificate details with the retrieve certificate endpoint.
status	string	The campaign status controls whether passes can be issued or not. An ACTIVE campaign allows passes to be issued, both FROZEN and INVALID campaigns will not allow any passes to be issued. A FROZEN campaign can be set to ACTIVE again, however you cannot update an INVALID campaign.
startDate	ISO8601 datetime	This is the start date of your campaign. Before this time customers will not be able to download a pass for the campaign. Although this is a required parameter, you can always set the start date to be in the past.
endDate (optional)	ISO8601 datetime	This is the end date of your campaign. After this time customers will not be able to download a pass for the campaign and all existing passes will be invalidated.
createdAt	ISO8601 datetime	This is when your campaign was created.
updatedAt	ISO8601 datetime	This is when your campaign was last updated.
displayName	string	This is the human friendly version of your campaign name, this will be displayed to customers when they are looking to download their pass.
description	string	This is the description of your campaign, this will be displayed to customers when they are looking to download their pass. Try to detail what all the templates in the campaign will offer to the customer.
whiteLabel	WhiteLabelObject	This is used to customise the campaign landing page. At the moment this feature is only available via a custom implementation. Please contact us with any enquiries.
maxIssue	integer	This is the maximum number of passes allowed to be issued within this campaign, this is used to help limit the number of passes created. 0 means no limit.
issued	integer	This is total number of passes that have currently been issued for this campaign.

Apple Certificates

Certificates are required if you want to work with Apple Wallet. To generate a certificate you will need an apple developer account (why?). Certificates are used by Apple to verify the data that is being sent to them. Specifically for passes, apple has an identifier called the Pass Type ID. To work with Apple Wallet, you need a certificate generated from a Pass Type ID, signed with our Certificate Signing Request (CSR).

For detailed instructions on how to do this in the apple developer site, see sections 2-5 of our help post on the topic. To upload a certificate via the API you will need to download a CSR file via the API. You can then use this to generate the certificate at developer.apple.com, which should then be uploaded with the API.

Generate CSR

curl https://api-pass-staging.pk-rocks.com/v2/passbookCsrs
  -X POST
  -H "Authorization:PKAuth json_web_token"
  -o /path/to/download.csr

# Using -o with cURL to download the csr file to a specific location and name.

HTTP Request

POST https://api-pass.passkit.net/v2/passbookCsrs

Upload Certificate

To upload a certificate, the request must be sent via multipart form

json = '{
    "name": "My Certificate",
    "description": "The certificate I created"
}'

curl https://api-pass.passkit.net/v2/campaigns
  -X POST
  -H "Authorization:PKAuth json_web_token"
  -F "passbookPEM=@certificate.cer"
  -F "jsonBody=$json"

The above request will return the Certificate ID (generated by PassKit) in JSON format:

{
  "id": "Poxgb4dEJa"
}

HTTP Request

POST https://api-pass.passkit.net/v2/passbookCerts

Multipart Form Parameters

Uploading a certificate file is done via multipart form, the attachments are:

Parameter	Type	Description
passbookPEM	CER file	This is the certificate file, it needs to be in CER format
jsonBody	JSON string	This field is optional and contains the name and description for the certificate

JSON Body Parameters

Parameter	Data Type	Description
name (optional)	string	This is the name of your certificate, this is only used to help you identify the certificate
description (optional)	string	This is the description of your certificate, this is only used to help you identify the certificate

Retrieve Certificate Information

curl https://api-pass.passkit.net/v2/passbookCerts/Poxgb4dEJa
  -X GET
  -H "Authorization:PKAuth json_web_token"

The above request will return the certificate information in JSON format:

{
  "id": "Poxgb4dEJa",
  "passTypeId": "pass.com.example.app",
  "name": "My Certificate",
  "description": "The certificate I created",
  "validFrom": "2015-08-06T05:19:21Z",
  "validUntil": "2016-08-05T05:19:21Z",
  "teamName": "YourCompany",
  "teamCode": "YourCompanyCode",
  "createdAt": "2016-01-08T11:32:52.57531013Z",
  "updatedAt": "2016-01-08T11:32:52.575311554Z"
}

HTTP Request

GET https://api-pass.passkit.net/v2/passbookCerts/{certificateId}

URL Parameters

Parameter	Data Type	Description
certificateId	string	This is the Certificate ID returned when you upload a certificate

JSON Response

Parameter	Data Type	Description
id	string	This is the Certificate ID returned when you upload a certificate
passTypeId	string	This is the the pass type id that you registered with Apple
name (optional)	string	This is the name of your certificate, this is only used to help you identify the certificate
description (optional)	string	This is the description of your certificate, this is only used to help you identify the certificate
validFrom	ISO8601 datetime	This is date that your certificate is valid from.
validUntil	ISO8601 datetime	This is date that your certificate is valid until.
teamName	string	This is your Apple developer account team name.
teamCode	string	This is your Apple developer account team code.
createdAt	ISO8601 datetime	This is when your certificate was uploaded.
updatedAt	ISO8601 datetime	This is when your certificate was last updated.

List Your Certificates

curl https://api-pass.passkit.net/v2/passbookCerts
  -X GET
  -H "Authorization:PKAuth json_web_token"

The above request will return an array of certificate information in JSON format:

[
  {
    "id": "Poxgb4dEJa",
    "passTypeId": "pass.com.example.app",
    "name": "My Certificate",
    "description": "The certificate I created",
    "validFrom": "2015-08-06T05:19:21Z",
    "validUntil": "2016-08-05T05:19:21Z",
    "teamName": "YourCompany",
    "teamCode": "YourCompanyCode",
    "createdAt": "2016-01-08T11:32:52.57531013Z",
    "updatedAt": "2016-01-08T11:32:52.575311554Z"
  }
]

HTTP Request

GET https://api-pass.passkit.net/v2/passbookCerts

JSON Response

The response is similar to the one for retrieving a single certificate, but will instead contain an array of this information, one object for each certificate.

Templates

Create a Template

To create a template, image files are required, therefore this request must be sent via multipart form

templateBody='{
    "name": "templateName",
    "campaignName": "campaignName",
    "status": "ACTIVE",
    "language": "en",
    "startDate": "2010-08-01T00:00:00Z",
    "maxIssue": 0,
    "dynamicKeys": [
        {
            "key": "points",
            "type": "string",
            "defaultValue": null,
            "isEditable": true
        }
    ],
    "passbook": {
        "type": "generic",
        "orgName": "Organisation Name",
        "desc": "Basic description of the template.",
        "assoStoreId" : [967907684],
        "bgColor": {
            "red": 245,
            "green": 244,
            "blue": 244
        },
        "labelColor": {
            "red": 22,
            "green": 88,
            "blue": 168
        },
        "fgColor": {
            "red": 53,
            "green": 153,
            "blue": 219
        },
        "header": [
            {
                "changeMsg": "Your new point balance is %@",
                "defaultLabel": "Points",
                "defaultValue": "#{points}",
                "textAlign": "right",
                "format": {
                    "type": "number",
                    "numberFormat": "decimal"
                }
            }
        ],
        "secondary": [
            {
                "defaultValue": "Hello",
                "textAlign": "left",
                "format": {
                    "type": "text"
                }
            }
        ],
        "back": [
            {
                "defaultLabel": "Find us",
                "defaultValue": "contact.example.com",
                "format": {
                    "type": "text"
                }
            },
            {
                "defaultLabel": "Customer Service Number",
                "defaultValue": "1234567",
                "format": {
                    "type": "text"
                }
            }
        ]
    },
    "passbookLang": {
        "fr": {
            "text": {
                "Hello": "Bonjour"
            }
        }
    }
}'

curl https://api-pass.passkit.net/v2/templates
  -X POST
  -H "Authorization:PKAuth json_web_token"
  -F "passbook-IconFile=@icon.png"
  -F "passbook-StripFile=@strip.png"
  -F "passbook-fr-StripFile=@strip-fr.png"
  -F "jsonBody=$templateBody"

On success the api will respond with the Template Name in JSON format:

{
  "name": "templateName"
}

HTTP Request

POST https://api-pass.passkit.net/v2/templates

Multipart Form Parameters

Creating a campaign requires a certificate file to be uploaded at the same time so this request is sent as multipart form. The parameters required are as follows

Parameter	Type	Description
passbook-{imageType}	image file	These are the image files for the default Apple Wallet template and any alternate languages, see the image type section for a list of possible image types and their required format. Only the passbook-IconFile is required to create a template, other images are optional.
passbookRedeem-{imageType}	image file	These are the image files for the redeemed design of the Apple Wallet template and any alternate languages, see the image type section for a list of possible image types and their required format. Only the passbookRedeem-IconFile is required to create a redeemed template, other images are optional.
jsonBody	JSON string	This is the json object defining the template, see the JSON Body Parameters below for information on the structure.

JSON Body Parameters

Parameter	Data Type	Description
name	string	This is the reference name for your template, this will be used when referencing your template with the API in the future. The name must be alpha-numeric and cannot contain spaces. Note that this cannot be changed after the template is created, and each template must have a unique template name.
campaignName	string	This is the reference name that you chose to give your campaign when you created it.
status	string	The value must be either ACTIVE, FROZEN, or INVALID. The template status controls whether passes can be issued or not. An ACTIVE template allows passes to be issued, both FROZEN and INVALID templates will not allow any passes to be issued. A FROZEN template can be set to ACTIVE again, however you cannot update an INVALID template.
language	string	This defines the template’s default language. See the languages list for a list of supported languages.
startDate	ISO8601 datetime	This is the start date of your template. Before this time customers will not be able to download any pass. Although this is a required parameter, you can always set the start date to be in the past. When submitting in json format, the value should be given as a string in the ISO8601 datetime format.
endDate (optional)	ISO8601 datetime	This is the end date of your template. After this time customers will not be able to download a pass for the campaign and all existing passes will be invalidated. When submitting in json format, the value should be given as a string in the ISO8601 datetime format.
maxIssue	integer	This is the maximum number of passes allowed to be issued within this template, this is used to help limit the number of passes created. If you do not want to limit number of passes within the template, simply set the value to 0.
timezone (optional)	float32	The timezone format should be a number such as -10, 5.5, etc (-10 = -10:00, 5.5 = +05:30)
dynamicKeys (optional)	an array of dynamic keys	Contains the information about which dynamic keys will be replaced in the template. When designing the template, to use a dynamic key, just insert the field as #{key} into the template design. It will then get replaced when the pass is built. In the example json the dynamic field “points” has been included, you can see the field in the dynamic key section and being used in the template design.
passbook	Apple Wallet template	This is the design of the template for Apple Wallet. You must provide this to create a template. The Apple Wallet Template section has more detail on the stucture. The json example contains a basic template example.
passbookRedeem (optional)	Apple Wallet template	This is the design of the template for Apple Wallet after the pass has been redeemed. This design is optional and is what will be displayed when a pass is updated with isRedeemed set to true. The Apple Wallet Template section has more detail on the stucture. The json example contains a basic template example, this could be reused in the redeem section with small changes to let the customer know the pass has been redeemed.
passbookLang (optional)	passbook language object	You can use this field to define translations for your pass in multiple languages. The passbook language section provides more detail on the structure but a basic example is provided in the example json.
passbookLangRedeem (optional)	passbook language object	You can use this field to define translations for the redeemed version of your pass in multiple languages. The passbook language section provides more detail on the structure which is the same as passbookLang.

Retrieve a Template

Example of JSON body response to a GET request to retrieve a template.

> curl https://api-pass.passkit.net/v2/templates
  -X GET
  -H "Authorization:PKAuth json_web_token"
  -F "passbookPEM=@certificate.pem"
  -F "jsonBody=$templateJson"

{
    "index": "789oyiu",
    "name": "GREATNAME",
    "campaignName": "nameoftheCampaign",
    "status": "ACTIVE",
    "language": "en",
    "startDate": "2010-08-01T00:00:00Z",
    "createdAt": "2016-03-01T03:43:17.918425687Z",
    "updatedAt": "2016-03-01T03:43:17.918426641Z",
    "timezone": 0,
    "maxIssue": 0,
    "dynamicKeys": [{
        "key": "memberPoints",
        "type": "number",
        "defaultValue": null,
        "isEditable": false
    }, {
        "key": "memberFirstName",
        "type": "string",
        "defaultValue": null,
        "isEditable": false
    }, {
        "key": "memberLastName",
        "type": "string",
        "defaultValue": null,
        "isEditable": false
    }, {
        "key": "memberId",
        "type": "string",
        "defaultValue": null,
        "isEditable": false
    }, {
        "key": "memberSince",
        "type": "string",
        "defaultValue": null,
        "isEditable": false
    }, {
        "key": "sequenceId",
        "type": "string",
        "defaultValue": null,
        "isEditable": false
    }],
    "dynamicImageKeys": {
        "passbook": {
            "background": {
                "isDynamic": false,
                "isEditable": false
            },
            "footer": {
                "isDynamic": false,
                "isEditable": false
            },
            "icon": {
                "isDynamic": false,
                "isEditable": false
            },
            "logo": {
                "isDynamic": false,
                "isEditable": false
            },
            "strip": {
                "isDynamic": false,
                "isEditable": false
            },
            "thumbnail": {
                "isDynamic": false,
                "isEditable": false
            }
        }
    },
    "passbook": {
        "type": "generic",
        "orgName": "Your amazing rewards",
        "desc": "\"Add\" to Wallet \u003e\u003e",
        "bgColor": {
            "red": 0,
            "green": 255,
            "blue": 119
        },
        "labelColor": {
            "red": 255,
            "green": 255,
            "blue": 255
        },
        "fgColor": {
            "red": 27,
            "green": 255,
            "blue": 60
        },
        "iconFile": "myiconfile.png",
        "logoFile": "mylogofile.png",
        "header": [{
            "changeMsg": "Your new point balance is %@. Thanks for choosing us",
            "defaultLabel": "Points",
            "defaultValue": "${memberPoints}",
            "textAlign": "left",
            "format": {
                "type": "number",
                "numberFormat": "decimal"
            }
        }],
        "primary": [{
            "defaultLabel": "Name",
            "defaultValue": "${memberFirstName} ${memberLastName}",
            "format": {
                "type": "text"
            }
        }],
        "auxiliary": [{
            "changeMsg": "You're doing great!",
            "defaultLabel": "mylabel",
            "defaultValue": "myvalue",
            "textAlign": "",
            "format": {
                "type": "text"
            }
        }],
        "back": [{
            "defaultLabel": "Find a shop",
            "defaultValue": "book.example.com",
            "format": {
                "type": "text"
            }
        }, {
            "defaultLabel": "Customer Service",
            "defaultValue": "+1-076854937",
            "format": {
                "type": "text"
            }
        }],
        "secondary": [{
            "defaultLabel": "Member ID",
            "defaultValue": "${memberId}",
            "textAlign": "",
            "format": {
                "type": "text"
            }
        }, {
            "defaultLabel": "Member Since",
            "defaultValue": "${memberSince}",
            "textAlign": "right",
            "format": {
                "type": "text"
            }
        }]
    },
    "passbookLang": {
        "de": {
            "text": {
                "GREATNAME": "GREATNAME",
                "Company": "Firma",
                "Corporate Account ID": "Firmenkonto",
                "Customer Care": "Kundenservice",
                "Find a Shop": "Ladenverzeichnis",
                "Member ID": "Mitgliedsnummer",
                "Member Since": "Mitglied seit",
                "Partner": "Partner",
                "Platinum": "Platinum",
                "Points": "Punkte",
                "Program": "Programm",
                "Tier": "Status",
                "You are doing great!": "!",
                "Your new point balance is %@. Thanks for choosing Us!": "Sie tun ehrfürchtig!"
            }
        }
    },
    "issued": 105677,
    "pushed": 34690,
    "passbookDevices": 10546,
    "androidPayDevices": 11815,
    "alipayDevices": 8560
}

HTTP Request

GET https://api-pass.passkit.net/v2/templates/{templateId}

To retrieve a specific template you need to send a GET request to the server including the template id of the template you are retrieving. The JSON body response will contain the whole template, comprehensive of every value and attribute related to it.

On the right column you can see an example of a retrieved pass in English and German, you can identify some features such as the footer and icon image, as well as how many devices have that specific template.

You can basically see every piece of information related to that specific template.

Update a Template

curl https://api-pass.passkit.net/v2/templates/templateName
  -X PUT
  -H "Authorization:PKAuth json_web_token"
  -H "Content-Type: application/json"
  -d '{
    "passbook": {
      "bgColor": {
        "red": 22,
        "green": 88,
        "blue": 168
      },
      "labelColor": {
        "red": 245,
        "green": 244,
        "blue": 244
      }
    }
  }'

On success the api will respond with the Template Name in JSON format:

{
  "name": "templateName"
}

If you want to update the images on a template you will need to use multipart form, as detailed in update a template with images. Otherwise, this version can be used to update any of the other template attributes.

HTTP Request

PUT https://api-pass.passkit.net/v2/templates/{templateName}

URL Parameters

Parameter	Data Type	Description
templateName	string	This is the reference name that you chose to give your template when you created it.

JSON Body Parameters

Parameter	Data Type	Description
status	string	The value must be either ACTIVE, FROZEN, or INVALID. The template status controls whether passes can be issued or not. An ACTIVE template allows passes to be issued, both FROZEN and INVALID templates will not allow any passes to be issued. A FROZEN template can be set to ACTIVE again, however you cannot update an INVALID template.
language	string	This defines the template’s default language. See the languages list for a list of supported languages.
startDate	ISO8601 datetime	This is the start date of your template. Before this time customers will not be able to download any pass. Although this is a required parameter, you can always set the start date to be in the past. When submitting in json format, the value should be given as a string in the ISO8601 datetime format.
endDate (optional)	ISO8601 datetime	This is the end date of your template. After this time customers will not be able to download a pass for the campaign and all existing passes will be invalidated. When submitting in json format, the value should be given as a string in the ISO8601 datetime format.
maxIssue	integer	This is the maximum number of passes allowed to be issued within this template, this is used to help limit the number of passes created. If you do not want to limit number of passes within the template, simply set the value to 0.
timezone (optional)	float32	The timezone format should be a number such as -10, 5.5, etc (-10 = -10:00, 5.5 = +05:30)
dynamicKeys (optional)	an array of dynamic keys	Contains the information about which dynamic keys will be replaced in the template. When designing the template, to use a dynamic key, just insert the field as #{key} into the template design. It will then get replaced when the pass is built. In the example json the dynamic field “points” has been included, you can see the field in the dynamic key section and being used in the template design.
passbook	Apple Wallet template	This is the design of the template for Apple Wallet. You must provide this to create a template. The Apple Wallet Template section has more detail on the stucture. The json example contains a basic template example.
passbookRedeem (optional)	Apple Wallet template	This is the design of the template for Apple Wallet after the pass has been redeemed. This design is optional and is what will be displayed when a pass is updated with isRedeemed set to true. The Apple Wallet Template section has more detail on the stucture. The json example contains a basic template example, this could be reused in the redeem section with small changes to let the customer know the pass has been redeemed.
passbookLang (optional)	passbook language object	You can use this field to define translations for your pass in multiple languages. The passbook language section provides more detail on the structure but a basic example is provided in the example json.
passbookLangRedeem (optional)	passbook language object	You can use this field to define translations for the redeemed version of your pass in multiple languages. The passbook language section provides more detail on the structure which is the same as passbookLang.

Update a Template With Images

templateBody='{
  "passbook": {
    "bgColor": {
      "red": 22,
      "green": 88,
      "blue": 168
    },
    "labelColor": {
      "red": 245,
      "green": 244,
      "blue": 244
    }
  }
}'

curl https://api-pass.passkit.net/v2/templates/templateName
  -X PUT
  -H "Authorization:PKAuth json_web_token"
  -F "passbook-IconFile=@icon-new.png"
  -F "jsonBody=$templateBody"

On success the api will respond with the Template Name in JSON format:

{
  "name": "templateName"
}

If you want to update the images on a template you will need to use multipart form. If you only want to update the other template attributes, you can use the simpler update template method.

HTTP Request

PUT https://api-pass.passkit.net/v2/templates/{templateName}

URL Parameters

Parameter	Data Type	Description
templateName	string	This is the reference name that you chose to give your template when you created it.

Multipart Form Parameters

Parameter	Type	Description
passbook-{imageType} (optional)	image file	These are the image files for the default Apple Wallet template and any alternate languages, see the image type section for a list of possible image types and their required format. Only the passbook-IconFile is required to create a template, other images are optional.
passbookRedeem-{imageType} (optional)	image file	These are the image files for the redeemed design of the Apple Wallet template and any alternate languages, see the image type section for a list of possible image types and their required format. Only the passbookRedeem-IconFile is required to create a redeemed template, other images are optional.
jsonBody (optional)	JSON string	This is the json object defining the template, see the JSON Body Parameters below for information on the structure.

JSON Body Parameters

Parameter	Data Type	Description
status	string	The value must be either ACTIVE, FROZEN, or INVALID. The template status controls whether passes can be issued or not. An ACTIVE template allows passes to be issued, both FROZEN and INVALID templates will not allow any passes to be issued. A FROZEN template can be set to ACTIVE again, however you cannot update an INVALID template.
language	string	This defines the template’s default language. See the languages list for a list of supported languages.
startDate	ISO8601 datetime	This is the start date of your template. Before this time customers will not be able to download any pass. Although this is a required parameter, you can always set the start date to be in the past. When submitting in json format, the value should be given as a string in the ISO8601 datetime format.
endDate (optional)	ISO8601 datetime	This is the end date of your template. After this time customers will not be able to download a pass for the campaign and all existing passes will be invalidated. When submitting in json format, the value should be given as a string in the ISO8601 datetime format.
maxIssue	integer	This is the maximum number of passes allowed to be issued within this template, this is used to help limit the number of passes created. If you do not want to limit number of passes within the template, simply set the value to 0.
timezone (optional)	float32	The timezone format should be a number such as -10, 5.5, etc (-10 = -10:00, 5.5 = +05:30)
dynamicKeys (optional)	an array of dynamic keys	Contains the information about which dynamic keys will be replaced in the template. When designing the template, to use a dynamic key, just insert the field as #{key} into the template design. It will then get replaced when the pass is built. In the example json the dynamic field “points” has been included, you can see the field in the dynamic key section and being used in the template design.
passbook	Apple Wallet template	This is the design of the template for Apple Wallet. You must provide this to create a template. The Apple Wallet Template section has more detail on the stucture. The json example contains a basic template example.
passbookRedeem (optional)	Apple Wallet template	This is the design of the template for Apple Wallet after the pass has been redeemed. This design is optional and is what will be displayed when a pass is updated with isRedeemed set to true. The Apple Wallet Template section has more detail on the stucture. The json example contains a basic template example, this could be reused in the redeem section with small changes to let the customer know the pass has been redeemed.
passbookLang (optional)	passbook language object	You can use this field to define translations for your pass in multiple languages. The passbook language section provides more detail on the structure but a basic example is provided in the example json.
passbookLangRedeem (optional)	passbook language object	You can use this field to define translations for the redeemed version of your pass in multiple languages. The passbook language section provides more detail on the structure which is the same as passbookLang.

Push Updates

curl https://api-pass.passkit.net/v2/templates/templateName/push
  -X PUT
  -H "Authorization:PKAuth json_web_token"

On success the api will respond with the Template Name in JSON format:

{
  "name": "templateName"
}

Updates to a template will not immediately be pushed out to all your customers. When you have made all the changes you want, you can actively push them out to your customers using this endpoint.

HTTP Request

PUT https://api-pass.passkit.net/v2/templates/{templateName}/push

Additional Information

Dynamic Key Structure

Example json:

    {
        "key": "points",
        "type": "number",
        "defaultValue": 100,
        "isEditable": false
    }

Parameter	Type	Description
key	string	This is the name used to reference your dynamic field. For example, if the key is “points”, you can reference it wherever you need it in the template as # {points}.
type	string	Can be either “dateTime”, “string” or “number”.
defaultValue	string or integer	The default value for the field that is used if no data is provided.
isEditable	boolean	Set to true if you want your customer to be able to edit the value of this dynamic field.

Passbook Language

The basic layout in json:

    {
        "lang1": {
            "text": {
                "Original Text1": "Language1 Translated Text1",
                "Original Text2": "Language1 Translated Text2"
            }
        },
        "lang2": {
            "text": {
                "Original Text1": "Language2 Translated Text1",
                "Original Text2": "Language2 Translated Text2"
            }
        }
    }

The basic layout of the passbook language object is shown to the right. The variables in the example are as follows:

Parameter	Type	Description
lang	string	lang1 and lang2 in the example should be chosen from the list of supported languages. You can support as many languages as you want as long as they are in the list.
Original Text	string	All the “Original Text” variables should be text from your original template that you want to translate. They need to match the text in the template exactly.
Translated Text	string	All the “Translated Text” should be translations of the “Original Text” in their correct language. The text will be used to exactly replace its corresponding original text, if that language is selected.

Apple Wallet Template

Apple Wallet Documentation

Our api follows the original Apple structure closely, sometimes it may be necessary to refer back to Apple’s documentation to understand the true purpose of an optional field, as they are not always immediately obvious. We have left our api as open as possible to allow the full flexibility that Apple can provide with their passes.

Overall Structure

The overall json:

{
    "type": "general",
    "orgName": "Example Company",
    "desc": "Description of the template",
    "groupId": "PassGroup1",
    "assoStoreId": [284882215],
    "appLaunchUrl": "fb://profile/331998086879963",
    "userInfo": "{\"Name\": \"Percy\"}",
    "bgColor": {
        "red": 245,
        "blue": 244,
        "green": 244
    },
    "labelColor": {
        "red": 22,
        "blue": 168,
        "green": 88
    },
    "fgColor": {
        "red": 53,
        "blue": 219,
        "green": 153
    },
    "logoText": "My Company",
    "transitType": "air",
    "header": [],
    "primary":[],
    "auxiliary": [],
    "secondary": [],
    "back": [],
    "beacons": [
        {
            "major": 0,
            "minor": 0,
            "uuid": "19d5f76a-fd04-5aa3-b16e-e93277163af6",
            "relevantText": "Welcome to PassKit"
        }
    ],
    "locations": [
        {
            "alt": 15,
            "lat": 22.28735687010302,
            "lon": 114.14827988250626,
            "relevantText": "Welcome to PassKit"
        }
    ],
    "maxDist": 10,
    "relevantDate": "2010-08-01T00:00:00Z",
    "barcode": {
        "altText": "Text below the barcode",
        "altTextOption": "text",
        "format": "pdf417",
        "message": "BarcodeText",
        "messageOption": "text",
        "messageEncoding": "UTF-8"
    },
    "nfc": {
        "message": "messageForTerminal",
        "encryptionPublicKey": "L0ngRand0m3ncrypt1onK3y"
    }
}

The example json shows all the possible fields for creating a pass and example data for most of them. You will not need a lot of these fields, so check the descriptions below to see the purpose of each one. The table works down the json object from the top to the bottom.

Parameter	Data Type	Description
type	string	Valid options for this parameter are: boardingPass, coupon, storeCard, generic, eventTicket
orgName	string	This should be your company name.
desc	string	This should be a brief description of the template, it is used by apple for user accessibility.
groupId (optional)	string	See groupingIdentifier for reference. This is used to group similar passes together for event tickets and boarding passes.
assoStoreId (optional)	array of integers	This is used to link to an app on the back of the pass. Each number in the array should be an Itunes Adam ID, the pass will display the first app in the array which is compatible with the current device.
appLaunchUrl (optional)	string	This is used to deep link into the app on the back of the pass (the app is chosen from the assoStoreId). If the app supports deep linking, you can use this url to go to a specific point within the app when it is opened.
userInfo (optional)	JSON string	This is used to provide json data to the linked app. When the app is opened it will be provided this information.
bgColor	color object	This field allows you to provide the rgb values for the background colour of the pass.
labelColor	color object	This field allows you to provide the rgb values for the text colour of the field labels on pass.
fgColor	color object	This field allows you to provide the rgb values for the text colour of the field values on pass.
logoText (optional)	string	This is you logo text on your template.
transitType (optional)*	string	*This field is required for boarding passes, it changes which icon is displayed on the pass. Available values are air, boat, bus, generic, train.
header (optional) primary (optional) auxiliary (optional) secondary (optional) back (optional)	array of passbook template fields	These five fields contain the text that goes on the pass. While all of these fields are marked as optional, you do need to have some contact information on the pass as this is a requirement from Apple. These fields all follow roughly the same format described below in the passbook template fields section. There are only a few differences: the back fields are the only fields which have the detectorTypes array, and both the primary field(s) and the back fields do not have the text align attribute.
beacons (optional)		Beacons allow you to display subtle messages to your users when they are in close proximity. Ideally used at places where the user may want to access the pass. For more information on beacons, see our GemTots or download our guide to iBeacon.
- major	integer	This is the major id of your beacon
- minor	integer	This is the minor id of your beacon
- uuid	string	This is the uuid of your beacon
- relevantText	string	This is the message that will display on the lockscreen when the phone is near the beacon.
locations (optional)		Locations provide a broader range using GPS to trigger a lockscreen message.
- alt (optional)	integer	This is an optional setting to allow the notification to only trigger at a certain altitude, useful in shopping malls.
- lat	integer	This is the latitude of the location.
- lon	string	This is the longitude of the location.
- relevantText	string	This is the message that will display on the lockscreen when the phone is within range of the location.
maxDist (optional)	integer	This field allows you to set a maximum distance for all locations to trigger on the pass, this can help to pinpoint your location. Apple will use their default max range if it is smaller than the one set here.
relevantDate (optional)	ISO8601 datetime	This allows you to set a time which will let the user know when the pass is relevant. For example an event ticket should be relevant at the beginning of the event, to let users know they should use it now.
barcode (optional)
- altText	string	This is the alternative text for your barcode, it is displayed directly under the barcode.
- altTextOption	string	Can be either text, pid, or none. Setting to text will display the altText underneath the barcode, setting to pid will override teh altText field and display the pass id below the barcode, setting to none will display no alternative text under the barcode.
- format	string	This is the format of the barcode, it can be qr, pdf417, aztec, or code128
- message	string	This is the message that will be encoded in the barcode
- messageOption	string	Can be either message or pid, setting to message will display the text from the message field above, setting to pid will override the message and display the pass id in the barcode.
- messageEncoding	string	This is the text encoding that you want the barcode in, it can be any IANA character set name.
nfc (optional)		Note that you need to have a special NFC certificate with Apple in order to enable this feature of apple passes. Contact us directly with any enquiries for custom solutions involving NFC.
- message	string	This is the data that will get sent to the NFC terminal.
- encryptionPublicKey	string	This is the public encryption key used to make sure the NFC transaction is secure.

Passbook Template Field

The json for a template field (header, auxiliary, secondary, primary, back):

{
    "itemName": "secondaryField1",
    "attributedValue": "<a href=\"https://cherrypie.passkit.net\">CherryPie</a>",
    "changeMsg": "Value Changed",
    "defaultLabel": "Item Label",
    "defaultValue": "Item Value",
    "textAlign": "left",
    "format": {
        "type": "text",
        "dateFormat": "short",
        "timeFormat": "long",
        "ignoreTimezone": true,
        "isRelative": false,
        "currencyCode": "",
        "numberFormat": "decimal"
    },
    "detectorTypes": []
}

Again, it is a good idea to check the Apple Documentation on the template fields. It will help clarify when certain fields should be used.

Parameter	Data Type	Description
itemName (optional)	string	This is a unique identifier of the field, it must not be reused in the same template. You do not have to provide an itemName, we will automatically generate them for you.
attributedValue (optional)	string	The attributed value allows you to enter html links. It will override the default value. The format only allows the tag with a href attribute.
changeMsg (optional)	string	This is the message that will be displayed as a notification if this field is updated. If %@ is used in the change message it will be replaced, when the message is displayed, with the new value of the field.
defaultLabel (optional)	string	This is the label that is displayed on the pass for the field.
defaultValue	string, number or ISO8601 datetime	This is the value of the field, it must match the format selected for the field.
textAlign (optional)	string	This field sets the alignment of the field, the possible settings are left, center, right, and natural. This field is not used in the primary field or the back fields.
detectorTypes (optional)	array of strings	This field allows you to set which string types will be detected on the back of the pass. When these types are detected, Apple will automatically link them to add more functionality. Any combination of phone, link, address, and event can be included in the array to allow for their detection. If the field is not provided, all are turned on by default. Phone will detect phone numbers and provide a link to automatically load the number, link will detect web urls and automatically link them to open them in a browser, address will detect addresses for use in maps, and event will detect calendar events to be added to calendar.
format
- type	string	This is the type of the field, the possible values are text, number, currency, date, or dateTime
- dateFormat	string	This is only used for the date, or dateTime type. The value can be none, short, medium, long, or full which will affect the length of the date displayed.
- timeFormat	string	This is only used for the date, or dateTime type. The value can be none, short, medium, long, or full which will affect the length of the time section displayed.
- ignoreTimezone	boolean	This is only used for the date, or dateTime type. If true, the time will display in the given time zone, not the user’s time zone.
- isRelative	boolean	This is only used for the date, or dateTime type. If true, the time will display as a relative date, otherwise the date is displayed as an absolute date.
- currencyCode	string	This is only used for the currency type, the code must be in the list of currency codes
- numberFormat	string	This is only used for the number type. The value can be decimal, percent, scientific, or spellout.

Passes

Create a Pass

Example of pass creation request

curl "https://api-pass.passkit.net/v2/passes"
  -X "POST" 
  -H "Authorization:PKAuth json_web_token"
  -H "Content-Type: application/json"
  -d '{
    "templateName": "templateName",
    "dynamicData": {
      "points":"10"
    }
  }'

On success the api will respond with the Pass Id in JSON format:

{
  "id": "RanD0mStr1ng"
}

HTTP Request

POST https://api-pass.passkit.net/v2/passes

JSON parameters

Data	type	Description
templateName	string	This is the reference name that you chose to give your template when you created it.
userDefinedId (optional)	string	This is the user defined id, it is not required as all our passes are given unique ids, however it can be used if you want to provide easy compatibilty with an existing system of unique customer identifiers (eg membership numbers).
dynamicData (optional)	JSON object containing key value pairs	This is the customer’s unique data. See the example json for an example of the format.
recoveryEmail (optional)	string	The customer’s email address. If this is included when the pass is created, the customer will be sent an email with a link to their pass.

Retrieve a Pass

To retrieve a pass, a GET request is needed

curl https://api-pass.passkit.net/v2/passes/RanD0mStr1ng
  -X GET
  -H "Authorization:PKAuth json_web_token"

Example of server response:

{
  "id": "RanD0mStr1ng",
  "campaignName": "campaignName",
  "templateName": "templateName",
  "passbookDevices": 0,
  "androidPayDevices": 0,
  "alipayDevices": 0,
  "updatedAt": "2016-03-15T23:42:56.271326844Z",
  "createdAt": "2016-03-15T23:42:56.271325489Z",
  "isInvalid": false,
  "isRedeemed": false,
  "dynamicData": {},
  "dynamicImages": null
}

HTTP Request

GET https://api-pass.passkit.net/v2/passes/{passId}

URL Parameters

Parameter	Data Type	Description
passId	string	This is the pass Id that was returned when you created the pass.

JSON Response

Data	type	Description
passId	string	This is the pass Id that was returned when you created the pass.
userDefinedId (optional)	string	If a user defined id was provided on pass creation, it can be checked here.
campaignName	string	This is the reference name that you chose to give your campaign when you created it.
templateName	string	This is the reference name that you chose to give your template when you created it.
passbookDevices	uint64	This is the number of passbook devices that the pass is registered on.
androidPayDevices	uint64	This is the number of androidpay devices that the pass is registered on.
alipayDevices	uint64	This is the number of alipay devices that the pass is registered on.
updatedAt	ISO8601 datetime	This is when the pass was last updated.
createdAt	ISO8601 datetime	This is when the pass was created.
firstUnRegisteredAt (optional)	ISO8601 datetime	This is when the pass was first removed from one of the devices it is installed on.
lastUnRegisteredAt (optional)	ISO8601 datetime	This is when the pass was most recently removed from one of the devices it is installed on.
firstRegisteredAt (optional)	ISO8601 datetime	This is when the pass was first added to one of the devices it is installed on.
lastRegisteredAt (optional)	ISO8601 datetime	This is when the pass was most recently added to one of the devices it is installed on.
isInvalid	bool	This value indicates the validity of your pass. True means the pass has been invalidated.
isRedeemed	bool	This value shows if a pass is redeemed or not.
dynamicData (optional)	JSON object containing key-value pairs	On pass creation, you need to cross check the template and see if the data type is valid.
dynamicImages (optional)	DynamicImages	This contains information about any dynamic images used on the pass
recoveryEmail (optional)	string	This is the recovery email that was added when the pass was created.

Retrieve a Pass with User Defined Id

To retrieve a pass, a GET request is needed

curl https://api-pass.passkit.net/v2/passes?userDefinedId=12345&campaignName=campaignName
  -X GET
  -H "Authorization:PKAuth json_web_token"

Server response is the same as from a normal retrieve pass

HTTP Request

GET https://api-pass.passkit.net/v2/passes?userDefinedId={userDefinedId}&campaignName={campaignName}

URL Parameters

Parameter	Data Type	Description
userDefinedId	string	This is the user defined id that was assigned when you created the pass. If no user defined id was assigned on pass creation, the pass must be updated with a user defined id first before using this method.
campaignName	string	This is the reference name that you chose to give your campaign when you created it.

Update a Pass

Example of pass update request

curl "https://api-pass.passkit.net/v2/passes/RanD0mStr1ng"
  -X "PUT" 
  -H "Authorization:PKAuth json_web_token"
  -H "Content-Type: application/json"
  -d '{
    "dynamicData": {
      "points":"20"
    },
    "isRedeemed": true
  }'

On success the api will respond with the Pass Id in JSON format:

{
  "id": "RanD0mStr1ng"
}

HTTP Request

PUT https://api-pass.passkit.net/v2/passes/{passId}

URL Parameters

Parameter	Data Type	Description
passId	string	This is the pass Id that was returned when you created the pass

JSON parameters

Data	type	Description
templateName	string	This is the reference name that you chose to give your template when you created it.
userDefinedId (optional)	string	This is the user defined id, it is optional, however it can be used if you want to provide easy compatibilty with an existing system of unique customer identifiers (eg membership numbers).
dynamicData (optional)	JSON object containing key-value pairs	This is the customer’s unique data. See the example json for an example of the format.
isInvalid	boolean	If this is set to true, the pass is invalidated. Once a pass has been invalidated, it can no longer be updated ever and this process cannot be undone.
isRedeemed	boolean	If this is set to true, the pass is switched to the reddem state of the template it is currently on.
recoveryEmail (optional)	string	The customer’s email address. If this is included when the pass is created, the customer will be sent an email with a link to their pass.

Update a Pass with User Defined Id

Example of pass update request

curl https://api-pass.passkit.net/v2/passes?userDefinedId=12345&campaignName=campaignName
  -X PUT
  -H "Authorization:PKAuth json_web_token"
  -H "Content-Type: application/json"
  -d '{
    "dynamicData": {
      "points":"20"
    },
    "isRedeemed": true
  }'

On success the api will respond with the Pass Id in JSON format:

{
  "id": "RanD0mStr1ng"
}

HTTP Request

PUT https://api-pass.passkit.net/v2/passes?userDefinedId={userDefinedId}&campaignName={campaignName}

URL Parameters

Parameter	Data Type	Description
userDefinedId	string	This is the user defined id that was assigned when you created the pass. If no user defined id was assigned on pass creation, the pass must be updated normally with a user defined id first before using this method.
campaignName	string	This is the reference name that you chose to give your campaign when you created it.

JSON parameters

The JSON parameters are the same as for updating the pass normally

Batch Pass Methods

Batch Create Passes

Example of batch pass creation request

curl "https://api-pass.passkit.net/v2/passesBatch"
  -X "POST" 
  -H "Authorization:PKAuth json_web_token"
  -H "Content-Type: application/json"
  -d '{
    "passes": [
      {
        "templateName": "templateName",
        "dynamicData": {
          "points":"10"
        }
      }
    ]
  }'

On success the api will respond with an array of Pass Ids in JSON format. The order of these Ids will match the order of the passes in the array sent.

{
  "id": [
    "RanD0mStr1ng"
  ]
}

HTTP Request

POST https://api-pass.passkit.net/v2/passesBatch

JSON parameters

Data	type	Description
passes	an array of pass data	For batch create pass, the data is an array of up to 25 passes, containing the same data as found in create a pass

Batch Update Passes

Example of batch pass creation request

curl "https://api-pass.passkit.net/v2/passesBatch"
  -X "PUT" 
  -H "Authorization:PKAuth json_web_token"
  -H "Content-Type: application/json"
  -d '{
    "passes": [
      {
        "id": "RanD0mStr1ng"
        "templateName": "templateName",
        "dynamicData": {
          "points":"10"
        }
      }
    ]
  }'

On success the api will respond with an array of Pass Ids in JSON format. The order of these Ids will match the order of the passes in the array sent.

{
  "id": [
    "RanD0mStr1ng"
  ]
}

HTTP Request

PUT https://api-pass.passkit.net/v2/passesBatch

JSON parameters

Data	type	Description
passes	an array of pass data	For batch update pass, the data is an array of up to 25 passes, containing almost the same data as found in update a pass. Note that each pass in the batch update pass call will also need to have their pass id added to the update call.

General

Supported Languages

Language Code	Language
ar	(Arabic) العربية
ca	Català (Catalan)
zh-Hans	简体中文 (Simplified Chinese)
zh-Hant	繁體中文 (Traditional Chinese)
hr	Hrvatski (Croatian)
cs	Čeština (Czech)
da	Dansk (Danish)
nl	Nederlands (Dutch)
en	English
en-GB	English (British)
fi	Suomi (Finnish)
fr	Français (French)
de	Deutsch (German)
el	Ελληνικά (Greek)
he	(Hebrew) עברית
hu	Magyar (Hungarian)
id	Bahasa Indonesia (Indonesian)
it	Italiano (Italian)
ja	日本語 (Japanese)
ko	한국어 (Korean)
ms	Bahasa Melayu (Malay)
nb	Norsk Bokmål (Norwegian)
pl	Polski (Polish)
pt-BR	Português (Brazilian Portuguese)
pt	Português de Portugal (Portuguese)
ro	Română (Romanian)
ru	Русский (Russian)
sk	Slovenčina (Slovakian)
es	Español (Spanish)
sv	Svenska (Swedish)
th	ภาษาไทย (Thai)
tr	Türkçe (Turkish)
uk	Українська (Ukranian)
vi	Tiếng Việt (Vietnamese)

Currency Codes

All the available currency codes are listed here:

AED, AFN, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, BMD, BND, BOB, BOV, BRL, BSD, BTN, BWP, BYR, BZD, CAD, CDF, CHE, CHF, CHW, CLF, CLP, CNY, COP, COU, CRC, CUC, CUP, CVE, CZK, DJF, DKK, DOP, DZD, EGP, ERN, ETB, EUR, FJD, FKP, GBP, GEL, GHS, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, HRK, HTG, HUF, IDR, ILS, INR, IQD, IRR, ISK, JMD, JOD, JPY, KES, KGS, KHR, KMF, KPW, KRW, KWD, KYD, KZT, LAK, LBP, LKR, LRD, LSL, LTL, LVL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRO, MUR, MVR, MWK, MXN, MXV, MYR, MZN, NAD, NGN, NIO, NOK, NPR, NZD, OMR, PAB, PEN, PGK, PHP, PKR, PLN, PYG, QAR, RON, RSD, RUB, RWF, SAR, SBD, SCR, SDG, SEK, SGD, SHP, SLL, SOS, SRD, SSP, STD, SYP, SZL, THB, TJS, TMT, TND, TOP, TRY, TTD, TWD, TZS, UAH, UGX, USD, USN, USS, UYI, UYU, UZS, VEF, VND, VUV, WST, XAF, XAG, XAU, XBA, XBB, XBC, XBD, XCD, XDR, XFU, XOF, XPD, XPF, XPT, XTS, XXX, YER, ZAR, ZMK, ZWL

Passbook Image Types

When creating or updating a template, you may need to include image files. The naming convention for the multipart form upload is as follows:

Each file key begins with either passbook- or passbookRedeem- depending on whether it belongs to the default state or the redeemed state. If the image is for one of the translations an additional string is added to show which language the image is for. Example: passbook-fr-, the language codes are found here. Finally the image type that you are uploading is added onto the end of the file key name. For example passbook-IconFile is the default icon image for the template, passbook-fr-IconFile will be used instead if the user has the language set to French.

The exact specifications for images in Apple wallet can be found in their developer documentation. The list of image types that can be uploaded is as follows:

Image Type	Position on the Pass	Other Notes	Dimensions
IconFile	On the lock screen and by apps like Mail when showing an attached Pass		120 x 120
LogoFile	Displayed in the top left corner of the Pass	The maximum width is 320 pixels. In most cases it should be narrower. If you use the full pixel width note you may not have room for any Logo Text, or Header fields.	320 x 100
StripFile	Displayed behind the Primary Fields		On iPhone 6 and 6 Plus, the space is 750 x 196 for event tickets, 750 x 288 for gift cards and coupons, and 750 x 246 in all other cases. On earlier models, the space is 640 x 168 for event tickets, 640 x 220 for square barcodes on devices with 3.5 inch screens, and 640 x 246 in all other cases.
FooterFile	Above the barcode	Available on the Transport Pass Type	572 x 30
ThumbFile	Displayed next to the fields on the front of the pass	The aspect ratio should be in the range of 2:3 to 3:2, otherwise the image is cropped	Up to 180 x 180
BgFile	Behind the entire front of the pass	Available on the Event Pass Type. The image is cropped slightly on all sides and blurred	360 x 440

Errors

This section can detail the different error responses

Error Code	Meaning
400	Bad Request – Your request sucks
401	Unauthorized – Your API key is wrong
403	Forbidden – The request is for administrators only
404	Not Found – The specified request or data could not be found
500	Internal Server Error – We had a problem with our server. Try again later.
503	Service Unavailable – We’re temporarially offline for maintanance. Please try again later.