S
Sails
Dashboard
Browse Docs
IntroductionAuthenticationSDK Installation
Pricing Endpoints
Product Prediction
Listing Tools
eBay Endpoints
OAuth Sign-In URLOAuth Exchange CodeOAuth RefreshCategory SuggestionsItem AspectsCategory FeaturesInventory LocationsFulfillment PoliciesGet UserUpload PicturePost ItemEnd Item

eBay Endpoints

Use these endpoints to connect eBay seller accounts, prepare listings, and manage active listings.

Call these endpoints directly over HTTP with your Sails API key and JSON payloads.

During eBay sign-in, eBay redirects through GET /login/ebay before returning control to your app callback.

eBay OAuth Flow

Use this flow to connect a seller account and then call the eBay endpoints with the returned token.

Mermaid diagram showing the eBay OAuth and callback flow

Universal Link Callback Setup

Configure a universal link in your app (for example, https://app.yourdomain.com/login/ebay) so opening that URL routes into your app.

Send that exact callback URI in redirect_callback_schema when calling POST /api/v1/ebay/oauth/signin-url.

After eBay sign-in, we redirect back to your callback URI with the authorization code. Your app then sends that code to POST /api/v1/ebay/oauth/exchange-code to receive OAuth access and refresh tokens.

Use the returned ebay_access_token for the other eBay endpoints.

POST

/api/v1/ebay/oauth/signin-url

0 credits (free)

OAuth Sign-In URL

Create an eBay sign-in URL that starts the seller authorization flow.

Request Body

redirect_callback_schemastringREQUIRED

Callback URI for your app (recommended: a universal link).

Response Example

{
  "signin_url": "https://auth.ebay.com/oauth2/authorize?client_id=...&redirect_uri=...&response_type=code&scope=...&state=..."
}
curl -X POST https://sails.live/api/v1/ebay/oauth/signin-url \
  -H "Authorization: Bearer sails_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "redirect_callback_schema": "https://app.yourdomain.com/login/ebay"
  }'
Customise Example
POST

/api/v1/ebay/oauth/exchange-code

10 credits

OAuth Exchange Code

Exchange an eBay authorization code for access and refresh tokens.

Request Body

codestringREQUIRED

Authorization code returned by eBay after sign-in.

Response Example

{
  "ebay_access_token": "v^1.1#i^1#...",
  "ebay_access_token_expiry": "2026-03-14 10:15:00.000000",
  "ebay_refresh_token": "v^1.1#f^0#...",
  "ebay_refresh_token_expiry": "2026-09-14 10:15:00.000000"
}
curl -X POST https://sails.live/api/v1/ebay/oauth/exchange-code \
  -H "Authorization: Bearer sails_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "code": "v^1.1#i^1#p^3#..."
  }'
Customise Example
POST

/api/v1/ebay/oauth/refresh

0 credits (free)

OAuth Refresh

Refresh an eBay access token using a refresh token.

Request Body

refresh_tokenstringREQUIRED

eBay refresh token.

Response Example

{
  "ebay_access_token": "v^1.1#i^1#...",
  "ebay_access_token_expiry": "2026-03-14 12:00:00.000000"
}
curl -X POST https://sails.live/api/v1/ebay/oauth/refresh \
  -H "Authorization: Bearer sails_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "v^1.1#f^0#..."
  }'
Customise Example
POST

/api/v1/ebay/category-suggestions

0 credits (free)

Category Suggestions

Return suggested eBay categories for a search query.

Request Body

ebay_access_tokenstringREQUIRED

User eBay access token.

category_tree_idstringREQUIRED

eBay category tree id.

qstringREQUIRED

Search query text.

Response Example

{
  "categorySuggestions": []
}
curl -X POST https://sails.live/api/v1/ebay/category-suggestions \
  -H "Authorization: Bearer sails_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "ebay_access_token": "v^1.1#i^1#...",
    "category_tree_id": "0",
    "q": "vintage camera"
  }'
