Adverts

Overview of the Adverts resource and associated endpoints.

12 minute read

IMPORTANT

Sellers building integrations into Marketplacer should only use the current GraphQL-based Seller API, and not this (REST-based) API.

All future developments, including new features will be added to the the GraphQL-based Seller API only, more details on this API can be found here

Adverts in Marketplacer represent an item, such as a bike or a chair. An advert has one or more variants which represent the different ways an advert varies. For instance, a bike may come in Black or White colors, which would mean the advert would have two variants: a White variant and a Black variant.

Note

For products to be onboarded successfully, the Enable Automatic E-Commerce for Members setting must be enabled in the seller’s account. Although this setting is enabled by default, it may be manually disabled by sellers, which will prevent advert creation. Ensure this setting is active for seamless onboarding.

🧨 Deprecations

28/06/2023:
- The include query param option_values has been deprecated in favour of advert_option_values. option_values only returns option values from multi-select option types but advert_option_values returns values from all option types.
- The relationships.feature_option_values and features.product_details input attributes have been deprecated in favour of advert_option_values.

List adverts

This endpoint will return a paginated collection of your adverts, as well as their associated brands and taxons.

Request

GET /api/v2/client/adverts

You can filter by external_id to return only adverts with that external_id.

GET /api/v2/client/adverts?external_id=VALUE

You can also filter to only return adverts whose variants have a particular value for the sku or barcode.

GET /api/v2/client/adverts?sku=VALUE

Response

Status: 200 OK

{
  "data": [
    {
      "id": 1,
      "type": "adverts",
      "attributes": {
        "title": "Giant Cypress DX",
        "description": "Smooth-rolling 700c wheels give Cypress...",
        "price": "499.0",
        "published": true,
        "sale_type": "classified",
        "sale_price": "350.0",
        "code": "ABC1234",
        "youtube_video_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
        "max_purchase_quantity": 100,
        "min_purchase_quantity": 1,
        "sale_price_start_at": "2022-03-16T12:00:00",
        "sale_price_end_at": "2022-03-20T12:00:00",
        "wholesale_promo_price_start_at": "2022-04-16T12:00:00",
        "wholesale_promo_price_end_at": "2022-04-20T12:00:00",
        "wholesale_promo_price": 20,
        "features": {
        }
      },
      "relationships": {
        "taxon": {
          "data": {
            "type": "taxons",
            "id": 1
          }
        },
        "brand": {
          "data": {
            "type": "brands",
            "id": 1
          }
        }
      }
    }
  ],
  "included": [
    {
      "id": 1,
      "type": "taxons",
      "attributes": {
        "name": "Hybrid Bikes",
        "tree_name": "Bikes - Hybrid Bikes",
        "slug": "hybrid-bikes"
      }
    },
    {
      "id": 1,
      "type": "brands",
      "attributes": {
        "name": "Giant",
        "slug": "giant"
      }
    }
  ]
}

This endpoint will return a single advert as well as its associated brands and taxons.

Request

GET /api/v2/client/adverts/1

You may also opt to include the variants, shipping dimensions, secondary taxons, option values, or catalog rule errors of this advert too:

GET /api/v2/client/adverts/1?include=variants,shipping_parcel,secondary_taxons,advert_option_values,catalog_rule_errors

Response

The response shown below contains variants, shipping dimensions, and secondary taxons, which are not included by default.

Status: 200 OK

