Create a location

post
/locations

Create a manual location. Locations created through Commerce API are organization-level resources and are not bound to a store. A custom id can be provided, but it cannot start with the reserved prefix app-.

id
string

A custom identifier for the location. If not provided, the system will generate a UUID. Must be unique within the organization and immutable. Cannot start with the reserved prefix app-.

<= 128 characters
Example:
warehouse_1
Match pattern:
^[a-zA-Z0-9_-]+$
name
string
required

The location name.

<= 256 characters
Example:
SF Warehouse
address
AddressWithCoordinate
required

The physical address and contact information of the location. For Location resources, first_name and last_name are joined into one contact name on write; on read, the full contact name is returned as first_name and last_name is empty. The type field is accepted by the schema but not used for Location resources — omit it on write; on read it is always empty.

Example:
{"type":"business","street_1":"1234 Elm Street","street_2":"Apt 5","street_3":null,"city":"New York","state":"NY","postal_code":"10001","country_region":"USA","company":"My Company","first_name":"John","last_name":"Doe","email":"[email protected]","phone":"+13525554500","coordinate":{"latitude":43,"longitude":-75}}
type
string

The type of address.

Allowed values:
businessresidential
street_1
string
required

First line of the street address.

<= 256 characters
street_2
string or null

Second line of the street address.

<= 256 characters
street_3
string or null

Third line of the street address.

<= 256 characters
city
string

The location's city, town, or village.

<= 256 characters
state
string
required

The state or region of the location, such as a province, state, or prefecture.

<= 256 characters
postal_code
string

The postal code of the location (also known as zip code, postcode, Eircode, etc.).

<= 256 characters
country_region
string
required

The address country/region in ISO 3166-1 alpha-3 format.

Example:
USA
Match pattern:
^[A-Z]{3}$
company
string

The name of the company associated to the address.

<= 256 characters
first_name
string

The first name of the person associated to the address.

<= 256 characters
last_name
string

The last name of the person associated to the address.

<= 256 characters
email
string

The email address of the person associated to the address.

<= 256 characters
phone
string

The phone number of the person associated to the address.

<= 256 characters
coordinate
object

The coordinate of the address.

timezone_identifier
string

The name of the timezone where the location is located, as defined by the IANA timezone database standard.

<= 256 characters
Example:
America/New_York
opening_hours
OpeningHours

The regular opening hours of the location.

sunday
OpeningHourPeriod

The OpeningHourPeriod model provides detailed information about a location's operating hours for a specific day. It includes the start and end times, and indicates whether the location is open on that particular day.

Example:
{"open":true,"from":"10:30","to":"20:30"}
monday
OpeningHourPeriod

The OpeningHourPeriod model provides detailed information about a location's operating hours for a specific day. It includes the start and end times, and indicates whether the location is open on that particular day.

Example:
{"open":true,"from":"10:30","to":"20:30"}
tuesday
OpeningHourPeriod

The OpeningHourPeriod model provides detailed information about a location's operating hours for a specific day. It includes the start and end times, and indicates whether the location is open on that particular day.

Example:
{"open":true,"from":"10:30","to":"20:30"}
wednesday
OpeningHourPeriod

The OpeningHourPeriod model provides detailed information about a location's operating hours for a specific day. It includes the start and end times, and indicates whether the location is open on that particular day.

Example:
{"open":true,"from":"10:30","to":"20:30"}
thursday
OpeningHourPeriod

The OpeningHourPeriod model provides detailed information about a location's operating hours for a specific day. It includes the start and end times, and indicates whether the location is open on that particular day.

Example:
{"open":true,"from":"10:30","to":"20:30"}
friday
OpeningHourPeriod

The OpeningHourPeriod model provides detailed information about a location's operating hours for a specific day. It includes the start and end times, and indicates whether the location is open on that particular day.

Example:
{"open":true,"from":"10:30","to":"20:30"}
saturday
OpeningHourPeriod

The OpeningHourPeriod model provides detailed information about a location's operating hours for a specific day. It includes the start and end times, and indicates whether the location is open on that particular day.