Customise Example
POST

/api/v1/ebay/item-aspects

0 credits (free)

Item Aspects

Return recommended item specifics (aspects) for a selected category.

Request Body

ebay_access_tokenstringREQUIRED

User eBay access token.

category_tree_idstringREQUIRED

eBay category tree id.

category_idstringREQUIRED

Chosen category id.

Response Example

{
  "aspects": []
}
curl -X POST https://sails.live/api/v1/ebay/item-aspects \
  -H "Authorization: Bearer sails_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "ebay_access_token": "v^1.1#i^1#...",
    "category_tree_id": "0",
    "category_id": "31387"
  }'
Customise Example
POST

/api/v1/ebay/get-category-features

0 credits (free)

Category Features

Return category listing constraints such as condition options and returns settings.

Request Body

ebay_access_tokenstringREQUIRED

User eBay access token.

category_idstringREQUIRED

Chosen category id.

marketplace_idstringOPTIONAL

Marketplace id such as EBAY_AU, EBAY_US, or EBAY_UK.

Response Example

{
  "conditionValues": [
    { "ID": "1000", "DisplayName": "New" }
  ],
  "domesticReturnsRequired": true
}
curl -X POST https://sails.live/api/v1/ebay/get-category-features \
  -H "Authorization: Bearer sails_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "ebay_access_token": "v^1.1#i^1#...",
    "category_id": "31387",
    "marketplace_id": "EBAY_AU"
  }'
Customise Example
POST

/api/v1/ebay/inventory-locations

0 credits (free)

Inventory Locations

Return the seller's available inventory locations.

Request Body

ebay_access_tokenstringREQUIRED

User eBay access token.

Response Example

{
  "locations": []
}
curl -X POST https://sails.live/api/v1/ebay/inventory-locations \
  -H "Authorization: Bearer sails_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "ebay_access_token": "v^1.1#i^1#..."
  }'
Customise Example
POST

/api/v1/ebay/fulfillment-policies

0 credits (free)

Fulfillment Policies

Return seller fulfillment policies for the selected marketplace.

Request Body

ebay_access_tokenstringREQUIRED

User eBay access token.

marketplace_idstringOPTIONAL

Marketplace id such as EBAY_AU, EBAY_US, or EBAY_UK.

Response Example

{
  "fulfillmentPolicies": []
}
curl -X POST https://sails.live/api/v1/ebay/fulfillment-policies \
  -H "Authorization: Bearer sails_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "ebay_access_token": "v^1.1#i^1#...",
    "marketplace_id": "EBAY_AU"
  }'
Customise Example
POST

/api/v1/ebay/get-user

0 credits (free)

Get User

Return seller profile and registration address details.

Request Body

ebay_access_tokenstringREQUIRED

User eBay access token.

marketplace_idstringOPTIONAL

Marketplace id such as EBAY_AU, EBAY_US, or EBAY_UK.

Response Example

{
  "name": "Seller Name",
  "phone": "+61...",
  "addressLine1": "1 Main St",
  "addressLine2": "",
  "city": "Sydney",
  "stateOrProvince": "NSW",
  "postalCode": "2000",
  "country": "AU"
}
curl -X POST https://sails.live/api/v1/ebay/get-user \
  -H "Authorization: Bearer sails_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "ebay_access_token": "v^1.1#i^1#...",
    "marketplace_id": "EBAY_AU"
  }'
Customise Example
POST

/api/v1/ebay/upload-picture

0 credits (free)

Upload Picture

Upload a base64-encoded image to eBay picture hosting and return the hosted URL.

Request Body

ebay_access_tokenstringREQUIRED

User eBay access token.

image_base64stringREQUIRED

Raw base64 image bytes (no data URL prefix).

marketplace_idstringOPTIONAL

Marketplace id such as EBAY_AU, EBAY_US, or EBAY_UK.

Response Example

