Tokens

📝 Note: If the AppDirect logo appears in the upper-left corner of the page, when Manage > Marketplace appears in this topic, click the grid icon > Switch to | Store, instead.

Tokens represent data from the database. They can represent a single item such as a product name, a list of items such as of the invoice lines associated with a purchase, or characteristics of invoices lines such as whether they are credits or not. You can use tokens in the following ways:

• Add tokens to text, Markdown text, field, table components, and page number components. They return data they represent from the database and display it on invoices.
• Add sorting and grouping tokens to table components so the system can identify invoice lines that meet the data criteria that the token specifies, and group and sort the invoice lines accordingly. For more information on invoice lines, see Build invoice line tables.

Following is the JSON format for tokens:

{{Token Name}}

To display data on invoices with tokens, you can add one or more tokens to text, field, page number, and Markdown components. Examples are shown in the following table:

Example type	JSON value	Output example
Text (simple binding)	Please pay by the due date.	Please pay by the due date.
Data (simple binding)	{{Invoice Due Date}}	July 1, 2030
Text and data (compound binding)	Due date: {{Invoice Due Date}}	Due date: July 1, 2030

Additionally, you can combine tokens and Markdown markup syntax for Markdown components. For more information, see Build Markdown text components.

Tokens are organized into categories and some are only valid for specific component types. To determine which token categories you can use in a component, refer to the following table.

Component type	Valid token categories
Invoice lines table	Invoice line details Grouping and sorting
Tax summary table	Tax summary
Page number	Pagination
Components not in An Invoice lines table component. A tax table component. A page number component.	All categories not named above.

All available tokens, by category, follow.

Token category: User details

Use these tokens to display customer details such as name and address. In the default invoice template, these appear in the invoice header Billed To section, as shown in the following example image.

These tokens are valid for all components that have data properties except those in the following:

• An Invoice lines table component.
• A tax summary table component.
• A page number component.

Token value for use in JSON	Description
{{First Name}}	First name of the end user for whom the invoice is generated.
{{Last Name}}	Last name of the end user for whom the invoice is generated.
{{Company Name}}	Name of the company to which the end user who made the purchase belongs.
{{Street 1}}	First line for the street address of the end user for whom the invoice is generated.
{{Street 2}}	Second line for the street address of the end user for whom the invoice is generated.
{{City}}	City for the address of the end user for whom the invoice is generated.
{{State}}	State of the end user for whom the invoice is generated.
{{Zip Code}}	Zip code of the end user for whom the invoice is generated.
{{Email}}	Email address of the end user for whom the invoice is generated.

Token category: Seller details

Use this token to display seller details on invoices. In the default invoice template, these appear in the invoice header Payable to section, as shown in the following example image.

This token is valid for Markdown text components. For more information, see Build Markdown text components.

Token value for use in JSON

Description

{{Seller}}

Displays the seller details that you configure and format with Markdown markup language at Manage > Marketplace > Settings > Billing settings | Invoice settings. By default, effective immediately after AppDirect enables the invoice templates feature, the AppDirect platform uses the default templates which include this token to generate PDF invoices when users download them, until you publish different templates. We recommend you configure and test these templates immediately (see Configure and test default templates).

Token category: Invoice details

Use these tokens to display invoice and billing details such as the invoice number, invoice date, due date, and invoice status (paid, unpaid, and carried) on invoices. In the default invoice template, these appear in the invoice header, as shown in the following image:

These tokens are valid for cell and field components except those in the following:

• An Invoice lines table component.
• A tax summary table component.
• A page number component.

Token value for use in JSON	Description
{{Invoice Id}}	Unique system-assigned invoice identifier.
{{Invoice Number}}	System-assigned invoice number in the format configured for the marketplace. Displays as '#' followed by the invoice ID. For example, #67342.
{{Invoice Status}}	Status of the invoice. For example, Paid, Unpaid, Carried, Void.
{{Date}}	Invoice generation date.
{{Invoice Due Date}}	Date the invoice payment is due.
{{Amount Paid}}	Amount of the invoice total that the customer has paid.
{{Balance Due}}	Amount the customer owes for this invoice.
{{Carried Balance}}	Outstanding amounts from previous invoices that have been carried to this invoice.
{{Subtotal}}	Total invoice amount excluding tax.
{{Total}}	Total invoice amount including tax.
{{Memo}}	Memo content that Marketplace Managersconfigure to appear when users view invoices on-screen. You format the content with Markdown markup language at Manage > Marketplace > Settings > Billing settings | Invoice settings. By default, effective immediately after AppDirect enables the invoice templates feature, the AppDirect platform uses the default templates which include this token to generate PDF invoices when users download them, until you publish different templates. We recommend you configure and test these templates immediately. For information on configuring and testing the tempates, see Configure and test default templates.
{{Invoice Logo}}	Invoice logo that Marketplace managersconfigure at Manage > Marketplace > Settings > Billing settings | Invoice settings. By default, effective immediately after AppDirect enables the invoice templates feature, the AppDirect platform uses the default templates which include this token to generate PDF invoices when users download them, until you publish different templates. We recommend you configure and test these templates immediately.