Example:
{"open":true,"from":"10:30","to":"20:30"}
order_processing
object

The order processing setting for this location. When enabled is true, order_cutoff_time and order_processing_duration_days are required.

enabled
boolean

Whether order processing is enabled for this location.

Example:
true
order_cutoff_time
string

The daily cutoff time for processing orders in HH:mm format.

Example:
14:00
order_processing_duration_days
integer

The number of business days needed to process an order, from 0 to 60. Use 0 when orders are fulfilled on the same day.

>= 0<= 60
Example:
0
pickup_setting
object

The pickup setting for this location. order_processing_duration_seconds_min and order_processing_duration_seconds_max are optional even when enabled is true — leave them unset if you do not want an estimated pickup date shown to shoppers. On the branded tracking page, the date shown to shoppers currently comes from order_processing_duration_seconds_max.

enabled
boolean

Whether pickup is enabled for this location.

Example:
true
instructions
string

Pickup instructions shown to the customer.

<= 2048 characters
Example:
Please pick up at the front desk.
order_processing_duration_seconds_min
integer

The minimum number of seconds needed before the order is ready for pickup.

>= 0
Example:
3600
order_processing_duration_seconds_max
integer

The maximum number of seconds needed before the order is ready for pickup.

>= 0
Example:
7200
meta
Meta

The Meta model holds the metadata of the API response, including relevant error details for debugging purposes.Show all...

Example:
{"code":20000,"type":"OK","message":"The request was successfully processed by AfterShip."}
code
number
required

Error code in integer format. For detailed information, please refer to the Request Error introduction page.

Default:
20000
Example:
20000
type
string
required

Response type string for the reference. For detailed information, please refer to the Request Error introduction page.

>= 1 characters
Example:
OK
message
string
required

Human-readable response message. For detailed information, please refer to the Request Error introduction page.

>= 1 characters
Example:
The request was successfully processed by AfterShip.
errors
array[Error]

Error detail object. Each error object contains a "path" key and an "info" key. The "path" is the JSON path of the request object to indicate the error location. The "info" is a human-readable description of the error.Show all...

data
Location

A Location represents a warehouse, store, or other physical place used for fulfillment, order processing, and pickup settings. Location resources are scoped to the organization and are not bound to a store.

Example:
{"id":"warehouse_1","name":"SF Warehouse","source":"manual","address":{"company":"AfterShip","first_name":"John Doe","last_name":"","phone":"+14155551234","email":"[email protected]","street_1":"123 Main St","street_2":"Suite 100","street_3":"","city":"San Francisco","state":"CA","country_region":"USA","postal_code":"94105","coordinate":{"latitude":37.7749,"longitude":-122.4194}},"timezone_identifier":"America/New_York","opening_hours":{"sunday":{"open":false,"from":null,"to":null},"monday":{"open":true,"from":"09:00","to":"18:00"},"tuesday":{"open":true,"from":"09:00","to":"18:00"},"wednesday":{"open":true,"from":"09:00","to":"18:00"},"thursday":{"open":true,"from":"09:00","to":"18:00"},"friday":{"open":true,"from":"09:00","to":"18:00"},"saturday":{"open":false,"from":null,"to":null}},"order_processing":{"enabled":true,"order_cutoff_time":"14:00","order_processing_duration_days":0},"pickup_setting":{"enabled":true,"instructions":"Please pick up at the front desk.","order_processing_duration_seconds_min":3600,"order_processing_duration_seconds_max":7200},"created_at":"2026-01-01T00:00:00Z","updated_at":"2026-04-24T00:00:00Z"}
id
string
required

The unique identifier of the location. For locations created through Commerce API, this is the custom ID supplied when creating the location, or a system-generated UUID if no custom ID was provided. For ecommerce platform-sourced locations, the ID is returned in the format app-<platform>-<app_key>-<external_id>.

Example:
warehouse_1
name
string
required

The location name.

<= 256 characters
Example:
SF Warehouse
source
string
required

The source of the location. manual means the location was created through Commerce API. platform means the location was imported from an ecommerce platform.

