Onboarding Process

Access to our APIs requires an access token. A token can be obtained by calling our OAuth token endpoint as follows:
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:

Name Value
grant_type client_credentials
client_id The Client ID value supplied for your tenant
client_secret The client secret for your tenant

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

{
access_token”: “token_value_here”,
“expires_in”: 86400,
“token_type”: “Bearer”
}

Header

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:

Name Description
client_id Client id to be used when authenticating
client_secret Secret to be used when authenticating

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:

Name Type Description
products array The array of products (see below)

 

The products array should objects with the following properties:

Name Type Description
externalProductId string Unique identifier for the product. Can be SKU or any other id, preferably the same as is used internally within your system(s)

 

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 return 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
Product 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:

 

Name Type Description
externalOrderId string Your system’s unique order reference / ID
orderSubmittedOn string Date / Time the order was submitted in ISO-8601 format
currency string Currency code for the transaction (i.e. GBP)
netOrderAmount number Total value (excluding sales tax)
grossOrderAmount number Total value (including sales tax)
sourceChannel string Channel the order originated from
items array Array of items in the order (see below)

 

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:

Name Type Description
sku string The SKU of the product ordered (case insensitive)
name string The name of the product
quantity number The quantity ordered
price number The price of the item

 

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 return 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 products per request


[
{
“externalOrderId”: “123“
… (other properties)
},
{
“externalOrderId”: “456“
… (other properties)
}
]

Responses:

  • 201 Data accepted
  • 401 Unauthorised

 

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:

 

Name Type Description
discriminator string Account specific identifier
payload array An array of CPA data per day

 

CPA data should contain the following properties:

Name Type Description
date string Date / Time the order was submitted in ISO-8601 format
cpa number The average cost to acquire a customer

 

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 return one of the following response codes:

  • 202 Data accepted
  • 401 Unauthorised