{
  "links": {
    "self": "https://bikeexchange.com.au/api/v2/client/adverts/1"
  },
  "data": {
    "id": 1,
    "type": "adverts",
    "attributes": {
      "title": "Giant Cypress DX",
      "description": "Smooth-rolling 700c wheels give Cypress...",
      "price": "499.0",
      "published": true,
      "sale_type": "classified",
      "sale_price": "350.0",
      "code": "ABC1234",
      "youtube_video_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
      "max_purchase_quantity": 100,
      "min_purchase_quantity": 1,
      "sale_price_start_at": "2022-03-16T12:00:00",
      "sale_price_end_at": "2022-03-20T12:00:00",
      "wholesale_promo_price_start_at": "2022-04-16T12:00:00",
      "wholesale_promo_price_end_at": "2022-04-20T12:00:00",
      "wholesale_promo_price": 20,
      "features": {
      }
    },
    "catalog_rule_errors": [
      {
        "field_name": "description_plus_specifications",
        "error_message": "Description must be at least 50 characters long"
      }
    ],
    "relationships": {
      "variants": {
        "data": [
          {
            "type": "variants",
            "id": 1
          }
        ]
      },
      "taxon": {
        "data": {
          "type": "taxons",
          "id": 1
        }
      },
      "brand": {
        "data": {
          "type": "brands",
          "id": 1
        }
      },
      "shipping_parcel": {
        "data": {
          "type": "shipping_parcels",
          "id": 1
        }
      },
      "secondary_taxons": {
        "data": [
          {
            "type": "taxons",
            "id": 2
          }
        ]
      }
    }
  },
  "included": [
    {
      "id": 1,
      "type": "variants",
      "attributes": {
        "count_on_hand": 10,
        "sku": "SKU002",
        "barcode": "9300601 123457",
        "fulfilment_provider": "fulfilio",
        "price": 30.0,
        "sale_price": 15.0,
        "ean": "4003994155486",
        "upc": "9300601123456",
        "max_purchase_quantity": 100,
        "min_purchase_quantity": 1
      }
    },
    {
      "id": 1,
      "type": "taxons",
      "attributes": {
        "name": "Hybrid Bikes",
        "tree_name": "Bikes - Hybrid Bikes",
        "slug": "hybrid-bikes"
      }
    },
    {
      "id": 1,
      "type": "brands",
      "attributes": {
        "name": "Giant",
        "slug": "giant"
      }
    },
    {
      "id": 1,
      "type": "shipping_parcels",
      "attributes": {
        "weight": 5.0,
        "width": 8.3,
        "length": 98.3,
        "depth": 3.5,
        "mass_unit": "g",
        "distance_unit": "cm"
      }
    }
  ]
}

Creating an advert is a multi-step process

Select the appropriate taxon & brand with the API only.

Find the appropriate taxon and brand slugs by using the Taxon API and Brand API.
Submit the advert to /api/v2/client/adverts as below, using the taxon_slug and brand_slug attributes.

Or, select the appropriate taxon & brand using the client admin in Marketplacer.

Submit the advert to /api/v2/client/adverts as below, using the map_taxon and map_brand attributes.
In the Marketplacer client admin /client/mappings, relate these values to the corresponding Marketplacer taxon and brand.

If supplying the published attribute be sure to set it to false, otherwise you may get a validation error relating to Variant Option Values. Note: Variants, along with any required Option Values are created separately, read more about that here.

Request

POST /api/v2/client/adverts

Input