Allowed values:
manualplatform
Example:
manual
address
AddressWithCoordinate
required

The physical address and contact information of the location. For Location resources, first_name and last_name are joined into one contact name on write; on read, the full contact name is returned as first_name and last_name is empty. The type field is accepted by the schema but not used for Location resources — omit it on write; on read it is always empty.

Example:
{"type":"business","street_1":"1234 Elm Street","street_2":"Apt 5","street_3":null,"city":"New York","state":"NY","postal_code":"10001","country_region":"USA","company":"My Company","first_name":"John","last_name":"Doe","email":"[email protected]","phone":"+13525554500","coordinate":{"latitude":43,"longitude":-75}}
timezone_identifier
string

The name of the timezone where the location is located, as defined by the IANA timezone database standard.

<= 256 characters
Example:
America/New_York
opening_hours
OpeningHours

The regular opening hours of the location.

order_processing
object

The order processing setting for this location.

pickup_setting
object

The pickup setting for this location.

created_at
string<date-time>
required

The date and time when the location was created in AfterShip, formatted in ISO 8601.

Example:
2026-01-01T00:00:00Z
updated_at
string<date-time>
required

The date and time when the location was updated in AfterShip, formatted in ISO 8601.

Example:
2026-04-24T00:00:00Z
Auth
:
Body
{ "id": "warehouse_1", "name": "SF Warehouse", "address": { "company": "AfterShip", "first_name": "John", "last_name": "Doe", "phone": "+14155551234", "email": "[email protected]", "street_1": "123 Main St", "street_2": "Suite 100", "street_3": "", "city": "San Francisco", "state": "CA", "country_region": "USA", "postal_code": "94105", "coordinate": { "latitude": 37.7749, "longitude": -122.4194 } }, "timezone_identifier": "America/New_York", "opening_hours": { "sunday": { "open": false, "from": null, "to": null }, "monday": { "open": true, "from": "09:00", "to": "18:00" }, "tuesday": { "open": true, "from": "09:00", "to": "18:00" }, "wednesday": { "open": true, "from": "09:00", "to": "18:00" }, "thursday": { "open": true, "from": "09:00", "to": "18:00" }, "friday": { "open": true, "from": "09:00", "to": "18:00" }, "saturday": { "open": false, "from": null, "to": null } }, "order_processing": { "enabled": true, "order_cutoff_time": "14:00", "order_processing_duration_days": 0 }, "pickup_setting": { "enabled": true, "instructions": "Please pick up at the front desk.", "order_processing_duration_seconds_min": 3600, "order_processing_duration_seconds_max": 7200 } }
Response Example
{ "meta": { "code": 20100, "type": "Created", "message": "The request was successful, we created a new resource and the response body contains the representation." }, "data": { "id": "warehouse_1", "name": "SF Warehouse", "source": "manual", "address": { "company": "AfterShip", "first_name": "John Doe", "last_name": "", "phone": "+14155551234", "email": "[email protected]", "street_1": "123 Main St", "street_2": "Suite 100", "street_3": "", "city": "San Francisco", "state": "CA", "country_region": "USA", "postal_code": "94105", "coordinate": { "latitude": 37.7749, "longitude": -122.4194 } }, "timezone_identifier": "America/New_York", "opening_hours": { "sunday": { "open": false, "from": null, "to": null }, "monday": { "open": true, "from": "09:00", "to": "18:00" }, "tuesday": { "open": true, "from": "09:00", "to": "18:00" }, "wednesday": { "open": true, "from": "09:00", "to": "18:00" }, "thursday": { "open": true, "from": "09:00", "to": "18:00" }, "friday": { "open": true, "from": "09:00", "to": "18:00" }, "saturday": { "open": false, "from": null, "to": null } }, "order_processing": { "enabled": true, "order_cutoff_time": "14:00", "order_processing_duration_days": 0 }, "pickup_setting": { "enabled": true, "instructions": "Please pick up at the front desk.", "order_processing_duration_seconds_min": 3600, "order_processing_duration_seconds_max": 7200 }, "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-04-24T00:00:00Z" } }