eBay fulfillment openAPI (V1)

Download OpenAPI specification:Download

Introduction

OrangeConnex is a standardized interface for fulfillment service providers and their customers.

Getting started

  • OC’s ERP team receive connection request

    seller/ERP initiate connection request

    Unless account details have been provided by the local OC team, the Seller/ERP system should send the following request to:ERPintegrationGB.EF@orangeconnex.com

    Customer Name ********limited(3PP-ERP do not required)
    Country/Region Mainland China/HK/DE/UK/AU
    OCID 00000000(3PP-ERP do not required)
    ERP Type Seller-ERP or 3PP-ERP
    ERP Name Seller-ERP Name/3PP-ERP Name
    OC Service DE/UK/AU(3PP-ERP do not required)

    *3PP-ERP means third party’s ERP , Seller-ERP means seller has its own ERP

  • OC open the testing account & information
    The OC team will request test accounts on behalf of Australian 3PPs. On receipt of a test account request, the OC team will generate a unique ClientKey & SecretKey for each 3PP.

  • SELLER/ERP initiate connection request in SANDBOX environment

    The OC team will verify the testing results and record the API connectors’ testing status as quickly as possible.

  • Opening of the production environment account
    After passing the ‘testing environment tests, the OC team will then open a production-environment account for the user and ERP system. It takes around 1-2 working days to action. In addition, third-party ERP needs to provide user set-up guidelines to help users finish set-up.

Authorization introduction

  • Authorization code & token’s connector explanation

    API name in document Connector Usage Explanation
    URL(getAuthorizationCode) Purpose:To allow the ERP system to request OC’s authorization code
    accessToken&refreshToken Usage:To allow the ERP system to request accessToken & refreshToken Please Note:The ‘access_token’ is valid for 3,600 seconds. If it has expired, please use ‘refresh_token’ to retrieve a new one. The “refresh token” is valid for one year, please store a record of the “refresh token” to make sure you can retrieve the ‘access token’
    refresh accessToken Purpose:To allow the ERP system to use the ‘refeshToken’ to retrieve a new “accessToken”

    Important note regarding the authorization code & token connectionURL(getAuthorizationCode)
    The ERP system receives OC’s authorization code via this connector.
    For more information, please refer to URL(getAuthorizationCode).
    A connection example is shown below:

    https://openapi-cn.orangeconnex.com/oauth/authorize?response_type=code&client_id=ClientKey&redirect_uri=http://en.newsign.com&state=userID

    Please Note: The highlighted sections are placeholders; Clients should replace these with their own information. ClientKey: the ClientKey which the client applyed before http://en.newsign.com: the website which the client wishes to access userID: username/userID used by ERP


    After inserting the link, the webpage will return to the OC website home page. At this point, please enter the client’s username/userID and password.

    Click "AGREE” button

    Following this, the webpage will return to the website entered into the code.
    The following syntax is used to copy the authorization code from the address. Please copy the returned authorization code into the highlighted area

    http://en.newsign.com?act=getAuthorizationCode&code=returned authorization code&state=userID (ERP user account)

    (Example of a returned web page)

  • accessToken&refreshToken
    The ERP system retrieves the ‘accessToken&refreshToken’ for the user via this connector.
    For more information, please refer to OC API SPECIFICATION section 1.1 accessToken & refreshToken.
    The following is an example connection message:
    https://openapi-cn.orangeconnex.com/oauth/token?grant_type=authorization_code&code=accessed authorization code&redirect_uri=http://en.newsign.com&client_id= ClientKey
    OC will return 2 tokens back to the ERP system

    {
      "access_token": "access_token information",
      "token_type": "bearer",
      "refresh_token": "refresh_token information",
      "expires_in": 3600
    }
    

    *[·-·]:Please Note
    access_token:is only valid for 3,600 seconds. If expired, please use the refresh token to generate another access token.
    refresh token:is valid for one year. Please store details of the refresh token to make sure you can retrieve a new access token.

  • refresh accessToken The ERP system will use the refresh_token to generate another access_token.
    For more information, please refer to OC API SPECIFICATION section 1.2 refresh accessToken.
    Connection example:
    POST /oauth/token?grant_type=refresh_token&refresh_token=“refresh_token”&client_id=“yourclientid” HTTP/1.1(Host: server.example.com, Content-Type: application/x-www-form-urlencoded)
    Response:

    {
      "access_token": "new access_token",
      "token_type": "bearer",
      "expires_in": 3600
    }
    

    *[·-·]:Please Note
    The Access_token’s validation time is very short, OC suggests that the code includes a re-access rule to prevent problems from occurring.

