Listing Guide
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude

Here's a step-by-step guide to help you publish your item for sale using the API.

Technical-focus

This guide provides a technical overview of the steps required to publish an item for sale on the Wallapop platform using the API, along with sample API requests. For a conceptual understanding of the process at a high level, please refer to our Publish Item Flow.

The following sequence diagram demonstrates the actions performed by the API client during the item listing process:

1) Identify Item Categories

First things first—let's find the right category for your item! Start by sending a GET request to /items/categories to access Wallapop’s category hierarchy. Don’t forget to replace <YOUR_TOKEN_HERE> with your access token.

curl -i -X GET \
  https://connect.wallapop.com/items/categories \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

A successful request returns a 200 OK status with Wallapop's categories.

2) Choose a Category

The next step is to a choose a category from the list. Choose wisely! An item can only be assigned to a category if its assignable_to_item property is set to true. For example, if you’re selling a pair of women’s activewear shorts, you’ll want to select Shorts under the Activewear category.

3) Retrieve Category Attributes

Next up, find out what info Wallapop needs for your category. Send a GET request to /items/categories/{id}/attributes, swapping {id} with the relevant category ID.

curl -i -X GET \
  https://connect.wallapop.com/items/categories/12467/attributes \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

A successful request will return a 200 OK status, along with a list of attributes. Some attributes are mandatory while others are optional. If you’re selling a car, for instance, you'll need attributes like brand and model:

{
  "attributes": [
    { "type": "text", "id": "brand", "is_mandatory": true, "max_length": 75 },
    { "type": "text", "id": "model", "is_mandatory": true, "max_length": 75 },
    // other attributes...
  ]
}

Pro Tip: Mapping your Inventory

To simplify synchronization between your system and Wallapop, you can use specific attributes to store your own identifiers directly on the item:

external_id: Available for all categories. Use this field to store your internal reference code (SKU, ID, etc.).

{ "type": "text", "id": "external_id", "is_mandatory": false, "max_length": 75 }

license_plate: Specific to the Cars category. Useful for identifying unique vehicles in your fleet.

{ "type": "text", "id": "license_plate", "is_mandatory": false, "max_length": 10 }

By providing these values during creation (POST) or modification (PUT), and retrieving them via GET, you can easily maintain the relationship between your internal identifiers and Wallapop listings.

Make sure you stick with any character limits and guidelines—it's all in the details!

4) Publish Your Items

You’re ready to go! Send a POST request to the /items endpoint with all the necessary info in the request body. Don't forget the category_leaf_id, which links to your chosen category.

curl -i -X POST \
  https://connect.wallapop.com/items \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "item": {
      "category_leaf_id": "9931",
      "title": "Title example",
      "description": "A renowned line of performance and lifestyle sneakers that offer superior comfort, support, and style both on and off the court.",
      "price": {
        "cash_amount": 75.5,
        "currency": "EUR"
      },
      "attributes": {
        "external_id": "407947058",
        "brand": "Abc Design",
        "size": 34,
        "condition": "new",
        "color": "yellow"
      },
      "hashtags": [
        "awesome",
        "original"
      ],
      "delivery": {
        "allowed_by_user": true,
        "max_weight_kg": 10,
        "free_shipping": false
      }
    },
    "main_image": {
      "url": "http://cdn.portal.com/image129.jpg"
    },
    "stock": {
      "units": 0
    }
  }'

A successful request will net you a 201 Created status, plus the id of your brand-new listing.

Want to check on your item later?

Just send a GET request to /items/{id}, using the item's specific id!

Deactivating published items

To stop showing an item (like a virtual hiding act!), send a PUT request to /items/{id}/inactivate. You’ll need a Wallapop Pro subscription for this magic. Want to bring it back? Just send a request to /items/{id}/activate.

5) Adding Images

Last but definitely not least, let's make your listing pop! In the previous example, while creating an item, we specified a main_image to feature at the top. Want to add more flair? Send a POST request to /items/{id}/images, including the image url and display order—starting with 0 for your first additional image!

