Spree Commerce Addresses API
The Addresses API from Spree Commerce — 2 operation(s) for addresses.
OpenAPI Specification
openapi: 3.0.3
info:
title: Admin Account / Address Addresses API
contact:
name: Spree Commerce
url: https://spreecommerce.org
email: hello@spreecommerce.org
description: "Spree Admin API v3 - Administrative API for managing products, orders, and store settings.\n\n## Authentication\n\nThe Admin API requires a secret API key passed in the `x-spree-api-key` header.\nSecret API keys can be generated in the Spree admin dashboard.\n\n## Response Format\n\nAll responses are JSON. List endpoints return paginated responses with `data` and `meta` keys.\nSingle resource endpoints return a flat JSON object.\n\n## Resource IDs\n\nEvery resource is identified by an opaque string ID (e.g. `prod_86Rf07xd4z`,\n`variant_k5nR8xLq`, `or_UkLWZg9DAJ`). Use these IDs everywhere — URL paths,\nrequest bodies, and Ransack filters all accept them directly.\n\n## Error Handling\n\nErrors return a consistent format:\n```json\n{\n \"error\": {\n \"code\": \"validation_error\",\n \"message\": \"Validation failed\",\n \"details\": { \"name\": [\"can't be blank\"] }\n }\n}\n```\n"
version: v3
servers:
- url: http://{defaultHost}
variables:
defaultHost:
default: localhost:3000
tags:
- name: Addresses
paths:
/api/v2/platform/addresses:
get:
summary: Return a list of Addresses
tags:
- Addresses
security:
- bearer_auth: []
description: Returns a list of Addresses
operationId: addresses-list
parameters:
- name: page
in: query
example: 1
schema:
type: integer
- name: per_page
in: query
example: 50
schema:
type: integer
- name: include
in: query
description: 'Select which associated resources you would like to fetch, see: <a href="https://jsonapi.org/format/#fetching-includes">https://jsonapi.org/format/#fetching-includes</a>'
example: user,country,state
schema:
type: string
- name: filter[user_id_eq]
in: query
description: ''
example: '1'
schema:
type: string
- name: filter[firstname_cont]
in: query
description: ''
example: John
schema:
type: string
responses:
'200':
description: Records returned
content:
application/vnd.api+json:
examples:
Example:
value:
data:
- id: '1'
type: address
attributes:
firstname: John
lastname: Doe
address1: 1 Lovely Street
address2: Northwest
city: Herndon
zipcode: '35005'
phone: 555-555-0199
state_name: null
alternative_phone: 555-555-0199
company: Company
created_at: '2022-11-08T19:33:50.821Z'
updated_at: '2022-11-08T19:33:50.821Z'
deleted_at: null
label: null
public_metadata: {}
private_metadata: {}
relationships:
country:
data:
id: '1'
type: country
state:
data:
id: '1'
type: state
user:
data: null
- id: '2'
type: address
attributes:
firstname: John
lastname: Doe
address1: 2 Lovely Street
address2: Northwest
city: Herndon
zipcode: '35005'
phone: 555-555-0199
state_name: null
alternative_phone: 555-555-0199
company: Company
created_at: '2022-11-08T19:33:50.825Z'
updated_at: '2022-11-08T19:33:50.825Z'
deleted_at: null
label: null
public_metadata: {}
private_metadata: {}
relationships:
country:
data:
id: '1'
type: country
state:
data:
id: '2'
type: state
user:
data: null
meta:
count: 2
total_count: 2
total_pages: 1
links:
self: http://www.example.com/api/v2/platform/addresses?page=1&per_page=&include=&filter[user_id_eq]=&filter[firstname_cont]=
next: http://www.example.com/api/v2/platform/addresses?filter%5Bfirstname_cont%5D=&filter%5Buser_id_eq%5D=&include=&page=1&per_page=
prev: http://www.example.com/api/v2/platform/addresses?filter%5Bfirstname_cont%5D=&filter%5Buser_id_eq%5D=&include=&page=1&per_page=
last: http://www.example.com/api/v2/platform/addresses?filter%5Bfirstname_cont%5D=&filter%5Buser_id_eq%5D=&include=&page=1&per_page=
first: http://www.example.com/api/v2/platform/addresses?filter%5Bfirstname_cont%5D=&filter%5Buser_id_eq%5D=&include=&page=1&per_page=
schema:
$ref: '#/components/schemas/resources_list'
'401':
description: Authentication Failed
content:
application/vnd.api+json:
examples:
Example:
value:
error: The access token is invalid
schema:
$ref: '#/components/schemas/error'
post:
summary: Create an Address
tags:
- Addresses
security:
- bearer_auth: []
description: Creates an Address
operationId: create-address
parameters:
- name: include
in: query
description: 'Select which associated resources you would like to fetch, see: <a href="https://jsonapi.org/format/#fetching-includes">https://jsonapi.org/format/#fetching-includes</a>'
example: user,country,state
schema:
type: string
responses:
'201':
description: Record created
content:
application/vnd.api+json:
examples:
Example:
value:
data:
id: '5'
type: address
attributes:
firstname: John
lastname: Doe
address1: 5 Lovely Street
address2: Northwest
city: Herndon
zipcode: '35005'
phone: 555-555-0199
state_name: null
alternative_phone: 555-555-0199
company: Company
created_at: '2022-11-08T19:33:51.471Z'
updated_at: '2022-11-08T19:33:51.471Z'
deleted_at: null
label: null
public_metadata: {}
private_metadata: {}
relationships:
country:
data:
id: '4'
type: country
state:
data:
id: '5'
type: state
user:
data:
id: '1'
type: user
schema:
$ref: '#/components/schemas/resource'
'422':
description: Invalid request
content:
application/vnd.api+json:
examples:
Example:
value:
error: First Name can't be blank, Last Name can't be blank, Address can't be blank, City can't be blank, Country can't be blank, Zip Code can't be blank, and Phone can't be blank
errors:
firstname:
- can't be blank
lastname:
- can't be blank
address1:
- can't be blank
city:
- can't be blank
country:
- can't be blank
zipcode:
- can't be blank
phone:
- can't be blank
schema:
$ref: '#/components/schemas/validation_errors'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/create_address_params'
/api/v2/platform/addresses/{id}:
get:
summary: Return an Address
tags:
- Addresses
security:
- bearer_auth: []
description: Returns an Address
operationId: show-address
parameters:
- name: id
in: path
required: true
schema:
type: string
- name: include
in: query
description: 'Select which associated resources you would like to fetch, see: <a href="https://jsonapi.org/format/#fetching-includes">https://jsonapi.org/format/#fetching-includes</a>'
example: user,country,state
schema:
type: string
responses:
'200':
description: Record found
content:
application/vnd.api+json:
examples:
Example:
value:
data:
id: '6'
type: address
attributes:
firstname: John
lastname: Doe
address1: 6 Lovely Street
address2: Northwest
city: Herndon
zipcode: '35005'
phone: 555-555-0199
state_name: null
alternative_phone: 555-555-0199
company: Company
created_at: '2022-11-08T19:33:51.740Z'
updated_at: '2022-11-08T19:33:51.740Z'
deleted_at: null
label: null
public_metadata: {}
private_metadata: {}
relationships:
country:
data:
id: '6'
type: country
state:
data:
id: '6'
type: state
user:
data: null
schema:
$ref: '#/components/schemas/resource'
'404':
description: Record not found
content:
application/vnd.api+json:
examples:
Example:
value:
error: The resource you were looking for could not be found.
schema:
$ref: '#/components/schemas/error'
'401':
description: Authentication Failed
content:
application/vnd.api+json:
examples:
Example:
value:
error: The access token is invalid
schema:
$ref: '#/components/schemas/error'
patch:
summary: Update an Address
tags:
- Addresses
security:
- bearer_auth: []
description: Updates an Address
operationId: update-address
parameters:
- name: id
in: path
required: true
schema:
type: string
- name: include
in: query
description: 'Select which associated resources you would like to fetch, see: <a href="https://jsonapi.org/format/#fetching-includes">https://jsonapi.org/format/#fetching-includes</a>'
example: user,country,state
schema:
type: string
responses:
'200':
description: Record updated
content:
application/vnd.api+json:
examples:
Example:
value:
data:
id: '8'
type: address
attributes:
firstname: Jack
lastname: Doe
address1: 8 Lovely Street
address2: Northwest
city: Herndon
zipcode: '35005'
phone: 555-555-0199
state_name: null
alternative_phone: 555-555-0199
company: Company
created_at: '2022-11-08T19:33:52.269Z'
updated_at: '2022-11-08T19:33:52.501Z'
deleted_at: null
label: null
public_metadata: {}
private_metadata: {}
relationships:
country:
data:
id: '9'
type: country
state:
data:
id: '8'
type: state
user:
data: null
schema:
$ref: '#/components/schemas/resource'
'422':
description: Invalid request
content:
application/vnd.api+json:
examples:
Example:
value:
error: First Name can't be blank and Last Name can't be blank
errors:
firstname:
- can't be blank
lastname:
- can't be blank
schema:
$ref: '#/components/schemas/validation_errors'
'404':
description: Record not found
content:
application/vnd.api+json:
examples:
Example:
value:
error: The resource you were looking for could not be found.
schema:
$ref: '#/components/schemas/error'
'401':
description: Authentication Failed
content:
application/vnd.api+json:
examples:
Example:
value:
error: The access token is invalid
schema:
$ref: '#/components/schemas/error'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/update_address_params'
delete:
summary: Delete an Address
tags:
- Addresses
security:
- bearer_auth: []
description: Deletes an Address
operationId: delete-address
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'204':
description: Record deleted
'404':
description: Record not found
content:
application/vnd.api+json:
examples:
Example:
value:
error: The resource you were looking for could not be found.
schema:
$ref: '#/components/schemas/error'
'401':
description: Authentication Failed
content:
application/vnd.api+json:
examples:
Example:
value:
error: The access token is invalid
schema:
$ref: '#/components/schemas/error'
components:
schemas:
resource_properties:
type: object
properties:
id:
type: string
type:
type: string
attributes:
type: object
relationships:
type: object
required:
- id
- type
- attributes
x-internal: false
error:
type: object
properties:
error:
type: string
required:
- error
x-internal: false
resources_list:
type: object
properties:
data:
type: array
items:
allOf:
- $ref: '#/components/schemas/resource_properties'
meta:
type: object
properties:
count:
type: integer
total_count:
type: integer
total_pages:
type: integer
required:
- count
- total_count
- total_pages
links:
type: object
properties:
self:
type: string
next:
type: string
prev:
type: string
last:
type: string
first:
type: string
required:
- self
- next
- prev
- last
- first
required:
- data
- meta
- links
x-internal: false
validation_errors:
type: object
properties:
error:
type: string
errors:
type: object
required:
- error
- errors
x-internal: false
create_address_params:
type: object
properties:
address:
type: object
required:
- country_id
- address1
- city
- zipcode
- phone
- firstname
- lastname
properties:
country_id:
type: string
example: '224'
state_id:
type: string
example: '516'
state_name:
type: string
example: New York
address1:
type: string
example: 5th ave
address2:
type: string
example: 1st suite
city:
type: string
example: NY
zipcode:
type: string
example: '10001'
phone:
type: string
example: +1 123 456 789
alternative_phone:
type: string
firstname:
type: string
example: John
lastname:
type: string
example: Snow
label:
type: string
example: My home address
company:
type: string
example: Vendo Connect Inc
user_id:
type: string
public_metadata:
type: object
example:
distance_from_nearest_city_in_km: 10
location_type: building
private_metadata:
type: object
example:
close_to_shop: true
required:
- address
x-internal: false
resource:
type: object
properties:
data:
$ref: '#/components/schemas/resource_properties'
required:
- data
x-internal: false
update_address_params:
type: object
properties:
address:
type: object
properties:
country_id:
type: string
example: '224'
state_id:
type: string
example: '516'
state_name:
type: string
example: New York
address1:
type: string
example: 5th ave
address2:
type: string
example: 1st suite
city:
type: string
example: NY
zipcode:
type: string
example: '10001'
phone:
type: string
example: +1 123 456 789
alternative_phone:
type: string
firstname:
type: string
example: John
lastname:
type: string
example: Snow
label:
type: string
example: My home address
company:
type: string
example: Vendo Connect Inc
user_id:
type: string
public_metadata:
type: object
example:
distance_from_city_in_km: 10
location_type: building
private_metadata:
type: object
example:
close_to_shop: true
required:
- address
x-internal: false
securitySchemes:
api_key:
type: apiKey
name: x-spree-api-key
in: header
description: Secret API key for admin access
bearer_auth:
type: http
scheme: bearer
bearerFormat: JWT
description: JWT token for admin user authentication
x-tagGroups:
- name: Authentication
tags:
- Authentication
- name: Products & Catalog
tags:
- Products
- Variants
- Option Types
- Custom Fields
- Channels
- name: Pricing
tags:
- Pricing
- Markets
- name: Orders & Fulfillment
tags:
- Orders
- Payments
- Fulfillments
- Refunds
- name: Customers
tags:
- Customers
- Customer Groups
- name: Promotions & Gift Cards
tags:
- Promotions
- Gift Cards
- name: Data
tags:
- Exports
- name: Configuration
tags:
- Settings
- Stock Locations
- Payment Methods
- Staff
- API Keys
- Allowed Origins
- Webhooks