UB HomeSupport
Guides
  1. Direct API integration (BETA)

API endpoints (BETA)

Issue temporary access token (if you don’t have one)

If you do not already have an access token for a user, you need to issue a temporary access token. This creates a temporary user account which can later be converted into a registered user account or merged with an existing one if the user logs in with pre-existing details.

API endpoint##

POST https://api.ub.io/oauth/issue
ParameterValue
key
string		apiKey
platform
string		Optional.
Type of application: web, ios or android.

Example response##

The API will return an access token as a string. Subsequent requests must be made with the access_token header set to the value of the access token issued.

{
  "status": "success",
  "access_token": {
    "userId": 10360,
    "appId": 1,
    "token": "09385d8eaa733a339789f0ab2c815aa3b762b90[...]",
    "scope": {},
    "expiryDate": "2016-08-09T15:58:34.365Z",
    "id": "d5cf40da-[...]"
  },
  "secret": "27a5afc3bbd4b91e89c44d5c041fa187fe61e4d0[...]",
  "x-render-time": 132
}

Crawl product and wait for response from API

Before adding to basket, all products must be crawled. For a broader explanation of crawling, see the Crawling section.

API endpoint##

POST https://api.ub.io/products/crawl
ParameterValue
apiKey
string		API key
url
string		URL of the product (must be encoded)
wait
bool		true returns the crawl data as a JSON object.
false (default) performs the crawl with no returned result.
country
string		ISO_3166-1 alpha-2 (2 letters) country code, e.g. gb. Why?

cURL Example

curl -XPOST https://api.ub.io/products/crawl -d "apiKey=YOUR_API_KEY&url=PRODUCT_URL&wait=true&country=GB"

HTTPIE Example

http POST https://api.ub.io/products/crawl apiKey=API_KEY url=PRODUCT_URL wait:=true country=GB

Possible responses##

200 – success with product details. (Please note product.outOfStock value.)
403 – access restricted (rate limit reached or authentication failed)
404 – not found or shop not supported
50x – error. Please treat as out of stock. We receive automatic notifications for errors and will investigate accordingly.

Rate limiting##

We’re limiting API requests rate to 10,000 crawls per partner per hour. You can check X-Rate-Limit and X-Rate-Remaining headers of the HTTP response to see the limit and number of available crawls available to you.

Tempering your requests to keep them below 10k/hr will ensure the smooth running of your crawling.

Data returned from crawling##

The crawler will return the following data per product URL:

  • ID
  • Price
  • Currency
  • Title
  • Description
  • Images (Guaranteed one image, with scope for supporting multiple images in development.)
  • Attributes (with availability) e.g. size, colour.
    Item is out of stock.

Please note the format of the attribute data. The field names and values must match those being set in the set attributes phase of the purchase.

Example response

