How can I create and manage listings using a product feed?

By publishing listings on Ricardo, you agree to our Terms & Conditions (GTC) and accept our Privacy Policy.

A selling fee applies for every successfully sold item.

Ricardo is required to collect VAT for sales to buyers in Switzerland and Liechtenstein and remit it to the Swiss Federal Tax Administration (ESTV) on behalf of sellers. Ricardo may also be required to share the following data upon request:

• Your name, mailing address, email address, and website
• Sales generated via Ricardo
• The types of goods offered

Ricardo shoppers prefer unique items, collectibles, design classics, and bargains – and they value sustainability. If an item is passed on and reused, it reduces the need for new production, transportation, and disposal, preserving resources and reducing emissions.

You’ll have the most success if you offer products such as:

• Secondhand
• Previous season's stock
• Refurbished
• Display models
• Handmade
• Overstock
• Collectibles
• Spare parts
• Products with expiry dates
• Damaged or production-defect items

Inventory that doesn't fall into these categories – e.g., mass-produced new goods or dropshipping products – may lead to rejection or limitation of your listing limit.

All feed-imported listings are managed under a single Ricardo account.

The default listing limit is 100 active listings. Higher limits may be granted based on:

• Inventory aligns with the categories listed under Inventory Guidelines
• At least 10% of inventory sells each month (e.g. 1,000 orders for 10,000 listings)

The inventory is synchronized with Ricardo via a publicly accessible product feed over HTTPS in a specific JSON format (see Feed Content & Format). The URL must be static.

You should update the feed immediately when there are changes to stock levels, product removals, or price adjustments. Otherwise, a daily update is sufficient.

For efficient processing, we require that the HTTP response which serves the feed includes an ETag in the HTTP response header. If your feed is served from Channable, the ETag header is included by default. The ETag allows us to detect changes in the feed in a resource-efficient way, without needing to download and process the entire content each time. The ETag header must be present in both GET and HEAD responses.

We reserve the right to remove items that have not sold within 90 days of initial publication.

The following settings are not passed per product in the feed, but are configured per user account. Please specify your chosen configuration for the following in your integration request:

• Delivery: Shipping only / Pickup only / Shipping and pickup

• For shipping: Specify the shipping method and price (e.g. Package B-Post 2kg, CHF 8.50)

  Check our web settings form for available shipping methods and allowable shipping cost ranges.

• For shipping: Set the threshold for free shipping (at what item price the shipping costs will be set to CHF 0.-)

The individual products in the feed are defined and described using the following information:

• product_id (string): Each product must have a unique and permanent ID that appears only once in the entire inventory and does not change.
  • For order creation to work correctly, the product_id values you provide in the feed must exactly match the variant_ids in your Shopify store. If there is a mismatch, we won’t be able to create the orders in Shopify.
• gtin (optional, string): A valid and unique number according to GTIN Standards.
• title (string):
  • Max. 60 characters
  • Readable and starting with capital letters
  • Contains the most important features
  • Identical or very similar across variants
  • Supported languages: DE, FR or IT
  • No internal codes, IDs or price information
• description (string):
  • Max. 5,000 characters
  • Plain text only (no HTML); line breaks with \\n
  • Structured and readable, normal capitalisation
  • Similar across variants
  • Present your product objectively but in a friendly manner
  • Detailed information about condition, special features, and characteristics
  • Mention any defects or signs of wear
  • State the original selling price
  • Supported languages: DE, FR or IT
  • No contact information or URLs
• images (list of strings):
  • 1 to 10 image URLs
  • Format: JPG or PNG, min. 700px resolution
  • Maximum 5MB per image
  • Image changes are only detected if the URL also changes
  • No stock photos
  • No watermarks, QR codes, logos, or contact details
• price (integer, in cents):
  • Currency: CHF
  • Must end in 0 or 5 (e.g., 1995)
  • Including VAT, excluding shipping costs
  • Allowed range: CHF 1.00 to CHF 1,000,000
