# eBay (prebuilt connector)

## Description

**eBay** is a global eCommerce platform that enables individuals and businesses to buy and sell through online auctions and fixed-price listings.

## Authentication 

When adding connector instances for eBay, the following authentication methods are supported:

* [Client credentials](#client-credentials)

### Client credentials

When a user chooses to [add a connector instance](https://doc.wearepatchworks.com/product-documentation/connectors-and-instances/working-with-instances/adding-an-instance) using `client credentials` authentication, the credentials below are prompted:

<table><thead><tr><th>Credential</th><th data-type="checkbox">Required?</th><th>Notes</th></tr></thead><tbody><tr><td><code>refresh token</code></td><td>true</td><td>See <a href="#generating-a-refresh-token">generating a refresh token</a> for details.</td></tr><tr><td><code>Client ID</code> and <code>Client secret</code></td><td>true</td><td>To obtain your <code>client id</code> and <code>client secret</code>, you need to create and configure an application in the eBay Developer Portal. For more information, please refer to Ebay's guide: <a href="https://developer.ebay.com/api-docs/static/oauth-credentials.html">Getting your OAuth credentials</a>.</td></tr><tr><td><code>Marketplace ID</code></td><td>true</td><td>For a UK marketplace, leave set to EBAY_GB. A list of valid IDs can be found in Ebay's guide: <a href="https://developer.ebay.com/api-docs/static/rest-request-components.html#marketpl">Marketplace ID values</a>.</td></tr><tr><td><code>Host</code></td><td>true</td><td><p>Refers to the domain name of the eBay API server you're calling. </p><p>For a sandbox:<br><code>sandbox.ebay.com</code><br><br>For production:<br><code>api.ebay.com</code></p></td></tr></tbody></table>

## Generating a refresh token

To obtain a `refresh token` , we use eBay's [Auth 'n' Auth flow](https://developer.ebay.com/api-docs/static/understand_auth_n_auth_tokens.html). In this way, you don't need to provide direct access to your eBay account.

{% hint style="info" %}
Refresh tokens are valid for 18 months. Remember to renew these before expiry, and then [update authentication details](https://doc.wearepatchworks.com/product-documentation/connectors-and-instances/working-with-instances/updating-an-instance) for your eBay connector instance(s)!
{% endhint %}

For this to work, you must be a user of an application that’s registered on [eBay’s Developer Program](https://developer.ebay.com/). Having registered an application (i.e. Patchworks), you receive the following details that are needed for authentication:

* App id (client id)
* Cert id (client secret)
* Redirect URI (as registered in your application settings)

With this information to hand, follow the steps [below](#the-steps) to obtain a refresh token.

### The steps

{% stepper %}
{% step %}
**Log in to eBay**

To ensure that redirects work correctly, [log in to eBay](https://signin.ebay.com/signin/) using the account to be authenticated.
{% endstep %}

{% step %}
**Grant consent**

Using a different tab *in the same browser*, give consent for the (Patchworks) application to access required data, using the following URL structure:

```
https://auth.ebay.com/oauth2/authorize?
  client_id=YOUR_CLIENT_ID&
  response_type=code&  
  scope=YOUR_SCOPES&
  redirect_uri=YOUR_REDIRECT_URI  
```

For example:

{% code overflow="wrap" %}

```
https://auth.ebay.com/oauth2/authorize?client_id=MyTestCompany-
2bc8999404-
ab6bbc86&response_type=code&scope=https%3A%2F%2Fapi.ebay.com%2Foauth%2F
api_scope%20https%3A%2F%2Fapi.ebay.com%2Foauth%2Fapi_scope%2Fsell.marke
ting.readonly%20https%3A%2F%2Fapi.ebay.com%2Foauth%2Fapi_scope%2Fsell.m
arketing%20https%3A%2F%2Fapi.ebay.com%2Foauth%2Fapi_scope%2Fsell.invent
ory.readonly%20https%3A%2F%2Fapi.ebay.com%2Foauth%2Fapi_scope%2Fsell.in
ventory%20https%3A%2F%2Fapi.ebay.com%2Foauth%2Fapi_scope%2Fsell.account
.readonly%20https%3A%2F%2Fapi.ebay.com%2Foauth%2Fapi_scope%2Fsell.accou
nt%20https%3A%2F%2Fapi.ebay.com%2Foauth%2Fapi_scope%2Fsell.fulfillment.
readonly%20https%3A%2F%2Fapi.ebay.com%2Foauth%2Fapi_scope%2Fsell.fulfil
lment%20https%3A%2F%2Fapi.ebay.com%2Foauth%2Fapi_scope%2Fsell.analytics
.readonly%20https%3A%2F%2Fapi.ebay.com%2Foauth%2Fapi_scope%2Fsell.finan
ces%20https%3A%2F%2Fapi.ebay.com%2Foauth%2Fapi_scope%2Fsell.payment.dis
pute%20https%3A%2F%2Fapi.ebay.com%2Foauth%2Fapi_scope%2Fcommerce.identi
ty.readonly%20https%3A%2F%2Fapi.ebay.com%2Foauth%2Fapi_scope%2Fcommerce
.notification.subscription%20https%3A%2F%2Fapi.ebay.com%2Foauth%2Fapi_s
cope%2Fcommerce.notification.subscription.readonly&redirect_uri=MyTestCompan-2bc899940

```

{% endcode %}
{% endstep %}

{% step %}
**Copy the returned code**

After logging in and consenting, eBay redirects you back to your redirect URI with a `code` parameter. For example:

```
/https://auth.ebay.com/oauth2/ThirdPartyAuthSucessFailure?
isAuthSuccessful=true&code=v%5A1.1%14i%5E1%12r%5E1%11I%5E3%221g%5E0%23p%
3A3%23t%5EUl51XzY5TDhCOTE5NzFBNTY1ADFBQjFBRkQGTkFMKkUwTfE0NkRfMl8xI0VeM
PYw&expires_in=299
```

Copy just the `code` value from this response, for example:

```
v%5A1.1%14i%5E1%12r%5E1%11I%5E3%221g%5E0%23p%
3A3%23t%5EUl51XzY5TDhCOTE5NzFBNTY1ADFBQjFBRkQGTkFMKkUwTfE0NkRfMl8xI0VeM
PYw
```

{% hint style="info" %}
The code value is everything between `code=` and the final `&` character.
{% endhint %}
{% endstep %}

{% step %}
**Decode the copied value**

Navigate to the following URL:

{% embed url="<https://www.urldecoder.org>" %}

Here, decode the `code` value that you copied in the previous step. For example:

{% code overflow="wrap" %}

```
vZ1.1i^1r^1I^3"1g^0#p:3#t^Ul51XzY5TDhCOTE5NzFBNTY1ADFBQjFBRkQGTkFMKkUwTfE0NkRfMl8xI0VeMPYw
```

{% endcode %}
{% endstep %}

{% step %}
**Get a refresh token**

Post a request to eBay's OAuth token endpoint, using the decoded code value. The format of this request is shown below:

```
curl --location 'https://api.ebay.com/identity/v1/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic <decoded code value>' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'redirect_uri=<your-redirect-uri>' \
--data-urlencode 'code=DECODED_AUTHORIZATION_CODE_HERE'
```

For example:

{% code overflow="wrap" %}

```
curl --location 'https://api.ebay.com/identity/v1/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic
VGhlTW90aGUtU2V0dGxlbWUtUFJELTJmZDg1OTQwNC1hYjZiYmM4NjpQUkQtZmQ4NTk0MDR
mN2M4LTRlMmEtNDNlNi05YTFkLTc4ODQ=' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'redirect_uri=MyTestCompany-
2bc8999404' \
--data-urlencode
'code=vZ1.1i^1r^1I^3"1g^0#p:3#t^Ul51XzY5TDhCOTE5NzFBNTY1ADFBQjFBRkQGTkFMKkUwTfE0NkRfMl8xI0VeMPYw'
```

{% endcode %}
{% endstep %}
{% endstepper %}