Name	Type	Description
`title`	`string`	Required. A short description of the advert.
`description`	`string`	Required. A longer description of the advert.
`price`	`float`	Required. Decimal separated with no signs or commas (i.e. 1234.56). The price of the advert, and the default price of all variants (unless `sale_price` is set).
`condition`	`string`	Required. `new` or `used`.
`taxon_slug`	`string`	Required if `published: true`. The slug of the taxon/category where this advert should appear under.
`brand_slug`	`string`	Required if `published: true`. The slug of the brand of this advert.
`specifications`	`string`	The specifications of the product.
`gender`	`string`	Indicates the gender that would use this product. Use one of ‘female’, ‘male’, or ‘unisex’.
`year`	`string`	What year the product was created in.
`published`	`boolean`	Whether or not to display the advert immediately.
`sale_price`	`float`	Decimal separated with no signs or commas (i.e. 1234.56). The discounted price of the advert, applies to all variants unless they override the price.
`sale_price_start_at`	`string`	String representation of a date in the iso8601 format yyyy-MM-ddThh:mm:ss. The start date of the sale price for the product, this field is optional and only available for use by Headless or Connected instances of Marketplacer.
`sale_price_end_at`	`string`	String representation of a date in the iso8601 format yyyy-MM-ddThh:mm:ss. The start date of the sale price for the product, this field is optional and only available for use by Headless or Connected instances of Marketplacer.
`sale_type`	`string`	Allows you to specify whether you can buy online, click and collect etc. Permitted values are: `buy_online`, `buy_online_only`, `buy_online_or_click_and_collect` (default if this value is not specified), `click_and_collect`, `classified`, `hire` and `in_store`
`domestic_shipping_cost`	`float`	Decimal separated with no signs or commas (i.e. 1234.56). The additional domestic shipping cost for the advert, applies to all variants.
`international_shipping_cost`	`float`	Decimal separated with no signs or commas (i.e. 1234.56). The additional international shipping cost for the advert, applies to all variants.
`recommended_retail_price`	`float`	Decimal separated with no signs or commas (i.e. 1234.56). The recommended retail price for the product, this field is optional and only available for use by Headless or Connected instances of Marketplacer.
`wholesale_price`	`float`	Decimal separated with no signs or commas (i.e. 1234.56). The wholesale price for the product, this field is optional and only available for use by Headless or Connected instances of Marketplacer.
`wholesale_promo_price`	`float`	Decimal separated with no signs or commas (i.e. 1234.56). The promotional wholesale price for the product, this field is optional and only available for use by Headless or Connected instances of Marketplacer.
`wholesale_promo_price_start_at`	`string`	String representation of a date in the iso8601 format yyyy-MM-ddThh:mm:ss. The start date of the promotional wholesale price for the product, this field is optional and only available for use by Headless or Connected instances of Marketplacer.
`wholesale_promo_price_end_at`	`string`	String representation of a date in the iso8601 format yyyy-MM-ddThh:mm:ss. The end date of the promotional wholesale price for the product, this field is optional and only available for use by Headless or Connected instances of Marketplacer.
`features`	`hash`	Includes two nested parameters: `product_features`, which is an array of key features that this product has, and `product_details` (🧨 DEPRECATED: Please use `advert_option_values` instead), which is a hash composed of `option_type` keys and `option_value` values. See the example request below for how these nested params are structured.
`external_id`	`string`	Your system’s identifier for this advert.
`map_taxon`	`string` or `array of strings`	The value/s to be mapped to the taxon. Prefer full paths.
`map_brand`	`string` or `array of strings`	The value/s to be mapped to the brand.
`code`	`string`	Optional - not shown to shoppers.
`notes`	`string`	Optional - not shown to shoppers.
`publish_streams`	`array of strings`	Optional - advert publication streams for `marketplace` and/or `m_store`, not shown to shoppers.
`feature_option_values`	`array of objects`	🧨 DEPRECATED: Please use `advert_option_values` instead. The id values of feature options for the product. The list of valid option values (with names) can be found using the Taxon API. Please note that this is part of the `relationships` object rather than the `attributes` object.
`advert_option_values`	`array of objects`	The option type values for the product. Free-text option type values require `option_type_id` and `text_value` and single-select and multi-select option type values require `option_type_id`. The list of valid option types and values (with names) can be found using the Taxon API. Please note that this is part of the `relationships` object rather than the `attributes` object.
`secondary_taxons`	`array of objects`	The slugs of taxons that you want to add as secondary taxons for the product. Please note that this is part of the `relationships` object rather than the `attributes` object.
`youtube_video_url`	`string`	Optional - the URL to a YouTube video highlighting this product.
`shipping_parcel_attributes`	`object`	Optional - object that contains shipping dimensions for the advert. These include `weight`, `width`, `length`, `depth`, `mass_unit`, and `distance_unit`. Valid values for `mass_unit` are ‘g’, ‘kg’, ’lb’, and ‘oz’. Valid values for `distance_unit` are ‘mm’, ‘cm’, ’m’, ‘in’, ‘ft’, and ‘yd’. This overrides the `shipping_parcel` attribute of the associated taxon if present.
`therapeutic_goods_labelling_enabled`	boolean	Optional - Determines whether you want to enable Therapeutic Goods Labeling for the advert. If enabled labeling can be added to the individual variants. If not supplied it defaults to false.
`max_purchase_quantity`	float	The maximum purchase quantity for this item
`min_purchase_quantity`	float	The minimum purchase quantity for this item