About this API

OAuth

The eF openAPI uses OAuth2 with the Authorization Code Grant for its endpoints. Users must have an active OrangeConnex Seller Portal account to authorize against the OAuth2 server. Applications and services using the API must acquire client credentials from OrangeConnex.

Application credentials

When making calls against the API, you need to do it in the context of an application. You will get the credentials for your application from OrangeConnex.

Application credentials consist of the following:

  • client_id - uniquely identifies your application
  • client_secret - secret used to authenticate your application
  • redirect_uri - the uri the OAuth2 server redirect to on authorization requests

Requesting authorization

When you want to authorize a user you redirect him to https://openapi-stage-hk.orangeconnex.com/oauth/authorize with the following query string parameters:

  • response_type - Must be set to "code" for the Authorization Code Grant.
  • redirect_uri - After the user accepts your authorization request this is the url that will be redirected to. It must match the redirect_uri in your client credentials.
  • client_id - Your applications identifier from your application credentials.
  • state - An opaque value that will be included when redirecting back after the user accepts the authorisation. This is not required, but is important for security considerations.

After successful authorization by the user, the OAuth2 server will redirect back to your applications callback with the following query string parameters:

  • code - The authorization code.
  • state - The state parameter that was sent in the request.

Verifying authorization

The authorization code you acquired in the last step will now be exchanged for an access token. In order to do this you need to POST a request to https://openapi-stage-hk.orangeconnex.com/oauth/token.

POST https://openapi-stage-hk.orangeconnex.com/oauth/token

Authorization: Basic application_basic_auth\n>Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=code&redirect_uri=redirect_uri

In the Authorization header Basic HTTP authentication is used. Your application credentials client_id will be used as the username and your client_secret as the password. The header should have the value "Basic" plus the Base64 encoded string comprising of client_id:client_secret.

The body of the request consist of the form encoded parameters:

  • grant_type - Must be set to "authorization_code".
  • code - The authorization code received from the previous step.
  • redirect_uri - Must match the redirect_uri in your client credentials.

A successful verification request will return a JSON response with the properties:

  • token_type - is always "Bearer"
  • expires_in - the time in seconds until the access token will expire
  • access_token - the access token used for API requests
  • refresh_token - token used to get a new access_token without needing to ask the user again

Now the APIs endpoints that need authorization can be called by setting the header

Authorization: Bearer access_token

Refreshing authorization

To get a new access_token (for example when the old one expired) one can POST a request to https://openapi-stage-hk.orangeconnex.com/oauth/token.

POST https://openapi-stage-hk.orangeconnex.com/oauth/token

Authorization: Basic application_basic_auth\n>Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=refresh_token

The Basic HTTP Authorization works exactly as in the verification step.

The body of the request consist of the form encoded parameters:

  • grant_type - Must be set to "refresh_token".
  • refresh_token - The refresh_token you acquired during verification.

The response will be the same as in the verification step.

Inbound

Slark Inbound Controller

Inbound Order Cancellation

If the seller doesn't want OC to fulfill orders they placed previously, seller can cancel these orders through 3PP and 3PP needs to sync canceled orders to OC.

Request
header Parameters
clientKey
required
string

clientKey

vAuthorization
required
string

vAuthorization

Access-Token
required
string

Access-Token

Request Body schema: application/json
apiVersion
string
object (Inbound TrackingReq)
messageId
string
timestamp
integer <int64>
Responses
200