{
  "status": "success",
  "product": {
    "id": 2037067,
    "url": "http://www.marksandspencer.com/3-4-sleeve-striped-t-shirt/p/p22423712",
    "title": "3/4 Sleeve Striped T-Shirt",
    "price": {
      "value": 22.5,
      "currency": {
        "code": "GBP",
        "symbol": "£"
      },
      "text": "£22.50"
    },
    "currency": "£",
    "thumbnailUrl": "http://asset1.marksandspencer.com/is/image/mands/SD_01_T41_3865Q_E4_X_EC_90?$PDP_PROD_IMAGE_IPAD$",
    "attachments": [
      {
        "type": "image",
        "url": "http://asset1.marksandspencer.com/is/image/mands/SD_01_T41_3865Q_E4_X_EC_90?$PDP_PROD_IMAGE_IPAD$",
        "id": 1
      },
      {
        "type": "image",
        "url": "http://asset1.marksandspencer.com/is/image/mands/SD_01_T41_3865Q_E4_X_EC_90?$PDP_PROD_IMAGE$",
        "id": 2
      }
    ],
    "variants": {
      "name": "colour",
      "options": [
        {
          "value": "BlueMix",
          "text": "BlueMix",
          "available": true,
          "price": {
            "strValue": "22.50",
            "value": 22.5,
            "currency": "£"
          },
          "image": false,
          "picture": "http://asset1.marksandspencer.com/is/image/mands/SD_01_T41_3865Q_E4_X_EC_90?$PDP_PROD_IMAGE$",
          "url": "http://www.marksandspencer.com/3-4-sleeve-striped-t-shirt/p/p22423712",
          "title": "3/4 Sleeve Striped T-Shirt",
          "child": {
            "name": "size",
            "options": [
              {
                "value": "8DUMMY",
                "text": "8",
                "available": true,
                "title": "3/4 Sleeve Striped T-Shirt"
              },
              {
                "value": "10DUMMY",
                "text": "10",
                "available": true,
                "title": "3/4 Sleeve Striped T-Shirt"
              },
              {
                "value": "12DUMMY",
                "text": "12",
                "available": true,
                "title": "3/4 Sleeve Striped T-Shirt"
              },
            ],
            "price": {
              "max": 22.5,
              "min": 22.5,
              "value": 22.5,
              "currency": "£"
            }
          }
        },
        {
          "value": "CoralMix",
          "text": "CoralMix",
          "available": true,
          "price": {
            "strValue": "22.50",
            "value": 22.5,
            "currency": "£"
          },
          "image": false,
          "url": "http://www.marksandspencer.com/3-4-sleeve-striped-t-shirt/p/p22423712",
          "child": {
            "name": "size",
            "options": [
              {
                "value": "8DUMMY",
                "text": "8",
                "available": true,
                "picture": "http://asset1.marksandspencer.com/is/image/mands/SD_01_T41_3865Q_E4_X_EC_90?$PDP_PROD_IMAGE$",
                "title": "3/4 Sleeve Striped T-Shirt"
              },
              {
                "value": "10DUMMY",
                "text": "10",
                "available": true,
                "picture": "http://asset1.marksandspencer.com/is/image/mands/SD_01_T41_3865Q_C8_X_EC_90?$PDP_PROD_IMAGE$",
                "title": "3/4 Sleeve Striped T-Shirt"
              },
              {
                "value": "12DUMMY",
                "text": "12",
                "available": true,
                "picture": "http://asset1.marksandspencer.com/is/image/mands/SD_01_T41_3865Q_C8_X_EC_90?$PDP_PROD_IMAGE$",
                "title": "3/4 Sleeve Striped T-Shirt"
              },
            ],
            "price": {
              "max": 22.5,
              "min": 22.5,
              "value": 22.5,
              "currency": "£"
            }
          }
        }
      ],
      "maxPrice": 22.5,
      "minPrice": 22.5
    },
    "shop": {
      "id": "240",
      "name": "Welcome to Marks & Spencer",
      "url": "http://www.marksandspencer.com",
      "shippingOptions": [
        {
          "id": 3163,
          "text": "Standard Delivery",
          "price": 7,
          "threshold": null
        },
        {
          "id": 3164,
          "text": "Express Delivery",
          "price": 12,
          "threshold": null
        }
      ]
    },
    "recrawling": 1439223561384
  },
  "x-render-time": 71
}

Add product to basket

Once products are crawled and determined to be in stock, they can be added to basket.

API endpoint##

POST https://api.ub.io/basket/add/:productId

productId is returned from the data returned from each of the crawling steps.

ParameterValue
options
JSON object		Optional element which contains the affiliate URL we will use to place the order. You'll need this to get paid.
e.g. { affiliateUrl: 'http://[...]' }

Responses##

200 – success with basket returned
403 – access restricted (rate limit reached or authentication failed)
404 – not found or invalid product added to basket.
50x – error.

Removing products from basket

API endpoint##

DELETE https://api.ub.io/basket/remove/:lineId

Please note that lineId is used, not productId.

Responses

200 – success with basket returned
403 – access restricted
404 – basket or lineId not found
50x – error.

Retrieve basket

You can retrieve the basket at any time.

API endpoint##

GET https://api.ub.io/basket/get
curl -sS -X GET https://api.ub.io/basket/get

Example response##

The full basket object with all products, selected products etc.

