Litecard API User Guide

(Last reviewed 4th of July, 2026)

Introduction

This is a quick-start user guide for using Litecard’s API. For our official API documentation – click this link to access our API development resources.

Litecard API Endpoints 

Production / Enterprise  #

Swagger UI: https://bff-api.enterprise.litecard.io/api/v1/swagger 

JSON Docs: https://bff-api.enterprise.litecard.io/api/v1/docs 

Demo #

Swagger UI: https://bff-api.demo.litecard.io/api/v1/swagger 

JSON Docs: https://bff-api.demo.litecard.io/api/v1/docs 

Glossary

Commonly used terminology within the Litecard ecosystem

Authentication

Litecard will provide the user with a set of credentials to use in the relevant environment. This step will be required for the rest of the endpoint guides.

Authenticate Endpoint: 

Production/ Enterprise: https://bff-api.enterprise.litecard.io/api/v1/token

Demo: https://bff-api.demo.litecard.io/api/v1/token

Master / Sub Account Method

Litecard has a Master / Sub account structure available where 1 set of credentials can access multiple accounts owned by the Business. When logged into the master account using the Litecard portal, you will be able to create sub accounts there, either with login credentials or without.

If you create a sub account with login credentials, you can use those when using the Litecard API. If the sub account has no credentials, you will need to follow this method to use the Litecard API. This method can be used for sub-accounts with credentials.

• Authenticate to the Litecard API using the master account credentials
• In your subsequent API calls, include this header x-active-business-id with the businessId of the sub account
• You can find the sub account’s businessId inside the Litecard dashboard under ‘Manage Accounts’

UI Method:

• Use the relevant Swagger UI endpoint above
• Open and expand the Authentication tab https://bff-api.enterprise.litecard.io/api/v1/swagger#/Authentication/authenticate 

• Enter the username and password provided by Litecard 
• After pressing the “Execute” the server response will return the server response Copy the value for “access_token” 

• Scroll up and click ‘Authorise’. Paste the value for “access_token” in the input box.

• API requests executed in the swagger will now be authenticated
  

Template Creation

In most scenarios, Litecard will be generating and providing the client with the template (either a JSON file or simply the ID to use for the subsequent endpoints). 

Create Template Endpoint

Production / Enterprise: https://bff-api.enterprise.litecard.io/api/v1/template 

Demo: https://bff-api.demo.litecard.io/api/v1/template

UI Method:

• Obtain an access token following the above Authentication guide
• Open and Expand the ‘Create Template Endpoint’. Click ‘Try it Out’

https://bff-api.enterprise.litecard.io/api/v1/swagger#/Card%20Template/createTemplate_v1

• Paste in the contents of the template JSON file provided by Litecard inside the ‘Request Body’. Click Execute.

• Take note of the response. Save the templateId and formId for future reference.

Multi tier Templates

Multi Tier templates mean a single template can support have different designs depending on what is provided at the time the pass is created or when the pass is updated. We will be introducing this inside our Template Builder on our website shortly.

Here are the things that can be different between ‘tiers’

• Colours (background, label and text colours)
• Images
• DataFields (static data fields only, etc., information fields at the back of the pass)
• Links
• Expiry date

A template must always have a ‘default’ tier, which will be used if one is not specified during card creation. As mentioned above, we cannot support dynamic data fields on a per-tier basis.

Card Creation

The payload when generating cards will differ based on what fields are present inside the template / form. The example below is using the generic litecard template file, which will be provided to the user.

Litecard uses either an email or a phone number to uniquely identify a user. All passes associated with the same email / phone number will be grouped together.

That means when you update the first name / last name of a pass, all passes under that user will have their names updated as well.

If the intention is to use a Litecard provided Signup Form, an email or phone number has to be present to deliver the pass to the user.

Create Card Endpoint

Production / Enterprise: https://bff-api.enterprise.litecard.io/api/v1/card POST

Demo: https://bff-api.demo.litecard.io/api/v1/card POST

UI Method

• Obtain an access token following the above Authentication guide
• If you have not created a template yet or have not been provided with a templateId, follow the  Template Creation guide above first.
• Click and Expand the ‘Create Card Endpoint’. Click ‘Try it out’

https://bff-api.enterprise.litecard.io/api/v1/swagger#/Card/createCard

• Paste and fill in the following sample payload:

{

  “templateId”: “”,

  “tier”: “”,

  “cardPayload”: {

    “email”: “”, // All passes require either email or phone number to be provided.

    “firstName”: “”,

    “lastName”: “”

  },

  “options”: {

    “emailInvitationEnabled” false

  }

}