OK

201

Created

401

Unauthorized

403

Forbidden

404

Not Found

post/3pp/inbound/v1/cancel
Request samples
application/json
{
  • "apiVersion": "string",
  • "data": {
    },
  • "messageId": "string",
  • "timestamp": 0
}

Place Inbound Order

When seller going to ship products into warehouse. They needs to place a inbound order from ERP first.

Request
header Parameters
clientKey
required
string

clientKey

vAuthorization
required
string

vAuthorization

Access-Token
required
string

Access-Token

Request Body schema: application/json
apiVersion
string
object (Inbound order list)
messageId
string
timestamp
integer <int64>
Responses
200

OK

201

Created

401

Unauthorized

403

Forbidden

404

Not Found

post/3pp/inbound/v1/creation
Request samples
application/json
{
  • "apiVersion": "string",
  • "data": {
    },
  • "messageId": "string",
  • "timestamp": 0
}

Inbound Order Detail Query

3PP can upload 'Customs Clearance' file if origin is not European countries

Request
header Parameters
clientKey
required
string

clientKey

vAuthorization
required
string

vAuthorization

Access-Token
required
string

Access-Token

Request Body schema: application/json
apiVersion
string
object (ExternalInboundOrderQueryInfoRequestDto)
messageId
string
timestamp
integer <int64>
Responses
200

OK

201

Created

401

Unauthorized

403

Forbidden

404

Not Found

post/3pp/inbound/v1/detail
Request samples
application/json
{
  • "apiVersion": "string",
  • "data": {
    },
  • "messageId": "string",
  • "timestamp": 0
}

Inbound Order List Query

3PP could get inbound order status through this API

Request
header Parameters
clientKey
required
string

clientKey

vAuthorization
required
string

vAuthorization

Access-Token
required
string

Access-Token

Request Body schema: application/json
apiVersion
string
object (Inbound TrackingReq)
messageId
string
timestamp
integer <int64>
Responses
200

OK

201

Created

401

Unauthorized

403

Forbidden

404

Not Found

post/3pp/inbound/v1/query
Request samples
application/json
{
  • "apiVersion": "string",
  • "data": {
    },
  • "messageId": "string",
  • "timestamp": 0
}

Inbound Label Query

The seller has create an inbound order successful,and they can use this API to print inbound carton label

Request
header Parameters
clientKey
required
string

clientKey

vAuthorization
required
string

vAuthorization

Access-Token
required
string

Access-Token

Request Body schema: application/json
apiVersion
string
object (ExternalInboundOrderQueryLabelRequestDto)
messageId
string
timestamp
integer <int64>
Responses
200

OK

201

Created

401

Unauthorized

403

Forbidden

404

Not Found

post/3pp/inbound/v1/query/labels
Request samples
application/json
{
  • "apiVersion": "string",
  • "data": {
    },
  • "messageId": "string",
  • "timestamp": 0
}

Upload Clearance Doc

3PP chold upload 'Customs Clearance' file if origin is not European countries

Request
header Parameters
clientKey
required
string

clientKey

vAuthorization
required
string

vAuthorization

Access-Token
required
string

Access-Token

Request Body schema: application/json
apiVersion
string
object (Inbound order Clearance File)
messageId
string
timestamp
integer <int64>
Responses
200

OK

201

Created

401

Unauthorized

403

Forbidden

404

Not Found

post/3pp/inbound/v1/upload/customs-clearance-file
Request samples
application/json
{
  • "apiVersion": "string",
  • "data": {
    },
  • "messageId": "string",
  • "timestamp": 0
}

Upload TrackingNo

3PP could upload tracking number if the shipping method is express

Request
header Parameters
clientKey
required
string

clientKey

vAuthorization
required
string

vAuthorization

Access-Token
required
string

Access-Token

Request Body schema: application/json
apiVersion
string
object (Order Shipment No File)
messageId
string
timestamp
integer <int64>
Responses
200

OK

201

