Spree Commerce Store Credits API
The Store Credits API from Spree Commerce — 2 operation(s) for store credits.
OpenAPI Specification
openapi: 3.0.3
info:
title: Admin Account / Address Store Credits 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: Store Credits
paths:
/api/v2/platform/store_credits:
get:
summary: Return a list of Store Credits
tags:
- Store Credits
security:
- bearer_auth: []
description: Returns a list of Store Credits
operationId: store-credits-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,created_by,category,credit_type
schema:
type: string
- name: filter[user_id_eq]
in: query
description: ''
example: '5'
schema:
type: string
- name: filter[created_by_id_eq]
in: query
description: ''
example: '2'
schema:
type: string
- name: filter[amount_gteq]
in: query
description: ''
example: '50.0'
schema:
type: string
- name: filter[currency_eq]
in: query
description: ''
example: USD
schema:
type: string
responses:
'200':
description: Records returned
content:
application/vnd.api+json:
examples:
Example:
value:
data:
- id: '2'
type: store_credit
attributes:
amount: '150.0'
amount_used: '0.0'
memo: null
deleted_at: null
currency: USD
amount_authorized: '0.0'
originator_type: null
created_at: '2022-11-08T19:35:38.714Z'
updated_at: '2022-11-08T19:35:38.714Z'
public_metadata: {}
private_metadata: {}
display_amount: $150.00
display_amount_used: $0.00
relationships:
user:
data:
id: '107'
type: user
created_by:
data:
id: '108'
type: user
store_credit_category:
data:
id: '14'
type: store_credit_category
store_credit_type:
data:
id: '14'
type: store_credit_type
store_credit_events:
data:
- id: '3'
type: store_credit_event
- id: '3'
type: store_credit
attributes:
amount: '150.0'
amount_used: '0.0'
memo: null
deleted_at: null
currency: USD
amount_authorized: '0.0'
originator_type: null
created_at: '2022-11-08T19:35:38.722Z'
updated_at: '2022-11-08T19:35:38.722Z'
public_metadata: {}
private_metadata: {}
display_amount: $150.00
display_amount_used: $0.00
relationships:
user:
data:
id: '107'
type: user
created_by:
data:
id: '109'
type: user
store_credit_category:
data:
id: '15'
type: store_credit_category
store_credit_type:
data:
id: '15'
type: store_credit_type
store_credit_events:
data:
- id: '4'
type: store_credit_event
meta:
count: 2
total_count: 2
total_pages: 1
links:
self: http://www.example.com/api/v2/platform/store_credits?page=1&per_page=&include=&filter[user_id_eq]=&filter[created_by_id_eq]=&filter[amount_gteq]=&filter[currency_eq]=
next: http://www.example.com/api/v2/platform/store_credits?filter%5Bamount_gteq%5D=&filter%5Bcreated_by_id_eq%5D=&filter%5Bcurrency_eq%5D=&filter%5Buser_id_eq%5D=&include=&page=1&per_page=
prev: http://www.example.com/api/v2/platform/store_credits?filter%5Bamount_gteq%5D=&filter%5Bcreated_by_id_eq%5D=&filter%5Bcurrency_eq%5D=&filter%5Buser_id_eq%5D=&include=&page=1&per_page=
last: http://www.example.com/api/v2/platform/store_credits?filter%5Bamount_gteq%5D=&filter%5Bcreated_by_id_eq%5D=&filter%5Bcurrency_eq%5D=&filter%5Buser_id_eq%5D=&include=&page=1&per_page=
first: http://www.example.com/api/v2/platform/store_credits?filter%5Bamount_gteq%5D=&filter%5Bcreated_by_id_eq%5D=&filter%5Bcurrency_eq%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 a Store Credit
tags:
- Store Credits
security:
- bearer_auth: []
description: Creates a Store Credit
operationId: create-store-credit
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,created_by,category,credit_type
schema:
type: string
responses:
'201':
description: Record created
content:
application/vnd.api+json:
examples:
Example:
value:
data:
id: '6'
type: store_credit
attributes:
amount: '150.0'
amount_used: '0.0'
memo: null
deleted_at: null
currency: USD
amount_authorized: '0.0'
originator_type: null
created_at: '2022-11-08T19:35:39.272Z'
updated_at: '2022-11-08T19:35:39.272Z'
public_metadata: {}
private_metadata: {}
display_amount: $150.00
display_amount_used: $0.00
relationships:
user:
data:
id: '113'
type: user
created_by:
data:
id: '114'
type: user
store_credit_category:
data:
id: '18'
type: store_credit_category
store_credit_type:
data:
id: '18'
type: store_credit_type
store_credit_events:
data:
- id: '7'
type: store_credit_event
schema:
$ref: '#/components/schemas/resource'
'422':
description: Invalid request
content:
application/vnd.api+json:
examples:
Example:
value:
error: User can't be blank, Category can't be blank, Created by can't be blank, Currency can't be blank, Amount must be greater than 0, Amount used Cannot be greater than amount., and Amount authorized Exceeds total credits.
errors:
user:
- can't be blank
category:
- can't be blank
created_by:
- can't be blank
currency:
- can't be blank
amount:
- must be greater than 0
amount_used:
- Cannot be greater than amount.
amount_authorized:
- Exceeds total credits.
schema:
$ref: '#/components/schemas/validation_errors'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/create_store_credit_params'
/api/v2/platform/store_credits/{id}:
get:
summary: Return a Store Credit
tags:
- Store Credits
security:
- bearer_auth: []
description: Returns a Store Credit
operationId: show-store-credit
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,created_by,category,credit_type
schema:
type: string
responses:
'200':
description: Record found
content:
application/vnd.api+json:
examples:
Example:
value:
data:
id: '7'
type: store_credit
attributes:
amount: '150.0'
amount_used: '0.0'
memo: null
deleted_at: null
currency: USD
amount_authorized: '0.0'
originator_type: null
created_at: '2022-11-08T19:35:39.554Z'
updated_at: '2022-11-08T19:35:39.554Z'
public_metadata: {}
private_metadata: {}
display_amount: $150.00
display_amount_used: $0.00
relationships:
user:
data:
id: '115'
type: user
created_by:
data:
id: '116'
type: user
store_credit_category:
data:
id: '19'
type: store_credit_category
store_credit_type:
data:
id: '20'
type: store_credit_type
store_credit_events:
data:
- id: '8'
type: store_credit_event
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 a Store Credit
tags:
- Store Credits
security:
- bearer_auth: []
description: Updates a Store Credit
operationId: update-store-credit
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,created_by,category,credit_type
schema:
type: string
responses:
'200':
description: Record updated
content:
application/vnd.api+json:
examples:
Example:
value:
data:
id: '9'
type: store_credit
attributes:
amount: '500.0'
amount_used: '0.0'
memo: The user is awarded
deleted_at: null
currency: CAD
amount_authorized: '0.0'
originator_type: null
created_at: '2022-11-08T19:35:40.170Z'
updated_at: '2022-11-08T19:35:40.405Z'
public_metadata:
loyalty_reward: true
private_metadata: {}
display_amount: $500.00
display_amount_used: $0.00
relationships:
user:
data:
id: '119'
type: user
created_by:
data:
id: '120'
type: user
store_credit_category:
data:
id: '21'
type: store_credit_category
store_credit_type:
data:
id: '22'
type: store_credit_type
store_credit_events:
data:
- id: '10'
type: store_credit_event
schema:
$ref: '#/components/schemas/resource'
'422':
description: Invalid request
content:
application/vnd.api+json:
examples:
Example:
value:
error: Amount must be greater than 0, Amount used Cannot be greater than amount., and Amount authorized Exceeds total credits.
errors:
amount:
- must be greater than 0
amount_used:
- Cannot be greater than amount.
amount_authorized:
- Exceeds total credits.
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_store_credit_params'
delete:
summary: Delete a Store Credit
tags:
- Store Credits
security:
- bearer_auth: []
description: Deletes a Store Credit
operationId: delete-store-credit
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
update_store_credit_params:
type: object
properties:
store_credit:
type: object
required:
- user_id
- category_id
- type_id
- created_by_id
- currency
- store_id
- amount
properties:
user_id:
type: string
example: '2'
category_id:
type: string
example: '4'
created_by_id:
type: string
example: '5'
amount:
type: number
example: 25.0
amount_used:
type: number
example: 10.0
memo:
type: string
example: This credit was given as a refund
currency:
type: string
example: USD
amount_authorized:
type: number
example: 15.5
originator_id:
type: string
example: '3'
originator_type:
type: string
example: Refund
type_id:
type: string
example: '1'
store_id:
type: string
example: '2'
public_metadata:
type: object
private_metadata:
type: object
required:
- store_credit
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
resource:
type: object
properties:
data:
$ref: '#/components/schemas/resource_properties'
required:
- data
x-internal: false
create_store_credit_params:
type: object
properties:
store_credit:
type: object
required:
- user_id
- category_id
- type_id
- created_by_id
- currency
- store_id
- amount
properties:
user_id:
type: string
example: '2'
category_id:
type: string
example: '4'
created_by_id:
type: string
example: '5'
amount:
type: number
example: 25.0
amount_used:
type: number
example: 10.0
memo:
type: string
example: This credit was given as a refund
currency:
type: string
example: USD
amount_authorized:
type: number
example: 15.5
originator_id:
type: string
example: '3'
originator_type:
type: string
example: Refund
type_id:
type: string
example: '1'
store_id:
type: string
example: '2'
public_metadata:
type: object
private_metadata:
type: object
required:
- store_credit
x-internal: false
validation_errors:
type: object
properties:
error:
type: string
errors:
type: object
required:
- error
- errors
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