See also:
telecoms.cart functions| arg | required? | syntax | info |
|---|---|---|---|
items | N | array of item objects | items to add to the cart immediately; optional - you can always add them later with telecoms.cart.edit |
promo_code | N | string | If you have a promo code, specify it here; you may get some discounts depending on what the code |
An array of item records. An item record consists of a type sub-argument and then additional sub-arguments depending on the type.
The currently supported types are:
number if the cart item is a phone numbercall_credit if the cart item is call credit for prepay accountsnumber
A number cart item consists of these parameters:
type with a value of value "number"svcchg_optionID - specifies the service-package that will be assigned to the number
See telecoms.num.svcopt.list for a list of possible values.
svcchg_keyword - alternative to svcchg_optionID but specifying by keyword instead of ID; you cannot specify both.
See telecoms.num.svcopt.list for a list of possible values.
svcchg_until - if svcchg_optionID or svcchg_keyword have been specified, then this parameter is the date
up to which to charge for the service package. The format is YYYY-MM-DD, eg 2021-01-12 for 12 January 2021.
setup_fee - can only be specified by a system user; used for overriding the setup fee to a different value.
Supply the value in pounds (£GBP) and pence, eg 19.50, or 0.00 to make the setup free of charge.
call_credit
A call_credit cart item consists of just two parameters:
type with a value of value "number"amount_net - the amount of call credit to buy (for a prepay account) in pounds (£ / GBP) and pence.
VAT (if applicable) will be added automatically.cartID - this is the cartID that you will need to pass into the other telecoms.cart functions
in order to add, remove or change its contents, and to check out.
items - a list of the items in your cart; see telecoms.cart.get for more informationitems_meta - like items but contains additional data; see telecoms.cart.get for more informationTTL - time to live - how many seconds the cart will exist without any further updates.price_net - the total price of all of the items in the cart (without VAT) in pounds (£ / GBP) and pence.price_vat - the amount of VAT that will be charged. The total to pay will be price_net + price_vatCreating a new empty cart.
JSON example request:
POST https://live.apicontrol.co.uk/1/json
{
"auth" : {
"username" : "YOURUSERNAME",
"password" : "YOURPASSWORD",
},
"func" : "telecoms.cart.create",
"args" : {}
}
JSON example response:
{
"success" : 1,
"results" : {
"price_vat" : "0.00",
"items" : [],
"items_meta" : [],
"price_net" : "0.00",
"TTL" : 900,
"cartID" : 1838700
}
}
Note that the response contains the cartID. You will need to pass this value back in to the other cart functions in order to
update the cart or check out.
Creating a new cart with two phone numbers in it.
JSON example request:
POST https://live.apicontrol.co.uk/1/json
{
"auth" : {
"username" : "YOURUSERNAME",
"password" : "YOURPASSWORD",
},
"func" : "telecoms.cart.create",
"args" : {
"items" : [
{
"type" : "number",
"number" : "03330440770"
},
{
"type" : "number",
"number" : "03330440772"
}
]
}
}
JSON example response:
{
"success" : 1,
"results" : {
"cartID" : 1838704,
"items" : [
{
"svcchg_optionID" : 19,
"number" : "03330440770",
"type" : "number",
"svcchg_until" : "2021-09-30"
},
{
"svcchg_optionID" : 19,
"number" : "03330440772",
"svcchg_until" : "2021-09-30",
"type" : "number"
}
],
"items_meta" : [
{
"svcchg_until" : "2021-09-30",
"type" : "number",
"svcchg_price_monthly" : "2.95",
"svcchg_price" : "2.75",
"svcchg_keyword" : "standard",
"svcchg_months" : 0.933333333333333,
"number" : "03330440770",
"itemID" : 2,
"svcchg_optionID" : 19,
"setup_fee" : "49.00",
"item_total_price" : "51.75"
},
{
"svcchg_keyword" : "standard",
"svcchg_months" : 0.933333333333333,
"number" : "03330440772",
"svcchg_until" : "2021-09-30",
"type" : "number",
"svcchg_price_monthly" : "2.95",
"svcchg_price" : "2.75",
"svcchg_optionID" : 19,
"setup_fee" : "0.00",
"item_total_price" : "2.75",
"itemID" : 4
}
],
"TTL" : 900,
"price_vat" : "10.90",
"price_net" : "54.50"
}
}
There are several things to note here.
The items section returns the cart items in a format that is suitable for passing back in as the item list to other
cart functions.
The items_meta section returns the cart items in a format that is suitable for passing back in as the item list to other
cart functions.
If in the above example we just requested the first number, and then tried again to create a new cart but adding both numbers, the first number would be temporarily unavailable as it would be currently reserved by the cart created in the previous call (remember, each time you call this function it creates a new cart instance).
The cart will still be created, but it was only able to add the one number. The response will show you what failed.
JSON example response:
{
"results" : {
"price_vat" : "0.55",
"items_meta" : [
{
"type" : "number",
"setup_fee" : "0.00",
"svcchg_price" : "2.75",
"svcchg_months" : 0.933333333333333,
"itemID" : 16,
"number" : "03330440772",
"svcchg_price_monthly" : "2.95",
"svcchg_keyword" : "standard",
"svcchg_optionID" : 19,
"svcchg_until" : "2021-09-30",
"item_total_price" : "2.75"
}
],
"items" : [
{
"type" : "number",
"svcchg_optionID" : 19,
"number" : "03330440772",
"svcchg_until" : "2021-09-30"
}
],
"failures" : {
"number" : {
"03330440770" : "unavail; number not available"
}
},
"cartID" : 1838716,
"TTL" : 900,
"price_net" : "2.75"
},
"success" : 1
}
Note that the function still returned a success result because the cart itself was created, even though it was not able to add all of the requested items.
Example of creating a cart with a number and some prepay call credit (see telecoms.prepay).
JSON example request:
POST https://live.apicontrol.co.uk/1/json
{
"auth" : {
"username" : "YOURUSERNAME",
"password" : "YOURPASSWORD",
},
"func" : "telecoms.cart.create",
"args" : {
"items" : [
{
"number" : "03330440770",
"type" : "number"
},
{
"type" : "call_credit",
"amount_net" : "25.00"
}
]
}
}
JSON example response:
{
"success" : 1,
"results" : {
"TTL" : 900,
"price_net" : "76.26",
"cartID" : 1838762,
"items" : [
{
"number" : "03330440770",
"type" : "number",
"svcchg_optionID" : 19,
"svcchg_until" : "2021-09-30"
},
{
"type" : "call_credit",
"amount_net" : "25.00"
}
],
"price_vat" : "15.25",
"items_meta" : [
{
"svcchg_price" : "2.26",
"type" : "number",
"number" : "03330440770",
"svcchg_months" : 0.766666666666667,
"svcchg_keyword" : "standard",
"item_total_price" : "51.26",
"itemID" : 22,
"svcchg_price_monthly" : "2.95",
"svcchg_until" : "2021-09-30",
"setup_fee" : "49.00",
"svcchg_optionID" : 19
},
{
"amount_net" : "25.00",
"type" : "call_credit",
"itemID" : 24,
"item_total_price" : "25.00",
"bonus_net" : "0.00"
}
]
}
}
| arg | required? | syntax | info |
|---|---|---|---|
supplier_custID | see description | posint | Supply the master account custID if you're using one of our master API accounts, otherwise don't supply this argument. Requires one of billcomp, billcompID. |
custID | see description | posint | custID of the customer who is to own the shopping cart (leave blank to use your own account) |
billcomp | conditional | string | Identifies the supplier company; mutually exclusive with billcompID |
billcompID | conditional | posint | Identifies the supplier company; mutually exclusive with billcomp |
brand | N | string | brand name (if applicable) being used to sell to the customer |