Example

  data: {
    type: "adverts",
    attributes: {
      title: "Giant Cypress DX",
      description: "Smooth-rolling 700c wheels give Cypress...",
      price: 529,
      sale_price: 399,
      domestic_shipping_cost: 9.95,
      international_shipping_cost: 39.95,
      condition: "new",
      brand_slug: "giant",
      taxon_slug: "hybrid-bikes",
      published: true,
      external_id: "ABC1234",
      code: "",
      notes: "",
      max_purchase_quantity: 100,
      min_purchase_quantity: 1,
      shipping_parcel_attributes: {
        weight: 5.3,
        width: 8.3,
        length: 8.2,
        depth: 2.9,
        mass_unit: "g",
        distance_unit: "cm"
      },
      features: {
        product_features: ["7 gears", "Ready to use"],
        product_details: { ⬅ DEPRECATED 🧨
          shape: "Rectangle",
          texture: "Crisp as an autumn morning"
        }
      }
    },
    relationships: {
      feature_option_values: [ ⬅ DEPRECATED 🧨
        {
          type: "option_values",
          id: 214
        }
      ],
      advert_option_values: [
        {
          type: "advert_option_values",
          option_value_id: 214
        },
        {
          type: "advert_option_values",
          option_value_id: 201
        },
        {
          type: "advert_option_values",
          option_type_id: 12
          text_value: "Crisp as an autumn morning"
        }
      ],
      secondary_taxons: [
        {
          type: "taxons",
          slug: "tricycles"
        }
      ]
    }
  }

  data: {
    type: "adverts",
    attributes: {
      title: "Giant Cypress DX",
      description: "Smooth-rolling 700c wheels give Cypress...",
      price: 529,
      sale_price: 399,
      domestic_shipping_cost: 9.95,
      international_shipping_cost: 39.95,
      condition: "new",
      map_brand: ["Bikes - Hybrid Bikes", "Bikes - Giant Bikes"],
      map_taxon: ["Bikes - Hybrid Bikes", "Bikes - Giant Bikes"],
      published: false,
      publish_streams: ["m_store"],
      external_id: "ABC1234",
      code: "",
      notes: ""
    }
  }

Response

Status: 200 OK

{
  "links": {
    "self": "https://bikeexchange.com.au/api/v2/client/adverts/1"
  },
  "data": {
    "id": 1,
    "type": "adverts",
    "attributes": {
      "title": "Giant Cypress DX",
      "description": "Smooth-rolling 700c wheels give Cypress...",
      "price": "499.0",
      "published": true,
      "sale_type": "classified",
      "sale_price": "350.0",
      "code": "ABC1234",
      "youtube_video_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
      "max_purchase_quantity": 100,
      "min_purchase_quantity": 1,
      "sale_price_start_at": "2022-03-16T12:00:00",
      "sale_price_end_at": "2022-03-20T12:00:00",
      "wholesale_promo_price_start_at": "2022-04-16T12:00:00",
      "wholesale_promo_price_end_at": "2022-04-20T12:00:00",
      "wholesale_promo_price": 20,
      "features": {
      }
    },
    "relationships": {
      "taxon": {
        "data": {
          "type": "taxons",
          "id": 1
        }
      },
      "brand": {
        "data": {
          "type": "brands",
          "id": 1
        }
      }
    }
  },
  "included": [
    {
      "id": 1,
      "type": "taxons",
      "attributes": {
        "name": "Hybrid Bikes",
        "tree_name": "Bikes - Hybrid Bikes",
        "slug": "hybrid-bikes"
      }
    },
    {
      "id": 1,
      "type": "brands",
      "attributes": {
        "name": "Giant",
        "slug": "giant"
      }
    }
  ]
}

Use this endpoint to update any attributes for an advert.

To clear all advert_option_values or secondary_taxons, assign an empty array. Not supplying the key for advert_option_values or secondary_taxons will leave the relevant relationship unchanged.

A request with the key below will remove all advert_option_values from the advert and leave secondary_taxons unchanged:

{
  "relationships": {
    "advert_option_values": [

    ]
  }
}

A request with the key below will remove all secondary_taxons from the advert and leave advert_option_values unchanged:

{
  "relationships": {
    "secondary_taxons": [

    ]
  }
}