• stock (integer):
  • Number of items you want to offer for sale on Ricardo.
  • If you offer the same item on multiple platforms, you can intentionally specify a lower stock level in the feed than actually available to minimize the risk of overselling. However, since the inventory on Ricardo is updated with some delay, there remains a residual risk.
  • Allowed range: 1-99
• specification:
  • product_type (string):
    • Product classification according to your own taxonomy – is mapped to Ricardo taxonomy (e.g., Jacket / veste / giacca da sci is mapped to Jacket)
    • Product is rejected if no valid mapping is possible.
    • Use the web form to check valid product types.
    • Supported languages: DE, FR or IT. English terms are mapped less reliably
  • category (optional, string):
    • Higher-level classification/grouping according to your own taxonomy, used to better map the product to Ricardo's taxonomy (e.g., Clothing / Women's Fashion / Clothes & Accessories / Pants.
    • Supported languages: DE, FR or IT. English terms are mapped less reliably
  • attributes (list of attributes as name/value pairs):
    • List of attributes and their values to characterize the product (e.g., Color: blue)
    • Names according to your own taxonomy, are mapped to Ricardo taxonomy
    • Non-mappable attributes are ignored
    • Required attributes must be included and mappable – otherwise the product is rejected
    • See web form for mandatory attributes per product type
    • Date formats according to RFC 3339
    • Decimal numbers in valid format allowed
    • Supported languages: DE, FR or IT. English terms are mapped less reliably
    • No duplicate attributes: Each attribute may only appear once and must have exactly one value.
• condition (string):
  • Indicates the general condition of a product.
  • Use the description for additional details.
  • One of these values: new, like_new, used, damaged
• variant (optional object): Used to group products that are essentially the same but differ in some specific attributes (e.g., the same shoe in different sizes or colors). All products in a variant group must have a very similar or identical title, similar description, and the same condition. Each variant (i.e., each product in the group) must have a different combination of attribute values.
  • group (string): Unique identifier for the variant group. All products with the same group value belong to the same product group.
  • image (string): A specific image for the respective variant (e.g., red version of the shoe).
  • options (list of attributes as name/value pairs): Defines what makes a variant different within a group (typical: size, color, material). These attributes must also be present in the product's specification.attributes.

Consult our help pages for more tips on how to best describe your article.

The product feed must contain a JSON array of product objects.

[{Product},
{Product},
{Product},
...
{Product}]

{
  "product_id": "12345678900",
  "gtin": "77665544332211",
  "title": "My product title",
  "description": "My product description.",
  "images": [
    "https://my.cdn.com/image1.jpg",
    "https://my.cdn.com/image2.jpg",
    "https://my.cdn.com/image3.jpg"
  ],
  "price": "12300",
  "stock": "20",
  "specification: {
    "category": "Product category",
    "product_type": "Product type",
    "attributes": [
      {
        "name": "Color",
        "value": [
          "Red"
        ]
      },
      {
        "name": "Size",
        "value": [
          "M"
        ]
      },
      {
        "name": "My attribute name",
        "value": [
          "My first attribute value",
          "My second attribute value"
          ]
      }
    ]
  },
  "condition": "used",
  "variant": {
    "group": "999888777",
    "image": "https://my.cdn.com/image1.jpg",
    "options": [
      {
        "name": "Color",
        "value": "Red"
      },
      {
        "name": "Size",
        "value": "M"
      }
    ]
  }
}