{
  "fullUrl": "https://i.ebayimg.com/images/..."
}
curl -X POST https://sails.live/api/v1/ebay/upload-picture \
  -H "Authorization: Bearer sails_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "ebay_access_token": "v^1.1#i^1#...",
    "image_base64": "iVBORw0KGgoAAAANSUhEUgAA...",
    "marketplace_id": "EBAY_AU"
  }'
Customise Example
POST

/api/v1/ebay/post-item

0 credits (free)

Post Item

Create a new eBay listing from listing fields, or validate listing details before posting when verify mode is enabled.

Request Body

ebay_access_tokenstringREQUIRED

User eBay access token.

verifyOnlybooleanREQUIRED

When true, validates listing without posting. Must be a boolean true/false value.

titlestringREQUIRED

Listing title.

descriptionstringREQUIRED

Listing description.

categoryIdstringREQUIRED

eBay category id.

conditionIdstringOPTIONAL

eBay condition id (for example 3000 = Used). Defaults to 3000 when omitted in app-style mode.

startPricestringREQUIRED

Listing start price.

pictureUrlsarray<string>REQUIRED

Hosted image URLs. Must include at least one URL in app-style mode.

itemSpecificsobjectOPTIONAL

Optional item specifics object (for example NameValueList).

listingTypestringREQUIRED

Listing type.

domesticReturnsRequiredbooleanOPTIONAL

If true, sets ReturnsAccepted; otherwise ReturnsNotAccepted. Must be a boolean true/false value.

countryCodestringREQUIRED

Country code.

currencystringREQUIRED

Currency code.

siteNamestringREQUIRED

Site name.

shippingServicestringREQUIRED

Shipping service code.

postalCodestringREQUIRED

Origin postal code.

measurementUnitstringREQUIRED

Package measurement unit.

shippingPackagestringREQUIRED

Shipping package type.

packageDepthstringREQUIRED

Package depth.

packageLengthstringREQUIRED

Package length.

packageWidthstringREQUIRED

Package width.

WeightMajorstringREQUIRED

Major weight component.

WeightMinorstringREQUIRED

Minor weight component.

Response Example

{
  "Ack": "Success"
}
curl -X POST https://sails.live/api/v1/ebay/post-item \
  -H "Authorization: Bearer sails_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "ebay_access_token": "v^1.1#i^1#...",
    "verifyOnly": true,
    "title": "Vintage Camera",
    "description": "Working condition",
    "categoryId": "31387",
    "conditionId": "3000",
    "startPrice": "99.00",
    "pictureUrls": ["https://i.ebayimg.com/a.jpg"],
    "itemSpecifics": {"NameValueList":[{"Name":"Brand","Value":"Canon"}]},
    "listingType": "FixedPriceItem",
    "domesticReturnsRequired": false,
    "countryCode": "AU",
    "currency": "AUD",
    "siteName": "Australia",
    "shippingService": "AU_Regular",
    "postalCode": "2000",
    "measurementUnit": "English",
    "shippingPackage": "PackageThickEnvelope",
    "packageDepth": "5",
    "packageLength": "10",
    "packageWidth": "8",
    "WeightMajor": "1",
    "WeightMinor": "0"
  }'
Customise Example
POST

/api/v1/ebay/end-item

0 credits (free)

End Item

End a currently active listing by item id.

Request Body

ebay_access_tokenstringREQUIRED

User eBay access token.

item_idstringREQUIRED

eBay item id to end.

marketplace_idstringOPTIONAL

Marketplace id such as EBAY_AU, EBAY_US, or EBAY_UK.

Response Example

{
  "Ack": "Success"
}
curl -X POST https://sails.live/api/v1/ebay/end-item \
  -H "Authorization: Bearer sails_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "ebay_access_token": "v^1.1#i^1#...",
    "item_id": "123456789012",
    "marketplace_id": "EBAY_AU"
  }'
Customise Example
Previous
Listing Tools