A request with the field below won’t change either relationship.

{
  "relationships": {
  }
}

Request

PUT /api/v2/client/adverts/1

Example

  data: {
    attributes: {
      title: "Giant Cypress DX 2014",
      features: { product_features: ["Feature 1", "Feature 2"] }
    },
    relationships: {
      advert_option_values: []
    }
  }

Response

Status: 200 OK

{
  "links": {
    "self": "https://bikeexchange.com.au/api/v2/client/adverts/1"
  },
  "data": {
    "id": 1,
    "type": "adverts",
    "attributes": {
      "title": "Giant Cypress DX 2014",
      "description": "Smooth-rolling 700c wheels give Cypress...",
      "price": "499.0",
      "published": true,
      "sale_type": "classified",
      "sale_price": "350.0",
      "code": "ABC1234",
      "youtube_video_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
      "max_purchase_quantity": 100,
      "min_purchase_quantity": 1,
      "sale_price_start_at": "2022-03-16T12:00:00",
      "sale_price_end_at": "2022-03-20T12:00:00",
      "wholesale_promo_price_start_at": "2022-04-16T12:00:00",
      "wholesale_promo_price_end_at": "2022-04-20T12:00:00",
      "wholesale_promo_price": 20,
      "features": {
        "product_features": [
          "Feature 1",
          "Feature 2"
        ]
      }
    },
    "relationships": {
      "taxon": {
        "data": {
          "type": "taxons",
          "id": 1
        }
      },
      "brand": {
        "data": {
          "type": "brands",
          "id": 1
        }
      }
    }
  },
  "included": [
    {
      "id": 1,
      "type": "taxons",
      "attributes": {
        "name": "Hybrid Bikes",
        "tree_name": "Bikes - Hybrid Bikes",
        "slug": "hybrid-bikes"
      }
    },
    {
      "id": 1,
      "type": "brands",
      "attributes": {
        "name": "Giant",
        "slug": "giant"
      }
    }
  ]
}

Use this endpoint to resubmit a rejected advert to an operator for vetting.

Request

PUT /api/v2/client/adverts/1/resubmit_for_vetting

Response

Status: 200 OK

{
  "links": {
    "self": "https://bikeexchange.com.au/api/v2/client/adverts/1"
  },
  "data": {
    "id": 1,
    "type": "adverts",
    "attributes": {
      "title": "Giant Cypress DX 2014",
      "description": "Smooth-rolling 700c wheels give Cypress...",
      "price": "499.0",
      "published": true,
      "sale_type": "classified",
      "sale_price": "350.0",
      "code": "ABC1234",
      "youtube_video_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
      "max_purchase_quantity": 100,
      "min_purchase_quantity": 1,
      "sale_price_start_at": "2022-03-16T12:00:00",
      "sale_price_end_at": "2022-03-20T12:00:00",
      "wholesale_promo_price_start_at": "2022-04-16T12:00:00",
      "wholesale_promo_price_end_at": "2022-04-20T12:00:00",
      "wholesale_promo_price": 20,
      "features": {
        "product_features": [
          "Feature 1",
          "Feature 2"
        ]
      }
    },
    "relationships": {
      "taxon": {
        "data": {
          "type": "taxons",
          "id": 1
        }
      },
      "brand": {
        "data": {
          "type": "brands",
          "id": 1
        }
      }
    }
  },
  "included": [
    {
      "id": 1,
      "type": "taxons",
      "attributes": {
        "name": "Hybrid Bikes",
        "tree_name": "Bikes - Hybrid Bikes",
        "slug": "hybrid-bikes"
      }
    },
    {
      "id": 1,
      "type": "brands",
      "attributes": {
        "name": "Giant",
        "slug": "giant"
      }
    }
  ]
}

Use this endpoint to delete an advert.

Request

DELETE /api/v2/client/adverts/1

Response

Status: 204 No Content

Adverts

IMPORTANT

Note

🧨 Deprecations

List adverts

Request

Response

Get a single advert

Request

Response

Create an advert

Request

Input

Example

Response

Updating an advert

Request

Example

Response

Resubmit a rejected advert for vetting

Request

Response

Deleting an advert

Request

Response