Note: the “emailInvitationEnabled” option determines whether you want a Litecard email sent to the above email address with the download link for the card.Card Update

This endpoint is used to update certain fields on the card. You can update data fields or utilise template overrides to update certain parts of the card, like image, backlinks, etc.

Note: tier is only for a multi-tier template (for which the design/logic can be set up via the Litecard dashboard).

Update Card Endpoint

Production / Enterprise: https://bff-api.enterprise.litecard.io/api/v1/card PATCH

Demo: https://bff-api.demo.litecard.io/api/v1/card PATCH

UI Method

• Obtain an access token following the above Authentication guide
• Click and Expand the Update Card Endpoint’. Click ‘Try it out’

https://bff-api.enterprise.litecard.io/api/v1/swagger#/Card/updateCard

• Fill in the payload. Payload will look something like this:

{

  “cardId”: “”,

  “cardPayload”: {

    //Fields you want to update on that exist on the card

    “email”: “”,

  }

}

Note: Inside the cardPayload field, contains the fields you want to update on the card. These fields will correspond to the same fields that were used inside the create card payload for the pass.

Dynamic Fields

Best used for updating fields throughout the pass’s lifetime, such as loyalty points, rewards, offers, tiers, and more.

The requirements inside the cardPayload when generating a card depend on the dataFields defined by the Template used. By default, Litecard requires no fields except email or phone if Litecard is delivering the download link to the end user.

The template will define whether a field is dynamic and, if so, whether it is required or optional.

Dynamic Fields can be created using the template builder inside the ‘Form Fields’ section here:

The key to use inside the cardPayload is derived from the label. You can assume the key will be the content of the label with no spaces and capitals. Etc Barcode Value would be barcodevalue.

Get Card

This endpoint is used to retrieve details on the card.

Get Card Endpoint

Production / Enterprise: https://bff-api.enterprise.litecard.io/api/v1/card/{cardId}

Demo: https://bff-api.demo.litecard.io/api/v1/card/{cardId}

UI Method

• Obtain an access token following the above Authentication guide
• Click and Expand the ‘Get Card by Id Endpoint’. Click ‘Try it out’

https://bff-api.enterprise.litecard.io/api/v1/swagger#/Card/getCard

• Enter in the cardId of the card data you want to retrieve. Press ‘Execute’

Delete Card

This endpoint is used to delete/expire passes.

Delete Card Endpoint

Production / Enterprise: https://bff-api.enterprise.litecard.io/api/v1/card/status 

Demo: https://bff-api.demo.litecard.io/api/v1/card/status

UI Method

• Obtain an access token following the above Authentication guide
• Click and Expand the ‘Card Status Endpoint’. Click ‘Try it out’

https://bff-api.enterprise.litecard.io/api/v1/swagger#/Card/setCardStatus

• For the payload:

{

  “cardId”: {cardId},

  “status”: “DELETED”

}

• Press Execute

Deactivating Vs Deleting

Deactivating the card expires the card on the user’s device, rendering it unable to be scanned. This action, however, leaves open the possibility of reactivating the pass at a later time. The status update for this action is marked as “INACTIVE”. Deleting the card also causes it to expire on the user’s device, but, unlike deactivation, it completely removes the ability to re-enable the pass in the future. After deletion, the status update is designated as “DELETED”.

Please refer to the request schema below.

Fast Create

Fast Create refers to an alternative method of card creation. This method has been created to bypass the Google Wallet API Rate Limits (30RPS). Typically, when a pass gets generated, both the Apple and Google wallet API’s are called to generate the pass at that point in time. Litecard then returns the device download links in the API call. 

The fast create method instead simply validates the card and stores the relevant data in the Litecard Database. Litecard then returns a Litecard link for Apple and Google. Then, when a user clicks on the link, Litecard will generate the device-specific pass and serve it to the user. This means the Google wallet rate limit isn’t relevant during the initial loading of the user data into Litecard, but instead when the user wants to download the Pass.

There are a number of ways to generate a Fast Card. This can be enabled at the template level or enabled per card via options inside the createCard payload. Litecard has also introduced a bulk create endpoint for users to quickly pre-load passes into the Litecard system, ready for distribution.

Activating a Fast Card

This endpoint is not required in the fast create process if you want to use the Litecard-supplied links. However, during the actual creation of cards, there may be a delay of up to 4 seconds. During that time, you will see the Litecard download page essentially.