Created

401

Unauthorized

403

Forbidden

404

Not Found

post/3pp/inbound/v1/upload/shipment-file
Request samples
application/json
{
  • "apiVersion": "string",
  • "data": {
    },
  • "messageId": "string",
  • "timestamp": 0
}

Outbound

Meepo Outbound Controller

Outbound Order Cancellation

When the seller doesn't want OCH to fulfill the non-MF orders they placed previously, they can cancel these orders through the 3PP site. The 3PP site needs to sync canceled orders to OCH.

Request
header Parameters
clientKey
required
string

clientKey

vAuthorization
required
string

vAuthorization

Access-Token
required
string

Access-Token

Request Body schema: application/json
apiVersion
string
object (ExternalOrderCancelRequestDTO)
messageId
string
timestamp
integer <int64>
Responses
200

OK

201

Created

401

Unauthorized

403

Forbidden

404

Not Found

post/3pp/outbound/v1/cancel
Request samples
application/json
{
  • "apiVersion": "string",
  • "data": {
    },
  • "messageId": "string",
  • "timestamp": 0
}

Place Outbound Order

When the seller place non-MF orders on the 3PP site and they want OCH fulfil the orders, the 3PP site could sync these orders to OCH through this API.

Request
header Parameters
clientKey
required
string

clientKey

vAuthorization
required
string

vAuthorization

Access-Token
required
string

Access-Token

Request Body schema: application/json
apiVersion
string
Array of objects (Outbound order list)
messageId
string
timestamp
integer <int64>
Responses
200

OK

201

Created

401

Unauthorized

403

Forbidden

404

Not Found

post/3pp/outbound/v1/creation
Request samples
application/json
{
  • "apiVersion": "string",
  • "data": [
    ],
  • "messageId": "string",
  • "timestamp": 0
}

Outbound Order Query v2

After the seller placed an order on the 3PP site, if they want to monitor or view order fulfillment status, OCH support 3PP querying orders information by an "order list" or by order creation/order status update time slot.

Request
header Parameters
clientKey
required
string

clientKey

vAuthorization
required
string

vAuthorization

Access-Token
required
string

Access-Token

Request Body schema: application/json
apiVersion
string
object (ExternalOrdersQueryRequestDTO)
messageId
string
timestamp
integer <int64>
Responses
200

OK

201

Created

401

Unauthorized

403

Forbidden

404

Not Found

post/3pp/outbound/v2/query
Request samples
application/json
{
  • "apiVersion": "string",
  • "data": {
    },
  • "messageId": "string",
  • "timestamp": 0
}

SKU

Nyx Sku Controller

Create SKU V1

The seller has SKUs maintained on the 3PP site, and they want to enroll in the MF program. Then they sync their SKUs that already existed on the 3PP site to the OCH platform. This API support batch sync.

Request
header Parameters
clientKey
required
string

clientKey

vAuthorization
required
string

vAuthorization

Access-Token
required
string

Access-Token

Request Body schema: application/json
apiVersion
string
Array of objects (SKU info)
messageId
string
timestamp
integer <int64>
Responses
200

OK

201

Created

401

Unauthorized

403

Forbidden

404

Not Found

post/3pp/sku/v1/creation
Request samples
application/json
{
  • "apiVersion": "string",
  • "data": [
    ],
  • "messageId": "string",
  • "timestamp": 0
}

3PP print SKU Label

If sellers want to print the SKU Label on the 3PP, they can use this API and OC will return the SKU label.

Request
header Parameters
clientKey
required
string

clientKey

vAuthorization
required
string

vAuthorization

Access-Token
required
string

Access-Token

Request Body schema: application/json
apiVersion
string
object (3PP SKU label print)
messageId
string
timestamp
integer <int64>
Responses
200

OK

201

Created

401

Unauthorized

403

Forbidden

404

Not Found

post/3pp/sku/v1/print/skuFor3pp
Request samples
application/json
{
  • "apiVersion": "string",
  • "data": {
    },
  • "messageId": "string",
  • "timestamp": 0
}

