Adverts

Overview of the Adverts resource and associated endpoints.

  11 minute read  

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.

🧨 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"
      }
    }
  ]
}

Get a single advert

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"
      }
    }
  ]
}

Create an advert

Creating an advert is a multi-step process

Select the appropriate taxon & brand with the API only.

  1. Find the appropriate taxon and brand slugs by using the Taxon API and Brand API.
  2. 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.

  1. Submit the advert to /api/v2/client/adverts as below, using the map_taxon and map_brand attributes.
  2. 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

NameTypeDescription
titlestringRequired. A short description of the advert.
descriptionstringRequired. A longer description of the advert.
pricefloatRequired. 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).
conditionstringRequired. new or used.
taxon_slugstringRequired if published: true. The slug of the taxon/category where this advert should appear under.
brand_slugstringRequired if published: true. The slug of the brand of this advert.
specificationsstringThe specifications of the product.
genderstringIndicates the gender that would use this product. Use one of ‘female’, ‘male’, or ‘unisex’.
yearstringWhat year the product was created in.
publishedbooleanWhether or not to display the advert immediately.
sale_pricefloatDecimal 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_atstringString 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_atstringString 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_typestringAllows 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_costfloatDecimal separated with no signs or commas (i.e. 1234.56). The additional domestic shipping cost for the advert, applies to all variants.
international_shipping_costfloatDecimal separated with no signs or commas (i.e. 1234.56). The additional international shipping cost for the advert, applies to all variants.
recommended_retail_pricefloatDecimal 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_pricefloatDecimal 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_pricefloatDecimal 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_atstringString 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_atstringString 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.
featureshashIncludes 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_idstringYour system’s identifier for this advert.
map_taxonstring or array of stringsThe value/s to be mapped to the taxon. Prefer full paths.
map_brandstring or array of stringsThe value/s to be mapped to the brand.
codestringOptional - not shown to shoppers.
notesstringOptional - not shown to shoppers.
publish_streamsarray of stringsOptional - advert publication streams for marketplace and/or m_store, not shown to shoppers.
feature_option_valuesarray 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_valuesarray of objectsThe 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_taxonsarray of objectsThe 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_urlstringOptional - the URL to a YouTube video highlighting this product.
shipping_parcel_attributesobjectOptional - 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_enabledbooleanOptional - 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_quantityfloatThe maximum purchase quantity for this item
min_purchase_quantityfloatThe 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"
        }
      ]
    }
  }

or

  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"
      }
    }
  ]
}

Updating an advert

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"
      }
    }
  ]
}

Resubmit a rejected advert for vetting

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"
      }
    }
  ]
}

Deleting an advert

Use this endpoint to delete an advert.

Request

DELETE /api/v2/client/adverts/1

Response

Status: 204 No Content