Places

This guide explains how to work with places in the Unified Order Service (UOS) API.

What is a Place?

In the UOS system, a "place" represents a physical or virtual location associated with a channel, such as:

Stores
Warehouses
Fulfillment centers
Virtual storefronts

Places are used to organize orders and provide location-specific settings and data.

Creating a Place

To create a new place, send a POST request to the /v1/places endpoint with the place data.

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-456",
    "name": "Main Store",
    "active": true,
    "active_for_ordering": true,
    "address": {
      "line1": "123 Main St",
      "city": "Metropolis",
      "postal_code": "12345",
      "country": "US"
    }
  }'

Retrieving Places

To retrieve a list of places for a specific channel, send a GET request to the /v1/places endpoint.

curl -X GET "https://api.uos.example.com/v1/places?channel_id=channel-456" \
  -H "Authorization: Bearer YOUR_API_KEY"

Updating a Place

To update an existing place, send a PUT request to the /v1/places/{placeId} endpoint.

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 St",
      "city": "Metropolis",
      "postal_code": "12345",
      "country": "US"
    }
  }'

Managing Channel Associations

Places can be associated with multiple channels. One channel is always designated as the primary channel.

Adding a Place to a Channel

To add a place to an additional channel, send a POST request to the /v1/places/{placeId}/channels/{channelId} endpoint.

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

Removing a Place from a Channel

To remove a place from a channel, send a DELETE request to the /v1/places/{placeId}/channels/{channelId} endpoint.

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

Note: You cannot remove a place from its primary channel unless you first designate another channel as the primary channel.

Place Field Reference

Field	Type	Description
`identifier`	string	Unique identifier for the place (within channel)
`channel_id`	string	ID of the primary channel
`channel_ids`	array	Array of all channel IDs this place belongs to
`name`	string	Display name of the place
`active`	boolean	Whether the place is active
`active_for_ordering`	boolean	Whether the place can accept orders
`sales_channel`	string	Type of sales channel (e.g., "brick-and-click")
`address`	object	Physical address of the place
`coordinates`	object	Geographic coordinates (latitude, longitude)
`chain`	object	Chain information if the place belongs to a chain
`contact`	object	Contact information
`business_name`	string	Official business name
`business_id`	string	Official business identifier
`metadata`	object	Additional custom data