SKU query V1

The seller has SKUs maintained on the OC site, and then they sync their SKUs that already existed on the OC site to the 3PP platform. This API support batch sync.

Request
header Parameters
clientKey
required
string

clientKey

vAuthorization
required
string

vAuthorization

Access-Token
required
string

Access-Token

Request Body schema: application/json
apiVersion
string
object (SKU query)
messageId
string
timestamp
integer <int64>
Responses
200

OK

201

Created

401

Unauthorized

403

Forbidden

404

Not Found

post/3pp/sku/v1/query
Request samples
application/json
{
  • "apiVersion": "string",
  • "data": {
    },
  • "messageId": "string",
  • "timestamp": 0
}

Create SKU V2

The seller has SKUs maintained on the 3PP site, and they want to enroll in the MF program. Then they sync their SKUs that already existed on the 3PP site to the OCH platform. This API support batch sync. v2 version batteryType change:LB > BC = Button Cell DCB > OLB = Other Lithium Battery; OT > no change

Request
header Parameters
clientKey
required
string

clientKey

vAuthorization
required
string

vAuthorization

Access-Token
required
string

Access-Token

Request Body schema: application/json
apiVersion
string
Array of objects (SKU info)
messageId
string
timestamp
integer <int64>
Responses
200

OK

201

Created

401

Unauthorized

403

Forbidden

404

Not Found

post/3pp/sku/v2/creation
Request samples
application/json
{
  • "apiVersion": "string",
  • "data": [
    ],
  • "messageId": "string",
  • "timestamp": 0
}

SKU query V2

The seller has SKUs maintained on the 3PP site, and they want to enroll in the eBay fulfillment program. Then they sync their SKUs that already existed on the 3PP site to the OC platform. This API support batch sync.

Request
header Parameters
clientKey
required
string

clientKey

vAuthorization
required
string

vAuthorization

Access-Token
required
string

Access-Token

Request Body schema: application/json
apiVersion
string
object (SkuQueryRequestV2)
messageId
string
timestamp
integer <int64>
Responses
200

OK

201

Created

401

Unauthorized

403

Forbidden

404

Not Found

post/3pp/sku/v2/query
Request samples
application/json
{
  • "apiVersion": "string",
  • "data": {
    },
  • "messageId": "string",
  • "timestamp": 0
}

Create SKU V3

The seller has SKUs maintained on the 3PP site, and they want to enroll in the MF program. Then they sync their SKUs that already existed on the 3PP site to the OCH platform. This API support batch sync. v3 support UK warehouse

Request
header Parameters
clientKey
required
string

clientKey

vAuthorization
required
string

vAuthorization

Access-Token
required
string

Access-Token

Request Body schema: application/json
apiVersion
string
Array of objects (SkuCreationRequestV3)
messageId
string
timestamp
integer <int64>
Responses
200

OK

201

Created

401

Unauthorized

403

Forbidden

404

Not Found

post/3pp/sku/v3/creation
Request samples
application/json
{
  • "apiVersion": "string",
  • "data": [
    ],
  • "messageId": "string",
  • "timestamp": 0
}

SKU query V3

The seller has SKUs maintained on the OC site, and then they sync their SKUs that already exist on the OC site to the 3PP platform. This API supports batch sync.

Request
header Parameters
clientKey
required
string

clientKey

vAuthorization
required
string

vAuthorization

Access-Token
required
string

Access-Token

Request Body schema: application/json
apiVersion
string
object (SkuQueryRequestV3)
messageId
string
timestamp
integer <int64>
Responses
200

OK

201

Created

401

Unauthorized

403

Forbidden

404

Not Found

post/3pp/sku/v3/query
Request samples
application/json
{
  • "apiVersion": "string",
  • "data": {
    },
  • "messageId": "string",
  • "timestamp": 0
}

Setup EF services.

This API is used to join/exit EF services.

Request
header Parameters
clientKey
required
string

clientKey

vAuthorization
required
string

