See also:
telecoms.cart functions| arg | required? | syntax | info |
|---|---|---|---|
cartID | Y | posint | identifies the cart instance; the value returned by telecoms.cart.create |
This function fetches the detail of the cart identified by the cartID argument. Also, using this function
to fetch the cart contents also refreshes the cart's TTL value and refreshes the reservations of any
phone numbers it contains.
Even if the cart has expired, as long as it has not been purged from the system, this function will still fetch and resurrect it and also refresh the reservations on any numbers the cart contained, provided that the numbers have not been bought or reserved by someone else (or added to another cart whether yours or not). All reservations that can be refreshed will be.
As long as the cart was fetched successfully (even if empty), then the following parameters will be returned:
cartID - the ID of the cart instanceitems - an array of items in the cart, in a format suitable for sending to telecoms.cart.edit *items_meta - a superset of the items parameter - contains additional information which may be usefulTTL - time to live - the number of seconds that the items in the cart are guaranteed safeprice_net - the total price of all of the items in the cart, excluding VAT. Price is in £ (GBP).price_vat - the VAT payable on the cart total, should the cart be checked out. Price is in £ (GBP).telecoms.cart.create for that matter, but there would be few cases where that would be useful.
If the cart was successfully fetched but some items within could not be (eg if the cart was fetched after it had already expired and previously contained phone number that in the meantime someone else has bought or reserved) then you would also expect to see this parameter:
failures - keyed by item type, this contains one or more lists of items that could not be fetched.
These failed items will have been automatically removed from the cart.
items
The items parameter contains an array of cart items. Each cart item will have a type parameter.
Depending on the value of type, the item may have additional parameters.
The currently supported item types are:
number - a phone number - a phone number from phone of our phone number ranges, contains:
type - the string "number"number - the phone number itselfsvcchg_optionID - the ID of the service-package for the number, if one was selected.svcchg_until - if a service-package was selected, the monthly fee will be payable for an
initial period when you check out. This will typically be the end of the current month, but may vary depending on the package. This field
shows the end of that period. The price of the cart item will include the pro-rata service charge up to this date.
call_credit - prepaid call credit Note: service packages - some number types require a service package whereas there are some that don't. If you didn't select a service package on a number when you added it to your cart, and the number is a type where a service package is required, the cart will have chosen the default package for you.
items_metaTTLThe TTL (time to live) is the remaining time, in seconds, that the cart and its contents will be guaranteed, reserved for you and inaccessible to others. Without the TTL mechanism, somebody else could create a cart and add to it a phone number that you wanted, and then leave it there permanently. This strikes us as being rather mean. With the TTL mechanism, their cart will expire after a time, thus avoiding that situation.
failuresA successful cart fetch and refresh.
JSON example request:
POST https://live.apicontrol.co.uk/1/json
{
"auth" : {
"username" : "YOURUSERNAME",
"password" : "YOURPASSWORD",
},
"func" : "telecoms.cart.get",
"args" : {
"cartID" : 1838716
}
}
JSON example response:
{
"results" : {
"cartID" : 1838716,
"price_net" : "2.75",
"items_meta" : [
{
"svcchg_months" : 0.933333333333333,
"number" : "03330440772",
"svcchg_keyword" : "standard",
"setup_fee" : "0.00",
"svcchg_until" : "2021-09-30",
"svcchg_price" : "2.75",
"itemID" : 16,
"svcchg_optionID" : 19,
"svcchg_price_monthly" : "2.95",
"type" : "number",
"item_total_price" : "2.75"
}
],
"price_vat" : "0.55",
"items" : [
{
"number" : "03330440772",
"svcchg_optionID" : 19,
"type" : "number",
"svcchg_until" : "2021-09-30"
}
],
"TTL" : 900
},
"success" : 1
}
In this example, the cart had been allowed to expire before being re-fetched, and meanwhile somebody else added one of the numbers it previously contained into their own cart. The reservation had expired, so it was fair game and up for grabs.
You can see in the response that the one number has been retained, but the other one has been listed under failures.
JSON example request:
POST https://live.apicontrol.co.uk/1/json
{
"auth" : {
"username" : "YOURUSERNAME",
"password" : "YOURPASSWORD",
},
"func" : "telecoms.cart.get",
"args" : {
"cartID" : 1838704
}
}
JSON example response:
{
"success" : 1,
"results" : {
"price_net" : "2.75",
"TTL" : 900,
"items" : [
{
"number" : "03330440772",
"svcchg_optionID" : 19,
"svcchg_until" : "2021-09-30",
"type" : "number"
}
],
"price_vat" : "0.55",
"cartID" : 1838704,
"failures" : {
"number" : {
"03330440770" : "unavail; number not available"
}
},
"items_meta" : [
{
"item_total_price" : "2.75",
"number" : "03330440772",
"type" : "number",
"svcchg_months" : 0.933333333333333,
"svcchg_price" : "2.75",
"svcchg_price_monthly" : "2.95",
"svcchg_optionID" : 19,
"svcchg_until" : "2021-09-30",
"setup_fee" : "0.00",
"svcchg_keyword" : "standard",
"itemID" : 4
}
]
}
}
Trying (and failing) to fetch a cart that either has never existed or has expired and been purged.
JSON example request:
POST https://live.apicontrol.co.uk/1/json
{
"auth" : {
"username" : "YOURUSERNAME",
"password" : "YOURPASSWORD",
},
"func" : "telecoms.cart.get",
"args" : {
"cartID" : 998877
}
}
JSON example response:
{
"error" : "cartID not found within account",
"errornum" : "5.2.18",
"errordiags" : {
"errtype" : "perm",
"parent_account_arg" : "custID",
"child_val" : 998877,
"info" : "No cart found with cartID 998877 for custID 12345",
"child_arg" : "cartID",
"errclass" : "illegal",
"parent_account_val" : 12345
},
"success" : 0,
"results" : {}
}
| 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) |