Places API Reference

This page documents the Places endpoints in the Core API.

List Places

Returns a paginated list of places for a specific channel.

URL: /v1/places

Method: GET

Auth required: Yes

Parameters:

Parameter	Type	Required	Description
`channel_id`	string	Yes	Filter places by channel ID
`limit`	integer	No	Number of items per page (default: 10)
`offset`	integer	No	Offset for pagination (default: 0)

Example Request:

curl -X GET "https://api.uos.example.com/v1/places?channel_id=channel-123&limit=10&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY"

Success Response:

Code: 200 OK
Content:

{
  "data": [
    {
      "id": "place-123",
      "identifier": "store-123",
      "channel_id": "channel-123",
      "name": "Main Store",
      "active": true,
      "active_for_ordering": true,
      "address": {
        "line1": "123 Main St",
        "city": "Metropolis",
        "postal_code": "12345",
        "country": "US"
      },
      "created_at": "2023-06-01T10:00:00Z",
      "updated_at": "2023-06-01T10:00:00Z"
    },
    {
      "id": "place-456",
      "identifier": "store-456",
      "channel_id": "channel-123",
      "name": "Downtown Store",
      "active": true,
      "active_for_ordering": true,
      "address": {
        "line1": "456 Market St",
        "city": "Metropolis",
        "postal_code": "12345",
        "country": "US"
      },
      "created_at": "2023-06-01T11:00:00Z",
      "updated_at": "2023-06-01T11:00:00Z"
    }
  ],
  "pagination": {
    "total": 2,
    "limit": 10,
    "offset": 0
  }
}

Error Responses:

Code: 400 Bad Request
- Content: { "error": "Missing required channel_id parameter" }
Code: 403 Forbidden
- Content: { "error": "No access to the specified channel" }

Get Place by ID

Returns detailed information about a specific place.

URL: /v1/places/{placeId}

Method: GET

Auth required: Yes

Example Request:

curl -X GET "https://api.uos.example.com/v1/places/place-123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Success Response:

Code: 200 OK
Content:

{
  "id": "place-123",
  "identifier": "store-123",
  "channel_id": "channel-123",
  "channel_specific_identifiers": ["store-123-amazon", "store-123-alt"],
  "name": "Main Store",
  "active": true,
  "active_for_ordering": true,
  "sales_channel": "brick-and-click",
  "address": {
    "line1": "123 Main Street",
    "building": "Building A",
    "postal_code": "12345",
    "postal_area": "Downtown",
    "town": "Smallville",
    "city": "Metropolis",
    "state": "NY",
    "country": "US"
  },
  "coordinates": {
    "latitude": 40.7128,
    "longitude": -74.0060
  },
  "chain": {
    "id": "chain-123",
    "name": "Sample Chain",
    "logo_url": "https://example.com/chain-logo.jpg",
    "type": "grocery"
  },
  "contact": {
    "email": "support@example.com",
    "phone": "+1-555-123-4568",
    "website": "https://example.com"
  },
  "pickup_locations": [
    {
      "id": 1001,
      "name": "Main Entrance",
      "address": "123 Main Street, Metropolis",
      "street": "123 Main Street",
      "city": "Metropolis",
      "zip": "12345",
      "country": "US",
      "store_guid": "store-123"
    }
  ],
  "phones": [
    {
      "number": "+1-555-123-4567",
      "type": "main"
    }
  ],
  "images": [
    {
      "url": "https://example.com/store-image.jpg",
      "type": "storefront"
    }
  ],
  "business_name": "Sample Business LLC",
  "business_id": "B12345",
  "vat_number": "VAT12345",
  "delivery_options": [
    {
      "id": "delivery-standard",
      "name": "Standard Delivery",
      "price": 4.99
    }
  ],
  "payment_methods": [
    {
      "id": "payment-card",
      "name": "Credit Card",
      "type": "card"
    }
  ],
  "metadata": {},
  "created_at": "2023-06-01T10:00:00Z",
  "updated_at": "2023-06-01T10:00:00Z",
  "channel_ids": ["channel-123"]
}

Error Responses:

Code: 403 Forbidden
- Content: { "error": "No access to the specified channel" }
Code: 404 Not Found
- Content: { "error": "Place not found" }

Create Place

Creates a new place associated with a channel.

URL: /v1/places

Method: POST

Auth required: Yes

Request Body:

Field	Type	Required	Description
`identifier`	string	Yes	Unique identifier for the place (per channel)
`channel_id`	string	Yes	Channel ID the place belongs to
`name`	string	No	Name of the place
`active`	boolean	No	Whether the place is active
`active_for_ordering`	boolean	No	Whether the place can accept orders
`address`	object	No	Address details
`coordinates`	object	No	Geographic coordinates
`metadata`	object	No	Additional metadata
`additional_channel_ids`	array	No	Additional channel IDs

Example Request:

curl -X POST "https://api.uos.example.com/v1/places" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "store-123",
    "channel_id": "channel-123",
    "name": "Main Store",
    "active": true,
    "active_for_ordering": true,
    "sales_channel": "brick-and-click",
    "address": {
      "line1": "123 Main Street",
      "city": "Metropolis",
      "postal_code": "12345",
      "country": "US"
    },
    "coordinates": {
      "latitude": 40.7128,
      "longitude": -74.0060
    },
    "metadata": {
      "opening_hours": "9AM-9PM"
    }
  }'

Success Response:

Code: 201 Created
Content:

