Getting started with the Marketplacer API

The Marketplacer API allows developers to connect in to a Marketplacer store on sites such as BikeExchange (bikeexchange.com.au), Tinitrader (tinitrader.com.au) and House of Home (houseofhome.com.au).

This tutorial will cover the steps required to create an advert and a variant on a Bike Exchange store using the Marketplacer API.

Please note that the Marketplacer v2 API currently supports product adverts only. Future releases of the API will allow you to access other advert types such as services, events, holidays and digital downloads.

The first thing that is required to connect to the API is an API key. There are two types of API keys - a “client” API key which is associated with a particular seller on the site (e.g. Bob’s Bikes) and an “admin” API key which is associated with a site administrator.

Generating a client API key

You can get one of these by logging into your store on a Marketplacer site, then clicking “API Documentation” near the bottom of the sidebar:

API Documentation link

After you click this link, you will see the “API Access & Documentation” page.

API Documentation

Clicking “Generate API Key” on this page will generate your API key and display it to you, along with the endpoint that you must use to access the API.

API key generated

Generating an admin API key

You can get one of these by logging in to the Marketplacer admin system, then clicking “My Details & Password” in the “User Settings” menu:

My Details

Towards the bottom of the “My Details” page, you will see an “API Key” section.

API Key panel

Clicking “Generate an API Key” on this page will generate your API key and display it to you, along with the endpoint that you must use to access the API.

Admin API key generated

We’ll make our first request to the API with the API key and endpoint now.

Testing our API key

Note: The following section requires a client API key. For an example of using the admin API key, see the Email Sellers endpoint

Before we go creating new adverts, let’s make sure that our API key works first. To do that, we’ll make a call to the API to retrieve adverts for our new account. To make that request, we’ll use the endpoint and API key that we just saw, along with the curl command.

curl -H "Authorization: Bearer 471dfba..." \
  https://www.bikeexchange.com.au/api/v2/client/adverts

In the first part of this command, we’re passing an Authorization header through. This is done so that the API knows who we are. At the end of the command, we specify the URL that we would like to request. When we make this request, we’ll see this response:

{"data":[]}

Or, if your account has adverts already, you will see those adverts returned along with some links metadata. This metadata is explained further in the API documentation

Now that we have confirmed that our API key is working, let’s go about creating an advert.

Creating an advert

In this section, we’ll add a new advert to Bike Exchange. The advert will be for a Giant Cypress DX 2015 bike, which is a hybrid bike.

Before we can issue a request to the API to create an advert, we will first need to do a lookup for the relevant taxon and brand slugs. A taxon in Marketplacer can be thought of as a category for the advert. A brand, well, you probably know what that is. We cannot create an advert without linking it to both a brand and a taxon.

Note: We don’t need to do a request for both taxons and brands if we know their slugs already. For instance, if we want to create another Giant hybrid bike, then we could just make the request to create the advert without making requests for the brands and taxons again.

The taxon that we’ll be looking for is the “Hybrid Bikes” taxon. We can search for it by issuing a request like this:

curl -H "Authorization: Bearer 471dfba..." \
  https://www.bikeexchange.com.au/api/v2/taxons/search?name=Hybrid%20bik

Note: The name parameter here is URI-encoded. We’ve used a partial name here to demonstrate that the taxon search endpoint matches on the beginning of the name. You could also search less specifically by adding the autocomplete parameter. e.g.

curl -H "Authorization: Bearer 471dfba..." \
  https://www.bikeexchange.com.au/api/v2/taxons/search?name=ybri&autocomplete=1

This request will return a list of taxons that best match the search terms:

{
  "data": [
    {
      "type": "taxons",
      "id": "4",
      "attributes": {
        "name": "Hybrid Bikes",
        "tree_name": "Bikes - Hybrid Bikes",
        "slug": "hybrid-bikes"
      }
    }
  ]
}

You must select from these the taxon that best matches your product.

We must now do a similar request to get our brand; this time to /api/v2/brands/search.

curl -H "Authorization: Bearer 471dfba..." \
  https://www.bikeexchange.com.au/api/v2/brands/search?name=Giant

