Spree Commerce · Schema
Spree Admin API Schemas
JSON Schema definitions extracted from Spree Admin API OpenAPI 3.0 specification
E-CommerceHeadless CommerceProductsOrdersInventoryPaymentsPromotionsOpen SourceRuby on Rails
JSON Schema
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Spree Admin API Schemas",
"description": "JSON Schema definitions extracted from Spree Admin 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"
},
"user": {
"$ref": "#/components/schemas/AdminUser"
}
},
"required": [
"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
},
"label": {
"type": "string",
"nullable": true
},
"metadata": {
"type": "object"
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"customer_id": {
"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",
"label",
"metadata",
"created_at",
"updated_at",
"customer_id"
],
"x-typelizer": true
},
"Adjustment": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"label": {
"type": "string"
},
"display_amount": {
"type": "string"
},
"included": {
"type": "boolean"
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"amount": {
"type": "string"
},
"order_id": {
"type": "string",
"nullable": true
}
},
"required": [
"id",
"label",
"display_amount",
"included",
"created_at",
"updated_at",
"amount",
"order_id"
],
"x-typelizer": true
},
"AdminUser": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"email": {
"type": "string"
},
"first_name": {
"type": "string",
"nullable": true
},
"last_name": {
"type": "string",
"nullable": true
},
"full_name": {
"type": "string",
"nullable": true
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"roles": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AdminUserRoleAssignment"
}
}
},
"required": [
"id",
"email",
"first_name",
"last_name",
"full_name",
"created_at",
"updated_at",
"roles"
],
"x-typelizer": true
},
"AllowedOrigin": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"origin": {
"type": "string"
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
}
},
"required": [
"id",
"origin",
"created_at",
"updated_at"
],
"x-typelizer": true
},
"ApiKey": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"key_type": {
"type": "string"
},
"token_prefix": {
"type": "string",
"nullable": true
},
"scopes": {
"type": "array",
"items": {
"type": "string"
}
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"revoked_at": {
"type": "string",
"nullable": true
},
"last_used_at": {
"type": "string",
"nullable": true
},
"plaintext_token": {
"type": "string",
"nullable": true
},
"created_by_email": {
"type": "string",
"nullable": true
}
},
"required": [
"id",
"name",
"key_type",
"token_prefix",
"scopes",
"created_at",
"updated_at",
"revoked_at",
"last_used_at",
"plaintext_token",
"created_by_email"
],
"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"
}
},
"metadata": {
"type": "object"
},
"pretty_name": {
"type": "string"
},
"lft": {
"type": "number"
},
"rgt": {
"type": "number"
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
}
},
"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",
"metadata",
"pretty_name",
"lft",
"rgt",
"created_at",
"updated_at"
],
"x-typelizer": true
},
"Channel": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"code": {
"type": "string"
},
"active": {
"type": "boolean"
},
"default": {
"type": "boolean"
},
"preferred_order_routing_strategy": {
"type": "string",
"nullable": true
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
}
},
"required": [
"id",
"name",
"code",
"active",
"default",
"preferred_order_routing_strategy",
"created_at",
"updated_at"
],
"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
},
"created_at": {
"type": "object"
},
"updated_at": {
"type": "object"
}
},
"required": [
"iso",
"iso3",
"name",
"states_required",
"zipcode_required",
"created_at",
"updated_at"
],
"x-typelizer": true
},
"CouponCode": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"code": {
"type": "string"
},
"state": {
"type": "string",
"nullable": true
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"promotion_id": {
"type": "string"
},
"order_id": {
"type": "string",
"nullable": true
}
},
"required": [
"id",
"code",
"state",
"created_at",
"updated_at",
"promotion_id",
"order_id"
],
"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
},
"customer_id": {
"type": "string",
"nullable": true
},
"payment_method_id": {
"type": "string",
"nullable": true
},
"metadata": {
"type": "object"
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
}
},
"required": [
"id",
"brand",
"last4",
"month",
"year",
"name",
"default",
"gateway_payment_profile_id",
"customer_id",
"payment_method_id",
"metadata",
"created_at",
"updated_at"
],
"x-typelizer": true
},
"CustomFieldDefinition": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"namespace": {
"type": "string"
},
"key": {
"type": "string"
},
"label": {
"type": "string"
},
"field_type": {
"type": "string",
"enum": [
"short_text",
"long_text",
"rich_text",
"number",
"boolean",
"json"
]
},
"resource_type": {
"type": "string"
},
"storefront_visible": {
"type": "boolean"
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
}
},
"required": [
"id",
"namespace",
"key",
"label",
"field_type",
"resource_type",
"storefront_visible",
"created_at",
"updated_at"
],
"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"
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"storefront_visible": {
"type": "boolean"
},
"custom_field_definition_id": {
"type": "string"
}
},
"required": [
"id",
"label",
"type",
"field_type",
"key",
"value",
"created_at",
"updated_at",
"storefront_visible",
"custom_field_definition_id"
],
"x-typelizer": true
},
"CustomerGroup": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": "string",
"nullable": true
},
"customers_count": {
"type": "number"
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"customers": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Customer"
}
}
},
"required": [
"id",
"name",
"description",
"customers_count",
"created_at",
"updated_at"
],
"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
},
"login": {
"type": "string",
"nullable": true
},
"metadata": {
"type": "object"
},
"last_sign_in_at": {
"type": "string",
"nullable": true
},
"current_sign_in_at": {
"type": "string",
"nullable": true
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"sign_in_count": {
"type": "number"
},
"failed_attempts": {
"type": "number"
},
"last_sign_in_ip": {
"type": "string",
"nullable": true
},
"current_sign_in_ip": {
"type": "string",
"nullable": true
},
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"internal_note_html": {
"type": "string",
"nullable": true
},
"default_billing_address_id": {
"type": "string",
"nullable": true
},
"default_shipping_address_id": {
"type": "string",
"nullable": true
},
"orders_count": {
"type": "number"
},
"total_spent": {
"type": "string"
},
"display_total_spent": {
"type": "string"
},
"last_order_completed_at": {
"type": "string",
"nullable": true
},
"orders": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Order"
}
},
"store_credits": {
"type": "array",
"items": {
"$ref": "#/components/schemas/StoreCredit"
}
},
"customer_groups": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CustomerGroup"
}
}
},
"required": [
"id",
"email",
"first_name",
"last_name",
"phone",
"accepts_email_marketing",
"full_name",
"available_store_credit_total",
"display_available_store_credit_total",
"login",
"metadata",
"last_sign_in_at",
"current_sign_in_at",
"created_at",
"updated_at",
"sign_in_count",
"failed_attempts",
"last_sign_in_ip",
"current_sign_in_ip",
"tags",
"internal_note_html",
"default_billing_address_id",
"default_shipping_address_id",
"orders_count",
"total_spent",
"display_total_spent",
"last_order_completed_at"
],
"x-typelizer": true
},
"DeliveryMethod": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"code": {
"type": "string",
"nullable": true
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
}
},
"required": [
"id",
"name",
"code",
"created_at",
"updated_at"
],
"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"
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
}
},
"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",
"created_at",
"updated_at"
],
"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"
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
}
},
"required": [
"id",
"access_counter",
"filename",
"content_type",
"download_url",
"authorizable",
"expired",
"access_limit_exceeded",
"created_at",
"updated_at"
],
"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"
# --- truncated at 32 KB (102 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/spree/refs/heads/main/json-schema/spree-admin-api-schemas.json