Locations API
Copper provides an API for all major CRUD operations related to Locations.
Create a Location
POST /locations
Creates a new Location resource. Only merchant accounts are able to create locations.
Parameters
Many - but not all - properties of Location resources are accepted as parameters to this API. The display_name
and at least the address.country properties are required, whereas the phone, website, metadata and address
fields other than address.country are optional.
| Parameter | Type | Required? | Description |
|---|---|---|---|
display_name |
string | Required | The display name of the Location. |
address[country] |
string | Required | Two-letter country code (ISO 3166-1 alpha2) that the Location exists in. |
phone |
string | Optional | The Location phone number. |
website |
string | Optional | The Location website. |
address[line1] |
string | Optional | Address line 1 (e.g., street, PO Box, or company name). |
address[line2] |
string | Optional | Address line 2 (e.g., apartment, suite, unit, or building). |
address[city] |
string | Optional | City, district, suburb, town, or village. |
address[postal_code] |
string | Optional | ZIP or postal code. |
address[state] |
string | Optional | State, county, province, or region. |
metadata |
object | Optional | Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata. |
Returns
A Location resource if object creation was successful.
Example
curl https://api.usecopper.com/next/locations \
-u sk_test_XXXXXXXXXXXXXXXXXXXXXXXXXX: \
-d "address[city]"=Reno \
-d "address[country]"=US \
-d "address[line1]"="10753 Harbottle Drive" \
-d "address[postal_code]"=89511 \
-d "address[state]"=NV \
-d display_name="Copper Damonte Ranch" \
-d phone="+1 (415) 395-6398"
Retrieve a Location
GET /locations/{id}
Retrieves an existing Location resource.
Parameters
This API method only accepts a single parameter, the id, via the URL path.
Returns
An Location resource if a valid id was provided.
Example
curl https://api.usecopper.com/next/locations/someid \
-u sk_test_XXXXXXXXXXXXXXXXXXXXXXXXXX:
Update a Location
POST /locations/{id}
Updates an existing Location resource.
Parameters
Location properties that can be updated include address, display_name, phone, website and metadata. To unset any of these parameters, post an empty value for them. Any ommitted parameters will be left unchanged.
| Parameter | Type | Description |
|---|---|---|
display_name |
string | The display name of the Location. |
phone |
string | The Location phone number. |
website |
string | The Location website. |
address[country] |
string | Two-letter country code (ISO 3166-1 alpha2) that the Location exists in. |
address[line1] |
string | Address line 1 (e.g., street, PO Box, or company name). |
address[line2] |
string | Address line 2 (e.g., apartment, suite, unit, or building). |
address[city] |
string | City, district, suburb, town, or village. |
address[postal_code] |
string | ZIP or postal code. |
address[state] |
string | State, county, province, or region. |
metadata |
object | Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata. |
Returns
The updated Location resource if object update was successful.
Example
curl https://api.usecopper.com/next/locations/someid \
-u sk_test_XXXXXXXXXXXXXXXXXXXXXXXXXX: \
-d "address[city]"="Las Vegas"
List Locations
GET /locations
Returns one or more Location resources.
Parameters
This API accepts pagination parameters.
Returns
An object containing the matching locatiions, if any. The response data format is described in more detail in the pagination list response format documentation.
Example
curl https://api.usecopper.com/next/locations \
-u sk_test_XXXXXXXXXXXXXXXXXXXXXXXXXX: \
-d limit=3 \
-G
Delete a Location
DELETE /locations/{id}
Deletes an existing Location resource.
☢️ This API is currently disabled - it will abort and return an HTTP 501 status code.