UB HomeSupport
Guides
Start typing to search…

API endpoints (BETA)

Based on the flow described on the previous page, here's a list of all API endpoints and their params.

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

Parameter

Value

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

Parameter

Value

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.

Parameter

Value

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.

Parameter

Value

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

Parameter

Value

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

Parameter

Value

key string

API key

code

pin

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

Parameter

Value

number

e.g. 07777123456 or +447777123456

email

e.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

Parameter

Value

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

Parameter

Value

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

Parameter

Value

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

Parameter

Value

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

Parameter

Value

cvv string

CVV of the selected payment card.

Updated about 2 months ago