> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ethioreview.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Provision shops and products

> Upsert vendor shops and catalog products with external IDs from your marketplace.

Use your marketplace secret (`sk_test_*` or `sk_live_*`) with scope `marketplace:shops`. Create credentials from **Integrations → Digital platform** (or **Integrations → API keys** with marketplace scopes).

## Who this is for

Backend engineers syncing vendor storefronts and SKUs into EthioReview.

## Upsert a shop

```http theme={null}
PUT /api/v1/partner/platform/shops
Authorization: Bearer sk_test_YOUR_SECRET
Content-Type: application/json
```

```json theme={null}
{
  "externalShopId": "vendor_42",
  "name": "Bole Coffee House",
  "description": "Specialty coffee in Addis Ababa",
  "externalShopUrl": "https://marketplace.example.com/shops/vendor_42",
  "city": "Addis Ababa",
  "products": [
    {
      "externalProductId": "sku_1001",
      "name": "Yirgacheffe 250g",
      "productKind": "PHYSICAL"
    }
  ]
}
```

The call is **idempotent** on `(marketplace, externalShopId)`. Updates refresh name and metadata without creating a duplicate EthioReview account.

## Response highlights

* `organizationProfile.id` / `slug` — EthioReview shop account
* `urls.claim` — link for the vendor owner to claim the listing
* `widget.embedSnippet` — shop-level widget markup
* `products[]` — catalog items that are independent review targets

## Upsert a product later

```http theme={null}
PUT /api/v1/partner/platform/shops/vendor_42/products
Authorization: Bearer sk_test_YOUR_SECRET
Content-Type: application/json
```

```json theme={null}
{
  "externalProductId": "sku_1002",
  "name": "Sidamo 500g",
  "productKind": "PHYSICAL"
}
```

## List shops

```http theme={null}
GET /api/v1/partner/platform/shops
Authorization: Bearer sk_test_YOUR_SECRET
```

## Claim flow

Shops start as **unclaimed**. Send the vendor the claim URL from the upsert response. After claim, the shop keeps its EthioReview reviews and parent link to your marketplace.

## One failure mode

**Reusing the same `externalShopId` across two marketplaces** — IDs are scoped per marketplace organization. Collisions only happen inside your own platform; use stable vendor IDs from your database.

## Next

[Display reviews →](/integrations/digital-platform/display-reviews.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.