{
  "status": "success",
  "basket": {
    "id": "f2b30f6a-[...]",
    "appId": 1,
    "identifier": "sda49237",
    "subtotal": {
      "value": 22.5,
      "currency": {
        "code": "GBP",
        "symbol": "£"
      },
      "text": "£22.50"
    },
    "total": {
      "value": 26,
      "currency": {
        "code": "GBP",
        "symbol": "£"
      },
      "text": "£26.00"
    },
    "transactions": [
      {
        "shop": {
          "id": "240",
          "name": "Welcome to Marks & Spencer",
          "url": "http://www.marksandspencer.com",
          "currency": "GBP",
          "itemsLimit": 0,
          "shippingOptions": [
            {
              "id": "2540",
              "text": "Standard Delivery",
              "price": {
                "value": 3.5,
                "currency": {
                  "code": "GBP",
                  "symbol": "£"
                },
                "text": "£3.50"
              }
            }
          ]
        },
        "lines": [
          {
            "id": "47e66ee6-b048-4c8f-a27b-484fe659ccc2",
            "product": {
              "id": 2037067,
              "url": "http://www.marksandspencer.com/3-4-sleeve-striped-t-shirt/p/p22423712",
              "title": "3/4 Sleeve Striped T-Shirt",
              "price": {
                "value": 22.5,
                "currency": {
                  "code": "GBP",
                  "symbol": "£"
                },
                "text": "£22.50"
              },
              "currency": "£",
              "thumbnailUrl": "http://asset1.marksandspencer.com/is/image/mands/SD_01_T41_3865Q_E4_X_EC_90?$PDP_PROD_IMAGE_IPAD$",
              "attachments": [
                {
                  "type": "image",
                  "url": "http://asset1.marksandspencer.com/is/image/mands/SD_01_T41_3865Q_E4_X_EC_90?$PDP_PROD_IMAGE_IPAD$",
                  "id": 1
                }
              ],
              "variants": {
                "name": "colour",
                "options": [
                  {
                    "value": "BlueMix",
                    "text": "BlueMix",
                    "available": true,
                    "price": {
                      "strValue": "22.50",
                      "value": 22.5,
                      "currency": "£"
                    },
                    "image": false,
                    "picture": "http://asset1.marksandspencer.com/is/image/mands/SD_01_T41_3865Q_E4_X_EC_90?$PDP_PROD_IMAGE$",
                    "url": "http://www.marksandspencer.com/3-4-sleeve-striped-t-shirt/p/p22423712",
                    "title": "3/4 Sleeve Striped T-Shirt",
                    "child": {
                      "name": "size",
                      "options": [
                        {
                          "value": "8DUMMY",
                          "text": "8",
                          "available": true,
                          "title": "3/4 Sleeve Striped T-Shirt"
                        },
                        {
                          "value": "10DUMMY",
                          "text": "10",
                          "available": true,
                          "title": "3/4 Sleeve Striped T-Shirt"
                        },
                        {
                          "value": "12DUMMY",
                          "text": "12",
                          "available": true,
                          "title": "3/4 Sleeve Striped T-Shirt"
                        }
                      ],
                      "price": {
                        "max": 22.5,
                        "min": 22.5,
                        "value": 22.5,
                        "currency": "£"
                      }
                    }
                  },
                  {
                    "value": "CoralMix",
                    "text": "CoralMix",
                    "available": true,
                    "price": {
                      "strValue": "22.50",
                      "value": 22.5,
                      "currency": "£"
                    },
                    "image": false,
                    "picture": "http://asset1.marksandspencer.com/is/image/mands/SD_01_T41_3865Q_C8_X_EC_90?$PDP_PROD_IMAGE$",
                    "url": "http://www.marksandspencer.com/3-4-sleeve-striped-t-shirt/p/p22423712",
                    "child": {
                      "name": "size",
                      "options": [
                        {
                          "value": "8DUMMY",
                          "text": "8",
                          "available": true,
                          "title": "3/4 Sleeve Striped T-Shirt"
                        },
                        {
                          "value": "10DUMMY",
                          "text": "10",
                          "available": true,
                          "title": "3/4 Sleeve Striped T-Shirt"
                        },
                        {
                          "value": "12DUMMY",
                          "text": "12",
                          "available": true,
                          "title": "3/4 Sleeve Striped T-Shirt"
                        }
                      ],
                      "price": {
                        "max": 22.5,
                        "min": 22.5,
                        "value": 22.5,
                        "currency": "£"
                      }
                    }
                  }
                ],
                "maxPrice": 22.5,
                "minPrice": 22.5
              },
              "shop": {
                "id": "240",
                "name": "Welcome to Marks & Spencer",
                "url": "http://www.marksandspencer.com"
              },
              "recrawling": 0
            },
            "attributes": {},
            "selectedAttributes": [],
            "quantity": 1
          }
        ],
        "selectedShippingOption": {
          "id": "2540",
          "text": "Standard Delivery",
          "price": {
            "value": 3.5,
            "currency": {
              "code": "GBP",
              "symbol": "£"
            },
            "text": "£3.50"
          }
        },
        "estimatedShipping": {
          "value": 3.5,
          "currency": {
            "code": "GBP",
            "symbol": "£"
          },
          "text": "£3.50"
        },
        "subtotal": {
          "value": 22.5,
          "currency": {
            "code": "GBP",
            "symbol": "£"
          },
          "text": "£22.50"
        },
        "total": {
          "value": 26,
          "currency": {
            "code": "GBP",
            "symbol": "£"
          },
          "text": "£26.00"
        },
        "baseCurrency": "GBP"
      }
    ],
    "itemsTotal": 1,
    "updating": false,
    "multipleCurrencies": false,
    "baseCurrency": "GBP",
    "successfulTransactions": [
      {
        "shop": {
          "id": "240",
          "name": "Welcome to Marks & Spencer",
          "url": "http://www.marksandspencer.com",
          "currency": "GBP",
          "itemsLimit": 0,
          "shippingOptions": [
            {
              "id": "2540",
              "text": "Standard Delivery",
              "price": {
                "value": 3.5,
                "currency": {
                  "code": "GBP",
                  "symbol": "£"
                },
                "text": "£3.50"
              }
            }
          ]
        },
        "lines": [
          {
            "id": "47e66ee6-b048-4c8f-a27b-484fe659ccc2",
            "product": {
              "id": 2037067,
              "url": "http://www.marksandspencer.com/3-4-sleeve-striped-t-shirt/p/p22423712",
              "title": "3/4 Sleeve Striped T-Shirt",
              "price": {
                "value": 22.5,
                "currency": {
                  "code": "GBP",
                  "symbol": "£"
                },
                "text": "£22.50"
              },
              "currency": "£",
              "thumbnailUrl": "http://asset1.marksandspencer.com/is/image/mands/SD_01_T41_3865Q_E4_X_EC_90?$PDP_PROD_IMAGE_IPAD$",
              "attachments": [
                {
                  "type": "image",
                  "url": "http://asset1.marksandspencer.com/is/image/mands/SD_01_T41_3865Q_E4_X_EC_90?$PDP_PROD_IMAGE_IPAD$",
                  "id": 1
                }
              ],
              "variants": {
                "name": "colour",
                "options": [
                  {
                    "value": "BlueMix",
                    "text": "BlueMix",
                    "available": true,
                    "price": {
                      "strValue": "22.50",
                      "value": 22.5,
                      "currency": "£"
                    },
                    "image": false,
                    "picture": "http://asset1.marksandspencer.com/is/image/mands/SD_01_T41_3865Q_E4_X_EC_90?$PDP_PROD_IMAGE$",
                    "url": "http://www.marksandspencer.com/3-4-sleeve-striped-t-shirt/p/p22423712",
                    "title": "3/4 Sleeve Striped T-Shirt",
                    "child": {
                      "name": "size",
                      "options": [
                        {
                          "value": "8DUMMY",
                          "text": "8",
                          "available": true,
                          "title": "3/4 Sleeve Striped T-Shirt"
                        },
                        {
                          "value": "10DUMMY",
                          "text": "10",
                          "available": true,
                          "title": "3/4 Sleeve Striped T-Shirt"
                        },
                        {
                          "value": "12DUMMY",
                          "text": "12",
                          "available": true,
                          "title": "3/4 Sleeve Striped T-Shirt"
                        }
                      ],
                      "price": {
                        "max": 22.5,
                        "min": 22.5,
                        "value": 22.5,
                        "currency": "£"
                      }
                    }
                  },
                  {
                    "value": "CoralMix",
                    "text": "CoralMix",
                    "available": true,
                    "price": {
                      "strValue": "22.50",
                      "value": 22.5,
                      "currency": "£"
                    },
                    "image": false,
                    "picture": "http://asset1.marksandspencer.com/is/image/mands/SD_01_T41_3865Q_C8_X_EC_90?$PDP_PROD_IMAGE$",
                    "url": "http://www.marksandspencer.com/3-4-sleeve-striped-t-shirt/p/p22423712",
                    "child": {
                      "name": "size",
                      "options": [
                        {
                          "value": "8DUMMY",
                          "text": "8",
                          "available": true,
                          "title": "3/4 Sleeve Striped T-Shirt"
                        },
                        {
                          "value": "10DUMMY",
                          "text": "10",
                          "available": true,
                          "title": "3/4 Sleeve Striped T-Shirt"
                        },
                        {
                          "value": "12DUMMY",
                          "text": "12",
                          "available": true,
                          "title": "3/4 Sleeve Striped T-Shirt"
                        }
                      ],
                      "price": {
                        "max": 22.5,
                        "min": 22.5,
                        "value": 22.5,
                        "currency": "£"
                      }
                    }
                  }
                ],
                "maxPrice": 22.5,
                "minPrice": 22.5
              },
              "shop": {
                "id": "240",
                "name": "Welcome to Marks & Spencer",
                "url": "http://www.marksandspencer.com"
              },
              "recrawling": 0
            },
            "attributes": {},
            "selectedAttributes": [],
            "quantity": 1
          }
        ],
        "selectedShippingOption": {
          "id": "2540",
          "text": "Standard Delivery",
          "price": {
            "value": 3.5,
            "currency": {
              "code": "GBP",
              "symbol": "£"
            },
            "text": "£3.50"
          }
        },
        "estimatedShipping": {
          "value": 3.5,
          "currency": {
            "code": "GBP",
            "symbol": "£"
          },
          "text": "£3.50"
        },
        "subtotal": {
          "value": 22.5,
          "currency": {
            "code": "GBP",
            "symbol": "£"
          },
          "text": "£22.50"
        },
        "total": {
          "value": 26,
          "currency": {
            "code": "GBP",
            "symbol": "£"
          },
          "text": "£26.00"
        },
        "baseCurrency": "GBP"
      }
    ],
    "failedTransactions": [],
    "shipping": {
      "value": 3.5,
      "currency": {
        "code": "GBP",
        "symbol": "£"
      },
      "text": "£3.50"
    }
  },
  "x-render-time": 131
}

