createBuyUrl
Syntax
createBuyUrl(
product_id,
buyer=array(),
payment_plan=array(),
tracking=array(),
valid_until='24h',
urls=array(),
placeholders=array(),settings=array(),
addons_array()
)
Creates a special order form URL that can be customized to the visitor. For example, customer data can be entered, and, if necessary, can be read-only. The prices can also be changed.
We provide an example PHP script together with our PHP-Connector-Class. You can find it in the zip archive in the file examples/buyurl.php.
Access rights
Full access required.
Arguments
product_id – the ID of the product in Digistore24 buyer – an array with this buyer data (all fields are optional):
- buyer[email]
- buyer[salutation] – M (for ‘male’) or F (for ‘female’)
- buyer[title] – z.B. “Prof.” or “Dr.”
- buyer[last_name]
- buyer[first_name]
- buyer[company]
- buyer[street]
- buyer[city]
- buyer[zipcode]
- buyer[state]
- buyer[country] – two-digit country code, see listCountries(). If the country code specified is not valid, the function will return an error.
- buyer[phone_no]
- buyer[tax_id]
- buyer[readonly_keys] – all’, ‘email’, ‘email_and_name’ or ‘none’ – indicates which fields are read-only. Remember to transfer the read-only values as well – otherwise the function will return an error. Default is ‘none’.
- buyer[id] – Buyer ID (buyer_id) or order ID (order_id). If specified, the address of this buyer/order is used.
payment_plan – an array with the data on the purchase price/payment plan. All fields are optional.
- payment_plan[first_amount] – the purchase price (or the first payment for subscription and installment payments), e.g. 17.99
- payment_plan[other_amounts] – for subscription or installment payments, the amount of the follow-up payments e.g. 39.50
- payment_plan[currency] – the three-digit currency code e.g. EUR or USD. If this is not specified, Digistore24 will automatically try to find the currency.
- payment_plan[number_of_installments] – the default value is „1“ and equals a single payment. For subscriptions/installments the value is set to „0“. ATTENTION: When using payplan_plan[other_amounts] the value for payplan_plan[number_of_installments] is set 0 (subscriptions/installments) by default.
- payment_plan[first_billing_interval] – for subscription or installment payments: the time interval between the purchase and second installment. Default is 1 month (“1_month”). Possible values are e.g. “10_day”, “12_month” etc.
- payment_plan[other_billing_intervals] –as above, only for the second and further payments
- payment_plan[test_interval] – gives a test period. Payment only begins after the test period. The format is as above e.g. “1_month”.
- payment_plan[template] – ID of the payment method used as a template. Any values that are not specified in getting up the API are then copied from the selected template. The * payment methods (incl. the IDs) can be found in the product editor in the tab “Payment method”.
- payment_plan[upgrade_order_id] –order ID of a subscription order for which an upgrade is to be purchased.
- payment_plan[upgrade_type]– possible values:
- upgrade = the new tariff starts immediately. The remaining balance from the current billing period will be credited. That is the default.
- downgrade = the new tariff starts at the beginning of the next billing period
- payment_plan[tax_mode]– possible values:
- as_set (default) = use price mode setting from product editor (tab payment plans)
- exclude = the prices in the payment plan are without tax. Vat resp. US sales tax will be added to the given prices.
- include = the prices in the payment plan are including vat. Vat will not be added. Only US sales tax will be added.
tracking – an array with the data for tracking. All fields are optional.
- tracking [custom] – the custom value which you as a vendor can transfer to the order form via the GET parameter “custom” and which is then looped through. Use this value as a reference for your own system. In the IPN notification about the order, the value of this field is then transferred as custom. The same applies for the API functions listPurchases() and getPurchase().
- tracking [affiliate] – the Digistore24 ID of the affiliate. If it is not valid, the function will return an error.
- tracking [affiliate_priority]- Use
- "email" to prefer the affiliate set by setAffiliateForEmail().
- "as_set" to prefer the affiliate given as tracking[affiliate] - this is the default.
- tracking [campaignkey] – the Campaignkey (of the affiliate)
- tracking [trackingkey] – the Trackingkey of the vendor (which can also be transferred to the order form as GET parameter “ds24tr”.
- tracking [utm_source]
tracking [utm_medium]
tracking [utm_campaign]
tracking [utm_term]
tracking [utm_content] - the utm tracking parameters. If one utm parameter is given, all utm paramters append to the created buy url later are ignored.
valid_until – Time period, indicates when the link becomes invalid. Default value is “24h” meaning that the link is valid for 24 hours. Enter “forever” to ensure the link never becomes invalid. All links become invalid 1 year after the last usage or (if never used) 1 year after creation.
urls – an array with the following (optional) URLs (all fields optional):
- urls [thankyou_url] – if specified, this URL will be used as a thank you page URL rather than the default product thank you page. You can use the thank you page URL placeholders in this URL.
- urls [fallback_url] – if the link has become invalid, the visitor will be directed to this URL. Default is the normal sales page of the product.
- urls[upgrade_error_url] – if “payment_plan[upgrade_order_id]” is specified, but the upgrade cannot be performed, then the visitor will be redirected to this URL.
placeholders – an array with placeholders for product name and product description
Example: For the placeholders [size] and [color], enter these arrays:
array( size => XL, color => blue )
The square brackets are automatically added to the name of the placeholder.
You can then use these placeholders in the product name, e.g. T-shirt size [size], color [color].
The order form will then display: T-shirt size XL, color blue.
For the array keys please only use the characters a-z, A-Z -9 _ –
The following array values are not allowed: < > & # ; “ ‚ ´`
The function getPurchase() lists these placeholders when details about an order are requested.
These placeholders are also transferred for IPN notifications. Here the name is preceded by a “placeholder_” e.g. placeholder_size = XL.
settings – further settings for the order form (all optional):
- settings[orderform_id] – the ID of the order form
- settings[img]– the ID of the product image or an array that specifies an image ID for the product IDs.
- Example 1:
…&settings[img]=ABCD1234
The first product receives image ABCD1234 - Example 2:
…&settings[img][987]=ABCD1234&settings[img][543]=EFGH9876&settings[img][default]=IJKL0011
Product 987 receives image ABCD1234, Product 543 image EFGH9876. All other images IJKL0011.
- Example 1:
- settings[affiliate_commission_rate] – the affiliate commission in percent
- settings[affiliate_commission_fix] – the affiliate commission as a fixed amount. If no affiliate commission is indicated, the affiliate will receive the default commission of their affiliate partnership with the product.
- settings[voucher_code] – If no discount is indicated, an attempt will be made to use the voucher with this code. If a discount is indicated, the discount will be displayed together with this voucher code.
- settings[voucher_1st_rate] – Discount on the first payment of the purchase in %. settings[voucher_oth_rates] – Discount on follow-up payments of the purchase in %.
- settings[voucher_1st_amount] – Discount on the first payment of the purchase in the specified currency.
- settings[voucher_oth_amounts] – Discount on follow-up payments of the purchase in the specified currency.
- settings[force_rebilling] – The buyer must use a payment method, which is capable of automated payments. This is use for for upgrade and billing on demand.
- settings[pay_methods] - The the payment methods offered for payment. Depending on country and currency some methods may not be available. E.g. elv is only available in EUR and in the EU. If elv is selected outside EU or for USD payments, this is ignored. Possible values are:
- paypal
- sezzle
- creditcard
- elv
- banktransfer
- klarna
addons – a list of add-on products as a two-dimensional array. First dimension is an index (integer starting with 0), second dimension is the fields, for example:
addons[0][product_id]=12345
addons[0][first_amount]=27.99
Any number of add-ons can be added.
- product_id
- first_amount – for subscription/installment payment: the first amount
- other_amounts – for subscription/installment payment: the amount of the follow-up payments
- single_amount – for single payments: the purchase amount
- default_quantity – preselected quantity (if selectable). Default: 1
- max_quantity_type
- unlimited (default – can be purchased any number of times)
- like_main_item (can be purchased as often as the main product)
- number (the number specified as max_quantity is used)
- max_quantity – only for max_quantity_type number: how many times a buyer can buy the product in one order.
- currency – if prices are given, then at least the first add-on should be given a currency (this then applies to all other add-ons). Default is EUR. If necessary, the prices will be converted into the purchase currency.
- is_quantity_editable_before_purchase – Y/N – can the buyer change the quantity before buying on the order form? Default: N
- is_quantity_editable_after_purchase – Y/N – can the buyer change the quantity after the purchase (for example, to add packages)? Default: N
Return data
id: the ID of the BuyUrl object url: the order URL via which the visitor can make a purchase valid_until: the date when the URL becomes invalid. If left empty, it will not become invalid. upgrade_status: Possible values:
- none, if “payment_plan[upgrade_order_id]” was not specified
- ok, if the upgrade can be performed
- error, if the upgrade cannot be performed
Upgrades
So that an upgrade can be performed, enter a Digistore24 order ID for the parameter “payment_plan[upgrade_order_id]”.
The upgrade can be performed:
- if the old and new orders are both subscription payments
- if the old order belongs to your vendor account
- if there hasn’t been an upgrade (or downgrade) for the old order
If the upgrade cannot be performed and the visitor visits the order form, then one of these two things will happen:
- If “urls[upgrade_error_url]” is specified, the visitor will be redirected to this URL
- Otherwise the purchase will be made without an upgrade
Whether or not the upgrade can be performed is checked in two places:
- Directly by getting up the API function CreateBuyUrl(). The result is given in the variable “upgrade_status” – see above.
- Directly before the purchase. After getting up the CreateBuyUrl(), an upgrade may become impossible if the buyer performs an upgrade for the order in any other way or revisits the order form after an upgrade.
Multi Step Order Box
You may use createBuyUrl() also for an order form of type multi step order box (msob).
To do so, create a multi step order box.
Copy the order form id from the url: It's the number at the end of the url.
Example:
For the url: https://www.digistore24-app.com/vendor/account/orderforms/edit/123
The order form id is: 123
Pass the orderform id as parameter settings[orderform_id] to createBuyUrl().
Replace the order form url in the msob's code by the buy url.
Example:
The original code is:
<!-- Begin of Digistore24 Multi Step Orderbox Code -->
<script src='https://www.digistore24.com/service/js/orderform_widget.js'></script>
<iframe class='ds24_payIFrame' style='overflow: hidden; width: 100%; height: 600px; border: none; background: transparent;' src='https://www.digistore24.com/product/987/123'></iframe>
<!-- End of Digistore24 Multi Step Orderbox Code -->
The url returned by createBuyUrl is:
https://www.digistore24.com/offer/123456/abcdefgh1234567/987
Then use this code:
<!-- Begin of Digistore24 Multi Step Orderbox Code -->
<script src='https://www.digistore24.com/service/js/orderform_widget.js'></script>
<iframe class='ds24_payIFrame' style='overflow: hidden; width: 100%; height: 600px; border: none; background: transparent;' src='https://www.digistore24.com/offer/123456/abcdefgh1234567/987'></iframe>
<!-- End of Digistore24 Multi Step Orderbox Code -->