vAuthorization

Access-Token
required
string

Access-Token

Request Body schema: application/json
apiVersion
string
object (ExternalSkuJoinEfDTO)
messageId
string
timestamp
integer <int64>
Responses
200

OK

201

Created

401

Unauthorized

403

Forbidden

404

Not Found

post/3pp/sku/v1/setupEF
Request samples
application/json
{
  • "apiVersion": "string",
  • "data": {
    },
  • "messageId": "string",
  • "timestamp": 0
}

3PP Query SKU EF Service

This API is used to get the EF services available for SKU.

Request
header Parameters
clientKey
required
string

clientKey

vAuthorization
required
string

vAuthorization

Access-Token
required
string

Access-Token

Request Body schema: application/json
apiVersion
string
object (3PP Query SKU EF Service)
messageId
string
timestamp
integer <int64>
Responses
200

OK

201

Created

401

Unauthorized

403

Forbidden

404

Not Found

post/3pp/sku/v1/querySKUEFService
Request samples
application/json
{
  • "apiVersion": "string",
  • "data": {
    },
  • "messageId": "string",
  • "timestamp": 0
}

Stock

Weaver Controller

stockMovement

By requesting a timeslot, 3PP could get all the inventory movement details that happened during the giving time.

Request
header Parameters
clientKey
required
string

clientKey

vAuthorization
required
string

vAuthorization

Access-Token
required
string

Access-Token

Request Body schema: application/json
apiVersion
string
object (stock movement request info)
messageId
string
timestamp
integer <int64>
Responses
200

OK

201

Created

401

Unauthorized

403

Forbidden

404

Not Found

post/3pp/inventory/v1/movement
Request samples
application/json
{
  • "apiVersion": "string",
  • "data": {
    },
  • "messageId": "string",
  • "timestamp": 0
}

stockSnapshot

Per SKU, OCH would provide a location-specific inventory snapshot of the request time.

Request
header Parameters
clientKey
required
string

clientKey

vAuthorization
required
string

vAuthorization

Access-Token
required
string

Access-Token

Request Body schema: application/json
apiVersion
string
Array of objects (stockReq)
messageId
string
timestamp
integer <int64>
Responses
200

OK

201

Created

401

Unauthorized

403

Forbidden

404

Not Found

post/3pp/inventory/v1/snapshot
Request samples
application/json
{
  • "apiVersion": "string",
  • "data": [
    ],
  • "messageId": "string",
  • "timestamp": 0
}

stockSnapshotV2

Per SKU, OC will provide a location-specific inventory snapshot of the request time.

Request
Request Body schema: application/json
apiVersion
string
object (stock v2Req)
messageId
string
timestamp
integer <int64>
Responses
200

OK

201

Created

401

Unauthorized

403

Forbidden

404

Not Found

post/3pp/inventory/v2/snapshot
Request samples
application/json
{
  • "apiVersion": "string",
  • "data": {
    },
  • "messageId": "string",
  • "timestamp": 0
}

Warehouse

Invoker Controller

Warehouse List Query

When 3PP place non-MF orders to OCH, they need to tell OC from which warehouse the outbound order should be shipped and by which shipping service they want the outbound order to be fulfilled.

Request
header Parameters
clientKey
required
string

clientKey

vAuthorization
required
string

vAuthorization

Responses
200

OK

401

Unauthorized

403

Forbidden

404

Not Found

get/3pp/base/v1/service
Request samples
import java.net.*;
import java.net.http.*;
import java.util.*;

public class App {
  public static void main(String[] args) throws Exception {
    var httpClient = HttpClient.newBuilder().build();

    var host = "https://openapi-stage-hk.orangeconnex.com";
    var pathname = "/openapi/3pp/base/v1/service";
    var request = HttpRequest.newBuilder()
      .GET()
      .uri(URI.create(host + pathname ))
      .header("clientKey", "string")
      .header("vAuthorization", "string")
      .build();

    var response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());

    System.out.println(response.body());
  }
}