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