Set product options (colour, size etc.)

Once products are added to basket, the product options (size, colour etc) must be set. This is done on a per line-item basis. The line item IDs are returned in the basket response from the add to basket step.

API endpoint##

PUT https://api.ub.io/basket/update/:lineId

The parameters of the request must match the attribute names and values from the product crawl data. e.g.

size=6
color=white

Data returned from setting product options##

The full basket object with the updated attributes will be returned with each request.

Set delivery (shipping) option

This can usually be left as default.

API endpoint##

POST https://api.ub.io/basket/shippingOption

The parameters must specify the ID of the shop and the ID of the shipping option for that shop.

ParameterValue
shopId
string		ID of the shop.
id
string		Value of the shipping option chosen. Value must match the product crawl data.

Submit mobile number for verification

API endpoint##

POST https://api.ub.io/oauth/mobileverify
ParameterValue
key
string		API key
number
string		This should be in international format and include the country code, e.g. +447777123456

Data returned##

If the response includes { verify: true } this means that the mobile number is being changed - either from NULL for a new user or from a different number for an existing user. Therefore the mobile number must be verified by sending the PIN. If the response includes { userIsRegistered: true } it means that the mobile number is already associated with an active user.

Verify mobile number by entering pin

API endpoint##

POST https://api.ub.io/oauth/mobileverify/complete
ParameterValue
key
string		API key
codepin
number
string		Your user's mobile number