{
  "id": "place-123",
  "identifier": "store-123",
  "channel_id": "channel-123",
  "name": "Main Store",
  "active": true,
  "active_for_ordering": true,
  "sales_channel": "brick-and-click",
  "address": {
    "line1": "123 Main Street",
    "city": "Metropolis",
    "postal_code": "12345",
    "country": "US"
  },
  "coordinates": {
    "latitude": 40.7128,
    "longitude": -74.0060
  },
  "metadata": {
    "opening_hours": "9AM-9PM"
  },
  "created_at": "2023-06-01T10:00:00Z",
  "updated_at": "2023-06-01T10:00:00Z",
  "channel_ids": ["channel-123"]
}

Error Responses:

Code: 400 Bad Request
- Content: { "error": "Missing required fields" }
Code: 403 Forbidden
- Content: { "error": "No access to the specified channel" }

Update Place

Updates an existing place with new data.

URL: /v1/places/{placeId}

Method: PUT

Auth required: Yes

Request Body: Same as for creating a place, but identifier is required.

Example Request:

curl -X PUT "https://api.uos.example.com/v1/places/place-123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "store-123",
    "name": "Main Store - Updated",
    "active": true,
    "active_for_ordering": true,
    "address": {
      "line1": "123 Main Street",
      "city": "Metropolis",
      "postal_code": "12345",
      "country": "US"
    }
  }'

Success Response:

Code: 200 OK
Content:

{
  "id": "place-123",
  "identifier": "store-123",
  "channel_id": "channel-123",
  "name": "Main Store - Updated",
  "active": true,
  "active_for_ordering": true,
  "address": {
    "line1": "123 Main Street",
    "city": "Metropolis",
    "postal_code": "12345",
    "country": "US"
  },
  "created_at": "2023-06-01T10:00:00Z",
  "updated_at": "2023-06-01T12:00:00Z",
  "channel_ids": ["channel-123"]
}

Error Responses:

Code: 400 Bad Request
- Content: { "error": "Missing required fields" }
Code: 403 Forbidden
- Content: { "error": "No access to the specified channel" }
Code: 404 Not Found
- Content: { "error": "Place not found" }

Partially Update Place

Updates specific fields of a place.

URL: /v1/places/{placeId}

Method: PATCH

Auth required: Yes

Request Body: Only include fields that need to be updated.

Example Request:

curl -X PATCH "https://api.uos.example.com/v1/places/place-123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "active_for_ordering": false,
    "metadata": {
      "temporarily_closed": true,
      "reopening_date": "2023-07-01"
    }
  }'

Success Response:

Code: 200 OK
Content:

{
  "id": "place-123",
  "identifier": "store-123",
  "channel_id": "channel-123",
  "name": "Main Store - Updated",
  "active": true,
  "active_for_ordering": false,
  "address": {
    "line1": "123 Main Street",
    "city": "Metropolis",
    "postal_code": "12345",
    "country": "US"
  },
  "metadata": {
    "temporarily_closed": true,
    "reopening_date": "2023-07-01"
  },
  "created_at": "2023-06-01T10:00:00Z",
  "updated_at": "2023-06-01T13:00:00Z",
  "channel_ids": ["channel-123"]
}

Error Responses:

Code: 403 Forbidden
- Content: { "error": "No access to the specified channel" }
Code: 404 Not Found
- Content: { "error": "Place not found" }

Add Place to Channel

Adds a place to an additional channel. Optionally set it as the primary channel.

URL: /v1/places/{placeId}/channels/{channelId}

Method: POST

Auth required: Yes

Request Body:

Field	Type	Required	Description
`is_primary`	boolean	No	Whether this channel should be set as the primary channel for the place (default: false)

Example Request:

curl -X POST "https://api.uos.example.com/v1/places/place-123/channels/channel-456" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "is_primary": false
  }'

Success Response:

Code: 200 OK
Content:

{
  "id": "place-123",
  "identifier": "store-123",
  "channel_id": "channel-123",
  "name": "Main Store - Updated",
  "active": true,
  "active_for_ordering": false,
  "created_at": "2023-06-01T10:00:00Z",
  "updated_at": "2023-06-01T14:00:00Z",
  "channel_ids": ["channel-123", "channel-456"]
}

Error Responses:

Code: 403 Forbidden
- Content: { "error": "No access to the specified channel" }
Code: 404 Not Found
- Content: { "error": "Place not found" }

Remove Place from Channel

Removes a place from a specific channel. Cannot remove the primary channel unless another channel is set as primary first.

URL: /v1/places/{placeId}/channels/{channelId}

Method: DELETE

Auth required: Yes

Example Request:

curl -X DELETE "https://api.uos.example.com/v1/places/place-123/channels/channel-456" \
  -H "Authorization: Bearer YOUR_API_KEY"

Success Response:

Code: 200 OK
Content:

{
  "id": "place-123",
  "identifier": "store-123",
  "channel_id": "channel-123",
  "name": "Main Store - Updated",
  "active": true,
  "active_for_ordering": false,
  "created_at": "2023-06-01T10:00:00Z",
  "updated_at": "2023-06-01T15:00:00Z",
  "channel_ids": ["channel-123"]
}

Error Responses:

Code: 400 Bad Request
- Content: { "error": "Cannot remove primary channel. Set another channel as primary first." }
Code: 403 Forbidden
- Content: { "error": "No access to the specified channel" }
Code: 404 Not Found
- Content: { "error": "Place not found" }