Spree Commerce · Schema
Spree Store API Schemas
JSON Schema definitions extracted from Spree Store API OpenAPI 3.0 specification
E-CommerceHeadless CommerceProductsOrdersInventoryPaymentsPromotionsOpen SourceRuby on Rails
JSON Schema
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Spree Store API Schemas",
"description": "JSON Schema definitions extracted from Spree Store API OpenAPI 3.0 specification",
"definitions": {
"PaginationMeta": {
"type": "object",
"properties": {
"page": {
"type": "integer",
"example": 1
},
"limit": {
"type": "integer",
"example": 25
},
"count": {
"type": "integer",
"example": 100,
"description": "Total number of records"
},
"pages": {
"type": "integer",
"example": 4,
"description": "Total number of pages"
},
"from": {
"type": "integer",
"example": 1,
"description": "Index of first record on this page"
},
"to": {
"type": "integer",
"example": 25,
"description": "Index of last record on this page"
},
"in": {
"type": "integer",
"example": 25,
"description": "Number of records on this page"
},
"previous": {
"type": "integer",
"nullable": true,
"example": null,
"description": "Previous page number"
},
"next": {
"type": "integer",
"nullable": true,
"example": 2,
"description": "Next page number"
}
},
"required": [
"page",
"limit",
"count",
"pages",
"from",
"to",
"in"
]
},
"ErrorResponse": {
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"example": "record_not_found"
},
"message": {
"type": "string",
"example": "Record not found"
},
"details": {
"type": "object",
"description": "Field-specific validation errors",
"nullable": true,
"example": {
"name": [
"is too short",
"is required"
],
"email": [
"is invalid"
]
}
}
},
"required": [
"code",
"message"
]
}
},
"required": [
"error"
],
"example": {
"error": {
"code": "validation_error",
"message": "Validation failed",
"details": {
"name": [
"is too short"
],
"email": [
"is invalid"
]
}
}
}
},
"AuthResponse": {
"type": "object",
"properties": {
"token": {
"type": "string",
"description": "JWT access token"
},
"refresh_token": {
"type": "string",
"description": "Refresh token for obtaining new access tokens"
},
"user": {
"$ref": "#/components/schemas/Customer"
}
},
"required": [
"token",
"refresh_token",
"user"
]
},
"PermissionRule": {
"type": "object",
"description": "A single permission rule (CanCanCan rule). Rules are applied in order, last-matching-wins.",
"properties": {
"allow": {
"type": "boolean",
"description": "true for `can`, false for `cannot`"
},
"actions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Action names, e.g. [\"read\", \"update\"] or [\"manage\"]"
},
"subjects": {
"type": "array",
"items": {
"type": "string"
},
"description": "Subject class names, e.g. [\"Spree::Product\"] or [\"all\"]"
},
"has_conditions": {
"type": "boolean",
"description": "True if the server-side rule has per-record conditions. The SPA shows the action optimistically and handles 403 from the API."
}
},
"required": [
"allow",
"actions",
"subjects",
"has_conditions"
]
},
"MeResponse": {
"type": "object",
"description": "Current admin user profile and serialized permissions",
"properties": {
"user": {
"$ref": "#/components/schemas/AdminUser"
},
"permissions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PermissionRule"
}
}
},
"required": [
"user",
"permissions"
]
},
"CheckoutRequirement": {
"type": "object",
"properties": {
"step": {
"type": "string",
"description": "Checkout step this requirement belongs to",
"example": "payment"
},
"field": {
"type": "string",
"description": "Field that needs to be satisfied",
"example": "payment"
},
"message": {
"type": "string",
"description": "Human-readable requirement message",
"example": "Add a payment method"
}
},
"required": [
"step",
"field",
"message"
]
},
"CartWarning": {
"type": "object",
"description": "A warning about a cart issue (e.g., item removed due to stock change)",
"properties": {
"code": {
"type": "string",
"description": "Machine-readable warning code",
"example": "line_item_removed"
},
"message": {
"type": "string",
"description": "Human-readable warning message",
"example": "Blue T-Shirt was removed because it was sold out"
},
"line_item_id": {
"type": "string",
"nullable": true,
"description": "Prefixed line item ID (when applicable)",
"example": "li_abc123"
},
"variant_id": {
"type": "string",
"nullable": true,
"description": "Prefixed variant ID (when applicable)",
"example": "variant_abc123"
}
},
"required": [
"code",
"message"
]
},
"FulfillmentManifestItem": {
"type": "object",
"description": "An item within a fulfillment \u2014 which line item and how many units are in this fulfillment",
"properties": {
"item_id": {
"type": "string",
"description": "Line item ID",
"example": "li_abc123"
},
"variant_id": {
"type": "string",
"description": "Variant ID",
"example": "variant_abc123"
},
"quantity": {
"type": "integer",
"description": "Quantity in this fulfillment",
"example": 2
}
},
"required": [
"item_id",
"variant_id",
"quantity"
]
},
"AdminUserRoleAssignment": {
"type": "object",
"description": "A role assignment for the current store on a staff member",
"properties": {
"id": {
"type": "string",
"description": "Prefixed role ID",
"example": "role_abc123"
},
"name": {
"type": "string",
"description": "Role name",
"example": "admin"
}
},
"required": [
"id",
"name"
]
},
"PreferenceField": {
"type": "object",
"description": "A single configurable preference on a payment method, promotion rule/action, or calculator. The frontend uses `type` + `default` to render a sensible input.",
"properties": {
"key": {
"type": "string",
"example": "amount_min"
},
"type": {
"type": "string",
"example": "decimal",
"description": "string | text | password | integer | decimal | boolean | array | hash"
},
"default": {
"description": "Default value (any JSON type), null when there is no default",
"nullable": true
}
},
"required": [
"key",
"type"
]
},
"PromotionActionCalculator": {
"type": "object",
"description": "The action's nested calculator (when the action carries one \u2014 null for actions like `free_shipping`)",
"properties": {
"type": {
"type": "string",
"example": "flat_rate",
"description": "Wire shorthand for the calculator subclass"
},
"label": {
"type": "string",
"example": "Flat Rate"
},
"preferences": {
"type": "object",
"additionalProperties": true
},
"preference_schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PreferenceField"
}
}
},
"required": [
"type",
"label",
"preferences",
"preference_schema"
]
},
"PromotionActionLineItem": {
"type": "object",
"description": "One row in a `create_line_items` action \u2014 the variant added to the order and how many",
"properties": {
"variant_id": {
"type": "string",
"example": "variant_abc123"
},
"quantity": {
"type": "integer",
"example": 1
}
},
"required": [
"variant_id",
"quantity"
]
},
"Address": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"first_name": {
"type": "string",
"nullable": true
},
"last_name": {
"type": "string",
"nullable": true
},
"full_name": {
"type": "string"
},
"address1": {
"type": "string",
"nullable": true
},
"address2": {
"type": "string",
"nullable": true
},
"postal_code": {
"type": "string",
"nullable": true
},
"city": {
"type": "string",
"nullable": true
},
"phone": {
"type": "string",
"nullable": true
},
"company": {
"type": "string",
"nullable": true
},
"country_name": {
"type": "string"
},
"country_iso": {
"type": "string"
},
"state_text": {
"type": "string",
"nullable": true
},
"state_abbr": {
"type": "string",
"nullable": true
},
"quick_checkout": {
"type": "boolean"
},
"is_default_billing": {
"type": "boolean"
},
"is_default_shipping": {
"type": "boolean"
},
"state_name": {
"type": "string",
"nullable": true
}
},
"required": [
"id",
"first_name",
"last_name",
"full_name",
"address1",
"address2",
"postal_code",
"city",
"phone",
"company",
"country_name",
"country_iso",
"state_text",
"state_abbr",
"quick_checkout",
"is_default_billing",
"is_default_shipping",
"state_name"
],
"x-typelizer": true
},
"Base": {
"type": "object",
"properties": {
"id": {
"type": "string"
}
},
"required": [
"id"
],
"x-typelizer": true
},
"Cart": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"market_id": {
"type": "string",
"nullable": true
},
"number": {
"type": "string"
},
"token": {
"type": "string"
},
"email": {
"type": "string",
"nullable": true
},
"customer_note": {
"type": "string",
"nullable": true
},
"currency": {
"type": "string"
},
"locale": {
"type": "string",
"nullable": true
},
"total_quantity": {
"type": "number"
},
"item_total": {
"type": "string"
},
"display_item_total": {
"type": "string"
},
"adjustment_total": {
"type": "string"
},
"display_adjustment_total": {
"type": "string"
},
"discount_total": {
"type": "string"
},
"display_discount_total": {
"type": "string"
},
"tax_total": {
"type": "string"
},
"display_tax_total": {
"type": "string"
},
"included_tax_total": {
"type": "string"
},
"display_included_tax_total": {
"type": "string"
},
"additional_tax_total": {
"type": "string"
},
"display_additional_tax_total": {
"type": "string"
},
"total": {
"type": "string"
},
"display_total": {
"type": "string"
},
"gift_card_total": {
"type": "string"
},
"display_gift_card_total": {
"type": "string"
},
"amount_due": {
"type": "string"
},
"display_amount_due": {
"type": "string"
},
"delivery_total": {
"type": "string"
},
"display_delivery_total": {
"type": "string"
},
"warnings": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CartWarning"
}
},
"store_credit_total": {
"type": "string"
},
"display_store_credit_total": {
"type": "string"
},
"covered_by_store_credit": {
"type": "boolean"
},
"current_step": {
"type": "string"
},
"completed_steps": {
"type": "array",
"items": {
"type": "string"
}
},
"requirements": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CheckoutRequirement"
}
},
"shipping_eq_billing_address": {
"type": "boolean"
},
"discounts": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Discount"
}
},
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/LineItem"
}
},
"fulfillments": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Fulfillment"
}
},
"payments": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Payment"
}
},
"billing_address": {
"allOf": [
{
"$ref": "#/components/schemas/Address"
}
],
"nullable": true
},
"shipping_address": {
"allOf": [
{
"$ref": "#/components/schemas/Address"
}
],
"nullable": true
},
"payment_methods": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PaymentMethod"
}
},
"gift_card": {
"allOf": [
{
"$ref": "#/components/schemas/GiftCard"
}
],
"nullable": true
},
"market": {
"allOf": [
{
"$ref": "#/components/schemas/Market"
}
],
"nullable": true
}
},
"required": [
"id",
"market_id",
"number",
"token",
"email",
"customer_note",
"currency",
"locale",
"total_quantity",
"item_total",
"display_item_total",
"adjustment_total",
"display_adjustment_total",
"discount_total",
"display_discount_total",
"tax_total",
"display_tax_total",
"included_tax_total",
"display_included_tax_total",
"additional_tax_total",
"display_additional_tax_total",
"total",
"display_total",
"gift_card_total",
"display_gift_card_total",
"amount_due",
"display_amount_due",
"delivery_total",
"display_delivery_total",
"warnings",
"store_credit_total",
"display_store_credit_total",
"covered_by_store_credit",
"current_step",
"completed_steps",
"requirements",
"shipping_eq_billing_address",
"discounts",
"items",
"fulfillments",
"payments",
"billing_address",
"shipping_address",
"payment_methods",
"gift_card",
"market"
],
"x-typelizer": true
},
"Category": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"permalink": {
"type": "string"
},
"position": {
"type": "number"
},
"depth": {
"type": "number"
},
"meta_title": {
"type": "string",
"nullable": true
},
"meta_description": {
"type": "string",
"nullable": true
},
"meta_keywords": {
"type": "string",
"nullable": true
},
"children_count": {
"type": "number"
},
"parent_id": {
"type": "string",
"nullable": true
},
"description": {
"type": "string"
},
"description_html": {
"type": "string"
},
"image_url": {
"type": "string",
"nullable": true
},
"square_image_url": {
"type": "string",
"nullable": true
},
"is_root": {
"type": "boolean"
},
"is_child": {
"type": "boolean"
},
"is_leaf": {
"type": "boolean"
},
"parent": {
"$ref": "#/components/schemas/Category"
},
"children": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Category"
}
},
"ancestors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Category"
}
},
"custom_fields": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CustomField"
}
}
},
"required": [
"id",
"name",
"permalink",
"position",
"depth",
"meta_title",
"meta_description",
"meta_keywords",
"children_count",
"parent_id",
"description",
"description_html",
"image_url",
"square_image_url",
"is_root",
"is_child",
"is_leaf"
],
"x-typelizer": true
},
"Channel": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"code": {
"type": "string"
},
"active": {
"type": "boolean"
}
},
"required": [
"id",
"name",
"code",
"active"
],
"x-typelizer": true
},
"Country": {
"type": "object",
"properties": {
"iso": {
"type": "string"
},
"iso3": {
"type": "string"
},
"name": {
"type": "string"
},
"states_required": {
"type": "boolean"
},
"zipcode_required": {
"type": "boolean"
},
"states": {
"type": "array",
"items": {
"$ref": "#/components/schemas/State"
}
},
"market": {
"allOf": [
{
"$ref": "#/components/schemas/Market"
}
],
"nullable": true
}
},
"required": [
"iso",
"iso3",
"name",
"states_required",
"zipcode_required"
],
"x-typelizer": true
},
"CreditCard": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"brand": {
"type": "string"
},
"last4": {
"type": "string"
},
"month": {
"type": "number"
},
"year": {
"type": "number"
},
"name": {
"type": "string",
"nullable": true
},
"default": {
"type": "boolean"
},
"gateway_payment_profile_id": {
"type": "string",
"nullable": true
}
},
"required": [
"id",
"brand",
"last4",
"month",
"year",
"name",
"default",
"gateway_payment_profile_id"
],
"x-typelizer": true
},
"Currency": {
"type": "object",
"properties": {
"iso_code": {
"type": "string"
},
"name": {
"type": "string"
},
"symbol": {
"type": "string"
}
},
"required": [
"iso_code",
"name",
"symbol"
],
"x-typelizer": true
},
"CustomField": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"label": {
"type": "string"
},
"type": {
"type": "string",
"deprecated": true
},
"field_type": {
"type": "string",
"enum": [
"short_text",
"long_text",
"rich_text",
"number",
"boolean",
"json"
]
},
"key": {
"type": "string"
},
"value": {
"type": "object"
}
},
"required": [
"id",
"label",
"type",
"field_type",
"key",
"value"
],
"x-typelizer": true
},
"Customer": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"email": {
"type": "string"
},
"first_name": {
"type": "string",
"nullable": true
},
"last_name": {
"type": "string",
"nullable": true
},
"phone": {
"type": "string",
"nullable": true
},
"accepts_email_marketing": {
"type": "boolean"
},
"full_name": {
"type": "string"
},
"available_store_credit_total": {
"type": "string"
},
"display_available_store_credit_total": {
"type": "string"
},
"addresses": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Address"
}
},
"default_billing_address": {
"allOf": [
{
"$ref": "#/components/schemas/Address"
}
],
"nullable": true
},
"default_shipping_address": {
"allOf": [
{
"$ref": "#/components/schemas/Address"
}
],
"nullable": true
}
},
"required": [
"id",
"email",
"first_name",
"last_name",
"phone",
"accepts_email_marketing",
"full_name",
"available_store_credit_total",
"display_available_store_credit_total",
"addresses",
"default_billing_address",
"default_shipping_address"
],
"x-typelizer": true
},
"DeliveryMethod": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"code": {
"type": "string",
"nullable": true
}
},
"required": [
"id",
"name",
"code"
],
"x-typelizer": true
},
"DeliveryRate": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"delivery_method_id": {
"type": "string"
},
"name": {
"type": "string"
},
"selected": {
"type": "boolean"
},
"cost": {
"type": "string"
},
"total": {
"type": "string"
},
"additional_tax_total": {
"type": "string"
},
"included_tax_total": {
"type": "string"
},
"tax_total": {
"type": "string"
},
"display_cost": {
"type": "string"
},
"display_total": {
"type": "string"
},
"display_additional_tax_total": {
"type": "string"
},
"display_included_tax_total": {
"type": "string"
},
"display_tax_total": {
"type": "string"
},
"delivery_method": {
"$ref": "#/components/schemas/DeliveryMethod"
}
},
"required": [
"id",
"delivery_method_id",
"name",
"selected",
"cost",
"total",
"additional_tax_total",
"included_tax_total",
"tax_total",
"display_cost",
"display_total",
"display_additional_tax_total",
"display_included_tax_total",
"display_tax_total",
"delivery_method"
],
"x-typelizer": true
},
"DigitalLink": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"access_counter": {
"type": "number"
},
"filename": {
"type": "string"
},
"content_type": {
"type": "string"
},
"download_url": {
"type": "string"
},
"authorizable": {
"type": "boolean"
},
"expired": {
"type": "boolean"
},
"access_limit_exceeded": {
"type": "boolean"
}
},
"required": [
"id",
"access_counter",
"filename",
"content_type",
"download_url",
"authorizable",
"expired",
"access_limit_exceeded"
],
"x-typelizer": true
},
"Digital": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"variant_id": {
"type": "string",
"nullable": true
}
},
"required": [
"id",
"created_at",
"updated_at",
"variant_id"
],
"x-typelizer": true
},
"Discount": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"promotion_id": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": "string",
"nullable": true
},
"code": {
"type": "string",
"nullable": true
},
"amount": {
"type": "string"
},
"display_amount": {
"type": "string"
}
},
"required": [
"id",
"promotion_id",
"name",
"description",
"code",
"amount",
"display_amount"
],
"x-typelizer": true
},
"Fulfillment": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"number": {
"type": "string"
},
"tracking": {
"type": "string",
"nullable": true
},
"tracking_url": {
"type": "string",
"nullable": true
},
"cost": {
"type": "string"
},
"display_cost": {
"type": "string"
},
"total": {
"type": "string"
},
"display_total": {
"type": "string"
},
"discount_total": {
"type": "string"
},
"display_discount_total": {
"type": "string"
},
"additional_tax_total": {
"type": "string"
},
"display_additional_tax_total": {
"type": "string"
},
"included_tax_total": {
"type": "string"
},
"display_included_tax_total": {
"type": "string"
},
"tax_total": {
"type": "string"
},
"display_tax_total": {
"type": "string"
},
"status": {
"type": "string"
},
"fulfillment_type": {
"type": "string"
},
"fulfilled_at": {
"type": "string",
"nullable": true
},
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FulfillmentManifestItem"
}
},
"delivery_method": {
"$ref": "#/components/schemas/DeliveryMethod"
},
"stock_location": {
"$ref": "#/components/schemas/StockLocation"
},
"delivery_rates": {
"type": "array",
"items": {
"$ref": "#/components/schemas/DeliveryRate"
}
}
},
"required": [
"id",
"number",
"tracking",
"tracking_url",
"cost",
"display_cost",
"total",
"display_total",
"discount_total",
"display_discount_total",
"additional_tax_total",
"display_additional_tax_total",
"included_tax_total",
"display_included_tax_total",
"tax_total",
"display_tax_total",
"status",
"fulfillment_type",
"fulfilled_at",
"items",
"delivery_method",
"stock_location",
"delivery_rates"
],
"x-typelizer": true
},
"GiftCardBatch": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"codes_count": {
"type": "number"
},
"currency": {
"type": "string",
"nullable": true
},
"prefix": {
"type": "string",
"nullable": true
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"amount": {
"type": "string",
"nullable": true
},
"expires_at": {
"type": "string",
"nullable": true
},
"created_by_id": {
"type": "string",
"nullable": true
}
},
"required": [
"id",
"codes_count",
"currency",
"prefix",
"created_at",
"updated_at",
"amount",
"expires_at",
"created_by_id"
],
"x-typelizer": true
},
"GiftCard": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"code": {
"type": "string"
},
"status": {
"type": "string"
},
"currency": {
"type": "string"
},
"amount": {
"type": "string"
},
"amount_used": {
"type": "string"
},
"amount_authorized": {
"type": "string"
},
"amount_remaining": {
"type": "string"
},
"display_amount": {
"type": "string"
# --- truncated at 32 KB (67 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/spree/refs/heads/main/json-schema/spree-store-api-schemas.json