curl -i -X POST \
  https://connect.wallapop.com/items/xpzpvny244z3/images \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "http://cdn.portal.com/image129.jpg",
    "order": 0
  }'

When all goes well, you'll get a 201 Created status on your image upload, plus its id.

No longer like an image you uploaded?

Just send a DELETE request to /items/{itemId}/images/{imageId}, using the image's specific id!

6) Managing Item Availability

As your inventory grows, managing which items are visible to buyers becomes crucial. This is especially important for Wallapop PRO subscribers, who have specific limits on the number of active listings allowed in their plan.

Check Item Status (Active vs Inactive)

To retrieve your full inventory, send a GET request to /items. Be aware that this list returns both active (published) and inactive (hidden) items.

You must check the inactive field in the response to determine the status of each item:

Active Item: The inactive field is omitted (not present) in the JSON object. These items are visible to buyers and count towards your quota.
Inactive Item: The response includes an inactive object with "flag": true. These items are hidden.

curl -i -X GET \
  https://connect.wallapop.com/items \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

To specifically view items that are hidden or have exceeded your quota, use the dedicated endpoint GET /items/inactive. This is the most efficient way to identify items waiting to be published.

Pagination

Both endpoints support pagination for large inventories. The response includes a meta.pagination.next token. To retrieve the next page of results, simply make the same request again adding the since query parameter with that token.

Real-time Monitoring via Webhooks

Alternatively, instead of constantly polling the API to check for status changes, you can integrate Webhooks to receive real-time updates.

For instance, by subscribing to the ITEM_INACTIVATED event, your system will be notified immediately when an item is deactivated (e.g., due to subscription limits or manual actions).

When the event occurs, Wallapop will send a POST request to your configured webhook URL with the following JSON structure:

{
  "id": "5b7263ce-69cd-4344-ae4a-61d226370eb5",
  "type": "ITEM_INACTIVATED",
  "occurred_on": 1752820579294,
  "data": {
    "item_id": "9nz0m00eejon"
  }
}

Choose the Right Action

Before you simply deactivate an item to free up space, check its real-world status. Using the correct endpoint is vital for keeping your sales history accurate.

Item Status	Recommended Action	Endpoint
Sold outside Wallapop	Mark it as sold. This removes it from the marketplace but keeps it in your sales history.	`PUT /items/{id}/sold`
No longer available	If the item was lost, broken, or you simply want to delete it permanently.	`DELETE /items/{id}`
Seasonal / Rotational	If you want to hide it temporarily to free up space (e.g., hiding winter coats in summer).	`PUT /items/{id}/inactivate`

Swapping Items (Rotation)

If you have confirmed the item wasn't sold or deleted, and you simply need to rotate stock because you reached your subscription limit, follow these steps:

Deactivate an Item: Identify a published item you want to hide and call PUT /items/{id}/inactivate.
Activate an Item: Once a slot is open, choose an item from your inactive list and call PUT /items/{id}/activate.

curl -i -X PUT \
  https://connect.wallapop.com/items/xpzpvny244z3/inactivate \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Subscription Limits

The /activate endpoint requires an available slot in your Wallapop PRO subscription. If you are already at your maximum limit, you must deactivate (or mark as sold/delete) an item before activating another.

Next steps

Your listing is live! Before you get ready for a buyer to swoop in, we recommend reviewing our Items API to learn how to manage your inventory. This will help you keep your listings up-to-date.

Once you are comfortable with managing your listings, you can head on over to our Transactions Guide!

Need to view all of your items for sale?

Send a GET request to /items! If you have many items for sale, you can paginate the results instead of receiving a large list all at once.

Listing GuideCopyCopy for LLMCopy page as Markdown for LLMsView as MarkdownOpen this page as MarkdownOpen in ChatGPTGet insights from ChatGPTOpen in ClaudeGet insights from Claude