If this is not desirable, rather than using the Litecard-supplied links, you can use the activate endpoint and then serve the real download link to the customer.

Activate Card endpoint #

Production / Enterprise: https://bff-api.enterprise.litecard.io/api/v1/card/status 

Demo: https://bff-api.demo.litecard.io/api/v1/card/status

UI Method #

• Obtain an access token following the above Authentication guide
• Click and Expand the ‘Retrieve Card endpoint’. Click ‘Try it out’ https://bff-api.enterprise.litecard.io/api/v1/swagger#/Card/retrieveDeviceCardLink 

• For the payload: 

{

  “downloadId”: “{download}”,

  “deviceType”: “APPLE” | “GOOGLE”

}

• Press Execute

Bulk Card Creation using Fast Card Method

Max number of cards per request: 100.

There are currently no limits in place for concurrency calls at this point in time.

Email and SMS pass invitations will not be sent when passes are created using this endpoint.

This is the schema for the bulk create card endpoint:

{

  “templateId”: “template-123”,

  “createCardPayloads”: [

    {

      “cardPayload”: {

        “email”: “john@example.com”,

        “phone”: “+12025550143”,

        “exampleProperty”: “Sample string property”,

        “additionalProp1”: {}

      },

      “tier*”: “GOLD”,

    }

  ],

  “options”: {

    “noPI”: true | false

  }

}

Currently, it is only possible to generate cards for a singular template per API call. 

The expected response should look like this:

{

  “success”: true,

  “cards”: [

    {

      “cardPayload”: {

        “email”: “john@example.com”,

        “phone”: “+12025550143”,

        “exampleProperty”: “Sample string property”,

        “additionalProp1”: {}

      },

      “tier”: “string”,

      “cardId”: “string”,

      “cardOwnerId”: “string”,

      “downloadId”: “string”,

      “appleLink”: “string”,

      “googleLink”: “string”,

      “success”: true

    }

  ]

}

The original cardPayload is returned for every single card.

Bulk Card Create Endpoint #

Production / Enterprise: https://bff-api.enterprise.litecard.io/api/v1/card/bulk-fast-create

Demo: https://bff-api.demo.litecard.io/api/v1/card/bulk-fast-create

UI Method #

• Obtain an access token following the above Authentication guide
• Click and Expand the ‘Bulk Fast Create Card Endpointt’. Click ‘Try it out’ 

• For the payload, please follow the above schema, the contents inside cardPayload will depend on the template you use.

Notifications

As a business owner, I can send notifications either via email or push (Apple devices only) to all or select users.

While neither Apple nor Google enforces a character limit, Apple requires the field to be no larger than 4KB. It is suggested that Notifications remain short and within 250 characters, as they will get cut off by the device.

For Apple: Notifications remain until the user swipes them away. The field on the back of the pass remains until a new notification comes to overwrite it.

For Google: Messages stay on the pass for an indefinite amount of time. New messages are stacked on top of one another. Currently, there is no way to adjust timeout settings.

Notifications Endpoint

Production / Enterprise: https://bff-api.enterprise.litecard.io/api/v1/queue/notification

Demo: https://bff-api.demo.litecard.io/api/v1/queue/notification

UI Method

• Obtain an access token following the above Authentication guide
• Click and Expand the ‘Notification via queue Endpoint’. Click ‘Try it out’

https://bff-api.enterprise.litecard.io/api/v1/swagger#/Notifications/sendNotificationQueue_v1

• Below is an example payload with some notes

{

  “cardIds”: [

    “abc123” // can be left blank if setting sendAll to true

  ],

  “notification”: {

    “title”: “”,

    “message”: “”,

    “dataFieldKey”: “notificationKey”, // Default Key should leave this alone unless notified otherwise or set custom by client

    “sendTime”: “” // Optional if want to send at specific time

  },

  “options”: {

    “email”: false, //send email notification 

    “pushNotification”: true, // send push notification

    “sendAll”: false // send to all active users. This overwrites the cardIds field.

  }

}

• Enter the payload inside the request body field, then press execute.

Location-based Notifications

Location-based Notifications are not triggered via Litecard API. Instead, they are typically defined when creating or updating a template. It works for Apple and Google Wallet Devices and works by using the user’s GPS to determine if it’s within a set of pre-defined coordinates before triggering the message.

To apply location-based notifications for existing passes, you will need to update the Template with the notification and then trigger the Update Card Endpoint for it to apply to all existing cards. You can also set up locations on the Litecard Dashboard by navigating to the ‘Locations’ sidebar, inputting longitude/latitude or searching for location names and then attaching the message to each location in the pass template design process.

