Client onboarding

Access to our APIs requires an access token. A token can be obtained by calling our OAuth token endpoint. You should make an OAuth client_credentials request to the following URL:

https://svc.upp.ai/auth/oauth/token

The POST request should contain a form body (content-type application/x-www-form-urlencoded) with the following properties:

You will receive a response similar to the following containing your access token:

{
  "access_token": "token_value_here",
  "expires_in": 86400,
  "token_type": "Bearer"
}

Headers

After authentication, calls to all APIs should contain the following headers:

Content-Type: application/json
Accept: application/json
Authorization: Bearer my_token_here
Api-Version: 1

Where my_token_here is the value of the access token received from the Auth endpoint.

Data formatting

In almost all cases, data sent to and received from Upp APIs will be in JSON format.

Tenant-specific values

You will be supplied with the following values which are specific to your tenant to use in API calls:

Upp’s ingest API is used to collect product information, including pricing and stock details. Whenever there is a change in relevant data, the full product information should be sent to the API.

API details

Product information should be supplied as an HTTP POST to the following URL:

https://svc.upp.ai/ingest/bulk

The maximum batch size is 1000 products per request.

The following properties must be supplied in the JSON body of the request:

The products array should contain objects with the following properties:

Any other JSON properties and structure. Property names are not mandated however the data should ideally include values for the following as a minimum:

• SKU (case insensitive)
• Title
• GroupId (how you group SKUs)
• Main Image
• Price
• Stock Count
• Cost of Goods
• Currency (Cost of Goods currency)

{
  "products": [
    {
      "sku": "AB-1",
      "title": "My product",
      "groupId": "AB",
      "imageUrl": "http://a.valid.url/to_my_image",
      "stock": 100,
      "price": 99.99,
      "costOfGoods": 58.99,
      "currency": "GBP"
    }
  ]
}

Responses

The API returns one of the following response codes:

• 202 Data accepted
• 401 Unauthorised

Upp’s order API is used to collect details of orders in real time. Order data can be sent to the API at any point after the order has been placed.

API details

Order information should be supplied as an HTTP POST to the following URL:

https://svc.upp.ai/orders

The following properties must be supplied in the JSON body of the request:

Note. If the externalOrderId already exists in our system, we will update the existing document, instead of creating a new one.

Order Items should contain the following properties:

Example

POST https://svc.upp.ai/orders

{
  "externalOrderId": "test-order-2",
  "orderSubmittedOn": "2020-10-28T13:00:00Z",
  "currency": "GBP",
  "netOrderAmount": 19.99,
  "grossOrderAmount": 19.99,
  "sourceChannel": "web",
  "items": [
    {
      "sku": "AB-1",
      "name": "A product",
      "quantity": 1,
      "price": 19.99
    }
  ]
}

Responses

The API returns one of the following response codes:

• 201 Data accepted
• 401 Unauthorised

Bulk endpoint

POST https://svc.upp.ai/orders/bulk

The maximum batch size is 1000 orders per request.

[
  {
    "externalOrderId": "123"
    // ... (other properties)
  },
  {
    "externalOrderId": "456"
    // ... (other properties)
  }
]

Responses:

• 201 Data accepted
• 401 Unauthorised

Reading orders

To view orders submitted via the API, utilise the Get endpoint:

GET https://svc.upp.ai/orders

Responses:

• 200 OK
• 401 Unauthorised

Upp’s CPA API is used to collect details of cost per acquisition. CPA can be sent to the API at any point after the data has been calculated.

API details

CPA information should be supplied as an HTTP POST to the following URL:

https://svc.upp.ai/cpa

The following properties must be supplied in the JSON body of the request:

CPA data should contain the following properties:

Example

POST https://svc.upp.ai/cpa

{
  "discriminator": "uk",
  "payload": [
    {
      "date": "2021-11-28T00:00:00.000Z",
      "cpa": 30.03
    },
    {
      "date": "2021-11-29T00:00:00.000Z",
      "cpa": 34.74
    },
    {
      "date": "2021-11-30T00:00:00.000Z",
      "cpa": 27.56
    }
  ]
}

Responses

The API returns one of the following response codes:

• 202 Data accepted
• 401 Unauthorised