Spree Platform API v2 - the broad REST API that backs the legacy admin and platform-level integrations. Provides full CRUD coverage of the Spree data model including addresses, taxons, classifications, line items, payments, refunds, shipments, stock items, and platform configuration. Authenticated with OAuth 2.0 bearer tokens.
---
openapi: 3.0.3
info:
title: Platform API
contact:
name: Vendo Connect Inc.
url: https://getvendo.com
email: sales@getvendo.com
description: Spree Platform API
version: v2
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:
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:
label:
public_metadata: {}
private_metadata: {}
relationships:
country:
data:
id: '1'
type: country
state:
data:
id: '1'
type: state
user:
data:
- 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:
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:
label:
public_metadata: {}
private_metadata: {}
relationships:
country:
data:
id: '1'
type: country
state:
data:
id: '2'
type: state
user:
data:
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:
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:
label:
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:
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:
label:
public_metadata: {}
private_metadata: {}
relationships:
country:
data:
id: '6'
type: country
state:
data:
id: '6'
type: state
user:
data:
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:
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:
label:
public_metadata: {}
private_metadata: {}
relationships:
country:
data:
id: '9'
type: country
state:
data:
id: '8'
type: state
user:
data:
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"
"/api/v2/platform/adjustments":
get:
summary: Return a list of Adjustments
tags:
- Adjustments
security:
- bearer_auth: []
description: Returns a list of Adjustments
operationId: adjustments-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: order,adjustable
schema:
type: string
- name: filter[order_id]
in: query
description: ''
example: '1234'
schema:
type: string
responses:
'200':
description: Records returned
content:
application/vnd.api+json:
examples:
Example:
value:
data:
- id: '1'
type: adjustment
attributes:
source_type: Spree::TaxRate
adjustable_type: Spree::Order
amount: '100.0'
label: Shipping
mandatory:
eligible: true
created_at: '2022-11-08T19:33:53.732Z'
updated_at: '2022-11-08T19:33:53.732Z'
state: open
included: false
display_amount: "$100.00"
relationships:
order:
data:
id: '1'
type: order
adjustable:
data:
id: '2'
type: order
source:
data:
id: '1'
type: tax_rate
- id: '2'
type: adjustment
attributes:
source_type: Spree::TaxRate
adjustable_type: Spree::Order
amount: '100.0'
label: Shipping
mandatory:
eligible: true
created_at: '2022-11-08T19:33:53.754Z'
updated_at: '2022-11-08T19:33:53.754Z'
state: open
included: false
display_amount: "$100.00"
relationships:
order:
data:
id: '1'
type: order
adjustable:
data:
id: '3'
type: order
source:
data:
id: '2'
type: tax_rate
meta:
count: 2
total_count: 2
total_pages: 1
links:
self: http://www.example.com/api/v2/platform/adjustments?page=1&per_page=&include=&filter[order_id]=
next: http://www.example.com/api/v2/platform/adjustments?filter%5Border_id%5D=&include=&page=1&per_page=
prev: http://www.example.com/api/v2/platform/adjustments?filter%5Border_id%5D=&include=&page=1&per_page=
last: http://www.example.com/api/v2/platform/adjustments?filter%5Border_id%5D=&include=&page=1&per_page=
first: http://www.example.com/api/v2/platform/adjustments?filter%5Border_id%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 Adjustment
tags:
- Adjustments
security:
- bearer_auth: []
description: Creates an Adjustment
operationId: create-adjustment
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: order,adjustable
schema:
type: string
responses:
'201':
description: Record created
content:
application/vnd.api+json:
examples:
Example:
value:
data:
id: '5'
type: adjustment
attributes:
source_type: Spree::TaxRate
adjustable_type: Spree::LineItem
amount: '100.0'
label: Shipping
mandatory:
eligible: true
created_at: '2022-11-08T19:33:54.527Z'
updated_at: '2022-11-08T19:33:54.527Z'
state: open
included: false
display_amount: "$100.00"
relationships:
order:
data:
id: '7'
type: order
adjustable:
data:
id: '1'
type: line_item
source:
data:
schema:
"$ref": "#/components/schemas/resource"
'422':
description: Invalid request
content:
application/vnd.api+json:
examples:
Example:
value:
error: Adjustable can't be blank, Order can't be blank, Label
can't be blank, and Amount is not a number
errors:
adjustable:
- can't be blank
order:
- can't be blank
label:
- can't be blank
amount:
- is not a number
schema:
"$ref": "#/components/schemas/validation_errors"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/create_adjustment_params"
"/api/v2/platform/adjustments/{id}":
get:
summary: Return an Adjustment
tags:
- Adjustments
security:
- bearer_auth: []
description: Returns an Adjustment
operationId: show-adjustment
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: order,adjustable
schema:
type: string
responses:
'200':
description: Record found
content:
application/vnd.api+json:
examples:
Example:
value:
data:
id: '6'
type: adjustment
attributes:
source_type: Spree::TaxRate
adjustable_type: Spree::LineItem
amount: '1.0'
label: Shipping
mandatory:
eligible: true
created_at: '2022-11-08T19:33:54.871Z'
updated_at: '2022-11-08T19:33:54.875Z'
state: open
included: false
display_amount: "$1.00"
relationships:
order:
data:
id: '8'
type: order
adjustable:
data:
id: '2'
type: line_item
source:
data:
id: '5'
type: tax_rate
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 Adjustment
tags:
- Adjustments
security:
- bearer_auth: []
description: Updates an Adjustment
operationId: update-adjustment
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: order,adjustable
schema:
type: string
responses:
'200':
description: Record updated
content:
application/vnd.api+json:
examples:
Example:
value:
data:
id: '8'
type: adjustment
attributes:
source_type: Spree::TaxRate
adjustable_type: Spree::LineItem
amount: '15.0'
label: New label
mandatory:
eligible: true
created_at: '2022-11-08T19:33:55.540Z'
updated_at: '2022-11-08T19:33:55.775Z'
state: open
included: false
display_amount: "$15.00"
relationships:
order:
data:
id: '10'
type: order
adjustable:
data:
id: '4'
type: line_item
source:
data:
id: '7'
type: tax_rate
schema:
"$ref": "#/components/schemas/resource"
'422':
description: Invalid request
content:
application/vnd.api+json:
examples:
Example:
value:
error: Label can't be blank
errors:
label:
- 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_adjustment_params"
delete:
summary: Delete an Adjustment
tags:
- Adjustments
security:
- bearer_auth: []
description: Deletes an Adjustment
operationId: delete-adjustment
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"
"/api/v2/platform/classifications":
get:
summary: Return a list of Classifications
tags:
- Classifications
security:
- bearer_auth: []
description: Returns a list of Classifications
operationId: classifications-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: product,taxon
schema:
type: string
- name: filter[taxon_id_eq]
in: query
description: ''
example: '1'
schema:
type: string
responses:
'200':
description: Records returned
content:
application/vnd.api+json:
examples:
Example:
value:
data:
- id: '1'
type: classification
attributes:
position: 1
created_at: '2022-11-08T19:33:57.238Z'
updated_at: '2022-11-08T19:33:57.238Z'
relationships:
product:
data:
id: '9'
type: product
taxon:
data:
id: '2'
type: taxon
- id: '2'
type: classification
attributes:
position: 1
created_at: '2022-11-08T19:33:57.322Z'
updated_at: '2022-11-08T19:33:57.322Z'
relationships:
product:
data:
id: '10'
type: product
taxon:
data:
id: '4'
type: taxon
meta:
count: 2
total_count: 2
total_pages: 1
links:
self: http://www.example.com/api/v2/platform/classifications?page=1&per_page=&include=&filter[taxon_id_eq]=
next: http://www.example.com/api/v2/platform/classifications?filter%5Btaxon_id_eq%5D=&include=&page=1&per_page=
prev: http://www.e
# --- truncated at 32 KB (755 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/spree-commerce/refs/heads/main/openapi/spree-commerce-platform-api-openapi.yml