Location-based notifications can only be applied to 10 locations at a time on Apple or Google devices and are accurate within 50-100m of longitude and latitude coordinates. 

 “locations”: [

   {

     “id”: “string”,

     “lat”: “-37.806454120154115”,

     “lon”: “144.9864286613659”,

     “apple”: {

       “lockScreenMessage”: “Come and visit our office for a free gift!”

     },

     “order”: 0,

     “usage”: [

       “APPLE_WALLET, GOOGLE_WALLET”

     ]

   }

 ]

You can do this on a per-card basis by using templateOverrides when generating or updating a card.

Here is what the create card payload may look like:

{

 “templateId”: “exampleTemplateId”,

 “cardPayload”: {

   “email”: “testing1234@example.com”,

   “firstName”: “John”,

   “lastName”: “Citizen”

 },

 “options”: {

   “emailInvitationEnabled”: false

 },

 “templateOverrides”: {

   “locations”: [

     {

       “id”: “string”,

       “lat”: “-37.806454120154115”,

       “lon”: “144.9864286613659”,

       “apple”: {

         “lockScreenMessage”: “Come and visit our office for a free gift!”

       },

       “order”: 0,

       “usage”: [

         “APPLE_WALLET, GOOGLE_WALLET”

       ]

     }

   ]

 }

}

Here is what an update card payload would look like:

{

 “cardId”: “exampleCardId”,

 “templateOverrides”: {

   “locations”: [

     {

       “id”: “string”,

       “lat”: “-37.806454120154115”,

       “lon”: “144.9864286613659”,

       “apple”: {

         “lockScreenMessage”: “Come and visit our office for a free gift!”

       },

       “order”: 0,

       “usage”: [

         “APPLE_WALLET, GOOGLE_WALLET”

       ]

     }

   ]

 }

}

Note: Push notifications are supported via both Apple and Google Wallets with Litecard’s platform

Apple Order Overview

The Apple Order Tracking API allows you to generate order passes for Apple Wallet, providing customers with a seamless way to track their purchases directly on their devices. This integration enables businesses to push real-time status updates, ensuring customers stay informed about their order progress from any marketplace or platform. Orders need to be added into the mobile wallet from CRM channels such as SMS or emails as well. They are delivered via a unique link that can be embedded via an order tracking button (similar to adding a membership card or voucher to your phone).

Litecard supports two primary fulfillment types for these order passes, each designed with unique layouts and status tracking capabilities:

• Shipping Fulfillment: Tailored for delivered goods, this type includes a progress bar and detailed logistics information, such as the carrier name, tracking URLs, and tracking IDs.
• Pickup Fulfillment: Designed for in-store collection, this type displays essential pickup details, including the location, a designated barcode, and the scheduled time window for pickup.

These attributes can be managed and configured during both the initial order creation and subsequent updates.

Glossary

Order Template Creation

An order template is a prerequisite for creating orders, as it stores essential shared data such as merchant identification, barcode settings, configurations, and default fulfillment status descriptions. You can generate these templates either through the API or by using the user-friendly Litecard Order Template UI Builder.

Create Order Template Endpoint

Production / Enterprise: https://bff-api.enterprise.litecard.io/api/v1/order-templates

Demo: https://bff-api.demo.litecard.io/api/v1/order-templates

UI Method

• Obtain an access token following the above Authentication guide
• Open and Expand the ‘Create Order Template Endpoint’. Click ‘Try it Out’

https://bff-api.enterprise.litecard.io/api/v1/swagger#/Wallet%20Order/createOrderTemplate_v1

• Paste in the contents of the template JSON file provided by Litecard inside the ‘Request Body’. Click Execute.
• Take note of the response. Save the orderTemplateId for your reference when creating an order later.

Schema Definition

Payload Example

{

  “name”: “Litecard Shipping”,

  “description”: “Offline Store Shipping Template”,

  “merchant”: {

    “merchantName”: “Litecard Store 2”,

    “logo”: “https://assets.dev.litecard.io/shared/logo.png”,

    “url”: “https://www.bonds.com.au/”

  },

  “barcode”: {

    “type”: “QR_CODE”,

    “messageEncoding”: “iso-8859-1”

  },

  “settings”: {

    “sendInvitationEmail”: false

  }

}

Create Order