The response we’ll look very similar to the taxon response:

{
  "data": [
    {
      "type": "brands",
      "id": "42",
      "attributes": {
        "name": "Giant",
        "slug": "giant"
      }
    }
  ]
}

You can use the autocomplete parameter on brand search just as you can with taxon search.

Now that we know the correct brand and taxon slugs, we can create our advert. The bike that we’re selling is a Giant Cypress DX 2015; a hybrid bike. We’ll sell it for $499 and its in mint condition. With all that in mind, we can build a request to create a bike. This request will be a POST request.

curl -i \
  -H "Authorization: Bearer 471dfba..." \
  -H "Content-Type: application/vnd.api+json" \
  https://www.bikeexchange.com.au/api/v2/client/adverts -d '
{
  "data": {
    "type": "adverts",
    "attributes": {
      "title": "Giant Cypress DX",
      "description": "Smooth-rolling 700c wheels give Cypress...",
      "price": 499,
      "condition": "new",
      "taxon_slug": "hybrid-bikes",
      "brand_slug": "giant"
    }
  }
}'

One thing to note about this request is that we’re passing through a Content-Type header as well as our typical Authorization header. This Content-Type header needs to be passed through so that the Marketplacer server knows that we’re submitting a JSON blob. POST and PUT requests that do not use this header will cause Marketplacer sites to return a 415 Unsupported Media Type header, along with an error:

{
  "errors": [
    {
      "title": "Unsupported media type",
      "detail": "All requests must use the 'application/vnd.api+json' Content-Type. ...",
      "id": null,
      "href": null,
      "code": 415,
      "source": null,
      "links": null,
      "status": "unsupported_media_type"
    }
  ]
}

Because we’re specifying the correct Content-Type header, this request will suceeed:

HTTP/1.1 200 OK

Underneath, we’ll see a JSON representation of the advert that was just created:

{
  "links": {
    "self": "https://www.bikeexchange.com.au/api/v2/client/adverts/102743768-giant-giant-cypress-dx"
  },
  "data": {
    "type": "adverts",
    "id": "102743768",
    "attributes": {
      "title": "Giant Cypress DX",
      "description": "Smooth-rolling 700c wheels give Cypress...",
      "sale_type": "classified",
      "published": false,
      "code": ""
    }
  }
}

The returned information will also include taxon and brand relationships. You can see this demonstrated in the full example output, shown under the “Response” header for “Create an advert”.

Note that the published field here has a value of false. This means that the advert is not yet visible on the site. We can toggle this advert to be published by making this request:

curl -i -X PUT -H "Authorization: Bearer 471dfba..." \
  -H "Content-Type: application/vnd.api+json"
  https://www.bikeexchange.com.au/api/v2/client/adverts/102743768 \
  -d '{ "data": { "attributes": { published": true } } }'

A couple of things to note about this request:

  1. We’re using -X PUT. This changes the method of the request to be PUT rather than POST. Using a POST here will return a 404 from the server instead.
  2. We’re using the advert’s ID here: /api/v2/client/adverts/102743768. We first saw this in the response from when we created an advert.

When we make this request, we’ll see that it fails:

HTTP/1.1 422 Unprocessable Entity
...

{
  "errors": [
    {"title": "Validation error",
    "detail":" Missing variants Size must be selected",
    "id": null,
    "href": null,
    "code": 422,
    "source":"data/attributes/missing_variants",
    "status":"resource_invalid"}
  ]
}

This request is failing because the advert is missing variants. Variants in Marketplacer are used to differentiate between the different variations of an advert. In this case, bikes in the “Hybrid Bikes” taxon, must have at least one variant which indicates what size the bike is available in. Due to the fact that this advert does not have any variants at all, we cannot toggle the published field at this moment.

For more information about the adverts API, please read the Adverts API documentation.

To fix this, we’re going to need to create a variant.

Creating a variant

To create a variant in Marketplacer, we first need an advert. Thankfully, we have one of those already. The process to create a variant requires a couple of steps.

  1. Fetching the list of option types and option values.
  2. Creating the variant