Data returned##

If the mobile number PIN verification is successful, a new access_token will be returned. This must replace the existing access token stored in the app and the full user should be reloaded (see Retrieve User).

Update contact information (email, mobile number)

API endpoint##

POST https://api.ub.io/user/update
ParameterValue
numbere.g. 07777123456 or +447777123456
emaile.g. [email protected]

Retrieve user

API endpoint##

GET https://api.ub.io/user/me

Get user addresses

API endpoint##

GET https://api.ub.io/address/list

Get user payment cards

API endpoint##

GET https://api.ub.io/card/list

Add address

API endpoint##

POST https://api.ub.io/address/add
ParameterValue
firstname
string		user.firstname
lastname
string		user.lastname
title
string		user.title
countryId
int		user.countryId (currently with a value of 1 for UK)
phoneCountry
string		user.phoneCountry
phone
string		user.phone
line1
string		Address line 1, e.g. '1 Buckingham Palace Road'.
line2
string		Address line 2, e.g. 'Flat 2'.
city
string		e.g. 'London'.
company
string		e.g. 'MegaCorp'
province
string		Province or county, e.g. 'Greater London'
postcode
string		e.g. 'SW1 9JE'.

Select delivery address

API endpoint##

PUT https://api.ub.io/basket/update
ParameterValue
shippingAddressId
string		The ID value of the applicable address in the User object, e.g. '1'.

Add payment card

API endpoint##

POST https://api.ub.io/card/add
ParameterValue
number
string		PAN, e.g. '4111111111111111'.
expiryDate
string		Card expiry date in mm/yy format, e.g. ''12/18'.
name
string		Cardholder name, e.g. 'Mr Bob Smith'.
addressId
string		The ID value of the applicable address in the User object, e.g. '1'
cvv
string		CVV/CVC of the payment card. (Used for validation, not stored.)

Select payment card

API endpoint##

PUT https://api.ub.io/basket/update
ParameterValue
cardId
string		The ID value of the card, e.g. '1'

Place orders with CVV

The final step is to place the orders. The CVV is not stored in the UB database and therefore must be passed into this request in order to complete the order.

API endpoint##

POST https://api.ub.io/basket/checkout
ParameterValue
cvv
string		CVV of the selected payment card.

Updated 11 months ago