{
  "product_id": "1",
  "gtin": "1000000",
  "title": "Cool T-Shirt",
  "description": "Comfortable cotton t-shirt, available in multiple colors and sizes.",
  "images": [
    "https://my.cdn.com/image-red-m1.jpg",
    "https://my.cdn.com/image-red-m2.jpg",
    "https://my.cdn.com/image-red-m3.jpg"
  ],
  "price": "12300",
  "stock": "20",
  "specification: {
    "category": "Apparel",
    "product_type": "T-Shirt",
    "attributes": [
      {
        "name": "Color",
        "value": ["Red"]
      },{
        "name": "Size",
        "value": ["M"]
      },{
        "name": "Brand",
        "value": ["Nike"]
      },{
        "name": "Fit",
        "value": ["oversized"]
      }
  },
  "condition": "new",
  "variant": {
    "group": "TSHIRT_GROUP_001",
    "image": "https://my.cdn.com/image-red-m1.jpg",
    "options": [
      {
        "name": "Color",
        "value": "Red"
      },{
        "name": "Size",
        "value": "M"
      }
    ]
  }
},{
  "product_id": "2",
  "gtin": "200000",
  "title": "Cool T-Shirt",
  "description": "Comfortable cotton t-shirt, available in multiple colors and sizes.",
  "images": [
    "https://my.cdn.com/image-blue-m1.jpg",
    "https://my.cdn.com/image-blue-m2.jpg",
    "https://my.cdn.com/image-blue-m3.jpg"
  ],
  "price": "12300",
  "stock": "20",
  "specification: {
    "category": "Apparel",
    "product_type": "T-Shirt",
    "attributes": [
      {
        "name": "Color",
        "value": ["Blue"]
      },{
        "name": "Size",
        "value": ["M"]
      },{
        "name": "Brand",
        "value": ["Nike"]
      },{
        "name": "Fit",
        "value": ["oversized"]
      }
  },
  "condition": "new",
  "variant": {
    "group": "TSHIRT_GROUP_001",
    "image": "https://my.cdn.com/image-blue-m1.jpg",
    "options": [
      {
        "name": "Color",
        "value": "Blue"
      },{
        "name": "Size",
        "value": "M"
      }
    ]
},{
  "product_id": "3",
  "gtin": "3000000",
  "title": "Cool T-Shirt",
  "description": "Comfortable cotton t-shirt, available in multiple colors and sizes.",
  "images": [
    "https://my.cdn.com/image-red-s1.jpg",
    "https://my.cdn.com/image-red-s2.jpg",
    "https://my.cdn.com/image-red-s3.jpg"
  ],
  "price": "12300",
  "stock": "20",
  "specification: {
    "category": "Apparel",
    "product_type": "T-Shirt",
    "attributes": [
      {
        "name": "Color",
        "value": ["Red"]
      },{
        "name": "Size",
        "value": ["S"]
      },{
        "name": "Brand",
        "value": ["Nike"]
      },{
        "name": "Fit",
        "value": ["oversized"]
      }
  },
  "condition": "new",
  "variant": {
    "group": "TSHIRT_GROUP_001",
    "image": "https://my.cdn.com/image-red-s1.jpg",
    "options": [
      {
        "name": "Color",
        "value": "Red"
      },{
        "name": "Size",
        "value": "S"
      }
    ]
}

{
      [{
    "product_id": "11111111",
    "gtin": "25345345345345",
    "title": "Jacke Damen",
    "description": "Beschreibung Jacke Damen",
    "images": [
        "https://cdn.wherever.com/image1.jpg",
        "https://cdn.wherever.com/image2.jpg"
    ],
    "price": "2990",
    "stock": "3",
    "attributes": {
        "color": [
            "Pink"
        ],
        "size": [
            "36"
        ],
        "gender": [
            "Damen"
        ],
        "age": [
            "Erwachsen"
        ],
        "model": [
            "Carol-W"
        ],
        "brand": [
            "Adidas"
        ]
    },
    "category": "Skijacken",
    "product_type": "Jacken",
    "condition": "new",
    "variant": {
        "option_color": [
            "Pink"
        ],
        "group": [
            "879878976789897"
        ],
        "option_size": [
            "36"
        ],
        "image": [
            "https://cdn.wherever.com/image1.jpg"
        ]
    }
}]

Currently, we only support the feed formats listed above. Other formats can be evaluated upon request — please contact us at accountmanagement@ricardo.ch.