Introduction
Uphance exposes a REST API that allows programmatic access to various data from a Uphance account. Datasets currently exposed include product, SKU, orders, invoices, payments, inventory, pick tickets and receiving tickets. Uphance API also provides webhooks that allow you to execute code in your application after specific events in Uphance.
All API requests will be over HTTPS. All webhook endpoints need to be HTTPS, also.
Establishing a Connection With the Uphance API
Prior to making API requests, your application will have to establish a connection with the Uphance API. This is achieved through three calls performed in sequential order.
1. Get an authorization token
Send the user's Uphance username and password to the Uphance API and receive an authorization access token.
POST https://api.uphance.com/oauth/token
This request should include a header "Content-type: application/json" and the following Params:
Optional Parameter:
expires_in: (integer, optional) Custom token expiry in seconds (default is 7.days = 604800 seconds)
{
"email": "[email protected]",
"password": "example123",
"grant_type": "password"
}
Example response:
{
"access_token": "2a87f33253ea6d9475a5b9c85146fd66fe17bf37958ea87b76a450e3c239bc29",
"token_type": "Bearer",
"expires_in": 604800,
"refresh_token": "b4f42a0fc9e5b32ac82df9f4efd7f1c9843764dde0472f9e5e987f8ae064f06d",
"created_at": 1754301091
}When the access token expires, you can use the refresh token to obtain a new one without re-authenticating.
POST https://api.uphance.com/oauth/token
{
"grant_type": "refresh_token",
"refresh_token": "b4f42a0fc9e5b32ac82df9f4efd7f1c9843764dde0472f9e5e987f8ae064f06d "
}
2. Get a list of Organizations the user has access
A user can have access to multiple organizations. The second step in establishing a connection is to get a list of organizations. This may return one or more organizations.
GET https://api.uphance.com/organisations
This request should include the following headers.
Authorization: Bearer ACCESS_TOKEN
Content-type: application/json
Example response:
{
"organisations": [
{
"id": 9579,
"name": "Uphance Demo"
}
]
}
3. Register the organization with the API
The final step in establishing the connection is to register the organization. This is done through the call Set Current Organization.
POST https://api.uphance.com/organisations/set_current_org
This request should include headers as in step 2 and the following Param:
organizationId: the ID of the organization from Step 2.
Example response:
{
"Status": "Updated"
}That completes the process of establishing a connection with the API and subsequent requests only need the bearer token. A re-authorization is needed only when the token expires.
Authentication
Each request made to the Uphance API must include a Authorization header, containing your access token returned above. For example:
Authorization: Bearer ACCESS_TOKEN
You can tell curl to add the header by appending the following to your curl command:
curl -H "Content-type: application/json" "Authorization: Bearer ACCESS_TOKEN"
You must access the API with HTTPS requests. HTTP requests to the API will always fail. Requests without an Authorization header will also fail.
Revoke Access Tokens
You can revoke access tokens issued via the Uphance API. This endpoint supports revoking:
Specific tokens
All tokens for the current user
The current token (default if no params are passed)
POST https://api.uphance.com/oauth/revoke_tokens
Requires valid Authorization:
Bearer ACCESS_TOKEN header.
You can pass one of the following optional parameters:
revoke_all: (boolean, optional) - Revoke all tokens belonging to the authenticated user.
tokens: (string[], optional) - Array of token strings to revoke specific tokens.
(no params) - If no params are passed, only the current access token is revoked.
Pagination
GET API endpoints that return multiple records use pagination to limit the number of records returned in a single request. You should use the paging metadata included in the response JSON body to navigate to the subsequent page if you require all records. To avoid rate limiting, you should download each page sequentially and not in parallel.
The metadata is included in a meta hash at the top level of the JSON document. The following example shows the metadata for the first page in a two page collection.
"meta": {
"current_page": 1,
"next_page": 2,
"prev_page": null,
"total_pages": 2,
"total_count": 128
}To fetch the second or subsequent pages, repeat the same call with a page parameter. For example, to get page 2 on Get all SKUs, your call would look like this:
GET https://api.uphance.com/skus?page=2
If no meta hash is present in the response, you can assume that responses from that endpoint are not paginated.