This endpoint constructs a signed .order bundle from the provided payload, returning an appleLink to download the order pass. Additionally, if sendInvitationEmail is set to true in template.settings, the customer will receive an email invitation to download the .order pass.

Create Order Endpoint

Production / Enterprise: https://bff-api.enterprise.litecard.io/api/v1/orders POST

Demo: https://bff-api.demo.litecard.io/api/v1/orders POST

UI Method

• Obtain an access token following the above Authentication guide
• If you have not created a template yet or have not been provided with an orderTemplateId, follow the Order Template Creation guide above first.
• Click and Expand the ‘Create Order Endpoint’. Click ‘Try it out’

https://bff-api.enterprise.litecard.io/api/v1/swagger#/Wallet%20Order/createWalletOrder_v1

Schema Definition

Payload Example

{

  “orderTemplateId”: “4065614404”,

  “orderManagementURL”: “https://example.com/order-management”,

  “orderType”: “ecommerce”,

  “orderNumber”: “ORD-0001”,

  “fulfillment”: {

    “fulfillmentIdentifier”: “fulfillment-1”,

    “fulfillmentType”: “shipping”,

    “status”: “open”

  },

  “externalReference”: “erp-invoice-998877”,

  “payment”: {

    “summaryItems”: [

      {

        “label”: “Subtotal”,

        “value”: {

          “amount”: 23,

          “currency”: “USD”

        }

      },

      {

        “label”: “Tax”,

        “value”: {

          “amount”: 2,

          “currency”: “USD”

        }

      },

      {

        “label”: “Total”,

        “value”: {

          “amount”: 25,

          “currency”: “USD”

        }

      }

    ],

    “status”: “pending”,

    “total”: {

      “amount”: 25,

      “currency”: “USD”

    },

    “paymentMethods”: [

      “VISA 1234”

    ]

  },

  “lineItems”: [

    {

      “title”: “Kids Long Sleeve Raglan Tee”,

      “quantity”: 1,

      “price”: {

        “amount”: 25,

        “currency”: “USD”

      },

      “imageUrl”: “https://assets.dev.litecard.io/s1p_qClremNRiNJeCgJ1F%23FxENlOjOcmQIduQmfKuEn/qdDoyzQaVDNvIQxHUIbtf-logo%403x.png”

    }

  ],

  “customer”: {

    “firstName”: “John”,

    “lastName”: “Doe”,

    “emailAddress”: “john.doe@example.com”,

    “phoneNumber”: “+12025550156”

  },

  “barcode”: {

    “barcodeValue”: “ORD-0001”

  }

}

Update Order

This endpoint is used to update an order’s fulfillment status, payment information, or both. At least one of these fields must be provided during an update.

Update Order Endpoint

Production / Enterprise: https://bff-api.enterprise.litecard.io/api/v1/orders/{orderIdentifier} PATCH

Demo: https://bff-api.demo.litecard.io/api/v1/orders/{orderIdentifier} PATCH

UI Method

• Obtain an access token following the above Authentication guide
• Put the {orderIdentifier} or orderId in the path parameter.
• Click and Expand the ‘Update Order Endpoint’. Click ‘Try it out’

https://bff-api.enterprise.litecard.io/api/v1/swagger#/Wallet%20Order/patchWalletOrder_v1

Schema Definition

Payload Example

{

  “fulfillment”: {

    “status”: “processing”,

    “statusDescription”: “Your order has been processed…”,

    “notes”: “Please wait for 1-2 days until your order is prepared…”

  },

  “payment”: {

    “status”: “paid”

  }

}

Shipping Fulfillment Status

The standard workflow for shipping is: open > processing > shipped > onTheWay > outForDelivery > delivered > issue > cancelled.

• Status Description: A statusDescription can be provided for any status.
• Notes: Note fields are not supported for delivered, issue, or cancelled statuses.
• Conditional Parameters:
  • When status is shipped: You may include shippedAt, carrier, trackingNumber, and trackingURL.
  • When status is delivered: You may include deliveredAt.

Pickup Fulfillment Status

The standard workflow for pickup is: open > processing > readyForPickup > pickedUp > issue > cancelled.

• Status Description: A statusDescription can be provided for any status.
• Notes: Note fields are not supported for pickedUp, issue, or cancelled statuses.
• Conditional Parameters:
  • When status is readyForPickup: You may include pickupAt, pickupWindowDuration (ISO-8601), pickupLocation (lat/long), and pickupBarcode.
  • When status is pickedUp: You may include pickedUpAt.

Thank you. For any further questions, please contact: dev@litecard.com