createInvoiceLink

Use this method to create a link for an invoice. Returns the created invoice link as String on success.

Parameters

business_connection_idStringOptional

Unique identifier of the business connection on behalf of which the link will be created. For payments in Telegram Stars only.

titleStringRequiredminLen 1maxLen 32

Product name, 1-32 characters

descriptionStringRequiredminLen 1maxLen 255

Product description, 1-255 characters

payloadStringRequired

Bot-defined invoice payload, 1-128 bytes. This will not be displayed to the user, use it for your internal processes.

provider_tokenStringOptional

Payment provider token, obtained via @BotFather. Pass an empty string for payments in Telegram Stars.

currencyCurrenciesRequired

Three-letter ISO 4217 currency code, see more on currencies. Pass "XTR" for payments in Telegram Stars.

pricesLabeledPrice[]Required

Price breakdown, a JSON-serialized list of components (e.g. product price, tax, discount, delivery cost, delivery tax, bonus, etc.). Must contain exactly one item for payments in Telegram Stars.

subscription_periodIntegerOptional

The number of seconds the subscription will be active for before the next payment. The currency must be set to "XTR" (Telegram Stars) if the parameter is used. Currently, it must always be 2592000 (30 days) if specified. Any number of subscriptions can be active for a given bot at the same time, including multiple concurrent subscriptions from the same user. Subscription price must no exceed 10000 Telegram Stars.

max_tip_amountIntegerOptional Default: 0

The maximum accepted amount for tips in the smallest units of the currency (integer, not float/double). For example, for a maximum tip of US$ 1.45 pass maxtipamount = 145. See the exp parameter in currencies.json, it shows the number of digits past the decimal point for each currency (2 for the majority of currencies). Defaults to 0. Not supported for payments in Telegram Stars.

suggested_tip_amountsInteger[]Optional

A JSON-serialized array of suggested amounts of tips in the smallest units of the currency (integer, not float/double). At most 4 suggested tip amounts can be specified. The suggested tip amounts must be positive, passed in a strictly increased order and must not exceed max\tip\amount.

provider_dataStringOptional

JSON-serialized data about the invoice, which will be shared with the payment provider. A detailed description of required fields should be provided by the payment provider.

photo_urlStringOptional

URL of the product photo for the invoice. Can be a photo of the goods or a marketing image for a service.

photo_sizeIntegerOptional

Photo size in bytes

photo_widthIntegerOptional

Photo width

photo_heightIntegerOptional

Photo height

need_nameBooleanOptional

Pass True if you require the user's full name to complete the order. Ignored for payments in Telegram Stars.

need_phone_numberBooleanOptional

Pass True if you require the user's phone number to complete the order. Ignored for payments in Telegram Stars.

need_emailBooleanOptional

Pass True if you require the user's email address to complete the order. Ignored for payments in Telegram Stars.

need_shipping_addressBooleanOptional

Pass True if you require the user's shipping address to complete the order. Ignored for payments in Telegram Stars.

send_phone_number_to_providerBooleanOptional

Pass True if the user's phone number should be sent to the provider. Ignored for payments in Telegram Stars.

send_email_to_providerBooleanOptional

Pass True if the user's email address should be sent to the provider. Ignored for payments in Telegram Stars.

is_flexibleBooleanOptional

Pass True if the final price depends on the shipping method. Ignored for payments in Telegram Stars.

Returns

On success, String is returned.

GramIO Usage

// Create a Telegram Stars invoice link (no provider token needed)
const link = await bot.api.createInvoiceLink({
  title: "Premium Access",
  description: "30 days of premium features",
  payload: "premium_30d_user123",
  provider_token: "", // empty string for Stars
  currency: "XTR",
  prices: [{ label: "Premium Access", amount: 100 }],
});
console.log(link); // https://t.me/$...

// Create a fiat currency invoice link with tip support
const link = await bot.api.createInvoiceLink({
  title: "Coffee Donation",
  description: "Support the project",
  payload: "donation_coffee",
  provider_token: "YOUR_PROVIDER_TOKEN",
  currency: "USD",
  prices: [{ label: "Coffee", amount: 500 }], // $5.00 in cents
  max_tip_amount: 2000, // max $20 tip
  suggested_tip_amounts: [300, 500, 1000], // $3, $5, $10 suggested
});

// Create a recurring Stars subscription invoice link
const link = await bot.api.createInvoiceLink({
  title: "Monthly Newsletter",
  description: "Exclusive monthly content for subscribers",
  payload: "newsletter_monthly",
  provider_token: "",
  currency: "XTR",
  prices: [{ label: "Monthly subscription", amount: 50 }],
  subscription_period: 2592000, // must be exactly 30 days
});

// Create an invoice with shipping and contact info collection
const link = await bot.api.createInvoiceLink({
  title: "Physical Product",
  description: "Hand-crafted item shipped to your door",
  payload: "shop_item_42",
  provider_token: "YOUR_PROVIDER_TOKEN",
  currency: "EUR",
  prices: [
    { label: "Item", amount: 1500 }, // €15.00
    { label: "Shipping", amount: 500 }, // €5.00
  ],
  need_name: true,
  need_shipping_address: true,
  is_flexible: true, // final price depends on chosen shipping
});

Errors

Code	Error	Cause
400	`Bad Request: CURRENCY_TOTAL_AMOUNT_INVALID`	Total price amount is out of range for the selected currency
400	`Bad Request: INVOICE_PAYLOAD_INVALID`	`payload` is empty or exceeds 128 bytes
400	`Bad Request: provider_token is empty`	`provider_token` is empty but `currency` is not `"XTR"` — empty token is only valid for Stars
400	`Bad Request: SUBSCRIPTION_PERIOD_INVALID`	`subscription_period` is not `2592000` — the only currently supported value
400	`Bad Request: SUBSCRIPTION_CURRENCY_INVALID`	`subscription_period` is set but `currency` is not `"XTR"`
400	`Bad Request: PRICES_TOO_MANY`	Stars payments must have exactly 1 item in `prices`
400	`Bad Request: SUGGESTED_TIP_AMOUNTS_TOO_MANY`	More than 4 suggested tip amounts provided
400	`Bad Request: TIP_AMOUNTS_SORTED_INVALID`	`suggested_tip_amounts` must be in strictly increasing order
429	`Too Many Requests: retry after N`	Rate limit hit — check `retry_after`, use auto-retry plugin

TIP

Use GramIO's auto-retry plugin to handle 429 errors automatically.

Tips & Gotchas

For Telegram Stars, use currency: "XTR" and provider_token: "" (empty string). All shipping, contact data, and tip parameters are silently ignored for Stars.
Stars invoices must have exactly 1 item in prices. Multiple price components (e.g., item + tax) are only supported for fiat currencies.
payload is bot-internal — users never see it. Encode order context here (user ID, product ID, plan) so your pre_checkout_query handler knows what to fulfil.
Amounts are in the smallest currency unit. For USD/EUR, 500 = $5.00 / €5.00 (divide by 100). Check the exp field in currencies.json for other currencies.
subscription_period must be exactly 2592000 (30 days). No other value is currently accepted; subscriptions auto-renew monthly.
max_tip_amount defaults to 0 (tips disabled). Explicitly set a positive integer to enable tips; fiat-only, not supported for Stars.
The returned string is a t.me/$ invoice deep link that opens the payment UI when clicked — share it in messages, websites, or embed in QR codes.

createInvoiceLink ​

Parameters ​

Returns ​

GramIO Usage ​

Errors ​

Tips & Gotchas ​

See Also ​