--- title: "Create QuickLink" method: POST path: "/api_quicklink.json" --- # Create QuickLink `POST /api_quicklink.json` ## Request - Base URL: `https://secure.telr.com/gateway` - URL: `https://secure.telr.com/gateway/api_quicklink.json` - Auth: none required Creates a new QuickLink and returns its shareable URL. Errors come back as `QuickLinkResponse.Code`; see the response samples for the full list. ## Headers - `Content-Type` string, required ## Request body - object - `QuickLinkRequest` object, required - `StoreID` integer, required: Your store ID. Numeric value only. - `AuthKey` string, required: Your authentication key. - `Details` object, required: Core QuickLink details. - `Desc` string, required: QuickLink title/description shown to the payer. 2–60 characters; truncated beyond 60. - `Cart` string, required: Cart ID / your reference for this QuickLink. Must be unique. Maximum 63 characters. - `Currency` string, required: 3-letter ISO currency code. Reference: https://www.iban.com/country-codes - `Amount` string, required: Amount in major units, e.g. 9 dollars 50 cents is "9.50". Must be greater than 0 unless `VariableValueMode.Status` (donation/variable-amount mode) is enabled. - `MinQuantity` integer: Minimum order quantity. The quantity range only applies when MinQuantity is at least 1 and MaxQuantity is at least 2 and not less than MinQuantity; otherwise both silently fall back to 1 (a fixed quantity of 1, no range). Also ignored, falling back to 1/1, when VariableValueMode or AdditionalValueMode is enabled. - `MaxQuantity` integer: Maximum order quantity. Must be at least 2 for the quantity range to take effect; MaxQuantity of 0 or 1 falls back to a fixed quantity of 1, same as MinQuantity above. - `FullName` string: Prefilled cardholder first + last name. - `Addr1` string: Prefilled cardholder address, line 1. - `City` string: Prefilled cardholder city. - `Country` string: Prefilled cardholder country, 2-letter ISO code. - `Email` string: Prefilled cardholder email address. - `Phone` string: Prefilled cardholder phone number. - `AgreementID` integer: Existing card-on-file agreement ID to link this QuickLink to. Must belong to this store. `Email` is required when set, and `RepeatBilling`/`VariableValueMode` fields must be omitted. - `ChangeCard` boolean: If true, paying via this QuickLink updates the card stored against `AgreementID` instead of taking a payment. Requires `AgreementID`. - `VariableValueMode` object: "Donation" mode. Lets the payer enter their own amount instead of a fixed `Details.Amount`. - `Status` integer: 1 to enable variable-amount mode, 0/omitted to disable. - `SectionTitle` string: Section title shown above the amount input on the payment page. - `AdditionalValueMode` object: Optional additional/tip percentage the payer can choose to add on top of the amount. - `Status` integer: 1 to enable, 0 to disable. Required if `Percentage` or `SectionTitle` is set. - `SectionTitle` string: Section title shown for the additional-value input. Maximum 64 characters. - `Percentage` integer: Default additional-value percentage, 0–50. - `RepeatBilling` object: Recurring billing configuration. Omit entirely for a one-off QuickLink. Not compatible with `AgreementID`. - `Status` boolean: Enable repeat billing. Mutually exclusive with `Auto`; set exactly one of the two. - `Auto` boolean: Enable repeat billing in auto-charge mode. Mutually exclusive with `Status`. - `Type` 'recurring' | 'unscheduled': Billing schedule type. Defaults to "recurring". "unscheduled" is only valid when `Auto` is not set. - `Amount` string: Regular payment amount, in major units. - `Period` string: Billing period unit, e.g. "M" (monthly) or "W" (weekly). - `Interval` integer: Number of periods between charges (e.g. Period="M", Interval=2 → every 2 months). - `Start` integer: Start day for the billing schedule. - `Term` integer: Maximum number of regular payments to take, 0–100. 0 = unlimited. - `Final` string: Final payment amount, if different from the regular `Amount`. Only used when `Term` > 0. - `Availability` object: Controls when the QuickLink is valid, and stock/quantity limits. - `NotValidBefore` object: QuickLink becomes valid at this date/time, in the store's configured timezone. Omit entirely for no restriction. - `Day` integer - `Month` integer - `Year` integer - `Hour` integer: 0–23. Optional; omit for start-of-day (00:00). - `Minute` integer: 0–59. Optional; omit for start-of-day (00:00). - `NotValidAfter` object: QuickLink expires after this date/time, in the store's configured timezone. Must not be before `NotValidBefore`. Omit entirely for no restriction. - `Day` integer - `Month` integer - `Year` integer - `Hour` integer: 0–23. Optional; omit for end-of-day (23:59). - `Minute` integer: 0–59. Optional; omit for end-of-day (23:59). - `StockControl` integer: 1 to enable stock/quantity limiting on this QuickLink, 0/omitted to disable. - `StockCount` integer: Initial stock level. Only used when `StockControl` is enabled. - `ShowStock` integer: 1 to display remaining stock count on the payment page. Only used when `StockControl` is enabled. - `StockTitle` string: Label shown next to the stock count. Defaults to "Remaining Stock" if empty. - `Splits` object[]: Split payment configuration. Divides the payout across multiple accounts. Only usable when split payments are enabled for the store. Percentages across all entries must sum to 100% or less. - `id` integer, required: Configured split-payout ID for this store, or 0 for an ad-hoc split defined inline via `type`/`value`. - `type` 'flat' | 'percentage' | 'remaining': Split type. "remaining" (at most one per request) takes whatever is left after other splits and must not have a `value`. - `value` string: Flat amount (major units) or percentage (0–100), depending on `type`. Not used with `type: remaining`. - `extra` object: Up to 7 arbitrary merchant-defined key/value fields, stored against the QuickLink and echoed back on payment. Additional properties beyond 7 are rejected. ## Response `200` 200 - union - object - `QuickLinkResponse` object - `Code` integer - `Status` string - `URL` string - object - `QuickLinkResponse` object - `Code` integer - `Status` string --- [API](https://skmtc.dev/telr/apis/quicklink-api.md) - [All operations](https://skmtc.dev/telr/apis/quicklink-api/llms.txt) - [OpenAPI document](https://skmtc.dev/telr/apis/quicklink-api/revisions/fc843e28af9e?raw)