Option types and option values within Marketplacer represent the ways that a variant can vary. For instance, an option type could be “Size”, where its related option values would be “Small”, “Medium” and “Large”. To get the list of option types and option values for a new variant, we can make this request:

curl -H "Authorization: Bearer 471dfba..." \
https://www.bikeexchange.com.au/api/v2/client/adverts/102743768/variants/new

This will return JSON like this:

{
  "data": [
    {
      "type": "option_types",
      "id": "2",
      "attributes": {
        "name": "Bike Size",
        "presentation": "Size"
      },
      "relationships": {
        "option_values": {
          "data": [
            {
              "type": "option_values",
              "id": "3",
              "attributes": {
                "name": "XXS",
                "presentation": "XXS"
              }
            },
            {
              "type": "option_values",
              "id": "4",
              "attributes": {
                "name": "XS",
                "presentation": "XS"
              }
            },
...

You must select an option value to use from this list. Let’s use the “XS” size here, which has an ID of 4, to create a new variant for our Giant Cypress DX advert. The request we’ll make to do that is this:

curl -i -H "Authorization: Bearer 471dfba..." \
  -H "Content-Type: application/vnd.api+json" \
  https://www.bikeexchange.com.au/api/v2/client/adverts/102743768/variants \
  -d '{
  "data": {
    "type": "variants",
    "attributes": {
      "count_on_hand": 1,
      "barcode": "9300601 123456"
    },
    "relationships": {
      "option_values": [
        { "type": "option_values", "id": 4 }
      ]
    }
  }
}
'

After this request succeeds, we’ll see our new variant:

{
  "links": {
    "self": "https://www.bikeexchange.com.au/api/v2/client/adverts/102743768-giant-giant-cypress-dx/variants/2446836"
  },
  "data": {
    "type": "variants",
    "id": "2446836",
    "attributes": {
      "sku": "",
      "barcode": "9300601 123456",
      "count_on_hand": 1
    },
    "relationships": {
      "option_values": {
        "data": {
          "type": "option_values",
          "id": 6
        }
      }
    }
  }
}

For more information about the variants API, please read the Variants API documentation.

Our advert now has a variant associated with it. This means that we will now be able to publish this advert. Let’s make that request to publish the advert again:

curl -X PUT -i -H "Authorization: Bearer 471dfba..." \
  -H "Content-Type: application/vnd.api+json" \
  https://www.bikeexchange.com.au/api/v2/client/adverts/102743768 \
  -d '{ "data": { "attributes": { published": true } } }'

This time, our request will succeed:

HTTP/1.1 200 OK
...

This means that our advert is now published and viewable on Bike Exchange! We can view this ad by logging into Bike Exchange and then clicking “My Adverts” in the sidebar.

My Adverts

If we then click “Preview” next to the ad:

Preview an advert

We’ll see that our advert now shows the information that we supplied when we created it:

Our bike

You’ll notice that it’s missing a cruicial piece: an image! Let’s upload one now.

Adding an image to an advert

Let’s assume that we already have an image for this bike handy in our current directory and the image is called bike.jpg. We can attach it to our advert by running this curl command:

curl -i -H 'Authorization: Bearer 471dfba...' \
  -F data[attributes][image]=@bike.jpg \
  https://bikeexchange.com.au/api/v2/client/adverts/102743768/images

The response we’ll get back looks like this:

HTTP/1.1 200 OK

...

{
  "data": {
    "type": "images",
    "id": "3868b196624595aa78823e667cf59c03",
    "attributes": {
      "url": "/dbimages/bike/fn_2/768/102743768/bike.jpg"
    }
  }
}

This JSON blob tells us where we can find the image that we’ve just uploaded relative to www.bikeexchange.com.au. If we went to https://www.bikeexchange.com.au/dbimages/bike/fn_2/768/102743768/bike.jpg, we would see the image that was just uploaded.

We can upload up to 20 images to adverts on Marketplacer, but for now we’ll be happy with just one. You can also upload PDF documents.

Conclusion

In this tutorial we’ve seen how we can create an advert with a variant and an image on Bike Exchange. The same actions can be taken to create adverts on other Marketplacer sites.

If you want to find out more about the API, read the rest of the documentation.