Token category: Invoice line details

Populate the invoice lines with these tokens to display data such as product and edition name, billing frequency, quantity, fees, discounts, and credits. For more information, see Build invoice line tables.

These, and tokens from the Grouping and sorting category, are the only tokens valid for invoice line table components.

Token value for use in JSON	Description
{{Invoice Lines}}	List of invoice lines for all charges, discounts, and credits associated with an end user's purchase. Used for invoice lines table components.
{{Subscription ID}}	Subscription ID.
{{Subscription Type}}	Type of subscription.
{{Subscription Start Date}}	Date the subscription starts.
{{Product Name}}	Name of the product.
{{Product ID}}	Unique system-assigned product identifier.
{{Edition Name}}	Edition name.
{{Edition ID}}	Unique system-assigned product edition identifier.
{{Product Description}}	Description of the product as defined by the Marketplace Manager. For example, descriptions on the invoices are generated depending on the cost types of the products.
{{Billing Period Start}}	Billing period start date.
{{Billing Period End}}	Billing period end date.
{{Price Per Unit}}	Price for each unit of the product.
{{Quantity}}	Quantity of the product purchased, through checkout or metered usage.
{{Line Total}}	Total amount (charge) for the product: price multiplied by quantity.
{{Cost Type}}	Cost (charge) type. For example: Recurring flat, Recurring per unit, Termination fee, Set up fee. This key token references the Grouping and sorting category tokens such as {{Product Type - Contract Fee}} and {{Product Type - Add-On}} to determine sort order in invoice line tables. For more information, see Build invoice line tables.
{{Order Type}}	Type of order. For example: prepaid, postpaid.
{{IS CREDIT}}	Boolean value specifying whether the product is a credit. This key token references the Grouping and sorting category {{Product Type - Credit}} and {{Product Type - Non-Credit}} tokens to determine sort order in invoice line tables.
{{Billing Period}}	Billing period formatted with start and end dates separated by a hyphen. For example: June 1, 2018 - June 30, 2018

Token category: Grouping and sorting tokens

These, and tokens from the Invoice line details category, are the only tokens valid for invoice line table components. For more information, see Build invoice line tables.

Use the tokens in this category to define the Grouping and sorting order of invoice line details tokens. They do not display data. Instead, they group the type of data in the order you specify in the table component.

Token value for use in JSON	Description
Note:The Invoice line details token category {{Cost Type}} token references all tokens in this category except {{Product Type - Credit}} and {{Product Type - Non-Credit}} to determine sort order in invoice line tables. The Invoice line details token category {{IS CREDIT}} token references {{Product Type - Credit}} and {{Product Type - Non-Credit}} to determine sort order in invoice line tables.
{{Product Type - Recurring Flat}}	Products of cost type: RECURRING_FLAT.
{{Product Type - Recurring Per Unit}}	Products of cost type: RECURRING_PER_UNIT.
{{Product Type - One Time Flat}}	Products of cost type: ONE_TIME_FLAT.
{{Product Type - One Time Per Unit}}	Products of cost type: ONE_TIME_PER_UNIT
{{Product Type - Setup Fee}}	Products of cost type: SETUP_FEE
{{Product Type - Setup Fee Per Unit}}	Products of cost type: SETUP_PER_UNIT
{{Product Type - Metered Usage}}	Products of cost type: METERED_USAGE
{{Product Type - Discount Flat}}	Products of cost type: DISCOUNT_FLAT
{{Product Type - Discount Per Unit}}	Products of cost type: DISCOUNT_PER_UNIT
{{Product Type - Contract Fee}}	Products of cost type: CONTRACT_FEE
{{Product Type - Additional Fee}}	Products of cost type: ADDITIONAL_FEE
{{Product Type - Termination Fee}}	Products of cost type: TERMINATION_FEE
{{Product Type - Add-On}}	Resolves to the product of cost type: ADD_ON
{{Product Type - Credit}}	Products of cost type: credit.
{{Product Type - Non-Credit}}	Products of cost type: not a credit.

Token category: Tax summary details

Populate tax summary tables with these tokens to display tax data on invoices. In the default invoice templates, these appear below the invoice lines table, as shown in the following example image.

Populate tax summary table components with these tokens. For more information on tax summary table, see Build tax summary tables.

Token value for use in JSON	Description
{{Tax Summary}}	List of tax lines applicable to the invoice. Data for tax summary tables.
{{Tax Type}}	Name of the tax.
{{Tax Rate}}	Tax rate, expressed as a percentage.
{{Tax Amount}}	Tax amount for the tax type.
{{Taxable Amount}}	Total invoice charges subject to the tax type.

Token category: Pagination tokens

Use these tokens to display the page number and total number of pages in invoice headers and footers.

These are the only tokens valid for page number components. For more informaton on page numbers, see Build page number components.

Token value for use in JSON	Description
{{Page Number}}	Invoice page number.
{{Total Pages}}	Total number of invoice pages.