Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Added seller-owned package types (#14599)
Damian Legawiec42387b018797
diff --git a/docs/api-reference/admin.yaml b/docs/api-reference/admin.yamlindex 8ba92520b7..f7f951e54d 100644--- a/docs/api-reference/admin.yaml+++ b/docs/api-reference/admin.yaml@@ -376,6 +376,8 @@ paths:- write_settings- read_delivery_methods- write_delivery_methods+ - read_package_types+ - write_package_types- read_webhooks- write_webhooks- read_integrations@@ -509,6 +511,8 @@ paths:- write_settings- read_delivery_methods- write_delivery_methods+ - read_package_types+ - write_package_types- read_webhooks- write_webhooks- read_integrations@@ -24656,6 +24660,20 @@ paths:group_label: Settingslabel: Delivery methodsdescription: ''+ - key: read_package_types+ resource: package_types+ kind: read+ group: settings+ group_label: Settings+ label: Package types+ description: ''+ - key: write_package_types+ resource: package_types+ kind: write+ group: settings+ group_label: Settings+ label: Package types+ description: ''- key: read_webhooksresource: webhookskind: read@@ -24776,7 +24794,7 @@ paths:label: Analytics dashboarddescription: Sales and performance analyticsmeta:- count: 51+ count: 53"/api/v3/admin/roles":get:summary: List roles@@ -24862,6 +24880,8 @@ paths:- write_settings- read_delivery_methods- write_delivery_methods+ - read_package_types+ - write_package_types- read_webhooks- write_webhooks- read_integrations@@ -32333,13 +32353,13 @@ paths:video_embed_url:video_url:poster_url:- original_url: http://localhost:3000/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--22b0b06fdcb2e00b205d0a6800cb54c308345930/thinking-cat.jpg- mini_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--22b0b06fdcb2e00b205d0a6800cb54c308345930/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjgsMTI4XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--285b3917fb12b51c9a42eb7b7e7cd0f539a71d0f/thinking-cat.jpg- small_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--22b0b06fdcb2e00b205d0a6800cb54c308345930/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyNTYsMjU2XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--01a5570c75ffec990b28ff84eb5c6d248ae0aed7/thinking-cat.jpg- medium_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--22b0b06fdcb2e00b205d0a6800cb54c308345930/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls0MDAsNDAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--f8f8173ea6e3dbd52958d148c031eb90b1f7887b/thinking-cat.jpg- large_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--22b0b06fdcb2e00b205d0a6800cb54c308345930/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls3MjAsNzIwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--16ab042f8184f3f2e4100808d2288a92a263a35b/thinking-cat.jpg- xlarge_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--22b0b06fdcb2e00b205d0a6800cb54c308345930/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyMDAwLDIwMDBdLCJzYXZlciI6eyJzdHJpcCI6dHJ1ZSwicXVhbGl0eSI6NzUsImxvc3NsZXNzIjpmYWxzZSwiYWxwaGFfcSI6ODUsInJlZHVjdGlvbl9lZmZvcnQiOjYsInNtYXJ0X3N1YnNhbXBsZSI6dHJ1ZX19LCJwdXIiOiJ2YXJpYXRpb24ifX0=--09a3feb7bc6972e0808e6fac63e6cfe8aad11729/thinking-cat.jpg- og_image_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--22b0b06fdcb2e00b205d0a6800cb54c308345930/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjAwLDYzMF0sInNhdmVyIjp7InN0cmlwIjp0cnVlLCJxdWFsaXR5Ijo3NSwibG9zc2xlc3MiOmZhbHNlLCJhbHBoYV9xIjo4NSwicmVkdWN0aW9uX2VmZm9ydCI6Niwic21hcnRfc3Vic2FtcGxlIjp0cnVlfX0sInB1ciI6InZhcmlhdGlvbiJ9fQ==--7a3ab12c8c6a276e5ac32ebfa4611c0c042a14ae/thinking-cat.jpg+ original_url: http://localhost:3000/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--8397c7f5947f42bb70d44a0210e65d936a4aa78f/thinking-cat.jpg+ mini_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--8397c7f5947f42bb70d44a0210e65d936a4aa78f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjgsMTI4XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--3c0aba87eeb01158ead12346e9ab5281961868ab/thinking-cat.jpg+ small_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--8397c7f5947f42bb70d44a0210e65d936a4aa78f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyNTYsMjU2XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--7c924f15175bec706e022ad3ede0cc2f6810ec7f/thinking-cat.jpg+ medium_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--8397c7f5947f42bb70d44a0210e65d936a4aa78f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls0MDAsNDAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--479aa4f175002b66726ddca93466ba7bcb9bcc14/thinking-cat.jpg+ large_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--8397c7f5947f42bb70d44a0210e65d936a4aa78f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls3MjAsNzIwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--3b0a16c92fd57e8a78946945c6033159a6c2413a/thinking-cat.jpg+ xlarge_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--8397c7f5947f42bb70d44a0210e65d936a4aa78f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyMDAwLDIwMDBdLCJzYXZlciI6eyJzdHJpcCI6dHJ1ZSwicXVhbGl0eSI6NzUsImxvc3NsZXNzIjpmYWxzZSwiYWxwaGFfcSI6ODUsInJlZHVjdGlvbl9lZmZvcnQiOjYsInNtYXJ0X3N1YnNhbXBsZSI6dHJ1ZX19LCJwdXIiOiJ2YXJpYXRpb24ifX0=--86dfdbd5da5bafb65c43e5bbe067760b854822b9/thinking-cat.jpg+ og_image_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--8397c7f5947f42bb70d44a0210e65d936a4aa78f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjAwLDYzMF0sInNhdmVyIjp7InN0cmlwIjp0cnVlLCJxdWFsaXR5Ijo3NSwibG9zc2xlc3MiOmZhbHNlLCJhbHBoYV9xIjo4NSwicmVkdWN0aW9uX2VmZm9ydCI6Niwic21hcnRfc3Vic2FtcGxlIjp0cnVlfX0sInB1ciI6InZhcmlhdGlvbiJ9fQ==--07e35701d864cede251fab4e935d9851eb2be515/thinking-cat.jpgexternal_references: {}created_at: '2026-01-15T12:00:00.000Z'updated_at: '2026-01-15T12:00:00.000Z'@@ -32347,10 +32367,10 @@ paths:filename: thinking-cat.jpgcontent_type: image/jpegbyte_size: 18090- embed_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--22b0b06fdcb2e00b205d0a6800cb54c308345930/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2xpbWl0IjpbMTIwMCwxMjAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--404af3d2abdd9e7b9ce5daccb41a2ec61553b439/thinking-cat.jpg- signed_id: eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--22b0b06fdcb2e00b205d0a6800cb54c308345930+ embed_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--8397c7f5947f42bb70d44a0210e65d936a4aa78f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2xpbWl0IjpbMTIwMCwxMjAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--6b0e64f5f9958922707822ec0e963e2218e6cc62/thinking-cat.jpg+ signed_id: eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--8397c7f5947f42bb70d44a0210e65d936a4aa78fviewable_id: prod_UkLWZg9DAJ- download_url: http://localhost:3000/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--22b0b06fdcb2e00b205d0a6800cb54c308345930/thinking-cat.jpg?disposition=attachment+ download_url: http://localhost:3000/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--8397c7f5947f42bb70d44a0210e65d936a4aa78f/thinking-cat.jpg?disposition=attachmentmetadata: {}viewable_type: productmeta:@@ -32421,13 +32441,13 @@ paths:video_embed_url:video_url:poster_url:- original_url: http://localhost:3000/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--16f527fe734067cabae0342880e1d013f52a7536/library-upload.jpg- mini_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--16f527fe734067cabae0342880e1d013f52a7536/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjgsMTI4XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--285b3917fb12b51c9a42eb7b7e7cd0f539a71d0f/library-upload.jpg- small_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--16f527fe734067cabae0342880e1d013f52a7536/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyNTYsMjU2XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--01a5570c75ffec990b28ff84eb5c6d248ae0aed7/library-upload.jpg- medium_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--16f527fe734067cabae0342880e1d013f52a7536/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls0MDAsNDAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--f8f8173ea6e3dbd52958d148c031eb90b1f7887b/library-upload.jpg- large_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--16f527fe734067cabae0342880e1d013f52a7536/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls3MjAsNzIwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--16ab042f8184f3f2e4100808d2288a92a263a35b/library-upload.jpg- xlarge_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--16f527fe734067cabae0342880e1d013f52a7536/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyMDAwLDIwMDBdLCJzYXZlciI6eyJzdHJpcCI6dHJ1ZSwicXVhbGl0eSI6NzUsImxvc3NsZXNzIjpmYWxzZSwiYWxwaGFfcSI6ODUsInJlZHVjdGlvbl9lZmZvcnQiOjYsInNtYXJ0X3N1YnNhbXBsZSI6dHJ1ZX19LCJwdXIiOiJ2YXJpYXRpb24ifX0=--09a3feb7bc6972e0808e6fac63e6cfe8aad11729/library-upload.jpg- og_image_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--16f527fe734067cabae0342880e1d013f52a7536/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjAwLDYzMF0sInNhdmVyIjp7InN0cmlwIjp0cnVlLCJxdWFsaXR5Ijo3NSwibG9zc2xlc3MiOmZhbHNlLCJhbHBoYV9xIjo4NSwicmVkdWN0aW9uX2VmZm9ydCI6Niwic21hcnRfc3Vic2FtcGxlIjp0cnVlfX0sInB1ciI6InZhcmlhdGlvbiJ9fQ==--7a3ab12c8c6a276e5ac32ebfa4611c0c042a14ae/library-upload.jpg+ original_url: http://localhost:3000/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--39006a87ba6983bc70399a8d1be2074554f9275f/library-upload.jpg+ mini_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--39006a87ba6983bc70399a8d1be2074554f9275f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjgsMTI4XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--3c0aba87eeb01158ead12346e9ab5281961868ab/library-upload.jpg+ small_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--39006a87ba6983bc70399a8d1be2074554f9275f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyNTYsMjU2XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--7c924f15175bec706e022ad3ede0cc2f6810ec7f/library-upload.jpg+ medium_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--39006a87ba6983bc70399a8d1be2074554f9275f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls0MDAsNDAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--479aa4f175002b66726ddca93466ba7bcb9bcc14/library-upload.jpg+ large_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--39006a87ba6983bc70399a8d1be2074554f9275f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls3MjAsNzIwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--3b0a16c92fd57e8a78946945c6033159a6c2413a/library-upload.jpg+ xlarge_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--39006a87ba6983bc70399a8d1be2074554f9275f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyMDAwLDIwMDBdLCJzYXZlciI6eyJzdHJpcCI6dHJ1ZSwicXVhbGl0eSI6NzUsImxvc3NsZXNzIjpmYWxzZSwiYWxwaGFfcSI6ODUsInJlZHVjdGlvbl9lZmZvcnQiOjYsInNtYXJ0X3N1YnNhbXBsZSI6dHJ1ZX19LCJwdXIiOiJ2YXJpYXRpb24ifX0=--86dfdbd5da5bafb65c43e5bbe067760b854822b9/library-upload.jpg+ og_image_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--39006a87ba6983bc70399a8d1be2074554f9275f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjAwLDYzMF0sInNhdmVyIjp7InN0cmlwIjp0cnVlLCJxdWFsaXR5Ijo3NSwibG9zc2xlc3MiOmZhbHNlLCJhbHBoYV9xIjo4NSwicmVkdWN0aW9uX2VmZm9ydCI6Niwic21hcnRfc3Vic2FtcGxlIjp0cnVlfX0sInB1ciI6InZhcmlhdGlvbiJ9fQ==--07e35701d864cede251fab4e935d9851eb2be515/library-upload.jpgexternal_references: {}created_at: '2026-01-15T12:00:00.000Z'updated_at: '2026-01-15T12:00:00.000Z'@@ -32435,10 +32455,10 @@ paths:filename: library-upload.jpgcontent_type: image/jpegbyte_size: 18090- embed_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--16f527fe734067cabae0342880e1d013f52a7536/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2xpbWl0IjpbMTIwMCwxMjAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--404af3d2abdd9e7b9ce5daccb41a2ec61553b439/library-upload.jpg- signed_id: eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--16f527fe734067cabae0342880e1d013f52a7536+ embed_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--39006a87ba6983bc70399a8d1be2074554f9275f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2xpbWl0IjpbMTIwMCwxMjAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--6b0e64f5f9958922707822ec0e963e2218e6cc62/library-upload.jpg+ signed_id: eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--39006a87ba6983bc70399a8d1be2074554f9275fviewable_id:- download_url: http://localhost:3000/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--16f527fe734067cabae0342880e1d013f52a7536/library-upload.jpg?disposition=attachment+ download_url: http://localhost:3000/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--39006a87ba6983bc70399a8d1be2074554f9275f/library-upload.jpg?disposition=attachmentmetadata: {}viewable_type:schema:@@ -32595,13 +32615,13 @@ paths:video_embed_url:video_url:poster_url:- original_url: http://localhost:3000/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--22b0b06fdcb2e00b205d0a6800cb54c308345930/thinking-cat.jpg- mini_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--22b0b06fdcb2e00b205d0a6800cb54c308345930/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjgsMTI4XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--285b3917fb12b51c9a42eb7b7e7cd0f539a71d0f/thinking-cat.jpg- small_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--22b0b06fdcb2e00b205d0a6800cb54c308345930/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyNTYsMjU2XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--01a5570c75ffec990b28ff84eb5c6d248ae0aed7/thinking-cat.jpg- medium_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--22b0b06fdcb2e00b205d0a6800cb54c308345930/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls0MDAsNDAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--f8f8173ea6e3dbd52958d148c031eb90b1f7887b/thinking-cat.jpg- large_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--22b0b06fdcb2e00b205d0a6800cb54c308345930/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls3MjAsNzIwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--16ab042f8184f3f2e4100808d2288a92a263a35b/thinking-cat.jpg- xlarge_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--22b0b06fdcb2e00b205d0a6800cb54c308345930/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyMDAwLDIwMDBdLCJzYXZlciI6eyJzdHJpcCI6dHJ1ZSwicXVhbGl0eSI6NzUsImxvc3NsZXNzIjpmYWxzZSwiYWxwaGFfcSI6ODUsInJlZHVjdGlvbl9lZmZvcnQiOjYsInNtYXJ0X3N1YnNhbXBsZSI6dHJ1ZX19LCJwdXIiOiJ2YXJpYXRpb24ifX0=--09a3feb7bc6972e0808e6fac63e6cfe8aad11729/thinking-cat.jpg- og_image_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--22b0b06fdcb2e00b205d0a6800cb54c308345930/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjAwLDYzMF0sInNhdmVyIjp7InN0cmlwIjp0cnVlLCJxdWFsaXR5Ijo3NSwibG9zc2xlc3MiOmZhbHNlLCJhbHBoYV9xIjo4NSwicmVkdWN0aW9uX2VmZm9ydCI6Niwic21hcnRfc3Vic2FtcGxlIjp0cnVlfX0sInB1ciI6InZhcmlhdGlvbiJ9fQ==--7a3ab12c8c6a276e5ac32ebfa4611c0c042a14ae/thinking-cat.jpg+ original_url: http://localhost:3000/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--8397c7f5947f42bb70d44a0210e65d936a4aa78f/thinking-cat.jpg+ mini_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--8397c7f5947f42bb70d44a0210e65d936a4aa78f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjgsMTI4XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--3c0aba87eeb01158ead12346e9ab5281961868ab/thinking-cat.jpg+ small_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--8397c7f5947f42bb70d44a0210e65d936a4aa78f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyNTYsMjU2XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--7c924f15175bec706e022ad3ede0cc2f6810ec7f/thinking-cat.jpg+ medium_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--8397c7f5947f42bb70d44a0210e65d936a4aa78f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls0MDAsNDAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--479aa4f175002b66726ddca93466ba7bcb9bcc14/thinking-cat.jpg+ large_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--8397c7f5947f42bb70d44a0210e65d936a4aa78f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls3MjAsNzIwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--3b0a16c92fd57e8a78946945c6033159a6c2413a/thinking-cat.jpg+ xlarge_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--8397c7f5947f42bb70d44a0210e65d936a4aa78f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyMDAwLDIwMDBdLCJzYXZlciI6eyJzdHJpcCI6dHJ1ZSwicXVhbGl0eSI6NzUsImxvc3NsZXNzIjpmYWxzZSwiYWxwaGFfcSI6ODUsInJlZHVjdGlvbl9lZmZvcnQiOjYsInNtYXJ0X3N1YnNhbXBsZSI6dHJ1ZX19LCJwdXIiOiJ2YXJpYXRpb24ifX0=--86dfdbd5da5bafb65c43e5bbe067760b854822b9/thinking-cat.jpg+ og_image_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--8397c7f5947f42bb70d44a0210e65d936a4aa78f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjAwLDYzMF0sInNhdmVyIjp7InN0cmlwIjp0cnVlLCJxdWFsaXR5Ijo3NSwibG9zc2xlc3MiOmZhbHNlLCJhbHBoYV9xIjo4NSwicmVkdWN0aW9uX2VmZm9ydCI6Niwic21hcnRfc3Vic2FtcGxlIjp0cnVlfX0sInB1ciI6InZhcmlhdGlvbiJ9fQ==--07e35701d864cede251fab4e935d9851eb2be515/thinking-cat.jpgexternal_references: {}created_at: '2026-01-15T12:00:00.000Z'updated_at: '2026-01-15T12:00:00.000Z'@@ -32609,10 +32629,10 @@ paths:filename: thinking-cat.jpgcontent_type: image/jpegbyte_size: 18090- embed_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--22b0b06fdcb2e00b205d0a6800cb54c308345930/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2xpbWl0IjpbMTIwMCwxMjAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--404af3d2abdd9e7b9ce5daccb41a2ec61553b439/thinking-cat.jpg- signed_id: eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--22b0b06fdcb2e00b205d0a6800cb54c308345930+ embed_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--8397c7f5947f42bb70d44a0210e65d936a4aa78f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2xpbWl0IjpbMTIwMCwxMjAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--6b0e64f5f9958922707822ec0e963e2218e6cc62/thinking-cat.jpg+ signed_id: eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--8397c7f5947f42bb70d44a0210e65d936a4aa78fviewable_id: prod_gbHJdmfrXB- download_url: http://localhost:3000/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--22b0b06fdcb2e00b205d0a6800cb54c308345930/thinking-cat.jpg?disposition=attachment+ download_url: http://localhost:3000/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--8397c7f5947f42bb70d44a0210e65d936a4aa78f/thinking-cat.jpg?disposition=attachmentmetadata: {}viewable_type: productschema:@@ -33501,7 +33521,7 @@ paths:measured.- **Required scope:** `read_settings` (for API-key authentication).+ **Required scope:** `read_package_types` (for API-key authentication).x-codeSamples:- lang: javascriptlabel: Spree Admin SDK@@ -33575,6 +33595,8 @@ paths:dimensions_unit: cmweight_unit: kgvolume: '0.03'+ seller_id:+ seller_name:meta:page: 1limit: 25@@ -33626,7 +33648,7 @@ paths:into; other kinds are the merchant's own vocabulary.- **Required scope:** `write_settings` (for API-key authentication).+ **Required scope:** `write_package_types` (for API-key authentication).x-codeSamples:- lang: javascriptlabel: Spree Admin SDK@@ -33684,6 +33706,8 @@ paths:dimensions_unit: cmweight_unit: lbvolume: '0.144'+ seller_id:+ seller_name:schema:"$ref": "#/components/schemas/PackageType"'422':@@ -33775,7 +33799,7 @@ paths:description: |-Returns a single package type by prefixed ID.- **Required scope:** `read_settings` (for API-key authentication).+ **Required scope:** `read_package_types` (for API-key authentication).x-codeSamples:- lang: javascriptlabel: Spree Admin SDK@@ -33824,6 +33848,8 @@ paths:dimensions_unit: cmweight_unit: kgvolume: '0.03'+ seller_id:+ seller_name:schema:"$ref": "#/components/schemas/PackageType"'404':@@ -33846,7 +33872,7 @@ paths:description: |-Updates a package type. Every product packed in it follows the new geometry.- **Required scope:** `write_settings` (for API-key authentication).+ **Required scope:** `write_package_types` (for API-key authentication).x-codeSamples:- lang: javascriptlabel: Spree Admin SDK@@ -33897,6 +33923,8 @@ paths:dimensions_unit: cmweight_unit: kgvolume: '0.03'+ seller_id:+ seller_name:schema:"$ref": "#/components/schemas/PackageType"requestBody:@@ -33963,7 +33991,7 @@ paths:it — repack those products first.- **Required scope:** `write_settings` (for API-key authentication).+ **Required scope:** `write_package_types` (for API-key authentication).x-codeSamples:- lang: javascriptlabel: Spree Admin SDK@@ -34932,6 +34960,18 @@ paths:accepted_content_types: []association_fields: []preference_schema: []+ - type: package_type+ name: Shipping box+ description: Tell us the size and weight of the box you ship orders+ in+ allow_multiple: false+ accepts_submissions: false+ reviewed_by_operator: false+ configured: false+ addable: true+ accepted_content_types: []+ association_fields: []+ preference_schema: []- type: minimum_productsname: Minimum productsdescription: List at least this many products@@ -41335,6 +41375,12 @@ components:volume:type: stringnullable: true+ seller_id:+ type: string+ nullable: true+ seller_name:+ type: string+ nullable: truerequired:- id- name@@ -41351,6 +41397,8 @@ components:- dimensions_unit- weight_unit- volume+ - seller_id+ - seller_namex-typelizer: truePaymentMethod:type: objectdiff --git a/docs/api-reference/seller.yaml b/docs/api-reference/seller.yamlindex d80e327570..e5393258ec 100644--- a/docs/api-reference/seller.yaml+++ b/docs/api-reference/seller.yaml@@ -420,7 +420,7 @@ paths:avatar_url:sellers:- id: sel_UkLWZg9DAJ- name: Seller 70+ name: Seller 77status: approvedschema:"$ref": "#/components/schemas/AuthResponse"@@ -13996,8 +13996,8 @@ paths:application/json:example:id: sel_UkLWZg9DAJ- name: Seller 87- slug: seller-87+ name: Seller 94+ slug: seller-94about: ''about_html: ''logo_url:@@ -14069,7 +14069,7 @@ paths:example:id: sel_UkLWZg9DAJname: Acme Supplies- slug: seller-89+ slug: seller-96about: ''about_html: ''logo_url:@@ -14816,10 +14816,10 @@ paths:application/json:example:direct_upload:- url: http://www.example.com/rails/active_storage/disk/eyJfcmFpbHMiOnsiZGF0YSI6eyJrZXkiOiJuem5oOGdra3VxendvbDc1ODBxNHNwZmpmMjVxIiwiY29udGVudF90eXBlIjoiYXBwbGljYXRpb24vcGRmIiwiY29udGVudF9sZW5ndGgiOjUxMjM0LCJjaGVja3N1bSI6IlZqaHowNGxRdUVHdXY0bkR2aHNhTlE9PSIsInNlcnZpY2VfbmFtZSI6InRlc3QifSwiZXhwIjoiMjAyNi0wMS0xNVQxMjowNTowMC4wMDBaIiwicHVyIjoiYmxvYl90b2tlbiJ9fQ==--d405b93fe982c6dc17f531d9513d5724b68c2440+ url: http://www.example.com/rails/active_storage/disk/eyJfcmFpbHMiOnsiZGF0YSI6eyJrZXkiOiJuem5oOGdra3VxendvbDc1ODBxNHNwZmpmMjVxIiwiY29udGVudF90eXBlIjoiYXBwbGljYXRpb24vcGRmIiwiY29udGVudF9sZW5ndGgiOjUxMjM0LCJjaGVja3N1bSI6IlZqaHowNGxRdUVHdXY0bkR2aHNhTlE9PSIsInNlcnZpY2VfbmFtZSI6InRlc3QifSwiZXhwIjoiMjAyNi0wMS0xNVQxMjowNTowMC4wMDBaIiwicHVyIjoiYmxvYl90b2tlbiJ9fQ==--90ea643bd59542dcfdac7b6237df290a67faadbeheaders:Content-Type: application/pdf- signed_id: eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--22b0b06fdcb2e00b205d0a6800cb54c308345930+ signed_id: eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--8397c7f5947f42bb70d44a0210e65d936a4aa78fschema:"$ref": "#/components/schemas/DirectUploadResponse"requestBody:@@ -17354,6 +17354,372 @@ paths:"$ref": "#/components/schemas/Reason"required:- data+ "/api/v3/seller/package_types":+ get:+ summary: List package types+ tags:+ - Package Types+ security:+ - bearer_auth: []+ description: |+ What this seller packs their goods into: the boxes their parcels ship+ in, the cartons their products are packed into, the pallets a+ wholesale order leaves on.++ The list carries the marketplace's own packaging alongside the+ seller's, so a seller can pack into the operator's standard cartons+ rather than measuring them again. Those rows report `editable: false`+ and are refused by every write.++ The row marked `default` is the box this seller's parcels are quoted+ with — its size and weight are added to every rate.+ parameters:+ - name: X-Spree-Seller-Id+ in: header+ required: true+ schema:+ type: string+ - name: owner+ in: query+ required: false+ enum:+ - mine+ description: "Narrows the list to the seller's own packaging, leaving out+ the marketplace's shared rows:\n * `mine` \n "+ schema:+ type: string+ - name: page+ in: query+ required: false+ description: Page number+ schema:+ type: integer+ - name: limit+ in: query+ required: false+ description: Records per page (max 100)+ schema:+ type: integer+ responses:+ '200':+ description: package types listed+ content:+ application/json:+ example:+ data:+ - id: pkgtype_UkLWZg9DAJ+ name: Standard mailer+ kind: box+ length: '30.0'+ width: '20.0'+ height: '15.0'+ weight: '0.4'+ max_weight:+ default: true+ metadata: {}+ created_at: '2026-01-15T12:00:00.000Z'+ updated_at: '2026-01-15T12:00:00.000Z'+ dimensions_unit: cm+ weight_unit: kg+ volume: '0.009'+ editable: true+ - id: pkgtype_gbHJdmfrXB+ name: Marketplace carton+ kind: carton+ length: '40.0'+ width: '30.0'+ height: '25.0'+ weight:+ max_weight: '20.0'+ default: false+ metadata: {}+ created_at: '2026-01-15T12:00:00.000Z'+ updated_at: '2026-01-15T12:00:00.000Z'+ dimensions_unit: cm+ weight_unit: kg+ volume: '0.03'+ editable: false+ meta:+ page: 1+ limit: 25+ count: 2+ pages: 1+ from: 1+ to: 2+ in: 2+ previous:+ next:+ schema:+ type: object+ properties:+ data:+ type: array+ items:+ "$ref": "#/components/schemas/PackageType"+ meta:+ "$ref": "#/components/schemas/PaginationMeta"+ required:+ - data+ - meta+ post:+ summary: Create a package type+ tags:+ - Package Types+ security:+ - bearer_auth: []+ description: |+ Records a piece of the seller's own packaging. Marking it `default`+ makes it the box their parcels are quoted with, and demotes whichever+ of their rows held the flag before — the marketplace's default is a+ different owner's row and is left alone.+ parameters:+ - name: X-Spree-Seller-Id+ in: header+ required: true+ schema:+ type: string+ responses:+ '201':+ description: package type created+ content:+ application/json:+ example:+ id: pkgtype_EfhxLZ9ck8+ name: Large mailer+ kind: box+ length: '40.0'+ width: '30.0'+ height: '20.0'+ weight: '0.6'+ max_weight:+ default: false+ metadata: {}+ created_at: '2026-01-15T12:00:00.000Z'+ updated_at: '2026-01-15T12:00:00.000Z'+ dimensions_unit: cm+ weight_unit: kg+ volume: '0.024'+ editable: true+ schema:+ "$ref": "#/components/schemas/PackageType"+ '422':+ description: validation error+ content:+ application/json:+ example:+ error:+ code: validation_error+ message: Kind is not included in the list+ details:+ kind:+ - is not included in the list+ schema:+ "$ref": "#/components/schemas/ErrorResponse"+ requestBody:+ content:+ application/json:+ schema:+ type: object+ properties:+ name:+ type: string+ kind:+ type: string+ enum:+ - box+ - envelope+ - carton+ - pallet+ - container+ length:+ type: number+ nullable: true+ width:+ type: number+ nullable: true+ height:+ type: number+ nullable: true+ dimensions_unit:+ type: string+ nullable: true+ weight:+ type: number+ nullable: true+ description: The empty package's own weight, added to every quote+ max_weight:+ type: number+ nullable: true+ weight_unit:+ type: string+ nullable: true+ default:+ type: boolean+ metadata:+ type: object+ nullable: true+ required:+ - name+ - kind+ required: true+ "/api/v3/seller/package_types/{id}":+ parameters:+ - name: id+ in: path+ required: true+ description: Package type ID+ schema:+ type: string+ get:+ summary: Get a package type+ tags:+ - Package Types+ security:+ - bearer_auth: []+ description: |+ Returns one package type by prefixed ID — the seller's own, or a+ marketplace row they may pack into.+ parameters:+ - name: X-Spree-Seller-Id+ in: header+ required: true+ schema:+ type: string+ responses:+ '200':+ description: package type found+ content:+ application/json:+ example:+ id: pkgtype_UkLWZg9DAJ+ name: Standard mailer+ kind: box+ length: '30.0'+ width: '20.0'+ height: '15.0'+ weight: '0.4'+ max_weight:+ default: true+ metadata: {}+ created_at: '2026-01-15T12:00:00.000Z'+ updated_at: '2026-01-15T12:00:00.000Z'+ dimensions_unit: cm+ weight_unit: kg+ volume: '0.009'+ editable: true+ schema:+ "$ref": "#/components/schemas/PackageType"+ '404':+ description: package type not found+ content:+ application/json:+ example:+ error:+ code: record_not_found+ message: Package type not found+ schema:+ "$ref": "#/components/schemas/ErrorResponse"+ patch:+ summary: Update a package type+ tags:+ - Package Types+ security:+ - bearer_auth: []+ description: |+ Changes the seller's own packaging. A marketplace row is not theirs to+ edit and answers 404.+ parameters:+ - name: X-Spree-Seller-Id+ in: header+ required: true+ schema:+ type: string+ responses:+ '200':+ description: package type updated+ content:+ application/json:+ example:+ id: pkgtype_UkLWZg9DAJ+ name: Standard mailer+ kind: box+ length: '30.0'+ width: '20.0'+ height: '15.0'+ weight: '0.4'+ max_weight: '25.0'+ default: true+ metadata: {}+ created_at: '2026-01-15T12:00:00.000Z'+ updated_at: '2026-01-15T12:00:00.000Z'+ dimensions_unit: cm+ weight_unit: kg+ volume: '0.009'+ editable: true+ schema:+ "$ref": "#/components/schemas/PackageType"+ requestBody:+ content:+ application/json:+ schema:+ type: object+ properties:+ name:+ type: string+ kind:+ type: string+ enum:+ - box+ - envelope+ - carton+ - pallet+ - container+ length:+ type: number+ nullable: true+ width:+ type: number+ nullable: true+ height:+ type: number+ nullable: true+ dimensions_unit:+ type: string+ nullable: true+ weight:+ type: number+ nullable: true+ max_weight:+ type: number+ nullable: true+ weight_unit:+ type: string+ nullable: true+ default:+ type: boolean+ metadata:+ type: object+ nullable: true+ required: true+ delete:+ summary: Delete a package type+ tags:+ - Package Types+ security:+ - bearer_auth: []+ description: |+ Retires one of the seller's own package types. The default box is+ refused — name another default first, or every parcel silently falls+ back to the marketplace's box.+ parameters:+ - name: X-Spree-Seller-Id+ in: header+ required: true+ schema:+ type: string+ responses:+ '204':+ description: package type deleted"/api/v3/seller/orders/{order_id}/returns":parameters:- name: order_id@@ -19913,6 +20279,66 @@ components:- shipping_address- billing_addressx-typelizer: true+ PackageType:+ type: object+ properties:+ id:+ type: string+ name:+ type: string+ kind:+ type: string+ length:+ type: string+ nullable: true+ width:+ type: string+ nullable: true+ height:+ type: string+ nullable: true+ weight:+ type: string+ nullable: true+ max_weight:+ type: string+ nullable: true+ default:+ type: boolean+ metadata:+ type: object+ nullable: true+ created_at:+ type: string+ updated_at:+ type: string+ dimensions_unit:+ type: string+ weight_unit:+ type: string+ volume:+ type: string+ nullable: true+ editable:+ type: boolean+ required:+ - id+ - name+ - kind+ - length+ - width+ - height+ - weight+ - max_weight+ - default+ - metadata+ - created_at+ - updated_at+ - dimensions_unit+ - weight_unit+ - volume+ - editable+ x-typelizer: truePolicy:type: objectproperties:@@ -20764,6 +21190,10 @@ components:depth:type: numbernullable: true+ weight_unit:+ type: string+ dimensions_unit:+ type: stringminimum_order_quantity:type: numbernullable: true@@ -20818,12 +21248,6 @@ components:barcode:type: stringnullable: true- weight_unit:- type: string- nullable: true- dimensions_unit:- type: string- nullable: truebackorder_limit:type: numbernullable: true@@ -20873,6 +21297,8 @@ components:- height- width- depth+ - weight_unit+ - dimensions_unit- minimum_order_quantity- order_multiple- purchase_unit@@ -20886,8 +21312,6 @@ components:- cost_price- cost_currency- barcode- - weight_unit- - dimensions_unit- backorder_limit- hs_code- country_of_origindiff --git a/docs/developer/core-concepts/delivery-setup.mdx b/docs/developer/core-concepts/delivery-setup.mdxindex e13fa7a767..519b648293 100644--- a/docs/developer/core-concepts/delivery-setup.mdx+++ b/docs/developer/core-concepts/delivery-setup.mdx@@ -122,6 +122,79 @@ A method is priced one of two ways, and the choice is per method:A carrier-priced method returns one option per service, so a single "Carrierrates" method can offer Ground, 2-Day and Overnight as separate choices.+## Packaging++Every quote needs to know what the goods travel in. A carrier charges by+dimensional weight as well as actual weight, so the size of the box matters to+the price, and the empty box's own weight has to be added to what it holds —+otherwise every parcel is quoted light.++Package types are that vocabulary: the box parcels ship in, and for wholesale,+the cartons products are packed into and the pallets or containers an order+leaves on.++```typescript Admin SDK+await adminClient.packageTypes.create({+ name: 'Standard mailer',+ kind: 'box',+ length: 30, width: 20, height: 15, dimensions_unit: 'cm',+ weight: 0.4, weight_unit: 'kg',+ default: true,+})+```++One row is marked `default`, and that is the box quotes are built on. Marking+another one default demotes the first, so there is never more than one.++Measurements are optional individually, which is how a merchant records what+they know. A box with no dimensions still contributes its weight; a box with+nothing measured contributes nothing, and dimensional pricing has nothing to+work from.++<Note>+Deleting the default box is refused, and so is switching its flag off when+nothing else would take it. Both would leave quotes with no size and no tare,+which under-prices bulky parcels silently rather than failing.+</Note>++### On a marketplace++A seller packs their own goods, in their own boxes, from their own warehouse.+So packaging has an owner: rows created by the operator are the marketplace's,+and each seller has their own.++A parcel is quoted with the box belonging to whoever's warehouse it left,+falling back to the marketplace's when a seller has not recorded one. Sellers+manage theirs through the Seller API, and can also pack products into the+marketplace's cartons — those they read but cannot change.++```typescript Seller SDK+// Their own packaging — what the seller panel's settings page lists.+const { data: mine } = await sellerClient.packageTypes.list({ owner: 'mine' })++// Their own plus the marketplace's, which is what a carton picker wants.+const { data: available } = await sellerClient.packageTypes.list()++available.forEach((row) => {+ row.name+ row.editable // false on the marketplace's own rows+ row.default // this seller's default box+})+```++A seller's settings page asks for `owner: 'mine'`. A list mixing both owners+reads as "packaging is configured" while the seller has recorded nothing of+their own, which makes the shipping-box requirement look broken rather than+outstanding. Where a seller genuinely benefits from the marketplace's rows —+choosing the carton a product is packed into — the unfiltered list is what+the picker reads.++Because the fallback keeps checkout working, a seller who never opens the page+would quietly ship with someone else's measurements. The **shipping box**+onboarding requirement is what asks them for it: it is satisfied by a default+box of their own with all three dimensions and a weight recorded. See+[sellers](/developer/core-concepts/sellers#onboarding-requirements).+## Related- [Fulfillments](/developer/core-concepts/fulfillments) — what happens to the parcel afterwardsdiff --git a/docs/developer/core-concepts/sellers.mdx b/docs/developer/core-concepts/sellers.mdxindex 762ca2aa8c..08c3f3cbc4 100644--- a/docs/developer/core-concepts/sellers.mdx+++ b/docs/developer/core-concepts/sellers.mdx@@ -87,7 +87,7 @@ Requirements come in three flavours, which is what lets one mechanism cover very| **Attested** | The seller confirms something — accepting terms || **Verified** | The seller submits something and the marketplace rules on it — a document, an operator review |-Shipped out of the box: accepting terms, completing the profile, a billing address, a returns address, and a minimum number of products. Also available are generic document upload, attestation, operator review, and required custom fields.+Shipped out of the box: accepting terms, completing the profile, a billing address, a returns address, a way to ship, the box they ship in, and a minimum number of products. Also available are generic document upload, attestation, operator review, and required custom fields.A seller sees their checklist and its progress:@@ -205,7 +205,7 @@ await sellerClient.orders.fulfillments.fulfill(orderId, fulfillmentId, {})```-Sellers can manage their profile, invite their own team, list and submit products, see and fulfil their orders, manage their stock locations, and work through onboarding. They cannot see other sellers, the marketplace's own catalog, or anything belonging to the store at large.+Sellers can manage their profile, invite their own team, list and submit products, see and fulfil their orders, manage their stock locations, delivery methods and packaging, and work through onboarding. They cannot see other sellers, the marketplace's own catalog, or anything belonging to the store at large.What a seller's staff may do is governed by [roles](/developer/core-concepts/staff-roles) owned by the seller — the same permission system as the back office, with a narrower set of keys, so a seller role can never reach store settings.@@ -214,5 +214,6 @@ What a seller's staff may do is governed by [roles](/developer/core-concepts/sta- [Commissions](/developer/core-concepts/commissions) — rates, rules, and what the marketplace charges- [Products](/developer/core-concepts/products#seller-submissions) — the listing review flow- [Orders](/developer/core-concepts/orders) — orders and their statuses+- [Delivery setup](/developer/core-concepts/delivery-setup#on-a-marketplace) — how a seller's goods ship, and what they ship in- [Staff & Roles](/developer/core-concepts/staff-roles) — how seller teams are governed- [Seller API](/api-reference/seller-api/introduction) — the full endpoint referencediff --git a/docs/plans/6.0-b2b-wholesale-shipping.md b/docs/plans/6.0-b2b-wholesale-shipping.mdindex 252beb9321..33d67c4c0b 100644--- a/docs/plans/6.0-b2b-wholesale-shipping.md+++ b/docs/plans/6.0-b2b-wholesale-shipping.md@@ -196,6 +196,16 @@ end- Admin API: `/api/v3/admin/package_types` CRUD under the `settings` scope;dashboard page under Settings → Shipping.+> **Cross-reference (2026-09-08, `6.0-seller-package-types.md`).** On a+> marketplace a package type has an optional seller owner: the marketplace's+> rows (nil `seller_id`) are a vocabulary every seller reads and may pack into,+> a seller's rows are theirs alone, and a package from a seller's warehouse is+> quoted with that seller's default box before falling back to the store's.+> Two consequences for this section: "one default per store" became one per+> owner, and the admin endpoint moved from the `settings` permission resource+> to a seller-grantable `package_types` resource. `Stock::Package#default_package_type`+> is the one place that resolves whose box a package gets.+### Variant carton details```rubydiff --git a/docs/plans/6.0-multi-vendor-marketplace.md b/docs/plans/6.0-multi-vendor-marketplace.mdindex 03e3b98a3d..2a77283908 100644--- a/docs/plans/6.0-multi-vendor-marketplace.md+++ b/docs/plans/6.0-multi-vendor-marketplace.md@@ -265,6 +265,15 @@ A marketplace has two different delivery questions, and they get two different oTwo details settled during implementation. The eligibility filter runs in Ruby over the loaded methods rather than as a merged scope, because `Package#eligible_delivery_methods` is stubbed with a plain array in a good deal of existing coverage. And the seller's rule vocabulary is a subset of the operator's — channel rules segment the marketplace's own traffic and the excluded-products rule wants a catalog picker the panel does not have — with a kind outside that subset refused rather than dropped, so a seller is never told a condition saved that did not.+> **Cross-reference (2026-09-08, `6.0-seller-package-types.md`).** Packaging+> joins the seller's side of this split: `Spree::PackageType` gains a nullable+> `seller_id` with the same `first_party` / `for_seller` scopes and the same+> `dependent: nil` reasoning as delivery methods, a seller's package is quoted+> with their own default box, and a computed `PackageType` onboarding+> requirement asks each seller for it. Unlike methods there is no+> `available_to_sellers` flag — the marketplace's cartons carry no price, so+> every seller may read and pack into them.+## Design Details### Seller identity & teamsdiff --git a/docs/plans/6.0-seller-onboarding-requirements.md b/docs/plans/6.0-seller-onboarding-requirements.mdindex 36789f7a5a..9e8121b5fb 100644--- a/docs/plans/6.0-seller-onboarding-requirements.md+++ b/docs/plans/6.0-seller-onboarding-requirements.md@@ -120,8 +120,9 @@ Kind i18n keys: `seller_requirement_types.<api_type>.name` / `.description`, mir| `OperatorReview` | verified | latest submission `accepted` (or `waived`) | — (`allow_multiple?`, `reviewed_by_operator?`) — "we will verify your VAT number": the seller marks it done with a note/reference, the operator confirms || `Document` | verified | latest submission `accepted` (or `waived`) and it carries a file | none — `Document::ACCEPTED_CONTENT_TYPES` is fixed (PDF, images, Word) and **told** to the operator, never asked: the answer is the same for every marketplace, and typing MIME types is a way to get `image/jpg` wrong and accept nothing. `allow_multiple?`, `reviewed_by_operator?`; one row per document the operator wants, each with its own name and description; the file lives on the submission || `DeliveryMethod` | computed | at least one active seller-owned delivery method | — ; ships with the marketplace plan's Phase 3 (seller-owned delivery methods do not exist before that) |+| `PackageType` | computed | the seller's own default package type has all three dimensions and a weight recorded — the marketplace's box does not count | — ; ships with `6.0-seller-package-types.md` (seller-owned package types do not exist before it) |-Provisioned by default (in this order): `AcceptTerms`, `CompleteProfile`, `BillingAddress`, `ReturnsAddress`, `MinimumProducts`, and `DeliveryMethod` once it exists. All `active`, all `required`. `RequiredCustomFields`, `Attestation`, `OperatorReview` and `Document` are never provisioned — they only mean something once the operator has written what they ask for.+Provisioned by default, in the order `DEFAULT_KINDS` lists them (which is the order the checklist renders): `AcceptTerms`, `CompleteProfile`, `BillingAddress`, `ReturnsAddress`, `DeliveryMethod`, `PackageType`, `MinimumProducts`. All `active`, all `required`. `RequiredCustomFields`, `Attestation`, `OperatorReview` and `Document` are never provisioned — they only mean something once the operator has written what they ask for.Kinds shipped by other gems, not core: the monorepo Stripe gateway (`spree/providers/stripe`) adds a **payout account** kind (`satisfied?` = connected account can receive transfers, `status_for` = `pending` while the provider still lists outstanding requirements, `action_url` = the hosted onboarding link, `applicable?` only when the store has that payout provider configured) — shipped with the marketplace plan's Phase 3b. Enterprise adds its KYC follow-through and external store connection kinds. Their paid value is in the kind; the checklist that renders them is this plan.@@ -215,7 +216,7 @@ New OSS code — no in-place migration for existing stores. Steps, each shippabl1. **Core**: `Spree::SellerRequirement` + STI kinds, `Spree::SellerRequirementSubmission`, evaluator + value object, `Spree.seller_requirements` registry, the four submission workflows, `StartOnboarding` / `SubmitForReview` / `ReopenOnboarding`, the `Approve` change, `auto_approve_sellers` preference, `provision_defaults` + `Seeds::SellerRequirements`, events, mailer additions, factories, specs.2. **API**: admin controllers + `types`, the `onboarding` include on the admin seller serializer, seller-branch endpoints, serializers with typelizer output, integration specs → OpenAPI, SDK regeneration.3. **Dashboard**: settings page, seller detail card, index column, locales.-4. **Providers**: the payout-account kind in `spree/providers/stripe` (with marketplace Phase 3b); `DeliveryMethod` kind with Phase 3.+4. **Providers**: the payout-account kind in `spree/providers/stripe` (with marketplace Phase 3b); `DeliveryMethod` kind with Phase 3; `PackageType` kind with `6.0-seller-package-types.md` (implemented 2026-09-08).5. **Enterprise backfill** (Enterprise-side task): the legacy `preferred_shipping_rates_confirmed` becomes an accepted `Attestation` submission; the legacy `skip_global_onboarding_tasks` per-vendor flag becomes waived submissions; its Stripe check maps onto the payout-account kind.## Constraints on Current Workdiff --git a/docs/plans/6.0-seller-package-types.md b/docs/plans/6.0-seller-package-types.mdnew file mode 100644index 0000000000..494478af2a--- /dev/null+++ b/docs/plans/6.0-seller-package-types.md@@ -0,0 +1,322 @@+# Seller-owned package types++**Status:** Implemented — design finalized 2026-09-08; all five phases implemented 2026-09-08 (core ownership and quoting, the seller API and permission resource, the onboarding requirement, both panels, docs)+**Target:** Spree 6.0+**Depends on:** `6.0-b2b-wholesale-shipping.md` (`Spree::PackageType`, the carton chain on variants, the tare and dimensions a parcel quote is built on), `6.0-multi-vendor-marketplace.md` (Decision 13: the seller owns "who ships it and how"; seller-owned delivery methods and stock locations are the precedent), `6.0-seller-onboarding-requirements.md` (the requirement kinds registry the new kind joins), `6.0-admin-rbac.md` (permission catalog; a capability a new audience holds gets its own resource)+**Author:** Damian Legawiec+**Last updated:** 2026-09-08++## Summary++`Spree::PackageType` is the store's packaging vocabulary: the box parcels ship+in, the cartons products are packed into, the pallets and containers wholesale+orders leave on. It was built store-scoped, and on a marketplace that is the+wrong owner for most of it. A seller packs their own goods into their own+cartons and posts them in their own boxes, yet today every seller's parcel is+quoted with the marketplace's default box, the seller API already accepts a+carton reference on a variant that no seller can discover, and the seller panel+has no way to record either. This plan gives package types an optional seller+owner, following the split the marketplace plan settled for delivery methods:+the operator's rows stay a shared vocabulary every seller can read and pack+into, a seller's rows are theirs alone, and a package from a seller's warehouse+is quoted with that seller's box. A new computed onboarding requirement asks+each seller to record the size and weight of the box they ship in, so the+fallback to the operator's box is a safety net rather than the norm.++## Key Decisions (do not deviate without discussion)++- **Package types are seller-ownable, like delivery methods and stock+ locations; they are not marketplace vocabulary like profiles and zones**+ (2026-09-08). Decision 13 of the marketplace plan draws the line at the+ question being answered: "what kind of goods is this" belongs to the+ marketplace, "who ships it, how, and in what" belongs to the seller. A+ carton size is a fact about the seller's product and a box is what the seller+ physically posts, so `spree_package_types` gains a nullable `seller_id`. A+ nil owner is the marketplace's row, exactly as it is for delivery methods and+ stock locations.+- **The operator's rows are readable by every seller; a seller's rows are+ readable by nobody else** (2026-09-08). A package type is only geometry and a+ tare, so letting sellers pack into the marketplace's standard cartons costs+ nothing and gives a new seller a vocabulary from day one. No opt-in flag like+ `available_to_sellers`: that flag exists because a delivery method carries a+ price, and a carton carries none. Writes root in the seller's own rows, so a+ marketplace row's id is a 404 on every seller action but `show`.+- **A package's box is its seller's default, falling back to the store's**+ (2026-09-08). `Stock::Package` reads the box through its stock location's+ seller, which is how a package's seller is derived everywhere else. A seller+ with no default box of their own is quoted with the marketplace's, so+ checkout never loses its tare because a seller skipped a settings page; the+ onboarding requirement below is what makes that fallback rare.+- **One default per owner, not one per store** (2026-09-08). The operator has a+ default box and each seller has their own. The partial unique index that+ enforces "one default per store" today is split into two, one for marketplace+ rows and one for seller rows, because a nullable column inside a unique index+ constrains nothing for the rows where it is null. The name uniqueness index is+ split the same way. MySQL cannot express partial indexes and already relies on+ the model validations for the default flag; it now relies on them for the name+ as well. Accepted trade-off, recorded under Constraints.+- **Package types leave the `settings` permission resource for their own,+ seller-grantable `package_types` resource** (2026-09-08). `settings` is+ never seller-grantable, and per the RBAC plan a capability a new audience+ holds gets its own entry rather than a widened existing one. This is the same+ move `delivery_methods` made on 2026-09-01. Unreleased edge, so no bridge:+ operator roles are data and the seeded admin role is a super-role.+- **A seller must be asked for their box, not blocked without one**+ (2026-09-08). `Spree::SellerRequirements::PackageType` is a computed kind,+ satisfied when the seller has a default package type of their own with all+ three dimensions and a weight recorded. A default row with blanks is exactly+ the silent under-quoting the model's own guards exist to prevent, so the kind+ checks the numbers, not the row. It does not count the operator's box: a+ seller using the marketplace's shared rates still packs and posts their own+ parcel, and a marketplace where the operator physically ships everything+ switches the requirement off. Provisioned by default, active and required,+ for parity with the `DeliveryMethod` kind; both close the same gap, a wrong+ quote at checkout.+- **The seller's settings page lists only their own rows** (2026-09-08, found+ in manual QA). The endpoint still answers both owners by default, because a+ carton picker needs the marketplace's shared vocabulary. But a settings page+ showing three marketplace boxes beside an outstanding "shipping box"+ requirement reads as a bug in the requirement rather than as work the seller+ has not done — which is exactly how it was reported. `owner=mine` narrows+ it, sent as a plain query param rather than a Ransack predicate because+ `available_to_seller` composes with `.or()`, so a `seller_id` filter widens+ back out to the whole condition instead of narrowing it.+- **A departed seller's rows are not released to the marketplace**+ (2026-09-08). `Spree::Seller#package_types` is `dependent: nil`, for the+ reason delivery methods are: a nil `seller_id` *is* the marketplace's row, so+ nullifying a seller's default box would hand the operator a second default+ and start quoting the seller's tare on first-party parcels. The seller is+ paranoid, so the rows keep pointing at a record that still resolves.++## Design Details++### Schema++One migration, `add_seller_to_spree_package_types`:++```ruby+add_reference :spree_package_types, :seller, null: true++remove_index :spree_package_types, name: 'index_spree_package_types_on_store_and_name'+remove_index :spree_package_types, name: 'index_spree_package_types_default_per_store', if_exists: true++# Two of each because a null seller_id inside a unique index constrains+# nothing for the rows where it is null (the marketplace's own).+unless mysql?+ add_index :spree_package_types, [:store_id, :name], unique: true,+ where: 'seller_id IS NULL', name: 'index_spree_package_types_marketplace_name'+ add_index :spree_package_types, [:store_id, :seller_id, :name], unique: true,+ where: 'seller_id IS NOT NULL', name: 'index_spree_package_types_seller_name'+ add_index :spree_package_types, :store_id, unique: true,+ where: '"default" = TRUE AND seller_id IS NULL', name: 'index_spree_package_types_marketplace_default'+ add_index :spree_package_types, [:store_id, :seller_id], unique: true,+ where: '"default" = TRUE AND seller_id IS NOT NULL', name: 'index_spree_package_types_seller_default'+else+ add_index :spree_package_types, [:store_id, :seller_id, :name], unique: true,+ name: 'index_spree_package_types_seller_name'+end+```++On MySQL the seller-row index still holds (no nulls in it) and the marketplace+rows fall back to the validation, which is already the arrangement for the+default flag there. No data migration: every existing row has a nil+`seller_id` and is, correctly, the marketplace's.++### Spree::PackageType++```ruby+belongs_to :seller, -> { with_deleted }, class_name: 'Spree::Seller', optional: true,+ inverse_of: :package_types++scope :first_party, -> { where(seller_id: nil) }+scope :for_seller, ->(seller) { where(seller_id: seller.respond_to?(:id) ? seller.id : seller) }+# Everything a seller may pack into: their own rows plus the marketplace's.+scope :available_to_seller, ->(seller) { seller.nil? ? first_party : for_seller(seller).or(first_party) }++validates :name, presence: true,+ uniqueness: { scope: spree_base_uniqueness_scope + [:store_id, :seller_id] }+```++The default-flag machinery (`demote_other_defaults`, `default_cannot_be_given_up`,+`ensure_not_default`) changes its unit from "same store" to "same store and+same seller". `Spree::Store#default_package_type` becomes+`where(default: true, seller_id: nil)` so the store's answer is the+marketplace's box, and `Spree::Seller` gains:++```ruby+has_many :package_types, class_name: 'Spree::PackageType', dependent: nil, inverse_of: :seller+has_one :default_package_type, -> { where(default: true) }, class_name: 'Spree::PackageType',+ dependent: nil, inverse_of: :seller+```++`whitelisted_ransackable_attributes` gains `seller_id` so the operator's list+can filter to one seller's rows or (blank) the marketplace's, as delivery+methods do.++### Which box quotes a package++`Stock::Package#default_package_type` reads, in order: the stock location's+seller's default box, then the store's. `#tare` and `#dimensions` already read+through that one method, so the EasyPost parcel and the internal calculators+change nothing.++```ruby+def default_package_type+ return @default_package_type if defined?(@default_package_type)++ @default_package_type = stock_location&.seller&.default_package_type || owner&.store&.default_package_type+end+```++### Which cartons a variant may reference++`Variant#carton_package_type_must_belong_to_store` widens to ownership: the+row must belong to the product's store and be either the marketplace's or the+variant's own seller's (`resolved_seller_id`). A seller's variant pointing at+another seller's carton is `:invalid`, the same error a foreign store's row+gets today.++The products import's `prepare_carton` resolves a seller's row through+`store.package_types.available_to_seller(seller)`, preferring the seller's own+row when both owners named a carton the same way. An operator's import is+unchanged.++### Permission++```ruby+register_resource(:package_types, group: :settings, audiences: %i[seller], subjects: -> {+ [Spree::PackageType]+})+```++`Spree::PackageType` leaves the `settings` subjects list. The admin controller+moves to `scoped_resource :package_types`; a secret key that held+`write_settings` for this endpoint needs `write_package_types` instead, which+is the unreleased-edge cost accepted above.++### API surface++- **Admin:** `/api/v3/admin/package_types` is unchanged in shape. The admin+ serializer gains `seller_id` and `seller_name` (as the delivery method and+ stock location serializers carry), and the list accepts `q[seller_id_eq]`.+ The operator reads and writes every row in the store, marketplace or+ seller's, and a row the operator creates is the marketplace's; `seller_id`+ is not writable there.+- **Seller:** `/api/v3/seller/package_types` CRUD rooted in+ `current_seller.package_types` for writes and `available_to_seller` for the+ listing, mirroring `Seller::DeliveryMethodsController#scope` /+ `#resource_scope` / `#find_resource`. The seller serializer carries+ `seller_id` so the panel can label a row "Mine" or "Marketplace". The+ permitted attributes are the admin controller's list; the store and seller+ come from the request, never the payload.+- **Seller onboarding:** the kind appears in `GET /seller/onboarding` like+ every other; nothing new on the wire.++### Spree::SellerRequirements::PackageType++```ruby+class PackageType < Spree::SellerRequirement+ def met_by_seller?(seller)+ box = seller.default_package_type+ box.present? && [box.length, box.width, box.height, box.weight].all? { |value| value.to_d.positive? }+ end+end+```++Registered in the engine's kind list and in `DEFAULT_KINDS` after+`DeliveryMethod`, so a store provisioned before it existed picks it up on the+next idempotent run. i18n under `seller_requirement_types.package_type`+("Shipping box" / "Tell us the size and weight of the box you ship orders in").+A `package_type_requirement` factory beside the others. `action_url` stays nil:+the work happens in the panel, and the panel's onboarding page maps the kind to+its settings route itself.++### Seller panel++- **Settings → Fulfillment → Package types**, beside Stock locations and+ Delivery methods. The operator's page+ (`routes/.../settings/package-types.tsx`) is the reference; its table, sheet+ form and schema move into shared pieces (`@spree/dashboard-core` for the+ page and form, `@spree/dashboard-ui` for anything presentational) that both+ panels mount, per the seller-panel rule in `CLAUDE.md`. The seller's table+ adds an owner column ("Mine" / "Marketplace") and hides the row actions on+ marketplace rows.+- **Carton picker for free.** The shared product form and the bulk variants+ dialog already read cartons through `client.packageTypes?.list(...)` and+ render nothing when the panel's client has no such entry. Registering+ `packageTypes: { list }` in `packages/seller-dashboard/src/api-client.ts`+ lights the existing picker up for sellers with no product-form change.+- **Onboarding page:** `panelRoute('package_type')` points at the new settings+ route.+- **`@spree/seller-sdk`:** a `packageTypes` resource (list, get, create,+ update, delete) and the generated `PackageType` type.++### Operator dashboard++The package types settings page gains an owner column and a seller filter,+matching the delivery methods page. Nothing else changes.++## Migration Path++1. **Core:** migration, `Spree::PackageType` ownership (association, scopes,+ uniqueness, per-owner default), `Spree::Seller` associations,+ `Spree::Store#default_package_type`, `Stock::Package#default_package_type`,+ the variant validation, the import's carton lookup. Model and service specs.+2. **API:** the `package_types` permission resource; admin serializer owner+ fields and Ransack filter; `Seller::PackageTypesController` and serializer;+ routes; type generation for both SDKs; the seller SDK resource; controller+ specs and one integration spec for the OpenAPI examples.+3. **Requirement:** the kind, registration, `DEFAULT_KINDS`, factory, i18n,+ examples in `seller_requirements_spec.rb`.+4. **Panels:** extract the operator's page into shared pieces; mount it in the+ seller panel with the owner column; wire `packageTypes` into the seller+ panel's client; map the kind on the onboarding page; operator owner column+ and filter. Translations in every locale of both panels. One seller-panel+ e2e spec: create a box, mark it default, see the requirement turn complete.+5. **Docs:** developer docs for seller package types and the requirement kind;+ cross-references from the three depending plans; OpenAPI regeneration.++No upgrade task. Existing rows are the marketplace's and stay so.++## Constraints on Current Work++- **Anything that needs "the box for this package" reads+ `Stock::Package#default_package_type`, never `store.default_package_type`+ directly.** The store's answer is the marketplace's box; only the package+ knows whose warehouse it left.+- **A seller-facing lookup of package types goes through+ `available_to_seller(seller)`; a seller write goes through+ `seller.package_types`.** `store.package_types` is the operator's view and+ hands a seller every other seller's rows.+- **MySQL enforces marketplace-row name uniqueness and the default flag through+ the model validations only.** Do not remove or weaken those validations on+ the grounds that "the index covers it"; on MySQL it does not.+- **A new seller-facing requirement kind is mapped in the panel's onboarding+ page** (`panelRoute`) when its work happens on a panel page; `action_url` is+ for flows the server knows about.+- **Secret keys reaching `/admin/package_types` need `read_package_types` /+ `write_package_types`**, not `settings`.++## Open Questions++None left. The four the draft raised — whether a seller may pack into the+marketplace's cartons, whether the requirement is provisioned by default, what+satisfies it, and what quotes a seller's package when they have no box — were+settled on 2026-09-08 and are recorded above under Key Decisions.++## References++- `docs/plans/6.0-b2b-wholesale-shipping.md` — `Spree::PackageType`, the+ carton chain, tare and dimensions on `Stock::Package`.+- `docs/plans/6.0-multi-vendor-marketplace.md` — Decision 13 (seller-owned+ delivery methods; who owns which delivery question), per-seller stock+ locations.+- `docs/plans/6.0-seller-onboarding-requirements.md` — kinds registry,+ `DEFAULT_KINDS`, the `DeliveryMethod` computed kind.+- `docs/plans/6.0-admin-rbac.md` — permission catalog, per-audience resources.+- `docs/plans/decisions.md` — 2026-09-05, "A CSV names its carton rather than+ referencing one".+- Precedents in code: `Spree::DeliveryMethod` (`seller_id`, `first_party`,+ `for_seller`, `available_to_seller`), `Spree::StockLocation` (`owned_by`),+ `Spree::Api::V3::Seller::DeliveryMethodsController` (shared rows read-only,+ writes rooted in the seller), `Spree::SellerRequirements::DeliveryMethod`.diff --git a/docs/plans/decisions.md b/docs/plans/decisions.mdindex d7b5c5a614..e633fd3c1e 100644--- a/docs/plans/decisions.md+++ b/docs/plans/decisions.md@@ -5102,3 +5102,34 @@ into a packaging change.**Constraint now:** a new named lookup in an importer resolves through thestore's own association.+## 2026-09-08 — Package types are the seller's to own; the marketplace's are shared vocabulary++Settled in `6.0-seller-package-types.md`.++**A package type follows the seller side of the marketplace plan's Decision+13.** "What kind of goods is this" (profiles, zones) is the marketplace's+question; "who ships it, how, and in what" is the seller's. Cartons and boxes+are the third clause, so `spree_package_types.seller_id` is nullable and a nil+owner is the marketplace's row, exactly as for delivery methods and stock+locations. The operator's rows are readable by every seller with no opt-in+flag — a carton is geometry and a tare, nothing to protect — while a seller's+rows are theirs alone. A package is quoted with its stock location's seller's+default box, falling back to the marketplace's.++**One default per owner needs two partial indexes, not one.** A nullable+column inside a unique index constrains nothing for the rows where it is+null, so "one default per (store, seller)" is enforced as one index for+marketplace rows and one for seller rows; the name index is split the same+way. MySQL, which has no partial indexes, relies on the model validations for+marketplace rows — do not weaken them on the grounds that an index covers it.++**A seller is asked for their box, never blocked without one.** A computed+`Spree::SellerRequirements::PackageType` kind, provisioned by default, is met+by a default box with all three dimensions and a weight recorded. It does not+count the marketplace's box: a seller on shared rates still posts their own+parcel.++**Constraint now:** code that needs "the box for this package" reads+`Stock::Package#default_package_type`, never `store.default_package_type`;+seller-facing reads go through `available_to_seller(seller)`, seller writes+through `seller.package_types`.diff --git a/packages/admin-sdk/src/types/generated/PackageType.ts b/packages/admin-sdk/src/types/generated/PackageType.tsindex 4c1b22b08c..87580ecacd 100644--- a/packages/admin-sdk/src/types/generated/PackageType.ts+++ b/packages/admin-sdk/src/types/generated/PackageType.ts@@ -1,4 +1,4 @@-// Typelizer digest 4b4a9fb0c10f0cd34286adc9028d9a7f+// Typelizer digest 31bc1472cda70ad696960c02a9051d2d//// DO NOT MODIFY: This file was automatically generated by Typelizer.@@ -18,6 +18,8 @@ interface PackageType {dimensions_unit: string;weight_unit: string;volume: string | null;+ seller_id: string | null;+ seller_name: string | null;}export default PackageType;diff --git a/packages/cli/src/generated/admin-spec.json b/packages/cli/src/generated/admin-spec.jsonindex 28d299b8f2..07cc054d65 100644--- a/packages/cli/src/generated/admin-spec.json+++ b/packages/cli/src/generated/admin-spec.json@@ -1 +1 @@-{"info":{"title":"Admin API","contact":{"name":"Spree Commerce","url":"https://spreecommerce.org","email":"[email protected]"},"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"},"paths":{"/api/v3/admin/auth/login":{"post":{"summary":"Login","tags":["Authentication"],"security":[{"api_key":[]}],"description":"Authenticates an admin user and returns a short-lived JWT access token.\nThe rotatable refresh token is set in an HttpOnly cookie — it is not\nincluded in the response body.\n\nThe `provider` field selects the authentication method. When omitted it\ndefaults to `email`, the built-in email/password login.\n\nTo authenticate against a third-party identity provider (Okta, Azure AD,\nGoogle Workspace SSO, a custom JWT issuer, SAML, etc.), send\n`{ \"provider\": \"<your_key>\", ... }` with the fields that provider\nrequires. The endpoint returns the same JWT regardless of which provider\nauthenticated the request. See\n[Custom API Authentication](https://spreecommerce.org/docs/developer/how-to/custom-api-authentication)\nfor the list of configured providers and their required fields.\n","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"login successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResponse"}}}},"401":{"description":"invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"title":"EmailPasswordLogin","description":"Built-in email/password authentication (default when `provider` is omitted).","type":"object","properties":{"provider":{"type":"string","enum":["email"],"default":"email"},"email":{"type":"string","format":"email"},"password":{"type":"string"}},"required":["email","password"]},{"title":"ProviderLogin","description":"Provider-dispatched login. The `provider` key selects a configured\nauthentication provider; the remaining fields are forwarded to it.\nRequired fields depend on the provider — see\n[Custom API Authentication](https://spreecommerce.org/docs/developer/how-to/custom-api-authentication).\n","type":"object","properties":{"provider":{"type":"string","description":"Registered provider key (anything other than `email`).","not":{"enum":["email"]}}},"required":["provider"],"additionalProperties":true}]}}}}}},"/api/v3/admin/auth/refresh":{"post":{"summary":"Refresh token","tags":["Authentication"],"security":[{"api_key":[]}],"description":"Exchanges the HttpOnly refresh-token cookie for a new access JWT and a\nrotated refresh token cookie. No request body or Authorization header\nis required — the cookie alone authenticates the call.\n","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"refresh successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResponse"}}}},"401":{"description":"missing or invalid refresh-token cookie","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/auth/logout":{"post":{"summary":"Logout","tags":["Authentication"],"security":[{"api_key":[]}],"description":"Revokes the refresh-token cookie, effectively logging the admin out.","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"logout successful"}}}},"/api/v3/admin/me":{"get":{"summary":"Get current admin user and permissions","tags":["Authentication"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the current admin user profile and a serialized list of permissions (CanCanCan rules). The SPA uses these to drive UI permission checks.","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"current admin user and permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeResponse"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update the current admin profile","tags":["Authentication"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Self-service update of the signed-in admin's own profile, such as their admin UI display language (`selected_locale`).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"profile updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"selected_locale":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"}}}}}}}},"/api/v3/admin/auth/password_resets":{"post":{"summary":"Request password reset","tags":["Authentication"],"security":[{"api_key":[]}],"description":"Requests a password reset email for an admin user. Always returns `202`\nwhether or not the email matches an account, to prevent enumeration.\n\n`redirect_url` is where the emailed link should point (the reset token\nis appended as a `token` query param). It must match one of the store's\nallowed origins — otherwise it is silently ignored and the server-side\ndefault is used. The email is delivered by Spree itself via the\n`admin_user.password_reset_requested` event; this event is never\nforwarded to webhook endpoints.\n","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"202":{"description":"reset requested","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"redirect_url":{"type":"string","description":"Must match an allowed origin of the store; ignored otherwise."}},"required":["email"]}}}}}},"/api/v3/admin/auth/password_resets/{id}":{"patch":{"summary":"Reset password","tags":["Authentication"],"security":[{"api_key":[]}],"description":"Consumes a password reset token (the `token` query param from the\nemailed link), sets the new password, and signs the admin in: the\nresponse carries a JWT access token and the rotatable refresh token is\nset in an HttpOnly cookie. The token is single-use — it invalidates as\nsoon as the password changes.\n","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","description":"The reset token from the emailed link","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"password reset","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResponse"}}}},"422":{"description":"invalid or expired token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"password":{"type":"string"},"password_confirmation":{"type":"string"}},"required":["password","password_confirmation"]}}}}}},"/api/v3/admin/auth/setup":{"get":{"summary":"Check first-run setup availability","tags":["Authentication"],"description":"Reports whether first-run setup is still available — true only while\nthe installation has no admin user. Unauthenticated; the dashboard\nlogin page uses it to offer the setup screen.\n","responses":{"200":{"description":"setup status","content":{"application/json":{}}}}},"post":{"summary":"Complete first-run setup","tags":["Authentication"],"description":"Creates the first admin account and adopts the seeded store, authorized\nby the one-time setup token printed at install time (rotate it with\n`bin/rails spree:setup:token`). Issues a JWT access token and a\nrefresh-token cookie exactly like login. Returns 404 once any admin\nuser exists — the flow is closed permanently after setup.\n","parameters":[],"responses":{"200":{"description":"setup completed","content":{"application/json":{}}},"404":{"description":"setup not available","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["setup_token","email","password","country_code"],"properties":{"setup_token":{"type":"string","description":"One-time token from the install output."},"email":{"type":"string","format":"email"},"password":{"type":"string"},"password_confirmation":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"store_name":{"type":"string"},"country_code":{"type":"string","description":"ISO 3166-1 alpha-2 country the store sells from. Determines the default market, the warehouse, the delivery zones and the currency."},"locale":{"type":"string","description":"Storefront locale. Defaults to the country's own language."},"currency":{"type":"string","description":"ISO 4217 currency. Defaults to the country's own currency — pass one only when the store prices in something else."}}}}}}}},"/api/v3/admin/auth/setup/countries":{"get":{"summary":"List countries for first-run setup","tags":["Authentication"],"description":"Countries the store can be set up in, each with the currency and\nofficial languages derived from it. Unauthenticated, because the setup\nscreen runs before any credential exists. Returns 404 once any admin\nuser exists.\n","responses":{"200":{"description":"countries","content":{"application/json":{}}}}}},"/api/v3/admin/allowed_origins":{"get":{"summary":"List allowed origins","tags":["Allowed Origins"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the CORS allowlist for the current store. Each entry is a\nbare `scheme://host[:port]` permitted to call the admin API from a\nbrowser. Backs the `Rack::Cors` allowlist and the CSRF boundary of\nthe admin cookie session (see\n`docs/plans/5.5-admin-auth-cookie-refresh.md`).\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[origin_cont]","in":"query","required":false,"description":"Filter by origin (contains)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"allowed origins found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AllowedOrigin"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create an allowed origin","tags":["Allowed Origins"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds an origin to the admin CORS allowlist. The value must be a bare\n`scheme://host[:port]` (no path, query, or fragment) and use `http` or\n`https`.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"allowed origin created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AllowedOrigin"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"origin":{"type":"string"}},"required":["origin"]}}}}}},"/api/v3/admin/allowed_origins/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Allowed origin ID","schema":{"type":"string"}}],"get":{"summary":"Get an allowed origin","tags":["Allowed Origins"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single allowed origin by prefixed ID.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"allowed origin found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AllowedOrigin"}}}},"404":{"description":"allowed origin not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update an allowed origin","tags":["Allowed Origins"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an existing allowed origin.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"allowed origin updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AllowedOrigin"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"origin":{"type":"string"}}}}}}},"delete":{"summary":"Delete an allowed origin","tags":["Allowed Origins"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes an origin from the admin CORS allowlist. After deletion the\nadmin SPA running at that origin will no longer be able to call the\nadmin API from a browser.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"allowed origin deleted"}}}},"/api/v3/admin/api_keys":{"get":{"summary":"List API keys","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns publishable and secret API keys for the current store. Secret keys are listed by `token_prefix` only — the plaintext token is delivered exactly once on create.\n\n**Required scope:** `read_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"API keys found","content":{"application/json":{}}}}},"post":{"summary":"Create an API key","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a publishable or secret API key. The plaintext token is included in the response **once** for secret keys; publishable keys expose their token on every read since they are intended for client-side use.\n\n**Required scope:** `write_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"secret key created — plaintext token returned once","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name","key_type"],"properties":{"name":{"type":"string"},"key_type":{"type":"string","enum":["publishable","secret"]},"scopes":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/api_keys/{id}":{"get":{"summary":"Show an API key","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"API key found","content":{"application/json":{}}}}},"patch":{"summary":"Update an API key","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Renames a key. `key_type` and `scopes` are fixed at creation — to change a key's authority, create a new key and revoke the old one.\n\n**Required scope:** `write_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"API key renamed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"}}}}}}},"delete":{"summary":"Delete an API key","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"API key deleted"}}}},"/api/v3/admin/api_keys/current":{"get":{"summary":"Describe the current API key","tags":["API Keys"],"security":[{"api_key":[]}],"description":"Returns the secret key that authenticated this request, including its live scopes. Useful to confirm a key's real, current authority. Only secret-key principals have a single key to describe.\n\n**Required scope:** none — any key can describe itself (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"current API key","content":{"application/json":{}}}}}},"/api/v3/admin/api_keys/{id}/revoke":{"patch":{"summary":"Revoke an API key","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Marks the key revoked. Future requests using its token will fail; the row is preserved for audit.\n\n**Required scope:** `write_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"API key revoked","content":{"application/json":{}}}}}},"/api/v3/admin/categories":{"get":{"summary":"List categories","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of the store's categories (manual hierarchical taxons; rule-based collections are excluded).\n\n**Required scope:** `read_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., children, parent, ancestors).","schema":{"type":"string"}}],"responses":{"200":{"description":"categories found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a category. Nests under the parent when parent_id is given, otherwise creates a top-level category.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"category created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Category"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"parent_id":{"type":"string","description":"Prefixed ID of the parent category"},"description":{"type":"string"},"permalink":{"type":"string"},"meta_title":{"type":"string"},"meta_description":{"type":"string"},"meta_keywords":{"type":"string"}},"required":["name"]}}}}}},"/api/v3/admin/categories/{id}":{"get":{"summary":"Get a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single category by ID.\n\n**Required scope:** `read_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., children, parent, ancestors).","schema":{"type":"string"}}],"responses":{"200":{"description":"category found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Category"}}}},"404":{"description":"category not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a category.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"200":{"description":"category updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Category"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"parent_id":{"type":"string","description":"Prefixed ID of the parent category"},"description":{"type":"string"},"permalink":{"type":"string"},"meta_title":{"type":"string"},"meta_description":{"type":"string"},"meta_keywords":{"type":"string"}}}}}}},"delete":{"summary":"Delete a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a category and its descendants.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"204":{"description":"category deleted"}}}},"/api/v3/admin/categories/{id}/reposition":{"patch":{"summary":"Reposition a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Moves a category to a new parent and/or index within the tree.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"200":{"description":"category repositioned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Category"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"new_parent_id":{"type":"string","description":"Prefixed ID of the new parent (omit for top level)"},"new_position":{"type":"integer","description":"0-based index among the new parent's children"}},"required":["new_position"]}}}}}},"/api/v3/admin/categories/{category_id}/products":{"get":{"summary":"List category products","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Products classified under the category, ordered by their classification position.\n\n**Required scope:** `read_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"category_id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"200":{"description":"products found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Add products to a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Classifies products under the category in bulk (appended to the end). Already-classified products are skipped; the count reports what was added.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"category_id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"201":{"description":"products added","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}},"delete":{"summary":"Remove products from a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes products from the category's manual classification in bulk. Ids that are not classified are ignored; the count reports what was removed.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"category_id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"200":{"description":"products removed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}}},"/api/v3/admin/categories/{category_id}/products/{id}/reposition":{"patch":{"summary":"Reposition a category product","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Moves a product to a new index among the category's products.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"category_id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"204":{"description":"product repositioned"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"new_position":{"type":"integer","description":"0-based index among the category's products"}},"required":["new_position"]}}}}}},"/api/v3/admin/channels":{"get":{"summary":"List channels","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the channels configured for the current store.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"channels found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new channel on the current store. `code` is normalized to a\nURL-safe slug (`Point of Sale` → `point-of-sale`); when omitted it's\nderived from `name`.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"channel created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"code":{"type":"string","description":"Slug — auto-derived from `name` when blank."},"active":{"type":"boolean","default":true},"default":{"type":"boolean","default":false},"preferred_order_routing_strategy":{"type":"string","nullable":true,"description":"Routing strategy class name. `null` inherits the store setting."},"preferred_storefront_access":{"type":"string","nullable":true,"enum":["public","prices_hidden","login_required"],"description":"Anonymous-visitor access posture. `null` inherits the store setting."},"preferred_guest_checkout":{"type":"boolean","nullable":true,"description":"Whether guests can check out without an account. `null` inherits the store setting."}}}}}}}},"/api/v3/admin/channels/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"channel found","content":{"application/json":{}}}}},"patch":{"summary":"Update a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"channel updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"code":{"type":"string"},"active":{"type":"boolean"},"default":{"type":"boolean"},"preferred_order_routing_strategy":{"type":"string","nullable":true,"description":"Routing strategy class name. `null` inherits the store setting."},"preferred_storefront_access":{"type":"string","nullable":true,"enum":["public","prices_hidden","login_required"],"description":"Anonymous-visitor access posture. `null` inherits the store setting."},"preferred_guest_checkout":{"type":"boolean","nullable":true,"description":"Whether guests can check out without an account. `null` inherits the store setting."}}}}}}},"delete":{"summary":"Delete a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"channel deleted"}}}},"/api/v3/admin/channels/{id}/add_products":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Publish products on a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Publishes the listed products on this channel. Idempotent — re-publishing\nan already-published product updates its publication window. Products from\nsibling stores are silently dropped.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products published","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["product_ids"],"properties":{"product_ids":{"type":"array","items":{"type":"string"}},"published_at":{"type":"string","format":"date-time","nullable":true,"description":"When the publications go live. `null` means immediately."},"unpublished_at":{"type":"string","format":"date-time","nullable":true,"description":"When the publications come down. `null` means never."}}}}}}}},"/api/v3/admin/channels/{id}/remove_products":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Unpublish products from a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Unpublishes the listed products from this channel.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products unpublished","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["product_ids"],"properties":{"product_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/channels/{channel_id}/order_routing_rules":{"parameters":[{"name":"channel_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List order routing rules for a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the channel's routing rules in priority order. The rules engine walks them top-down; see the Order Routing guide.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"rules found","content":{"application/json":{}}}}},"post":{"summary":"Create an order routing rule on a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a rule to the channel's routing list. The `type` is the wire shorthand from `GET /order_routing_rules/types` (e.g. `preferred_location`). Omitting `position` appends the rule at the end of the list. Each rule kind can appear at most once per channel — a duplicate `type` is rejected with a validation error.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"rule created","content":{"application/json":{}}},"422":{"description":"unknown rule type","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"active":{"type":"boolean"},"position":{"type":"integer"},"preferences":{"type":"object","additionalProperties":true}},"required":["type"]}}}}}},"/api/v3/admin/channels/{channel_id}/order_routing_rules/{id}":{"parameters":[{"name":"channel_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Update an order routing rule","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a rule's `active` flag, `position` (the list reorders around it), or `preferences`. The rule kind cannot be changed — delete and re-create instead.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"rule updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"active":{"type":"boolean"},"position":{"type":"integer"},"preferences":{"type":"object","additionalProperties":true}}}}}}},"delete":{"summary":"Delete an order routing rule","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"rule deleted"}}}},"/api/v3/admin/order_routing_rules/types":{"get":{"summary":"List available order routing rule types","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Enumerates the registered rule kinds with their labels, descriptions and preference schemas — drives the \"Add rule\" picker in the admin dashboard. Plugins extend the list by registering `Spree::OrderRoutingRule` subclasses via `Spree.order_routing.rules`.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"types found","content":{"application/json":{}}}}}},"/api/v3/admin/custom_field_definitions":{"get":{"summary":"List custom field definitions","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all defined custom fields. Filter by `?q[resource_type_eq]=Spree::Product` to narrow to one parent type.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand. Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., key,label,field_type). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"definitions returned","content":{"application/json":{}}}}},"post":{"summary":"Create a custom field definition","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"definition created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["key","field_type","resource_type"],"properties":{"namespace":{"type":"string","description":"Defaults to `custom`"},"key":{"type":"string"},"label":{"type":"string","description":"Human-readable name; defaults to titleized `key`"},"field_type":{"type":"string","description":"Custom field type identifier (one of the registered field-type class names)."},"resource_type":{"type":"string","description":"Owner class, e.g. `Spree::Product`"},"storefront_visible":{"type":"boolean","description":"When false, the definition is admin-only and never exposed in the Store API"},"searchable":{"type":"boolean","description":"When true, values are included in storefront product text search"},"sortable":{"type":"boolean","description":"When true, storefront product listings can sort by this field"}}}}}}}},"/api/v3/admin/custom_field_definitions/{id}":{"get":{"summary":"Show a custom field definition","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand. Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., key,label,field_type). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"definition found","content":{"application/json":{}}}}},"patch":{"summary":"Update a custom field definition","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"definition updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string"},"storefront_visible":{"type":"boolean"},"searchable":{"type":"boolean"},"sortable":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a custom field definition","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes the definition and cascades to all custom field values referencing it.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"definition deleted"}}}},"/api/v3/admin/customer_groups":{"get":{"summary":"List customer groups","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the customer groups configured for the current store. Groups\nsegment customers for targeted promotions (see the `customer_group`\npromotion rule) and reporting. The list endpoint never embeds the\nmember list — fetch a single group with `?expand=customers` if you\nneed them inline, or query `/admin/customers?customer_group_id_in=…`\nfor paginated membership.\n\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"customer groups found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CustomerGroup"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a customer group","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a customer group in the current store. `customer_ids` is\noptional; when present, customers are attached at create time.\nPass prefixed IDs (e.g. `cus_…`) — the server decodes them\nautomatically.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"customer group created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerGroup"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"customer_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/customer_groups/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Customer group prefixed ID","schema":{"type":"string"}}],"get":{"summary":"Get a customer group","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single customer group. Pass `?expand=customers` to embed\nthe full member list inline (recommended only for single-record\nreads — embed cost scales with membership size).\n\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed. Supported: `customers`.","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"customer group with embedded customers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerGroup"}}}},"404":{"description":"customer group not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a customer group","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates name, description, or membership. `customer_ids` is a\nfull-set replacement — the server reconciles the membership to\nmatch the array, adding new IDs and removing ones not present.\nSend `customer_ids: []` to clear all members.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customer group updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerGroup"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"customer_ids":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a customer group","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the group. Member users are not deleted; their `customer_group_users` rows are dropped.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"customer group deleted"}}}},"/api/v3/admin/customers/{id}/export":{"get":{"summary":"Export a customer's personal data","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns everything the store holds about this customer, for answering a\nGDPR right-of-access request (Art. 15) that reached the merchant\ndirectly.\n\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customer data","content":{"application/json":{"schema":{"type":"object","properties":{"account":{"type":"object"},"marketing_consent":{"type":"object"},"consent_records":{"type":"array","items":{"type":"object"}},"addresses":{"type":"array","items":{"type":"object"}},"orders":{"type":"array","items":{"type":"object"}},"exported_at":{"type":"string"}}}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/customers/{id}/anonymize":{"post":{"summary":"Erase a customer's personal data","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Carries out a GDPR right-to-erasure request (Art. 17). Personal data is\nreplaced across the account, its addresses, the address snapshots on\npast orders, saved cards, connected identities and live sessions.\n\nOrders, payments and tax records are kept — they carry their own\nretention obligation — with the personal details removed. The country,\nstate and a truncated postal code survive on order addresses so the tax\njurisdiction of a past sale stays provable.\n\nIrreversible.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customer anonymized","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"anonymized":{"type":"boolean"},"anonymized_at":{"type":"string","nullable":true}}}}}}}}},"/api/v3/admin/customers/{customer_id}/addresses":{"get":{"summary":"List customer addresses","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the customer's saved addresses.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., country, state). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., first_name,last_name,address1,city). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"addresses found","content":{"application/json":{}}}}},"post":{"summary":"Create a customer address","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a new address to the customer's address book. Pass `is_default_billing: true` or `is_default_shipping: true` to set as the default — the previous default loses its flag in the same transaction.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"address created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"country_code":{"type":"string","description":"ISO-2 country code (e.g. US)"},"state_code":{"type":"string","description":"State/province abbreviation (e.g. NY)"},"phone":{"type":"string"},"company":{"type":"string"},"label":{"type":"string"},"is_default_billing":{"type":"boolean"},"is_default_shipping":{"type":"boolean"}}}}}}}},"/api/v3/admin/customers/{customer_id}/addresses/{id}":{"patch":{"summary":"Update a customer address","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a customer address.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"address updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"city":{"type":"string"},"is_default_billing":{"type":"boolean"},"is_default_shipping":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a customer address","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes the address. If it was a default, the customer loses that default (no auto-promotion).\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"address deleted"}}}},"/api/v3/admin/customers/{customer_id}/credit_cards":{"get":{"summary":"List customer credit cards","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the customer's saved credit cards. Useful for off-session admin charges via `POST /admin/orders/:id/payments { source_id }`.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., payment_method). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., brand,last4,month,year). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"credit cards found","content":{"application/json":{}}}}}},"/api/v3/admin/customers/{customer_id}/credit_cards/{id}":{"get":{"summary":"Show a customer credit card","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a saved credit card by ID.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., payment_method). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., brand,last4,month,year). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"credit card found","content":{"application/json":{}}}}},"delete":{"summary":"Delete a customer credit card","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a saved credit card.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"credit card deleted"}}}},"/api/v3/admin/customers/{customer_id}/store_credits":{"get":{"summary":"List customer store credits","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns store credits issued to the customer.\n\n**Required scope:** `read_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., store, created_by). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., amount,amount_used,memo,currency). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"store credits found","content":{"application/json":{}}}}},"post":{"summary":"Issue a store credit to a customer","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"`created_by` is set automatically from the authenticated admin.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"store credit created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"string"},"currency":{"type":"string"},"memo":{"type":"string"}}}}}}}},"/api/v3/admin/customers/{customer_id}/store_credits/{id}":{"patch":{"summary":"Update a store credit","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Update memo / amount. The amount can only be changed if `amount_used == 0`.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"store credit updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string"},"memo":{"type":"string"}}}}}}},"delete":{"summary":"Delete a store credit","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes an unused store credit (amount_used == 0). Returns 422 otherwise.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"store credit deleted"}}}},"/api/v3/admin/customers":{"get":{"summary":"List customers","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of customers. Supports Ransack search/filters.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"q[search]","in":"query","required":false,"description":"Email + name full-text-ish search","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., addresses, store_credits). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., email,first_name,last_name). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"customers found","content":{"application/json":{}}}}},"post":{"summary":"Create a customer","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a customer. No welcome email is sent automatically.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"customer created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"phone":{"type":"string"},"accepts_email_marketing":{"type":"boolean"},"internal_note":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object"}}}}}}}},"/api/v3/admin/customers/{id}":{"get":{"summary":"Show a customer","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns full customer details including computed order stats (orders_count, total_spent, last_order_completed_at).\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Customer ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations: addresses, orders, store_credits, default_billing_address, default_shipping_address","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., email,first_name,last_name). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"customer found","content":{"application/json":{}}}}},"patch":{"summary":"Update a customer","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates customer attributes. `tags` replaces the full set.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customer updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"phone":{"type":"string"},"accepts_email_marketing":{"type":"boolean"},"internal_note":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object"}}}}}}},"delete":{"summary":"Delete a customer","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a customer. Returns 422 if the customer has any orders.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"customer deleted"}}}},"/api/v3/admin/customers/bulk_add_to_groups":{"post":{"summary":"Bulk-add customers to groups","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Attaches each customer in `ids` to every group in `customer_group_ids`.\nIdempotent — customers already in a group are skipped server-side.\nGroups from sibling stores are silently ignored. Returns counts of\ncustomers and groups that were processed (post store-scoping).\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customers added to groups","content":{"application/json":{"schema":{"type":"object","properties":{"customer_count":{"type":"integer"},"customer_group_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","customer_group_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"customer_group_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/customers/bulk_remove_from_groups":{"post":{"summary":"Bulk-remove customers from groups","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Detaches each customer in `ids` from every group in `customer_group_ids`.\nNo-op for non-members. Groups from sibling stores are silently ignored.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customers removed from groups","content":{"application/json":{"schema":{"type":"object","properties":{"customer_count":{"type":"integer"},"customer_group_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","customer_group_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"customer_group_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/customers/bulk_add_tags":{"post":{"summary":"Bulk-add tags to customers","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds each tag name in `tags` to every customer in `ids`. Tags are\nupserted by name; re-adding an existing tag is a no-op.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"tags added","content":{"application/json":{"schema":{"type":"object","properties":{"customer_count":{"type":"integer"},"tag_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","tags"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/customers/bulk_remove_tags":{"post":{"summary":"Bulk-remove tags from customers","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes each tag name in `tags` from every customer in `ids`. No-op\nfor customers that don't carry the tag.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"tags removed","content":{"application/json":{"schema":{"type":"object","properties":{"customer_count":{"type":"integer"},"tag_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","tags"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/exports":{"get":{"summary":"List exports","tags":["Exports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns CSV exports queued or completed for the current store. Polled by the admin SPA to detect when an export finishes (`done: true`).\n\n**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"exports found","content":{"application/json":{}}}}},"post":{"summary":"Create an export","tags":["Exports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Queues a CSV export. The `type` selects the dataset; `search_params` is an\noptional Ransack query (same shape used by the `q[...]` params on list endpoints)\nthat filters which records are exported. Pass `record_selection: \"all\"` to\nclear the filter server-side and export everything in scope.\n\nGeneration is asynchronous. Poll `GET /admin/exports/{id}` until `done` is `true`,\nthen redirect the browser to `download_url` to fetch the file.\n\n\n**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"export queued","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["products","orders","customers","product_translations","gift_cards","coupon_codes","newsletter_subscribers","price_list_prices"]},"record_selection":{"type":"string","enum":["filtered","all"],"description":"Set to \"all\" to ignore search_params and export everything in scope."},"search_params":{"type":"object","description":"Ransack query hash. Same predicates accepted by the list endpoint. A `price_list_prices` export requires `price_list_id_eq` naming a price list of the current store, and refuses `record_selection: \"all\"`.","additionalProperties":true},"results_url":{"type":"string","description":"Absolute URL of your admin exports view; the export-done email uses it as the download button target. Only honored when it matches one of the store's configured allowed origins."}}}}}}}},"/api/v3/admin/exports/{id}":{"get":{"summary":"Show an export","tags":["Exports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns export status. While `done` is `false`, the SPA continues polling.\n\n**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"export found","content":{"application/json":{}}}}},"delete":{"summary":"Delete an export","tags":["Exports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes the export and purges its attachment.\n\n**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"export deleted"}}}},"/api/v3/admin/exports/{id}/download":{"get":{"summary":"Download an export","tags":["Exports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Streams the exported CSV with `Content-Disposition: attachment`. Returns 422 with `code: export_not_ready` while `done` is still `false`. The endpoint is JWT/API-key protected, so SPA clients must fetch it (with `Authorization` header) and trigger the browser download via a Blob URL — a top-level navigation cannot carry the JWT.\n\n**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"CSV file","content":{"application/json":{},"text/csv":{"schema":{"type":"string","format":"binary"}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments":{"get":{"summary":"List fulfillments","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all shipments for an order.\n\n**Required scope:** `read_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., inventory_units, stock_location, shipping_rates). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., number,status,tracking,cost). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillments found","content":{"application/json":{}}}}},"post":{"summary":"Create a fulfillment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Manually creates a fulfillment on a completed order, bypassing order routing — for example to mirror a shipment handled by an external carrier or 3PL. Moves the requested line item quantities out of their current fulfillments; when `items` is omitted, every not-yet-shipped unit is moved. Pass `status: 'shipped'` to register an already-shipped fulfillment (fires shipped webhooks and freezes cost/carrier). When `delivery_method_id` is omitted, the fulfillment inherits the delivery method and cost of the source fulfillment(s) it fully drains — keeping the order total unchanged; partially drained splits get no carrier when shipped, and pending fulfillments are otherwise (re)priced by the standard rate engine, which selects the lowest-cost available rate. Pass `cost` to set an explicit shipping cost instead (e.g. the 3PL price) — note this changes the order total and payment state, and is guaranteed to persist only with `status: 'shipped'` (pending fulfillments are re-priced by the rate engine).\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"fulfillment created","content":{"application/json":{}}},"422":{"description":"order not completed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["stock_location_id"],"properties":{"stock_location_id":{"type":"string","description":"Stock location the fulfillment ships from"},"tracking":{"type":"string","description":"Carrier tracking number, or a full https:// tracking link — a full URL is served back as tracking_url unchanged instead of being templated into the delivery method tracking URL"},"delivery_method_id":{"type":"string","description":"Delivery method (carrier) to attach as the selected rate. Defaults to the delivery method of the fully drained source fulfillment(s)"},"cost":{"type":"string","description":"Explicit shipping cost. Defaults to the summed cost of the fully drained source fulfillment(s), which keeps the order total unchanged; an explicit cost changes the order total and payment state. Guaranteed to persist only with status: 'shipped' — pending fulfillments are re-priced by the rate engine"},"status":{"type":"string","enum":["shipped"],"description":"Pass 'shipped' to register the fulfillment as already shipped"},"items":{"type":"array","description":"Line item quantities to fulfill. Omit to fulfill every not-yet-shipped unit.","items":{"type":"object","required":["item_id","quantity"],"properties":{"item_id":{"type":"string","description":"Line item ID"},"quantity":{"type":"integer"}}}},"metadata":{"type":"object","additionalProperties":true}}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}":{"get":{"summary":"Show a shipment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns details of a specific shipment.\n\n**Required scope:** `read_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., inventory_units, stock_location, shipping_rates). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., number,status,tracking,cost). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"shipment found","content":{"application/json":{}}}}},"patch":{"summary":"Update a shipment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a fulfillment (tracking, delivery rate).\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"shipment updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tracking":{"type":"string","description":"Carrier tracking number, or a full https:// tracking link served back as tracking_url unchanged"},"selected_delivery_rate_id":{"type":"string","description":"Delivery rate ID (dr_...) to select"}}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/fulfill":{"patch":{"summary":"Fulfill a fulfillment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Marks a fulfillment as fulfilled.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillment fulfilled","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/mark_delivered":{"patch":{"summary":"Mark a fulfillment delivered","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Records that the customer received the goods. Only a fulfilled shipment can be marked delivered.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillment delivered","content":{"application/json":{}}},"422":{"description":"fulfillment has not shipped","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"delivered_at":{"type":"string","format":"date-time","description":"When the goods arrived. Defaults to now."},"notify_customer":{"type":"boolean","description":"Whether the customer gets a delivery notification. Defaults to true."}}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/cancel":{"patch":{"summary":"Cancel a fulfillment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Cancels a fulfillment.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillment canceled","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/split":{"patch":{"summary":"Split a fulfillment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Transfers items from this shipment to a new shipment at a different stock location.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillment split","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["variant_id","quantity"],"properties":{"variant_id":{"type":"string","description":"Variant ID"},"quantity":{"type":"integer"},"stock_location_id":{"type":"string","description":"Target stock location ID"}}}}}}}},"/api/v3/admin/gift_card_batches":{"get":{"summary":"List gift card batches","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the gift card batches issued by the current store. Each batch\ngroups the cards generated together for a campaign or bulk-issuance\n— the cards themselves live under `/admin/gift_cards` and reference\nthe batch via `gift_card_batch_id`.\n\n\n**Required scope:** `read_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Records per page","schema":{"type":"integer"}},{"name":"q[prefix_cont]","in":"query","required":false,"description":"Filter by prefix (contains)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending.","schema":{"type":"string"}}],"responses":{"200":{"description":"gift card batches found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/GiftCardBatch"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a gift card batch","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Issues a batch of gift cards in a single call. The server generates\n`codes_count` cards inline for small batches (configurable via\n`Spree.config.gift_card_batch_web_limit`, default 500) or enqueues\na background job for larger ones. Each card's code is the batch\n`prefix` followed by random hex.\n\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"gift card batch created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCardBatch"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["prefix","amount","codes_count"],"properties":{"prefix":{"type":"string","description":"Lowercased and prepended to every generated code."},"amount":{"type":"string","description":"Decimal amount per card, greater than zero."},"currency":{"type":"string","description":"ISO 4217 currency code. Defaults to the store currency."},"codes_count":{"type":"integer","description":"Number of cards to generate. Capped at `gift_card_batch_limit`."},"expires_at":{"type":"string","nullable":true}}}}}}}},"/api/v3/admin/gift_card_batches/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Gift card batch prefixed ID","schema":{"type":"string"}}],"get":{"summary":"Get a gift card batch","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single batch.\n\n**Required scope:** `read_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"gift card batch found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCardBatch"}}}},"404":{"description":"gift card batch not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/gift_cards":{"get":{"summary":"List gift cards","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the gift cards issued by the current store. Filter by\n`q[code_cont]` for code search, `q[customer_id_eq]` for cards issued\nto a specific customer, or `q[status_eq]` for status filtering.\n\n\n**Required scope:** `read_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[code_cont]","in":"query","required":false,"description":"Filter by gift card code (contains)","schema":{"type":"string"}},{"name":"q[status_eq]","in":"query","required":false,"description":"Filter by status (active, redeemed, partially_redeemed, canceled)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"gift cards found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/GiftCard"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a gift card","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Issues a gift card scoped to the current store. The code is\nauto-generated when omitted. `currency` defaults to the store's\nconfigured currency. Pass `customer_id` (prefixed ID) to attach the\ncard to a specific customer.\n\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"gift card created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCard"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["amount"],"properties":{"amount":{"type":"string","description":"Decimal amount, greater than zero."},"currency":{"type":"string","description":"ISO 4217 currency code. Defaults to the store currency."},"code":{"type":"string","description":"Optional caller-supplied code. Auto-generated when omitted."},"expires_at":{"type":"string","description":"ISO 8601 date.","nullable":true},"customer_id":{"type":"string","description":"Optional customer prefixed ID.","nullable":true}}}}}}}},"/api/v3/admin/gift_cards/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Gift card prefixed ID","schema":{"type":"string"}}],"get":{"summary":"Get a gift card","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single gift card.\n\n**Required scope:** `read_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"gift card found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCard"}}}},"404":{"description":"gift card not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a gift card","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an active gift card's editable attributes. Redeemed or\npartially-redeemed cards cannot be edited.\n\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"gift card updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCard"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string"},"expires_at":{"type":"string","nullable":true},"customer_id":{"type":"string","nullable":true}}}}}}},"delete":{"summary":"Delete a gift card","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes an unused gift card. Cards that have been redeemed or\npartially redeemed cannot be deleted and return 422.\n\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"gift card deleted"},"422":{"description":"redeemed gift card cannot be deleted","content":{"application/json":{}}}}}},"/api/v3/admin/imports":{"get":{"summary":"List imports","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns CSV imports queued or completed for the current store.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"imports found","content":{"application/json":{}}}}},"post":{"summary":"Create an import","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Queues a CSV import. Upload the file first via `POST /api/v3/admin/direct_uploads`\nand pass the returned `signed_id` as `attachment`. On success the import is in the\n`mapping` state and the response carries the mapping payload: `schema_fields`\n(the canonical columns for the type), `csv_headers`, a `sample_row`, and the\nauto-assigned `mappings`.\n\nAdjust mappings if needed, then call `PATCH /admin/imports/{id}/complete_mapping`\nto start processing. Poll `GET /admin/imports/{id}` while `status` is\n`completed_mapping`/`processing`; terminal statuses are `completed` and `failed`.\n\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"import created in mapping state","content":{"application/json":{}}},"422":{"description":"unknown import type","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["type","attachment"],"properties":{"type":{"type":"string","enum":["products","customers","product_translations","price_list_prices"]},"price_list_id":{"type":"string","description":"For `price_list_prices` imports: the price list the rows are merged into. Must belong to the current store."},"attachment":{"type":"string","description":"ActiveStorage signed blob id from POST /api/v3/admin/direct_uploads."},"preferred_delimiter":{"type":"string","enum":[",",";","|","\t"],"description":"CSV column separator. Defaults to a comma."},"results_url":{"type":"string","description":"Absolute URL of your admin imports view; the import-done email links back to it with `?import=<id>` appended. Only honored when it matches one of the store's configured allowed origins."}}}}}}}},"/api/v3/admin/imports/template":{"get":{"summary":"Download an import template","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a CSV header row for the given import type, including the custom field columns available for the model.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"type","in":"query","required":true,"description":"Registered import type, e.g. products.","schema":{"type":"string"}}],"responses":{"200":{"description":"CSV template","content":{"application/json":{},"text/csv":{"schema":{"type":"string","format":"binary"}}}}}}},"/api/v3/admin/imports/example":{"get":{"summary":"Download an example import file","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Redirects to a populated example CSV for the given import type — the same sample data `rake spree:load_sample_data` uses, pinned to the installed Spree version. Returns 404 for a type that ships no example file.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"type","in":"query","required":true,"description":"Registered import type, e.g. products.","schema":{"type":"string"}}],"responses":{"302":{"description":"Redirect to the example CSV"}}}},"/api/v3/admin/imports/{id}":{"get":{"summary":"Show an import","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns import status and row counters. The admin dashboard polls this endpoint while `status` is `completed_mapping` or `processing`; `rows_count`, `completed_rows_count` and `failed_rows_count` drive the progress bar. The mapping payload (`csv_headers`, `sample_row`) is only present while `status` is `mapping`.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"import found","content":{"application/json":{}}}}},"delete":{"summary":"Delete an import","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes the import, its rows and the uploaded file. Returns 422 while the import is being processed.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"import deleted"}}}},"/api/v3/admin/imports/{id}/download":{"get":{"summary":"Download the originally uploaded file","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Streams the CSV exactly as it was uploaded — the audit trail for what was imported. JWT/API-key protected; SPA clients fetch it with the Authorization header and trigger the browser download via a Blob URL.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"CSV file","content":{"application/json":{},"text/csv":{"schema":{"type":"string","format":"binary"}}}}}}},"/api/v3/admin/imports/{id}/complete_mapping":{"patch":{"summary":"Complete mapping and start processing","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Applies the submitted column mappings, then starts row processing. Omit `mappings`\nto accept the auto-assigned ones from the create response. Returns 422 when a\nrequired schema field is left unmapped (`details.missing_required_fields`) or a\nfile column is assigned twice.\n\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"mapping completed, processing queued","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"mappings":{"type":"array","description":"Column assignments to apply before starting. `file_column: null` unmaps a field.","items":{"type":"object","required":["schema_field"],"properties":{"schema_field":{"type":"string"},"file_column":{"type":"string","nullable":true}}}}}}}}}}},"/api/v3/admin/imports/{id}/retry_failed_rows":{"patch":{"summary":"Retry failed rows","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Re-processes the rows that failed. The import re-enters `processing`; poll `GET /admin/imports/{id}` until it completes again. Returns 422 when the import is not `completed` or has no failed rows.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"retry queued","content":{"application/json":{}}}}}},"/api/v3/admin/imports/{import_id}/rows":{"get":{"summary":"List import rows","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Paginated rows of an import — the failure report. Filter with `q[status_eq]=failed` to list only rows that could not be imported; each row carries the raw CSV `data` and its `validation_errors`.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"import_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"q[status_eq]","in":"query","required":false,"description":"Filter rows by status: pending, processing, completed, failed.","schema":{"type":"string"}}],"responses":{"200":{"description":"rows found","content":{"application/json":{}}}}}},"/api/v3/admin/markets":{"get":{"summary":"List markets","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the markets configured for the current store. Markets are\nstore-scoped and ordered by `position` (an `acts_as_list` column —\nupdate the order via `PATCH /markets/{id}` with `position`).\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed. Supported: `countries`.","schema":{"type":"string"}}],"responses":{"200":{"description":"markets found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Market"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a market","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new market for the current store.\n\n- `country_codes` accepts 2-letter ISO country codes (e.g. `[\"DE\", \"FR\"]`);\n the market must contain at least one country. Unknown codes are\n silently dropped.\n- `supported_locales` accepts an array of locale codes; the\n `default_locale` is always implicitly included.\n- Setting `default: true` automatically demotes the previous default\n market in the store.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"market created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Market"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"currency":{"type":"string","description":"ISO 4217 currency code."},"default_locale":{"type":"string","description":"IETF locale tag used as the market default."},"supported_locales":{"type":"array","items":{"type":"string"},"description":"Locale codes available in this market. The default is always implicitly included."},"tax_inclusive":{"type":"boolean","default":false,"description":"Display prices with tax included."},"default":{"type":"boolean","default":false,"description":"Setting to true demotes the previous default."},"position":{"type":"integer","description":"Sort order within the store; lower = first."},"country_codes":{"type":"array","items":{"type":"string"},"description":"2-letter ISO country codes assigned to this market. At least one is required."}},"required":["name","currency","default_locale","country_codes"]}}}}}},"/api/v3/admin/markets/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a market","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"market found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Market"}}}},"404":{"description":"market not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a market","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an existing market. Pass `country_codes` to replace the\nmarket's country list (full-set update), `supported_locales` to\nreplace the supported locales, or `position` to reorder the market\nwithin the store.\n\nSetting `default: true` automatically demotes the previous default.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"market updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Market"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"currency":{"type":"string"},"default_locale":{"type":"string"},"supported_locales":{"type":"array","items":{"type":"string"}},"tax_inclusive":{"type":"boolean"},"default":{"type":"boolean"},"position":{"type":"integer"},"country_codes":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a market","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the market (sets `deleted_at`). The default market and\nthe last remaining market in a store cannot be deleted — both return\n422 with a `validation_error`.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"market deleted"},"422":{"description":"cannot delete default or last market","content":{"application/json":{}}}}}},"/api/v3/admin/option_types":{"get":{"summary":"List option types","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of option types.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., option_values). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,label,position). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"option types found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OptionType"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create an option type","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new option type. Supports nested option values.\n\nOption values can be provided inline and will be created or updated by name.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"option type created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptionType"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"integer"},"filterable":{"type":"boolean"},"option_values":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"integer"}}}}},"required":["name","label"]}}}}}},"/api/v3/admin/option_types/{id}":{"get":{"summary":"Get an option type","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single option type by ID, including its option values.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Option type ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., option_values). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,label,position). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"option type found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptionType"}}}},"404":{"description":"option type not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update an option type","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an option type. Supports updating nested option values.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Option type ID","schema":{"type":"string"}}],"responses":{"200":{"description":"option type updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptionType"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"integer"},"filterable":{"type":"boolean"},"option_values":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Existing option value ID to update"},"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"integer"}}}}}}}}}},"delete":{"summary":"Delete an option type","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes an option type.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Option type ID","schema":{"type":"string"}}],"responses":{"204":{"description":"option type deleted"}}}},"/api/v3/admin/orders/{order_id}/tax_lines":{"get":{"summary":"List tax lines","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Typed tax rows on the order. Read-only — written exclusively by the tax provider.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order prefixed ID","schema":{"type":"string"}}],"responses":{"200":{"description":"tax lines found","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/discounts":{"get":{"summary":"List discounts","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Typed discount rows (promotion-sourced and manual) on the order.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order prefixed ID","schema":{"type":"string"}}],"responses":{"200":{"description":"discounts found","content":{"application/json":{}}}}},"post":{"summary":"Create manual discount","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a manual discount. With line_item_id a single row is created; without it the amount is distributed across line items (largest remainder). This is the sanctioned post-placement discount path and works on completed orders.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order prefixed ID","schema":{"type":"string"}}],"responses":{"201":{"description":"discount created","content":{"application/json":{}}},"422":{"description":"invalid discount","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string"},"value":{"type":"number"},"value_type":{"type":"string","enum":["flat","percent"]},"line_item_id":{"type":"string","nullable":true,"description":"Target line item; omit to distribute order-level"}},"required":["label","value"]}}}}}},"/api/v3/admin/orders/{order_id}/fees":{"post":{"summary":"Create fee","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a fee (surcharge, handling, gift wrap, COD, payment fee). Order-level when no target is given. Works on completed orders.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order prefixed ID","schema":{"type":"string"}}],"responses":{"201":{"description":"fee created","content":{"application/json":{}}},"422":{"description":"invalid fee","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string"},"amount":{"type":"number"},"kind":{"type":"string","enum":["surcharge","handling","gift_wrap","cod","payment","duty"],"description":"Defaults to 'surcharge'"},"line_item_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true}},"required":["label","amount"]}}}}}},"/api/v3/admin/orders/{order_id}/gift_cards":{"post":{"summary":"Apply a gift card to an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Applies a gift card by code to the order. Returns the gift card.\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"gift card applied","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Gift card code"}}}}}}}},"/api/v3/admin/orders/{order_id}/gift_cards/{id}":{"delete":{"summary":"Remove a gift card from an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes the gift card from the order.\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Gift card ID","schema":{"type":"string"}}],"responses":{"204":{"description":"gift card removed"}}}},"/api/v3/admin/orders/{order_id}/items":{"get":{"summary":"List order items","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all line items for an order.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., variant, variant.product). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., quantity,price,total). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"items found","content":{"application/json":{}}}}},"post":{"summary":"Add an item","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a new line item to the order.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"item added","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["variant_id"],"properties":{"variant_id":{"type":"string","description":"Prefixed variant ID"},"quantity":{"type":"integer","default":1}}}}}}}},"/api/v3/admin/orders/{order_id}/items/{id}":{"get":{"summary":"Show an item","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns details of a specific line item.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Item ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., variant, variant.product). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., quantity,price,total). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"item found","content":{"application/json":{}}}}},"patch":{"summary":"Update an item","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an order item quantity or metadata.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Item ID","schema":{"type":"string"}}],"responses":{"200":{"description":"item updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"quantity":{"type":"integer"}}}}}}},"delete":{"summary":"Remove an item","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes an item from the order.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Item ID","schema":{"type":"string"}}],"responses":{"204":{"description":"line item removed"}}}},"/api/v3/admin/orders/{order_id}/store_credits":{"post":{"summary":"Apply customer's store credit to an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Applies the order customer's available store credit. When `amount` is omitted, applies up to the order outstanding balance.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"store credit applied","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string","description":"Optional explicit amount; defaults to order outstanding balance"}}}}}}},"delete":{"summary":"Remove store credit from an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes any applied store credit from the order.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"204":{"description":"store credit removed"}}}},"/api/v3/admin/orders":{"get":{"summary":"List orders","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of orders for the current store.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"sort","in":"query","required":false,"description":"Sort field (e.g., created_at, -created_at, completed_at)","schema":{"type":"string"}},{"name":"q[state_eq]","in":"query","required":false,"description":"Filter by state (cart, address, delivery, payment, confirm, complete, canceled)","schema":{"type":"string"}},{"name":"q[email_cont]","in":"query","required":false,"description":"Filter by email (contains)","schema":{"type":"string"}},{"name":"q[number_eq]","in":"query","required":false,"description":"Filter by order number","schema":{"type":"string"}},{"name":"q[completed_at_gt]","in":"query","required":false,"description":"Filter by completed after date","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., items, fulfillments, payments, customer, discounts, billing_address, shipping_address). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., number,total,status,completed_at). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"orders found","content":{"application/json":{}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a draft order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new draft order in one shot. Customer, items, addresses, currency,\nmarket, channel, locale, notes, metadata, and a coupon code can all be\nprovided inline.\n\nSetting `preferred_stock_location_id` pins the order's preferred fulfillment\nlocation — Order Routing's built-in `PreferredLocation` rule consumes it\nwhen picking which stock location ships each shipment.\n\nInvalid coupon codes are non-fatal — the order is created and the failure\nis reported on the service result (not in the API response body for now).\n\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"order created with preferred_stock_location_id","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"},"customer_id":{"type":"string","description":"Customer ID."},"use_customer_default_address":{"type":"boolean","description":"When true with customer_id, copies the customer's saved billing/shipping addresses onto the order."},"currency":{"type":"string"},"market_id":{"type":"string","description":"Market ID"},"channel_id":{"type":"string","description":"Channel ID. Defaults to the store primary channel when omitted."},"preferred_stock_location_id":{"type":"string","description":"Stock Location ID to prefer for fulfillment. Order Routing's built-in PreferredLocation rule reads this and ranks the location first; routing falls back to the next rule when the preferred location can't cover the cart."},"locale":{"type":"string"},"customer_note":{"type":"string","description":"Public, customer-visible note"},"internal_note":{"type":"string","description":"Staff-only note"},"metadata":{"type":"object","description":"Arbitrary key/value metadata"},"shipping_address":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"address1":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"},"phone":{"type":"string"}}},"shipping_address_id":{"type":"string","description":"Existing customer address ID"},"billing_address":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"address1":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"},"phone":{"type":"string"}}},"billing_address_id":{"type":"string","description":"Existing customer address ID"},"items":{"type":"array","items":{"type":"object","required":["variant_id","quantity"],"properties":{"variant_id":{"type":"string","description":"Variant ID"},"quantity":{"type":"integer"},"metadata":{"type":"object"}}}},"coupon_code":{"type":"string","description":"Optional. Applied non-fatally; invalid codes do not block creation."}}}}}}}},"/api/v3/admin/orders/{id}":{"get":{"summary":"Show an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns full order details including admin-only fields.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID (e.g., or_xxx)","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., items, fulfillments, payments, customer, discounts, billing_address, shipping_address). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., number,total,status,completed_at). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"order found","content":{"application/json":{}}},"404":{"description":"order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an order. Supports updating email, addresses, special instructions, and line items.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"order updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"},"customer_note":{"type":"string"},"internal_note":{"type":"string"},"channel_id":{"type":"string","description":"Channel ID"},"preferred_stock_location_id":{"type":"string","description":"Stock Location ID to prefer for fulfillment. Re-runs Order Routing's PreferredLocation rule on subsequent shipment rebuilds."},"shipping_address":{"type":"object","properties":{"firstname":{"type":"string"},"lastname":{"type":"string"},"address1":{"type":"string"},"city":{"type":"string"},"zipcode":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"},"phone":{"type":"string"}}},"billing_address":{"type":"object","properties":{"firstname":{"type":"string"},"lastname":{"type":"string"},"address1":{"type":"string"},"city":{"type":"string"},"zipcode":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"},"phone":{"type":"string"}}},"items":{"type":"array","items":{"type":"object","required":["variant_id"],"properties":{"variant_id":{"type":"string","description":"Variant ID"},"quantity":{"type":"integer"},"metadata":{"type":"object"}}}}}}}}}},"delete":{"summary":"Delete a draft order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a draft order. Completed orders cannot be deleted.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"204":{"description":"order deleted"}}}},"/api/v3/admin/orders/{id}/complete":{"patch":{"summary":"Complete an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Completes an order in the `confirm` state, marking it as placed.\n\nSet `notify_customer: true` to send the order confirmation email.\n\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"order completed","content":{"application/json":{}}},"422":{"description":"order cannot be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"notify_customer":{"type":"boolean","description":"Send the order confirmation email after completion."}}}}}}}},"/api/v3/admin/orders/{id}/cancel":{"patch":{"summary":"Cancel an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Cancels a completed order.\n\n`cancel_reason_id` records why, from the store's own cancellation-reason\nvocabulary (`/admin/order_cancellation_reasons`), and `cancel_note` is a\nstaff-facing note; both are shown on the order afterwards.\n\nStock is always released — the goods are not going out either way — and\nevery payment is settled at the gateway, which releases an\nauthorization it never drew on and refunds a charge it cannot release.\n\n`refund_payments` and `refund_amount` govern the shared payment of a\nsplit checkout, where one payment covers several orders: they decide\nwhether this order's share comes back, and how much of it. A\n`refund_amount` on an ordinary order is refused with a 422.\n\nSet `notify_customer: true` to send the order cancellation email.\n\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"order canceled","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"cancel_reason_id":{"type":"string","description":"Why the order was canceled — the id of one of the store's cancellation reasons."},"cancel_note":{"type":"string","description":"Staff-facing note about the cancellation."},"refund_payments":{"type":"boolean","default":false,"description":"Whether this order's share of a payment shared across a split checkout is handed back."},"refund_amount":{"type":"string","description":"How much of that share to return. Defaults to all of it; refused on an order whose payment is not shared."},"notify_customer":{"type":"boolean","default":false,"description":"Send the order cancellation email after canceling."}}}}}}}},"/api/v3/admin/orders/{id}/approve":{"patch":{"summary":"Approve an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Approves an order (e.g., for fraud review).\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"order approved","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{id}/resend_confirmation":{"post":{"summary":"Resend confirmation email","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Publishes the order.completed event to trigger confirmation email delivery.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"confirmation resent","content":{"application/json":{}}}}}},"/api/v3/admin/payment_methods":{"get":{"summary":"List payment methods","tags":["Payment Methods"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the store's configured payment methods. Use `source_required: true` to know which methods need a saved source.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand. Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,type,active). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"payment methods found","content":{"application/json":{}}}}}},"/api/v3/admin/payment_methods/types":{"get":{"summary":"List available payment provider types","tags":["Payment Methods"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the registered Spree::PaymentMethod subclasses that can be used to create new payment methods. Useful for populating a \"Provider\" dropdown in admin UIs.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"provider types found","content":{"application/json":{}}}}}},"/api/v3/admin/payment_methods/{id}":{"get":{"summary":"Show a payment method","tags":["Payment Methods"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a payment method by ID.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand. Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,type,active). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"payment method found","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/payments":{"get":{"summary":"List payments","tags":["Payments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all payments for an order.\n\n**Required scope:** `read_payments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., payment_method, source). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., amount,status,number,response_code). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"payments found","content":{"application/json":{}}}}},"post":{"summary":"Create a payment","tags":["Payments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new payment for the order.\n\n**Required scope:** `write_payments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"payment created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["payment_method_id"],"properties":{"payment_method_id":{"type":"string","description":"Payment method ID"},"amount":{"type":"string"},"source_id":{"type":"string","description":"Payment source ID"}}}}}}}},"/api/v3/admin/orders/{order_id}/payments/{id}":{"get":{"summary":"Show a payment","tags":["Payments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns details of a specific payment.\n\n**Required scope:** `read_payments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Payment ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., payment_method, source). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., amount,status,number,response_code). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"payment found","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/payments/{id}/capture":{"patch":{"summary":"Capture a payment","tags":["Payments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Captures a pending payment.\n\n**Required scope:** `write_payments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Payment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"payment captured","content":{"application/json":{}}},"422":{"description":"capture failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/orders/{order_id}/payments/{id}/void":{"patch":{"summary":"Void a payment","tags":["Payments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Voids a payment.\n\n**Required scope:** `write_payments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Payment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"payment voided","content":{"application/json":{}}}}}},"/api/v3/admin/price_lists":{"get":{"summary":"List price lists","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the price lists configured for the current store.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"schema":{"type":"string"}},{"name":"q[status_eq]","in":"query","required":false,"schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed. Supported: `price_rules`.","schema":{"type":"string"}}],"responses":{"200":{"description":"price lists found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PriceList"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new draft price list.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"price list created (server-to-server — rules + prices)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceList"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"starts_at":{"type":"string","nullable":true},"ends_at":{"type":"string","nullable":true},"match_policy":{"type":"string","enum":["all","any"]},"position":{"type":"integer"},"rules":{"type":"array","description":"STI-typed price rules to attach on create. Existing rules on the same payload via PATCH reconcile by id.","items":{"type":"object","required":["type"],"properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}}}},"prices":{"type":"array","description":"Server-to-server shape: ship the exact per-variant prices the list should contain. Each row upserts on the unique key `(variant_id, currency, price_list_id)` — `prices` alone tells the server which variants belong to the list and what the override amount is. Curating whole products goes through the nested `/price_lists/{id}/products` surface instead.","items":{"type":"object","required":["variant_id","currency"],"properties":{"variant_id":{"type":"string"},"currency":{"type":"string"},"amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true}}}}}}}}}}},"/api/v3/admin/price_lists/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"price list found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceList"}}}},"404":{"description":"price list not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a price list. The optional `rules:` array reconciles nested\nSTI-typed price rules in a single round-trip — existing rules update\nby `id`, new rules build, missing rules destroy. Mirrors the\npromotion editor's \"save the whole thing on Save\" pattern.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"price list updated with nested rules","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceList"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"starts_at":{"type":"string","nullable":true},"ends_at":{"type":"string","nullable":true},"match_policy":{"type":"string","enum":["all","any"]},"position":{"type":"integer"},"rules":{"type":"array","items":{"type":"object","required":["type"],"properties":{"id":{"type":"string","nullable":true},"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}}}},"prices":{"type":"array","description":"Individual price overrides (the spreadsheet payload). Each row updates by `id` if shipped, otherwise upserts on the unique key `(variant_id, currency, price_list_id)`.","items":{"type":"object","oneOf":[{"required":["id"]},{"required":["variant_id","currency"]}],"properties":{"id":{"type":"string"},"variant_id":{"type":"string"},"currency":{"type":"string"},"amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true}}}}}}}}}},"delete":{"summary":"Delete a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the price list. Associated prices are removed asynchronously.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"price list deleted"}}}},"/api/v3/admin/price_lists/{id}/activate":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Activate a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Transitions a draft / inactive list to `active`. If `starts_at` is\nin the future the list is marked `scheduled` instead, matching the\nlegacy admin behaviour.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"price list activated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceList"}}}}}}},"/api/v3/admin/price_lists/{id}/deactivate":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Deactivate a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"price list deactivated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceList"}}}}}}},"/api/v3/admin/prices":{"get":{"summary":"List prices","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Generic prices endpoint covering both base prices and price-list\noverrides. Filter with Ransack: `q[price_list_id_eq]=…`,\n`q[currency_eq]=USD`, `q[price_list_id_null]=true` (base prices only).\n\nThe admin spreadsheet uses this with server-side pagination so it\nscales past the metadata-PATCH path on `/price_lists/:id`.\n\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"q[price_list_id_eq]","in":"query","required":false,"schema":{"type":"string"}},{"name":"q[price_list_id_null]","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"q[currency_eq]","in":"query","required":false,"schema":{"type":"string"}},{"name":"q[variant_id_eq]","in":"query","required":false,"schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort keys. Supports e.g. `variant_product_name,variant_id`.","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed. Supported: `variant`.","schema":{"type":"string"}}],"responses":{"200":{"description":"prices found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Price"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a price","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a single price. Omit `price_list_id` to create a base price.\nFor more than a handful of rows, prefer `POST /admin/prices/bulk_upsert`.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"price created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Price"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["variant_id","currency"],"properties":{"variant_id":{"type":"string"},"currency":{"type":"string"},"amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true},"price_list_id":{"type":"string","nullable":true}}}}}}}},"/api/v3/admin/prices/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a price","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"price found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Price"}}}},"404":{"description":"price not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a price","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"price updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Price"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true}}}}}}},"delete":{"summary":"Delete a price","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the price (acts_as_paranoid).\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"price deleted"}}}},"/api/v3/admin/prices/bulk_upsert":{"post":{"summary":"Bulk-upsert prices","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Upserts a batch of prices in a single SQL round trip.\n\nEach row either:\n* targets an existing price by `id`, OR\n* matches on the unique key `(variant_id, currency, price_list_id)` —\n updating the existing row if one exists, creating one otherwise.\n\nModel callbacks (e.g. PriceHistory) are bypassed; this is a\nbulk-write fast path for the admin spreadsheet. The response\ncarries `price_count` — the number of rows touched.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"prices upserted","content":{"application/json":{"schema":{"type":"object","properties":{"price_count":{"type":"integer"}}}}}},"422":{"description":"missing prices key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["prices"],"properties":{"prices":{"type":"array","items":{"type":"object","required":["variant_id","currency"],"properties":{"id":{"type":"string","nullable":true},"variant_id":{"type":"string"},"currency":{"type":"string"},"price_list_id":{"type":"string","nullable":true},"amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true}}}}}}}}}}},"/api/v3/admin/prices/bulk_destroy":{"delete":{"summary":"Bulk-delete prices","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes each price in `ids`. Returns the count actually destroyed.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"prices deleted","content":{"application/json":{"schema":{"type":"object","properties":{"price_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/{product_id}/custom_fields":{"get":{"summary":"List product custom fields","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the product's custom field values.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., custom_field_definition). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., key,value,namespace). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"custom fields found","content":{"application/json":{}}}}},"post":{"summary":"Create a product custom field","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Sets a custom field value on the product. Requires an existing CustomFieldDefinition; pass its prefixed `cfdef_…` id.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"custom field created","content":{"application/json":{}}},"422":{"description":"duplicate definition for the same product","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["custom_field_definition_id","value"],"properties":{"custom_field_definition_id":{"type":"string","description":"Prefixed `cfdef_…` id"},"value":{"description":"Value matching the definition's `field_type`"}}}}}}}},"/api/v3/admin/products/{product_id}/custom_fields/{id}":{"get":{"summary":"Show a product custom field","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., custom_field_definition). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., key,value,namespace). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"custom field found","content":{"application/json":{}}}}},"patch":{"summary":"Update a product custom field","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates the custom field's `value`. The linked definition cannot be changed — delete and recreate to switch.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"custom field updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["value"],"properties":{"value":{"description":"New value"}}}}}}},"delete":{"summary":"Delete a product custom field","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"custom field deleted"}}}},"/api/v3/admin/products/{product_id}/translations":{"get":{"summary":"List product translations","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the full translation matrix for the product: the source value and content type per translatable field, plus the translated value for every supported locale.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"translations found","content":{"application/json":{}}}}}},"/api/v3/admin/products":{"get":{"summary":"List products","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of products for the current store.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"sort","in":"query","required":false,"description":"Sort field (e.g., name, -name, price, -price, best_selling)","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., variants, media, option_types, categories). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,slug,price,status). id is always included.","schema":{"type":"string"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[status_eq]","in":"query","required":false,"description":"Filter by status","schema":{"type":"string"}}],"responses":{"200":{"description":"products found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a product","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new product. Supports nested variants with prices and option types.\n\nOption types and values are auto-created if they don't exist.\nPrices are upserted by currency. Stock items are upserted by stock location.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"product created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"slug":{"type":"string"},"status":{"type":"string","enum":["draft","active","archived"]},"tax_category_id":{"type":"string","description":"Tax category ID"},"category_ids":{"type":"array","items":{"type":"string"},"description":"Array of category IDs"},"tags":{"type":"array","items":{"type":"string"}},"prices":{"type":"array","description":"Shorthand for a simple (no-options) product: per-currency prices that forward to the product's sole variant. For products with options, set prices per variant under `variants:` instead.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"variants":{"type":"array","description":"Array of variant payloads. Variants can declare multiple option pairs via `options:` and per-currency prices via `prices:`. Stock counts go in `stock_levels:` (per stock location).","items":{"type":"object","properties":{"sku":{"type":"string"},"options":{"type":"array","description":"One pair per option type the variant participates in (e.g. size + color). Option types and values are auto-created if missing.","items":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string"},"value":{"type":"string"}}}},"prices":{"type":"array","description":"Per-currency prices. Upserted by currency.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"stock_levels":{"type":"array","description":"Per-stock-location inventory. Upserted by stock_location_id.","items":{"type":"object","required":["stock_location_id","count_on_hand"],"properties":{"stock_location_id":{"type":"string","description":"Stock location ID (e.g. sloc_xxx)"},"count_on_hand":{"type":"integer"},"backorderable":{"type":"boolean"}}}}}}}},"required":["name"]}}}}}},"/api/v3/admin/products/{id}":{"get":{"summary":"Get a product","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single product by ID.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID (e.g., prod_xxx)","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., variants, media, option_types, categories). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,slug,price,status). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"product found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"404":{"description":"product not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a product","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a product. Only provided fields are updated.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"200":{"description":"product updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"slug":{"type":"string"},"status":{"type":"string","enum":["draft","active","archived"]},"tax_category_id":{"type":"string","description":"Tax category ID"},"category_ids":{"type":"array","items":{"type":"string"},"description":"Array of category IDs"},"tags":{"type":"array","items":{"type":"string"}},"prices":{"type":"array","description":"Shorthand for a simple (no-options) product: per-currency prices that forward to the product's sole variant. For products with options, set prices per variant under `variants:` instead.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"variants":{"type":"array","description":"Array of variant payloads. Variants can declare multiple option pairs via `options:` and per-currency prices via `prices:`. Stock counts go in `stock_levels:` (per stock location).","items":{"type":"object","properties":{"sku":{"type":"string"},"options":{"type":"array","description":"One pair per option type the variant participates in (e.g. size + color). Option types and values are auto-created if missing.","items":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string"},"value":{"type":"string"}}}},"prices":{"type":"array","description":"Per-currency prices. Upserted by currency.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"stock_levels":{"type":"array","description":"Per-stock-location inventory. Upserted by stock_location_id.","items":{"type":"object","required":["stock_location_id","count_on_hand"],"properties":{"stock_location_id":{"type":"string","description":"Stock location ID (e.g. sloc_xxx)"},"count_on_hand":{"type":"integer"},"backorderable":{"type":"boolean"}}}}}}}}}}}}},"delete":{"summary":"Delete a product","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes a product.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"204":{"description":"product deleted"},"422":{"description":"deletion refused by a store rule","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/products/bulk_status_update":{"post":{"summary":"Bulk-update product status","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Sets `status` on each product in `ids`. Reindexes the affected products\nfor search. Cross-store IDs are silently dropped. Returns counts.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"cross-store products silently dropped","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"status":{"type":"string"}}}}}},"422":{"description":"invalid status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","status"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["draft","active","archived"]}}}}}}}},"/api/v3/admin/products/bulk_add_to_categories":{"post":{"summary":"Bulk-add products to categories","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Attaches each product in `ids` to every category (category) in `category_ids`.\nCategories from sibling stores are silently ignored.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products added to categories","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"category_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","category_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_remove_from_categories":{"post":{"summary":"Bulk-remove products from categories","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Detaches each product in `ids` from every category in `category_ids`.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products removed from categories","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","category_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_add_to_collections":{"post":{"summary":"Bulk-add products to collections","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Attaches each product in `ids` to every manual collection in `collection_ids`.\nAutomatic (rule-based) and sibling-store collections are silently ignored.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products added to collections","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"collection_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","collection_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"collection_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_remove_from_collections":{"post":{"summary":"Bulk-remove products from collections","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Detaches each product in `ids` from every collection in `collection_ids`.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products removed from collections","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","collection_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"collection_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_add_to_channels":{"post":{"summary":"Bulk-add products to channels","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Publishes each product in `ids` on every channel in `channel_ids`. Idempotent —\nre-publishing on an existing channel is a no-op. Channels from sibling stores\nare silently ignored.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products published on channels","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"channel_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","channel_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"channel_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_remove_from_channels":{"post":{"summary":"Bulk-remove products from channels","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Unpublishes each product in `ids` from every channel in `channel_ids`.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products unpublished from channels","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"channel_count":{"type":"integer"},"removed":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","channel_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"channel_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_add_tags":{"post":{"summary":"Bulk-add tags to products","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds each tag name in `tags` to every product in `ids`. Tags are upserted by name.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"tags added","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"tag_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","tags"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_remove_tags":{"post":{"summary":"Bulk-remove tags from products","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes each tag in `tags` from every product in `ids`.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"tags removed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","tags"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_destroy":{"delete":{"summary":"Bulk-delete products","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes each product in `ids`. Returns the count actually destroyed.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products deleted","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/translations":{"get":{"summary":"Translation coverage for a resource type","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Reports how much of each record is translated into each of the store's non-default locales, plus per-locale totals. A record counts as covered for a locale only when every one of its translatable fields is filled in.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"resource_type","in":"query","required":true,"description":"A translatable resource type, e.g. `product`, `category`, `option_type`.","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"search","in":"query","required":false,"description":"Free-text term, applied through whichever predicate the resource type whitelists (reported back as `search_field`).","schema":{"type":"string"}}],"responses":{"200":{"description":"coverage found","content":{"application/json":{}}},"404":{"description":"resource type is not translatable","content":{"application/json":{}}}}}},"/api/v3/admin/policies":{"get":{"summary":"List policies","tags":["Policies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the store's policy documents — terms of service, privacy\npolicy, returns policy, shipping policy, and any others the merchant\nhas written. Every store is created with the four standard policies,\nnamed but empty.\n\nA marketplace seller's own policies are managed by the seller and are\nnot listed here.\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"policies listed","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Policy"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a policy","tags":["Policies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a policy. `body` accepts HTML and is sanitized before it is\nstored; the stored markup is returned as `body_html`, and `body` reads\nback as plain text.\n\nThe slug is derived from the name when one is not given, and is what\nthe storefront addresses the policy by.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"policy created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Policy"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"},"body":{"type":"string"}},"required":["name"]}}}}}},"/api/v3/admin/policies/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Policy prefixed ID or slug","schema":{"type":"string"}}],"get":{"summary":"Get a policy","tags":["Policies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single policy, addressed by prefixed ID or by slug.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"policy found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Policy"}}}},"404":{"description":"policy not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a policy","tags":["Policies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a policy. `body` accepts HTML and is sanitized before it is stored.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"policy updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Policy"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"},"body":{"type":"string"}}}}}}},"delete":{"summary":"Delete a policy","tags":["Policies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a policy. The four policies a store is created with can be\ndeleted like any other — they are conventions, not fixtures.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"policy deleted"}}}},"/api/v3/admin/claim_reasons":{"get":{"summary":"List claim reasons","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Why a customer raised a claim — what the merchant got wrong, rather than a change of mind.\n\nThe vocabulary is the merchant's own — seeded with a starting set and\nedited from the dashboard. Inactive rows stay for the records that\nalready reference them, but are not offered on new ones.\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[active_eq]","in":"query","required":false,"description":"Filter by active flag","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"responses":{"200":{"description":"claim reasons found","content":{"application/json":{}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a claim reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a claim reason to this store. Names are unique per store, ignoring case.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"claim reason created","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"active":{"type":"boolean","description":"Inactive reasons are hidden from the pickers on new records."}}}}}}}},"/api/v3/admin/claim_reasons/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Claim reason ID","schema":{"type":"string"}}],"get":{"summary":"Get a claim reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single claim reason by prefixed ID.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"claim reason found","content":{"application/json":{}}},"404":{"description":"claim reason not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a claim reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Renames a claim reason or retires it. Deactivating keeps it on the records\nthat already carry it while removing it from the pickers.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"claim reason updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"active":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a claim reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes a claim reason the store no longer uses. A reason already recorded\non a document is refused — deactivate it instead, so the history it\nexplains stays readable.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"claim reason deleted"}}}},"/api/v3/admin/order_cancellation_reasons":{"get":{"summary":"List order cancellation reasons","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Why an order was called off before it shipped. Staff pick one when canceling.\n\nThe vocabulary is the merchant's own — seeded with a starting set and\nedited from the dashboard. Inactive rows stay for the records that\nalready reference them, but are not offered on new ones.\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[active_eq]","in":"query","required":false,"description":"Filter by active flag","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"responses":{"200":{"description":"order cancellation reasons found","content":{"application/json":{}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a order cancellation reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a order cancellation reason to this store. Names are unique per store, ignoring case.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"order cancellation reason created","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"active":{"type":"boolean","description":"Inactive reasons are hidden from the pickers on new records."}}}}}}}},"/api/v3/admin/order_cancellation_reasons/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Order cancellation reason ID","schema":{"type":"string"}}],"get":{"summary":"Get a order cancellation reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single order cancellation reason by prefixed ID.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"order cancellation reason found","content":{"application/json":{}}},"404":{"description":"order cancellation reason not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a order cancellation reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Renames a order cancellation reason or retires it. Deactivating keeps it on the records\nthat already carry it while removing it from the pickers.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"order cancellation reason updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"active":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a order cancellation reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes a order cancellation reason the store no longer uses. A reason already recorded\non a document is refused — deactivate it instead, so the history it\nexplains stays readable.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"order cancellation reason deleted"}}}},"/api/v3/admin/refund_reasons":{"get":{"summary":"List refund reasons","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Why money went back. Some rows are seeded and looked up by name, so they refuse renaming and deletion.\n\nThe vocabulary is the merchant's own — seeded with a starting set and\nedited from the dashboard. Inactive rows stay for the records that\nalready reference them, but are not offered on new ones.\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[active_eq]","in":"query","required":false,"description":"Filter by active flag","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"responses":{"200":{"description":"refund reasons found","content":{"application/json":{}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a refund reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a refund reason to this store. Names are unique per store, ignoring case.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"refund reason created","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"active":{"type":"boolean","description":"Inactive reasons are hidden from the pickers on new records."}}}}}}}},"/api/v3/admin/refund_reasons/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Refund reason ID","schema":{"type":"string"}}],"get":{"summary":"Get a refund reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single refund reason by prefixed ID.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"refund reason found","content":{"application/json":{}}},"404":{"description":"refund reason not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a refund reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Renames a refund reason or retires it. Deactivating keeps it on the records\nthat already carry it while removing it from the pickers.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"refund reason updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"active":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a refund reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes a refund reason the store no longer uses. A reason already recorded\non a document is refused — deactivate it instead, so the history it\nexplains stays readable.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"refund reason deleted"}}}},"/api/v3/admin/return_reasons":{"get":{"summary":"List return reasons","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Why a customer is sending items back. Shared by returns and exchanges.\n\nThe vocabulary is the merchant's own — seeded with a starting set and\nedited from the dashboard. Inactive rows stay for the records that\nalready reference them, but are not offered on new ones.\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[active_eq]","in":"query","required":false,"description":"Filter by active flag","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"responses":{"200":{"description":"return reasons found","content":{"application/json":{}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a return reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a return reason to this store. Names are unique per store, ignoring case.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"return reason created","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"active":{"type":"boolean","description":"Inactive reasons are hidden from the pickers on new records."}}}}}}}},"/api/v3/admin/return_reasons/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Return reason ID","schema":{"type":"string"}}],"get":{"summary":"Get a return reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single return reason by prefixed ID.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"return reason found","content":{"application/json":{}}},"404":{"description":"return reason not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a return reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Renames a return reason or retires it. Deactivating keeps it on the records\nthat already carry it while removing it from the pickers.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"return reason updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"active":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a return reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes a return reason the store no longer uses. A reason already recorded\non a document is refused — deactivate it instead, so the history it\nexplains stays readable.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"return reason deleted"}}}},"/api/v3/admin/promotions/{promotion_id}/coupon_codes":{"parameters":[{"name":"promotion_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List coupon codes for a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the auto-generated coupon codes for a multi-code promotion. Single-code promotions store the code on the promotion itself; this endpoint returns an empty list for them.\n\n**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"coupon codes found","content":{"application/json":{}}}}}},"/api/v3/admin/promotions/{promotion_id}/promotion_actions":{"parameters":[{"name":"promotion_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List actions for a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"actions found","content":{"application/json":{}}}}},"post":{"summary":"Create an action on a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a new action to a promotion. The `type` is the wire shorthand from `GET /promotion_actions/types` (e.g. `free_shipping`, `create_item_adjustments`). Fully-qualified Ruby class names are also accepted for backward compatibility.\n\n**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"action created","content":{"application/json":{}}},"422":{"description":"unknown action type","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}},"required":["type"]}}}}}},"/api/v3/admin/promotions/{promotion_id}/promotion_actions/{id}":{"parameters":[{"name":"promotion_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"delete":{"summary":"Delete an action from a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"action deleted"}}}},"/api/v3/admin/promotions/{promotion_id}/promotion_rules":{"parameters":[{"name":"promotion_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List rules for a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"rules found","content":{"application/json":{}}}}},"post":{"summary":"Create a rule on a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a new rule to a promotion. The `type` is the wire shorthand from `GET /promotion_rules/types` (e.g. `currency`, `item_total`, `product`). Fully-qualified Ruby class names are also accepted for backward compatibility.\n\n**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"rule created with preferences","content":{"application/json":{}}},"422":{"description":"unknown rule type","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}},"required":["type"]}}}}}},"/api/v3/admin/promotions/{promotion_id}/promotion_rules/{id}":{"parameters":[{"name":"promotion_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Update a rule's preferences","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"rule updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"preferences":{"type":"object","additionalProperties":true}}}}}}},"delete":{"summary":"Delete a rule from a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"rule deleted"}}}},"/api/v3/admin/promotions":{"get":{"summary":"List promotions","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the store's promotions, including manual coupon and automatic promotions.\n\n**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"promotions found","content":{"application/json":{}}}}},"post":{"summary":"Create a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new promotion. `code` is required for single-code coupon promotions;\npass `multi_codes: true` with `number_of_codes` to auto-generate a batch.\n\nRules and actions can be created in the same request by passing arrays of\n`{ type, preferences, ... }` rows. The server reconciles to the desired set:\nnew rows are built, existing rows (by `id`) are updated, omitted rows are removed.\n\n\n**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"promotion created with rules and actions","content":{"application/json":{}}},"422":{"description":"invalid params","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"code":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"starts_at":{"type":"string","format":"date-time","nullable":true},"expires_at":{"type":"string","format":"date-time","nullable":true},"usage_limit":{"type":"integer","nullable":true},"match_policy":{"type":"string","enum":["all","any"]},"kind":{"type":"string","enum":["coupon_code","automatic"]},"multi_codes":{"type":"boolean"},"number_of_codes":{"type":"integer","nullable":true},"code_prefix":{"type":"string","nullable":true},"promotion_category_id":{"type":"string","nullable":true},"rules":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true},"product_ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}},"customer_ids":{"type":"array","items":{"type":"string"}}},"required":["type"]}},"actions":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true},"calculator":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}}}},"required":["type"]}}},"required":["name"]}}}}}},"/api/v3/admin/promotions/{id}":{"get":{"summary":"Show a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"promotion found","content":{"application/json":{}}}}},"patch":{"summary":"Update a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a promotion. The `rules` and `actions` arrays are treated as\na *desired set* — rows with `id` update in place, rows without `id` are\nbuilt fresh, and any existing row not present in the array is destroyed.\nPass `rules: []` or `actions: []` to clear them.\n\n\n**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"rules and actions cleared with empty arrays","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"code":{"type":"string","nullable":true},"starts_at":{"type":"string","format":"date-time","nullable":true},"expires_at":{"type":"string","format":"date-time","nullable":true},"usage_limit":{"type":"integer","nullable":true},"match_policy":{"type":"string","enum":["all","any"]},"kind":{"type":"string","enum":["coupon_code","automatic"]},"promotion_category_id":{"type":"string","nullable":true},"rules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","nullable":true,"description":"Pass to update an existing rule; omit to build a new one"},"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true},"product_ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}},"customer_ids":{"type":"array","items":{"type":"string"}}},"required":["type"]}},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","nullable":true},"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true},"calculator":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}}}},"required":["type"]}}}}}}}},"delete":{"summary":"Delete a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"promotion deleted"}}}},"/api/v3/admin/promotion_actions/types":{"get":{"summary":"List available promotion action types","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the registered Spree::PromotionAction subclasses with their preference schemas. Used by admin UIs to populate the \"Add action\" picker and render generic preference forms.\n\n**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"action types found","content":{"application/json":{}}}}}},"/api/v3/admin/promotion_rules/types":{"get":{"summary":"List available promotion rule types","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the registered Spree::PromotionRule subclasses with their preference schemas.\n\n**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"rule types found","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/refunds":{"get":{"summary":"List refunds","tags":["Refunds"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all refunds for an order.\n\n**Required scope:** `read_refunds` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., payment, refund_reason). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., amount,reason,transaction_id). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"refunds found","content":{"application/json":{}}}}},"post":{"summary":"Create a refund","tags":["Refunds"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a refund for a payment on the order. The refund is automatically processed via the payment gateway.\n\n**Required scope:** `write_refunds` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"refund created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["payment_id","amount"],"properties":{"payment_id":{"type":"string","description":"Payment ID"},"amount":{"type":"string"},"refund_reason_id":{"type":"string","description":"Refund reason ID"}}}}}}}},"/api/v3/admin/locales":{"get":{"summary":"List supported locales","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the locales a merchant can translate content into for the current store, with the default and right-to-left flags.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"locales found","content":{"application/json":{}}}}}},"/api/v3/admin/store":{"get":{"summary":"Get the current store","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the current store configuration. The store is resolved from the request context (host or admin selection); there is no `id` parameter.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"current store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Store"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update the current store","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates the current store configuration.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"store updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Store"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"preferred_admin_locale":{"type":"string"},"preferred_timezone":{"type":"string"},"preferred_weight_unit":{"type":"string"},"preferred_unit_system":{"type":"string"}}}}}}}},"/api/v3/admin/tags":{"get":{"summary":"List tags","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns tag names for a given taggable type. Used for autocomplete in tag inputs on products, orders, and customers.","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"taggable_type","in":"query","required":true,"description":"Taggable type (`Spree::Product`, `Spree::Order`, or `Spree::User`)","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"description":"Optional case-insensitive substring filter","schema":{"type":"string"}}],"responses":{"200":{"description":"tags found","content":{"application/json":{}}},"422":{"description":"invalid taggable type","content":{"application/json":{}}}}}},"/api/v3/admin/tax_rates":{"get":{"summary":"List tax rates","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the store's tax rates. Rates are the entire configuration of\nthe built-in tax provider: each pairs a tax category with a jurisdiction\n(a country, optionally narrowed to one state) and a percentage, and\ndecides whether the tax is already included in the product price\n(VAT-style) or added on top (US-style).\n\nMarkets using an external tax provider ignore these rows — that\nprovider carries its own jurisdiction data.\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[included_in_price_true]","in":"query","required":false,"description":"Only rates included in the product price","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"responses":{"200":{"description":"tax rates found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TaxRate"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a tax rate","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a tax rate for the current store. Give either `amount` as a\ndecimal (`0.19`) or `amount_percentage` as a percentage (`19`).\n\nName the jurisdiction with `country_code` (and `state_code` for a\nstate-level rate). Omitting the country makes the rate apply everywhere.\n\nSet `included_in_price` for VAT-style pricing, where the rate is backed\nout of the displayed price rather than added to it.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"tax rate created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxRate"}}}},"422":{"description":"validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Customer-facing rate name, e.g. \"VAT\""},"amount":{"type":"string","description":"Rate as a decimal, e.g. \"0.19\""},"amount_percentage":{"type":"number","description":"Rate as a percentage, e.g. 19"},"included_in_price":{"type":"boolean"},"show_rate_in_label":{"type":"boolean"},"tax_category_id":{"type":"string"},"country_code":{"type":"string","description":"ISO code, e.g. \"DE\". Omit for every country."},"state_code":{"type":"string","description":"State abbreviation within that country, e.g. \"CA\"."}},"required":["name","tax_category_id"]}}},"required":true}}},"/api/v3/admin/tax_rates/{id}":{"parameters":[{"name":"id","in":"path","description":"Tax rate ID","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a tax rate","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"tax rate found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxRate"}}}}}},"patch":{"summary":"Update a tax rate","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"tax rate updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxRate"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"amount":{"type":"string"},"amount_percentage":{"type":"number"},"included_in_price":{"type":"boolean"},"show_rate_in_label":{"type":"boolean"},"tax_category_id":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"}}}}},"required":true}},"delete":{"summary":"Delete a tax rate","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the rate. Tax lines it already produced keep their own rate snapshot.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"tax rate deleted"}}}},"/api/v3/admin/translatable_resources":{"get":{"summary":"List translatable resources","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns every translatable resource type and its translatable fields (key + content type), so clients can render translation editors generically.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"translatable resources found","content":{"application/json":{}}}}}},"/api/v3/admin/translations/batch":{"post":{"summary":"Batch upsert translations","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Atomically upserts translations across many records of (possibly) different translatable resource types in one request — e.g. an option type and all its option values in one save. A flat list of independent registry writes; all entries succeed or none do.\n\n**Required scope:** `write_<resource>` for every resource type in the batch (for API-key authentication) (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"translations upserted","content":{"application/json":{}}},"422":{"description":"unsupported locale rolls back the whole batch","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["translations"],"properties":{"translations":{"type":"array","items":{"type":"object","required":["resource_type","resource_id","values"],"properties":{"resource_type":{"type":"string","description":"Translatable resource type token, e.g. `option_type`"},"resource_id":{"type":"string","description":"Prefixed id of the record"},"values":{"type":"object","description":"Map of locale code to { field: value }","additionalProperties":{"type":"object","additionalProperties":true}}}}}}}}}}}},"/api/v3/admin/admin_users":{"get":{"summary":"List staff","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns admin users with at least one role assignment on the current store.\n\n**Required scope:** `read_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"staff found","content":{"application/json":{}}}}}},"/api/v3/admin/admin_users/{id}":{"get":{"summary":"Show a staff member","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"staff member found","content":{"application/json":{}}}}},"patch":{"summary":"Update a staff member","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates name fields and reassigns roles for the current store. `role_ids` is a complete replacement — roles not in the array are removed for this store.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"staff member updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"role_ids":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Remove a staff member from this store","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes the user's role assignments on the current store. The account is preserved — the user keeps access to any other stores.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"staff removed from store"}}}},"/api/v3/admin/invitations":{"get":{"summary":"List invitations","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns invitations for the current store, including pending and accepted.\n\n**Required scope:** `read_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"invitations found","content":{"application/json":{}}}}},"post":{"summary":"Create an invitation","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Invites a teammate by email. The invitation is scoped to the current store and carries the chosen role; on accept, a `RoleUser` is created via the invitation's `after_accept` callback.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"invitation created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["email","role_id"],"properties":{"email":{"type":"string"},"role_id":{"type":"string"}}}}}}}},"/api/v3/admin/invitations/{id}":{"delete":{"summary":"Revoke an invitation","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"invitation revoked"}}}},"/api/v3/admin/invitations/{id}/resend":{"patch":{"summary":"Resend an invitation","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Issues a fresh token and dispatches the invitation email again.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"invitation resent","content":{"application/json":{}}}}}},"/api/v3/admin/permissions":{"get":{"summary":"List the permission catalog","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the permission catalog — the grant vocabulary shared by staff role permissions and secret API key scopes. Entries are grouped for permission pickers; labels and descriptions are localized. Readable by any authenticated admin credential.","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"catalog returned","content":{"application/json":{}}}}}},"/api/v3/admin/roles":{"get":{"summary":"List roles","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns staff roles with their catalog permissions. Roles are global, not per-store; `mutable: false` marks the protected admin role and host-locked rows.\n\n**Required scope:** `read_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"roles found","content":{"application/json":{}}}}},"post":{"summary":"Create a role","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a staff role. `permissions` holds catalog keys (see GET /admin/permissions); a caller may only grant keys they effectively hold.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"role created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"permissions":{"type":"array","items":{"type":"string"}}},"required":["name"]}}}}}},"/api/v3/admin/roles/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Update a role","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a role name, description or permissions. The admin role and host-locked roles (`mutable: false`) reject changes.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"role updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"permissions":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a role","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a role. Fails with 422 while the role is protected or still referenced by staff members or pending invitations.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"role deleted"},"422":{"description":"role cannot be deleted","content":{"application/json":{}}}}}},"/api/v3/admin/stock_locations":{"get":{"summary":"List stock locations","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the configured stock locations. Stock locations are global\n(shared across stores). Filter with Ransack predicates such as\n`q[active_eq]`, `q[kind_eq]`, `q[pickup_enabled_eq]`, or\n`q[name_cont]`.\n\nPickup-related attributes (`kind`, `pickup_enabled`,\n`pickup_stock_policy`, `pickup_ready_in_minutes`,\n`pickup_instructions`) drive merchant pickup support at checkout —\ncustomers can collect orders from any active location with\n`pickup_enabled: true`.\n\n\n**Required scope:** `read_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[active_eq]","in":"query","required":false,"description":"Filter by active status","schema":{"type":"boolean"}},{"name":"q[kind_eq]","in":"query","required":false,"description":"Filter by kind (built-in: 'warehouse', 'store', 'fulfillment_center')","schema":{"type":"string"}},{"name":"q[pickup_enabled_eq]","in":"query","required":false,"description":"Filter by pickup-enabled flag","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"stock locations found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StockLocation"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a stock location","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new stock location.\n\nSetting `default: true` automatically demotes the previous default\nlocation.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"stock location created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockLocation"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"admin_name":{"type":"string","nullable":true,"description":"Internal name shown only in the admin"},"active":{"type":"boolean"},"default":{"type":"boolean","description":"Setting to true demotes the previous default."},"kind":{"type":"string","enum":["warehouse","store","fulfillment_center"],"description":"Categorizes the location."},"propagate_all_variants":{"type":"boolean"},"backorderable_default":{"type":"boolean"},"address1":{"type":"string","nullable":true},"address2":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true,"description":"ISO-3166 alpha-2 country code (e.g. \"US\")."},"state_code":{"type":"string","nullable":true,"description":"State / province abbreviation (e.g. \"NY\"). Resolved against the selected country."},"state_name":{"type":"string","nullable":true,"description":"Free-text state for countries without a states list."},"pickup_enabled":{"type":"boolean"},"pickup_stock_policy":{"type":"string","enum":["local","any"],"description":"'local' = items at this location only; 'any' = transfer-eligible (ship-to-store)."},"pickup_ready_in_minutes":{"type":"number","nullable":true,"minimum":0},"pickup_instructions":{"type":"string","nullable":true}},"required":["name"]}}}}}},"/api/v3/admin/stock_locations/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Stock location ID","schema":{"type":"string"}}],"get":{"summary":"Get a stock location","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single stock location by prefixed ID.\n\n**Required scope:** `read_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"stock location found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockLocation"}}}},"404":{"description":"stock location not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a stock location","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an existing stock location. Same address-field conventions as\nthe create endpoint.\n\nSetting `default: true` automatically demotes the previous default.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"stock location updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockLocation"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"admin_name":{"type":"string","nullable":true},"active":{"type":"boolean"},"default":{"type":"boolean"},"kind":{"type":"string","enum":["warehouse","store","fulfillment_center"]},"propagate_all_variants":{"type":"boolean"},"backorderable_default":{"type":"boolean"},"address1":{"type":"string","nullable":true},"address2":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"state_name":{"type":"string","nullable":true},"pickup_enabled":{"type":"boolean"},"pickup_stock_policy":{"type":"string","enum":["local","any"]},"pickup_ready_in_minutes":{"type":"number","nullable":true,"minimum":0},"pickup_instructions":{"type":"string","nullable":true}}}}}}},"delete":{"summary":"Delete a stock location","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the stock location (sets `deleted_at`). Existing\nfulfillments that referenced it keep the historical record via\n`Spree::StockLocation.with_deleted`.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"stock location deleted"}}}},"/api/v3/admin/products/{product_id}/variants":{"get":{"summary":"List product variants","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of variants for a product, including the default variant.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., images, prices, stock_levels, option_values). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., sku,price,stock). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"variants found","content":{"application/json":{}}}}},"post":{"summary":"Create a variant","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new variant for a product. Supports nested prices and stock items.\n\nOption types and values are auto-created if they don't exist.\nPrices are upserted by currency. Stock items are upserted by stock location.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"201":{"description":"variant created","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sku":{"type":"string"},"cost_price":{"type":"string"},"cost_currency":{"type":"string"},"weight":{"type":"number"},"height":{"type":"number"},"width":{"type":"number"},"depth":{"type":"number"},"weight_unit":{"type":"string"},"dimensions_unit":{"type":"string"},"track_inventory":{"type":"boolean"},"tax_category_id":{"type":"string"},"options":{"type":"array","description":"A variant on a product with option types should declare its option pairs (e.g. size + color) — one per option type it participates in. Option types and values are auto-created if missing.","items":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string"},"value":{"type":"string"}}}},"position":{"type":"integer"},"barcode":{"type":"string"},"prices":{"type":"array","description":"Per-currency prices. Upserted by currency.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"stock_levels":{"type":"array","description":"Per-stock-location inventory. Upserted by stock_location_id.","items":{"type":"object","required":["stock_location_id","count_on_hand"],"properties":{"stock_location_id":{"type":"string","description":"Stock location ID (e.g. sloc_xxx)"},"count_on_hand":{"type":"integer"},"backorderable":{"type":"boolean"}}}}}}}}}}},"/api/v3/admin/products/{product_id}/variants/{id}":{"get":{"summary":"Get a variant","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single variant by ID.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Variant ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., images, prices, stock_levels, option_values). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., sku,price,stock). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"variant found","content":{"application/json":{}}},"404":{"description":"variant not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a variant","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a variant. Only provided fields are updated.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Variant ID","schema":{"type":"string"}}],"responses":{"200":{"description":"variant updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sku":{"type":"string"},"cost_price":{"type":"string"},"cost_currency":{"type":"string"},"weight":{"type":"number"},"height":{"type":"number"},"width":{"type":"number"},"depth":{"type":"number"},"weight_unit":{"type":"string"},"dimensions_unit":{"type":"string"},"track_inventory":{"type":"boolean"},"tax_category_id":{"type":"string"},"options":{"type":"array","description":"One pair per option type the variant participates in (e.g. size + color). Option types and values are auto-created if missing.","items":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string"},"value":{"type":"string"}}}},"position":{"type":"integer"},"barcode":{"type":"string"},"prices":{"type":"array","description":"Per-currency prices. Upserted by currency.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"stock_levels":{"type":"array","description":"Per-stock-location inventory. Upserted by stock_location_id.","items":{"type":"object","required":["stock_location_id","count_on_hand"],"properties":{"stock_location_id":{"type":"string","description":"Stock location ID (e.g. sloc_xxx)"},"count_on_hand":{"type":"integer"},"backorderable":{"type":"boolean"}}}}}}}}}},"delete":{"summary":"Delete a variant","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes a variant.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Variant ID","schema":{"type":"string"}}],"responses":{"204":{"description":"variant deleted"}}}},"/api/v3/admin/webhook_endpoints/{webhook_endpoint_id}/deliveries":{"parameters":[{"name":"webhook_endpoint_id","in":"path","required":true,"description":"Parent webhook endpoint ID","schema":{"type":"string"}}],"get":{"summary":"List webhook deliveries","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns delivery attempts for the given endpoint, most recent first.\nEach row carries the original request payload, the response code\n(when the receiver replied), the execution time, and any transport\nerror — everything needed to audit failures and decide whether to\nredeliver.\n\n\n**Required scope:** `read_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[event_name_eq]","in":"query","required":false,"description":"Filter by event name (exact)","schema":{"type":"string"}},{"name":"q[success_eq]","in":"query","required":false,"description":"Filter by success flag","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-delivered_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"deliveries found","content":{"application/json":{}}},"404":{"description":"parent webhook endpoint not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/webhook_endpoints/{webhook_endpoint_id}/deliveries/{id}":{"parameters":[{"name":"webhook_endpoint_id","in":"path","required":true,"description":"Parent webhook endpoint ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Webhook delivery ID","schema":{"type":"string"}}],"get":{"summary":"Get a webhook delivery","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single delivery attempt with the full request payload and\nthe response body the receiver returned. Use this for ad-hoc debug\nof failed deliveries.\n\n\n**Required scope:** `read_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"delivery found","content":{"application/json":{}}},"404":{"description":"delivery not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/webhook_endpoints/{webhook_endpoint_id}/deliveries/{id}/redeliver":{"parameters":[{"name":"webhook_endpoint_id","in":"path","required":true,"description":"Parent webhook endpoint ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Webhook delivery ID to redeliver","schema":{"type":"string"}}],"post":{"summary":"Redeliver a webhook delivery","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new delivery row with the same payload + event_name and\nqueues it. The original row is preserved for audit history.\n\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"redelivery queued","content":{"application/json":{}}}}}},"/api/v3/admin/webhook_endpoints":{"get":{"summary":"List webhook endpoints","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns outbound webhook subscriptions for the current store. Each\nendpoint receives a signed POST when any subscribed event fires.\n`secret_key` is `null` on list reads — the plaintext is delivered\nexactly once on create.\n\n\n**Required scope:** `read_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[url_cont]","in":"query","required":false,"description":"Filter by URL (contains)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"webhook endpoints found","content":{"application/json":{}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new outbound webhook subscription. The plaintext\n`secret_key` is returned **once** in this response — persist it\nimmediately to verify incoming webhook signatures. Subsequent reads\nreturn `null` for the secret. Pass an empty `subscriptions` array or\nomit it to receive every event.\n\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"webhook endpoint created — secret_key returned once","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"name":{"type":"string"},"url":{"type":"string"},"active":{"type":"boolean"},"subscriptions":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/webhook_endpoints/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook endpoint ID","schema":{"type":"string"}}],"get":{"summary":"Get a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single webhook endpoint by prefixed ID.\n\n**Required scope:** `read_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"webhook endpoint found","content":{"application/json":{}}},"404":{"description":"webhook endpoint not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates name, URL, active flag, or the event subscription list.\nToggling `active` here is equivalent to calling `disable`/`enable`\nwithout an audit reason.\n\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"webhook endpoint updated","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string"},"active":{"type":"boolean"},"subscriptions":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the endpoint and stops future deliveries.\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"webhook endpoint deleted"}}}},"/api/v3/admin/webhook_endpoints/{id}/send_test":{"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook endpoint ID","schema":{"type":"string"}}],"post":{"summary":"Send a test delivery","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a `webhook.test` delivery record and queues it. Use this to\nverify the endpoint is reachable and your signature verification\naccepts Spree's payloads.\n\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"test delivery queued","content":{"application/json":{}}}}}},"/api/v3/admin/webhook_endpoints/{id}/enable":{"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook endpoint ID","schema":{"type":"string"}}],"patch":{"summary":"Re-enable a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Re-enables an endpoint that was manually or automatically disabled.\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"webhook endpoint enabled","content":{"application/json":{}}}}}},"/api/v3/admin/webhook_endpoints/{id}/disable":{"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook endpoint ID","schema":{"type":"string"}}],"patch":{"summary":"Disable a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Manually pauses an endpoint. Unlike auto-disable (triggered after\nrepeated delivery failures), no notification email is sent.\n\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"webhook endpoint disabled","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}}}},"/api/v3/admin/catalogs":{"get":{"summary":"List catalogs","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the store catalogs — product assortments with an optional price list, shown to audiences through assignments.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"catalogs found","content":{"application/json":{}}}}},"post":{"summary":"Create a catalog","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a catalog. Add products and assign audiences (customer group, or company subtree) afterwards.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"catalog created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"active":{"type":"boolean"},"price_list":{"type":"object","nullable":true,"description":"The price list this catalog owns, written inline. Omit for assortment-only (base prices); send null to remove the pricing, which deletes the list. A catalog with an empty assortment prices without restricting visibility; import or curate products to make it restrictive.","properties":{"price_adjustment_percentage":{"type":"string","nullable":true},"adjust_compare_at":{"type":"boolean"}}}},"required":["name"]}}}}}},"/api/v3/admin/catalogs/{id}/assign":{"post":{"summary":"Assign a catalog to an audience","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Shows the catalog to an audience. A company assignment covers the node and its whole subtree.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"catalog assigned","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"assignable_type":{"type":"string","enum":["customer_group","company"]},"assignable_id":{"type":"string"}},"required":["assignable_type","assignable_id"]}}}}}},"/api/v3/admin/catalogs/{catalog_id}/products":{"get":{"summary":"List catalog products","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The catalog's curated assortment, listed by product name — membership\ncarries no order.\n\n`expand=catalog_price` adds what a buyer on this agreement pays for\neach row and where the amount comes from: `explicit` (an amount\nentered on the catalog's own price list), `automatic` (that list's\npercentage applied to the shop price) or `base` (the shop price\nitself — this agreement does not price the product).\n\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated. `catalog_price` adds the resolved price to every row.","schema":{"type":"string"}}],"responses":{"200":{"description":"products found, with what the agreement charges","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CatalogProduct"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Add products to a catalog","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Curates products into the assortment in bulk. Already-present products are skipped; the count reports what was added.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"products added","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}},"delete":{"summary":"Remove products from a catalog","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes products from the assortment in bulk. Ids that are not members are ignored; the count reports what was removed.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products removed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}}},"/api/v3/admin/catalogs/{catalog_id}/order_minimums":{"get":{"summary":"List catalog order minimums","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The least a whole order must come to under this agreement. One row per currency — Spree holds no exchange rates, so a threshold is never stated once and converted.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"order minimums found","content":{"application/json":{}}}}},"post":{"summary":"Create a catalog order minimum","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Requires orders in one currency to reach an amount. The buyer sees the shortfall on the cart while they can still act on it; completion is refused below it.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"order minimum created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"currency":{"type":"string"},"amount":{"type":"string"}},"required":["currency","amount"]}}}}}},"/api/v3/admin/catalogs/{catalog_id}/order_minimums/{id}":{"patch":{"summary":"Update a catalog order minimum","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Restates one currency's threshold.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"order minimum updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string"}}}}}}},"delete":{"summary":"Delete a catalog order minimum","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Lifts the threshold for one currency, so orders in it may come to any total.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"order minimum deleted"}}}},"/api/v3/admin/catalogs/{catalog_id}/quantity_rules":{"put":{"summary":"Set catalog quantity rules","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Writes the given products' quantity terms in one request, keyed by prefixed product id. The stated pair is written to every variant of the product, which is the grain the database keeps them at. Both fields null clears that product's terms; a product not yet in the assortment is added, since a term with nothing to apply to is not a reachable state. Products absent from the payload are left alone — an agreement may name terms for thousands of SKUs. Read them back on the assortment rows: `GET /catalogs/{id}/products?expand=quantity_rule`.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"quantity rules set"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"terms":{"type":"object","additionalProperties":{"type":"object","properties":{"minimum_order_quantity":{"type":"integer","nullable":true},"order_multiple":{"type":"integer","nullable":true}}}}},"required":["terms"]}}}}}},"/api/v3/admin/catalogs/{id}/activate":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Activate a catalog","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Puts the agreement into effect: its audience starts seeing its\nassortment and paying its prices. Refused for a catalog nobody is\nassigned to, since activating it would reach no buyer — a channel's\ndefault catalog is reached through the channel instead, so it needs\nno assignment.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"catalog activated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Catalog"}}}}}}},"/api/v3/admin/catalogs/{id}/deactivate":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Deactivate a catalog","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Takes the agreement out of effect. Everything it holds — assignments,\ncommercial terms, its price list — survives, so activating again\nresumes exactly what was there.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"catalog deactivated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Catalog"}}}}}}},"/api/v3/admin/collections":{"get":{"summary":"List collections","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of the store's collections.\n\n**Required scope:** `read_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., rules, custom_fields, translations).","schema":{"type":"string"}}],"responses":{"200":{"description":"collections found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Collection"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a manual or automatic (rule-based) collection. For automatic collections, send the full desired rule set under `rules`.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"collection created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"automatic":{"type":"boolean"},"rules_match_policy":{"type":"string","enum":["all","any"]},"sort_order":{"type":"string"},"permalink":{"type":"string"},"description":{"type":"string"},"meta_title":{"type":"string"},"meta_description":{"type":"string"},"meta_keywords":{"type":"string"},"rules":{"type":"array","description":"Full desired rule set. Entries with an id update, id-less entries create, omitted rules are removed.","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"value":{"type":"string"},"match_policy":{"type":"string"}}}}},"required":["name"]}}}}}},"/api/v3/admin/collections/{id}":{"get":{"summary":"Get a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single collection by ID, including its rules.\n\n**Required scope:** `read_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., rules, custom_fields, translations).","schema":{"type":"string"}}],"responses":{"200":{"description":"collection found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}},"404":{"description":"collection not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a collection. Send `position` to reorder it within the flat list; send the full `rules` set to sync automatic rules.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}}],"responses":{"200":{"description":"collection updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"permalink":{"type":"string"},"description":{"type":"string"},"meta_title":{"type":"string"},"meta_description":{"type":"string"},"meta_keywords":{"type":"string"},"sort_order":{"type":"string"},"automatic":{"type":"boolean"},"rules_match_policy":{"type":"string","enum":["all","any"]},"position":{"type":"integer","description":"Reorders the collection within the flat list (acts_as_list)"},"rules":{"type":"array","description":"Full desired rule set (see create).","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"value":{"type":"string"},"match_policy":{"type":"string"}}}}}}}}}},"delete":{"summary":"Delete a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a collection.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}}],"responses":{"204":{"description":"collection deleted"}}}},"/api/v3/admin/collections/{collection_id}/products":{"get":{"summary":"List collection products","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Products curated in the collection, ordered by their membership position.\n\n**Required scope:** `read_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"collection_id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}}],"responses":{"200":{"description":"products found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Add products to a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Curates products into the collection in bulk (appended to the end). Already-curated products are skipped; the count reports what was added.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"collection_id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}}],"responses":{"201":{"description":"products added","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}},"delete":{"summary":"Remove products from a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes products from the collection's manual curation in bulk. Ids that are not curated are ignored; the count reports what was removed.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"collection_id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}}],"responses":{"200":{"description":"products removed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}}},"/api/v3/admin/collections/{collection_id}/products/{id}/reposition":{"patch":{"summary":"Reposition a collection product","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Moves a product to a new index among the collection's products.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"collection_id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"204":{"description":"product repositioned"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"new_position":{"type":"integer","description":"0-based index among the collection's products"}},"required":["new_position"]}}}}}},"/api/v3/admin/collection_rules/types":{"get":{"summary":"List available collection rule types","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Enumerates the registered rule kinds with their labels and descriptions — drives the rule picker on an automatic collection. Plugins extend the list by registering `Spree::CollectionRule` subclasses via `config.spree.collection_rules`. The `type` returned here is the wire shorthand accepted when writing a collection's `rules`.\n\n**Required scope:** `read_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"types found","content":{"application/json":{}}}}}},"/api/v3/admin/commission_lines":{"get":{"summary":"List commission lines","tags":["Commission Lines"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"What each sale actually earned the marketplace, frozen when the order\nwas placed. A later change to a commission rate never reaches these.\n\n`amount` is the fee charged to the seller and `tax_amount` is the VAT on\nthat fee — the marketplace's own service to the seller, a supply\nseparate from the sale itself, which is why the two are not folded\ntogether. `total` is their sum.\n\nOne line per commissioned item, plus one per delivery when the rate that\napplied charges shipping too — read `line_item_id` and `fulfillment_id`\nto tell them apart.\n\nRead-only: correcting a charge is a reversal, not an edit.\n\n\n**Required scope:** `read_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[seller_id_eq]","in":"query","required":false,"description":"Filter to one seller","schema":{"type":"string"}},{"name":"q[order_id_eq]","in":"query","required":false,"description":"Filter to one order","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed (e.g., `commission_rate`).","schema":{"type":"string"}}],"responses":{"200":{"description":"commission lines found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CommissionLine"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/commission_lines/{id}":{"parameters":[{"name":"id","in":"path","description":"Commission line ID","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a commission line","tags":["Commission Lines"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"commission line found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommissionLine"}}}},"404":{"description":"commission line not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/commission_rates":{"get":{"summary":"List commission rates","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"What the marketplace charges its sellers.\n\nRates are returned in resolution order: the list is walked top-down and\nthe first rate whose targeting matches the sale wins, so the order you\nsee is the precedence. Move a rate with `position` on update.\n\nA rate carrying no rules matches every sale — `global` says so — which\nis how a marketplace expresses a single default. Because resolution\nstops at the first match, a global rate makes everything below it\nunreachable, so it belongs at the bottom.\n\n\n**Required scope:** `read_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[enabled_eq]","in":"query","required":false,"description":"Filter by whether the rate is in use","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-position`).","schema":{"type":"string"}}],"responses":{"200":{"description":"commission rates found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CommissionRate"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a commission rate","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Sets what the marketplace charges, and which sales it applies to.\n\n`rules` is the rate's whole targeting, sent inline. Every rule has to\nhold, and a rule naming several records means any of them — so\n\"(Cameras OR Audio) AND that seller\" is a category rule holding two ids\nbeside a seller rule holding one. Send no rules to charge every sale.\n\nRule kinds come from `GET /commission_rates/rule_types`, which also\ndescribes the configuration each one takes. A marketplace that adds its\nown kind sees it there without this endpoint changing.\n\n`commission_tax_rate` is VAT on the commission itself — the\nmarketplace's own service to the seller, a separate supply from the\nsale. Leave it null to let the store's tax engine answer for wherever\nthe seller's business sits.\n\n\n**Required scope:** `write_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"commission rate created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommissionRate"}}}},"422":{"description":"validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name","kind","value"],"properties":{"name":{"type":"string"},"code":{"type":"string","nullable":true,"description":"Your own identifier for this rate; unique per store."},"enabled":{"type":"boolean"},"position":{"type":"integer","description":"Place in the list. Rates resolve top-down, so 1 is tried first. New rates are created at the top; send this to move one."},"kind":{"type":"string","enum":["percentage","fixed"]},"value":{"type":"string","description":"A percentage (10 = 10%) or a flat amount, per `kind`."},"amounts":{"type":"object","additionalProperties":{"type":"string"},"description":"What a flat fee charges, keyed by currency. A currency with no amount is one this rate does not charge — those sales fall to the next rate. Ignored for a percentage."},"tax_inclusive":{"type":"boolean","description":"Charge on the price including the customer's VAT. Left off, commission is charged on the seller's net revenue, which is the usual basis where the fee is taxed as its own supply."},"include_shipping":{"type":"boolean","description":"Also charge commission on the seller's delivery revenue."},"bounds":{"type":"object","additionalProperties":{"type":"object","properties":{"min_amount":{"type":"string","nullable":true},"max_amount":{"type":"string","nullable":true}}},"description":"The floor and cap a percentage charges within, keyed by currency. Each holds only in its own currency; a sale in a currency with no bounds is charged unbounded."},"commission_tax_rate":{"type":"string","nullable":true,"description":"A fraction, not a percentage. Null asks the tax engine."},"rules":{"type":"array","description":"The full targeting; what you send replaces what the rate holds.","items":{"type":"object","properties":{"id":{"type":"string","description":"Present for an existing rule; omit to create one."},"type":{"type":"string","description":"A kind from /commission_rates/rule_types."},"preferences":{"type":"object","description":"Configuration for the kind, per its preference_schema."},"product_ids":{"type":"array","items":{"type":"string"},"description":"For kinds that name products, which are kept outside preferences."}}}}}}}}}}},"/api/v3/admin/commission_rates/rule_types":{"get":{"summary":"List the commission rule kinds","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Every rule kind a rate can be narrowed by, with the schema describing\nthe configuration it takes — so a client builds its editor from what\nthis marketplace has rather than a list hardcoded to match core's.\n\n`association_fields` names any catalog-scale reference a kind keeps\noutside its preferences, so an editor knows to render a picker for it.\n\n\n**Required scope:** `read_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"subject types found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"preference_schema":{"type":"array","items":{"type":"object"}},"association_fields":{"type":"array","items":{"type":"string"}}}}}}}}}}}}},"/api/v3/admin/commission_rates/{id}":{"parameters":[{"name":"id","in":"path","description":"Commission rate ID","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a commission rate","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"commission rate found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommissionRate"}}}},"404":{"description":"commission rate not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a commission rate","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Editing a rate changes what the next sale is charged, never what a past\none was: commission lines keep their own snapshot of the rate that\napplied.\n\n\n**Required scope:** `write_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"commission rate updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommissionRate"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"enabled":{"type":"boolean"},"position":{"type":"integer"},"value":{"type":"string"},"rules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"preferences":{"type":"object"},"product_ids":{"type":"array","items":{"type":"string"}}}}}}}}}}},"delete":{"summary":"Delete a commission rate","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"commission rate deleted"}}}},"/api/v3/admin/companies/{company_id}/memberships":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List company members","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the people with standing over this node. Standing covers the node and everything below it in the tree.\n\n**Required scope:** `read_customers` (for API-key authentication).","responses":{"200":{"description":"members found","content":{"application/json":{}}}}},"post":{"summary":"Add a member by email","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a person to the node by email. An email matching an existing customer becomes a\nmembership immediately (a `cmem_…` id); an unknown email becomes an invitation\n(a `cinv_…` id) and the invite email goes out.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[],"responses":{"201":{"description":"member added","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"customer_email":{"type":"string"}},"required":["customer_email"]}}}}}},"/api/v3/admin/companies/{company_id}/tax_exemption_certificates":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List tax exemption certificates","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a business's exemption evidence. `active` is the field that decides whether a certificate\nexempts a sale: a verified certificate stops counting once its expiry date passes, so the status\nalone does not answer it.\n\n\n**Required scope:** `read_customers` (for API-key authentication).","responses":{"200":{"description":"certificates found","content":{"application/json":{}}}}},"post":{"summary":"Create a tax exemption certificate","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Records exemption evidence against a business. Certificates start `pending` and exempt nothing\nuntil verified.\n\n`country_code` and `state_code` say where the certificate holds — omit both for one valid\neverywhere, give only the country for one valid throughout it. `document` takes an ActiveStorage\nsigned blob id obtained from `POST /api/v3/admin/direct_uploads`.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[],"responses":{"201":{"description":"certificate created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"certificate_number":{"type":"string"},"reason_code":{"type":"string","description":"Becomes the tax provider's entity use code."},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"expires_at":{"type":"string","format":"date-time","nullable":true},"issuing_authority":{"type":"string","nullable":true},"document":{"type":"string","description":"ActiveStorage signed blob id from POST /api/v3/admin/direct_uploads."}},"required":["certificate_number","reason_code"]}}}}}},"/api/v3/admin/companies/{company_id}/tax_exemption_certificates/{id}/verify":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Verify a tax exemption certificate","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Accepts the certificate as evidence, which is what makes it exempt sales. Only a pending\ncertificate can be accepted — re-accepting a revoked one would restore evidence that was\ndeliberately withdrawn. An installation that checks numbers against a registry, or requires a\nsecond approval, can refuse here, and the refusal is returned as a validation error.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","responses":{"200":{"description":"certificate verified","content":{"application/json":{}}}}}},"/api/v3/admin/companies/{company_id}/tax_exemption_certificates/{id}/revoke":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Revoke a tax exemption certificate","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Withdraws accepted evidence. A verified certificate cannot be deleted — how a sale was taxed has to remain explainable — so revoking is the way out.\n\n**Required scope:** `write_customers` (for API-key authentication).","responses":{"200":{"description":"certificate revoked","content":{"application/json":{}}}}}},"/api/v3/admin/companies/{company_id}/tax_exemption_certificates/{id}/download":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Download a certificate document","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Streams the uploaded document. Deliberately not a storage link: the bytes come through the API so\nthe same credentials apply to every read of a confidential document. Requires only read access.\n\n\n**Required scope:** `read_customers` (for API-key authentication).","responses":{"200":{"description":"document streamed","content":{"application/json":{}}},"422":{"description":"no document attached","content":{"application/json":{}}}}}},"/api/v3/admin/companies/{company_id}/tax_identifiers":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List company tax registrations","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the business's tax registrations, one per kind. A business registration takes precedence\nover the buyer's own when a sale is for that business, because the invoice is addressed to the\nentity rather than the person who placed the order.\n\n\n**Required scope:** `read_customers` (for API-key authentication).","responses":{"200":{"description":"registrations found","content":{"application/json":{}}}}},"post":{"summary":"Create a company tax registration","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Registers a tax number against the business. Verification against the relevant registry runs in\nthe background where a validator is installed for the kind; a stock installation registers none,\nleaving the status unattempted.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[],"responses":{"201":{"description":"registration created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","description":"The regime the number belongs to."},"value":{"type":"string"}},"required":["kind","value"]}}}}}},"/api/v3/admin/companies/{company_id}/tax_identifiers/{id}/validate":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Re-check a company tax registration","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Asks the registry again. Manual because a registry answers only \"valid now\" — a number verified\nlast year may have been deregistered since — and because a check that came back unavailable\ncannot otherwise be retried without editing the number.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","responses":{"422":{"description":"no validator installed for this kind","content":{"application/json":{}}}}}},"/api/v3/admin/companies":{"get":{"summary":"List companies","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the business customers of the current store.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"companies found","content":{"application/json":{}}}}},"post":{"summary":"Create a company","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a company node. A root node is a legal entity; pass parent_id and kind to build the organization tree. Exemption certificates and tax registrations hang off legal-entity nodes.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"company created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"kind":{"type":"string","enum":["company","division"],"description":"company = legal entity (may hold tax registrations), division = organizational unit. Roots must be company."},"parent_id":{"type":"string","nullable":true,"description":"The parent node. Omit for a root."},"external_references":{"type":"array","description":"Identities this business has in your own systems. A system you do not name keeps the reference it already has, and creating with a reference that already exists updates that business instead.","items":{"type":"object","properties":{"system":{"type":"string"},"external_id":{"type":"string"}},"required":["system","external_id"]}}},"required":["name"]}}}}}},"/api/v3/admin/custom_field_definitions/resource_types":{"get":{"summary":"List what custom fields can be attached to","tags":["Custom Field Definitions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The resources a definition can describe, from the server's own\nregistry (`Spree.custom_fields.enabled_resources`).\n\nRead this rather than carrying a list: a resource an extension\nregisters appears here without a client release, and a `resource_type`\nthat is not listed is refused on create.\n\n`resource_type` is the value to send; `name` is what a merchant calls\nit. The two differ where a class has been renamed — categories are\nstored under `Spree::Taxon` and shown as \"Categories\" — so send the\nvalue back verbatim rather than deriving it from the name.\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"resource types found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"resource_type":{"type":"string"},"name":{"type":"string"}}}}}}}}}}}},"/api/v3/admin/delivery_profiles":{"get":{"summary":"List delivery profiles","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Fulfillment profiles group products with the stock locations, delivery zones and delivery methods that fulfill them. Every store has exactly one default profile.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"delivery profiles found","content":{"application/json":{}}}}},"post":{"summary":"Create a delivery profile","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a delivery profile. `kind` selects the registered profile kind (shipping, digital, extension kinds); `stock_location_ids` limits fulfillment to those locations — empty means every store location.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"delivery profile created","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"kind":{"type":"string","description":"Registered profile kind; defaults to shipping."},"default":{"type":"boolean"},"stock_location_ids":{"type":"array","items":{"type":"string"},"description":"Empty means every store location."}},"required":["name"]}}}}}},"/api/v3/admin/delivery_profiles/{delivery_profile_id}/origin_groups":{"parameters":[{"name":"delivery_profile_id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Create an origin group","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Origin groups partition a profile's fulfillment origins: zones and methods belong to a group, so the same products can quote different rate tables per warehouse. `stock_location_ids` replaces the full membership; empty means every store location.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"origin group created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","nullable":true},"position":{"type":"integer","nullable":true},"stock_location_ids":{"type":"array","items":{"type":"string"},"description":"Empty means every store location."}}}}}}}},"/api/v3/admin/delivery_profiles/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Update a delivery profile","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"delivery profile updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"default":{"type":"boolean"},"stock_location_ids":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a delivery profile","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The default profile and profiles still referenced by products cannot be deleted.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"delivery profile deleted"}}}},"/api/v3/admin/delivery_methods":{"get":{"summary":"List delivery methods","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all delivery methods with calculator and zone configuration.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"delivery methods found","content":{"application/json":{}}}}},"post":{"summary":"Create delivery method","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a delivery method inside a delivery profile (defaults to the store default profile). Delivery behavior comes from the fulfillment provider.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"delivery method created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"admin_name":{"type":"string","nullable":true},"code":{"type":"string","nullable":true},"fulfillment_provider":{"type":"string","nullable":true},"delivery_profile_id":{"type":"string","nullable":true},"storefront_visible":{"type":"boolean"},"tracking_url":{"type":"string","nullable":true},"estimated_transit_business_days_min":{"type":"integer","nullable":true},"estimated_transit_business_days_max":{"type":"integer","nullable":true},"tax_category_id":{"type":"string","nullable":true},"calculator_type":{"type":"string"},"calculator_preferences":{"type":"object"},"delivery_zone_id":{"type":"string","nullable":true}},"required":["name"]}}}}}},"/api/v3/admin/delivery_methods/calculators":{"get":{"summary":"List delivery calculators","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Registered delivery calculator classes with preference schemas for building configuration forms.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"calculators found","content":{"application/json":{}}}}}},"/api/v3/admin/delivery_zones":{"post":{"summary":"Create delivery zone","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a delivery zone with typed members: country, state, or postal_code (prefix or from/to range).\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed, e.g. `members`","schema":{"type":"string"}}],"responses":{"201":{"description":"delivery zone created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"members":{"type":"array","items":{"type":"object","properties":{"member_type":{"type":"string","enum":["country","state","postal_code"]},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"postal_code_prefix":{"type":"string","nullable":true},"postal_code_from":{"type":"string","nullable":true},"postal_code_to":{"type":"string","nullable":true}},"required":["member_type"]}}},"required":["name"]}}}}}},"/api/v3/admin/integrations":{"get":{"summary":"List integrations","tags":["Integrations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the integrations connected to the current store. Secret preference values are masked.\n\n**Required scope:** `read_integrations` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"integrations found","content":{"application/json":{}}}}},"post":{"summary":"Connect integration","tags":["Integrations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Connects an integration type to the current store. Setting active: true verifies the connection and fails with 422 when it cannot connect. Submitting a masked secret value back keeps the stored secret.\n\n**Required scope:** `write_integrations` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"integration connected","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"Wire shorthand from GET /integrations/types"},"active":{"type":"boolean"},"preferences":{"type":"object"}},"required":["type"]}}}}}},"/api/v3/admin/integrations/types":{"get":{"summary":"List integration types","tags":["Integrations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Every registered integration type with its gallery metadata and configuration schema. Pure registry discovery — read live connection state from GET /integrations.\n\n**Required scope:** `read_integrations` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"integration types found","content":{"application/json":{}}}}}},"/api/v3/admin/integrations/{id}/test":{"post":{"summary":"Test integration connection","tags":["Integrations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Runs a live connection check against the provider. Nothing is persisted; a failed check reports the seller error message.\n\n**Required scope:** `write_integrations` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"connection checked","content":{"application/json":{}}}}}},"/api/v3/admin/media":{"get":{"summary":"List media","tags":["Media"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns every file in the store's media library, whether or not it has\nbeen placed on a product. Filter with `q[unattached]=true` for files not\nyet in use, `q[media_type_eq]` for images or video, and\n`q[filename_cont]` to search by file name.\n\n\n**Required scope:** `read_media` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}}],"responses":{"200":{"description":"media found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Media"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Upload a file to the library","tags":["Media"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a file to the library without placing it on anything. Upload the\nfile first through the direct-upload endpoint, then send the signed id\nhere. Put the file on a product by posting to that product's media with\nthis record's id as `source_media_id`.\n\n\n**Required scope:** `write_media` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"file added","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Media"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"signed_id":{"type":"string","description":"Direct-upload signed id for the file."},"alt":{"type":"string"},"media_type":{"type":"string","enum":["image","video","external_video"]},"external_video_url":{"type":"string","description":"YouTube or Vimeo link, for an external video."}}}}}}}},"/api/v3/admin/media/{id}/usage":{"parameters":[{"name":"id","in":"path","description":"Media ID","required":true,"schema":{"type":"string"}}],"get":{"summary":"Where a file is used","tags":["Media"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Lists everywhere this file appears: products it is placed on, image\nfields that picked it, and descriptions embedding it. Reusing a file\nshares it rather than copying it, so deleting one placement can leave\nothers pointing at the same file — check this first.\n\nDescription matches are best-effort: an embedded image is a plain URL\nwith nothing recording it, so treat an empty result as \"nothing found\",\nnot proof the file is unused.\n\n\n**Required scope:** `read_media` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"usage found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["media","attachment","rich_text"]},"name":{"type":"string","nullable":true},"owner_type":{"type":"string"},"owner_id":{"type":"string","nullable":true},"field":{"type":"string","nullable":true}}}}}}}}}}}},"/api/v3/admin/products/{product_id}/media":{"parameters":[{"name":"product_id","in":"path","description":"Product ID","required":true,"schema":{"type":"string"}}],"post":{"summary":"Place a library file on a product","tags":["Media"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Puts a file that is already in the library onto this product. The new\nrecord shares the source's file rather than copying it, so nothing is\nuploaded and no image is reprocessed; it carries its own alt text,\nposition and variant links from here on.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"file placed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Media"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"source_media_id":{"type":"string","description":"A media record already in the library."},"alt":{"type":"string"},"position":{"type":"integer"}},"required":["source_media_id"]}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/deliveries":{"get":{"summary":"List deliveries","tags":["Deliveries"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The consignments of a parcel — one per tracking number, each with the carrier status last reported.\n\n**Required scope:** `read_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"deliveries found","content":{"application/json":{}}}}},"post":{"summary":"Record a delivery","tags":["Deliveries"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a tracked consignment to a parcel — a second box, or a freight PRO number covering several pallets. The carrier is free text.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"201":{"description":"delivery recorded","content":{"application/json":{}}},"422":{"description":"tracking number already recorded on this parcel","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["tracking_number"],"properties":{"tracking_number":{"type":"string","description":"Carrier tracking number, freight PRO number, or a full tracking link"},"carrier":{"type":"string","description":"Free-text carrier; detected from the number when omitted"},"service":{"type":"string","description":"Carrier service"},"tracking_url":{"type":"string","description":"Tracking page for this consignment"}}}}},"required":true}}},"/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/deliveries/{id}":{"patch":{"summary":"Correct a delivery","tags":["Deliveries"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Corrects the tracking number, carrier or link. A corrected number starts the carrier journey over.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Delivery ID","schema":{"type":"string"}}],"responses":{"200":{"description":"delivery updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tracking_number":{"type":"string"},"carrier":{"type":"string"},"service":{"type":"string"},"tracking_url":{"type":"string"}}}}},"required":true}},"delete":{"summary":"Delete a delivery","tags":["Deliveries"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes a hand-entered consignment. One a label minted is refused — refund the label instead.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Delivery ID","schema":{"type":"string"}}],"responses":{"204":{"description":"delivery deleted"}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/deliveries/{id}/mark_delivered":{"patch":{"summary":"Mark a delivery delivered","tags":["Deliveries"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Staff confirming one consignment arrived. The parcel becomes delivered once every one of its consignments has.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Delivery ID","schema":{"type":"string"}}],"responses":{"200":{"description":"delivery marked delivered","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"delivered_at":{"type":"string","format":"date-time","description":"When it arrived. Defaults to now."},"notify_customer":{"type":"boolean","description":"Whether the customer gets a delivery notification when the parcel completes."}}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/labels":{"get":{"summary":"List shipping labels","tags":["Shipping Labels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Every label bought or uploaded for a parcel, refunded ones included.\n\n**Required scope:** `read_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"labels found","content":{"application/json":{}}}}},"post":{"summary":"Buy or record a shipping label","tags":["Shipping Labels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"With no body, buys the label through the parcel's carrier account. With a `file`, records a label bought elsewhere. Either way the tracking number becomes a delivery on the parcel.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"201":{"description":"label purchased","content":{"application/json":{}}},"422":{"description":"provider does not produce labels","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"file":{"type":"string","description":"Signed blob id of an uploaded label file; its presence records rather than buys"},"tracking_number":{"type":"string","description":"Number printed on an uploaded label"},"carrier":{"type":"string","description":"Free-text carrier; detected from the number when omitted"},"service":{"type":"string","description":"Carrier service the label was bought at"},"cost":{"type":"string","description":"What the merchant paid the carrier"},"currency":{"type":"string","description":"Currency of the cost"},"file_format":{"type":"string","enum":["pdf","png","zpl"],"description":"Label file format; taken from the file when omitted"},"tracking_url":{"type":"string","description":"Tracking page for the consignment"}}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/labels/{id}":{"get":{"summary":"Get a shipping label","tags":["Shipping Labels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"One label, with what it cost and where to print it from.\n\n**Required scope:** `read_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Shipping label ID","schema":{"type":"string"}}],"responses":{"200":{"description":"label found","content":{"application/json":{}}}}},"delete":{"summary":"Delete an uploaded label","tags":["Shipping Labels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes an uploaded label. A purchased label is refunded instead, so the postage history stays honest.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Shipping label ID","schema":{"type":"string"}}],"responses":{"204":{"description":"label deleted"}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/labels/{id}/refund":{"patch":{"summary":"Refund a shipping label","tags":["Shipping Labels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Asks the carrier to refund a purchased label. The consignment it minted is removed when the parcel never shipped.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Shipping label ID","schema":{"type":"string"}}],"responses":{"200":{"description":"refund filed","content":{"application/json":{}}},"422":{"description":"uploaded labels cannot be refunded","content":{"application/json":{}}}}}},"/api/v3/admin/package_types":{"get":{"summary":"List package types","tags":["Package Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the store's packaging vocabulary: the box it ships parcels in\nand the cartons, pallets and containers a wholesale order leaves on.\n\n`volume` is the cubic meters the package occupies, converted from\nwhatever unit its dimensions were recorded in — the figure freight\nvolume rules compare against. It is null until all three sides are\nmeasured.\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[kind_eq]","in":"query","required":false,"description":"Filter by kind (`box`, `envelope`, `carton`, `pallet`, `container`)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"responses":{"200":{"description":"package types found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PackageType"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a package type","tags":["Package Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a kind of packaging to the store.\n\n`weight` is the empty package's own weight, added to content weight on\nevery quote; `max_weight` is what it can hold. Setting `default` makes\nthis the box every parcel quote is built on, and demotes whichever row\nheld that before.\n\nA variant references a `carton`-kind row to say what it is packed\ninto; other kinds are the merchant's own vocabulary.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"package type created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PackageType"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"kind":{"type":"string","enum":["box","envelope","carton","pallet","container"]},"length":{"type":"number"},"width":{"type":"number"},"height":{"type":"number"},"dimensions_unit":{"type":"string","enum":["mm","cm","in","ft"]},"weight":{"type":"number"},"max_weight":{"type":"number"},"weight_unit":{"type":"string","enum":["g","kg","lb","oz"]},"default":{"type":"boolean"}},"required":["name","kind"]}}}}}},"/api/v3/admin/package_types/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Package type ID","schema":{"type":"string"}}],"get":{"summary":"Get a package type","tags":["Package Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single package type by prefixed ID.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"package type found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PackageType"}}}},"404":{"description":"package type not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a package type","tags":["Package Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a package type. Every product packed in it follows the new geometry.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"package type updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PackageType"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"kind":{"type":"string","enum":["box","envelope","carton","pallet","container"]},"length":{"type":"number"},"width":{"type":"number"},"height":{"type":"number"},"dimensions_unit":{"type":"string","enum":["mm","cm","in","ft"]},"weight":{"type":"number"},"max_weight":{"type":"number"},"weight_unit":{"type":"string","enum":["g","kg","lb","oz"]},"default":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a package type","tags":["Package Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes a kind of packaging. Refused while any variant is packed into\nit — repack those products first.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"package type deleted"}}}},"/api/v3/admin/price_lists/{price_list_id}/products":{"get":{"summary":"List price list products","tags":["Price Lists"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The products the list prices, listed by name — membership is derived from the price rows.\n`expand=price_list_price` adds what the list charges for each variant, with its quantity\nbreaks as tiers, the same reading a catalog's products carry.\n\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"price_list_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated. `price_list_price` adds the resolved price to every row.","schema":{"type":"string"}}],"responses":{"200":{"description":"products found, with what the list charges","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PriceListProduct"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Add products to a price list","tags":["Price Lists"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds products to the list in bulk, materializing a placeholder price per variant and store currency. Already-present products are skipped.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"price_list_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"products added","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}},"delete":{"summary":"Remove products from a price list","tags":["Price Lists"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes products from the list in bulk, hard-deleting their price rows. Ids that are not members are ignored.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"price_list_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products removed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}}},"/api/v3/admin/product_types":{"get":{"summary":"List product types","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of product types.\n\nA product type is a back-office template: it seeds option types and\ncategories onto products created with it, and defines which custom\nfields those products' forms show. It is not exposed on the Store API.\n\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}}],"responses":{"200":{"description":"product types found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ProductType"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a product type","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a product type.\n\n`option_type_ids` and `category_ids` seed products created with this\ntype. `custom_field_definitions` is a replace-set of the definitions the\nproduct form renders, in `sort_order`. `required` is advisory — the\ndashboard marks the field, but a blank value is never rejected.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"product type created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductType"}}}},"422":{"description":"unprocessable entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"delivery_profile_id":{"type":"string","nullable":true,"description":"Fulfillment profile stamped onto products created with this type. Null leaves new products on the store default profile."},"option_type_ids":{"type":"array","items":{"type":"string"},"description":"Option types seeded onto products created with this type."},"category_ids":{"type":"array","items":{"type":"string"},"description":"Categories seeded onto products created with this type."},"custom_field_definitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Prefixed custom field definition id."},"required":{"type":"boolean"},"sort_order":{"type":"integer"}}}}},"required":["name"]}}}}}},"/api/v3/admin/product_types/{id}":{"parameters":[{"name":"id","in":"path","description":"Product type ID","required":true,"schema":{"type":"string"}}],"get":{"summary":"Retrieve a product type","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single product type with its option types, categories and custom fields.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"product type found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductType"}}}},"404":{"description":"product type not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a product type","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a product type.\n\nChanges never modify products that already carry the type — use\n`apply_to_products` to backfill those.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"product type updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductType"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"delivery_profile_id":{"type":"string","nullable":true},"option_type_ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}},"custom_field_definitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"required":{"type":"boolean"},"sort_order":{"type":"integer"}}}}}}}}}},"delete":{"summary":"Delete a product type","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a product type. Types still used by products cannot be deleted.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"product type deleted"}}}},"/api/v3/admin/product_types/{id}/apply_to_products":{"parameters":[{"name":"id","in":"path","description":"Product type ID","required":true,"schema":{"type":"string"}}],"post":{"summary":"Apply a product type to its existing products","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Backfills the type's option types and categories onto the products that\nalready carry it. Additive and idempotent — nothing is removed, and\nre-running is safe.\n\nRuns in the background; the response reports how many products the type\ncurrently has.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"202":{"description":"backfill accepted","content":{"application/json":{"schema":{"type":"object","properties":{"products_count":{"type":"integer"}}}}}}}}},"/api/v3/admin/seller_requirements":{"get":{"summary":"List seller requirements","tags":["Seller Requirements"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"What this marketplace asks of a seller before it will let them trade,\nin the order sellers work through it.\n\nEach row is one configured requirement. `required` says whether it\nstands between the seller and approval — the others are shown as\nrecommended and counted in their progress, but never block. `active`\nswitches one off without losing how it was worded.\n\n\n**Required scope:** `read_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"seller requirements found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SellerRequirement"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}}}}}}},"post":{"summary":"Add a seller requirement","tags":["Seller Requirements"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds something the marketplace asks of its sellers.\n\n`type` comes from `GET /seller_requirements/types`, which also\ndescribes the configuration each kind takes. Most kinds answer one\nquestion and can be added once; the open-ended ones — a seller\nconfirmation, a manual check, a document — carry the question in your\nown `name` and `description`, so a store may add as many as it needs.\n\nA kind that reads the seller's own data (their addresses, their\nproducts, whether they accepted the terms) needs nothing from the\nseller beyond doing it. The others wait for the seller to submit\nsomething, and the ones you review wait for you.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"seller requirement created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SellerRequirement"}}}},"422":{"description":"kind is not registered","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["type"],"properties":{"type":{"type":"string","description":"The kind, from `GET /seller_requirements/types`."},"name":{"type":"string","description":"What the seller sees. Required for kinds that can be added more than once, since the wording is the only thing telling them apart. Left blank on the others, the kind names itself."},"description":{"type":"string","description":"Instructions shown to the seller."},"required":{"type":"boolean","description":"Whether this blocks approval. Off means recommended."},"active":{"type":"boolean"},"position":{"type":"integer","description":"Place in the checklist."},"preferences":{"type":"object","description":"Configuration for this kind, per its `preference_schema`."}}}}}}}},"/api/v3/admin/seller_requirements/types":{"get":{"summary":"List seller requirement kinds","tags":["Seller Requirements"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The kinds you can add, and the shape of each one's configuration form.\n\n`configured` says the store already has this kind — meaningful only\nwhere `allow_multiple` is false. `accepts_submissions` says the seller\nrecords having done it rather than it being read from their data, and\n`reviewed_by_operator` says what they send waits for you.\n\nA marketplace that registers its own kind server-side sees it here\nwithout this endpoint changing.\n\n\n**Required scope:** `read_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"kinds found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"allow_multiple":{"type":"boolean"},"accepts_submissions":{"type":"boolean"},"reviewed_by_operator":{"type":"boolean"},"configured":{"type":"boolean"},"addable":{"type":"boolean","description":"Whether the operator may add one now. The uniqueness rule is the server's, so clients filter on this rather than deriving it."},"preference_schema":{"type":"array","items":{"type":"object"}}}}}}}}}}}}},"/api/v3/admin/seller_requirements/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Update a seller requirement","tags":["Seller Requirements"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Changes how a requirement is worded, what it asks for, where it sits in\nthe checklist, and whether it blocks approval.\n\n`type` is not accepted: a saved row's kind never changes, because\nanything a seller already submitted answered the old one.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"seller requirement updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SellerRequirement"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"required":{"type":"boolean"},"active":{"type":"boolean"},"position":{"type":"integer"},"preferences":{"type":"object"}}}}}}},"delete":{"summary":"Delete a seller requirement","tags":["Seller Requirements"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Stops asking for this. Anything sellers already submitted against it\ngoes too — to keep the record while pausing the ask, set `active` to\nfalse instead.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"seller requirement deleted"}}}},"/api/v3/admin/sellers":{"get":{"summary":"List sellers","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the sellers on this marketplace. `status` says where each one\nis in its life on the marketplace, and `sellable` answers the question\nthe status alone cannot: an approved seller who is away cannot be\nbought from either.\n\n\n**Required scope:** `read_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[status_eq]","in":"query","required":false,"description":"Filter by status","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"responses":{"200":{"description":"sellers found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Seller"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Opens a seller record. The seller starts as `pending` and has no team\nyet — invite someone to run it with the `invite` action below.\n\n`status` is deliberately not writable here or on update: every move\nthrough the lifecycle is its own action, because each one does more\nthan set a column.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"seller created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"slug":{"type":"string","description":"Derived from the name when omitted."},"contact_email":{"type":"string","nullable":true},"billing_email":{"type":"string","nullable":true},"about":{"type":"string","nullable":true},"tax_remittance":{"type":"string","enum":["seller","platform"]},"payouts_schedule_interval":{"type":"string","enum":["daily","weekly","biweekly","monthly","manual"],"nullable":true},"minimum_payout_amount":{"type":"string","nullable":true}}}}}}}},"/api/v3/admin/sellers/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"get":{"summary":"Get a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single seller, including its settlement and tax configuration.\n\n**Required scope:** `read_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"seller found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}},"404":{"description":"seller not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates the seller's profile and the settlement configuration the\noperator owns. A `status` sent here is ignored — use the lifecycle\nactions.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"seller address written inline","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"billing_email":{"type":"string","nullable":true},"payouts_schedule_interval":{"type":"string","enum":["daily","weekly","biweekly","monthly","manual"],"nullable":true},"minimum_payout_amount":{"type":"string","nullable":true},"holiday_mode_until":{"type":"string","format":"date-time","nullable":true},"logo":{"type":"string","nullable":true,"description":"ActiveStorage signed id of a direct-uploaded file. Send `null` to remove the attachment, or omit the key to leave it alone. Same for `square_logo` and `cover_photo`."},"square_logo":{"type":"string","nullable":true},"cover_photo":{"type":"string","nullable":true},"billing_address":{"type":"object","description":"The seller's own address, written inline. There is no `billing_address_id` — an address belongs to whoever it was created for, so it is never referenced by id here.","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"company":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"phone":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"},"state_name":{"type":"string"},"label":{"type":"string"}}},"returns_address":{"type":"object","description":"The seller's own address, written inline. There is no `billing_address_id` — an address belongs to whoever it was created for, so it is never referenced by id here.","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"company":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"phone":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"},"state_name":{"type":"string"},"label":{"type":"string"}}}}}}}}},"delete":{"summary":"Delete a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the seller. Their products are kept and left without a\nseller rather than deleted — what happens to a departed seller's\ncatalog is the operator's decision.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"seller deleted"}}}},"/api/v3/admin/sellers/{id}/invite":{"parameters":[{"name":"id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"post":{"summary":"Invite someone to run a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Sends an invitation to the seller's own team and moves the seller to\n`invited`. The person becomes a member when they accept, and can then\nsign in to the seller panel.\n\n`role_id` must name a role this seller owns; omit it for the seller's\nown admin role. Re-inviting is allowed — an invitation expires, or the\nfirst one goes to the wrong address.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"invitation sent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string"},"role_id":{"type":"string","nullable":true}}}}}}}},"/api/v3/admin/sellers/{id}/approve":{"parameters":[{"name":"id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"patch":{"summary":"Approve a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Lets the seller sell. This is also the way back for one that was\nsuspended or turned down, and it clears any holiday along with the\nsuspension.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"seller approved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}},"422":{"description":"seller cannot be approved from its current status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/sellers/{id}/suspend":{"parameters":[{"name":"id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"patch":{"summary":"Suspend a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Stops a trading seller from selling. Their catalog and history stay,\nand approving reinstates them. Use this rather than `reject` for a\nseller already on the marketplace — it says something different, and\nit can be undone.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"seller suspended","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}}}},"/api/v3/admin/sellers/{id}/reject":{"parameters":[{"name":"id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"patch":{"summary":"Reject a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Turns down an applicant who never traded. A seller already selling is\nsuspended instead; rejecting one is refused.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"seller rejected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}}}},"/api/v3/admin/stock_levels/bulk_upsert":{"post":{"summary":"Bulk-upsert stock levels","tags":["Stock"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Sets stock levels for many (variant, location) pairs at once — what a\nwarehouse or ERP feed posts on a schedule.\n\nEach row names its variant and stock location by Spree id\n(`variant_id`, `stock_location_id`).\n\nA row carries either `count_on_hand` — the absolute level the external\nsystem reports — or `adjustment`, a relative change for feeds that\nreport movements instead. Every change is written as a stock movement,\nso a merchant can still see why a figure moved.\n\nThe response carries `stock_level_count`: how many rows moved a shelf.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"stock levels updated","content":{"application/json":{}}},"422":{"description":"row is missing a level","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["stock_levels"],"properties":{"stock_levels":{"type":"array","items":{"type":"object","required":["variant_id","stock_location_id"],"properties":{"variant_id":{"type":"string"},"stock_location_id":{"type":"string"},"count_on_hand":{"type":"integer","nullable":true},"adjustment":{"type":"integer","nullable":true},"backorderable":{"type":"boolean","nullable":true}}}}}}}}}}},"/api/v3/admin/stock_movements":{"get":{"summary":"List stock movements","tags":["Stock Movements"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the stock ledger, newest first. Every row says what happened to\nstock (`kind`) and carries a direct reference to what caused it, so a\nmerchant can answer \"why is this number what it is?\" from the data.\n\nKinds are `received` (goods arrived), `allocated` (stock promised to a\nplaced order), `shipped` (promised stock left), `released` (a promise\nwithdrawn) and `adjusted` (a manual correction, which always carries a\n`reason`).\n\nMovements are immutable — reversing one means writing its counterpart\nthrough the resource that caused it, which is why there is no create,\nupdate or delete here.\n\nFilter with Ransack predicates such as `q[kind_eq]`,\n`q[stock_level_id_eq]`, `q[order_id_eq]`, `q[fulfillment_id_eq]` or\n`q[created_at_gteq]`.\n\n`kind` is null on rows written before Spree 6.0 until\n`spree:migrate_stock_movements_to_typed_rows` has run.\n\n\n**Required scope:** `read_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[kind_eq]","in":"query","required":false,"description":"Filter by kind ('received', 'allocated', 'shipped', 'released', 'adjusted')","schema":{"type":"string"}},{"name":"q[stock_level_id_eq]","in":"query","required":false,"description":"Filter by stock level, e.g. sl_1234567890","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"stock movements found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StockMovement"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/stock_movements/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Stock movement ID","schema":{"type":"string"}}],"get":{"summary":"Get a stock movement","tags":["Stock Movements"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single stock movement by prefixed ID.\n\n**Required scope:** `read_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"stock movement found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockMovement"}}}},"404":{"description":"stock movement not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"schemas":{"PaginationMeta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"count":{"type":"integer","description":"Total number of records"},"pages":{"type":"integer","description":"Total number of pages"},"from":{"type":"integer","description":"Index of first record on this page"},"to":{"type":"integer","description":"Index of last record on this page"},"in":{"type":"integer","description":"Number of records on this page"},"previous":{"type":"integer","nullable":true,"description":"Previous page number"},"next":{"type":"integer","nullable":true,"description":"Next page number"}},"required":["page","limit","count","pages","from","to","in"]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","description":"Field-specific validation errors","nullable":true}},"required":["code","message"]}},"required":["error"]},"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"]},"ImportSchemaField":{"type":"object","description":"A canonical column of an import type, including per-store custom field columns","properties":{"name":{"type":"string","description":"Canonical field name used in mappings"},"label":{"type":"string","description":"Human-readable label"},"required":{"type":"boolean","description":"Whether the field must be mapped before processing"}},"required":["name","label","required"]},"CheckoutRequirement":{"type":"object","properties":{"step":{"type":"string","description":"Checkout step this requirement belongs to"},"field":{"type":"string","description":"Field that needs to be satisfied"},"message":{"type":"string","description":"Human-readable requirement message"}},"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"},"message":{"type":"string","description":"Human-readable warning message"},"line_item_id":{"type":"string","nullable":true,"description":"Prefixed line item ID (when applicable)"},"variant_id":{"type":"string","nullable":true,"description":"Prefixed variant ID (when applicable)"},"item_index":{"type":"integer","nullable":true,"description":"Position in the submitted items array, for warnings raised while applying a batch of item changes"}},"required":["code","message"]},"FulfillmentManifestItem":{"type":"object","description":"An item within a fulfillment — which line item and how many units are in this fulfillment","properties":{"item_id":{"type":"string","description":"Line item ID"},"variant_id":{"type":"string","description":"Variant ID"},"quantity":{"type":"integer","description":"Quantity in this fulfillment"}},"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"},"name":{"type":"string","description":"Role name"}},"required":["id","name"]},"AdminUserStore":{"type":"object","description":"A store the staff member can access through a role assignment","properties":{"id":{"type":"string","description":"Prefixed store ID"},"name":{"type":"string","description":"Store name"},"code":{"type":"string","description":"Store code"}},"required":["id","name","code"]},"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"},"type":{"type":"string","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 — null for actions like `free_shipping`)","properties":{"type":{"type":"string","description":"Wire shorthand for the calculator subclass"},"label":{"type":"string"},"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 — the variant added to the order and how many","properties":{"variant_id":{"type":"string"},"quantity":{"type":"integer"}},"required":["variant_id","quantity"]},"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"]},"Address":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string","nullable":true},"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_code":{"type":"string"},"state_text":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"quick_checkout":{"type":"boolean"},"is_default_billing":{"type":"boolean"},"is_default_shipping":{"type":"boolean"},"state_abbr":{"type":"string","nullable":true},"country_iso":{"type":"string"},"state_name":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"latitude":{"type":"number","nullable":true},"longitude":{"type":"number","nullable":true},"customer_id":{"type":"string","nullable":true},"owner_id":{"type":"string","nullable":true},"owner_type":{"type":"string","nullable":true}},"required":["id","label","first_name","last_name","full_name","address1","address2","postal_code","city","phone","company","country_name","country_code","state_text","state_code","quick_checkout","is_default_billing","is_default_shipping","state_abbr","country_iso","state_name","metadata","created_at","updated_at","latitude","longitude","customer_id","owner_id","owner_type"],"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},"selected_locale":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"avatar_url":{"type":"string","nullable":true},"roles":{"type":"array","items":{"$ref":"#/components/schemas/AdminUserRoleAssignment"}},"stores":{"type":"array","items":{"$ref":"#/components/schemas/AdminUserStore"}}},"required":["id","email","first_name","last_name","full_name","selected_locale","created_at","updated_at","avatar_url","roles","stores"],"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},"channel_id":{"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","channel_id","plaintext_token","created_by_email"],"x-typelizer":true},"AppliedPromotion":{"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"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","promotion_id","name","description","code","amount","display_amount","created_at","updated_at"],"x-typelizer":true},"Cart":{"type":"object","properties":{"id":{"type":"string"},"market_id":{"type":"string","nullable":true},"channel_id":{"type":"string","nullable":true},"preferred_stock_location_id":{"type":"string","nullable":true},"company_id":{"type":"string","nullable":true},"company_name":{"type":"string","nullable":true},"po_number_required":{"type":"boolean"},"po_document_filename":{"type":"string","nullable":true},"po_document_byte_size":{"type":"number","nullable":true},"number":{"type":"string"},"token":{"type":"string"},"email":{"type":"string","nullable":true},"customer_note":{"type":"string","nullable":true},"po_number":{"type":"string","nullable":true},"currency":{"type":"string"},"locale":{"type":"string","nullable":true},"total_quantity":{"type":"number"},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/CartWarning"}},"coupon_code":{"type":"string","nullable":true},"item_total":{"type":"string","nullable":true},"display_item_total":{"type":"string","nullable":true},"adjustment_total":{"type":"string","nullable":true},"display_adjustment_total":{"type":"string","nullable":true},"discount_total":{"type":"string","nullable":true},"display_discount_total":{"type":"string","nullable":true},"tax_total":{"type":"string","nullable":true},"display_tax_total":{"type":"string","nullable":true},"included_tax_total":{"type":"string","nullable":true},"display_included_tax_total":{"type":"string","nullable":true},"additional_tax_total":{"type":"string","nullable":true},"display_additional_tax_total":{"type":"string","nullable":true},"total":{"type":"string","nullable":true},"display_total":{"type":"string","nullable":true},"gift_card_total":{"type":"string","nullable":true},"display_gift_card_total":{"type":"string","nullable":true},"amount_due":{"type":"string","nullable":true},"display_amount_due":{"type":"string","nullable":true},"delivery_total":{"type":"string","nullable":true},"display_delivery_total":{"type":"string","nullable":true},"fee_total":{"type":"string","nullable":true},"display_fee_total":{"type":"string","nullable":true},"store_credit_total":{"type":"string","nullable":true},"display_store_credit_total":{"type":"string","nullable":true},"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"}},"order_minimum":{"type":"number","nullable":true},"order_minimum_shortfall":{"type":"number","nullable":true},"below_order_minimum":{"type":"boolean","nullable":true},"freight_summary":{"allOf":[{"$ref":"#/components/schemas/FreightSummary"}],"nullable":true},"shipping_eq_billing_address":{"type":"boolean"},"items":{"type":"array","items":{"$ref":"#/components/schemas/LineItem"}},"billing_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"shipping_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"market":{"allOf":[{"$ref":"#/components/schemas/Market"}],"nullable":true},"completed_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"applied_promotions":{"type":"array","items":{"$ref":"#/components/schemas/AppliedPromotion"}}},"required":["id","market_id","channel_id","preferred_stock_location_id","company_id","company_name","po_number_required","po_document_filename","po_document_byte_size","number","token","email","customer_note","po_number","currency","locale","total_quantity","warnings","coupon_code","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","fee_total","display_fee_total","store_credit_total","display_store_credit_total","covered_by_store_credit","current_step","completed_steps","requirements","order_minimum","order_minimum_shortfall","below_order_minimum","freight_summary","shipping_eq_billing_address","items","billing_address","shipping_address","market","completed_at","created_at","updated_at","applied_promotions"],"x-typelizer":true},"CatalogAssignment":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"catalog_id":{"type":"string"},"assignable_type":{"type":"string"},"assignable_id":{"type":"string"},"assignable_name":{"type":"string","nullable":true}},"required":["id","created_at","catalog_id","assignable_type","assignable_id","assignable_name"],"x-typelizer":true},"CatalogOrderMinimum":{"type":"object","properties":{"id":{"type":"string"},"currency":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"amount":{"type":"string"},"display_amount":{"type":"string"}},"required":["id","currency","created_at","updated_at","amount","display_amount"],"x-typelizer":true},"CatalogPrice":{"type":"object","properties":{"id":{"type":"string","nullable":true},"label":{"type":"string","nullable":true},"sku":{"type":"string","nullable":true},"currency":{"type":"string"},"source":{"type":"string"},"break_count":{"type":"number"},"amount":{"type":"string"},"display_amount":{"type":"string"},"tiers":{"type":"array","items":{"$ref":"#/components/schemas/CatalogPriceTier"}}},"required":["id","label","sku","currency","source","break_count","amount","display_amount","tiers"],"x-typelizer":true},"CatalogPriceTier":{"type":"object","properties":{"min_quantity":{"type":"number"},"display_amount":{"type":"string"},"amount":{"type":"string"}},"required":["min_quantity","display_amount","amount"],"x-typelizer":true},"CatalogProduct":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"thumbnail_url":{"type":"string","nullable":true},"quantity_rule":{"allOf":[{"$ref":"#/components/schemas/CatalogProductTerm"}],"nullable":true},"catalog_variants":{"type":"array","items":{"$ref":"#/components/schemas/CatalogPrice"}}},"required":["id","name","thumbnail_url"],"x-typelizer":true},"CatalogProductTerm":{"type":"object","properties":{"id":{"type":"string"},"product_id":{"type":"string"},"product_name":{"type":"string","nullable":true},"minimum_order_quantity":{"type":"number","nullable":true},"order_multiple":{"type":"number","nullable":true},"mixed":{"type":"boolean"}},"required":["id","product_id","product_name","minimum_order_quantity","order_multiple","mixed"],"x-typelizer":true},"CatalogQuantityRule":{"type":"object","properties":{"id":{"type":"string"},"minimum_order_quantity":{"type":"number","nullable":true},"order_multiple":{"type":"number","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"variant_id":{"type":"string","nullable":true},"variant_sku":{"type":"string","nullable":true},"product_name":{"type":"string","nullable":true},"options_text":{"type":"string","nullable":true}},"required":["id","minimum_order_quantity","order_multiple","created_at","updated_at","variant_id","variant_sku","product_name","options_text"],"x-typelizer":true},"Catalog":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"active":{"type":"boolean"},"position":{"type":"number","nullable":true},"metadata":{"type":"object","nullable":true},"minimum_order_quantity":{"type":"number","nullable":true},"order_multiple":{"type":"number","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"products_count":{"type":"number"},"pricing_strategy":{"type":"string"},"order_minimums":{"type":"array","items":{"$ref":"#/components/schemas/CatalogOrderMinimum"}},"price_list":{"$ref":"#/components/schemas/PriceList"},"assignments":{"type":"array","items":{"$ref":"#/components/schemas/CatalogAssignment"}}},"required":["id","name","description","active","position","metadata","minimum_order_quantity","order_multiple","created_at","updated_at","products_count","pricing_strategy"],"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"}},"external_references":{"type":"object"},"translations":{"type":"object"},"metadata":{"type":"object"},"pretty_name":{"type":"string"},"lft":{"type":"number"},"rgt":{"type":"number"},"products_count":{"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","external_references","metadata","pretty_name","lft","rgt","products_count","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"},"storefront_access":{"type":"string"},"guest_checkout":{"type":"boolean"},"preferred_order_routing_strategy":{"type":"string","nullable":true},"preferred_storefront_access":{"type":"string","nullable":true},"preferred_guest_checkout":{"type":"boolean","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"stock_location_ids":{"type":"array","items":{"type":"string"}},"default_catalog_id":{"type":"string","nullable":true}},"required":["id","name","code","active","default","storefront_access","guest_checkout","preferred_order_routing_strategy","preferred_storefront_access","preferred_guest_checkout","created_at","updated_at","stock_location_ids","default_catalog_id"],"x-typelizer":true},"ClaimLineItem":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"send_replacement":{"type":"boolean"},"description":{"type":"string","nullable":true},"refund_amount":{"type":"string"},"paid_amount":{"type":"string"},"display_refund_amount":{"type":"string"},"variant_id":{"type":"string","nullable":true},"replacement_variant_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"variant":{"$ref":"#/components/schemas/Variant"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"replacement_variant":{"$ref":"#/components/schemas/Variant"}},"required":["id","quantity","send_replacement","description","refund_amount","paid_amount","display_refund_amount","variant_id","replacement_variant_id","line_item_id","created_at","updated_at"],"x-typelizer":true},"ClaimReason":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"can_be_deleted":{"type":"boolean"}},"required":["id","name","active","created_at","updated_at","can_be_deleted"],"x-typelizer":true},"Claim":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"status":{"type":"string"},"resolution":{"type":"string","nullable":true},"order_id":{"type":"string","nullable":true},"reason_id":{"type":"string","nullable":true},"refund_total":{"type":"string"},"display_refund_total":{"type":"string"},"approved_at":{"type":"string","nullable":true},"resolved_at":{"type":"string","nullable":true},"denied_at":{"type":"string","nullable":true},"canceled_at":{"type":"string","nullable":true},"reason":{"$ref":"#/components/schemas/ClaimReason"},"claim_line_items":{"type":"array","items":{"$ref":"#/components/schemas/ClaimLineItem"}},"memo":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"created_by_id":{"type":"string","nullable":true},"order":{"$ref":"#/components/schemas/Order"},"refunds":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}}},"required":["id","number","status","resolution","order_id","reason_id","refund_total","display_refund_total","approved_at","resolved_at","denied_at","canceled_at","memo","metadata","created_at","updated_at","created_by_id"],"x-typelizer":true},"CollectionRule":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"value":{"type":"string","nullable":true},"match_policy":{"type":"string"}},"required":["id","type","value","match_policy"],"x-typelizer":true},"Collection":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"permalink":{"type":"string"},"position":{"type":"number"},"sort_order":{"type":"string"},"meta_title":{"type":"string","nullable":true},"meta_description":{"type":"string","nullable":true},"meta_keywords":{"type":"string","nullable":true},"products_count":{"type":"number"},"description":{"type":"string"},"description_html":{"type":"string"},"image_url":{"type":"string","nullable":true},"square_image_url":{"type":"string","nullable":true},"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"translations":{"type":"object"},"automatic":{"type":"boolean"},"rules_match_policy":{"type":"string"},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"rules":{"type":"array","items":{"$ref":"#/components/schemas/CollectionRule"}}},"required":["id","name","permalink","position","sort_order","meta_title","meta_description","meta_keywords","products_count","description","description_html","image_url","square_image_url","automatic","rules_match_policy","metadata","created_at","updated_at"],"x-typelizer":true},"CommissionLine":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"currency":{"type":"string"},"taxability_reason":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"rate":{"type":"string"},"tax_rate":{"type":"string"},"amount":{"type":"string"},"tax_amount":{"type":"string"},"total":{"type":"string"},"display_amount":{"type":"string"},"display_tax_amount":{"type":"string"},"display_total":{"type":"string"},"order_id":{"type":"string"},"seller_id":{"type":"string"},"line_item_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true},"commission_rate_id":{"type":"string","nullable":true},"seller_name":{"type":"string","nullable":true},"commission_rate":{"$ref":"#/components/schemas/CommissionRate"}},"required":["id","kind","currency","taxability_reason","country_code","state_code","created_at","updated_at","rate","tax_rate","amount","tax_amount","total","display_amount","display_tax_amount","display_total","order_id","seller_id","line_item_id","fulfillment_id","commission_rate_id","seller_name"],"x-typelizer":true},"CommissionRate":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"code":{"type":"string","nullable":true},"enabled":{"type":"boolean"},"position":{"type":"number"},"kind":{"type":"string"},"tax_inclusive":{"type":"boolean"},"include_shipping":{"type":"boolean"},"metadata":{"type":"object","nullable":true},"deleted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"value":{"type":"string"},"commission_tax_rate":{"type":"string","nullable":true},"amounts":{"type":"object"},"bounds":{"type":"object"},"global":{"type":"boolean"},"rules":{"type":"array","items":{"$ref":"#/components/schemas/CommissionRule"}}},"required":["id","name","code","enabled","position","kind","tax_inclusive","include_shipping","metadata","deleted_at","created_at","updated_at","value","commission_tax_rate","amounts","bounds","global","rules"],"x-typelizer":true},"CommissionRule":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"commission_rate_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"object"},"product_ids":{"type":"array","items":{"type":"string"}}},"required":["id","created_at","updated_at","type","commission_rate_id","preferences","preference_schema"],"x-typelizer":true},"CompanyInvitation":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"expires_at":{"type":"string","nullable":true},"company_id":{"type":"string"},"status":{"type":"string"},"accepted_at":{"type":"string","nullable":true},"revoked_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","email","expires_at","company_id","status","accepted_at","revoked_at","created_at","updated_at"],"x-typelizer":true},"CompanyMembership":{"type":"object","properties":{"id":{"type":"string"},"company_id":{"type":"string"},"customer_id":{"type":"string"},"email":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","company_id","customer_id","email","created_at","updated_at"],"x-typelizer":true},"Company":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string"},"po_number_required":{"type":"boolean"},"parent_id":{"type":"string","nullable":true},"ancestors":{"type":"object"},"external_references":{"type":"object"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"children_count":{"type":"number"},"members_count":{"type":"number"},"children":{"type":"array","items":{"$ref":"#/components/schemas/Company"}},"addresses":{"type":"array","items":{"$ref":"#/components/schemas/Address"}},"memberships":{"type":"array","items":{"$ref":"#/components/schemas/CompanyMembership"}}},"required":["id","name","kind","po_number_required","parent_id","ancestors","external_references","metadata","created_at","updated_at","children_count","members_count"],"x-typelizer":true},"ConsentRecord":{"type":"object","properties":{"id":{"type":"string"},"purpose":{"type":"string"},"source":{"type":"string"},"accepted":{"type":"boolean"},"email":{"type":"string","nullable":true},"ip_address":{"type":"string","nullable":true},"created_at":{"type":"string"},"recorded_at":{"type":"string","nullable":true},"documents":{"type":"object"}},"required":["id","purpose","source","accepted","email","ip_address","created_at","recorded_at","documents"],"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},"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"},"searchable":{"type":"boolean"},"sortable":{"type":"boolean"},"filter_key":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","namespace","key","label","field_type","resource_type","storefront_visible","searchable","sortable","filter_key","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"},"email_marketing_consent_updated_at":{"type":"string","nullable":true},"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},"newsletter_subscriber":{"allOf":[{"$ref":"#/components/schemas/NewsletterSubscriber"}],"nullable":true},"customer_groups":{"type":"array","items":{"$ref":"#/components/schemas/CustomerGroup"}},"failed_attempts":{"type":"number"},"metadata":{"type":"object"},"email_marketing_consent_source":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"anonymized_at":{"type":"string","nullable":true},"anonymized":{"type":"boolean"},"tags":{"type":"array","items":{"type":"string"}},"internal_note":{"type":"string","nullable":true},"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_group_ids":{"type":"array","items":{"type":"string"}},"companies":{"type":"array","items":{"$ref":"#/components/schemas/Company"}}},"required":["id","email","first_name","last_name","phone","accepts_email_marketing","email_marketing_consent_updated_at","full_name","available_store_credit_total","display_available_store_credit_total","failed_attempts","metadata","email_marketing_consent_source","created_at","updated_at","anonymized_at","anonymized","tags","internal_note","internal_note_html","default_billing_address_id","default_shipping_address_id","orders_count","total_spent","display_total_spent","last_order_completed_at","customer_group_ids"],"x-typelizer":true},"DataRequest":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"kind":{"type":"string"},"status":{"type":"string"},"requested_at":{"type":"string","nullable":true},"completed_at":{"type":"string","nullable":true},"expires_at":{"type":"string","nullable":true},"email":{"type":"string"},"error_message":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"customer_id":{"type":"string","nullable":true},"requested_by_id":{"type":"string","nullable":true},"customer":{"$ref":"#/components/schemas/Customer"}},"required":["id","number","kind","status","requested_at","completed_at","expires_at","email","error_message","created_at","updated_at","customer_id","requested_by_id"],"x-typelizer":true},"DeliveryMethodRule":{"type":"object","properties":{"id":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"object"},"product_ids":{"type":"array","items":{"type":"string"}}},"required":["id","active","created_at","updated_at","type","preferences","preference_schema","product_ids"],"x-typelizer":true},"DeliveryMethod":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"code":{"type":"string","nullable":true},"estimated_transit_business_days_min":{"type":"number","nullable":true},"estimated_transit_business_days_max":{"type":"number","nullable":true},"digital":{"type":"boolean"},"pickup":{"type":"boolean"},"pickup_point":{"type":"boolean"},"admin_name":{"type":"string","nullable":true},"fulfillment_provider":{"type":"string"},"pickup_point_provider":{"type":"string","nullable":true},"rate_provider":{"type":"string","nullable":true},"storefront_visible":{"type":"boolean"},"tracking_url":{"type":"string","nullable":true},"markup_flat":{"type":"string","nullable":true},"markup_percent":{"type":"string","nullable":true},"available_to_sellers":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"deleted_at":{"type":"string"},"seller_id":{"type":"string","nullable":true},"seller_name":{"type":"string","nullable":true},"services":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryMethodService"}},"rules":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryMethodRule"}},"tax_category_id":{"type":"string","nullable":true},"delivery_profile_id":{"type":"string"},"delivery_origin_group_id":{"type":"string","nullable":true},"delivery_zone_id":{"type":"string","nullable":true},"stock_location_ids":{"type":"array","items":{"type":"string"}},"calculator_type":{"type":"string","nullable":true},"calculator_preferences":{"type":"object","nullable":true}},"required":["id","name","code","estimated_transit_business_days_min","estimated_transit_business_days_max","digital","pickup","pickup_point","admin_name","fulfillment_provider","pickup_point_provider","rate_provider","storefront_visible","tracking_url","markup_flat","markup_percent","available_to_sellers","created_at","updated_at","deleted_at","seller_id","seller_name","services","rules","tax_category_id","delivery_profile_id","delivery_origin_group_id","delivery_zone_id","stock_location_ids","calculator_type","calculator_preferences"],"x-typelizer":true},"DeliveryMethodService":{"type":"object","properties":{"id":{"type":"string"},"carrier":{"type":"string"},"service":{"type":"string"},"label":{"type":"string","nullable":true},"markup_flat":{"type":"string","nullable":true},"markup_percent":{"type":"string","nullable":true},"position":{"type":"number"}},"required":["id","carrier","service","label","markup_flat","markup_percent","position"],"x-typelizer":true},"DeliveryOriginGroup":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","nullable":true},"position":{"type":"number","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivery_profile_id":{"type":"string"},"stock_location_ids":{"type":"array","items":{"type":"string"}},"delivery_zones_count":{"type":"number"},"delivery_methods_count":{"type":"number"}},"required":["id","name","position","created_at","updated_at","delivery_profile_id","stock_location_ids","delivery_zones_count","delivery_methods_count"],"x-typelizer":true},"DeliveryProfile":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"default":{"type":"boolean"},"position":{"type":"number","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"kind":{"type":"string"},"digital":{"type":"boolean"},"offers_pickup":{"type":"boolean"},"offers_shipping":{"type":"boolean"},"stock_location_ids":{"type":"array","items":{"type":"string"}},"origin_groups":{"type":"object"},"products_count":{"type":"number"},"delivery_methods_count":{"type":"number"},"delivery_zones_count":{"type":"number"}},"required":["id","name","default","position","created_at","updated_at","kind","digital","offers_pickup","offers_shipping","stock_location_ids","origin_groups","products_count","delivery_methods_count","delivery_zones_count"],"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"},"carrier":{"type":"string","nullable":true},"service_level":{"type":"string","nullable":true},"estimated_delivery_date":{"type":"string","nullable":true},"unpriced":{"type":"boolean"},"freight_summary":{"allOf":[{"$ref":"#/components/schemas/FreightSummary"}],"nullable":true},"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"},"metadata":{"type":"object","nullable":true},"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","carrier","service_level","estimated_delivery_date","unpriced","freight_summary","display_cost","display_total","display_additional_tax_total","display_included_tax_total","display_tax_total","metadata","created_at","updated_at"],"x-typelizer":true},"Delivery":{"type":"object","properties":{"id":{"type":"string"},"tracking_number":{"type":"string"},"carrier":{"type":"string","nullable":true},"carrier_name":{"type":"string","nullable":true},"service":{"type":"string","nullable":true},"status":{"type":"string"},"tracking_url":{"type":"string","nullable":true},"estimated_delivery_at":{"type":"string","nullable":true},"delivered_at":{"type":"string","nullable":true},"details":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"shipping_label_id":{"type":"string","nullable":true}},"required":["id","tracking_number","carrier","carrier_name","service","status","tracking_url","estimated_delivery_at","delivered_at","details","created_at","updated_at","shipping_label_id"],"x-typelizer":true},"DeliveryZoneMember":{"type":"object","properties":{"id":{"type":"string"},"member_type":{"type":"string"},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"postal_code_prefix":{"type":"string","nullable":true},"postal_code_from":{"type":"string","nullable":true},"postal_code_to":{"type":"string","nullable":true},"country_name":{"type":"string","nullable":true},"state_name":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","member_type","country_code","state_code","postal_code_prefix","postal_code_from","postal_code_to","country_name","state_name","created_at","updated_at"],"x-typelizer":true},"DeliveryZone":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"members":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryZoneMember"}},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivery_profile_id":{"type":"string"},"delivery_origin_group_id":{"type":"string","nullable":true},"delivery_method_ids":{"type":"array","items":{"type":"string"}}},"required":["id","name","description","created_at","updated_at","delivery_profile_id","delivery_origin_group_id","delivery_method_ids"],"x-typelizer":true},"DigitalAsset":{"type":"object","properties":{"id":{"type":"string"},"variant_id":{"type":"string","nullable":true},"filename":{"type":"string","nullable":true},"content_type":{"type":"string","nullable":true},"authorized_clicks":{"type":"number","nullable":true},"authorized_days":{"type":"number","nullable":true},"byte_size":{"type":"number","nullable":true},"provider_type":{"type":"string","nullable":true},"provider_settings":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"provider_name":{"type":"string"},"download_url":{"type":"string","nullable":true},"effective_authorized_clicks":{"type":"number"},"effective_authorized_days":{"type":"number"}},"required":["id","variant_id","filename","content_type","authorized_clicks","authorized_days","byte_size","provider_type","provider_settings","created_at","updated_at","provider_name","download_url","effective_authorized_clicks","effective_authorized_days"],"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"},"expires_at":{"type":"string","nullable":true},"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","expires_at","authorizable","expired","access_limit_exceeded","created_at","updated_at"],"x-typelizer":true},"Discount":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"kind":{"type":"string"},"code":{"type":"string","nullable":true},"value_type":{"type":"string","nullable":true},"value":{"type":"string","nullable":true},"promotion_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true},"amount":{"type":"string"},"display_amount":{"type":"string"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","label","kind","code","value_type","value","promotion_id","line_item_id","fulfillment_id","amount","display_amount","metadata","created_at","updated_at"],"x-typelizer":true},"ExchangeLineItem":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"received_quantity":{"type":"number"},"resellable":{"type":"boolean"},"original_price":{"type":"string"},"new_variant_price":{"type":"string"},"price_difference":{"type":"string"},"original_variant_id":{"type":"string","nullable":true},"new_variant_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"fulfillment_item_id":{"type":"string","nullable":true},"original_variant":{"$ref":"#/components/schemas/Variant"},"new_variant":{"$ref":"#/components/schemas/Variant"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","quantity","received_quantity","resellable","original_price","new_variant_price","price_difference","original_variant_id","new_variant_id","line_item_id","fulfillment_item_id","created_at","updated_at"],"x-typelizer":true},"Exchange":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"status":{"type":"string"},"order_id":{"type":"string","nullable":true},"reason_id":{"type":"string","nullable":true},"price_difference":{"type":"string"},"display_price_difference":{"type":"string"},"approved_at":{"type":"string","nullable":true},"received_at":{"type":"string","nullable":true},"fulfilled_at":{"type":"string","nullable":true},"canceled_at":{"type":"string","nullable":true},"reason":{"$ref":"#/components/schemas/ReturnReason"},"exchange_line_items":{"type":"array","items":{"$ref":"#/components/schemas/ExchangeLineItem"}},"memo":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"stock_location_id":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true},"order":{"$ref":"#/components/schemas/Order"},"stock_location":{"$ref":"#/components/schemas/StockLocation"},"refunds":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}}},"required":["id","number","status","order_id","reason_id","price_difference","display_price_difference","approved_at","received_at","fulfilled_at","canceled_at","memo","metadata","created_at","updated_at","stock_location_id","created_by_id"],"x-typelizer":true},"Export":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"format":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string","nullable":true},"user_id":{"type":"string","nullable":true},"done":{"type":"boolean"},"store_id":{"type":"string","nullable":true},"seller_id":{"type":"string","nullable":true},"seller_name":{"type":"string","nullable":true},"filename":{"type":"string","nullable":true},"byte_size":{"type":"number","nullable":true},"download_url":{"type":"string","nullable":true}},"required":["id","number","format","created_at","updated_at","type","user_id","done","store_id","seller_id","seller_name","filename","byte_size","download_url"],"x-typelizer":true},"Fee":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"kind":{"type":"string"},"line_item_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true},"amount":{"type":"string"},"display_amount":{"type":"string"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","label","kind","line_item_id","fulfillment_id","amount","display_amount","metadata","created_at","updated_at"],"x-typelizer":true},"FreightSummaryLine":{"type":"object","properties":{"variant_id":{"type":"string","nullable":true},"sku":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"units":{"type":"number"},"cartons":{"type":"number","nullable":true},"pallets":{"type":"number","nullable":true},"units_per_carton":{"type":"number","nullable":true},"cartons_per_pallet":{"type":"number","nullable":true},"complete":{"type":"boolean"},"weight_per_carton":{"type":"string","nullable":true},"volume":{"type":"string"},"weight":{"type":"string"}},"required":["variant_id","sku","name","units","cartons","pallets","units_per_carton","cartons_per_pallet","complete","weight_per_carton","volume","weight"],"x-typelizer":true},"FreightSummary":{"type":"object","properties":{"total_units":{"type":"number"},"total_cartons":{"type":"number"},"total_pallets":{"type":"number","nullable":true},"total_volume":{"type":"string"},"total_weight":{"type":"string"},"complete":{"type":"boolean"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/FreightSummaryLine"}}},"required":["total_units","total_cartons","total_pallets","total_volume","total_weight","complete","lines"],"x-typelizer":true},"FulfillmentItem":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"status":{"type":"string"},"variant_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"options_text":{"type":"string","nullable":true}},"required":["id","quantity","status","variant_id","line_item_id","name","options_text"],"x-typelizer":true},"Fulfillment":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"tracking":{"type":"string","nullable":true},"tracking_url":{"type":"string","nullable":true},"pickup_point_data":{"type":"object","nullable":true},"selected_delivery_rate_id":{"type":"string","nullable":true},"unpriced":{"type":"boolean"},"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},"delivered_at":{"type":"string","nullable":true},"items":{"type":"array","items":{"$ref":"#/components/schemas/FulfillmentManifestItem"}},"deliveries":{"type":"array","items":{"$ref":"#/components/schemas/Delivery"}},"delivery_method":{"$ref":"#/components/schemas/DeliveryMethod"},"stock_location":{"$ref":"#/components/schemas/StockLocation"},"delivery_rates":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryRate"}},"tax_lines":{"type":"array","items":{"$ref":"#/components/schemas/TaxLine"}},"metadata":{"type":"object"},"adjustment_total":{"type":"string"},"pre_tax_amount":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"order_id":{"type":"string","nullable":true},"stock_location_id":{"type":"string","nullable":true},"documents":{"type":"object"},"labels":{"type":"array","items":{"$ref":"#/components/schemas/ShippingLabel"}},"provider_generates_labels":{"type":"boolean"},"fulfillment_items":{"type":"array","items":{"$ref":"#/components/schemas/FulfillmentItem"}},"order":{"$ref":"#/components/schemas/Order"}},"required":["id","number","tracking","tracking_url","pickup_point_data","selected_delivery_rate_id","unpriced","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","delivered_at","items","deliveries","metadata","adjustment_total","pre_tax_amount","created_at","updated_at","order_id","stock_location_id","documents","labels","provider_generates_labels"],"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"},"display_amount_used":{"type":"string"},"display_amount_remaining":{"type":"string"},"expires_at":{"type":"string","nullable":true},"redeemed_at":{"type":"string","nullable":true},"expired":{"type":"boolean"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"customer_id":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true},"customer":{"$ref":"#/components/schemas/Customer"},"created_by":{"$ref":"#/components/schemas/AdminUser"},"gift_card_batch":{"$ref":"#/components/schemas/GiftCardBatch"},"orders":{"type":"array","items":{"$ref":"#/components/schemas/Order"}}},"required":["id","code","status","currency","amount","amount_used","amount_authorized","amount_remaining","display_amount","display_amount_used","display_amount_remaining","expires_at","redeemed_at","expired","active","created_at","updated_at","customer_id","created_by_id"],"x-typelizer":true},"ImportMapping":{"type":"object","properties":{"id":{"type":"string"},"schema_field":{"type":"string"},"file_column":{"type":"string","nullable":true},"required":{"type":"boolean"}},"required":["id","schema_field","file_column","required"],"x-typelizer":true},"ImportRow":{"type":"object","properties":{"id":{"type":"string"},"row_number":{"type":"number"},"status":{"type":"string"},"validation_errors":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"import_id":{"type":"string","nullable":true},"item_type":{"type":"string","nullable":true},"item_id":{"type":"string","nullable":true},"data":{"type":"object"}},"required":["id","row_number","status","validation_errors","created_at","updated_at","import_id","item_type","item_id","data"],"x-typelizer":true},"Import":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"rows_count":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string","nullable":true},"status":{"type":"string"},"store_id":{"type":"string","nullable":true},"seller_id":{"type":"string","nullable":true},"owner_type":{"type":"string","nullable":true},"owner_id":{"type":"string","nullable":true},"user_id":{"type":"string","nullable":true},"processing_errors":{"type":"string","nullable":true},"preferred_delimiter":{"type":"string"},"price_list_id":{"type":"string","nullable":true},"seller_name":{"type":"string","nullable":true},"original_filename":{"type":"string","nullable":true},"original_byte_size":{"type":"number","nullable":true},"original_file_url":{"type":"string","nullable":true},"completed_rows_count":{"type":"number"},"failed_rows_count":{"type":"number"},"schema_fields":{"type":"array","items":{"$ref":"#/components/schemas/ImportSchemaField"}},"csv_headers":{"type":"array","items":{"type":"string"}},"sample_row":{"type":"object"},"mappings":{"type":"array","items":{"$ref":"#/components/schemas/ImportMapping"}}},"required":["id","number","rows_count","created_at","updated_at","type","status","store_id","seller_id","owner_type","owner_id","user_id","processing_errors","preferred_delimiter","price_list_id","seller_name","original_filename","original_byte_size","original_file_url","completed_rows_count","failed_rows_count","schema_fields","csv_headers","sample_row","mappings"],"x-typelizer":true},"Integration":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"group":{"type":"string","nullable":true},"preferences":{"type":"object"},"preference_schema":{"type":"object"}},"required":["id","name","active","created_at","updated_at","type","group","preferences","preference_schema"],"x-typelizer":true},"Invitation":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"status":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"expires_at":{"type":"string"},"role_id":{"type":"string"},"role_name":{"type":"string"},"inviter_email":{"type":"string"},"acceptance_url":{"type":"string"},"invitee_exists":{"type":"boolean"},"store":{"type":"object"}},"required":["id","email","status","created_at","updated_at","expires_at","role_id","role_name","inviter_email","acceptance_url","invitee_exists","store"],"x-typelizer":true},"LineItem":{"type":"object","properties":{"id":{"type":"string"},"variant_id":{"type":"string"},"seller_id":{"type":"string","nullable":true},"preorder":{"type":"boolean"},"preorder_ships_at":{"type":"string","nullable":true},"quantity":{"type":"number"},"currency":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"options_text":{"type":"string"},"price":{"type":"string"},"display_price":{"type":"string"},"total":{"type":"string"},"display_total":{"type":"string"},"adjustment_total":{"type":"string"},"display_adjustment_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"},"discount_total":{"type":"string"},"display_discount_total":{"type":"string"},"pre_tax_amount":{"type":"string"},"display_pre_tax_amount":{"type":"string"},"discounted_amount":{"type":"string"},"display_discounted_amount":{"type":"string"},"display_compare_at_amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true},"seller":{"$ref":"#/components/schemas/Seller"},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}},"digital_links":{"type":"array","items":{"$ref":"#/components/schemas/DigitalLink"}},"tax_lines":{"type":"array","items":{"$ref":"#/components/schemas/TaxLine"}},"metadata":{"type":"object"},"price_source":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"catalog_price":{"type":"string","nullable":true},"cost_price":{"type":"string","nullable":true},"tax_category_id":{"type":"string","nullable":true},"variant":{"$ref":"#/components/schemas/Variant"},"tax_category":{"$ref":"#/components/schemas/TaxCategory"}},"required":["id","variant_id","seller_id","preorder","preorder_ships_at","quantity","currency","name","slug","options_text","price","display_price","total","display_total","adjustment_total","display_adjustment_total","additional_tax_total","display_additional_tax_total","included_tax_total","display_included_tax_total","discount_total","display_discount_total","pre_tax_amount","display_pre_tax_amount","discounted_amount","display_discounted_amount","display_compare_at_amount","compare_at_amount","thumbnail_url","option_values","digital_links","metadata","price_source","created_at","updated_at","catalog_price","cost_price","tax_category_id"],"x-typelizer":true},"Market":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"currency":{"type":"string"},"default_locale":{"type":"string"},"tax_inclusive":{"type":"boolean"},"default":{"type":"boolean"},"country_codes":{"type":"array","items":{"type":"string"}},"supported_locales":{"type":"array","items":{"type":"string"}},"countries":{"type":"array","items":{"$ref":"#/components/schemas/Country"}},"tax_provider":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","name","currency","default_locale","tax_inclusive","default","country_codes","supported_locales","tax_provider","created_at","updated_at"],"x-typelizer":true},"Media":{"type":"object","properties":{"id":{"type":"string"},"product_id":{"type":"string","nullable":true},"variant_ids":{"type":"array","items":{"type":"string"}},"position":{"type":"number"},"alt":{"type":"string","nullable":true},"media_type":{"type":"string"},"focal_point_x":{"type":"number","nullable":true},"focal_point_y":{"type":"number","nullable":true},"external_video_url":{"type":"string","nullable":true},"video_provider":{"type":"string","nullable":true},"video_embed_url":{"type":"string","nullable":true},"video_url":{"type":"string","nullable":true},"poster_url":{"type":"string","nullable":true},"original_url":{"type":"string","nullable":true},"mini_url":{"type":"string","nullable":true},"small_url":{"type":"string","nullable":true},"medium_url":{"type":"string","nullable":true},"large_url":{"type":"string","nullable":true},"xlarge_url":{"type":"string","nullable":true},"og_image_url":{"type":"string","nullable":true},"external_references":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"attached":{"type":"boolean"},"filename":{"type":"string","nullable":true},"content_type":{"type":"string","nullable":true},"byte_size":{"type":"number","nullable":true},"embed_url":{"type":"string","nullable":true},"signed_id":{"type":"string","nullable":true},"viewable_id":{"type":"string","nullable":true},"download_url":{"type":"string","nullable":true},"metadata":{"type":"object"},"viewable_type":{"type":"string","nullable":true}},"required":["id","product_id","variant_ids","position","alt","media_type","focal_point_x","focal_point_y","external_video_url","video_provider","video_embed_url","video_url","poster_url","original_url","mini_url","small_url","medium_url","large_url","xlarge_url","og_image_url","external_references","created_at","updated_at","attached","filename","content_type","byte_size","embed_url","signed_id","viewable_id","download_url","metadata","viewable_type"],"x-typelizer":true},"MembershipProduct":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"thumbnail_url":{"type":"string","nullable":true}},"required":["id","name","thumbnail_url"],"x-typelizer":true},"NewsletterSubscriber":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"verified":{"type":"boolean"},"verified_at":{"type":"string","nullable":true},"customer_id":{"type":"string","nullable":true}},"required":["id","email","created_at","updated_at","verified","verified_at","customer_id"],"x-typelizer":true},"OptionType":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"number"},"kind":{"type":"string"},"translations":{"type":"object"},"metadata":{"type":"object"},"filterable":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}}},"required":["id","name","label","position","kind","metadata","filterable","created_at","updated_at"],"x-typelizer":true},"OptionValue":{"type":"object","properties":{"id":{"type":"string"},"option_type_id":{"type":"string"},"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"number"},"color_code":{"type":"string","nullable":true},"option_type_name":{"type":"string"},"option_type_label":{"type":"string"},"image_url":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"option_type":{"$ref":"#/components/schemas/OptionType"}},"required":["id","option_type_id","name","label","position","color_code","option_type_name","option_type_label","image_url","metadata","created_at","updated_at"],"x-typelizer":true},"OrderCancellationReason":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"can_be_deleted":{"type":"boolean"}},"required":["id","name","active","created_at","updated_at","can_be_deleted"],"x-typelizer":true},"OrderGroup":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"email":{"type":"string","nullable":true},"currency":{"type":"string"},"total":{"type":"string","nullable":true},"display_total":{"type":"string","nullable":true},"item_total":{"type":"string","nullable":true},"display_item_total":{"type":"string","nullable":true},"fulfillment_status":{"type":"string","nullable":true},"payment_status":{"type":"string","nullable":true},"completed_at":{"type":"string","nullable":true},"billing_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"shipping_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"orders":{"type":"array","items":{"$ref":"#/components/schemas/Order"}},"customer_id":{"type":"string","nullable":true},"cart_id":{"type":"string","nullable":true},"seller_count":{"type":"number"},"includes_first_party":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"payments":{"type":"array","items":{"$ref":"#/components/schemas/Payment"}}},"required":["id","number","email","currency","total","display_total","item_total","display_item_total","fulfillment_status","payment_status","completed_at","billing_address","shipping_address","orders","customer_id","cart_id","seller_count","includes_first_party","created_at","updated_at","payments"],"x-typelizer":true},"OrderRoutingRule":{"type":"object","properties":{"id":{"type":"string"},"position":{"type":"number"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"channel_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"object"}},"required":["id","position","active","created_at","updated_at","type","channel_id","preferences","preference_schema"],"x-typelizer":true},"Order":{"type":"object","properties":{"id":{"type":"string"},"market_id":{"type":"string","nullable":true},"withdrawal_period_ends_at":{"type":"string","nullable":true},"within_withdrawal_period":{"type":"boolean"},"cart_id":{"type":"string","nullable":true},"channel_id":{"type":"string","nullable":true},"company_id":{"type":"string","nullable":true},"company_name":{"type":"string","nullable":true},"po_document_filename":{"type":"string","nullable":true},"po_document_byte_size":{"type":"number","nullable":true},"number":{"type":"string"},"email":{"type":"string"},"customer_note":{"type":"string","nullable":true},"po_number":{"type":"string","nullable":true},"currency":{"type":"string"},"locale":{"type":"string","nullable":true},"total_quantity":{"type":"number"},"coupon_code":{"type":"string","nullable":true},"fulfillment_status":{"type":"string","nullable":true},"payment_status":{"type":"string","nullable":true},"completed_at":{"type":"string","nullable":true},"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"},"fee_total":{"type":"string"},"display_fee_total":{"type":"string"},"store_credit_total":{"type":"string"},"display_store_credit_total":{"type":"string"},"covered_by_store_credit":{"type":"boolean"},"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},"gift_card":{"allOf":[{"$ref":"#/components/schemas/GiftCard"}],"nullable":true},"market":{"allOf":[{"$ref":"#/components/schemas/Market"}],"nullable":true},"external_references":{"type":"object"},"status":{"type":"string"},"last_ip_address":{"type":"string","nullable":true},"considered_risky":{"type":"boolean"},"confirmation_delivered":{"type":"boolean"},"store_owner_notification_delivered":{"type":"boolean"},"payment_total":{"type":"string"},"display_payment_total":{"type":"string"},"metadata":{"type":"object"},"cancel_note":{"type":"string","nullable":true},"commission_amount_total":{"type":"string"},"display_commission_amount_total":{"type":"string"},"commission_tax_total":{"type":"string"},"display_commission_tax_total":{"type":"string"},"commission_total":{"type":"string"},"display_commission_total":{"type":"string"},"canceled_at":{"type":"string","nullable":true},"approved_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"preferred_stock_location_id":{"type":"string","nullable":true},"po_document_url":{"type":"string","nullable":true},"seller_id":{"type":"string","nullable":true},"seller":{"$ref":"#/components/schemas/Seller"},"order_group_id":{"type":"string","nullable":true},"tags":{"type":"array","items":{"type":"string"}},"internal_note":{"type":"string","nullable":true},"internal_note_html":{"type":"string","nullable":true},"approver_id":{"type":"string","nullable":true},"canceler_id":{"type":"string","nullable":true},"cancel_reason_id":{"type":"string","nullable":true},"cancel_reason_name":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true},"customer_id":{"type":"string","nullable":true},"applied_promotions":{"type":"array","items":{"$ref":"#/components/schemas/AppliedPromotion"}},"cart":{"$ref":"#/components/schemas/Cart"},"channel":{"$ref":"#/components/schemas/Channel"},"preferred_stock_location":{"$ref":"#/components/schemas/StockLocation"},"payment_methods":{"type":"array","items":{"$ref":"#/components/schemas/PaymentMethod"}},"customer":{"$ref":"#/components/schemas/Customer"},"approver":{"$ref":"#/components/schemas/AdminUser"},"canceler":{"$ref":"#/components/schemas/AdminUser"},"cancel_reason":{"$ref":"#/components/schemas/OrderCancellationReason"},"created_by":{"$ref":"#/components/schemas/AdminUser"},"returns":{"type":"array","items":{"$ref":"#/components/schemas/Return"}},"exchanges":{"type":"array","items":{"$ref":"#/components/schemas/Exchange"}},"claims":{"type":"array","items":{"$ref":"#/components/schemas/Claim"}},"freight_summary":{"allOf":[{"$ref":"#/components/schemas/FreightSummary"}],"nullable":true}},"required":["id","market_id","withdrawal_period_ends_at","within_withdrawal_period","cart_id","channel_id","company_id","company_name","po_document_filename","po_document_byte_size","number","email","customer_note","po_number","currency","locale","total_quantity","coupon_code","fulfillment_status","payment_status","completed_at","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","fee_total","display_fee_total","store_credit_total","display_store_credit_total","covered_by_store_credit","gift_card","market","external_references","status","last_ip_address","considered_risky","confirmation_delivered","store_owner_notification_delivered","payment_total","display_payment_total","metadata","cancel_note","commission_amount_total","display_commission_amount_total","commission_tax_total","display_commission_tax_total","commission_total","display_commission_total","canceled_at","approved_at","created_at","updated_at","preferred_stock_location_id","po_document_url","seller_id","order_group_id","tags","internal_note","internal_note_html","approver_id","canceler_id","cancel_reason_id","cancel_reason_name","created_by_id","customer_id","freight_summary"],"x-typelizer":true},"PackageType":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string"},"length":{"type":"string","nullable":true},"width":{"type":"string","nullable":true},"height":{"type":"string","nullable":true},"weight":{"type":"string","nullable":true},"max_weight":{"type":"string","nullable":true},"default":{"type":"boolean"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"dimensions_unit":{"type":"string"},"weight_unit":{"type":"string"},"volume":{"type":"string","nullable":true}},"required":["id","name","kind","length","width","height","weight","max_weight","default","metadata","created_at","updated_at","dimensions_unit","weight_unit","volume"],"x-typelizer":true},"PaymentMethod":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"type":{"type":"string"},"session_required":{"type":"boolean"},"source_required":{"type":"boolean"},"metadata":{"type":"object"},"active":{"type":"boolean"},"auto_capture":{"type":"boolean","nullable":true},"capture_method":{"type":"string","enum":["checkout","on_dispatch","manual"],"nullable":true},"resolved_capture_method":{"type":"string","enum":["checkout","on_dispatch","manual"]},"storefront_visible":{"type":"boolean"},"position":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"object"}},"required":["id","name","description","type","session_required","source_required","metadata","active","auto_capture","capture_method","resolved_capture_method","storefront_visible","position","created_at","updated_at","preferences","preference_schema"],"x-typelizer":true},"Payment":{"type":"object","properties":{"id":{"type":"string"},"payment_method_id":{"type":"string"},"response_code":{"type":"string","nullable":true},"number":{"type":"string"},"status":{"type":"string"},"amount":{"type":"string"},"display_amount":{"type":"string"},"source_type":{"type":"string","nullable":true,"enum":["credit_card","store_credit","payment_source"]},"source_id":{"type":"string","nullable":true},"source":{"anyOf":[{"$ref":"#/components/schemas/CreditCard"},{"$ref":"#/components/schemas/StoreCredit"},{"$ref":"#/components/schemas/PaymentSource"}],"nullable":true},"payment_method":{"$ref":"#/components/schemas/PaymentMethod"},"metadata":{"type":"object"},"avs_response":{"type":"string","nullable":true},"cvv_response_code":{"type":"string","nullable":true},"cvv_response_message":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"captured_amount":{"type":"string"},"order_id":{"type":"string","nullable":true},"order":{"$ref":"#/components/schemas/Order"},"refunds":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}}},"required":["id","payment_method_id","response_code","number","status","amount","display_amount","source_type","source_id","source","metadata","avs_response","cvv_response_code","cvv_response_message","created_at","updated_at","captured_amount","order_id"],"x-typelizer":true},"PaymentSource":{"type":"object","properties":{"id":{"type":"string"},"gateway_payment_profile_id":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","gateway_payment_profile_id","metadata","created_at","updated_at"],"x-typelizer":true},"Permission":{"type":"object","properties":{"key":{"type":"string"},"resource":{"type":"string"},"kind":{"type":"string"},"group":{"type":"string"},"group_label":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"}},"required":["key","resource","kind","group","group_label","label","description"],"x-typelizer":true},"Policy":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"body":{"type":"string","nullable":true},"body_html":{"type":"string","nullable":true},"updated_at":{"type":"string"},"created_at":{"type":"string"}},"required":["id","name","slug","body","body_html","updated_at","created_at"],"x-typelizer":true},"PriceAdjustmentTier":{"type":"object","properties":{"id":{"type":"string"},"min_quantity":{"type":"number"},"percentage":{"type":"string"}},"required":["id","min_quantity","percentage"],"x-typelizer":true},"PriceHistory":{"type":"object","properties":{"id":{"type":"string"},"amount":{"type":"string"},"amount_in_cents":{"type":"number"},"currency":{"type":"string"},"display_amount":{"type":"string"},"recorded_at":{"type":"string"},"variant_id":{"type":"string"},"price_id":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true},"created_at":{"type":"string"}},"required":["id","amount","amount_in_cents","currency","display_amount","recorded_at","variant_id","price_id","compare_at_amount","created_at"],"x-typelizer":true},"PriceListProduct":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"thumbnail_url":{"type":"string","nullable":true},"price_list_variants":{"type":"array","items":{"$ref":"#/components/schemas/CatalogPrice"}}},"required":["id","name","thumbnail_url"],"x-typelizer":true},"PriceList":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"status":{"type":"string"},"position":{"type":"number"},"match_policy":{"type":"string"},"adjust_compare_at":{"type":"boolean"},"starts_at":{"type":"string","nullable":true},"ends_at":{"type":"string","nullable":true},"deleted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"price_adjustment_percentage":{"type":"string","nullable":true},"automatic_pricing":{"type":"boolean"},"currently_active":{"type":"boolean"},"products_count":{"type":"number"},"prices_count":{"type":"number"},"price_adjustment_tiers":{"type":"array","items":{"$ref":"#/components/schemas/PriceAdjustmentTier"}},"price_rules":{"type":"array","items":{"$ref":"#/components/schemas/PriceRule"}}},"required":["id","name","description","status","position","match_policy","adjust_compare_at","starts_at","ends_at","deleted_at","created_at","updated_at","price_adjustment_percentage","automatic_pricing","currently_active","products_count","prices_count","price_adjustment_tiers"],"x-typelizer":true},"PriceRule":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"price_list_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"array","items":{"$ref":"#/components/schemas/PreferenceField"}},"markets":{"type":"array","items":{"$ref":"#/components/schemas/Market"}},"customer_groups":{"type":"array","items":{"$ref":"#/components/schemas/CustomerGroup"}},"channels":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}},"customers":{"type":"array","items":{"$ref":"#/components/schemas/Customer"}}},"required":["id","created_at","updated_at","type","price_list_id","preferences","preference_schema"],"x-typelizer":true},"Price":{"type":"object","properties":{"id":{"type":"string"},"amount":{"type":"string","nullable":true},"amount_in_cents":{"type":"number","nullable":true},"compare_at_amount":{"type":"string","nullable":true},"compare_at_amount_in_cents":{"type":"number","nullable":true},"currency":{"type":"string","nullable":true},"display_amount":{"type":"string","nullable":true},"display_compare_at_amount":{"type":"string","nullable":true},"price_list_id":{"type":"string","nullable":true},"min_quantity":{"type":"number"},"variant_id":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"variant":{"$ref":"#/components/schemas/Variant"}},"required":["id","amount","amount_in_cents","compare_at_amount","compare_at_amount_in_cents","currency","display_amount","display_compare_at_amount","price_list_id","min_quantity","variant_id","created_at","updated_at"],"x-typelizer":true},"ProductPublication":{"type":"object","properties":{"id":{"type":"string"},"published_at":{"type":"string","nullable":true},"unpublished_at":{"type":"string","nullable":true},"product_id":{"type":"string"},"channel_id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","published_at","unpublished_at","product_id","channel_id","created_at","updated_at"],"x-typelizer":true},"Product":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"meta_title":{"type":"string","nullable":true},"meta_description":{"type":"string","nullable":true},"meta_keywords":{"type":"string","nullable":true},"variant_count":{"type":"number"},"available_on":{"type":"string","nullable":true},"preorder_ships_at":{"type":"string","nullable":true},"purchasable":{"type":"boolean"},"preorder":{"type":"boolean"},"in_stock":{"type":"boolean"},"backorderable":{"type":"boolean"},"available":{"type":"boolean"},"description":{"type":"string","nullable":true},"description_html":{"type":"string","nullable":true},"default_variant_id":{"type":"string"},"buy_box_variant_id":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true},"tags":{"type":"array","items":{"type":"string"}},"price":{"allOf":[{"$ref":"#/components/schemas/Price"}],"nullable":true},"original_price":{"allOf":[{"$ref":"#/components/schemas/Price"}],"nullable":true},"seller_id":{"type":"string","nullable":true},"seller":{"$ref":"#/components/schemas/Seller"},"primary_media":{"$ref":"#/components/schemas/Media"},"media":{"type":"array","items":{"$ref":"#/components/schemas/Media"}},"variants":{"type":"array","items":{"$ref":"#/components/schemas/Variant"}},"default_variant":{"$ref":"#/components/schemas/Variant"},"option_types":{"type":"array","items":{"$ref":"#/components/schemas/OptionType"}},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}},"categories":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"prior_price":{"allOf":[{"$ref":"#/components/schemas/PriceHistory"}],"nullable":true},"external_references":{"type":"object"},"translations":{"type":"object"},"status":{"type":"string"},"metadata":{"type":"object"},"deleted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivery_profile_id":{"type":"string","nullable":true},"submission":{"allOf":[{"$ref":"#/components/schemas/ProductSubmission"}],"nullable":true},"seller_name":{"type":"string","nullable":true},"product_type_id":{"type":"string","nullable":true},"tax_category_id":{"type":"string","nullable":true},"digital_assets":{"type":"array","items":{"$ref":"#/components/schemas/DigitalAsset"}},"collections":{"type":"array","items":{"$ref":"#/components/schemas/Collection"}},"product_publications":{"type":"array","items":{"$ref":"#/components/schemas/ProductPublication"}},"channels":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}},"product_type":{"$ref":"#/components/schemas/ProductType"}},"required":["id","name","slug","meta_title","meta_description","meta_keywords","variant_count","available_on","preorder_ships_at","purchasable","preorder","in_stock","backorderable","available","description","description_html","default_variant_id","buy_box_variant_id","thumbnail_url","tags","price","original_price","seller_id","external_references","status","metadata","deleted_at","created_at","updated_at","delivery_profile_id","seller_name","product_type_id","tax_category_id"],"x-typelizer":true},"ProductSubmission":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"review_note":{"type":"string","nullable":true},"reviewed_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"product_id":{"type":"string"},"metadata":{"type":"object","nullable":true},"updated_at":{"type":"string"},"submitted_by_id":{"type":"string","nullable":true},"reviewed_by_id":{"type":"string","nullable":true},"reviewed_by_name":{"type":"string","nullable":true},"auto_approved":{"type":"boolean"}},"required":["id","status","review_note","reviewed_at","created_at","product_id","metadata","updated_at","submitted_by_id","reviewed_by_id","reviewed_by_name","auto_approved"],"x-typelizer":true},"ProductTypeCustomFieldDefinition":{"type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"namespace":{"type":"string"},"label":{"type":"string"},"field_type":{"type":"string","enum":["short_text","long_text","rich_text","number","boolean","json"]},"required":{"type":"boolean"},"sort_order":{"type":"number"}},"required":["id","key","namespace","label","field_type","required","sort_order"],"x-typelizer":true},"ProductType":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"translations":{"type":"object"},"products_count":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivery_profile_id":{"type":"string","nullable":true},"option_type_ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}},"custom_field_definitions":{"type":"array","items":{"$ref":"#/components/schemas/ProductTypeCustomFieldDefinition"}}},"required":["id","name","products_count","created_at","updated_at","delivery_profile_id","option_type_ids","category_ids","custom_field_definitions"],"x-typelizer":true},"PromotionAction":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"promotion_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"array","items":{"$ref":"#/components/schemas/PreferenceField"}},"calculator":{"allOf":[{"$ref":"#/components/schemas/PromotionActionCalculator"}],"nullable":true},"line_items":{"type":"array","items":{"$ref":"#/components/schemas/PromotionActionLineItem"},"nullable":true}},"required":["id","created_at","updated_at","type","promotion_id","preferences","preference_schema","calculator","line_items"],"x-typelizer":true},"PromotionRule":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"promotion_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"array","items":{"$ref":"#/components/schemas/PreferenceField"}},"product_ids":{"type":"array","items":{"type":"string"},"nullable":true},"category_ids":{"type":"array","items":{"type":"string"},"nullable":true},"customer_ids":{"type":"array","items":{"type":"string"},"nullable":true},"option_value_ids":{"type":"array","items":{"type":"string"},"nullable":true},"products":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"categories":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"customers":{"type":"array","items":{"$ref":"#/components/schemas/Customer"}},"customer_groups":{"type":"array","items":{"$ref":"#/components/schemas/CustomerGroup"}},"countries":{"type":"array","items":{"$ref":"#/components/schemas/Country"}},"channels":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}},"markets":{"type":"array","items":{"$ref":"#/components/schemas/Market"}},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}}},"required":["id","created_at","updated_at","type","promotion_id","preferences","preference_schema","product_ids","category_ids","customer_ids","option_value_ids"],"x-typelizer":true},"Promotion":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"code":{"type":"string","nullable":true},"starts_at":{"type":"string","nullable":true},"expires_at":{"type":"string","nullable":true},"usage_limit":{"type":"number","nullable":true},"match_policy":{"type":"string","enum":["all","any"]},"path":{"type":"string","nullable":true},"kind":{"type":"string","enum":["coupon_code","automatic"]},"multi_codes":{"type":"boolean"},"number_of_codes":{"type":"number","nullable":true},"code_prefix":{"type":"string","nullable":true},"promotion_category_id":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"action_ids":{"type":"array","items":{"type":"string"}},"rule_ids":{"type":"array","items":{"type":"string"}}},"required":["id","name","description","code","starts_at","expires_at","usage_limit","match_policy","path","kind","multi_codes","number_of_codes","code_prefix","promotion_category_id","metadata","created_at","updated_at","action_ids","rule_ids"],"x-typelizer":true},"RefundReason":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"can_be_deleted":{"type":"boolean"}},"required":["id","name","active","created_at","updated_at","can_be_deleted"],"x-typelizer":true},"Refund":{"type":"object","properties":{"id":{"type":"string"},"transaction_id":{"type":"string","nullable":true},"amount":{"type":"string","nullable":true},"payment_id":{"type":"string","nullable":true},"refund_reason_id":{"type":"string","nullable":true},"originator_id":{"type":"string","nullable":true},"originator_type":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"payment":{"$ref":"#/components/schemas/Payment"}},"required":["id","transaction_id","amount","payment_id","refund_reason_id","originator_id","originator_type","metadata","created_at","updated_at"],"x-typelizer":true},"ReturnLineItem":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"received_quantity":{"type":"number"},"resellable":{"type":"boolean"},"pre_tax_amount":{"type":"string"},"display_pre_tax_amount":{"type":"string"},"variant_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"fulfillment_item_id":{"type":"string","nullable":true},"variant":{"$ref":"#/components/schemas/Variant"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"line_item":{"$ref":"#/components/schemas/LineItem"}},"required":["id","quantity","received_quantity","resellable","pre_tax_amount","display_pre_tax_amount","variant_id","line_item_id","fulfillment_item_id","created_at","updated_at"],"x-typelizer":true},"ReturnReason":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"can_be_deleted":{"type":"boolean"}},"required":["id","name","active","created_at","updated_at","can_be_deleted"],"x-typelizer":true},"Return":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"status":{"type":"string"},"order_id":{"type":"string","nullable":true},"reason_id":{"type":"string","nullable":true},"refund_total":{"type":"string"},"display_refund_total":{"type":"string"},"approved_at":{"type":"string","nullable":true},"received_at":{"type":"string","nullable":true},"refunded_at":{"type":"string","nullable":true},"canceled_at":{"type":"string","nullable":true},"reason":{"$ref":"#/components/schemas/ReturnReason"},"return_line_items":{"type":"array","items":{"$ref":"#/components/schemas/ReturnLineItem"}},"memo":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"stock_location_id":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true},"refunded_total":{"type":"string"},"refundable_total":{"type":"string"},"order":{"$ref":"#/components/schemas/Order"},"stock_location":{"$ref":"#/components/schemas/StockLocation"},"refunds":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}},"documents":{"type":"object"},"labels":{"type":"array","items":{"$ref":"#/components/schemas/ShippingLabel"}},"deliveries":{"type":"array","items":{"$ref":"#/components/schemas/Delivery"}}},"required":["id","number","status","order_id","reason_id","refund_total","display_refund_total","approved_at","received_at","refunded_at","canceled_at","memo","metadata","created_at","updated_at","stock_location_id","created_by_id","refunded_total","refundable_total","documents","labels","deliveries"],"x-typelizer":true},"Role":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"permissions":{"type":"array","items":{"type":"string"}},"mutable":{"type":"boolean"},"users_count":{"type":"number"}},"required":["id","name","description","created_at","updated_at","permissions","mutable","users_count"],"x-typelizer":true},"SellerPayout":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"currency":{"type":"string"},"provider":{"type":"string"},"reference":{"type":"string","nullable":true},"metadata":{"type":"object"},"period_start":{"type":"string","nullable":true},"period_end":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"amount":{"type":"string"},"display_amount":{"type":"string"},"seller_id":{"type":"string"},"seller_name":{"type":"string","nullable":true},"transfers_count":{"type":"number"}},"required":["id","status","currency","provider","reference","metadata","period_start","period_end","created_at","updated_at","amount","display_amount","seller_id","seller_name","transfers_count"],"x-typelizer":true},"SellerRequirement":{"type":"object","properties":{"id":{"type":"string"},"position":{"type":"number"},"active":{"type":"boolean"},"required":{"type":"boolean"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"kind":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"preferences":{"type":"object"},"custom_field_definition_ids":{"type":"array","items":{"type":"string"}},"allow_multiple":{"type":"boolean"},"accepts_submissions":{"type":"boolean"},"reviewed_by_operator":{"type":"boolean"}},"required":["id","position","active","required","metadata","created_at","updated_at","kind","name","description","preferences","custom_field_definition_ids","allow_multiple","accepts_submissions","reviewed_by_operator"],"x-typelizer":true},"SellerRequirementStatus":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"required":{"type":"boolean"},"position":{"type":"number"},"status":{"type":"string"},"action_url":{"type":"string","nullable":true},"blocker":{"type":"object","nullable":true},"blocking":{"type":"boolean"},"required_policy_name":{"type":"string","nullable":true},"submission":{"$ref":"#/components/schemas/SellerRequirementSubmission"},"published_policy":{"$ref":"#/components/schemas/Policy"}},"required":["id","kind","name","description","required","position","status","action_url","blocker","blocking","required_policy_name"],"x-typelizer":true},"SellerRequirementSubmission":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"note":{"type":"string","nullable":true},"review_note":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true},"reviewed_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"seller_id":{"type":"string"},"requirement_id":{"type":"string"},"requirement_name":{"type":"string"},"file_url":{"type":"string","nullable":true},"file_name":{"type":"string","nullable":true}},"required":["id","status","note","review_note","reference","metadata","reviewed_at","created_at","updated_at","seller_id","requirement_id","requirement_name","file_url","file_name"],"x-typelizer":true},"Seller":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"about":{"type":"string"},"about_html":{"type":"string"},"logo_url":{"type":"string","nullable":true},"square_logo_url":{"type":"string","nullable":true},"cover_photo_url":{"type":"string","nullable":true},"status":{"type":"string"},"contact_email":{"type":"string","nullable":true},"billing_email":{"type":"string","nullable":true},"tax_remittance":{"type":"string"},"payouts_schedule_interval":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true},"holiday_mode_until":{"type":"string","nullable":true},"terms_accepted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"deleted_at":{"type":"string","nullable":true},"minimum_payout_amount":{"type":"string","nullable":true},"on_holiday":{"type":"boolean"},"sellable":{"type":"boolean"},"products_count":{"type":"number"},"users_count":{"type":"number"},"onboarding_progress":{"type":"object"},"onboarding_complete":{"type":"boolean"},"legal_name":{"type":"string","nullable":true},"registration_number":{"type":"string","nullable":true},"billing_address":{"$ref":"#/components/schemas/Address"},"returns_address":{"$ref":"#/components/schemas/Address"}},"required":["id","name","slug","about","about_html","logo_url","square_logo_url","cover_photo_url","status","contact_email","billing_email","tax_remittance","payouts_schedule_interval","metadata","holiday_mode_until","terms_accepted_at","created_at","updated_at","deleted_at","minimum_payout_amount","on_holiday","sellable","products_count","users_count","onboarding_progress","onboarding_complete","legal_name","registration_number"],"x-typelizer":true},"SellerTeamMember":{"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"},"avatar_url":{"type":"string","nullable":true}},"required":["id","email","first_name","last_name","full_name","created_at","updated_at","avatar_url"],"x-typelizer":true},"SellerTransfer":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"status":{"type":"string"},"currency":{"type":"string"},"provider":{"type":"string"},"reference":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"amount":{"type":"string"},"display_amount":{"type":"string"},"seller_id":{"type":"string"},"order_id":{"type":"string","nullable":true},"payout_id":{"type":"string","nullable":true},"reversed_from_id":{"type":"string","nullable":true},"refund_id":{"type":"string","nullable":true},"seller_name":{"type":"string","nullable":true},"order_number":{"type":"string","nullable":true}},"required":["id","kind","status","currency","provider","reference","metadata","created_at","updated_at","amount","display_amount","seller_id","order_id","payout_id","reversed_from_id","refund_id","seller_name","order_number"],"x-typelizer":true},"SetupTask":{"type":"object","properties":{"name":{"type":"string"},"done":{"type":"boolean"}},"required":["name","done"],"x-typelizer":true},"ShippingLabel":{"type":"object","properties":{"id":{"type":"string"},"source":{"type":"string"},"status":{"type":"string"},"carrier":{"type":"string","nullable":true},"carrier_name":{"type":"string","nullable":true},"service":{"type":"string","nullable":true},"tracking_number":{"type":"string","nullable":true},"currency":{"type":"string","nullable":true},"format":{"type":"string","nullable":true},"external_id":{"type":"string","nullable":true},"metadata":{"type":"object"},"refunded_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"owner_id":{"type":"string"},"owner_type":{"type":"string"},"cost":{"type":"string"},"display_cost":{"type":"string"},"integration_id":{"type":"string","nullable":true},"file_pending":{"type":"boolean"},"download_url":{"type":"string","nullable":true}},"required":["id","source","status","carrier","carrier_name","service","tracking_number","currency","format","external_id","metadata","refunded_at","created_at","updated_at","owner_id","owner_type","cost","display_cost","integration_id","file_pending","download_url"],"x-typelizer":true},"State":{"type":"object","properties":{"abbr":{"type":"string"},"name":{"type":"string"}},"required":["abbr","name"],"x-typelizer":true},"StockLevel":{"type":"object","properties":{"id":{"type":"string"},"count_on_hand":{"type":"number"},"backorderable":{"type":"boolean"},"stock_location_id":{"type":"string","nullable":true},"variant_id":{"type":"string","nullable":true},"external_references":{"type":"object"},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"allocated_count":{"type":"number"},"available_count":{"type":"number"},"stock_location":{"$ref":"#/components/schemas/StockLocation"},"variant":{"$ref":"#/components/schemas/Variant"}},"required":["id","count_on_hand","backorderable","stock_location_id","variant_id","external_references","metadata","created_at","updated_at","allocated_count","available_count"],"x-typelizer":true},"StockLocation":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"address1":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"country_name":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"state_text":{"type":"string","nullable":true},"pickup_ready_in_minutes":{"type":"number","nullable":true},"pickup_instructions":{"type":"string","nullable":true},"external_references":{"type":"object"},"admin_name":{"type":"string","nullable":true},"address2":{"type":"string","nullable":true},"state_name":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"active":{"type":"boolean"},"default":{"type":"boolean"},"backorderable_default":{"type":"boolean"},"propagate_all_variants":{"type":"boolean"},"kind":{"type":"string"},"pickup_enabled":{"type":"boolean"},"pickup_stock_policy":{"type":"string"},"returns_enabled":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"seller_id":{"type":"string","nullable":true},"seller_name":{"type":"string","nullable":true},"seller":{"$ref":"#/components/schemas/Seller"}},"required":["id","name","address1","city","zipcode","country_code","country_name","state_code","state_text","pickup_ready_in_minutes","pickup_instructions","external_references","admin_name","address2","state_name","phone","company","active","default","backorderable_default","propagate_all_variants","kind","pickup_enabled","pickup_stock_policy","returns_enabled","created_at","updated_at","seller_id","seller_name"],"x-typelizer":true},"StockMovement":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"kind":{"type":"string","nullable":true},"reason":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"stock_level_id":{"type":"string","nullable":true},"order_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true},"return_id":{"type":"string","nullable":true},"exchange_id":{"type":"string","nullable":true},"stock_transfer_id":{"type":"string","nullable":true}},"required":["id","quantity","kind","reason","created_at","updated_at","stock_level_id","order_id","fulfillment_id","return_id","exchange_id","stock_transfer_id"],"x-typelizer":true},"StockReservation":{"type":"object","properties":{"id":{"type":"string"},"stock_level_id":{"type":"string"},"line_item_id":{"type":"string"},"order_id":{"type":"string"},"variant_id":{"type":"string","nullable":true},"stock_location_id":{"type":"string","nullable":true},"quantity":{"type":"number"},"expires_at":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","stock_level_id","line_item_id","order_id","variant_id","stock_location_id","quantity","expires_at","active","created_at","updated_at"],"x-typelizer":true},"StockTransfer":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"reference":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"source_location_id":{"type":"string","nullable":true},"destination_location_id":{"type":"string","nullable":true},"source_location":{"$ref":"#/components/schemas/StockLocation"},"destination_location":{"$ref":"#/components/schemas/StockLocation"}},"required":["id","number","reference","metadata","created_at","updated_at","source_location_id","destination_location_id"],"x-typelizer":true},"StoreCredit":{"type":"object","properties":{"id":{"type":"string"},"amount":{"type":"string"},"amount_used":{"type":"string"},"amount_remaining":{"type":"string"},"display_amount":{"type":"string"},"display_amount_used":{"type":"string"},"display_amount_remaining":{"type":"string"},"currency":{"type":"string"},"memo":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"customer_id":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true}},"required":["id","amount","amount_used","amount_remaining","display_amount","display_amount_used","display_amount_remaining","currency","memo","metadata","created_at","updated_at","customer_id","created_by_id"],"x-typelizer":true},"Store":{"type":"object","properties":{"id":{"type":"string"},"metadata":{"type":"object"},"name":{"type":"string"},"code":{"type":"string"},"preferred_storefront_url":{"type":"string","nullable":true},"default_currency":{"type":"string"},"default_locale":{"type":"string"},"default_country_code":{"type":"string","nullable":true},"mail_from_address":{"type":"string","nullable":true},"customer_support_email":{"type":"string","nullable":true},"new_order_notifications_email":{"type":"string","nullable":true},"preferred_send_consumer_transactional_emails":{"type":"boolean"},"preferred_admin_locale":{"type":"string","nullable":true},"preferred_timezone":{"type":"string"},"preferred_weight_unit":{"type":"string"},"preferred_unit_system":{"type":"string"},"preferred_storefront_access":{"type":"string"},"preferred_guest_checkout":{"type":"boolean"},"preferred_company_field_enabled":{"type":"boolean"},"preferred_address_requires_company":{"type":"boolean"},"preferred_address_requires_phone":{"type":"boolean"},"preferred_capture_method":{"type":"string"},"preferred_track_inventory_levels":{"type":"boolean"},"preferred_stock_reservations_enabled":{"type":"boolean"},"preferred_tax_using_ship_address":{"type":"boolean"},"preferred_track_price_history":{"type":"boolean"},"preferred_show_products_without_price":{"type":"boolean"},"preferred_disable_sku_validation":{"type":"boolean"},"preferred_order_routing_strategy":{"type":"string"},"preferred_pricing_provider":{"type":"string"},"preferred_inventory_provider":{"type":"string"},"preferred_pricing_provider_failure_policy":{"type":"string"},"preferred_inventory_provider_failure_policy":{"type":"string"},"preferred_payout_provider":{"type":"string","nullable":true},"preferred_default_payouts_schedule_interval":{"type":"string"},"preferred_default_minimum_payout_amount":{"type":"number"},"preferred_document_number_format":{"type":"string"},"preferred_order_number_prefix":{"type":"string"},"preferred_order_number_suffix":{"type":"string"},"preferred_order_number_sequence_start":{"type":"number"},"preferred_limit_digital_download_count":{"type":"boolean"},"preferred_digital_asset_authorized_clicks":{"type":"number"},"preferred_limit_digital_download_days":{"type":"boolean"},"preferred_digital_asset_authorized_days":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"order_number_sequence_started":{"type":"boolean"},"url":{"type":"string"},"api_url":{"type":"string"},"setup_tasks":{"type":"array","items":{"$ref":"#/components/schemas/SetupTask"}},"supported_currencies":{"type":"array","items":{"type":"string"}},"supported_locales":{"type":"array","items":{"type":"string"}},"available_locales":{"type":"array","items":{"type":"string"}},"logo_url":{"type":"string","nullable":true},"mailer_logo_url":{"type":"string","nullable":true}},"required":["id","metadata","name","code","preferred_storefront_url","default_currency","default_locale","default_country_code","mail_from_address","customer_support_email","new_order_notifications_email","preferred_send_consumer_transactional_emails","preferred_admin_locale","preferred_timezone","preferred_weight_unit","preferred_unit_system","preferred_storefront_access","preferred_guest_checkout","preferred_company_field_enabled","preferred_address_requires_company","preferred_address_requires_phone","preferred_capture_method","preferred_track_inventory_levels","preferred_stock_reservations_enabled","preferred_tax_using_ship_address","preferred_track_price_history","preferred_show_products_without_price","preferred_disable_sku_validation","preferred_order_routing_strategy","preferred_pricing_provider","preferred_inventory_provider","preferred_pricing_provider_failure_policy","preferred_inventory_provider_failure_policy","preferred_payout_provider","preferred_default_payouts_schedule_interval","preferred_default_minimum_payout_amount","preferred_document_number_format","preferred_order_number_prefix","preferred_order_number_suffix","preferred_order_number_sequence_start","preferred_limit_digital_download_count","preferred_digital_asset_authorized_clicks","preferred_limit_digital_download_days","preferred_digital_asset_authorized_days","created_at","updated_at","order_number_sequence_started","url","api_url","setup_tasks","supported_currencies","supported_locales","available_locales","logo_url","mailer_logo_url"],"x-typelizer":true},"TaxCategory":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"tax_code":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"is_default":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","name","tax_code","description","is_default","created_at","updated_at"],"x-typelizer":true},"TaxExemptionCertificate":{"type":"object","properties":{"id":{"type":"string"},"certificate_number":{"type":"string"},"reason_code":{"type":"string"},"status":{"type":"string"},"issuing_authority":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true},"issued_at":{"type":"string"},"expires_at":{"type":"string"},"verified_at":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"company_id":{"type":"string"},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"active":{"type":"boolean"},"lapsed":{"type":"boolean"},"can_be_deleted":{"type":"boolean"},"document_filename":{"type":"string","nullable":true},"document_byte_size":{"type":"number","nullable":true},"document_url":{"type":"string","nullable":true}},"required":["id","certificate_number","reason_code","status","issuing_authority","metadata","issued_at","expires_at","verified_at","created_at","updated_at","company_id","country_code","state_code","active","lapsed","can_be_deleted","document_filename","document_byte_size","document_url"],"x-typelizer":true},"TaxIdentifier":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"value":{"type":"string"},"validation_status":{"type":"string","nullable":true},"validation_evidence":{"type":"object","nullable":true},"source":{"type":"string","nullable":true},"validated_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"validatable":{"type":"boolean"},"customer_id":{"type":"string","nullable":true},"cart_id":{"type":"string","nullable":true},"order_id":{"type":"string","nullable":true}},"required":["id","kind","value","validation_status","validation_evidence","source","validated_at","created_at","updated_at","validatable","customer_id","cart_id","order_id"],"x-typelizer":true},"TaxLine":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"included":{"type":"boolean"},"rate":{"type":"string"},"tax_rate_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true},"fee_id":{"type":"string","nullable":true},"amount":{"type":"string"},"display_amount":{"type":"string"},"provider_id":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true},"taxability_reason":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"data":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","label","included","rate","tax_rate_id","line_item_id","fulfillment_id","fee_id","amount","display_amount","provider_id","metadata","taxability_reason","country_code","state_code","data","created_at","updated_at"],"x-typelizer":true},"TaxRate":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"included_in_price":{"type":"boolean"},"show_rate_in_label":{"type":"boolean"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"deleted_at":{"type":"string","nullable":true},"amount":{"type":"string"},"amount_percentage":{"type":"number","nullable":true},"tax_category_id":{"type":"string","nullable":true},"store_id":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true}},"required":["id","name","included_in_price","show_rate_in_label","metadata","created_at","updated_at","deleted_at","amount","amount_percentage","tax_category_id","store_id","country_code","state_code"],"x-typelizer":true},"Variant":{"type":"object","properties":{"id":{"type":"string"},"product_id":{"type":"string"},"sku":{"type":"string","nullable":true},"options_text":{"type":"string"},"track_inventory":{"type":"boolean"},"media_count":{"type":"number"},"preorder_ships_at":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true},"purchasable":{"type":"boolean"},"in_stock":{"type":"boolean"},"backorderable":{"type":"boolean"},"preorder":{"type":"boolean"},"weight":{"type":"number","nullable":true},"height":{"type":"number","nullable":true},"width":{"type":"number","nullable":true},"depth":{"type":"number","nullable":true},"minimum_order_quantity":{"type":"number","nullable":true},"order_multiple":{"type":"number","nullable":true},"purchase_unit":{"type":"string","nullable":true},"units_per_carton":{"type":"number","nullable":true},"price":{"$ref":"#/components/schemas/Price"},"original_price":{"allOf":[{"$ref":"#/components/schemas/Price"}],"nullable":true},"seller_id":{"type":"string","nullable":true},"seller":{"$ref":"#/components/schemas/Seller"},"primary_media":{"$ref":"#/components/schemas/Media"},"media":{"type":"array","items":{"$ref":"#/components/schemas/Media"}},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}},"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"prior_price":{"allOf":[{"$ref":"#/components/schemas/PriceHistory"}],"nullable":true},"external_references":{"type":"object"},"metadata":{"type":"object"},"position":{"type":"number"},"cost_price":{"type":"string","nullable":true},"cost_currency":{"type":"string","nullable":true},"barcode":{"type":"string","nullable":true},"backorder_limit":{"type":"number","nullable":true},"hs_code":{"type":"string","nullable":true},"country_of_origin":{"type":"string","nullable":true},"customs_description":{"type":"string","nullable":true},"carton_weight":{"type":"string","nullable":true},"cartons_per_pallet":{"type":"number","nullable":true},"deleted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"preorderable":{"type":"boolean"},"tax_category_id":{"type":"string","nullable":true},"weight_unit":{"type":"string","nullable":true},"dimensions_unit":{"type":"string","nullable":true},"carton_package_type_id":{"type":"string","nullable":true},"units_per_pallet":{"type":"number","nullable":true},"available_stock":{"type":"number","nullable":true},"reserved_quantity":{"type":"number"},"total_on_hand":{"type":"number","nullable":true},"product_name":{"type":"string"},"delivery_profile_id":{"type":"string","nullable":true},"prices":{"type":"array","items":{"$ref":"#/components/schemas/Price"}},"stock_levels":{"type":"array","items":{"$ref":"#/components/schemas/StockLevel"}}},"required":["id","product_id","sku","options_text","track_inventory","media_count","preorder_ships_at","thumbnail_url","purchasable","in_stock","backorderable","preorder","weight","height","width","depth","minimum_order_quantity","order_multiple","purchase_unit","units_per_carton","price","original_price","seller_id","option_values","external_references","metadata","position","cost_price","cost_currency","barcode","backorder_limit","hs_code","country_of_origin","customs_description","carton_weight","cartons_per_pallet","deleted_at","created_at","updated_at","preorderable","tax_category_id","weight_unit","dimensions_unit","carton_package_type_id","units_per_pallet","available_stock","reserved_quantity","total_on_hand","product_name","delivery_profile_id"],"x-typelizer":true},"WebhookDelivery":{"type":"object","properties":{"id":{"type":"string"},"event_name":{"type":"string"},"event_id":{"type":"string","nullable":true},"response_code":{"type":"number","nullable":true},"execution_time":{"type":"number","nullable":true},"error_type":{"type":"string","nullable":true},"request_errors":{"type":"string","nullable":true},"response_body":{"type":"string","nullable":true},"success":{"type":"boolean","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivered_at":{"type":"string","nullable":true},"payload":{"type":"object"},"webhook_endpoint_id":{"type":"string"},"webhook_endpoint_url":{"type":"string"}},"required":["id","event_name","event_id","response_code","execution_time","error_type","request_errors","response_body","success","created_at","updated_at","delivered_at","payload","webhook_endpoint_id","webhook_endpoint_url"],"x-typelizer":true},"WebhookEndpoint":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","nullable":true},"url":{"type":"string"},"active":{"type":"boolean"},"subscriptions":{"type":"array","items":{"type":"string"}},"disabled_reason":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"disabled_at":{"type":"string","nullable":true},"secret_key":{"type":"string","nullable":true},"last_delivery_at":{"type":"string","nullable":true},"recent_delivery_count":{"type":"number"},"recent_failure_count":{"type":"number"},"total_delivery_count":{"type":"number"},"successful_delivery_count":{"type":"number"},"failed_delivery_count":{"type":"number"}},"required":["id","name","url","active","subscriptions","disabled_reason","created_at","updated_at","disabled_at","secret_key","last_delivery_at","recent_delivery_count","recent_failure_count","total_delivery_count","successful_delivery_count","failed_delivery_count"],"x-typelizer":true}}}}\ No newline at end of file+{"info":{"title":"Admin API","contact":{"name":"Spree Commerce","url":"https://spreecommerce.org","email":"[email protected]"},"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"},"paths":{"/api/v3/admin/auth/login":{"post":{"summary":"Login","tags":["Authentication"],"security":[{"api_key":[]}],"description":"Authenticates an admin user and returns a short-lived JWT access token.\nThe rotatable refresh token is set in an HttpOnly cookie — it is not\nincluded in the response body.\n\nThe `provider` field selects the authentication method. When omitted it\ndefaults to `email`, the built-in email/password login.\n\nTo authenticate against a third-party identity provider (Okta, Azure AD,\nGoogle Workspace SSO, a custom JWT issuer, SAML, etc.), send\n`{ \"provider\": \"<your_key>\", ... }` with the fields that provider\nrequires. The endpoint returns the same JWT regardless of which provider\nauthenticated the request. See\n[Custom API Authentication](https://spreecommerce.org/docs/developer/how-to/custom-api-authentication)\nfor the list of configured providers and their required fields.\n","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"login successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResponse"}}}},"401":{"description":"invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"title":"EmailPasswordLogin","description":"Built-in email/password authentication (default when `provider` is omitted).","type":"object","properties":{"provider":{"type":"string","enum":["email"],"default":"email"},"email":{"type":"string","format":"email"},"password":{"type":"string"}},"required":["email","password"]},{"title":"ProviderLogin","description":"Provider-dispatched login. The `provider` key selects a configured\nauthentication provider; the remaining fields are forwarded to it.\nRequired fields depend on the provider — see\n[Custom API Authentication](https://spreecommerce.org/docs/developer/how-to/custom-api-authentication).\n","type":"object","properties":{"provider":{"type":"string","description":"Registered provider key (anything other than `email`).","not":{"enum":["email"]}}},"required":["provider"],"additionalProperties":true}]}}}}}},"/api/v3/admin/auth/refresh":{"post":{"summary":"Refresh token","tags":["Authentication"],"security":[{"api_key":[]}],"description":"Exchanges the HttpOnly refresh-token cookie for a new access JWT and a\nrotated refresh token cookie. No request body or Authorization header\nis required — the cookie alone authenticates the call.\n","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"refresh successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResponse"}}}},"401":{"description":"missing or invalid refresh-token cookie","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/auth/logout":{"post":{"summary":"Logout","tags":["Authentication"],"security":[{"api_key":[]}],"description":"Revokes the refresh-token cookie, effectively logging the admin out.","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"logout successful"}}}},"/api/v3/admin/me":{"get":{"summary":"Get current admin user and permissions","tags":["Authentication"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the current admin user profile and a serialized list of permissions (CanCanCan rules). The SPA uses these to drive UI permission checks.","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"current admin user and permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeResponse"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update the current admin profile","tags":["Authentication"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Self-service update of the signed-in admin's own profile, such as their admin UI display language (`selected_locale`).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"profile updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"selected_locale":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"}}}}}}}},"/api/v3/admin/auth/password_resets":{"post":{"summary":"Request password reset","tags":["Authentication"],"security":[{"api_key":[]}],"description":"Requests a password reset email for an admin user. Always returns `202`\nwhether or not the email matches an account, to prevent enumeration.\n\n`redirect_url` is where the emailed link should point (the reset token\nis appended as a `token` query param). It must match one of the store's\nallowed origins — otherwise it is silently ignored and the server-side\ndefault is used. The email is delivered by Spree itself via the\n`admin_user.password_reset_requested` event; this event is never\nforwarded to webhook endpoints.\n","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"202":{"description":"reset requested","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"redirect_url":{"type":"string","description":"Must match an allowed origin of the store; ignored otherwise."}},"required":["email"]}}}}}},"/api/v3/admin/auth/password_resets/{id}":{"patch":{"summary":"Reset password","tags":["Authentication"],"security":[{"api_key":[]}],"description":"Consumes a password reset token (the `token` query param from the\nemailed link), sets the new password, and signs the admin in: the\nresponse carries a JWT access token and the rotatable refresh token is\nset in an HttpOnly cookie. The token is single-use — it invalidates as\nsoon as the password changes.\n","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","description":"The reset token from the emailed link","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"password reset","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResponse"}}}},"422":{"description":"invalid or expired token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"password":{"type":"string"},"password_confirmation":{"type":"string"}},"required":["password","password_confirmation"]}}}}}},"/api/v3/admin/auth/setup":{"get":{"summary":"Check first-run setup availability","tags":["Authentication"],"description":"Reports whether first-run setup is still available — true only while\nthe installation has no admin user. Unauthenticated; the dashboard\nlogin page uses it to offer the setup screen.\n","responses":{"200":{"description":"setup status","content":{"application/json":{}}}}},"post":{"summary":"Complete first-run setup","tags":["Authentication"],"description":"Creates the first admin account and adopts the seeded store, authorized\nby the one-time setup token printed at install time (rotate it with\n`bin/rails spree:setup:token`). Issues a JWT access token and a\nrefresh-token cookie exactly like login. Returns 404 once any admin\nuser exists — the flow is closed permanently after setup.\n","parameters":[],"responses":{"200":{"description":"setup completed","content":{"application/json":{}}},"404":{"description":"setup not available","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["setup_token","email","password","country_code"],"properties":{"setup_token":{"type":"string","description":"One-time token from the install output."},"email":{"type":"string","format":"email"},"password":{"type":"string"},"password_confirmation":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"store_name":{"type":"string"},"country_code":{"type":"string","description":"ISO 3166-1 alpha-2 country the store sells from. Determines the default market, the warehouse, the delivery zones and the currency."},"locale":{"type":"string","description":"Storefront locale. Defaults to the country's own language."},"currency":{"type":"string","description":"ISO 4217 currency. Defaults to the country's own currency — pass one only when the store prices in something else."}}}}}}}},"/api/v3/admin/auth/setup/countries":{"get":{"summary":"List countries for first-run setup","tags":["Authentication"],"description":"Countries the store can be set up in, each with the currency and\nofficial languages derived from it. Unauthenticated, because the setup\nscreen runs before any credential exists. Returns 404 once any admin\nuser exists.\n","responses":{"200":{"description":"countries","content":{"application/json":{}}}}}},"/api/v3/admin/allowed_origins":{"get":{"summary":"List allowed origins","tags":["Allowed Origins"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the CORS allowlist for the current store. Each entry is a\nbare `scheme://host[:port]` permitted to call the admin API from a\nbrowser. Backs the `Rack::Cors` allowlist and the CSRF boundary of\nthe admin cookie session (see\n`docs/plans/5.5-admin-auth-cookie-refresh.md`).\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[origin_cont]","in":"query","required":false,"description":"Filter by origin (contains)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"allowed origins found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AllowedOrigin"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create an allowed origin","tags":["Allowed Origins"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds an origin to the admin CORS allowlist. The value must be a bare\n`scheme://host[:port]` (no path, query, or fragment) and use `http` or\n`https`.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"allowed origin created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AllowedOrigin"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"origin":{"type":"string"}},"required":["origin"]}}}}}},"/api/v3/admin/allowed_origins/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Allowed origin ID","schema":{"type":"string"}}],"get":{"summary":"Get an allowed origin","tags":["Allowed Origins"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single allowed origin by prefixed ID.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"allowed origin found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AllowedOrigin"}}}},"404":{"description":"allowed origin not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update an allowed origin","tags":["Allowed Origins"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an existing allowed origin.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"allowed origin updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AllowedOrigin"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"origin":{"type":"string"}}}}}}},"delete":{"summary":"Delete an allowed origin","tags":["Allowed Origins"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes an origin from the admin CORS allowlist. After deletion the\nadmin SPA running at that origin will no longer be able to call the\nadmin API from a browser.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"allowed origin deleted"}}}},"/api/v3/admin/api_keys":{"get":{"summary":"List API keys","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns publishable and secret API keys for the current store. Secret keys are listed by `token_prefix` only — the plaintext token is delivered exactly once on create.\n\n**Required scope:** `read_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"API keys found","content":{"application/json":{}}}}},"post":{"summary":"Create an API key","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a publishable or secret API key. The plaintext token is included in the response **once** for secret keys; publishable keys expose their token on every read since they are intended for client-side use.\n\n**Required scope:** `write_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"secret key created — plaintext token returned once","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name","key_type"],"properties":{"name":{"type":"string"},"key_type":{"type":"string","enum":["publishable","secret"]},"scopes":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/api_keys/{id}":{"get":{"summary":"Show an API key","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"API key found","content":{"application/json":{}}}}},"patch":{"summary":"Update an API key","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Renames a key. `key_type` and `scopes` are fixed at creation — to change a key's authority, create a new key and revoke the old one.\n\n**Required scope:** `write_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"API key renamed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"}}}}}}},"delete":{"summary":"Delete an API key","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"API key deleted"}}}},"/api/v3/admin/api_keys/current":{"get":{"summary":"Describe the current API key","tags":["API Keys"],"security":[{"api_key":[]}],"description":"Returns the secret key that authenticated this request, including its live scopes. Useful to confirm a key's real, current authority. Only secret-key principals have a single key to describe.\n\n**Required scope:** none — any key can describe itself (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"current API key","content":{"application/json":{}}}}}},"/api/v3/admin/api_keys/{id}/revoke":{"patch":{"summary":"Revoke an API key","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Marks the key revoked. Future requests using its token will fail; the row is preserved for audit.\n\n**Required scope:** `write_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"API key revoked","content":{"application/json":{}}}}}},"/api/v3/admin/categories":{"get":{"summary":"List categories","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of the store's categories (manual hierarchical taxons; rule-based collections are excluded).\n\n**Required scope:** `read_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., children, parent, ancestors).","schema":{"type":"string"}}],"responses":{"200":{"description":"categories found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a category. Nests under the parent when parent_id is given, otherwise creates a top-level category.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"category created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Category"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"parent_id":{"type":"string","description":"Prefixed ID of the parent category"},"description":{"type":"string"},"permalink":{"type":"string"},"meta_title":{"type":"string"},"meta_description":{"type":"string"},"meta_keywords":{"type":"string"}},"required":["name"]}}}}}},"/api/v3/admin/categories/{id}":{"get":{"summary":"Get a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single category by ID.\n\n**Required scope:** `read_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., children, parent, ancestors).","schema":{"type":"string"}}],"responses":{"200":{"description":"category found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Category"}}}},"404":{"description":"category not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a category.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"200":{"description":"category updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Category"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"parent_id":{"type":"string","description":"Prefixed ID of the parent category"},"description":{"type":"string"},"permalink":{"type":"string"},"meta_title":{"type":"string"},"meta_description":{"type":"string"},"meta_keywords":{"type":"string"}}}}}}},"delete":{"summary":"Delete a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a category and its descendants.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"204":{"description":"category deleted"}}}},"/api/v3/admin/categories/{id}/reposition":{"patch":{"summary":"Reposition a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Moves a category to a new parent and/or index within the tree.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"200":{"description":"category repositioned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Category"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"new_parent_id":{"type":"string","description":"Prefixed ID of the new parent (omit for top level)"},"new_position":{"type":"integer","description":"0-based index among the new parent's children"}},"required":["new_position"]}}}}}},"/api/v3/admin/categories/{category_id}/products":{"get":{"summary":"List category products","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Products classified under the category, ordered by their classification position.\n\n**Required scope:** `read_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"category_id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"200":{"description":"products found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Add products to a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Classifies products under the category in bulk (appended to the end). Already-classified products are skipped; the count reports what was added.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"category_id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"201":{"description":"products added","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}},"delete":{"summary":"Remove products from a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes products from the category's manual classification in bulk. Ids that are not classified are ignored; the count reports what was removed.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"category_id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"200":{"description":"products removed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}}},"/api/v3/admin/categories/{category_id}/products/{id}/reposition":{"patch":{"summary":"Reposition a category product","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Moves a product to a new index among the category's products.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"category_id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"204":{"description":"product repositioned"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"new_position":{"type":"integer","description":"0-based index among the category's products"}},"required":["new_position"]}}}}}},"/api/v3/admin/channels":{"get":{"summary":"List channels","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the channels configured for the current store.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"channels found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new channel on the current store. `code` is normalized to a\nURL-safe slug (`Point of Sale` → `point-of-sale`); when omitted it's\nderived from `name`.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"channel created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"code":{"type":"string","description":"Slug — auto-derived from `name` when blank."},"active":{"type":"boolean","default":true},"default":{"type":"boolean","default":false},"preferred_order_routing_strategy":{"type":"string","nullable":true,"description":"Routing strategy class name. `null` inherits the store setting."},"preferred_storefront_access":{"type":"string","nullable":true,"enum":["public","prices_hidden","login_required"],"description":"Anonymous-visitor access posture. `null` inherits the store setting."},"preferred_guest_checkout":{"type":"boolean","nullable":true,"description":"Whether guests can check out without an account. `null` inherits the store setting."}}}}}}}},"/api/v3/admin/channels/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"channel found","content":{"application/json":{}}}}},"patch":{"summary":"Update a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"channel updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"code":{"type":"string"},"active":{"type":"boolean"},"default":{"type":"boolean"},"preferred_order_routing_strategy":{"type":"string","nullable":true,"description":"Routing strategy class name. `null` inherits the store setting."},"preferred_storefront_access":{"type":"string","nullable":true,"enum":["public","prices_hidden","login_required"],"description":"Anonymous-visitor access posture. `null` inherits the store setting."},"preferred_guest_checkout":{"type":"boolean","nullable":true,"description":"Whether guests can check out without an account. `null` inherits the store setting."}}}}}}},"delete":{"summary":"Delete a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"channel deleted"}}}},"/api/v3/admin/channels/{id}/add_products":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Publish products on a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Publishes the listed products on this channel. Idempotent — re-publishing\nan already-published product updates its publication window. Products from\nsibling stores are silently dropped.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products published","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["product_ids"],"properties":{"product_ids":{"type":"array","items":{"type":"string"}},"published_at":{"type":"string","format":"date-time","nullable":true,"description":"When the publications go live. `null` means immediately."},"unpublished_at":{"type":"string","format":"date-time","nullable":true,"description":"When the publications come down. `null` means never."}}}}}}}},"/api/v3/admin/channels/{id}/remove_products":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Unpublish products from a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Unpublishes the listed products from this channel.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products unpublished","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["product_ids"],"properties":{"product_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/channels/{channel_id}/order_routing_rules":{"parameters":[{"name":"channel_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List order routing rules for a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the channel's routing rules in priority order. The rules engine walks them top-down; see the Order Routing guide.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"rules found","content":{"application/json":{}}}}},"post":{"summary":"Create an order routing rule on a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a rule to the channel's routing list. The `type` is the wire shorthand from `GET /order_routing_rules/types` (e.g. `preferred_location`). Omitting `position` appends the rule at the end of the list. Each rule kind can appear at most once per channel — a duplicate `type` is rejected with a validation error.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"rule created","content":{"application/json":{}}},"422":{"description":"unknown rule type","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"active":{"type":"boolean"},"position":{"type":"integer"},"preferences":{"type":"object","additionalProperties":true}},"required":["type"]}}}}}},"/api/v3/admin/channels/{channel_id}/order_routing_rules/{id}":{"parameters":[{"name":"channel_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Update an order routing rule","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a rule's `active` flag, `position` (the list reorders around it), or `preferences`. The rule kind cannot be changed — delete and re-create instead.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"rule updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"active":{"type":"boolean"},"position":{"type":"integer"},"preferences":{"type":"object","additionalProperties":true}}}}}}},"delete":{"summary":"Delete an order routing rule","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"rule deleted"}}}},"/api/v3/admin/order_routing_rules/types":{"get":{"summary":"List available order routing rule types","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Enumerates the registered rule kinds with their labels, descriptions and preference schemas — drives the \"Add rule\" picker in the admin dashboard. Plugins extend the list by registering `Spree::OrderRoutingRule` subclasses via `Spree.order_routing.rules`.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"types found","content":{"application/json":{}}}}}},"/api/v3/admin/custom_field_definitions":{"get":{"summary":"List custom field definitions","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all defined custom fields. Filter by `?q[resource_type_eq]=Spree::Product` to narrow to one parent type.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand. Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., key,label,field_type). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"definitions returned","content":{"application/json":{}}}}},"post":{"summary":"Create a custom field definition","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"definition created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["key","field_type","resource_type"],"properties":{"namespace":{"type":"string","description":"Defaults to `custom`"},"key":{"type":"string"},"label":{"type":"string","description":"Human-readable name; defaults to titleized `key`"},"field_type":{"type":"string","description":"Custom field type identifier (one of the registered field-type class names)."},"resource_type":{"type":"string","description":"Owner class, e.g. `Spree::Product`"},"storefront_visible":{"type":"boolean","description":"When false, the definition is admin-only and never exposed in the Store API"},"searchable":{"type":"boolean","description":"When true, values are included in storefront product text search"},"sortable":{"type":"boolean","description":"When true, storefront product listings can sort by this field"}}}}}}}},"/api/v3/admin/custom_field_definitions/{id}":{"get":{"summary":"Show a custom field definition","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand. Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., key,label,field_type). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"definition found","content":{"application/json":{}}}}},"patch":{"summary":"Update a custom field definition","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"definition updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string"},"storefront_visible":{"type":"boolean"},"searchable":{"type":"boolean"},"sortable":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a custom field definition","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes the definition and cascades to all custom field values referencing it.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"definition deleted"}}}},"/api/v3/admin/customer_groups":{"get":{"summary":"List customer groups","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the customer groups configured for the current store. Groups\nsegment customers for targeted promotions (see the `customer_group`\npromotion rule) and reporting. The list endpoint never embeds the\nmember list — fetch a single group with `?expand=customers` if you\nneed them inline, or query `/admin/customers?customer_group_id_in=…`\nfor paginated membership.\n\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"customer groups found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CustomerGroup"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a customer group","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a customer group in the current store. `customer_ids` is\noptional; when present, customers are attached at create time.\nPass prefixed IDs (e.g. `cus_…`) — the server decodes them\nautomatically.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"customer group created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerGroup"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"customer_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/customer_groups/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Customer group prefixed ID","schema":{"type":"string"}}],"get":{"summary":"Get a customer group","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single customer group. Pass `?expand=customers` to embed\nthe full member list inline (recommended only for single-record\nreads — embed cost scales with membership size).\n\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed. Supported: `customers`.","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"customer group with embedded customers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerGroup"}}}},"404":{"description":"customer group not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a customer group","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates name, description, or membership. `customer_ids` is a\nfull-set replacement — the server reconciles the membership to\nmatch the array, adding new IDs and removing ones not present.\nSend `customer_ids: []` to clear all members.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customer group updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerGroup"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"customer_ids":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a customer group","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the group. Member users are not deleted; their `customer_group_users` rows are dropped.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"customer group deleted"}}}},"/api/v3/admin/customers/{id}/export":{"get":{"summary":"Export a customer's personal data","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns everything the store holds about this customer, for answering a\nGDPR right-of-access request (Art. 15) that reached the merchant\ndirectly.\n\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customer data","content":{"application/json":{"schema":{"type":"object","properties":{"account":{"type":"object"},"marketing_consent":{"type":"object"},"consent_records":{"type":"array","items":{"type":"object"}},"addresses":{"type":"array","items":{"type":"object"}},"orders":{"type":"array","items":{"type":"object"}},"exported_at":{"type":"string"}}}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/customers/{id}/anonymize":{"post":{"summary":"Erase a customer's personal data","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Carries out a GDPR right-to-erasure request (Art. 17). Personal data is\nreplaced across the account, its addresses, the address snapshots on\npast orders, saved cards, connected identities and live sessions.\n\nOrders, payments and tax records are kept — they carry their own\nretention obligation — with the personal details removed. The country,\nstate and a truncated postal code survive on order addresses so the tax\njurisdiction of a past sale stays provable.\n\nIrreversible.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customer anonymized","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"anonymized":{"type":"boolean"},"anonymized_at":{"type":"string","nullable":true}}}}}}}}},"/api/v3/admin/customers/{customer_id}/addresses":{"get":{"summary":"List customer addresses","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the customer's saved addresses.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., country, state). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., first_name,last_name,address1,city). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"addresses found","content":{"application/json":{}}}}},"post":{"summary":"Create a customer address","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a new address to the customer's address book. Pass `is_default_billing: true` or `is_default_shipping: true` to set as the default — the previous default loses its flag in the same transaction.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"address created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"country_code":{"type":"string","description":"ISO-2 country code (e.g. US)"},"state_code":{"type":"string","description":"State/province abbreviation (e.g. NY)"},"phone":{"type":"string"},"company":{"type":"string"},"label":{"type":"string"},"is_default_billing":{"type":"boolean"},"is_default_shipping":{"type":"boolean"}}}}}}}},"/api/v3/admin/customers/{customer_id}/addresses/{id}":{"patch":{"summary":"Update a customer address","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a customer address.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"address updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"city":{"type":"string"},"is_default_billing":{"type":"boolean"},"is_default_shipping":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a customer address","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes the address. If it was a default, the customer loses that default (no auto-promotion).\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"address deleted"}}}},"/api/v3/admin/customers/{customer_id}/credit_cards":{"get":{"summary":"List customer credit cards","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the customer's saved credit cards. Useful for off-session admin charges via `POST /admin/orders/:id/payments { source_id }`.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., payment_method). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., brand,last4,month,year). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"credit cards found","content":{"application/json":{}}}}}},"/api/v3/admin/customers/{customer_id}/credit_cards/{id}":{"get":{"summary":"Show a customer credit card","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a saved credit card by ID.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., payment_method). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., brand,last4,month,year). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"credit card found","content":{"application/json":{}}}}},"delete":{"summary":"Delete a customer credit card","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a saved credit card.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"credit card deleted"}}}},"/api/v3/admin/customers/{customer_id}/store_credits":{"get":{"summary":"List customer store credits","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns store credits issued to the customer.\n\n**Required scope:** `read_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., store, created_by). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., amount,amount_used,memo,currency). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"store credits found","content":{"application/json":{}}}}},"post":{"summary":"Issue a store credit to a customer","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"`created_by` is set automatically from the authenticated admin.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"store credit created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"string"},"currency":{"type":"string"},"memo":{"type":"string"}}}}}}}},"/api/v3/admin/customers/{customer_id}/store_credits/{id}":{"patch":{"summary":"Update a store credit","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Update memo / amount. The amount can only be changed if `amount_used == 0`.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"store credit updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string"},"memo":{"type":"string"}}}}}}},"delete":{"summary":"Delete a store credit","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes an unused store credit (amount_used == 0). Returns 422 otherwise.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"store credit deleted"}}}},"/api/v3/admin/customers":{"get":{"summary":"List customers","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of customers. Supports Ransack search/filters.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"q[search]","in":"query","required":false,"description":"Email + name full-text-ish search","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., addresses, store_credits). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., email,first_name,last_name). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"customers found","content":{"application/json":{}}}}},"post":{"summary":"Create a customer","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a customer. No welcome email is sent automatically.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"customer created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"phone":{"type":"string"},"accepts_email_marketing":{"type":"boolean"},"internal_note":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object"}}}}}}}},"/api/v3/admin/customers/{id}":{"get":{"summary":"Show a customer","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns full customer details including computed order stats (orders_count, total_spent, last_order_completed_at).\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Customer ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations: addresses, orders, store_credits, default_billing_address, default_shipping_address","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., email,first_name,last_name). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"customer found","content":{"application/json":{}}}}},"patch":{"summary":"Update a customer","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates customer attributes. `tags` replaces the full set.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customer updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"phone":{"type":"string"},"accepts_email_marketing":{"type":"boolean"},"internal_note":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object"}}}}}}},"delete":{"summary":"Delete a customer","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a customer. Returns 422 if the customer has any orders.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"customer deleted"}}}},"/api/v3/admin/customers/bulk_add_to_groups":{"post":{"summary":"Bulk-add customers to groups","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Attaches each customer in `ids` to every group in `customer_group_ids`.\nIdempotent — customers already in a group are skipped server-side.\nGroups from sibling stores are silently ignored. Returns counts of\ncustomers and groups that were processed (post store-scoping).\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customers added to groups","content":{"application/json":{"schema":{"type":"object","properties":{"customer_count":{"type":"integer"},"customer_group_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","customer_group_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"customer_group_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/customers/bulk_remove_from_groups":{"post":{"summary":"Bulk-remove customers from groups","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Detaches each customer in `ids` from every group in `customer_group_ids`.\nNo-op for non-members. Groups from sibling stores are silently ignored.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customers removed from groups","content":{"application/json":{"schema":{"type":"object","properties":{"customer_count":{"type":"integer"},"customer_group_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","customer_group_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"customer_group_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/customers/bulk_add_tags":{"post":{"summary":"Bulk-add tags to customers","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds each tag name in `tags` to every customer in `ids`. Tags are\nupserted by name; re-adding an existing tag is a no-op.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"tags added","content":{"application/json":{"schema":{"type":"object","properties":{"customer_count":{"type":"integer"},"tag_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","tags"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/customers/bulk_remove_tags":{"post":{"summary":"Bulk-remove tags from customers","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes each tag name in `tags` from every customer in `ids`. No-op\nfor customers that don't carry the tag.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"tags removed","content":{"application/json":{"schema":{"type":"object","properties":{"customer_count":{"type":"integer"},"tag_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","tags"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/exports":{"get":{"summary":"List exports","tags":["Exports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns CSV exports queued or completed for the current store. Polled by the admin SPA to detect when an export finishes (`done: true`).\n\n**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"exports found","content":{"application/json":{}}}}},"post":{"summary":"Create an export","tags":["Exports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Queues a CSV export. The `type` selects the dataset; `search_params` is an\noptional Ransack query (same shape used by the `q[...]` params on list endpoints)\nthat filters which records are exported. Pass `record_selection: \"all\"` to\nclear the filter server-side and export everything in scope.\n\nGeneration is asynchronous. Poll `GET /admin/exports/{id}` until `done` is `true`,\nthen redirect the browser to `download_url` to fetch the file.\n\n\n**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"export queued","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["products","orders","customers","product_translations","gift_cards","coupon_codes","newsletter_subscribers","price_list_prices"]},"record_selection":{"type":"string","enum":["filtered","all"],"description":"Set to \"all\" to ignore search_params and export everything in scope."},"search_params":{"type":"object","description":"Ransack query hash. Same predicates accepted by the list endpoint. A `price_list_prices` export requires `price_list_id_eq` naming a price list of the current store, and refuses `record_selection: \"all\"`.","additionalProperties":true},"results_url":{"type":"string","description":"Absolute URL of your admin exports view; the export-done email uses it as the download button target. Only honored when it matches one of the store's configured allowed origins."}}}}}}}},"/api/v3/admin/exports/{id}":{"get":{"summary":"Show an export","tags":["Exports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns export status. While `done` is `false`, the SPA continues polling.\n\n**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"export found","content":{"application/json":{}}}}},"delete":{"summary":"Delete an export","tags":["Exports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes the export and purges its attachment.\n\n**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"export deleted"}}}},"/api/v3/admin/exports/{id}/download":{"get":{"summary":"Download an export","tags":["Exports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Streams the exported CSV with `Content-Disposition: attachment`. Returns 422 with `code: export_not_ready` while `done` is still `false`. The endpoint is JWT/API-key protected, so SPA clients must fetch it (with `Authorization` header) and trigger the browser download via a Blob URL — a top-level navigation cannot carry the JWT.\n\n**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"CSV file","content":{"application/json":{},"text/csv":{"schema":{"type":"string","format":"binary"}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments":{"get":{"summary":"List fulfillments","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all shipments for an order.\n\n**Required scope:** `read_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., inventory_units, stock_location, shipping_rates). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., number,status,tracking,cost). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillments found","content":{"application/json":{}}}}},"post":{"summary":"Create a fulfillment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Manually creates a fulfillment on a completed order, bypassing order routing — for example to mirror a shipment handled by an external carrier or 3PL. Moves the requested line item quantities out of their current fulfillments; when `items` is omitted, every not-yet-shipped unit is moved. Pass `status: 'shipped'` to register an already-shipped fulfillment (fires shipped webhooks and freezes cost/carrier). When `delivery_method_id` is omitted, the fulfillment inherits the delivery method and cost of the source fulfillment(s) it fully drains — keeping the order total unchanged; partially drained splits get no carrier when shipped, and pending fulfillments are otherwise (re)priced by the standard rate engine, which selects the lowest-cost available rate. Pass `cost` to set an explicit shipping cost instead (e.g. the 3PL price) — note this changes the order total and payment state, and is guaranteed to persist only with `status: 'shipped'` (pending fulfillments are re-priced by the rate engine).\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"fulfillment created","content":{"application/json":{}}},"422":{"description":"order not completed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["stock_location_id"],"properties":{"stock_location_id":{"type":"string","description":"Stock location the fulfillment ships from"},"tracking":{"type":"string","description":"Carrier tracking number, or a full https:// tracking link — a full URL is served back as tracking_url unchanged instead of being templated into the delivery method tracking URL"},"delivery_method_id":{"type":"string","description":"Delivery method (carrier) to attach as the selected rate. Defaults to the delivery method of the fully drained source fulfillment(s)"},"cost":{"type":"string","description":"Explicit shipping cost. Defaults to the summed cost of the fully drained source fulfillment(s), which keeps the order total unchanged; an explicit cost changes the order total and payment state. Guaranteed to persist only with status: 'shipped' — pending fulfillments are re-priced by the rate engine"},"status":{"type":"string","enum":["shipped"],"description":"Pass 'shipped' to register the fulfillment as already shipped"},"items":{"type":"array","description":"Line item quantities to fulfill. Omit to fulfill every not-yet-shipped unit.","items":{"type":"object","required":["item_id","quantity"],"properties":{"item_id":{"type":"string","description":"Line item ID"},"quantity":{"type":"integer"}}}},"metadata":{"type":"object","additionalProperties":true}}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}":{"get":{"summary":"Show a shipment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns details of a specific shipment.\n\n**Required scope:** `read_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., inventory_units, stock_location, shipping_rates). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., number,status,tracking,cost). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"shipment found","content":{"application/json":{}}}}},"patch":{"summary":"Update a shipment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a fulfillment (tracking, delivery rate).\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"shipment updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tracking":{"type":"string","description":"Carrier tracking number, or a full https:// tracking link served back as tracking_url unchanged"},"selected_delivery_rate_id":{"type":"string","description":"Delivery rate ID (dr_...) to select"}}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/fulfill":{"patch":{"summary":"Fulfill a fulfillment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Marks a fulfillment as fulfilled.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillment fulfilled","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/mark_delivered":{"patch":{"summary":"Mark a fulfillment delivered","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Records that the customer received the goods. Only a fulfilled shipment can be marked delivered.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillment delivered","content":{"application/json":{}}},"422":{"description":"fulfillment has not shipped","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"delivered_at":{"type":"string","format":"date-time","description":"When the goods arrived. Defaults to now."},"notify_customer":{"type":"boolean","description":"Whether the customer gets a delivery notification. Defaults to true."}}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/cancel":{"patch":{"summary":"Cancel a fulfillment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Cancels a fulfillment.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillment canceled","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/split":{"patch":{"summary":"Split a fulfillment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Transfers items from this shipment to a new shipment at a different stock location.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillment split","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["variant_id","quantity"],"properties":{"variant_id":{"type":"string","description":"Variant ID"},"quantity":{"type":"integer"},"stock_location_id":{"type":"string","description":"Target stock location ID"}}}}}}}},"/api/v3/admin/gift_card_batches":{"get":{"summary":"List gift card batches","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the gift card batches issued by the current store. Each batch\ngroups the cards generated together for a campaign or bulk-issuance\n— the cards themselves live under `/admin/gift_cards` and reference\nthe batch via `gift_card_batch_id`.\n\n\n**Required scope:** `read_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Records per page","schema":{"type":"integer"}},{"name":"q[prefix_cont]","in":"query","required":false,"description":"Filter by prefix (contains)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending.","schema":{"type":"string"}}],"responses":{"200":{"description":"gift card batches found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/GiftCardBatch"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a gift card batch","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Issues a batch of gift cards in a single call. The server generates\n`codes_count` cards inline for small batches (configurable via\n`Spree.config.gift_card_batch_web_limit`, default 500) or enqueues\na background job for larger ones. Each card's code is the batch\n`prefix` followed by random hex.\n\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"gift card batch created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCardBatch"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["prefix","amount","codes_count"],"properties":{"prefix":{"type":"string","description":"Lowercased and prepended to every generated code."},"amount":{"type":"string","description":"Decimal amount per card, greater than zero."},"currency":{"type":"string","description":"ISO 4217 currency code. Defaults to the store currency."},"codes_count":{"type":"integer","description":"Number of cards to generate. Capped at `gift_card_batch_limit`."},"expires_at":{"type":"string","nullable":true}}}}}}}},"/api/v3/admin/gift_card_batches/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Gift card batch prefixed ID","schema":{"type":"string"}}],"get":{"summary":"Get a gift card batch","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single batch.\n\n**Required scope:** `read_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"gift card batch found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCardBatch"}}}},"404":{"description":"gift card batch not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/gift_cards":{"get":{"summary":"List gift cards","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the gift cards issued by the current store. Filter by\n`q[code_cont]` for code search, `q[customer_id_eq]` for cards issued\nto a specific customer, or `q[status_eq]` for status filtering.\n\n\n**Required scope:** `read_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[code_cont]","in":"query","required":false,"description":"Filter by gift card code (contains)","schema":{"type":"string"}},{"name":"q[status_eq]","in":"query","required":false,"description":"Filter by status (active, redeemed, partially_redeemed, canceled)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"gift cards found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/GiftCard"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a gift card","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Issues a gift card scoped to the current store. The code is\nauto-generated when omitted. `currency` defaults to the store's\nconfigured currency. Pass `customer_id` (prefixed ID) to attach the\ncard to a specific customer.\n\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"gift card created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCard"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["amount"],"properties":{"amount":{"type":"string","description":"Decimal amount, greater than zero."},"currency":{"type":"string","description":"ISO 4217 currency code. Defaults to the store currency."},"code":{"type":"string","description":"Optional caller-supplied code. Auto-generated when omitted."},"expires_at":{"type":"string","description":"ISO 8601 date.","nullable":true},"customer_id":{"type":"string","description":"Optional customer prefixed ID.","nullable":true}}}}}}}},"/api/v3/admin/gift_cards/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Gift card prefixed ID","schema":{"type":"string"}}],"get":{"summary":"Get a gift card","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single gift card.\n\n**Required scope:** `read_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"gift card found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCard"}}}},"404":{"description":"gift card not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a gift card","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an active gift card's editable attributes. Redeemed or\npartially-redeemed cards cannot be edited.\n\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"gift card updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCard"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string"},"expires_at":{"type":"string","nullable":true},"customer_id":{"type":"string","nullable":true}}}}}}},"delete":{"summary":"Delete a gift card","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes an unused gift card. Cards that have been redeemed or\npartially redeemed cannot be deleted and return 422.\n\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"gift card deleted"},"422":{"description":"redeemed gift card cannot be deleted","content":{"application/json":{}}}}}},"/api/v3/admin/imports":{"get":{"summary":"List imports","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns CSV imports queued or completed for the current store.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"imports found","content":{"application/json":{}}}}},"post":{"summary":"Create an import","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Queues a CSV import. Upload the file first via `POST /api/v3/admin/direct_uploads`\nand pass the returned `signed_id` as `attachment`. On success the import is in the\n`mapping` state and the response carries the mapping payload: `schema_fields`\n(the canonical columns for the type), `csv_headers`, a `sample_row`, and the\nauto-assigned `mappings`.\n\nAdjust mappings if needed, then call `PATCH /admin/imports/{id}/complete_mapping`\nto start processing. Poll `GET /admin/imports/{id}` while `status` is\n`completed_mapping`/`processing`; terminal statuses are `completed` and `failed`.\n\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"import created in mapping state","content":{"application/json":{}}},"422":{"description":"unknown import type","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["type","attachment"],"properties":{"type":{"type":"string","enum":["products","customers","product_translations","price_list_prices"]},"price_list_id":{"type":"string","description":"For `price_list_prices` imports: the price list the rows are merged into. Must belong to the current store."},"attachment":{"type":"string","description":"ActiveStorage signed blob id from POST /api/v3/admin/direct_uploads."},"preferred_delimiter":{"type":"string","enum":[",",";","|","\t"],"description":"CSV column separator. Defaults to a comma."},"results_url":{"type":"string","description":"Absolute URL of your admin imports view; the import-done email links back to it with `?import=<id>` appended. Only honored when it matches one of the store's configured allowed origins."}}}}}}}},"/api/v3/admin/imports/template":{"get":{"summary":"Download an import template","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a CSV header row for the given import type, including the custom field columns available for the model.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"type","in":"query","required":true,"description":"Registered import type, e.g. products.","schema":{"type":"string"}}],"responses":{"200":{"description":"CSV template","content":{"application/json":{},"text/csv":{"schema":{"type":"string","format":"binary"}}}}}}},"/api/v3/admin/imports/example":{"get":{"summary":"Download an example import file","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Redirects to a populated example CSV for the given import type — the same sample data `rake spree:load_sample_data` uses, pinned to the installed Spree version. Returns 404 for a type that ships no example file.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"type","in":"query","required":true,"description":"Registered import type, e.g. products.","schema":{"type":"string"}}],"responses":{"302":{"description":"Redirect to the example CSV"}}}},"/api/v3/admin/imports/{id}":{"get":{"summary":"Show an import","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns import status and row counters. The admin dashboard polls this endpoint while `status` is `completed_mapping` or `processing`; `rows_count`, `completed_rows_count` and `failed_rows_count` drive the progress bar. The mapping payload (`csv_headers`, `sample_row`) is only present while `status` is `mapping`.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"import found","content":{"application/json":{}}}}},"delete":{"summary":"Delete an import","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes the import, its rows and the uploaded file. Returns 422 while the import is being processed.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"import deleted"}}}},"/api/v3/admin/imports/{id}/download":{"get":{"summary":"Download the originally uploaded file","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Streams the CSV exactly as it was uploaded — the audit trail for what was imported. JWT/API-key protected; SPA clients fetch it with the Authorization header and trigger the browser download via a Blob URL.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"CSV file","content":{"application/json":{},"text/csv":{"schema":{"type":"string","format":"binary"}}}}}}},"/api/v3/admin/imports/{id}/complete_mapping":{"patch":{"summary":"Complete mapping and start processing","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Applies the submitted column mappings, then starts row processing. Omit `mappings`\nto accept the auto-assigned ones from the create response. Returns 422 when a\nrequired schema field is left unmapped (`details.missing_required_fields`) or a\nfile column is assigned twice.\n\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"mapping completed, processing queued","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"mappings":{"type":"array","description":"Column assignments to apply before starting. `file_column: null` unmaps a field.","items":{"type":"object","required":["schema_field"],"properties":{"schema_field":{"type":"string"},"file_column":{"type":"string","nullable":true}}}}}}}}}}},"/api/v3/admin/imports/{id}/retry_failed_rows":{"patch":{"summary":"Retry failed rows","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Re-processes the rows that failed. The import re-enters `processing`; poll `GET /admin/imports/{id}` until it completes again. Returns 422 when the import is not `completed` or has no failed rows.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"retry queued","content":{"application/json":{}}}}}},"/api/v3/admin/imports/{import_id}/rows":{"get":{"summary":"List import rows","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Paginated rows of an import — the failure report. Filter with `q[status_eq]=failed` to list only rows that could not be imported; each row carries the raw CSV `data` and its `validation_errors`.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"import_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"q[status_eq]","in":"query","required":false,"description":"Filter rows by status: pending, processing, completed, failed.","schema":{"type":"string"}}],"responses":{"200":{"description":"rows found","content":{"application/json":{}}}}}},"/api/v3/admin/markets":{"get":{"summary":"List markets","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the markets configured for the current store. Markets are\nstore-scoped and ordered by `position` (an `acts_as_list` column —\nupdate the order via `PATCH /markets/{id}` with `position`).\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed. Supported: `countries`.","schema":{"type":"string"}}],"responses":{"200":{"description":"markets found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Market"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a market","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new market for the current store.\n\n- `country_codes` accepts 2-letter ISO country codes (e.g. `[\"DE\", \"FR\"]`);\n the market must contain at least one country. Unknown codes are\n silently dropped.\n- `supported_locales` accepts an array of locale codes; the\n `default_locale` is always implicitly included.\n- Setting `default: true` automatically demotes the previous default\n market in the store.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"market created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Market"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"currency":{"type":"string","description":"ISO 4217 currency code."},"default_locale":{"type":"string","description":"IETF locale tag used as the market default."},"supported_locales":{"type":"array","items":{"type":"string"},"description":"Locale codes available in this market. The default is always implicitly included."},"tax_inclusive":{"type":"boolean","default":false,"description":"Display prices with tax included."},"default":{"type":"boolean","default":false,"description":"Setting to true demotes the previous default."},"position":{"type":"integer","description":"Sort order within the store; lower = first."},"country_codes":{"type":"array","items":{"type":"string"},"description":"2-letter ISO country codes assigned to this market. At least one is required."}},"required":["name","currency","default_locale","country_codes"]}}}}}},"/api/v3/admin/markets/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a market","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"market found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Market"}}}},"404":{"description":"market not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a market","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an existing market. Pass `country_codes` to replace the\nmarket's country list (full-set update), `supported_locales` to\nreplace the supported locales, or `position` to reorder the market\nwithin the store.\n\nSetting `default: true` automatically demotes the previous default.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"market updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Market"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"currency":{"type":"string"},"default_locale":{"type":"string"},"supported_locales":{"type":"array","items":{"type":"string"}},"tax_inclusive":{"type":"boolean"},"default":{"type":"boolean"},"position":{"type":"integer"},"country_codes":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a market","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the market (sets `deleted_at`). The default market and\nthe last remaining market in a store cannot be deleted — both return\n422 with a `validation_error`.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"market deleted"},"422":{"description":"cannot delete default or last market","content":{"application/json":{}}}}}},"/api/v3/admin/option_types":{"get":{"summary":"List option types","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of option types.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., option_values). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,label,position). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"option types found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OptionType"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create an option type","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new option type. Supports nested option values.\n\nOption values can be provided inline and will be created or updated by name.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"option type created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptionType"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"integer"},"filterable":{"type":"boolean"},"option_values":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"integer"}}}}},"required":["name","label"]}}}}}},"/api/v3/admin/option_types/{id}":{"get":{"summary":"Get an option type","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single option type by ID, including its option values.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Option type ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., option_values). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,label,position). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"option type found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptionType"}}}},"404":{"description":"option type not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update an option type","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an option type. Supports updating nested option values.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Option type ID","schema":{"type":"string"}}],"responses":{"200":{"description":"option type updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptionType"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"integer"},"filterable":{"type":"boolean"},"option_values":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Existing option value ID to update"},"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"integer"}}}}}}}}}},"delete":{"summary":"Delete an option type","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes an option type.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Option type ID","schema":{"type":"string"}}],"responses":{"204":{"description":"option type deleted"}}}},"/api/v3/admin/orders/{order_id}/tax_lines":{"get":{"summary":"List tax lines","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Typed tax rows on the order. Read-only — written exclusively by the tax provider.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order prefixed ID","schema":{"type":"string"}}],"responses":{"200":{"description":"tax lines found","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/discounts":{"get":{"summary":"List discounts","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Typed discount rows (promotion-sourced and manual) on the order.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order prefixed ID","schema":{"type":"string"}}],"responses":{"200":{"description":"discounts found","content":{"application/json":{}}}}},"post":{"summary":"Create manual discount","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a manual discount. With line_item_id a single row is created; without it the amount is distributed across line items (largest remainder). This is the sanctioned post-placement discount path and works on completed orders.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order prefixed ID","schema":{"type":"string"}}],"responses":{"201":{"description":"discount created","content":{"application/json":{}}},"422":{"description":"invalid discount","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string"},"value":{"type":"number"},"value_type":{"type":"string","enum":["flat","percent"]},"line_item_id":{"type":"string","nullable":true,"description":"Target line item; omit to distribute order-level"}},"required":["label","value"]}}}}}},"/api/v3/admin/orders/{order_id}/fees":{"post":{"summary":"Create fee","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a fee (surcharge, handling, gift wrap, COD, payment fee). Order-level when no target is given. Works on completed orders.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order prefixed ID","schema":{"type":"string"}}],"responses":{"201":{"description":"fee created","content":{"application/json":{}}},"422":{"description":"invalid fee","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string"},"amount":{"type":"number"},"kind":{"type":"string","enum":["surcharge","handling","gift_wrap","cod","payment","duty"],"description":"Defaults to 'surcharge'"},"line_item_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true}},"required":["label","amount"]}}}}}},"/api/v3/admin/orders/{order_id}/gift_cards":{"post":{"summary":"Apply a gift card to an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Applies a gift card by code to the order. Returns the gift card.\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"gift card applied","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Gift card code"}}}}}}}},"/api/v3/admin/orders/{order_id}/gift_cards/{id}":{"delete":{"summary":"Remove a gift card from an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes the gift card from the order.\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Gift card ID","schema":{"type":"string"}}],"responses":{"204":{"description":"gift card removed"}}}},"/api/v3/admin/orders/{order_id}/items":{"get":{"summary":"List order items","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all line items for an order.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., variant, variant.product). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., quantity,price,total). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"items found","content":{"application/json":{}}}}},"post":{"summary":"Add an item","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a new line item to the order.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"item added","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["variant_id"],"properties":{"variant_id":{"type":"string","description":"Prefixed variant ID"},"quantity":{"type":"integer","default":1}}}}}}}},"/api/v3/admin/orders/{order_id}/items/{id}":{"get":{"summary":"Show an item","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns details of a specific line item.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Item ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., variant, variant.product). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., quantity,price,total). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"item found","content":{"application/json":{}}}}},"patch":{"summary":"Update an item","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an order item quantity or metadata.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Item ID","schema":{"type":"string"}}],"responses":{"200":{"description":"item updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"quantity":{"type":"integer"}}}}}}},"delete":{"summary":"Remove an item","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes an item from the order.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Item ID","schema":{"type":"string"}}],"responses":{"204":{"description":"line item removed"}}}},"/api/v3/admin/orders/{order_id}/store_credits":{"post":{"summary":"Apply customer's store credit to an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Applies the order customer's available store credit. When `amount` is omitted, applies up to the order outstanding balance.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"store credit applied","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string","description":"Optional explicit amount; defaults to order outstanding balance"}}}}}}},"delete":{"summary":"Remove store credit from an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes any applied store credit from the order.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"204":{"description":"store credit removed"}}}},"/api/v3/admin/orders":{"get":{"summary":"List orders","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of orders for the current store.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"sort","in":"query","required":false,"description":"Sort field (e.g., created_at, -created_at, completed_at)","schema":{"type":"string"}},{"name":"q[state_eq]","in":"query","required":false,"description":"Filter by state (cart, address, delivery, payment, confirm, complete, canceled)","schema":{"type":"string"}},{"name":"q[email_cont]","in":"query","required":false,"description":"Filter by email (contains)","schema":{"type":"string"}},{"name":"q[number_eq]","in":"query","required":false,"description":"Filter by order number","schema":{"type":"string"}},{"name":"q[completed_at_gt]","in":"query","required":false,"description":"Filter by completed after date","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., items, fulfillments, payments, customer, discounts, billing_address, shipping_address). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., number,total,status,completed_at). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"orders found","content":{"application/json":{}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a draft order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new draft order in one shot. Customer, items, addresses, currency,\nmarket, channel, locale, notes, metadata, and a coupon code can all be\nprovided inline.\n\nSetting `preferred_stock_location_id` pins the order's preferred fulfillment\nlocation — Order Routing's built-in `PreferredLocation` rule consumes it\nwhen picking which stock location ships each shipment.\n\nInvalid coupon codes are non-fatal — the order is created and the failure\nis reported on the service result (not in the API response body for now).\n\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"order created with preferred_stock_location_id","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"},"customer_id":{"type":"string","description":"Customer ID."},"use_customer_default_address":{"type":"boolean","description":"When true with customer_id, copies the customer's saved billing/shipping addresses onto the order."},"currency":{"type":"string"},"market_id":{"type":"string","description":"Market ID"},"channel_id":{"type":"string","description":"Channel ID. Defaults to the store primary channel when omitted."},"preferred_stock_location_id":{"type":"string","description":"Stock Location ID to prefer for fulfillment. Order Routing's built-in PreferredLocation rule reads this and ranks the location first; routing falls back to the next rule when the preferred location can't cover the cart."},"locale":{"type":"string"},"customer_note":{"type":"string","description":"Public, customer-visible note"},"internal_note":{"type":"string","description":"Staff-only note"},"metadata":{"type":"object","description":"Arbitrary key/value metadata"},"shipping_address":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"address1":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"},"phone":{"type":"string"}}},"shipping_address_id":{"type":"string","description":"Existing customer address ID"},"billing_address":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"address1":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"},"phone":{"type":"string"}}},"billing_address_id":{"type":"string","description":"Existing customer address ID"},"items":{"type":"array","items":{"type":"object","required":["variant_id","quantity"],"properties":{"variant_id":{"type":"string","description":"Variant ID"},"quantity":{"type":"integer"},"metadata":{"type":"object"}}}},"coupon_code":{"type":"string","description":"Optional. Applied non-fatally; invalid codes do not block creation."}}}}}}}},"/api/v3/admin/orders/{id}":{"get":{"summary":"Show an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns full order details including admin-only fields.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID (e.g., or_xxx)","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., items, fulfillments, payments, customer, discounts, billing_address, shipping_address). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., number,total,status,completed_at). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"order found","content":{"application/json":{}}},"404":{"description":"order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an order. Supports updating email, addresses, special instructions, and line items.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"order updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"},"customer_note":{"type":"string"},"internal_note":{"type":"string"},"channel_id":{"type":"string","description":"Channel ID"},"preferred_stock_location_id":{"type":"string","description":"Stock Location ID to prefer for fulfillment. Re-runs Order Routing's PreferredLocation rule on subsequent shipment rebuilds."},"shipping_address":{"type":"object","properties":{"firstname":{"type":"string"},"lastname":{"type":"string"},"address1":{"type":"string"},"city":{"type":"string"},"zipcode":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"},"phone":{"type":"string"}}},"billing_address":{"type":"object","properties":{"firstname":{"type":"string"},"lastname":{"type":"string"},"address1":{"type":"string"},"city":{"type":"string"},"zipcode":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"},"phone":{"type":"string"}}},"items":{"type":"array","items":{"type":"object","required":["variant_id"],"properties":{"variant_id":{"type":"string","description":"Variant ID"},"quantity":{"type":"integer"},"metadata":{"type":"object"}}}}}}}}}},"delete":{"summary":"Delete a draft order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a draft order. Completed orders cannot be deleted.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"204":{"description":"order deleted"}}}},"/api/v3/admin/orders/{id}/complete":{"patch":{"summary":"Complete an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Completes an order in the `confirm` state, marking it as placed.\n\nSet `notify_customer: true` to send the order confirmation email.\n\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"order completed","content":{"application/json":{}}},"422":{"description":"order cannot be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"notify_customer":{"type":"boolean","description":"Send the order confirmation email after completion."}}}}}}}},"/api/v3/admin/orders/{id}/cancel":{"patch":{"summary":"Cancel an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Cancels a completed order.\n\n`cancel_reason_id` records why, from the store's own cancellation-reason\nvocabulary (`/admin/order_cancellation_reasons`), and `cancel_note` is a\nstaff-facing note; both are shown on the order afterwards.\n\nStock is always released — the goods are not going out either way — and\nevery payment is settled at the gateway, which releases an\nauthorization it never drew on and refunds a charge it cannot release.\n\n`refund_payments` and `refund_amount` govern the shared payment of a\nsplit checkout, where one payment covers several orders: they decide\nwhether this order's share comes back, and how much of it. A\n`refund_amount` on an ordinary order is refused with a 422.\n\nSet `notify_customer: true` to send the order cancellation email.\n\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"order canceled","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"cancel_reason_id":{"type":"string","description":"Why the order was canceled — the id of one of the store's cancellation reasons."},"cancel_note":{"type":"string","description":"Staff-facing note about the cancellation."},"refund_payments":{"type":"boolean","default":false,"description":"Whether this order's share of a payment shared across a split checkout is handed back."},"refund_amount":{"type":"string","description":"How much of that share to return. Defaults to all of it; refused on an order whose payment is not shared."},"notify_customer":{"type":"boolean","default":false,"description":"Send the order cancellation email after canceling."}}}}}}}},"/api/v3/admin/orders/{id}/approve":{"patch":{"summary":"Approve an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Approves an order (e.g., for fraud review).\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"order approved","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{id}/resend_confirmation":{"post":{"summary":"Resend confirmation email","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Publishes the order.completed event to trigger confirmation email delivery.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"confirmation resent","content":{"application/json":{}}}}}},"/api/v3/admin/payment_methods":{"get":{"summary":"List payment methods","tags":["Payment Methods"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the store's configured payment methods. Use `source_required: true` to know which methods need a saved source.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand. Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,type,active). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"payment methods found","content":{"application/json":{}}}}}},"/api/v3/admin/payment_methods/types":{"get":{"summary":"List available payment provider types","tags":["Payment Methods"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the registered Spree::PaymentMethod subclasses that can be used to create new payment methods. Useful for populating a \"Provider\" dropdown in admin UIs.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"provider types found","content":{"application/json":{}}}}}},"/api/v3/admin/payment_methods/{id}":{"get":{"summary":"Show a payment method","tags":["Payment Methods"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a payment method by ID.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand. Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,type,active). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"payment method found","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/payments":{"get":{"summary":"List payments","tags":["Payments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all payments for an order.\n\n**Required scope:** `read_payments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., payment_method, source). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., amount,status,number,response_code). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"payments found","content":{"application/json":{}}}}},"post":{"summary":"Create a payment","tags":["Payments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new payment for the order.\n\n**Required scope:** `write_payments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"payment created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["payment_method_id"],"properties":{"payment_method_id":{"type":"string","description":"Payment method ID"},"amount":{"type":"string"},"source_id":{"type":"string","description":"Payment source ID"}}}}}}}},"/api/v3/admin/orders/{order_id}/payments/{id}":{"get":{"summary":"Show a payment","tags":["Payments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns details of a specific payment.\n\n**Required scope:** `read_payments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Payment ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., payment_method, source). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., amount,status,number,response_code). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"payment found","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/payments/{id}/capture":{"patch":{"summary":"Capture a payment","tags":["Payments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Captures a pending payment.\n\n**Required scope:** `write_payments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Payment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"payment captured","content":{"application/json":{}}},"422":{"description":"capture failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/orders/{order_id}/payments/{id}/void":{"patch":{"summary":"Void a payment","tags":["Payments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Voids a payment.\n\n**Required scope:** `write_payments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Payment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"payment voided","content":{"application/json":{}}}}}},"/api/v3/admin/price_lists":{"get":{"summary":"List price lists","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the price lists configured for the current store.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"schema":{"type":"string"}},{"name":"q[status_eq]","in":"query","required":false,"schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed. Supported: `price_rules`.","schema":{"type":"string"}}],"responses":{"200":{"description":"price lists found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PriceList"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new draft price list.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"price list created (server-to-server — rules + prices)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceList"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"starts_at":{"type":"string","nullable":true},"ends_at":{"type":"string","nullable":true},"match_policy":{"type":"string","enum":["all","any"]},"position":{"type":"integer"},"rules":{"type":"array","description":"STI-typed price rules to attach on create. Existing rules on the same payload via PATCH reconcile by id.","items":{"type":"object","required":["type"],"properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}}}},"prices":{"type":"array","description":"Server-to-server shape: ship the exact per-variant prices the list should contain. Each row upserts on the unique key `(variant_id, currency, price_list_id)` — `prices` alone tells the server which variants belong to the list and what the override amount is. Curating whole products goes through the nested `/price_lists/{id}/products` surface instead.","items":{"type":"object","required":["variant_id","currency"],"properties":{"variant_id":{"type":"string"},"currency":{"type":"string"},"amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true}}}}}}}}}}},"/api/v3/admin/price_lists/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"price list found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceList"}}}},"404":{"description":"price list not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a price list. The optional `rules:` array reconciles nested\nSTI-typed price rules in a single round-trip — existing rules update\nby `id`, new rules build, missing rules destroy. Mirrors the\npromotion editor's \"save the whole thing on Save\" pattern.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"price list updated with nested rules","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceList"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"starts_at":{"type":"string","nullable":true},"ends_at":{"type":"string","nullable":true},"match_policy":{"type":"string","enum":["all","any"]},"position":{"type":"integer"},"rules":{"type":"array","items":{"type":"object","required":["type"],"properties":{"id":{"type":"string","nullable":true},"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}}}},"prices":{"type":"array","description":"Individual price overrides (the spreadsheet payload). Each row updates by `id` if shipped, otherwise upserts on the unique key `(variant_id, currency, price_list_id)`.","items":{"type":"object","oneOf":[{"required":["id"]},{"required":["variant_id","currency"]}],"properties":{"id":{"type":"string"},"variant_id":{"type":"string"},"currency":{"type":"string"},"amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true}}}}}}}}}},"delete":{"summary":"Delete a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the price list. Associated prices are removed asynchronously.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"price list deleted"}}}},"/api/v3/admin/price_lists/{id}/activate":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Activate a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Transitions a draft / inactive list to `active`. If `starts_at` is\nin the future the list is marked `scheduled` instead, matching the\nlegacy admin behaviour.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"price list activated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceList"}}}}}}},"/api/v3/admin/price_lists/{id}/deactivate":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Deactivate a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"price list deactivated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceList"}}}}}}},"/api/v3/admin/prices":{"get":{"summary":"List prices","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Generic prices endpoint covering both base prices and price-list\noverrides. Filter with Ransack: `q[price_list_id_eq]=…`,\n`q[currency_eq]=USD`, `q[price_list_id_null]=true` (base prices only).\n\nThe admin spreadsheet uses this with server-side pagination so it\nscales past the metadata-PATCH path on `/price_lists/:id`.\n\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"q[price_list_id_eq]","in":"query","required":false,"schema":{"type":"string"}},{"name":"q[price_list_id_null]","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"q[currency_eq]","in":"query","required":false,"schema":{"type":"string"}},{"name":"q[variant_id_eq]","in":"query","required":false,"schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort keys. Supports e.g. `variant_product_name,variant_id`.","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed. Supported: `variant`.","schema":{"type":"string"}}],"responses":{"200":{"description":"prices found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Price"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a price","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a single price. Omit `price_list_id` to create a base price.\nFor more than a handful of rows, prefer `POST /admin/prices/bulk_upsert`.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"price created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Price"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["variant_id","currency"],"properties":{"variant_id":{"type":"string"},"currency":{"type":"string"},"amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true},"price_list_id":{"type":"string","nullable":true}}}}}}}},"/api/v3/admin/prices/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a price","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"price found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Price"}}}},"404":{"description":"price not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a price","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"price updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Price"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true}}}}}}},"delete":{"summary":"Delete a price","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the price (acts_as_paranoid).\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"price deleted"}}}},"/api/v3/admin/prices/bulk_upsert":{"post":{"summary":"Bulk-upsert prices","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Upserts a batch of prices in a single SQL round trip.\n\nEach row either:\n* targets an existing price by `id`, OR\n* matches on the unique key `(variant_id, currency, price_list_id)` —\n updating the existing row if one exists, creating one otherwise.\n\nModel callbacks (e.g. PriceHistory) are bypassed; this is a\nbulk-write fast path for the admin spreadsheet. The response\ncarries `price_count` — the number of rows touched.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"prices upserted","content":{"application/json":{"schema":{"type":"object","properties":{"price_count":{"type":"integer"}}}}}},"422":{"description":"missing prices key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["prices"],"properties":{"prices":{"type":"array","items":{"type":"object","required":["variant_id","currency"],"properties":{"id":{"type":"string","nullable":true},"variant_id":{"type":"string"},"currency":{"type":"string"},"price_list_id":{"type":"string","nullable":true},"amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true}}}}}}}}}}},"/api/v3/admin/prices/bulk_destroy":{"delete":{"summary":"Bulk-delete prices","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes each price in `ids`. Returns the count actually destroyed.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"prices deleted","content":{"application/json":{"schema":{"type":"object","properties":{"price_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/{product_id}/custom_fields":{"get":{"summary":"List product custom fields","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the product's custom field values.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., custom_field_definition). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., key,value,namespace). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"custom fields found","content":{"application/json":{}}}}},"post":{"summary":"Create a product custom field","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Sets a custom field value on the product. Requires an existing CustomFieldDefinition; pass its prefixed `cfdef_…` id.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"custom field created","content":{"application/json":{}}},"422":{"description":"duplicate definition for the same product","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["custom_field_definition_id","value"],"properties":{"custom_field_definition_id":{"type":"string","description":"Prefixed `cfdef_…` id"},"value":{"description":"Value matching the definition's `field_type`"}}}}}}}},"/api/v3/admin/products/{product_id}/custom_fields/{id}":{"get":{"summary":"Show a product custom field","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., custom_field_definition). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., key,value,namespace). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"custom field found","content":{"application/json":{}}}}},"patch":{"summary":"Update a product custom field","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates the custom field's `value`. The linked definition cannot be changed — delete and recreate to switch.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"custom field updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["value"],"properties":{"value":{"description":"New value"}}}}}}},"delete":{"summary":"Delete a product custom field","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"custom field deleted"}}}},"/api/v3/admin/products/{product_id}/translations":{"get":{"summary":"List product translations","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the full translation matrix for the product: the source value and content type per translatable field, plus the translated value for every supported locale.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"translations found","content":{"application/json":{}}}}}},"/api/v3/admin/products":{"get":{"summary":"List products","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of products for the current store.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"sort","in":"query","required":false,"description":"Sort field (e.g., name, -name, price, -price, best_selling)","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., variants, media, option_types, categories). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,slug,price,status). id is always included.","schema":{"type":"string"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[status_eq]","in":"query","required":false,"description":"Filter by status","schema":{"type":"string"}}],"responses":{"200":{"description":"products found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a product","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new product. Supports nested variants with prices and option types.\n\nOption types and values are auto-created if they don't exist.\nPrices are upserted by currency. Stock items are upserted by stock location.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"product created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"slug":{"type":"string"},"status":{"type":"string","enum":["draft","active","archived"]},"tax_category_id":{"type":"string","description":"Tax category ID"},"category_ids":{"type":"array","items":{"type":"string"},"description":"Array of category IDs"},"tags":{"type":"array","items":{"type":"string"}},"prices":{"type":"array","description":"Shorthand for a simple (no-options) product: per-currency prices that forward to the product's sole variant. For products with options, set prices per variant under `variants:` instead.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"variants":{"type":"array","description":"Array of variant payloads. Variants can declare multiple option pairs via `options:` and per-currency prices via `prices:`. Stock counts go in `stock_levels:` (per stock location).","items":{"type":"object","properties":{"sku":{"type":"string"},"options":{"type":"array","description":"One pair per option type the variant participates in (e.g. size + color). Option types and values are auto-created if missing.","items":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string"},"value":{"type":"string"}}}},"prices":{"type":"array","description":"Per-currency prices. Upserted by currency.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"stock_levels":{"type":"array","description":"Per-stock-location inventory. Upserted by stock_location_id.","items":{"type":"object","required":["stock_location_id","count_on_hand"],"properties":{"stock_location_id":{"type":"string","description":"Stock location ID (e.g. sloc_xxx)"},"count_on_hand":{"type":"integer"},"backorderable":{"type":"boolean"}}}}}}}},"required":["name"]}}}}}},"/api/v3/admin/products/{id}":{"get":{"summary":"Get a product","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single product by ID.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID (e.g., prod_xxx)","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., variants, media, option_types, categories). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,slug,price,status). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"product found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"404":{"description":"product not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a product","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a product. Only provided fields are updated.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"200":{"description":"product updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"slug":{"type":"string"},"status":{"type":"string","enum":["draft","active","archived"]},"tax_category_id":{"type":"string","description":"Tax category ID"},"category_ids":{"type":"array","items":{"type":"string"},"description":"Array of category IDs"},"tags":{"type":"array","items":{"type":"string"}},"prices":{"type":"array","description":"Shorthand for a simple (no-options) product: per-currency prices that forward to the product's sole variant. For products with options, set prices per variant under `variants:` instead.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"variants":{"type":"array","description":"Array of variant payloads. Variants can declare multiple option pairs via `options:` and per-currency prices via `prices:`. Stock counts go in `stock_levels:` (per stock location).","items":{"type":"object","properties":{"sku":{"type":"string"},"options":{"type":"array","description":"One pair per option type the variant participates in (e.g. size + color). Option types and values are auto-created if missing.","items":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string"},"value":{"type":"string"}}}},"prices":{"type":"array","description":"Per-currency prices. Upserted by currency.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"stock_levels":{"type":"array","description":"Per-stock-location inventory. Upserted by stock_location_id.","items":{"type":"object","required":["stock_location_id","count_on_hand"],"properties":{"stock_location_id":{"type":"string","description":"Stock location ID (e.g. sloc_xxx)"},"count_on_hand":{"type":"integer"},"backorderable":{"type":"boolean"}}}}}}}}}}}}},"delete":{"summary":"Delete a product","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes a product.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"204":{"description":"product deleted"},"422":{"description":"deletion refused by a store rule","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/products/bulk_status_update":{"post":{"summary":"Bulk-update product status","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Sets `status` on each product in `ids`. Reindexes the affected products\nfor search. Cross-store IDs are silently dropped. Returns counts.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"cross-store products silently dropped","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"status":{"type":"string"}}}}}},"422":{"description":"invalid status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","status"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["draft","active","archived"]}}}}}}}},"/api/v3/admin/products/bulk_add_to_categories":{"post":{"summary":"Bulk-add products to categories","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Attaches each product in `ids` to every category (category) in `category_ids`.\nCategories from sibling stores are silently ignored.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products added to categories","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"category_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","category_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_remove_from_categories":{"post":{"summary":"Bulk-remove products from categories","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Detaches each product in `ids` from every category in `category_ids`.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products removed from categories","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","category_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_add_to_collections":{"post":{"summary":"Bulk-add products to collections","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Attaches each product in `ids` to every manual collection in `collection_ids`.\nAutomatic (rule-based) and sibling-store collections are silently ignored.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products added to collections","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"collection_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","collection_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"collection_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_remove_from_collections":{"post":{"summary":"Bulk-remove products from collections","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Detaches each product in `ids` from every collection in `collection_ids`.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products removed from collections","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","collection_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"collection_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_add_to_channels":{"post":{"summary":"Bulk-add products to channels","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Publishes each product in `ids` on every channel in `channel_ids`. Idempotent —\nre-publishing on an existing channel is a no-op. Channels from sibling stores\nare silently ignored.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products published on channels","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"channel_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","channel_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"channel_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_remove_from_channels":{"post":{"summary":"Bulk-remove products from channels","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Unpublishes each product in `ids` from every channel in `channel_ids`.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products unpublished from channels","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"channel_count":{"type":"integer"},"removed":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","channel_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"channel_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_add_tags":{"post":{"summary":"Bulk-add tags to products","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds each tag name in `tags` to every product in `ids`. Tags are upserted by name.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"tags added","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"tag_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","tags"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_remove_tags":{"post":{"summary":"Bulk-remove tags from products","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes each tag in `tags` from every product in `ids`.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"tags removed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","tags"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_destroy":{"delete":{"summary":"Bulk-delete products","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes each product in `ids`. Returns the count actually destroyed.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products deleted","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/translations":{"get":{"summary":"Translation coverage for a resource type","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Reports how much of each record is translated into each of the store's non-default locales, plus per-locale totals. A record counts as covered for a locale only when every one of its translatable fields is filled in.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"resource_type","in":"query","required":true,"description":"A translatable resource type, e.g. `product`, `category`, `option_type`.","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"search","in":"query","required":false,"description":"Free-text term, applied through whichever predicate the resource type whitelists (reported back as `search_field`).","schema":{"type":"string"}}],"responses":{"200":{"description":"coverage found","content":{"application/json":{}}},"404":{"description":"resource type is not translatable","content":{"application/json":{}}}}}},"/api/v3/admin/policies":{"get":{"summary":"List policies","tags":["Policies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the store's policy documents — terms of service, privacy\npolicy, returns policy, shipping policy, and any others the merchant\nhas written. Every store is created with the four standard policies,\nnamed but empty.\n\nA marketplace seller's own policies are managed by the seller and are\nnot listed here.\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"policies listed","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Policy"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a policy","tags":["Policies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a policy. `body` accepts HTML and is sanitized before it is\nstored; the stored markup is returned as `body_html`, and `body` reads\nback as plain text.\n\nThe slug is derived from the name when one is not given, and is what\nthe storefront addresses the policy by.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"policy created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Policy"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"},"body":{"type":"string"}},"required":["name"]}}}}}},"/api/v3/admin/policies/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Policy prefixed ID or slug","schema":{"type":"string"}}],"get":{"summary":"Get a policy","tags":["Policies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single policy, addressed by prefixed ID or by slug.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"policy found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Policy"}}}},"404":{"description":"policy not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a policy","tags":["Policies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a policy. `body` accepts HTML and is sanitized before it is stored.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"policy updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Policy"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"},"body":{"type":"string"}}}}}}},"delete":{"summary":"Delete a policy","tags":["Policies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a policy. The four policies a store is created with can be\ndeleted like any other — they are conventions, not fixtures.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"policy deleted"}}}},"/api/v3/admin/claim_reasons":{"get":{"summary":"List claim reasons","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Why a customer raised a claim — what the merchant got wrong, rather than a change of mind.\n\nThe vocabulary is the merchant's own — seeded with a starting set and\nedited from the dashboard. Inactive rows stay for the records that\nalready reference them, but are not offered on new ones.\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[active_eq]","in":"query","required":false,"description":"Filter by active flag","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"responses":{"200":{"description":"claim reasons found","content":{"application/json":{}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a claim reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a claim reason to this store. Names are unique per store, ignoring case.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"claim reason created","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"active":{"type":"boolean","description":"Inactive reasons are hidden from the pickers on new records."}}}}}}}},"/api/v3/admin/claim_reasons/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Claim reason ID","schema":{"type":"string"}}],"get":{"summary":"Get a claim reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single claim reason by prefixed ID.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"claim reason found","content":{"application/json":{}}},"404":{"description":"claim reason not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a claim reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Renames a claim reason or retires it. Deactivating keeps it on the records\nthat already carry it while removing it from the pickers.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"claim reason updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"active":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a claim reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes a claim reason the store no longer uses. A reason already recorded\non a document is refused — deactivate it instead, so the history it\nexplains stays readable.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"claim reason deleted"}}}},"/api/v3/admin/order_cancellation_reasons":{"get":{"summary":"List order cancellation reasons","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Why an order was called off before it shipped. Staff pick one when canceling.\n\nThe vocabulary is the merchant's own — seeded with a starting set and\nedited from the dashboard. Inactive rows stay for the records that\nalready reference them, but are not offered on new ones.\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[active_eq]","in":"query","required":false,"description":"Filter by active flag","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"responses":{"200":{"description":"order cancellation reasons found","content":{"application/json":{}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a order cancellation reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a order cancellation reason to this store. Names are unique per store, ignoring case.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"order cancellation reason created","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"active":{"type":"boolean","description":"Inactive reasons are hidden from the pickers on new records."}}}}}}}},"/api/v3/admin/order_cancellation_reasons/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Order cancellation reason ID","schema":{"type":"string"}}],"get":{"summary":"Get a order cancellation reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single order cancellation reason by prefixed ID.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"order cancellation reason found","content":{"application/json":{}}},"404":{"description":"order cancellation reason not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a order cancellation reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Renames a order cancellation reason or retires it. Deactivating keeps it on the records\nthat already carry it while removing it from the pickers.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"order cancellation reason updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"active":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a order cancellation reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes a order cancellation reason the store no longer uses. A reason already recorded\non a document is refused — deactivate it instead, so the history it\nexplains stays readable.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"order cancellation reason deleted"}}}},"/api/v3/admin/refund_reasons":{"get":{"summary":"List refund reasons","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Why money went back. Some rows are seeded and looked up by name, so they refuse renaming and deletion.\n\nThe vocabulary is the merchant's own — seeded with a starting set and\nedited from the dashboard. Inactive rows stay for the records that\nalready reference them, but are not offered on new ones.\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[active_eq]","in":"query","required":false,"description":"Filter by active flag","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"responses":{"200":{"description":"refund reasons found","content":{"application/json":{}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a refund reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a refund reason to this store. Names are unique per store, ignoring case.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"refund reason created","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"active":{"type":"boolean","description":"Inactive reasons are hidden from the pickers on new records."}}}}}}}},"/api/v3/admin/refund_reasons/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Refund reason ID","schema":{"type":"string"}}],"get":{"summary":"Get a refund reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single refund reason by prefixed ID.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"refund reason found","content":{"application/json":{}}},"404":{"description":"refund reason not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a refund reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Renames a refund reason or retires it. Deactivating keeps it on the records\nthat already carry it while removing it from the pickers.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"refund reason updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"active":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a refund reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes a refund reason the store no longer uses. A reason already recorded\non a document is refused — deactivate it instead, so the history it\nexplains stays readable.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"refund reason deleted"}}}},"/api/v3/admin/return_reasons":{"get":{"summary":"List return reasons","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Why a customer is sending items back. Shared by returns and exchanges.\n\nThe vocabulary is the merchant's own — seeded with a starting set and\nedited from the dashboard. Inactive rows stay for the records that\nalready reference them, but are not offered on new ones.\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[active_eq]","in":"query","required":false,"description":"Filter by active flag","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"responses":{"200":{"description":"return reasons found","content":{"application/json":{}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a return reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a return reason to this store. Names are unique per store, ignoring case.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"return reason created","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"active":{"type":"boolean","description":"Inactive reasons are hidden from the pickers on new records."}}}}}}}},"/api/v3/admin/return_reasons/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Return reason ID","schema":{"type":"string"}}],"get":{"summary":"Get a return reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single return reason by prefixed ID.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"return reason found","content":{"application/json":{}}},"404":{"description":"return reason not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a return reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Renames a return reason or retires it. Deactivating keeps it on the records\nthat already carry it while removing it from the pickers.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"return reason updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"active":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a return reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes a return reason the store no longer uses. A reason already recorded\non a document is refused — deactivate it instead, so the history it\nexplains stays readable.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"return reason deleted"}}}},"/api/v3/admin/promotions/{promotion_id}/coupon_codes":{"parameters":[{"name":"promotion_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List coupon codes for a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the auto-generated coupon codes for a multi-code promotion. Single-code promotions store the code on the promotion itself; this endpoint returns an empty list for them.\n\n**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"coupon codes found","content":{"application/json":{}}}}}},"/api/v3/admin/promotions/{promotion_id}/promotion_actions":{"parameters":[{"name":"promotion_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List actions for a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"actions found","content":{"application/json":{}}}}},"post":{"summary":"Create an action on a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a new action to a promotion. The `type` is the wire shorthand from `GET /promotion_actions/types` (e.g. `free_shipping`, `create_item_adjustments`). Fully-qualified Ruby class names are also accepted for backward compatibility.\n\n**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"action created","content":{"application/json":{}}},"422":{"description":"unknown action type","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}},"required":["type"]}}}}}},"/api/v3/admin/promotions/{promotion_id}/promotion_actions/{id}":{"parameters":[{"name":"promotion_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"delete":{"summary":"Delete an action from a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"action deleted"}}}},"/api/v3/admin/promotions/{promotion_id}/promotion_rules":{"parameters":[{"name":"promotion_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List rules for a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"rules found","content":{"application/json":{}}}}},"post":{"summary":"Create a rule on a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a new rule to a promotion. The `type` is the wire shorthand from `GET /promotion_rules/types` (e.g. `currency`, `item_total`, `product`). Fully-qualified Ruby class names are also accepted for backward compatibility.\n\n**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"rule created with preferences","content":{"application/json":{}}},"422":{"description":"unknown rule type","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}},"required":["type"]}}}}}},"/api/v3/admin/promotions/{promotion_id}/promotion_rules/{id}":{"parameters":[{"name":"promotion_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Update a rule's preferences","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"rule updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"preferences":{"type":"object","additionalProperties":true}}}}}}},"delete":{"summary":"Delete a rule from a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"rule deleted"}}}},"/api/v3/admin/promotions":{"get":{"summary":"List promotions","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the store's promotions, including manual coupon and automatic promotions.\n\n**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"promotions found","content":{"application/json":{}}}}},"post":{"summary":"Create a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new promotion. `code` is required for single-code coupon promotions;\npass `multi_codes: true` with `number_of_codes` to auto-generate a batch.\n\nRules and actions can be created in the same request by passing arrays of\n`{ type, preferences, ... }` rows. The server reconciles to the desired set:\nnew rows are built, existing rows (by `id`) are updated, omitted rows are removed.\n\n\n**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"promotion created with rules and actions","content":{"application/json":{}}},"422":{"description":"invalid params","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"code":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"starts_at":{"type":"string","format":"date-time","nullable":true},"expires_at":{"type":"string","format":"date-time","nullable":true},"usage_limit":{"type":"integer","nullable":true},"match_policy":{"type":"string","enum":["all","any"]},"kind":{"type":"string","enum":["coupon_code","automatic"]},"multi_codes":{"type":"boolean"},"number_of_codes":{"type":"integer","nullable":true},"code_prefix":{"type":"string","nullable":true},"promotion_category_id":{"type":"string","nullable":true},"rules":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true},"product_ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}},"customer_ids":{"type":"array","items":{"type":"string"}}},"required":["type"]}},"actions":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true},"calculator":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}}}},"required":["type"]}}},"required":["name"]}}}}}},"/api/v3/admin/promotions/{id}":{"get":{"summary":"Show a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"promotion found","content":{"application/json":{}}}}},"patch":{"summary":"Update a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a promotion. The `rules` and `actions` arrays are treated as\na *desired set* — rows with `id` update in place, rows without `id` are\nbuilt fresh, and any existing row not present in the array is destroyed.\nPass `rules: []` or `actions: []` to clear them.\n\n\n**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"rules and actions cleared with empty arrays","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"code":{"type":"string","nullable":true},"starts_at":{"type":"string","format":"date-time","nullable":true},"expires_at":{"type":"string","format":"date-time","nullable":true},"usage_limit":{"type":"integer","nullable":true},"match_policy":{"type":"string","enum":["all","any"]},"kind":{"type":"string","enum":["coupon_code","automatic"]},"promotion_category_id":{"type":"string","nullable":true},"rules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","nullable":true,"description":"Pass to update an existing rule; omit to build a new one"},"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true},"product_ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}},"customer_ids":{"type":"array","items":{"type":"string"}}},"required":["type"]}},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","nullable":true},"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true},"calculator":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}}}},"required":["type"]}}}}}}}},"delete":{"summary":"Delete a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"promotion deleted"}}}},"/api/v3/admin/promotion_actions/types":{"get":{"summary":"List available promotion action types","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the registered Spree::PromotionAction subclasses with their preference schemas. Used by admin UIs to populate the \"Add action\" picker and render generic preference forms.\n\n**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"action types found","content":{"application/json":{}}}}}},"/api/v3/admin/promotion_rules/types":{"get":{"summary":"List available promotion rule types","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the registered Spree::PromotionRule subclasses with their preference schemas.\n\n**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"rule types found","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/refunds":{"get":{"summary":"List refunds","tags":["Refunds"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all refunds for an order.\n\n**Required scope:** `read_refunds` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., payment, refund_reason). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., amount,reason,transaction_id). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"refunds found","content":{"application/json":{}}}}},"post":{"summary":"Create a refund","tags":["Refunds"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a refund for a payment on the order. The refund is automatically processed via the payment gateway.\n\n**Required scope:** `write_refunds` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"refund created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["payment_id","amount"],"properties":{"payment_id":{"type":"string","description":"Payment ID"},"amount":{"type":"string"},"refund_reason_id":{"type":"string","description":"Refund reason ID"}}}}}}}},"/api/v3/admin/locales":{"get":{"summary":"List supported locales","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the locales a merchant can translate content into for the current store, with the default and right-to-left flags.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"locales found","content":{"application/json":{}}}}}},"/api/v3/admin/store":{"get":{"summary":"Get the current store","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the current store configuration. The store is resolved from the request context (host or admin selection); there is no `id` parameter.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"current store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Store"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update the current store","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates the current store configuration.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"store updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Store"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"preferred_admin_locale":{"type":"string"},"preferred_timezone":{"type":"string"},"preferred_weight_unit":{"type":"string"},"preferred_unit_system":{"type":"string"}}}}}}}},"/api/v3/admin/tags":{"get":{"summary":"List tags","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns tag names for a given taggable type. Used for autocomplete in tag inputs on products, orders, and customers.","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"taggable_type","in":"query","required":true,"description":"Taggable type (`Spree::Product`, `Spree::Order`, or `Spree::User`)","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"description":"Optional case-insensitive substring filter","schema":{"type":"string"}}],"responses":{"200":{"description":"tags found","content":{"application/json":{}}},"422":{"description":"invalid taggable type","content":{"application/json":{}}}}}},"/api/v3/admin/tax_rates":{"get":{"summary":"List tax rates","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the store's tax rates. Rates are the entire configuration of\nthe built-in tax provider: each pairs a tax category with a jurisdiction\n(a country, optionally narrowed to one state) and a percentage, and\ndecides whether the tax is already included in the product price\n(VAT-style) or added on top (US-style).\n\nMarkets using an external tax provider ignore these rows — that\nprovider carries its own jurisdiction data.\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[included_in_price_true]","in":"query","required":false,"description":"Only rates included in the product price","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"responses":{"200":{"description":"tax rates found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TaxRate"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a tax rate","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a tax rate for the current store. Give either `amount` as a\ndecimal (`0.19`) or `amount_percentage` as a percentage (`19`).\n\nName the jurisdiction with `country_code` (and `state_code` for a\nstate-level rate). Omitting the country makes the rate apply everywhere.\n\nSet `included_in_price` for VAT-style pricing, where the rate is backed\nout of the displayed price rather than added to it.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"tax rate created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxRate"}}}},"422":{"description":"validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Customer-facing rate name, e.g. \"VAT\""},"amount":{"type":"string","description":"Rate as a decimal, e.g. \"0.19\""},"amount_percentage":{"type":"number","description":"Rate as a percentage, e.g. 19"},"included_in_price":{"type":"boolean"},"show_rate_in_label":{"type":"boolean"},"tax_category_id":{"type":"string"},"country_code":{"type":"string","description":"ISO code, e.g. \"DE\". Omit for every country."},"state_code":{"type":"string","description":"State abbreviation within that country, e.g. \"CA\"."}},"required":["name","tax_category_id"]}}},"required":true}}},"/api/v3/admin/tax_rates/{id}":{"parameters":[{"name":"id","in":"path","description":"Tax rate ID","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a tax rate","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"tax rate found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxRate"}}}}}},"patch":{"summary":"Update a tax rate","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"tax rate updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxRate"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"amount":{"type":"string"},"amount_percentage":{"type":"number"},"included_in_price":{"type":"boolean"},"show_rate_in_label":{"type":"boolean"},"tax_category_id":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"}}}}},"required":true}},"delete":{"summary":"Delete a tax rate","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the rate. Tax lines it already produced keep their own rate snapshot.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"tax rate deleted"}}}},"/api/v3/admin/translatable_resources":{"get":{"summary":"List translatable resources","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns every translatable resource type and its translatable fields (key + content type), so clients can render translation editors generically.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"translatable resources found","content":{"application/json":{}}}}}},"/api/v3/admin/translations/batch":{"post":{"summary":"Batch upsert translations","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Atomically upserts translations across many records of (possibly) different translatable resource types in one request — e.g. an option type and all its option values in one save. A flat list of independent registry writes; all entries succeed or none do.\n\n**Required scope:** `write_<resource>` for every resource type in the batch (for API-key authentication) (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"translations upserted","content":{"application/json":{}}},"422":{"description":"unsupported locale rolls back the whole batch","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["translations"],"properties":{"translations":{"type":"array","items":{"type":"object","required":["resource_type","resource_id","values"],"properties":{"resource_type":{"type":"string","description":"Translatable resource type token, e.g. `option_type`"},"resource_id":{"type":"string","description":"Prefixed id of the record"},"values":{"type":"object","description":"Map of locale code to { field: value }","additionalProperties":{"type":"object","additionalProperties":true}}}}}}}}}}}},"/api/v3/admin/admin_users":{"get":{"summary":"List staff","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns admin users with at least one role assignment on the current store.\n\n**Required scope:** `read_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"staff found","content":{"application/json":{}}}}}},"/api/v3/admin/admin_users/{id}":{"get":{"summary":"Show a staff member","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"staff member found","content":{"application/json":{}}}}},"patch":{"summary":"Update a staff member","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates name fields and reassigns roles for the current store. `role_ids` is a complete replacement — roles not in the array are removed for this store.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"staff member updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"role_ids":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Remove a staff member from this store","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes the user's role assignments on the current store. The account is preserved — the user keeps access to any other stores.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"staff removed from store"}}}},"/api/v3/admin/invitations":{"get":{"summary":"List invitations","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns invitations for the current store, including pending and accepted.\n\n**Required scope:** `read_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"invitations found","content":{"application/json":{}}}}},"post":{"summary":"Create an invitation","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Invites a teammate by email. The invitation is scoped to the current store and carries the chosen role; on accept, a `RoleUser` is created via the invitation's `after_accept` callback.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"invitation created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["email","role_id"],"properties":{"email":{"type":"string"},"role_id":{"type":"string"}}}}}}}},"/api/v3/admin/invitations/{id}":{"delete":{"summary":"Revoke an invitation","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"invitation revoked"}}}},"/api/v3/admin/invitations/{id}/resend":{"patch":{"summary":"Resend an invitation","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Issues a fresh token and dispatches the invitation email again.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"invitation resent","content":{"application/json":{}}}}}},"/api/v3/admin/permissions":{"get":{"summary":"List the permission catalog","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the permission catalog — the grant vocabulary shared by staff role permissions and secret API key scopes. Entries are grouped for permission pickers; labels and descriptions are localized. Readable by any authenticated admin credential.","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"catalog returned","content":{"application/json":{}}}}}},"/api/v3/admin/roles":{"get":{"summary":"List roles","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns staff roles with their catalog permissions. Roles are global, not per-store; `mutable: false` marks the protected admin role and host-locked rows.\n\n**Required scope:** `read_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"roles found","content":{"application/json":{}}}}},"post":{"summary":"Create a role","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a staff role. `permissions` holds catalog keys (see GET /admin/permissions); a caller may only grant keys they effectively hold.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"role created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"permissions":{"type":"array","items":{"type":"string"}}},"required":["name"]}}}}}},"/api/v3/admin/roles/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Update a role","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a role name, description or permissions. The admin role and host-locked roles (`mutable: false`) reject changes.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"role updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"permissions":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a role","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a role. Fails with 422 while the role is protected or still referenced by staff members or pending invitations.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"role deleted"},"422":{"description":"role cannot be deleted","content":{"application/json":{}}}}}},"/api/v3/admin/stock_locations":{"get":{"summary":"List stock locations","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the configured stock locations. Stock locations are global\n(shared across stores). Filter with Ransack predicates such as\n`q[active_eq]`, `q[kind_eq]`, `q[pickup_enabled_eq]`, or\n`q[name_cont]`.\n\nPickup-related attributes (`kind`, `pickup_enabled`,\n`pickup_stock_policy`, `pickup_ready_in_minutes`,\n`pickup_instructions`) drive merchant pickup support at checkout —\ncustomers can collect orders from any active location with\n`pickup_enabled: true`.\n\n\n**Required scope:** `read_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[active_eq]","in":"query","required":false,"description":"Filter by active status","schema":{"type":"boolean"}},{"name":"q[kind_eq]","in":"query","required":false,"description":"Filter by kind (built-in: 'warehouse', 'store', 'fulfillment_center')","schema":{"type":"string"}},{"name":"q[pickup_enabled_eq]","in":"query","required":false,"description":"Filter by pickup-enabled flag","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"stock locations found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StockLocation"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a stock location","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new stock location.\n\nSetting `default: true` automatically demotes the previous default\nlocation.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"stock location created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockLocation"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"admin_name":{"type":"string","nullable":true,"description":"Internal name shown only in the admin"},"active":{"type":"boolean"},"default":{"type":"boolean","description":"Setting to true demotes the previous default."},"kind":{"type":"string","enum":["warehouse","store","fulfillment_center"],"description":"Categorizes the location."},"propagate_all_variants":{"type":"boolean"},"backorderable_default":{"type":"boolean"},"address1":{"type":"string","nullable":true},"address2":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true,"description":"ISO-3166 alpha-2 country code (e.g. \"US\")."},"state_code":{"type":"string","nullable":true,"description":"State / province abbreviation (e.g. \"NY\"). Resolved against the selected country."},"state_name":{"type":"string","nullable":true,"description":"Free-text state for countries without a states list."},"pickup_enabled":{"type":"boolean"},"pickup_stock_policy":{"type":"string","enum":["local","any"],"description":"'local' = items at this location only; 'any' = transfer-eligible (ship-to-store)."},"pickup_ready_in_minutes":{"type":"number","nullable":true,"minimum":0},"pickup_instructions":{"type":"string","nullable":true}},"required":["name"]}}}}}},"/api/v3/admin/stock_locations/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Stock location ID","schema":{"type":"string"}}],"get":{"summary":"Get a stock location","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single stock location by prefixed ID.\n\n**Required scope:** `read_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"stock location found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockLocation"}}}},"404":{"description":"stock location not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a stock location","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an existing stock location. Same address-field conventions as\nthe create endpoint.\n\nSetting `default: true` automatically demotes the previous default.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"stock location updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockLocation"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"admin_name":{"type":"string","nullable":true},"active":{"type":"boolean"},"default":{"type":"boolean"},"kind":{"type":"string","enum":["warehouse","store","fulfillment_center"]},"propagate_all_variants":{"type":"boolean"},"backorderable_default":{"type":"boolean"},"address1":{"type":"string","nullable":true},"address2":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"state_name":{"type":"string","nullable":true},"pickup_enabled":{"type":"boolean"},"pickup_stock_policy":{"type":"string","enum":["local","any"]},"pickup_ready_in_minutes":{"type":"number","nullable":true,"minimum":0},"pickup_instructions":{"type":"string","nullable":true}}}}}}},"delete":{"summary":"Delete a stock location","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the stock location (sets `deleted_at`). Existing\nfulfillments that referenced it keep the historical record via\n`Spree::StockLocation.with_deleted`.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"stock location deleted"}}}},"/api/v3/admin/products/{product_id}/variants":{"get":{"summary":"List product variants","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of variants for a product, including the default variant.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., images, prices, stock_levels, option_values). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., sku,price,stock). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"variants found","content":{"application/json":{}}}}},"post":{"summary":"Create a variant","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new variant for a product. Supports nested prices and stock items.\n\nOption types and values are auto-created if they don't exist.\nPrices are upserted by currency. Stock items are upserted by stock location.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"201":{"description":"variant created","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sku":{"type":"string"},"cost_price":{"type":"string"},"cost_currency":{"type":"string"},"weight":{"type":"number"},"height":{"type":"number"},"width":{"type":"number"},"depth":{"type":"number"},"weight_unit":{"type":"string"},"dimensions_unit":{"type":"string"},"track_inventory":{"type":"boolean"},"tax_category_id":{"type":"string"},"options":{"type":"array","description":"A variant on a product with option types should declare its option pairs (e.g. size + color) — one per option type it participates in. Option types and values are auto-created if missing.","items":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string"},"value":{"type":"string"}}}},"position":{"type":"integer"},"barcode":{"type":"string"},"prices":{"type":"array","description":"Per-currency prices. Upserted by currency.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"stock_levels":{"type":"array","description":"Per-stock-location inventory. Upserted by stock_location_id.","items":{"type":"object","required":["stock_location_id","count_on_hand"],"properties":{"stock_location_id":{"type":"string","description":"Stock location ID (e.g. sloc_xxx)"},"count_on_hand":{"type":"integer"},"backorderable":{"type":"boolean"}}}}}}}}}}},"/api/v3/admin/products/{product_id}/variants/{id}":{"get":{"summary":"Get a variant","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single variant by ID.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Variant ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., images, prices, stock_levels, option_values). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., sku,price,stock). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"variant found","content":{"application/json":{}}},"404":{"description":"variant not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a variant","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a variant. Only provided fields are updated.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Variant ID","schema":{"type":"string"}}],"responses":{"200":{"description":"variant updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sku":{"type":"string"},"cost_price":{"type":"string"},"cost_currency":{"type":"string"},"weight":{"type":"number"},"height":{"type":"number"},"width":{"type":"number"},"depth":{"type":"number"},"weight_unit":{"type":"string"},"dimensions_unit":{"type":"string"},"track_inventory":{"type":"boolean"},"tax_category_id":{"type":"string"},"options":{"type":"array","description":"One pair per option type the variant participates in (e.g. size + color). Option types and values are auto-created if missing.","items":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string"},"value":{"type":"string"}}}},"position":{"type":"integer"},"barcode":{"type":"string"},"prices":{"type":"array","description":"Per-currency prices. Upserted by currency.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"stock_levels":{"type":"array","description":"Per-stock-location inventory. Upserted by stock_location_id.","items":{"type":"object","required":["stock_location_id","count_on_hand"],"properties":{"stock_location_id":{"type":"string","description":"Stock location ID (e.g. sloc_xxx)"},"count_on_hand":{"type":"integer"},"backorderable":{"type":"boolean"}}}}}}}}}},"delete":{"summary":"Delete a variant","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes a variant.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Variant ID","schema":{"type":"string"}}],"responses":{"204":{"description":"variant deleted"}}}},"/api/v3/admin/webhook_endpoints/{webhook_endpoint_id}/deliveries":{"parameters":[{"name":"webhook_endpoint_id","in":"path","required":true,"description":"Parent webhook endpoint ID","schema":{"type":"string"}}],"get":{"summary":"List webhook deliveries","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns delivery attempts for the given endpoint, most recent first.\nEach row carries the original request payload, the response code\n(when the receiver replied), the execution time, and any transport\nerror — everything needed to audit failures and decide whether to\nredeliver.\n\n\n**Required scope:** `read_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[event_name_eq]","in":"query","required":false,"description":"Filter by event name (exact)","schema":{"type":"string"}},{"name":"q[success_eq]","in":"query","required":false,"description":"Filter by success flag","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-delivered_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"deliveries found","content":{"application/json":{}}},"404":{"description":"parent webhook endpoint not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/webhook_endpoints/{webhook_endpoint_id}/deliveries/{id}":{"parameters":[{"name":"webhook_endpoint_id","in":"path","required":true,"description":"Parent webhook endpoint ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Webhook delivery ID","schema":{"type":"string"}}],"get":{"summary":"Get a webhook delivery","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single delivery attempt with the full request payload and\nthe response body the receiver returned. Use this for ad-hoc debug\nof failed deliveries.\n\n\n**Required scope:** `read_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"delivery found","content":{"application/json":{}}},"404":{"description":"delivery not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/webhook_endpoints/{webhook_endpoint_id}/deliveries/{id}/redeliver":{"parameters":[{"name":"webhook_endpoint_id","in":"path","required":true,"description":"Parent webhook endpoint ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Webhook delivery ID to redeliver","schema":{"type":"string"}}],"post":{"summary":"Redeliver a webhook delivery","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new delivery row with the same payload + event_name and\nqueues it. The original row is preserved for audit history.\n\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"redelivery queued","content":{"application/json":{}}}}}},"/api/v3/admin/webhook_endpoints":{"get":{"summary":"List webhook endpoints","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns outbound webhook subscriptions for the current store. Each\nendpoint receives a signed POST when any subscribed event fires.\n`secret_key` is `null` on list reads — the plaintext is delivered\nexactly once on create.\n\n\n**Required scope:** `read_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[url_cont]","in":"query","required":false,"description":"Filter by URL (contains)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"webhook endpoints found","content":{"application/json":{}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new outbound webhook subscription. The plaintext\n`secret_key` is returned **once** in this response — persist it\nimmediately to verify incoming webhook signatures. Subsequent reads\nreturn `null` for the secret. Pass an empty `subscriptions` array or\nomit it to receive every event.\n\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"webhook endpoint created — secret_key returned once","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"name":{"type":"string"},"url":{"type":"string"},"active":{"type":"boolean"},"subscriptions":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/webhook_endpoints/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook endpoint ID","schema":{"type":"string"}}],"get":{"summary":"Get a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single webhook endpoint by prefixed ID.\n\n**Required scope:** `read_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"webhook endpoint found","content":{"application/json":{}}},"404":{"description":"webhook endpoint not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates name, URL, active flag, or the event subscription list.\nToggling `active` here is equivalent to calling `disable`/`enable`\nwithout an audit reason.\n\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"webhook endpoint updated","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string"},"active":{"type":"boolean"},"subscriptions":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the endpoint and stops future deliveries.\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"webhook endpoint deleted"}}}},"/api/v3/admin/webhook_endpoints/{id}/send_test":{"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook endpoint ID","schema":{"type":"string"}}],"post":{"summary":"Send a test delivery","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a `webhook.test` delivery record and queues it. Use this to\nverify the endpoint is reachable and your signature verification\naccepts Spree's payloads.\n\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"test delivery queued","content":{"application/json":{}}}}}},"/api/v3/admin/webhook_endpoints/{id}/enable":{"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook endpoint ID","schema":{"type":"string"}}],"patch":{"summary":"Re-enable a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Re-enables an endpoint that was manually or automatically disabled.\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"webhook endpoint enabled","content":{"application/json":{}}}}}},"/api/v3/admin/webhook_endpoints/{id}/disable":{"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook endpoint ID","schema":{"type":"string"}}],"patch":{"summary":"Disable a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Manually pauses an endpoint. Unlike auto-disable (triggered after\nrepeated delivery failures), no notification email is sent.\n\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"webhook endpoint disabled","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}}}},"/api/v3/admin/catalogs":{"get":{"summary":"List catalogs","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the store catalogs — product assortments with an optional price list, shown to audiences through assignments.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"catalogs found","content":{"application/json":{}}}}},"post":{"summary":"Create a catalog","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a catalog. Add products and assign audiences (customer group, or company subtree) afterwards.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"catalog created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"active":{"type":"boolean"},"price_list":{"type":"object","nullable":true,"description":"The price list this catalog owns, written inline. Omit for assortment-only (base prices); send null to remove the pricing, which deletes the list. A catalog with an empty assortment prices without restricting visibility; import or curate products to make it restrictive.","properties":{"price_adjustment_percentage":{"type":"string","nullable":true},"adjust_compare_at":{"type":"boolean"}}}},"required":["name"]}}}}}},"/api/v3/admin/catalogs/{id}/assign":{"post":{"summary":"Assign a catalog to an audience","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Shows the catalog to an audience. A company assignment covers the node and its whole subtree.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"catalog assigned","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"assignable_type":{"type":"string","enum":["customer_group","company"]},"assignable_id":{"type":"string"}},"required":["assignable_type","assignable_id"]}}}}}},"/api/v3/admin/catalogs/{catalog_id}/products":{"get":{"summary":"List catalog products","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The catalog's curated assortment, listed by product name — membership\ncarries no order.\n\n`expand=catalog_price` adds what a buyer on this agreement pays for\neach row and where the amount comes from: `explicit` (an amount\nentered on the catalog's own price list), `automatic` (that list's\npercentage applied to the shop price) or `base` (the shop price\nitself — this agreement does not price the product).\n\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated. `catalog_price` adds the resolved price to every row.","schema":{"type":"string"}}],"responses":{"200":{"description":"products found, with what the agreement charges","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CatalogProduct"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Add products to a catalog","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Curates products into the assortment in bulk. Already-present products are skipped; the count reports what was added.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"products added","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}},"delete":{"summary":"Remove products from a catalog","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes products from the assortment in bulk. Ids that are not members are ignored; the count reports what was removed.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products removed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}}},"/api/v3/admin/catalogs/{catalog_id}/order_minimums":{"get":{"summary":"List catalog order minimums","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The least a whole order must come to under this agreement. One row per currency — Spree holds no exchange rates, so a threshold is never stated once and converted.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"order minimums found","content":{"application/json":{}}}}},"post":{"summary":"Create a catalog order minimum","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Requires orders in one currency to reach an amount. The buyer sees the shortfall on the cart while they can still act on it; completion is refused below it.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"order minimum created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"currency":{"type":"string"},"amount":{"type":"string"}},"required":["currency","amount"]}}}}}},"/api/v3/admin/catalogs/{catalog_id}/order_minimums/{id}":{"patch":{"summary":"Update a catalog order minimum","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Restates one currency's threshold.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"order minimum updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string"}}}}}}},"delete":{"summary":"Delete a catalog order minimum","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Lifts the threshold for one currency, so orders in it may come to any total.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"order minimum deleted"}}}},"/api/v3/admin/catalogs/{catalog_id}/quantity_rules":{"put":{"summary":"Set catalog quantity rules","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Writes the given products' quantity terms in one request, keyed by prefixed product id. The stated pair is written to every variant of the product, which is the grain the database keeps them at. Both fields null clears that product's terms; a product not yet in the assortment is added, since a term with nothing to apply to is not a reachable state. Products absent from the payload are left alone — an agreement may name terms for thousands of SKUs. Read them back on the assortment rows: `GET /catalogs/{id}/products?expand=quantity_rule`.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"quantity rules set"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"terms":{"type":"object","additionalProperties":{"type":"object","properties":{"minimum_order_quantity":{"type":"integer","nullable":true},"order_multiple":{"type":"integer","nullable":true}}}}},"required":["terms"]}}}}}},"/api/v3/admin/catalogs/{id}/activate":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Activate a catalog","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Puts the agreement into effect: its audience starts seeing its\nassortment and paying its prices. Refused for a catalog nobody is\nassigned to, since activating it would reach no buyer — a channel's\ndefault catalog is reached through the channel instead, so it needs\nno assignment.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"catalog activated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Catalog"}}}}}}},"/api/v3/admin/catalogs/{id}/deactivate":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Deactivate a catalog","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Takes the agreement out of effect. Everything it holds — assignments,\ncommercial terms, its price list — survives, so activating again\nresumes exactly what was there.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"catalog deactivated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Catalog"}}}}}}},"/api/v3/admin/collections":{"get":{"summary":"List collections","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of the store's collections.\n\n**Required scope:** `read_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., rules, custom_fields, translations).","schema":{"type":"string"}}],"responses":{"200":{"description":"collections found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Collection"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a manual or automatic (rule-based) collection. For automatic collections, send the full desired rule set under `rules`.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"collection created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"automatic":{"type":"boolean"},"rules_match_policy":{"type":"string","enum":["all","any"]},"sort_order":{"type":"string"},"permalink":{"type":"string"},"description":{"type":"string"},"meta_title":{"type":"string"},"meta_description":{"type":"string"},"meta_keywords":{"type":"string"},"rules":{"type":"array","description":"Full desired rule set. Entries with an id update, id-less entries create, omitted rules are removed.","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"value":{"type":"string"},"match_policy":{"type":"string"}}}}},"required":["name"]}}}}}},"/api/v3/admin/collections/{id}":{"get":{"summary":"Get a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single collection by ID, including its rules.\n\n**Required scope:** `read_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., rules, custom_fields, translations).","schema":{"type":"string"}}],"responses":{"200":{"description":"collection found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}},"404":{"description":"collection not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a collection. Send `position` to reorder it within the flat list; send the full `rules` set to sync automatic rules.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}}],"responses":{"200":{"description":"collection updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"permalink":{"type":"string"},"description":{"type":"string"},"meta_title":{"type":"string"},"meta_description":{"type":"string"},"meta_keywords":{"type":"string"},"sort_order":{"type":"string"},"automatic":{"type":"boolean"},"rules_match_policy":{"type":"string","enum":["all","any"]},"position":{"type":"integer","description":"Reorders the collection within the flat list (acts_as_list)"},"rules":{"type":"array","description":"Full desired rule set (see create).","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"value":{"type":"string"},"match_policy":{"type":"string"}}}}}}}}}},"delete":{"summary":"Delete a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a collection.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}}],"responses":{"204":{"description":"collection deleted"}}}},"/api/v3/admin/collections/{collection_id}/products":{"get":{"summary":"List collection products","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Products curated in the collection, ordered by their membership position.\n\n**Required scope:** `read_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"collection_id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}}],"responses":{"200":{"description":"products found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Add products to a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Curates products into the collection in bulk (appended to the end). Already-curated products are skipped; the count reports what was added.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"collection_id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}}],"responses":{"201":{"description":"products added","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}},"delete":{"summary":"Remove products from a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes products from the collection's manual curation in bulk. Ids that are not curated are ignored; the count reports what was removed.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"collection_id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}}],"responses":{"200":{"description":"products removed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}}},"/api/v3/admin/collections/{collection_id}/products/{id}/reposition":{"patch":{"summary":"Reposition a collection product","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Moves a product to a new index among the collection's products.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"collection_id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"204":{"description":"product repositioned"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"new_position":{"type":"integer","description":"0-based index among the collection's products"}},"required":["new_position"]}}}}}},"/api/v3/admin/collection_rules/types":{"get":{"summary":"List available collection rule types","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Enumerates the registered rule kinds with their labels and descriptions — drives the rule picker on an automatic collection. Plugins extend the list by registering `Spree::CollectionRule` subclasses via `config.spree.collection_rules`. The `type` returned here is the wire shorthand accepted when writing a collection's `rules`.\n\n**Required scope:** `read_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"types found","content":{"application/json":{}}}}}},"/api/v3/admin/commission_lines":{"get":{"summary":"List commission lines","tags":["Commission Lines"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"What each sale actually earned the marketplace, frozen when the order\nwas placed. A later change to a commission rate never reaches these.\n\n`amount` is the fee charged to the seller and `tax_amount` is the VAT on\nthat fee — the marketplace's own service to the seller, a supply\nseparate from the sale itself, which is why the two are not folded\ntogether. `total` is their sum.\n\nOne line per commissioned item, plus one per delivery when the rate that\napplied charges shipping too — read `line_item_id` and `fulfillment_id`\nto tell them apart.\n\nRead-only: correcting a charge is a reversal, not an edit.\n\n\n**Required scope:** `read_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[seller_id_eq]","in":"query","required":false,"description":"Filter to one seller","schema":{"type":"string"}},{"name":"q[order_id_eq]","in":"query","required":false,"description":"Filter to one order","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed (e.g., `commission_rate`).","schema":{"type":"string"}}],"responses":{"200":{"description":"commission lines found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CommissionLine"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/commission_lines/{id}":{"parameters":[{"name":"id","in":"path","description":"Commission line ID","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a commission line","tags":["Commission Lines"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"commission line found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommissionLine"}}}},"404":{"description":"commission line not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/commission_rates":{"get":{"summary":"List commission rates","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"What the marketplace charges its sellers.\n\nRates are returned in resolution order: the list is walked top-down and\nthe first rate whose targeting matches the sale wins, so the order you\nsee is the precedence. Move a rate with `position` on update.\n\nA rate carrying no rules matches every sale — `global` says so — which\nis how a marketplace expresses a single default. Because resolution\nstops at the first match, a global rate makes everything below it\nunreachable, so it belongs at the bottom.\n\n\n**Required scope:** `read_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[enabled_eq]","in":"query","required":false,"description":"Filter by whether the rate is in use","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-position`).","schema":{"type":"string"}}],"responses":{"200":{"description":"commission rates found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CommissionRate"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a commission rate","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Sets what the marketplace charges, and which sales it applies to.\n\n`rules` is the rate's whole targeting, sent inline. Every rule has to\nhold, and a rule naming several records means any of them — so\n\"(Cameras OR Audio) AND that seller\" is a category rule holding two ids\nbeside a seller rule holding one. Send no rules to charge every sale.\n\nRule kinds come from `GET /commission_rates/rule_types`, which also\ndescribes the configuration each one takes. A marketplace that adds its\nown kind sees it there without this endpoint changing.\n\n`commission_tax_rate` is VAT on the commission itself — the\nmarketplace's own service to the seller, a separate supply from the\nsale. Leave it null to let the store's tax engine answer for wherever\nthe seller's business sits.\n\n\n**Required scope:** `write_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"commission rate created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommissionRate"}}}},"422":{"description":"validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name","kind","value"],"properties":{"name":{"type":"string"},"code":{"type":"string","nullable":true,"description":"Your own identifier for this rate; unique per store."},"enabled":{"type":"boolean"},"position":{"type":"integer","description":"Place in the list. Rates resolve top-down, so 1 is tried first. New rates are created at the top; send this to move one."},"kind":{"type":"string","enum":["percentage","fixed"]},"value":{"type":"string","description":"A percentage (10 = 10%) or a flat amount, per `kind`."},"amounts":{"type":"object","additionalProperties":{"type":"string"},"description":"What a flat fee charges, keyed by currency. A currency with no amount is one this rate does not charge — those sales fall to the next rate. Ignored for a percentage."},"tax_inclusive":{"type":"boolean","description":"Charge on the price including the customer's VAT. Left off, commission is charged on the seller's net revenue, which is the usual basis where the fee is taxed as its own supply."},"include_shipping":{"type":"boolean","description":"Also charge commission on the seller's delivery revenue."},"bounds":{"type":"object","additionalProperties":{"type":"object","properties":{"min_amount":{"type":"string","nullable":true},"max_amount":{"type":"string","nullable":true}}},"description":"The floor and cap a percentage charges within, keyed by currency. Each holds only in its own currency; a sale in a currency with no bounds is charged unbounded."},"commission_tax_rate":{"type":"string","nullable":true,"description":"A fraction, not a percentage. Null asks the tax engine."},"rules":{"type":"array","description":"The full targeting; what you send replaces what the rate holds.","items":{"type":"object","properties":{"id":{"type":"string","description":"Present for an existing rule; omit to create one."},"type":{"type":"string","description":"A kind from /commission_rates/rule_types."},"preferences":{"type":"object","description":"Configuration for the kind, per its preference_schema."},"product_ids":{"type":"array","items":{"type":"string"},"description":"For kinds that name products, which are kept outside preferences."}}}}}}}}}}},"/api/v3/admin/commission_rates/rule_types":{"get":{"summary":"List the commission rule kinds","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Every rule kind a rate can be narrowed by, with the schema describing\nthe configuration it takes — so a client builds its editor from what\nthis marketplace has rather than a list hardcoded to match core's.\n\n`association_fields` names any catalog-scale reference a kind keeps\noutside its preferences, so an editor knows to render a picker for it.\n\n\n**Required scope:** `read_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"subject types found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"preference_schema":{"type":"array","items":{"type":"object"}},"association_fields":{"type":"array","items":{"type":"string"}}}}}}}}}}}}},"/api/v3/admin/commission_rates/{id}":{"parameters":[{"name":"id","in":"path","description":"Commission rate ID","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a commission rate","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"commission rate found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommissionRate"}}}},"404":{"description":"commission rate not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a commission rate","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Editing a rate changes what the next sale is charged, never what a past\none was: commission lines keep their own snapshot of the rate that\napplied.\n\n\n**Required scope:** `write_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"commission rate updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommissionRate"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"enabled":{"type":"boolean"},"position":{"type":"integer"},"value":{"type":"string"},"rules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"preferences":{"type":"object"},"product_ids":{"type":"array","items":{"type":"string"}}}}}}}}}}},"delete":{"summary":"Delete a commission rate","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"commission rate deleted"}}}},"/api/v3/admin/companies/{company_id}/memberships":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List company members","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the people with standing over this node. Standing covers the node and everything below it in the tree.\n\n**Required scope:** `read_customers` (for API-key authentication).","responses":{"200":{"description":"members found","content":{"application/json":{}}}}},"post":{"summary":"Add a member by email","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a person to the node by email. An email matching an existing customer becomes a\nmembership immediately (a `cmem_…` id); an unknown email becomes an invitation\n(a `cinv_…` id) and the invite email goes out.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[],"responses":{"201":{"description":"member added","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"customer_email":{"type":"string"}},"required":["customer_email"]}}}}}},"/api/v3/admin/companies/{company_id}/tax_exemption_certificates":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List tax exemption certificates","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a business's exemption evidence. `active` is the field that decides whether a certificate\nexempts a sale: a verified certificate stops counting once its expiry date passes, so the status\nalone does not answer it.\n\n\n**Required scope:** `read_customers` (for API-key authentication).","responses":{"200":{"description":"certificates found","content":{"application/json":{}}}}},"post":{"summary":"Create a tax exemption certificate","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Records exemption evidence against a business. Certificates start `pending` and exempt nothing\nuntil verified.\n\n`country_code` and `state_code` say where the certificate holds — omit both for one valid\neverywhere, give only the country for one valid throughout it. `document` takes an ActiveStorage\nsigned blob id obtained from `POST /api/v3/admin/direct_uploads`.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[],"responses":{"201":{"description":"certificate created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"certificate_number":{"type":"string"},"reason_code":{"type":"string","description":"Becomes the tax provider's entity use code."},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"expires_at":{"type":"string","format":"date-time","nullable":true},"issuing_authority":{"type":"string","nullable":true},"document":{"type":"string","description":"ActiveStorage signed blob id from POST /api/v3/admin/direct_uploads."}},"required":["certificate_number","reason_code"]}}}}}},"/api/v3/admin/companies/{company_id}/tax_exemption_certificates/{id}/verify":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Verify a tax exemption certificate","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Accepts the certificate as evidence, which is what makes it exempt sales. Only a pending\ncertificate can be accepted — re-accepting a revoked one would restore evidence that was\ndeliberately withdrawn. An installation that checks numbers against a registry, or requires a\nsecond approval, can refuse here, and the refusal is returned as a validation error.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","responses":{"200":{"description":"certificate verified","content":{"application/json":{}}}}}},"/api/v3/admin/companies/{company_id}/tax_exemption_certificates/{id}/revoke":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Revoke a tax exemption certificate","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Withdraws accepted evidence. A verified certificate cannot be deleted — how a sale was taxed has to remain explainable — so revoking is the way out.\n\n**Required scope:** `write_customers` (for API-key authentication).","responses":{"200":{"description":"certificate revoked","content":{"application/json":{}}}}}},"/api/v3/admin/companies/{company_id}/tax_exemption_certificates/{id}/download":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Download a certificate document","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Streams the uploaded document. Deliberately not a storage link: the bytes come through the API so\nthe same credentials apply to every read of a confidential document. Requires only read access.\n\n\n**Required scope:** `read_customers` (for API-key authentication).","responses":{"200":{"description":"document streamed","content":{"application/json":{}}},"422":{"description":"no document attached","content":{"application/json":{}}}}}},"/api/v3/admin/companies/{company_id}/tax_identifiers":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List company tax registrations","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the business's tax registrations, one per kind. A business registration takes precedence\nover the buyer's own when a sale is for that business, because the invoice is addressed to the\nentity rather than the person who placed the order.\n\n\n**Required scope:** `read_customers` (for API-key authentication).","responses":{"200":{"description":"registrations found","content":{"application/json":{}}}}},"post":{"summary":"Create a company tax registration","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Registers a tax number against the business. Verification against the relevant registry runs in\nthe background where a validator is installed for the kind; a stock installation registers none,\nleaving the status unattempted.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[],"responses":{"201":{"description":"registration created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","description":"The regime the number belongs to."},"value":{"type":"string"}},"required":["kind","value"]}}}}}},"/api/v3/admin/companies/{company_id}/tax_identifiers/{id}/validate":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Re-check a company tax registration","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Asks the registry again. Manual because a registry answers only \"valid now\" — a number verified\nlast year may have been deregistered since — and because a check that came back unavailable\ncannot otherwise be retried without editing the number.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","responses":{"422":{"description":"no validator installed for this kind","content":{"application/json":{}}}}}},"/api/v3/admin/companies":{"get":{"summary":"List companies","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the business customers of the current store.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"companies found","content":{"application/json":{}}}}},"post":{"summary":"Create a company","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a company node. A root node is a legal entity; pass parent_id and kind to build the organization tree. Exemption certificates and tax registrations hang off legal-entity nodes.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"company created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"kind":{"type":"string","enum":["company","division"],"description":"company = legal entity (may hold tax registrations), division = organizational unit. Roots must be company."},"parent_id":{"type":"string","nullable":true,"description":"The parent node. Omit for a root."},"external_references":{"type":"array","description":"Identities this business has in your own systems. A system you do not name keeps the reference it already has, and creating with a reference that already exists updates that business instead.","items":{"type":"object","properties":{"system":{"type":"string"},"external_id":{"type":"string"}},"required":["system","external_id"]}}},"required":["name"]}}}}}},"/api/v3/admin/custom_field_definitions/resource_types":{"get":{"summary":"List what custom fields can be attached to","tags":["Custom Field Definitions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The resources a definition can describe, from the server's own\nregistry (`Spree.custom_fields.enabled_resources`).\n\nRead this rather than carrying a list: a resource an extension\nregisters appears here without a client release, and a `resource_type`\nthat is not listed is refused on create.\n\n`resource_type` is the value to send; `name` is what a merchant calls\nit. The two differ where a class has been renamed — categories are\nstored under `Spree::Taxon` and shown as \"Categories\" — so send the\nvalue back verbatim rather than deriving it from the name.\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"resource types found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"resource_type":{"type":"string"},"name":{"type":"string"}}}}}}}}}}}},"/api/v3/admin/delivery_profiles":{"get":{"summary":"List delivery profiles","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Fulfillment profiles group products with the stock locations, delivery zones and delivery methods that fulfill them. Every store has exactly one default profile.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"delivery profiles found","content":{"application/json":{}}}}},"post":{"summary":"Create a delivery profile","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a delivery profile. `kind` selects the registered profile kind (shipping, digital, extension kinds); `stock_location_ids` limits fulfillment to those locations — empty means every store location.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"delivery profile created","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"kind":{"type":"string","description":"Registered profile kind; defaults to shipping."},"default":{"type":"boolean"},"stock_location_ids":{"type":"array","items":{"type":"string"},"description":"Empty means every store location."}},"required":["name"]}}}}}},"/api/v3/admin/delivery_profiles/{delivery_profile_id}/origin_groups":{"parameters":[{"name":"delivery_profile_id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Create an origin group","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Origin groups partition a profile's fulfillment origins: zones and methods belong to a group, so the same products can quote different rate tables per warehouse. `stock_location_ids` replaces the full membership; empty means every store location.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"origin group created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","nullable":true},"position":{"type":"integer","nullable":true},"stock_location_ids":{"type":"array","items":{"type":"string"},"description":"Empty means every store location."}}}}}}}},"/api/v3/admin/delivery_profiles/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Update a delivery profile","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"delivery profile updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"default":{"type":"boolean"},"stock_location_ids":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a delivery profile","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The default profile and profiles still referenced by products cannot be deleted.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"delivery profile deleted"}}}},"/api/v3/admin/delivery_methods":{"get":{"summary":"List delivery methods","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all delivery methods with calculator and zone configuration.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"delivery methods found","content":{"application/json":{}}}}},"post":{"summary":"Create delivery method","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a delivery method inside a delivery profile (defaults to the store default profile). Delivery behavior comes from the fulfillment provider.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"delivery method created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"admin_name":{"type":"string","nullable":true},"code":{"type":"string","nullable":true},"fulfillment_provider":{"type":"string","nullable":true},"delivery_profile_id":{"type":"string","nullable":true},"storefront_visible":{"type":"boolean"},"tracking_url":{"type":"string","nullable":true},"estimated_transit_business_days_min":{"type":"integer","nullable":true},"estimated_transit_business_days_max":{"type":"integer","nullable":true},"tax_category_id":{"type":"string","nullable":true},"calculator_type":{"type":"string"},"calculator_preferences":{"type":"object"},"delivery_zone_id":{"type":"string","nullable":true}},"required":["name"]}}}}}},"/api/v3/admin/delivery_methods/calculators":{"get":{"summary":"List delivery calculators","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Registered delivery calculator classes with preference schemas for building configuration forms.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"calculators found","content":{"application/json":{}}}}}},"/api/v3/admin/delivery_zones":{"post":{"summary":"Create delivery zone","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a delivery zone with typed members: country, state, or postal_code (prefix or from/to range).\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed, e.g. `members`","schema":{"type":"string"}}],"responses":{"201":{"description":"delivery zone created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"members":{"type":"array","items":{"type":"object","properties":{"member_type":{"type":"string","enum":["country","state","postal_code"]},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"postal_code_prefix":{"type":"string","nullable":true},"postal_code_from":{"type":"string","nullable":true},"postal_code_to":{"type":"string","nullable":true}},"required":["member_type"]}}},"required":["name"]}}}}}},"/api/v3/admin/integrations":{"get":{"summary":"List integrations","tags":["Integrations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the integrations connected to the current store. Secret preference values are masked.\n\n**Required scope:** `read_integrations` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"integrations found","content":{"application/json":{}}}}},"post":{"summary":"Connect integration","tags":["Integrations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Connects an integration type to the current store. Setting active: true verifies the connection and fails with 422 when it cannot connect. Submitting a masked secret value back keeps the stored secret.\n\n**Required scope:** `write_integrations` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"integration connected","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"Wire shorthand from GET /integrations/types"},"active":{"type":"boolean"},"preferences":{"type":"object"}},"required":["type"]}}}}}},"/api/v3/admin/integrations/types":{"get":{"summary":"List integration types","tags":["Integrations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Every registered integration type with its gallery metadata and configuration schema. Pure registry discovery — read live connection state from GET /integrations.\n\n**Required scope:** `read_integrations` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"integration types found","content":{"application/json":{}}}}}},"/api/v3/admin/integrations/{id}/test":{"post":{"summary":"Test integration connection","tags":["Integrations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Runs a live connection check against the provider. Nothing is persisted; a failed check reports the seller error message.\n\n**Required scope:** `write_integrations` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"connection checked","content":{"application/json":{}}}}}},"/api/v3/admin/media":{"get":{"summary":"List media","tags":["Media"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns every file in the store's media library, whether or not it has\nbeen placed on a product. Filter with `q[unattached]=true` for files not\nyet in use, `q[media_type_eq]` for images or video, and\n`q[filename_cont]` to search by file name.\n\n\n**Required scope:** `read_media` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}}],"responses":{"200":{"description":"media found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Media"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Upload a file to the library","tags":["Media"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a file to the library without placing it on anything. Upload the\nfile first through the direct-upload endpoint, then send the signed id\nhere. Put the file on a product by posting to that product's media with\nthis record's id as `source_media_id`.\n\n\n**Required scope:** `write_media` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"file added","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Media"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"signed_id":{"type":"string","description":"Direct-upload signed id for the file."},"alt":{"type":"string"},"media_type":{"type":"string","enum":["image","video","external_video"]},"external_video_url":{"type":"string","description":"YouTube or Vimeo link, for an external video."}}}}}}}},"/api/v3/admin/media/{id}/usage":{"parameters":[{"name":"id","in":"path","description":"Media ID","required":true,"schema":{"type":"string"}}],"get":{"summary":"Where a file is used","tags":["Media"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Lists everywhere this file appears: products it is placed on, image\nfields that picked it, and descriptions embedding it. Reusing a file\nshares it rather than copying it, so deleting one placement can leave\nothers pointing at the same file — check this first.\n\nDescription matches are best-effort: an embedded image is a plain URL\nwith nothing recording it, so treat an empty result as \"nothing found\",\nnot proof the file is unused.\n\n\n**Required scope:** `read_media` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"usage found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["media","attachment","rich_text"]},"name":{"type":"string","nullable":true},"owner_type":{"type":"string"},"owner_id":{"type":"string","nullable":true},"field":{"type":"string","nullable":true}}}}}}}}}}}},"/api/v3/admin/products/{product_id}/media":{"parameters":[{"name":"product_id","in":"path","description":"Product ID","required":true,"schema":{"type":"string"}}],"post":{"summary":"Place a library file on a product","tags":["Media"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Puts a file that is already in the library onto this product. The new\nrecord shares the source's file rather than copying it, so nothing is\nuploaded and no image is reprocessed; it carries its own alt text,\nposition and variant links from here on.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"file placed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Media"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"source_media_id":{"type":"string","description":"A media record already in the library."},"alt":{"type":"string"},"position":{"type":"integer"}},"required":["source_media_id"]}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/deliveries":{"get":{"summary":"List deliveries","tags":["Deliveries"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The consignments of a parcel — one per tracking number, each with the carrier status last reported.\n\n**Required scope:** `read_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"deliveries found","content":{"application/json":{}}}}},"post":{"summary":"Record a delivery","tags":["Deliveries"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a tracked consignment to a parcel — a second box, or a freight PRO number covering several pallets. The carrier is free text.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"201":{"description":"delivery recorded","content":{"application/json":{}}},"422":{"description":"tracking number already recorded on this parcel","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["tracking_number"],"properties":{"tracking_number":{"type":"string","description":"Carrier tracking number, freight PRO number, or a full tracking link"},"carrier":{"type":"string","description":"Free-text carrier; detected from the number when omitted"},"service":{"type":"string","description":"Carrier service"},"tracking_url":{"type":"string","description":"Tracking page for this consignment"}}}}},"required":true}}},"/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/deliveries/{id}":{"patch":{"summary":"Correct a delivery","tags":["Deliveries"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Corrects the tracking number, carrier or link. A corrected number starts the carrier journey over.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Delivery ID","schema":{"type":"string"}}],"responses":{"200":{"description":"delivery updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tracking_number":{"type":"string"},"carrier":{"type":"string"},"service":{"type":"string"},"tracking_url":{"type":"string"}}}}},"required":true}},"delete":{"summary":"Delete a delivery","tags":["Deliveries"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes a hand-entered consignment. One a label minted is refused — refund the label instead.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Delivery ID","schema":{"type":"string"}}],"responses":{"204":{"description":"delivery deleted"}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/deliveries/{id}/mark_delivered":{"patch":{"summary":"Mark a delivery delivered","tags":["Deliveries"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Staff confirming one consignment arrived. The parcel becomes delivered once every one of its consignments has.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Delivery ID","schema":{"type":"string"}}],"responses":{"200":{"description":"delivery marked delivered","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"delivered_at":{"type":"string","format":"date-time","description":"When it arrived. Defaults to now."},"notify_customer":{"type":"boolean","description":"Whether the customer gets a delivery notification when the parcel completes."}}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/labels":{"get":{"summary":"List shipping labels","tags":["Shipping Labels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Every label bought or uploaded for a parcel, refunded ones included.\n\n**Required scope:** `read_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"labels found","content":{"application/json":{}}}}},"post":{"summary":"Buy or record a shipping label","tags":["Shipping Labels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"With no body, buys the label through the parcel's carrier account. With a `file`, records a label bought elsewhere. Either way the tracking number becomes a delivery on the parcel.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"201":{"description":"label purchased","content":{"application/json":{}}},"422":{"description":"provider does not produce labels","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"file":{"type":"string","description":"Signed blob id of an uploaded label file; its presence records rather than buys"},"tracking_number":{"type":"string","description":"Number printed on an uploaded label"},"carrier":{"type":"string","description":"Free-text carrier; detected from the number when omitted"},"service":{"type":"string","description":"Carrier service the label was bought at"},"cost":{"type":"string","description":"What the merchant paid the carrier"},"currency":{"type":"string","description":"Currency of the cost"},"file_format":{"type":"string","enum":["pdf","png","zpl"],"description":"Label file format; taken from the file when omitted"},"tracking_url":{"type":"string","description":"Tracking page for the consignment"}}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/labels/{id}":{"get":{"summary":"Get a shipping label","tags":["Shipping Labels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"One label, with what it cost and where to print it from.\n\n**Required scope:** `read_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Shipping label ID","schema":{"type":"string"}}],"responses":{"200":{"description":"label found","content":{"application/json":{}}}}},"delete":{"summary":"Delete an uploaded label","tags":["Shipping Labels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes an uploaded label. A purchased label is refunded instead, so the postage history stays honest.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Shipping label ID","schema":{"type":"string"}}],"responses":{"204":{"description":"label deleted"}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/labels/{id}/refund":{"patch":{"summary":"Refund a shipping label","tags":["Shipping Labels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Asks the carrier to refund a purchased label. The consignment it minted is removed when the parcel never shipped.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Shipping label ID","schema":{"type":"string"}}],"responses":{"200":{"description":"refund filed","content":{"application/json":{}}},"422":{"description":"uploaded labels cannot be refunded","content":{"application/json":{}}}}}},"/api/v3/admin/package_types":{"get":{"summary":"List package types","tags":["Package Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the store's packaging vocabulary: the box it ships parcels in\nand the cartons, pallets and containers a wholesale order leaves on.\n\n`volume` is the cubic meters the package occupies, converted from\nwhatever unit its dimensions were recorded in — the figure freight\nvolume rules compare against. It is null until all three sides are\nmeasured.\n\n\n**Required scope:** `read_package_types` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[kind_eq]","in":"query","required":false,"description":"Filter by kind (`box`, `envelope`, `carton`, `pallet`, `container`)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"responses":{"200":{"description":"package types found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PackageType"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a package type","tags":["Package Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a kind of packaging to the store.\n\n`weight` is the empty package's own weight, added to content weight on\nevery quote; `max_weight` is what it can hold. Setting `default` makes\nthis the box every parcel quote is built on, and demotes whichever row\nheld that before.\n\nA variant references a `carton`-kind row to say what it is packed\ninto; other kinds are the merchant's own vocabulary.\n\n\n**Required scope:** `write_package_types` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"package type created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PackageType"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"kind":{"type":"string","enum":["box","envelope","carton","pallet","container"]},"length":{"type":"number"},"width":{"type":"number"},"height":{"type":"number"},"dimensions_unit":{"type":"string","enum":["mm","cm","in","ft"]},"weight":{"type":"number"},"max_weight":{"type":"number"},"weight_unit":{"type":"string","enum":["g","kg","lb","oz"]},"default":{"type":"boolean"}},"required":["name","kind"]}}}}}},"/api/v3/admin/package_types/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Package type ID","schema":{"type":"string"}}],"get":{"summary":"Get a package type","tags":["Package Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single package type by prefixed ID.\n\n**Required scope:** `read_package_types` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"package type found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PackageType"}}}},"404":{"description":"package type not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a package type","tags":["Package Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a package type. Every product packed in it follows the new geometry.\n\n**Required scope:** `write_package_types` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"package type updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PackageType"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"kind":{"type":"string","enum":["box","envelope","carton","pallet","container"]},"length":{"type":"number"},"width":{"type":"number"},"height":{"type":"number"},"dimensions_unit":{"type":"string","enum":["mm","cm","in","ft"]},"weight":{"type":"number"},"max_weight":{"type":"number"},"weight_unit":{"type":"string","enum":["g","kg","lb","oz"]},"default":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a package type","tags":["Package Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes a kind of packaging. Refused while any variant is packed into\nit — repack those products first.\n\n\n**Required scope:** `write_package_types` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"package type deleted"}}}},"/api/v3/admin/price_lists/{price_list_id}/products":{"get":{"summary":"List price list products","tags":["Price Lists"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The products the list prices, listed by name — membership is derived from the price rows.\n`expand=price_list_price` adds what the list charges for each variant, with its quantity\nbreaks as tiers, the same reading a catalog's products carry.\n\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"price_list_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated. `price_list_price` adds the resolved price to every row.","schema":{"type":"string"}}],"responses":{"200":{"description":"products found, with what the list charges","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PriceListProduct"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Add products to a price list","tags":["Price Lists"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds products to the list in bulk, materializing a placeholder price per variant and store currency. Already-present products are skipped.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"price_list_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"products added","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}},"delete":{"summary":"Remove products from a price list","tags":["Price Lists"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes products from the list in bulk, hard-deleting their price rows. Ids that are not members are ignored.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"price_list_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products removed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}}},"/api/v3/admin/product_types":{"get":{"summary":"List product types","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of product types.\n\nA product type is a back-office template: it seeds option types and\ncategories onto products created with it, and defines which custom\nfields those products' forms show. It is not exposed on the Store API.\n\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}}],"responses":{"200":{"description":"product types found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ProductType"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a product type","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a product type.\n\n`option_type_ids` and `category_ids` seed products created with this\ntype. `custom_field_definitions` is a replace-set of the definitions the\nproduct form renders, in `sort_order`. `required` is advisory — the\ndashboard marks the field, but a blank value is never rejected.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"product type created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductType"}}}},"422":{"description":"unprocessable entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"delivery_profile_id":{"type":"string","nullable":true,"description":"Fulfillment profile stamped onto products created with this type. Null leaves new products on the store default profile."},"option_type_ids":{"type":"array","items":{"type":"string"},"description":"Option types seeded onto products created with this type."},"category_ids":{"type":"array","items":{"type":"string"},"description":"Categories seeded onto products created with this type."},"custom_field_definitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Prefixed custom field definition id."},"required":{"type":"boolean"},"sort_order":{"type":"integer"}}}}},"required":["name"]}}}}}},"/api/v3/admin/product_types/{id}":{"parameters":[{"name":"id","in":"path","description":"Product type ID","required":true,"schema":{"type":"string"}}],"get":{"summary":"Retrieve a product type","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single product type with its option types, categories and custom fields.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"product type found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductType"}}}},"404":{"description":"product type not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a product type","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a product type.\n\nChanges never modify products that already carry the type — use\n`apply_to_products` to backfill those.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"product type updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductType"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"delivery_profile_id":{"type":"string","nullable":true},"option_type_ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}},"custom_field_definitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"required":{"type":"boolean"},"sort_order":{"type":"integer"}}}}}}}}}},"delete":{"summary":"Delete a product type","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a product type. Types still used by products cannot be deleted.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"product type deleted"}}}},"/api/v3/admin/product_types/{id}/apply_to_products":{"parameters":[{"name":"id","in":"path","description":"Product type ID","required":true,"schema":{"type":"string"}}],"post":{"summary":"Apply a product type to its existing products","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Backfills the type's option types and categories onto the products that\nalready carry it. Additive and idempotent — nothing is removed, and\nre-running is safe.\n\nRuns in the background; the response reports how many products the type\ncurrently has.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"202":{"description":"backfill accepted","content":{"application/json":{"schema":{"type":"object","properties":{"products_count":{"type":"integer"}}}}}}}}},"/api/v3/admin/seller_requirements":{"get":{"summary":"List seller requirements","tags":["Seller Requirements"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"What this marketplace asks of a seller before it will let them trade,\nin the order sellers work through it.\n\nEach row is one configured requirement. `required` says whether it\nstands between the seller and approval — the others are shown as\nrecommended and counted in their progress, but never block. `active`\nswitches one off without losing how it was worded.\n\n\n**Required scope:** `read_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"seller requirements found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SellerRequirement"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}}}}}}},"post":{"summary":"Add a seller requirement","tags":["Seller Requirements"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds something the marketplace asks of its sellers.\n\n`type` comes from `GET /seller_requirements/types`, which also\ndescribes the configuration each kind takes. Most kinds answer one\nquestion and can be added once; the open-ended ones — a seller\nconfirmation, a manual check, a document — carry the question in your\nown `name` and `description`, so a store may add as many as it needs.\n\nA kind that reads the seller's own data (their addresses, their\nproducts, whether they accepted the terms) needs nothing from the\nseller beyond doing it. The others wait for the seller to submit\nsomething, and the ones you review wait for you.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"seller requirement created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SellerRequirement"}}}},"422":{"description":"kind is not registered","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["type"],"properties":{"type":{"type":"string","description":"The kind, from `GET /seller_requirements/types`."},"name":{"type":"string","description":"What the seller sees. Required for kinds that can be added more than once, since the wording is the only thing telling them apart. Left blank on the others, the kind names itself."},"description":{"type":"string","description":"Instructions shown to the seller."},"required":{"type":"boolean","description":"Whether this blocks approval. Off means recommended."},"active":{"type":"boolean"},"position":{"type":"integer","description":"Place in the checklist."},"preferences":{"type":"object","description":"Configuration for this kind, per its `preference_schema`."}}}}}}}},"/api/v3/admin/seller_requirements/types":{"get":{"summary":"List seller requirement kinds","tags":["Seller Requirements"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The kinds you can add, and the shape of each one's configuration form.\n\n`configured` says the store already has this kind — meaningful only\nwhere `allow_multiple` is false. `accepts_submissions` says the seller\nrecords having done it rather than it being read from their data, and\n`reviewed_by_operator` says what they send waits for you.\n\nA marketplace that registers its own kind server-side sees it here\nwithout this endpoint changing.\n\n\n**Required scope:** `read_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"kinds found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"allow_multiple":{"type":"boolean"},"accepts_submissions":{"type":"boolean"},"reviewed_by_operator":{"type":"boolean"},"configured":{"type":"boolean"},"addable":{"type":"boolean","description":"Whether the operator may add one now. The uniqueness rule is the server's, so clients filter on this rather than deriving it."},"preference_schema":{"type":"array","items":{"type":"object"}}}}}}}}}}}}},"/api/v3/admin/seller_requirements/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Update a seller requirement","tags":["Seller Requirements"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Changes how a requirement is worded, what it asks for, where it sits in\nthe checklist, and whether it blocks approval.\n\n`type` is not accepted: a saved row's kind never changes, because\nanything a seller already submitted answered the old one.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"seller requirement updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SellerRequirement"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"required":{"type":"boolean"},"active":{"type":"boolean"},"position":{"type":"integer"},"preferences":{"type":"object"}}}}}}},"delete":{"summary":"Delete a seller requirement","tags":["Seller Requirements"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Stops asking for this. Anything sellers already submitted against it\ngoes too — to keep the record while pausing the ask, set `active` to\nfalse instead.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"seller requirement deleted"}}}},"/api/v3/admin/sellers":{"get":{"summary":"List sellers","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the sellers on this marketplace. `status` says where each one\nis in its life on the marketplace, and `sellable` answers the question\nthe status alone cannot: an approved seller who is away cannot be\nbought from either.\n\n\n**Required scope:** `read_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[status_eq]","in":"query","required":false,"description":"Filter by status","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"responses":{"200":{"description":"sellers found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Seller"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Opens a seller record. The seller starts as `pending` and has no team\nyet — invite someone to run it with the `invite` action below.\n\n`status` is deliberately not writable here or on update: every move\nthrough the lifecycle is its own action, because each one does more\nthan set a column.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"seller created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"slug":{"type":"string","description":"Derived from the name when omitted."},"contact_email":{"type":"string","nullable":true},"billing_email":{"type":"string","nullable":true},"about":{"type":"string","nullable":true},"tax_remittance":{"type":"string","enum":["seller","platform"]},"payouts_schedule_interval":{"type":"string","enum":["daily","weekly","biweekly","monthly","manual"],"nullable":true},"minimum_payout_amount":{"type":"string","nullable":true}}}}}}}},"/api/v3/admin/sellers/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"get":{"summary":"Get a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single seller, including its settlement and tax configuration.\n\n**Required scope:** `read_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"seller found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}},"404":{"description":"seller not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates the seller's profile and the settlement configuration the\noperator owns. A `status` sent here is ignored — use the lifecycle\nactions.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"seller address written inline","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"billing_email":{"type":"string","nullable":true},"payouts_schedule_interval":{"type":"string","enum":["daily","weekly","biweekly","monthly","manual"],"nullable":true},"minimum_payout_amount":{"type":"string","nullable":true},"holiday_mode_until":{"type":"string","format":"date-time","nullable":true},"logo":{"type":"string","nullable":true,"description":"ActiveStorage signed id of a direct-uploaded file. Send `null` to remove the attachment, or omit the key to leave it alone. Same for `square_logo` and `cover_photo`."},"square_logo":{"type":"string","nullable":true},"cover_photo":{"type":"string","nullable":true},"billing_address":{"type":"object","description":"The seller's own address, written inline. There is no `billing_address_id` — an address belongs to whoever it was created for, so it is never referenced by id here.","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"company":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"phone":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"},"state_name":{"type":"string"},"label":{"type":"string"}}},"returns_address":{"type":"object","description":"The seller's own address, written inline. There is no `billing_address_id` — an address belongs to whoever it was created for, so it is never referenced by id here.","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"company":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"phone":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"},"state_name":{"type":"string"},"label":{"type":"string"}}}}}}}}},"delete":{"summary":"Delete a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the seller. Their products are kept and left without a\nseller rather than deleted — what happens to a departed seller's\ncatalog is the operator's decision.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"seller deleted"}}}},"/api/v3/admin/sellers/{id}/invite":{"parameters":[{"name":"id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"post":{"summary":"Invite someone to run a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Sends an invitation to the seller's own team and moves the seller to\n`invited`. The person becomes a member when they accept, and can then\nsign in to the seller panel.\n\n`role_id` must name a role this seller owns; omit it for the seller's\nown admin role. Re-inviting is allowed — an invitation expires, or the\nfirst one goes to the wrong address.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"invitation sent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string"},"role_id":{"type":"string","nullable":true}}}}}}}},"/api/v3/admin/sellers/{id}/approve":{"parameters":[{"name":"id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"patch":{"summary":"Approve a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Lets the seller sell. This is also the way back for one that was\nsuspended or turned down, and it clears any holiday along with the\nsuspension.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"seller approved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}},"422":{"description":"seller cannot be approved from its current status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/sellers/{id}/suspend":{"parameters":[{"name":"id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"patch":{"summary":"Suspend a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Stops a trading seller from selling. Their catalog and history stay,\nand approving reinstates them. Use this rather than `reject` for a\nseller already on the marketplace — it says something different, and\nit can be undone.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"seller suspended","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}}}},"/api/v3/admin/sellers/{id}/reject":{"parameters":[{"name":"id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"patch":{"summary":"Reject a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Turns down an applicant who never traded. A seller already selling is\nsuspended instead; rejecting one is refused.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"seller rejected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}}}},"/api/v3/admin/stock_levels/bulk_upsert":{"post":{"summary":"Bulk-upsert stock levels","tags":["Stock"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Sets stock levels for many (variant, location) pairs at once — what a\nwarehouse or ERP feed posts on a schedule.\n\nEach row names its variant and stock location by Spree id\n(`variant_id`, `stock_location_id`).\n\nA row carries either `count_on_hand` — the absolute level the external\nsystem reports — or `adjustment`, a relative change for feeds that\nreport movements instead. Every change is written as a stock movement,\nso a merchant can still see why a figure moved.\n\nThe response carries `stock_level_count`: how many rows moved a shelf.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"stock levels updated","content":{"application/json":{}}},"422":{"description":"row is missing a level","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["stock_levels"],"properties":{"stock_levels":{"type":"array","items":{"type":"object","required":["variant_id","stock_location_id"],"properties":{"variant_id":{"type":"string"},"stock_location_id":{"type":"string"},"count_on_hand":{"type":"integer","nullable":true},"adjustment":{"type":"integer","nullable":true},"backorderable":{"type":"boolean","nullable":true}}}}}}}}}}},"/api/v3/admin/stock_movements":{"get":{"summary":"List stock movements","tags":["Stock Movements"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the stock ledger, newest first. Every row says what happened to\nstock (`kind`) and carries a direct reference to what caused it, so a\nmerchant can answer \"why is this number what it is?\" from the data.\n\nKinds are `received` (goods arrived), `allocated` (stock promised to a\nplaced order), `shipped` (promised stock left), `released` (a promise\nwithdrawn) and `adjusted` (a manual correction, which always carries a\n`reason`).\n\nMovements are immutable — reversing one means writing its counterpart\nthrough the resource that caused it, which is why there is no create,\nupdate or delete here.\n\nFilter with Ransack predicates such as `q[kind_eq]`,\n`q[stock_level_id_eq]`, `q[order_id_eq]`, `q[fulfillment_id_eq]` or\n`q[created_at_gteq]`.\n\n`kind` is null on rows written before Spree 6.0 until\n`spree:migrate_stock_movements_to_typed_rows` has run.\n\n\n**Required scope:** `read_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[kind_eq]","in":"query","required":false,"description":"Filter by kind ('received', 'allocated', 'shipped', 'released', 'adjusted')","schema":{"type":"string"}},{"name":"q[stock_level_id_eq]","in":"query","required":false,"description":"Filter by stock level, e.g. sl_1234567890","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"stock movements found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StockMovement"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/stock_movements/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Stock movement ID","schema":{"type":"string"}}],"get":{"summary":"Get a stock movement","tags":["Stock Movements"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single stock movement by prefixed ID.\n\n**Required scope:** `read_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"stock movement found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockMovement"}}}},"404":{"description":"stock movement not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"schemas":{"PaginationMeta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"count":{"type":"integer","description":"Total number of records"},"pages":{"type":"integer","description":"Total number of pages"},"from":{"type":"integer","description":"Index of first record on this page"},"to":{"type":"integer","description":"Index of last record on this page"},"in":{"type":"integer","description":"Number of records on this page"},"previous":{"type":"integer","nullable":true,"description":"Previous page number"},"next":{"type":"integer","nullable":true,"description":"Next page number"}},"required":["page","limit","count","pages","from","to","in"]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","description":"Field-specific validation errors","nullable":true}},"required":["code","message"]}},"required":["error"]},"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"]},"ImportSchemaField":{"type":"object","description":"A canonical column of an import type, including per-store custom field columns","properties":{"name":{"type":"string","description":"Canonical field name used in mappings"},"label":{"type":"string","description":"Human-readable label"},"required":{"type":"boolean","description":"Whether the field must be mapped before processing"}},"required":["name","label","required"]},"CheckoutRequirement":{"type":"object","properties":{"step":{"type":"string","description":"Checkout step this requirement belongs to"},"field":{"type":"string","description":"Field that needs to be satisfied"},"message":{"type":"string","description":"Human-readable requirement message"}},"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"},"message":{"type":"string","description":"Human-readable warning message"},"line_item_id":{"type":"string","nullable":true,"description":"Prefixed line item ID (when applicable)"},"variant_id":{"type":"string","nullable":true,"description":"Prefixed variant ID (when applicable)"},"item_index":{"type":"integer","nullable":true,"description":"Position in the submitted items array, for warnings raised while applying a batch of item changes"}},"required":["code","message"]},"FulfillmentManifestItem":{"type":"object","description":"An item within a fulfillment — which line item and how many units are in this fulfillment","properties":{"item_id":{"type":"string","description":"Line item ID"},"variant_id":{"type":"string","description":"Variant ID"},"quantity":{"type":"integer","description":"Quantity in this fulfillment"}},"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"},"name":{"type":"string","description":"Role name"}},"required":["id","name"]},"AdminUserStore":{"type":"object","description":"A store the staff member can access through a role assignment","properties":{"id":{"type":"string","description":"Prefixed store ID"},"name":{"type":"string","description":"Store name"},"code":{"type":"string","description":"Store code"}},"required":["id","name","code"]},"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"},"type":{"type":"string","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 — null for actions like `free_shipping`)","properties":{"type":{"type":"string","description":"Wire shorthand for the calculator subclass"},"label":{"type":"string"},"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 — the variant added to the order and how many","properties":{"variant_id":{"type":"string"},"quantity":{"type":"integer"}},"required":["variant_id","quantity"]},"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"]},"Address":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string","nullable":true},"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_code":{"type":"string"},"state_text":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"quick_checkout":{"type":"boolean"},"is_default_billing":{"type":"boolean"},"is_default_shipping":{"type":"boolean"},"state_abbr":{"type":"string","nullable":true},"country_iso":{"type":"string"},"state_name":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"latitude":{"type":"number","nullable":true},"longitude":{"type":"number","nullable":true},"customer_id":{"type":"string","nullable":true},"owner_id":{"type":"string","nullable":true},"owner_type":{"type":"string","nullable":true}},"required":["id","label","first_name","last_name","full_name","address1","address2","postal_code","city","phone","company","country_name","country_code","state_text","state_code","quick_checkout","is_default_billing","is_default_shipping","state_abbr","country_iso","state_name","metadata","created_at","updated_at","latitude","longitude","customer_id","owner_id","owner_type"],"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},"selected_locale":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"avatar_url":{"type":"string","nullable":true},"roles":{"type":"array","items":{"$ref":"#/components/schemas/AdminUserRoleAssignment"}},"stores":{"type":"array","items":{"$ref":"#/components/schemas/AdminUserStore"}}},"required":["id","email","first_name","last_name","full_name","selected_locale","created_at","updated_at","avatar_url","roles","stores"],"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},"channel_id":{"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","channel_id","plaintext_token","created_by_email"],"x-typelizer":true},"AppliedPromotion":{"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"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","promotion_id","name","description","code","amount","display_amount","created_at","updated_at"],"x-typelizer":true},"Cart":{"type":"object","properties":{"id":{"type":"string"},"market_id":{"type":"string","nullable":true},"channel_id":{"type":"string","nullable":true},"preferred_stock_location_id":{"type":"string","nullable":true},"company_id":{"type":"string","nullable":true},"company_name":{"type":"string","nullable":true},"po_number_required":{"type":"boolean"},"po_document_filename":{"type":"string","nullable":true},"po_document_byte_size":{"type":"number","nullable":true},"number":{"type":"string"},"token":{"type":"string"},"email":{"type":"string","nullable":true},"customer_note":{"type":"string","nullable":true},"po_number":{"type":"string","nullable":true},"currency":{"type":"string"},"locale":{"type":"string","nullable":true},"total_quantity":{"type":"number"},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/CartWarning"}},"coupon_code":{"type":"string","nullable":true},"item_total":{"type":"string","nullable":true},"display_item_total":{"type":"string","nullable":true},"adjustment_total":{"type":"string","nullable":true},"display_adjustment_total":{"type":"string","nullable":true},"discount_total":{"type":"string","nullable":true},"display_discount_total":{"type":"string","nullable":true},"tax_total":{"type":"string","nullable":true},"display_tax_total":{"type":"string","nullable":true},"included_tax_total":{"type":"string","nullable":true},"display_included_tax_total":{"type":"string","nullable":true},"additional_tax_total":{"type":"string","nullable":true},"display_additional_tax_total":{"type":"string","nullable":true},"total":{"type":"string","nullable":true},"display_total":{"type":"string","nullable":true},"gift_card_total":{"type":"string","nullable":true},"display_gift_card_total":{"type":"string","nullable":true},"amount_due":{"type":"string","nullable":true},"display_amount_due":{"type":"string","nullable":true},"delivery_total":{"type":"string","nullable":true},"display_delivery_total":{"type":"string","nullable":true},"fee_total":{"type":"string","nullable":true},"display_fee_total":{"type":"string","nullable":true},"store_credit_total":{"type":"string","nullable":true},"display_store_credit_total":{"type":"string","nullable":true},"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"}},"order_minimum":{"type":"number","nullable":true},"order_minimum_shortfall":{"type":"number","nullable":true},"below_order_minimum":{"type":"boolean","nullable":true},"freight_summary":{"allOf":[{"$ref":"#/components/schemas/FreightSummary"}],"nullable":true},"shipping_eq_billing_address":{"type":"boolean"},"items":{"type":"array","items":{"$ref":"#/components/schemas/LineItem"}},"billing_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"shipping_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"market":{"allOf":[{"$ref":"#/components/schemas/Market"}],"nullable":true},"completed_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"applied_promotions":{"type":"array","items":{"$ref":"#/components/schemas/AppliedPromotion"}}},"required":["id","market_id","channel_id","preferred_stock_location_id","company_id","company_name","po_number_required","po_document_filename","po_document_byte_size","number","token","email","customer_note","po_number","currency","locale","total_quantity","warnings","coupon_code","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","fee_total","display_fee_total","store_credit_total","display_store_credit_total","covered_by_store_credit","current_step","completed_steps","requirements","order_minimum","order_minimum_shortfall","below_order_minimum","freight_summary","shipping_eq_billing_address","items","billing_address","shipping_address","market","completed_at","created_at","updated_at","applied_promotions"],"x-typelizer":true},"CatalogAssignment":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"catalog_id":{"type":"string"},"assignable_type":{"type":"string"},"assignable_id":{"type":"string"},"assignable_name":{"type":"string","nullable":true}},"required":["id","created_at","catalog_id","assignable_type","assignable_id","assignable_name"],"x-typelizer":true},"CatalogOrderMinimum":{"type":"object","properties":{"id":{"type":"string"},"currency":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"amount":{"type":"string"},"display_amount":{"type":"string"}},"required":["id","currency","created_at","updated_at","amount","display_amount"],"x-typelizer":true},"CatalogPrice":{"type":"object","properties":{"id":{"type":"string","nullable":true},"label":{"type":"string","nullable":true},"sku":{"type":"string","nullable":true},"currency":{"type":"string"},"source":{"type":"string"},"break_count":{"type":"number"},"amount":{"type":"string"},"display_amount":{"type":"string"},"tiers":{"type":"array","items":{"$ref":"#/components/schemas/CatalogPriceTier"}}},"required":["id","label","sku","currency","source","break_count","amount","display_amount","tiers"],"x-typelizer":true},"CatalogPriceTier":{"type":"object","properties":{"min_quantity":{"type":"number"},"display_amount":{"type":"string"},"amount":{"type":"string"}},"required":["min_quantity","display_amount","amount"],"x-typelizer":true},"CatalogProduct":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"thumbnail_url":{"type":"string","nullable":true},"quantity_rule":{"allOf":[{"$ref":"#/components/schemas/CatalogProductTerm"}],"nullable":true},"catalog_variants":{"type":"array","items":{"$ref":"#/components/schemas/CatalogPrice"}}},"required":["id","name","thumbnail_url"],"x-typelizer":true},"CatalogProductTerm":{"type":"object","properties":{"id":{"type":"string"},"product_id":{"type":"string"},"product_name":{"type":"string","nullable":true},"minimum_order_quantity":{"type":"number","nullable":true},"order_multiple":{"type":"number","nullable":true},"mixed":{"type":"boolean"}},"required":["id","product_id","product_name","minimum_order_quantity","order_multiple","mixed"],"x-typelizer":true},"CatalogQuantityRule":{"type":"object","properties":{"id":{"type":"string"},"minimum_order_quantity":{"type":"number","nullable":true},"order_multiple":{"type":"number","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"variant_id":{"type":"string","nullable":true},"variant_sku":{"type":"string","nullable":true},"product_name":{"type":"string","nullable":true},"options_text":{"type":"string","nullable":true}},"required":["id","minimum_order_quantity","order_multiple","created_at","updated_at","variant_id","variant_sku","product_name","options_text"],"x-typelizer":true},"Catalog":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"active":{"type":"boolean"},"position":{"type":"number","nullable":true},"metadata":{"type":"object","nullable":true},"minimum_order_quantity":{"type":"number","nullable":true},"order_multiple":{"type":"number","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"products_count":{"type":"number"},"pricing_strategy":{"type":"string"},"order_minimums":{"type":"array","items":{"$ref":"#/components/schemas/CatalogOrderMinimum"}},"price_list":{"$ref":"#/components/schemas/PriceList"},"assignments":{"type":"array","items":{"$ref":"#/components/schemas/CatalogAssignment"}}},"required":["id","name","description","active","position","metadata","minimum_order_quantity","order_multiple","created_at","updated_at","products_count","pricing_strategy"],"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"}},"external_references":{"type":"object"},"translations":{"type":"object"},"metadata":{"type":"object"},"pretty_name":{"type":"string"},"lft":{"type":"number"},"rgt":{"type":"number"},"products_count":{"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","external_references","metadata","pretty_name","lft","rgt","products_count","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"},"storefront_access":{"type":"string"},"guest_checkout":{"type":"boolean"},"preferred_order_routing_strategy":{"type":"string","nullable":true},"preferred_storefront_access":{"type":"string","nullable":true},"preferred_guest_checkout":{"type":"boolean","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"stock_location_ids":{"type":"array","items":{"type":"string"}},"default_catalog_id":{"type":"string","nullable":true}},"required":["id","name","code","active","default","storefront_access","guest_checkout","preferred_order_routing_strategy","preferred_storefront_access","preferred_guest_checkout","created_at","updated_at","stock_location_ids","default_catalog_id"],"x-typelizer":true},"ClaimLineItem":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"send_replacement":{"type":"boolean"},"description":{"type":"string","nullable":true},"refund_amount":{"type":"string"},"paid_amount":{"type":"string"},"display_refund_amount":{"type":"string"},"variant_id":{"type":"string","nullable":true},"replacement_variant_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"variant":{"$ref":"#/components/schemas/Variant"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"replacement_variant":{"$ref":"#/components/schemas/Variant"}},"required":["id","quantity","send_replacement","description","refund_amount","paid_amount","display_refund_amount","variant_id","replacement_variant_id","line_item_id","created_at","updated_at"],"x-typelizer":true},"ClaimReason":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"can_be_deleted":{"type":"boolean"}},"required":["id","name","active","created_at","updated_at","can_be_deleted"],"x-typelizer":true},"Claim":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"status":{"type":"string"},"resolution":{"type":"string","nullable":true},"order_id":{"type":"string","nullable":true},"reason_id":{"type":"string","nullable":true},"refund_total":{"type":"string"},"display_refund_total":{"type":"string"},"approved_at":{"type":"string","nullable":true},"resolved_at":{"type":"string","nullable":true},"denied_at":{"type":"string","nullable":true},"canceled_at":{"type":"string","nullable":true},"reason":{"$ref":"#/components/schemas/ClaimReason"},"claim_line_items":{"type":"array","items":{"$ref":"#/components/schemas/ClaimLineItem"}},"memo":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"created_by_id":{"type":"string","nullable":true},"order":{"$ref":"#/components/schemas/Order"},"refunds":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}}},"required":["id","number","status","resolution","order_id","reason_id","refund_total","display_refund_total","approved_at","resolved_at","denied_at","canceled_at","memo","metadata","created_at","updated_at","created_by_id"],"x-typelizer":true},"CollectionRule":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"value":{"type":"string","nullable":true},"match_policy":{"type":"string"}},"required":["id","type","value","match_policy"],"x-typelizer":true},"Collection":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"permalink":{"type":"string"},"position":{"type":"number"},"sort_order":{"type":"string"},"meta_title":{"type":"string","nullable":true},"meta_description":{"type":"string","nullable":true},"meta_keywords":{"type":"string","nullable":true},"products_count":{"type":"number"},"description":{"type":"string"},"description_html":{"type":"string"},"image_url":{"type":"string","nullable":true},"square_image_url":{"type":"string","nullable":true},"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"translations":{"type":"object"},"automatic":{"type":"boolean"},"rules_match_policy":{"type":"string"},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"rules":{"type":"array","items":{"$ref":"#/components/schemas/CollectionRule"}}},"required":["id","name","permalink","position","sort_order","meta_title","meta_description","meta_keywords","products_count","description","description_html","image_url","square_image_url","automatic","rules_match_policy","metadata","created_at","updated_at"],"x-typelizer":true},"CommissionLine":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"currency":{"type":"string"},"taxability_reason":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"rate":{"type":"string"},"tax_rate":{"type":"string"},"amount":{"type":"string"},"tax_amount":{"type":"string"},"total":{"type":"string"},"display_amount":{"type":"string"},"display_tax_amount":{"type":"string"},"display_total":{"type":"string"},"order_id":{"type":"string"},"seller_id":{"type":"string"},"line_item_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true},"commission_rate_id":{"type":"string","nullable":true},"seller_name":{"type":"string","nullable":true},"commission_rate":{"$ref":"#/components/schemas/CommissionRate"}},"required":["id","kind","currency","taxability_reason","country_code","state_code","created_at","updated_at","rate","tax_rate","amount","tax_amount","total","display_amount","display_tax_amount","display_total","order_id","seller_id","line_item_id","fulfillment_id","commission_rate_id","seller_name"],"x-typelizer":true},"CommissionRate":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"code":{"type":"string","nullable":true},"enabled":{"type":"boolean"},"position":{"type":"number"},"kind":{"type":"string"},"tax_inclusive":{"type":"boolean"},"include_shipping":{"type":"boolean"},"metadata":{"type":"object","nullable":true},"deleted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"value":{"type":"string"},"commission_tax_rate":{"type":"string","nullable":true},"amounts":{"type":"object"},"bounds":{"type":"object"},"global":{"type":"boolean"},"rules":{"type":"array","items":{"$ref":"#/components/schemas/CommissionRule"}}},"required":["id","name","code","enabled","position","kind","tax_inclusive","include_shipping","metadata","deleted_at","created_at","updated_at","value","commission_tax_rate","amounts","bounds","global","rules"],"x-typelizer":true},"CommissionRule":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"commission_rate_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"object"},"product_ids":{"type":"array","items":{"type":"string"}}},"required":["id","created_at","updated_at","type","commission_rate_id","preferences","preference_schema"],"x-typelizer":true},"CompanyInvitation":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"expires_at":{"type":"string","nullable":true},"company_id":{"type":"string"},"status":{"type":"string"},"accepted_at":{"type":"string","nullable":true},"revoked_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","email","expires_at","company_id","status","accepted_at","revoked_at","created_at","updated_at"],"x-typelizer":true},"CompanyMembership":{"type":"object","properties":{"id":{"type":"string"},"company_id":{"type":"string"},"customer_id":{"type":"string"},"email":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","company_id","customer_id","email","created_at","updated_at"],"x-typelizer":true},"Company":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string"},"po_number_required":{"type":"boolean"},"parent_id":{"type":"string","nullable":true},"ancestors":{"type":"object"},"external_references":{"type":"object"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"children_count":{"type":"number"},"members_count":{"type":"number"},"children":{"type":"array","items":{"$ref":"#/components/schemas/Company"}},"addresses":{"type":"array","items":{"$ref":"#/components/schemas/Address"}},"memberships":{"type":"array","items":{"$ref":"#/components/schemas/CompanyMembership"}}},"required":["id","name","kind","po_number_required","parent_id","ancestors","external_references","metadata","created_at","updated_at","children_count","members_count"],"x-typelizer":true},"ConsentRecord":{"type":"object","properties":{"id":{"type":"string"},"purpose":{"type":"string"},"source":{"type":"string"},"accepted":{"type":"boolean"},"email":{"type":"string","nullable":true},"ip_address":{"type":"string","nullable":true},"created_at":{"type":"string"},"recorded_at":{"type":"string","nullable":true},"documents":{"type":"object"}},"required":["id","purpose","source","accepted","email","ip_address","created_at","recorded_at","documents"],"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},"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"},"searchable":{"type":"boolean"},"sortable":{"type":"boolean"},"filter_key":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","namespace","key","label","field_type","resource_type","storefront_visible","searchable","sortable","filter_key","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"},"email_marketing_consent_updated_at":{"type":"string","nullable":true},"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},"newsletter_subscriber":{"allOf":[{"$ref":"#/components/schemas/NewsletterSubscriber"}],"nullable":true},"customer_groups":{"type":"array","items":{"$ref":"#/components/schemas/CustomerGroup"}},"failed_attempts":{"type":"number"},"metadata":{"type":"object"},"email_marketing_consent_source":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"anonymized_at":{"type":"string","nullable":true},"anonymized":{"type":"boolean"},"tags":{"type":"array","items":{"type":"string"}},"internal_note":{"type":"string","nullable":true},"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_group_ids":{"type":"array","items":{"type":"string"}},"companies":{"type":"array","items":{"$ref":"#/components/schemas/Company"}}},"required":["id","email","first_name","last_name","phone","accepts_email_marketing","email_marketing_consent_updated_at","full_name","available_store_credit_total","display_available_store_credit_total","failed_attempts","metadata","email_marketing_consent_source","created_at","updated_at","anonymized_at","anonymized","tags","internal_note","internal_note_html","default_billing_address_id","default_shipping_address_id","orders_count","total_spent","display_total_spent","last_order_completed_at","customer_group_ids"],"x-typelizer":true},"DataRequest":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"kind":{"type":"string"},"status":{"type":"string"},"requested_at":{"type":"string","nullable":true},"completed_at":{"type":"string","nullable":true},"expires_at":{"type":"string","nullable":true},"email":{"type":"string"},"error_message":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"customer_id":{"type":"string","nullable":true},"requested_by_id":{"type":"string","nullable":true},"customer":{"$ref":"#/components/schemas/Customer"}},"required":["id","number","kind","status","requested_at","completed_at","expires_at","email","error_message","created_at","updated_at","customer_id","requested_by_id"],"x-typelizer":true},"DeliveryMethodRule":{"type":"object","properties":{"id":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"object"},"product_ids":{"type":"array","items":{"type":"string"}}},"required":["id","active","created_at","updated_at","type","preferences","preference_schema","product_ids"],"x-typelizer":true},"DeliveryMethod":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"code":{"type":"string","nullable":true},"estimated_transit_business_days_min":{"type":"number","nullable":true},"estimated_transit_business_days_max":{"type":"number","nullable":true},"digital":{"type":"boolean"},"pickup":{"type":"boolean"},"pickup_point":{"type":"boolean"},"admin_name":{"type":"string","nullable":true},"fulfillment_provider":{"type":"string"},"pickup_point_provider":{"type":"string","nullable":true},"rate_provider":{"type":"string","nullable":true},"storefront_visible":{"type":"boolean"},"tracking_url":{"type":"string","nullable":true},"markup_flat":{"type":"string","nullable":true},"markup_percent":{"type":"string","nullable":true},"available_to_sellers":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"deleted_at":{"type":"string"},"seller_id":{"type":"string","nullable":true},"seller_name":{"type":"string","nullable":true},"services":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryMethodService"}},"rules":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryMethodRule"}},"tax_category_id":{"type":"string","nullable":true},"delivery_profile_id":{"type":"string"},"delivery_origin_group_id":{"type":"string","nullable":true},"delivery_zone_id":{"type":"string","nullable":true},"stock_location_ids":{"type":"array","items":{"type":"string"}},"calculator_type":{"type":"string","nullable":true},"calculator_preferences":{"type":"object","nullable":true}},"required":["id","name","code","estimated_transit_business_days_min","estimated_transit_business_days_max","digital","pickup","pickup_point","admin_name","fulfillment_provider","pickup_point_provider","rate_provider","storefront_visible","tracking_url","markup_flat","markup_percent","available_to_sellers","created_at","updated_at","deleted_at","seller_id","seller_name","services","rules","tax_category_id","delivery_profile_id","delivery_origin_group_id","delivery_zone_id","stock_location_ids","calculator_type","calculator_preferences"],"x-typelizer":true},"DeliveryMethodService":{"type":"object","properties":{"id":{"type":"string"},"carrier":{"type":"string"},"service":{"type":"string"},"label":{"type":"string","nullable":true},"markup_flat":{"type":"string","nullable":true},"markup_percent":{"type":"string","nullable":true},"position":{"type":"number"}},"required":["id","carrier","service","label","markup_flat","markup_percent","position"],"x-typelizer":true},"DeliveryOriginGroup":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","nullable":true},"position":{"type":"number","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivery_profile_id":{"type":"string"},"stock_location_ids":{"type":"array","items":{"type":"string"}},"delivery_zones_count":{"type":"number"},"delivery_methods_count":{"type":"number"}},"required":["id","name","position","created_at","updated_at","delivery_profile_id","stock_location_ids","delivery_zones_count","delivery_methods_count"],"x-typelizer":true},"DeliveryProfile":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"default":{"type":"boolean"},"position":{"type":"number","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"kind":{"type":"string"},"digital":{"type":"boolean"},"offers_pickup":{"type":"boolean"},"offers_shipping":{"type":"boolean"},"stock_location_ids":{"type":"array","items":{"type":"string"}},"origin_groups":{"type":"object"},"products_count":{"type":"number"},"delivery_methods_count":{"type":"number"},"delivery_zones_count":{"type":"number"}},"required":["id","name","default","position","created_at","updated_at","kind","digital","offers_pickup","offers_shipping","stock_location_ids","origin_groups","products_count","delivery_methods_count","delivery_zones_count"],"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"},"carrier":{"type":"string","nullable":true},"service_level":{"type":"string","nullable":true},"estimated_delivery_date":{"type":"string","nullable":true},"unpriced":{"type":"boolean"},"freight_summary":{"allOf":[{"$ref":"#/components/schemas/FreightSummary"}],"nullable":true},"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"},"metadata":{"type":"object","nullable":true},"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","carrier","service_level","estimated_delivery_date","unpriced","freight_summary","display_cost","display_total","display_additional_tax_total","display_included_tax_total","display_tax_total","metadata","created_at","updated_at"],"x-typelizer":true},"Delivery":{"type":"object","properties":{"id":{"type":"string"},"tracking_number":{"type":"string"},"carrier":{"type":"string","nullable":true},"carrier_name":{"type":"string","nullable":true},"service":{"type":"string","nullable":true},"status":{"type":"string"},"tracking_url":{"type":"string","nullable":true},"estimated_delivery_at":{"type":"string","nullable":true},"delivered_at":{"type":"string","nullable":true},"details":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"shipping_label_id":{"type":"string","nullable":true}},"required":["id","tracking_number","carrier","carrier_name","service","status","tracking_url","estimated_delivery_at","delivered_at","details","created_at","updated_at","shipping_label_id"],"x-typelizer":true},"DeliveryZoneMember":{"type":"object","properties":{"id":{"type":"string"},"member_type":{"type":"string"},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"postal_code_prefix":{"type":"string","nullable":true},"postal_code_from":{"type":"string","nullable":true},"postal_code_to":{"type":"string","nullable":true},"country_name":{"type":"string","nullable":true},"state_name":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","member_type","country_code","state_code","postal_code_prefix","postal_code_from","postal_code_to","country_name","state_name","created_at","updated_at"],"x-typelizer":true},"DeliveryZone":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"members":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryZoneMember"}},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivery_profile_id":{"type":"string"},"delivery_origin_group_id":{"type":"string","nullable":true},"delivery_method_ids":{"type":"array","items":{"type":"string"}}},"required":["id","name","description","created_at","updated_at","delivery_profile_id","delivery_origin_group_id","delivery_method_ids"],"x-typelizer":true},"DigitalAsset":{"type":"object","properties":{"id":{"type":"string"},"variant_id":{"type":"string","nullable":true},"filename":{"type":"string","nullable":true},"content_type":{"type":"string","nullable":true},"authorized_clicks":{"type":"number","nullable":true},"authorized_days":{"type":"number","nullable":true},"byte_size":{"type":"number","nullable":true},"provider_type":{"type":"string","nullable":true},"provider_settings":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"provider_name":{"type":"string"},"download_url":{"type":"string","nullable":true},"effective_authorized_clicks":{"type":"number"},"effective_authorized_days":{"type":"number"}},"required":["id","variant_id","filename","content_type","authorized_clicks","authorized_days","byte_size","provider_type","provider_settings","created_at","updated_at","provider_name","download_url","effective_authorized_clicks","effective_authorized_days"],"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"},"expires_at":{"type":"string","nullable":true},"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","expires_at","authorizable","expired","access_limit_exceeded","created_at","updated_at"],"x-typelizer":true},"Discount":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"kind":{"type":"string"},"code":{"type":"string","nullable":true},"value_type":{"type":"string","nullable":true},"value":{"type":"string","nullable":true},"promotion_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true},"amount":{"type":"string"},"display_amount":{"type":"string"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","label","kind","code","value_type","value","promotion_id","line_item_id","fulfillment_id","amount","display_amount","metadata","created_at","updated_at"],"x-typelizer":true},"ExchangeLineItem":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"received_quantity":{"type":"number"},"resellable":{"type":"boolean"},"original_price":{"type":"string"},"new_variant_price":{"type":"string"},"price_difference":{"type":"string"},"original_variant_id":{"type":"string","nullable":true},"new_variant_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"fulfillment_item_id":{"type":"string","nullable":true},"original_variant":{"$ref":"#/components/schemas/Variant"},"new_variant":{"$ref":"#/components/schemas/Variant"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","quantity","received_quantity","resellable","original_price","new_variant_price","price_difference","original_variant_id","new_variant_id","line_item_id","fulfillment_item_id","created_at","updated_at"],"x-typelizer":true},"Exchange":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"status":{"type":"string"},"order_id":{"type":"string","nullable":true},"reason_id":{"type":"string","nullable":true},"price_difference":{"type":"string"},"display_price_difference":{"type":"string"},"approved_at":{"type":"string","nullable":true},"received_at":{"type":"string","nullable":true},"fulfilled_at":{"type":"string","nullable":true},"canceled_at":{"type":"string","nullable":true},"reason":{"$ref":"#/components/schemas/ReturnReason"},"exchange_line_items":{"type":"array","items":{"$ref":"#/components/schemas/ExchangeLineItem"}},"memo":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"stock_location_id":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true},"order":{"$ref":"#/components/schemas/Order"},"stock_location":{"$ref":"#/components/schemas/StockLocation"},"refunds":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}}},"required":["id","number","status","order_id","reason_id","price_difference","display_price_difference","approved_at","received_at","fulfilled_at","canceled_at","memo","metadata","created_at","updated_at","stock_location_id","created_by_id"],"x-typelizer":true},"Export":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"format":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string","nullable":true},"user_id":{"type":"string","nullable":true},"done":{"type":"boolean"},"store_id":{"type":"string","nullable":true},"seller_id":{"type":"string","nullable":true},"seller_name":{"type":"string","nullable":true},"filename":{"type":"string","nullable":true},"byte_size":{"type":"number","nullable":true},"download_url":{"type":"string","nullable":true}},"required":["id","number","format","created_at","updated_at","type","user_id","done","store_id","seller_id","seller_name","filename","byte_size","download_url"],"x-typelizer":true},"Fee":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"kind":{"type":"string"},"line_item_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true},"amount":{"type":"string"},"display_amount":{"type":"string"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","label","kind","line_item_id","fulfillment_id","amount","display_amount","metadata","created_at","updated_at"],"x-typelizer":true},"FreightSummaryLine":{"type":"object","properties":{"variant_id":{"type":"string","nullable":true},"sku":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"units":{"type":"number"},"cartons":{"type":"number","nullable":true},"pallets":{"type":"number","nullable":true},"units_per_carton":{"type":"number","nullable":true},"cartons_per_pallet":{"type":"number","nullable":true},"complete":{"type":"boolean"},"weight_per_carton":{"type":"string","nullable":true},"volume":{"type":"string"},"weight":{"type":"string"}},"required":["variant_id","sku","name","units","cartons","pallets","units_per_carton","cartons_per_pallet","complete","weight_per_carton","volume","weight"],"x-typelizer":true},"FreightSummary":{"type":"object","properties":{"total_units":{"type":"number"},"total_cartons":{"type":"number"},"total_pallets":{"type":"number","nullable":true},"total_volume":{"type":"string"},"total_weight":{"type":"string"},"complete":{"type":"boolean"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/FreightSummaryLine"}}},"required":["total_units","total_cartons","total_pallets","total_volume","total_weight","complete","lines"],"x-typelizer":true},"FulfillmentItem":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"status":{"type":"string"},"variant_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"options_text":{"type":"string","nullable":true}},"required":["id","quantity","status","variant_id","line_item_id","name","options_text"],"x-typelizer":true},"Fulfillment":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"tracking":{"type":"string","nullable":true},"tracking_url":{"type":"string","nullable":true},"pickup_point_data":{"type":"object","nullable":true},"selected_delivery_rate_id":{"type":"string","nullable":true},"unpriced":{"type":"boolean"},"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},"delivered_at":{"type":"string","nullable":true},"items":{"type":"array","items":{"$ref":"#/components/schemas/FulfillmentManifestItem"}},"deliveries":{"type":"array","items":{"$ref":"#/components/schemas/Delivery"}},"delivery_method":{"$ref":"#/components/schemas/DeliveryMethod"},"stock_location":{"$ref":"#/components/schemas/StockLocation"},"delivery_rates":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryRate"}},"tax_lines":{"type":"array","items":{"$ref":"#/components/schemas/TaxLine"}},"metadata":{"type":"object"},"adjustment_total":{"type":"string"},"pre_tax_amount":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"order_id":{"type":"string","nullable":true},"stock_location_id":{"type":"string","nullable":true},"documents":{"type":"object"},"labels":{"type":"array","items":{"$ref":"#/components/schemas/ShippingLabel"}},"provider_generates_labels":{"type":"boolean"},"fulfillment_items":{"type":"array","items":{"$ref":"#/components/schemas/FulfillmentItem"}},"order":{"$ref":"#/components/schemas/Order"}},"required":["id","number","tracking","tracking_url","pickup_point_data","selected_delivery_rate_id","unpriced","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","delivered_at","items","deliveries","metadata","adjustment_total","pre_tax_amount","created_at","updated_at","order_id","stock_location_id","documents","labels","provider_generates_labels"],"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"},"display_amount_used":{"type":"string"},"display_amount_remaining":{"type":"string"},"expires_at":{"type":"string","nullable":true},"redeemed_at":{"type":"string","nullable":true},"expired":{"type":"boolean"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"customer_id":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true},"customer":{"$ref":"#/components/schemas/Customer"},"created_by":{"$ref":"#/components/schemas/AdminUser"},"gift_card_batch":{"$ref":"#/components/schemas/GiftCardBatch"},"orders":{"type":"array","items":{"$ref":"#/components/schemas/Order"}}},"required":["id","code","status","currency","amount","amount_used","amount_authorized","amount_remaining","display_amount","display_amount_used","display_amount_remaining","expires_at","redeemed_at","expired","active","created_at","updated_at","customer_id","created_by_id"],"x-typelizer":true},"ImportMapping":{"type":"object","properties":{"id":{"type":"string"},"schema_field":{"type":"string"},"file_column":{"type":"string","nullable":true},"required":{"type":"boolean"}},"required":["id","schema_field","file_column","required"],"x-typelizer":true},"ImportRow":{"type":"object","properties":{"id":{"type":"string"},"row_number":{"type":"number"},"status":{"type":"string"},"validation_errors":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"import_id":{"type":"string","nullable":true},"item_type":{"type":"string","nullable":true},"item_id":{"type":"string","nullable":true},"data":{"type":"object"}},"required":["id","row_number","status","validation_errors","created_at","updated_at","import_id","item_type","item_id","data"],"x-typelizer":true},"Import":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"rows_count":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string","nullable":true},"status":{"type":"string"},"store_id":{"type":"string","nullable":true},"seller_id":{"type":"string","nullable":true},"owner_type":{"type":"string","nullable":true},"owner_id":{"type":"string","nullable":true},"user_id":{"type":"string","nullable":true},"processing_errors":{"type":"string","nullable":true},"preferred_delimiter":{"type":"string"},"price_list_id":{"type":"string","nullable":true},"seller_name":{"type":"string","nullable":true},"original_filename":{"type":"string","nullable":true},"original_byte_size":{"type":"number","nullable":true},"original_file_url":{"type":"string","nullable":true},"completed_rows_count":{"type":"number"},"failed_rows_count":{"type":"number"},"schema_fields":{"type":"array","items":{"$ref":"#/components/schemas/ImportSchemaField"}},"csv_headers":{"type":"array","items":{"type":"string"}},"sample_row":{"type":"object"},"mappings":{"type":"array","items":{"$ref":"#/components/schemas/ImportMapping"}}},"required":["id","number","rows_count","created_at","updated_at","type","status","store_id","seller_id","owner_type","owner_id","user_id","processing_errors","preferred_delimiter","price_list_id","seller_name","original_filename","original_byte_size","original_file_url","completed_rows_count","failed_rows_count","schema_fields","csv_headers","sample_row","mappings"],"x-typelizer":true},"Integration":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"group":{"type":"string","nullable":true},"preferences":{"type":"object"},"preference_schema":{"type":"object"}},"required":["id","name","active","created_at","updated_at","type","group","preferences","preference_schema"],"x-typelizer":true},"Invitation":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"status":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"expires_at":{"type":"string"},"role_id":{"type":"string"},"role_name":{"type":"string"},"inviter_email":{"type":"string"},"acceptance_url":{"type":"string"},"invitee_exists":{"type":"boolean"},"store":{"type":"object"}},"required":["id","email","status","created_at","updated_at","expires_at","role_id","role_name","inviter_email","acceptance_url","invitee_exists","store"],"x-typelizer":true},"LineItem":{"type":"object","properties":{"id":{"type":"string"},"variant_id":{"type":"string"},"seller_id":{"type":"string","nullable":true},"preorder":{"type":"boolean"},"preorder_ships_at":{"type":"string","nullable":true},"quantity":{"type":"number"},"currency":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"options_text":{"type":"string"},"price":{"type":"string"},"display_price":{"type":"string"},"total":{"type":"string"},"display_total":{"type":"string"},"adjustment_total":{"type":"string"},"display_adjustment_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"},"discount_total":{"type":"string"},"display_discount_total":{"type":"string"},"pre_tax_amount":{"type":"string"},"display_pre_tax_amount":{"type":"string"},"discounted_amount":{"type":"string"},"display_discounted_amount":{"type":"string"},"display_compare_at_amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true},"seller":{"$ref":"#/components/schemas/Seller"},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}},"digital_links":{"type":"array","items":{"$ref":"#/components/schemas/DigitalLink"}},"tax_lines":{"type":"array","items":{"$ref":"#/components/schemas/TaxLine"}},"metadata":{"type":"object"},"price_source":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"catalog_price":{"type":"string","nullable":true},"cost_price":{"type":"string","nullable":true},"tax_category_id":{"type":"string","nullable":true},"variant":{"$ref":"#/components/schemas/Variant"},"tax_category":{"$ref":"#/components/schemas/TaxCategory"}},"required":["id","variant_id","seller_id","preorder","preorder_ships_at","quantity","currency","name","slug","options_text","price","display_price","total","display_total","adjustment_total","display_adjustment_total","additional_tax_total","display_additional_tax_total","included_tax_total","display_included_tax_total","discount_total","display_discount_total","pre_tax_amount","display_pre_tax_amount","discounted_amount","display_discounted_amount","display_compare_at_amount","compare_at_amount","thumbnail_url","option_values","digital_links","metadata","price_source","created_at","updated_at","catalog_price","cost_price","tax_category_id"],"x-typelizer":true},"Market":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"currency":{"type":"string"},"default_locale":{"type":"string"},"tax_inclusive":{"type":"boolean"},"default":{"type":"boolean"},"country_codes":{"type":"array","items":{"type":"string"}},"supported_locales":{"type":"array","items":{"type":"string"}},"countries":{"type":"array","items":{"$ref":"#/components/schemas/Country"}},"tax_provider":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","name","currency","default_locale","tax_inclusive","default","country_codes","supported_locales","tax_provider","created_at","updated_at"],"x-typelizer":true},"Media":{"type":"object","properties":{"id":{"type":"string"},"product_id":{"type":"string","nullable":true},"variant_ids":{"type":"array","items":{"type":"string"}},"position":{"type":"number"},"alt":{"type":"string","nullable":true},"media_type":{"type":"string"},"focal_point_x":{"type":"number","nullable":true},"focal_point_y":{"type":"number","nullable":true},"external_video_url":{"type":"string","nullable":true},"video_provider":{"type":"string","nullable":true},"video_embed_url":{"type":"string","nullable":true},"video_url":{"type":"string","nullable":true},"poster_url":{"type":"string","nullable":true},"original_url":{"type":"string","nullable":true},"mini_url":{"type":"string","nullable":true},"small_url":{"type":"string","nullable":true},"medium_url":{"type":"string","nullable":true},"large_url":{"type":"string","nullable":true},"xlarge_url":{"type":"string","nullable":true},"og_image_url":{"type":"string","nullable":true},"external_references":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"attached":{"type":"boolean"},"filename":{"type":"string","nullable":true},"content_type":{"type":"string","nullable":true},"byte_size":{"type":"number","nullable":true},"embed_url":{"type":"string","nullable":true},"signed_id":{"type":"string","nullable":true},"viewable_id":{"type":"string","nullable":true},"download_url":{"type":"string","nullable":true},"metadata":{"type":"object"},"viewable_type":{"type":"string","nullable":true}},"required":["id","product_id","variant_ids","position","alt","media_type","focal_point_x","focal_point_y","external_video_url","video_provider","video_embed_url","video_url","poster_url","original_url","mini_url","small_url","medium_url","large_url","xlarge_url","og_image_url","external_references","created_at","updated_at","attached","filename","content_type","byte_size","embed_url","signed_id","viewable_id","download_url","metadata","viewable_type"],"x-typelizer":true},"MembershipProduct":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"thumbnail_url":{"type":"string","nullable":true}},"required":["id","name","thumbnail_url"],"x-typelizer":true},"NewsletterSubscriber":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"verified":{"type":"boolean"},"verified_at":{"type":"string","nullable":true},"customer_id":{"type":"string","nullable":true}},"required":["id","email","created_at","updated_at","verified","verified_at","customer_id"],"x-typelizer":true},"OptionType":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"number"},"kind":{"type":"string"},"translations":{"type":"object"},"metadata":{"type":"object"},"filterable":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}}},"required":["id","name","label","position","kind","metadata","filterable","created_at","updated_at"],"x-typelizer":true},"OptionValue":{"type":"object","properties":{"id":{"type":"string"},"option_type_id":{"type":"string"},"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"number"},"color_code":{"type":"string","nullable":true},"option_type_name":{"type":"string"},"option_type_label":{"type":"string"},"image_url":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"option_type":{"$ref":"#/components/schemas/OptionType"}},"required":["id","option_type_id","name","label","position","color_code","option_type_name","option_type_label","image_url","metadata","created_at","updated_at"],"x-typelizer":true},"OrderCancellationReason":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"can_be_deleted":{"type":"boolean"}},"required":["id","name","active","created_at","updated_at","can_be_deleted"],"x-typelizer":true},"OrderGroup":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"email":{"type":"string","nullable":true},"currency":{"type":"string"},"total":{"type":"string","nullable":true},"display_total":{"type":"string","nullable":true},"item_total":{"type":"string","nullable":true},"display_item_total":{"type":"string","nullable":true},"fulfillment_status":{"type":"string","nullable":true},"payment_status":{"type":"string","nullable":true},"completed_at":{"type":"string","nullable":true},"billing_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"shipping_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"orders":{"type":"array","items":{"$ref":"#/components/schemas/Order"}},"customer_id":{"type":"string","nullable":true},"cart_id":{"type":"string","nullable":true},"seller_count":{"type":"number"},"includes_first_party":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"payments":{"type":"array","items":{"$ref":"#/components/schemas/Payment"}}},"required":["id","number","email","currency","total","display_total","item_total","display_item_total","fulfillment_status","payment_status","completed_at","billing_address","shipping_address","orders","customer_id","cart_id","seller_count","includes_first_party","created_at","updated_at","payments"],"x-typelizer":true},"OrderRoutingRule":{"type":"object","properties":{"id":{"type":"string"},"position":{"type":"number"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"channel_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"object"}},"required":["id","position","active","created_at","updated_at","type","channel_id","preferences","preference_schema"],"x-typelizer":true},"Order":{"type":"object","properties":{"id":{"type":"string"},"market_id":{"type":"string","nullable":true},"withdrawal_period_ends_at":{"type":"string","nullable":true},"within_withdrawal_period":{"type":"boolean"},"cart_id":{"type":"string","nullable":true},"channel_id":{"type":"string","nullable":true},"company_id":{"type":"string","nullable":true},"company_name":{"type":"string","nullable":true},"po_document_filename":{"type":"string","nullable":true},"po_document_byte_size":{"type":"number","nullable":true},"number":{"type":"string"},"email":{"type":"string"},"customer_note":{"type":"string","nullable":true},"po_number":{"type":"string","nullable":true},"currency":{"type":"string"},"locale":{"type":"string","nullable":true},"total_quantity":{"type":"number"},"coupon_code":{"type":"string","nullable":true},"fulfillment_status":{"type":"string","nullable":true},"payment_status":{"type":"string","nullable":true},"completed_at":{"type":"string","nullable":true},"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"},"fee_total":{"type":"string"},"display_fee_total":{"type":"string"},"store_credit_total":{"type":"string"},"display_store_credit_total":{"type":"string"},"covered_by_store_credit":{"type":"boolean"},"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},"gift_card":{"allOf":[{"$ref":"#/components/schemas/GiftCard"}],"nullable":true},"market":{"allOf":[{"$ref":"#/components/schemas/Market"}],"nullable":true},"external_references":{"type":"object"},"status":{"type":"string"},"last_ip_address":{"type":"string","nullable":true},"considered_risky":{"type":"boolean"},"confirmation_delivered":{"type":"boolean"},"store_owner_notification_delivered":{"type":"boolean"},"payment_total":{"type":"string"},"display_payment_total":{"type":"string"},"metadata":{"type":"object"},"cancel_note":{"type":"string","nullable":true},"commission_amount_total":{"type":"string"},"display_commission_amount_total":{"type":"string"},"commission_tax_total":{"type":"string"},"display_commission_tax_total":{"type":"string"},"commission_total":{"type":"string"},"display_commission_total":{"type":"string"},"canceled_at":{"type":"string","nullable":true},"approved_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"preferred_stock_location_id":{"type":"string","nullable":true},"po_document_url":{"type":"string","nullable":true},"seller_id":{"type":"string","nullable":true},"seller":{"$ref":"#/components/schemas/Seller"},"order_group_id":{"type":"string","nullable":true},"tags":{"type":"array","items":{"type":"string"}},"internal_note":{"type":"string","nullable":true},"internal_note_html":{"type":"string","nullable":true},"approver_id":{"type":"string","nullable":true},"canceler_id":{"type":"string","nullable":true},"cancel_reason_id":{"type":"string","nullable":true},"cancel_reason_name":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true},"customer_id":{"type":"string","nullable":true},"applied_promotions":{"type":"array","items":{"$ref":"#/components/schemas/AppliedPromotion"}},"cart":{"$ref":"#/components/schemas/Cart"},"channel":{"$ref":"#/components/schemas/Channel"},"preferred_stock_location":{"$ref":"#/components/schemas/StockLocation"},"payment_methods":{"type":"array","items":{"$ref":"#/components/schemas/PaymentMethod"}},"customer":{"$ref":"#/components/schemas/Customer"},"approver":{"$ref":"#/components/schemas/AdminUser"},"canceler":{"$ref":"#/components/schemas/AdminUser"},"cancel_reason":{"$ref":"#/components/schemas/OrderCancellationReason"},"created_by":{"$ref":"#/components/schemas/AdminUser"},"returns":{"type":"array","items":{"$ref":"#/components/schemas/Return"}},"exchanges":{"type":"array","items":{"$ref":"#/components/schemas/Exchange"}},"claims":{"type":"array","items":{"$ref":"#/components/schemas/Claim"}},"freight_summary":{"allOf":[{"$ref":"#/components/schemas/FreightSummary"}],"nullable":true}},"required":["id","market_id","withdrawal_period_ends_at","within_withdrawal_period","cart_id","channel_id","company_id","company_name","po_document_filename","po_document_byte_size","number","email","customer_note","po_number","currency","locale","total_quantity","coupon_code","fulfillment_status","payment_status","completed_at","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","fee_total","display_fee_total","store_credit_total","display_store_credit_total","covered_by_store_credit","gift_card","market","external_references","status","last_ip_address","considered_risky","confirmation_delivered","store_owner_notification_delivered","payment_total","display_payment_total","metadata","cancel_note","commission_amount_total","display_commission_amount_total","commission_tax_total","display_commission_tax_total","commission_total","display_commission_total","canceled_at","approved_at","created_at","updated_at","preferred_stock_location_id","po_document_url","seller_id","order_group_id","tags","internal_note","internal_note_html","approver_id","canceler_id","cancel_reason_id","cancel_reason_name","created_by_id","customer_id","freight_summary"],"x-typelizer":true},"PackageType":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string"},"length":{"type":"string","nullable":true},"width":{"type":"string","nullable":true},"height":{"type":"string","nullable":true},"weight":{"type":"string","nullable":true},"max_weight":{"type":"string","nullable":true},"default":{"type":"boolean"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"dimensions_unit":{"type":"string"},"weight_unit":{"type":"string"},"volume":{"type":"string","nullable":true},"seller_id":{"type":"string","nullable":true},"seller_name":{"type":"string","nullable":true}},"required":["id","name","kind","length","width","height","weight","max_weight","default","metadata","created_at","updated_at","dimensions_unit","weight_unit","volume","seller_id","seller_name"],"x-typelizer":true},"PaymentMethod":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"type":{"type":"string"},"session_required":{"type":"boolean"},"source_required":{"type":"boolean"},"metadata":{"type":"object"},"active":{"type":"boolean"},"auto_capture":{"type":"boolean","nullable":true},"capture_method":{"type":"string","enum":["checkout","on_dispatch","manual"],"nullable":true},"resolved_capture_method":{"type":"string","enum":["checkout","on_dispatch","manual"]},"storefront_visible":{"type":"boolean"},"position":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"object"}},"required":["id","name","description","type","session_required","source_required","metadata","active","auto_capture","capture_method","resolved_capture_method","storefront_visible","position","created_at","updated_at","preferences","preference_schema"],"x-typelizer":true},"Payment":{"type":"object","properties":{"id":{"type":"string"},"payment_method_id":{"type":"string"},"response_code":{"type":"string","nullable":true},"number":{"type":"string"},"status":{"type":"string"},"amount":{"type":"string"},"display_amount":{"type":"string"},"source_type":{"type":"string","nullable":true,"enum":["credit_card","store_credit","payment_source"]},"source_id":{"type":"string","nullable":true},"source":{"anyOf":[{"$ref":"#/components/schemas/CreditCard"},{"$ref":"#/components/schemas/StoreCredit"},{"$ref":"#/components/schemas/PaymentSource"}],"nullable":true},"payment_method":{"$ref":"#/components/schemas/PaymentMethod"},"metadata":{"type":"object"},"avs_response":{"type":"string","nullable":true},"cvv_response_code":{"type":"string","nullable":true},"cvv_response_message":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"captured_amount":{"type":"string"},"order_id":{"type":"string","nullable":true},"order":{"$ref":"#/components/schemas/Order"},"refunds":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}}},"required":["id","payment_method_id","response_code","number","status","amount","display_amount","source_type","source_id","source","metadata","avs_response","cvv_response_code","cvv_response_message","created_at","updated_at","captured_amount","order_id"],"x-typelizer":true},"PaymentSource":{"type":"object","properties":{"id":{"type":"string"},"gateway_payment_profile_id":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","gateway_payment_profile_id","metadata","created_at","updated_at"],"x-typelizer":true},"Permission":{"type":"object","properties":{"key":{"type":"string"},"resource":{"type":"string"},"kind":{"type":"string"},"group":{"type":"string"},"group_label":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"}},"required":["key","resource","kind","group","group_label","label","description"],"x-typelizer":true},"Policy":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"body":{"type":"string","nullable":true},"body_html":{"type":"string","nullable":true},"updated_at":{"type":"string"},"created_at":{"type":"string"}},"required":["id","name","slug","body","body_html","updated_at","created_at"],"x-typelizer":true},"PriceAdjustmentTier":{"type":"object","properties":{"id":{"type":"string"},"min_quantity":{"type":"number"},"percentage":{"type":"string"}},"required":["id","min_quantity","percentage"],"x-typelizer":true},"PriceHistory":{"type":"object","properties":{"id":{"type":"string"},"amount":{"type":"string"},"amount_in_cents":{"type":"number"},"currency":{"type":"string"},"display_amount":{"type":"string"},"recorded_at":{"type":"string"},"variant_id":{"type":"string"},"price_id":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true},"created_at":{"type":"string"}},"required":["id","amount","amount_in_cents","currency","display_amount","recorded_at","variant_id","price_id","compare_at_amount","created_at"],"x-typelizer":true},"PriceListProduct":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"thumbnail_url":{"type":"string","nullable":true},"price_list_variants":{"type":"array","items":{"$ref":"#/components/schemas/CatalogPrice"}}},"required":["id","name","thumbnail_url"],"x-typelizer":true},"PriceList":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"status":{"type":"string"},"position":{"type":"number"},"match_policy":{"type":"string"},"adjust_compare_at":{"type":"boolean"},"starts_at":{"type":"string","nullable":true},"ends_at":{"type":"string","nullable":true},"deleted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"price_adjustment_percentage":{"type":"string","nullable":true},"automatic_pricing":{"type":"boolean"},"currently_active":{"type":"boolean"},"products_count":{"type":"number"},"prices_count":{"type":"number"},"price_adjustment_tiers":{"type":"array","items":{"$ref":"#/components/schemas/PriceAdjustmentTier"}},"price_rules":{"type":"array","items":{"$ref":"#/components/schemas/PriceRule"}}},"required":["id","name","description","status","position","match_policy","adjust_compare_at","starts_at","ends_at","deleted_at","created_at","updated_at","price_adjustment_percentage","automatic_pricing","currently_active","products_count","prices_count","price_adjustment_tiers"],"x-typelizer":true},"PriceRule":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"price_list_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"array","items":{"$ref":"#/components/schemas/PreferenceField"}},"markets":{"type":"array","items":{"$ref":"#/components/schemas/Market"}},"customer_groups":{"type":"array","items":{"$ref":"#/components/schemas/CustomerGroup"}},"channels":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}},"customers":{"type":"array","items":{"$ref":"#/components/schemas/Customer"}}},"required":["id","created_at","updated_at","type","price_list_id","preferences","preference_schema"],"x-typelizer":true},"Price":{"type":"object","properties":{"id":{"type":"string"},"amount":{"type":"string","nullable":true},"amount_in_cents":{"type":"number","nullable":true},"compare_at_amount":{"type":"string","nullable":true},"compare_at_amount_in_cents":{"type":"number","nullable":true},"currency":{"type":"string","nullable":true},"display_amount":{"type":"string","nullable":true},"display_compare_at_amount":{"type":"string","nullable":true},"price_list_id":{"type":"string","nullable":true},"min_quantity":{"type":"number"},"variant_id":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"variant":{"$ref":"#/components/schemas/Variant"}},"required":["id","amount","amount_in_cents","compare_at_amount","compare_at_amount_in_cents","currency","display_amount","display_compare_at_amount","price_list_id","min_quantity","variant_id","created_at","updated_at"],"x-typelizer":true},"ProductPublication":{"type":"object","properties":{"id":{"type":"string"},"published_at":{"type":"string","nullable":true},"unpublished_at":{"type":"string","nullable":true},"product_id":{"type":"string"},"channel_id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","published_at","unpublished_at","product_id","channel_id","created_at","updated_at"],"x-typelizer":true},"Product":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"meta_title":{"type":"string","nullable":true},"meta_description":{"type":"string","nullable":true},"meta_keywords":{"type":"string","nullable":true},"variant_count":{"type":"number"},"available_on":{"type":"string","nullable":true},"preorder_ships_at":{"type":"string","nullable":true},"purchasable":{"type":"boolean"},"preorder":{"type":"boolean"},"in_stock":{"type":"boolean"},"backorderable":{"type":"boolean"},"available":{"type":"boolean"},"description":{"type":"string","nullable":true},"description_html":{"type":"string","nullable":true},"default_variant_id":{"type":"string"},"buy_box_variant_id":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true},"tags":{"type":"array","items":{"type":"string"}},"price":{"allOf":[{"$ref":"#/components/schemas/Price"}],"nullable":true},"original_price":{"allOf":[{"$ref":"#/components/schemas/Price"}],"nullable":true},"seller_id":{"type":"string","nullable":true},"seller":{"$ref":"#/components/schemas/Seller"},"primary_media":{"$ref":"#/components/schemas/Media"},"media":{"type":"array","items":{"$ref":"#/components/schemas/Media"}},"variants":{"type":"array","items":{"$ref":"#/components/schemas/Variant"}},"default_variant":{"$ref":"#/components/schemas/Variant"},"option_types":{"type":"array","items":{"$ref":"#/components/schemas/OptionType"}},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}},"categories":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"prior_price":{"allOf":[{"$ref":"#/components/schemas/PriceHistory"}],"nullable":true},"external_references":{"type":"object"},"translations":{"type":"object"},"status":{"type":"string"},"metadata":{"type":"object"},"deleted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivery_profile_id":{"type":"string","nullable":true},"submission":{"allOf":[{"$ref":"#/components/schemas/ProductSubmission"}],"nullable":true},"seller_name":{"type":"string","nullable":true},"product_type_id":{"type":"string","nullable":true},"tax_category_id":{"type":"string","nullable":true},"digital_assets":{"type":"array","items":{"$ref":"#/components/schemas/DigitalAsset"}},"collections":{"type":"array","items":{"$ref":"#/components/schemas/Collection"}},"product_publications":{"type":"array","items":{"$ref":"#/components/schemas/ProductPublication"}},"channels":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}},"product_type":{"$ref":"#/components/schemas/ProductType"}},"required":["id","name","slug","meta_title","meta_description","meta_keywords","variant_count","available_on","preorder_ships_at","purchasable","preorder","in_stock","backorderable","available","description","description_html","default_variant_id","buy_box_variant_id","thumbnail_url","tags","price","original_price","seller_id","external_references","status","metadata","deleted_at","created_at","updated_at","delivery_profile_id","seller_name","product_type_id","tax_category_id"],"x-typelizer":true},"ProductSubmission":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"review_note":{"type":"string","nullable":true},"reviewed_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"product_id":{"type":"string"},"metadata":{"type":"object","nullable":true},"updated_at":{"type":"string"},"submitted_by_id":{"type":"string","nullable":true},"reviewed_by_id":{"type":"string","nullable":true},"reviewed_by_name":{"type":"string","nullable":true},"auto_approved":{"type":"boolean"}},"required":["id","status","review_note","reviewed_at","created_at","product_id","metadata","updated_at","submitted_by_id","reviewed_by_id","reviewed_by_name","auto_approved"],"x-typelizer":true},"ProductTypeCustomFieldDefinition":{"type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"namespace":{"type":"string"},"label":{"type":"string"},"field_type":{"type":"string","enum":["short_text","long_text","rich_text","number","boolean","json"]},"required":{"type":"boolean"},"sort_order":{"type":"number"}},"required":["id","key","namespace","label","field_type","required","sort_order"],"x-typelizer":true},"ProductType":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"translations":{"type":"object"},"products_count":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivery_profile_id":{"type":"string","nullable":true},"option_type_ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}},"custom_field_definitions":{"type":"array","items":{"$ref":"#/components/schemas/ProductTypeCustomFieldDefinition"}}},"required":["id","name","products_count","created_at","updated_at","delivery_profile_id","option_type_ids","category_ids","custom_field_definitions"],"x-typelizer":true},"PromotionAction":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"promotion_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"array","items":{"$ref":"#/components/schemas/PreferenceField"}},"calculator":{"allOf":[{"$ref":"#/components/schemas/PromotionActionCalculator"}],"nullable":true},"line_items":{"type":"array","items":{"$ref":"#/components/schemas/PromotionActionLineItem"},"nullable":true}},"required":["id","created_at","updated_at","type","promotion_id","preferences","preference_schema","calculator","line_items"],"x-typelizer":true},"PromotionRule":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"promotion_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"array","items":{"$ref":"#/components/schemas/PreferenceField"}},"product_ids":{"type":"array","items":{"type":"string"},"nullable":true},"category_ids":{"type":"array","items":{"type":"string"},"nullable":true},"customer_ids":{"type":"array","items":{"type":"string"},"nullable":true},"option_value_ids":{"type":"array","items":{"type":"string"},"nullable":true},"products":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"categories":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"customers":{"type":"array","items":{"$ref":"#/components/schemas/Customer"}},"customer_groups":{"type":"array","items":{"$ref":"#/components/schemas/CustomerGroup"}},"countries":{"type":"array","items":{"$ref":"#/components/schemas/Country"}},"channels":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}},"markets":{"type":"array","items":{"$ref":"#/components/schemas/Market"}},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}}},"required":["id","created_at","updated_at","type","promotion_id","preferences","preference_schema","product_ids","category_ids","customer_ids","option_value_ids"],"x-typelizer":true},"Promotion":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"code":{"type":"string","nullable":true},"starts_at":{"type":"string","nullable":true},"expires_at":{"type":"string","nullable":true},"usage_limit":{"type":"number","nullable":true},"match_policy":{"type":"string","enum":["all","any"]},"path":{"type":"string","nullable":true},"kind":{"type":"string","enum":["coupon_code","automatic"]},"multi_codes":{"type":"boolean"},"number_of_codes":{"type":"number","nullable":true},"code_prefix":{"type":"string","nullable":true},"promotion_category_id":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"action_ids":{"type":"array","items":{"type":"string"}},"rule_ids":{"type":"array","items":{"type":"string"}}},"required":["id","name","description","code","starts_at","expires_at","usage_limit","match_policy","path","kind","multi_codes","number_of_codes","code_prefix","promotion_category_id","metadata","created_at","updated_at","action_ids","rule_ids"],"x-typelizer":true},"RefundReason":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"can_be_deleted":{"type":"boolean"}},"required":["id","name","active","created_at","updated_at","can_be_deleted"],"x-typelizer":true},"Refund":{"type":"object","properties":{"id":{"type":"string"},"transaction_id":{"type":"string","nullable":true},"amount":{"type":"string","nullable":true},"payment_id":{"type":"string","nullable":true},"refund_reason_id":{"type":"string","nullable":true},"originator_id":{"type":"string","nullable":true},"originator_type":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"payment":{"$ref":"#/components/schemas/Payment"}},"required":["id","transaction_id","amount","payment_id","refund_reason_id","originator_id","originator_type","metadata","created_at","updated_at"],"x-typelizer":true},"ReturnLineItem":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"received_quantity":{"type":"number"},"resellable":{"type":"boolean"},"pre_tax_amount":{"type":"string"},"display_pre_tax_amount":{"type":"string"},"variant_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"fulfillment_item_id":{"type":"string","nullable":true},"variant":{"$ref":"#/components/schemas/Variant"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"line_item":{"$ref":"#/components/schemas/LineItem"}},"required":["id","quantity","received_quantity","resellable","pre_tax_amount","display_pre_tax_amount","variant_id","line_item_id","fulfillment_item_id","created_at","updated_at"],"x-typelizer":true},"ReturnReason":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"can_be_deleted":{"type":"boolean"}},"required":["id","name","active","created_at","updated_at","can_be_deleted"],"x-typelizer":true},"Return":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"status":{"type":"string"},"order_id":{"type":"string","nullable":true},"reason_id":{"type":"string","nullable":true},"refund_total":{"type":"string"},"display_refund_total":{"type":"string"},"approved_at":{"type":"string","nullable":true},"received_at":{"type":"string","nullable":true},"refunded_at":{"type":"string","nullable":true},"canceled_at":{"type":"string","nullable":true},"reason":{"$ref":"#/components/schemas/ReturnReason"},"return_line_items":{"type":"array","items":{"$ref":"#/components/schemas/ReturnLineItem"}},"memo":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"stock_location_id":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true},"refunded_total":{"type":"string"},"refundable_total":{"type":"string"},"order":{"$ref":"#/components/schemas/Order"},"stock_location":{"$ref":"#/components/schemas/StockLocation"},"refunds":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}},"documents":{"type":"object"},"labels":{"type":"array","items":{"$ref":"#/components/schemas/ShippingLabel"}},"deliveries":{"type":"array","items":{"$ref":"#/components/schemas/Delivery"}}},"required":["id","number","status","order_id","reason_id","refund_total","display_refund_total","approved_at","received_at","refunded_at","canceled_at","memo","metadata","created_at","updated_at","stock_location_id","created_by_id","refunded_total","refundable_total","documents","labels","deliveries"],"x-typelizer":true},"Role":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"permissions":{"type":"array","items":{"type":"string"}},"mutable":{"type":"boolean"},"users_count":{"type":"number"}},"required":["id","name","description","created_at","updated_at","permissions","mutable","users_count"],"x-typelizer":true},"SellerPayout":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"currency":{"type":"string"},"provider":{"type":"string"},"reference":{"type":"string","nullable":true},"metadata":{"type":"object"},"period_start":{"type":"string","nullable":true},"period_end":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"amount":{"type":"string"},"display_amount":{"type":"string"},"seller_id":{"type":"string"},"seller_name":{"type":"string","nullable":true},"transfers_count":{"type":"number"}},"required":["id","status","currency","provider","reference","metadata","period_start","period_end","created_at","updated_at","amount","display_amount","seller_id","seller_name","transfers_count"],"x-typelizer":true},"SellerRequirement":{"type":"object","properties":{"id":{"type":"string"},"position":{"type":"number"},"active":{"type":"boolean"},"required":{"type":"boolean"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"kind":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"preferences":{"type":"object"},"custom_field_definition_ids":{"type":"array","items":{"type":"string"}},"allow_multiple":{"type":"boolean"},"accepts_submissions":{"type":"boolean"},"reviewed_by_operator":{"type":"boolean"}},"required":["id","position","active","required","metadata","created_at","updated_at","kind","name","description","preferences","custom_field_definition_ids","allow_multiple","accepts_submissions","reviewed_by_operator"],"x-typelizer":true},"SellerRequirementStatus":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"required":{"type":"boolean"},"position":{"type":"number"},"status":{"type":"string"},"action_url":{"type":"string","nullable":true},"blocker":{"type":"object","nullable":true},"blocking":{"type":"boolean"},"required_policy_name":{"type":"string","nullable":true},"submission":{"$ref":"#/components/schemas/SellerRequirementSubmission"},"published_policy":{"$ref":"#/components/schemas/Policy"}},"required":["id","kind","name","description","required","position","status","action_url","blocker","blocking","required_policy_name"],"x-typelizer":true},"SellerRequirementSubmission":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"note":{"type":"string","nullable":true},"review_note":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true},"reviewed_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"seller_id":{"type":"string"},"requirement_id":{"type":"string"},"requirement_name":{"type":"string"},"file_url":{"type":"string","nullable":true},"file_name":{"type":"string","nullable":true}},"required":["id","status","note","review_note","reference","metadata","reviewed_at","created_at","updated_at","seller_id","requirement_id","requirement_name","file_url","file_name"],"x-typelizer":true},"Seller":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"about":{"type":"string"},"about_html":{"type":"string"},"logo_url":{"type":"string","nullable":true},"square_logo_url":{"type":"string","nullable":true},"cover_photo_url":{"type":"string","nullable":true},"status":{"type":"string"},"contact_email":{"type":"string","nullable":true},"billing_email":{"type":"string","nullable":true},"tax_remittance":{"type":"string"},"payouts_schedule_interval":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true},"holiday_mode_until":{"type":"string","nullable":true},"terms_accepted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"deleted_at":{"type":"string","nullable":true},"minimum_payout_amount":{"type":"string","nullable":true},"on_holiday":{"type":"boolean"},"sellable":{"type":"boolean"},"products_count":{"type":"number"},"users_count":{"type":"number"},"onboarding_progress":{"type":"object"},"onboarding_complete":{"type":"boolean"},"legal_name":{"type":"string","nullable":true},"registration_number":{"type":"string","nullable":true},"billing_address":{"$ref":"#/components/schemas/Address"},"returns_address":{"$ref":"#/components/schemas/Address"}},"required":["id","name","slug","about","about_html","logo_url","square_logo_url","cover_photo_url","status","contact_email","billing_email","tax_remittance","payouts_schedule_interval","metadata","holiday_mode_until","terms_accepted_at","created_at","updated_at","deleted_at","minimum_payout_amount","on_holiday","sellable","products_count","users_count","onboarding_progress","onboarding_complete","legal_name","registration_number"],"x-typelizer":true},"SellerTeamMember":{"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"},"avatar_url":{"type":"string","nullable":true}},"required":["id","email","first_name","last_name","full_name","created_at","updated_at","avatar_url"],"x-typelizer":true},"SellerTransfer":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"status":{"type":"string"},"currency":{"type":"string"},"provider":{"type":"string"},"reference":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"amount":{"type":"string"},"display_amount":{"type":"string"},"seller_id":{"type":"string"},"order_id":{"type":"string","nullable":true},"payout_id":{"type":"string","nullable":true},"reversed_from_id":{"type":"string","nullable":true},"refund_id":{"type":"string","nullable":true},"seller_name":{"type":"string","nullable":true},"order_number":{"type":"string","nullable":true}},"required":["id","kind","status","currency","provider","reference","metadata","created_at","updated_at","amount","display_amount","seller_id","order_id","payout_id","reversed_from_id","refund_id","seller_name","order_number"],"x-typelizer":true},"SetupTask":{"type":"object","properties":{"name":{"type":"string"},"done":{"type":"boolean"}},"required":["name","done"],"x-typelizer":true},"ShippingLabel":{"type":"object","properties":{"id":{"type":"string"},"source":{"type":"string"},"status":{"type":"string"},"carrier":{"type":"string","nullable":true},"carrier_name":{"type":"string","nullable":true},"service":{"type":"string","nullable":true},"tracking_number":{"type":"string","nullable":true},"currency":{"type":"string","nullable":true},"format":{"type":"string","nullable":true},"external_id":{"type":"string","nullable":true},"metadata":{"type":"object"},"refunded_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"owner_id":{"type":"string"},"owner_type":{"type":"string"},"cost":{"type":"string"},"display_cost":{"type":"string"},"integration_id":{"type":"string","nullable":true},"file_pending":{"type":"boolean"},"download_url":{"type":"string","nullable":true}},"required":["id","source","status","carrier","carrier_name","service","tracking_number","currency","format","external_id","metadata","refunded_at","created_at","updated_at","owner_id","owner_type","cost","display_cost","integration_id","file_pending","download_url"],"x-typelizer":true},"State":{"type":"object","properties":{"abbr":{"type":"string"},"name":{"type":"string"}},"required":["abbr","name"],"x-typelizer":true},"StockLevel":{"type":"object","properties":{"id":{"type":"string"},"count_on_hand":{"type":"number"},"backorderable":{"type":"boolean"},"stock_location_id":{"type":"string","nullable":true},"variant_id":{"type":"string","nullable":true},"external_references":{"type":"object"},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"allocated_count":{"type":"number"},"available_count":{"type":"number"},"stock_location":{"$ref":"#/components/schemas/StockLocation"},"variant":{"$ref":"#/components/schemas/Variant"}},"required":["id","count_on_hand","backorderable","stock_location_id","variant_id","external_references","metadata","created_at","updated_at","allocated_count","available_count"],"x-typelizer":true},"StockLocation":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"address1":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"country_name":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"state_text":{"type":"string","nullable":true},"pickup_ready_in_minutes":{"type":"number","nullable":true},"pickup_instructions":{"type":"string","nullable":true},"external_references":{"type":"object"},"admin_name":{"type":"string","nullable":true},"address2":{"type":"string","nullable":true},"state_name":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"active":{"type":"boolean"},"default":{"type":"boolean"},"backorderable_default":{"type":"boolean"},"propagate_all_variants":{"type":"boolean"},"kind":{"type":"string"},"pickup_enabled":{"type":"boolean"},"pickup_stock_policy":{"type":"string"},"returns_enabled":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"seller_id":{"type":"string","nullable":true},"seller_name":{"type":"string","nullable":true},"seller":{"$ref":"#/components/schemas/Seller"}},"required":["id","name","address1","city","zipcode","country_code","country_name","state_code","state_text","pickup_ready_in_minutes","pickup_instructions","external_references","admin_name","address2","state_name","phone","company","active","default","backorderable_default","propagate_all_variants","kind","pickup_enabled","pickup_stock_policy","returns_enabled","created_at","updated_at","seller_id","seller_name"],"x-typelizer":true},"StockMovement":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"kind":{"type":"string","nullable":true},"reason":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"stock_level_id":{"type":"string","nullable":true},"order_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true},"return_id":{"type":"string","nullable":true},"exchange_id":{"type":"string","nullable":true},"stock_transfer_id":{"type":"string","nullable":true}},"required":["id","quantity","kind","reason","created_at","updated_at","stock_level_id","order_id","fulfillment_id","return_id","exchange_id","stock_transfer_id"],"x-typelizer":true},"StockReservation":{"type":"object","properties":{"id":{"type":"string"},"stock_level_id":{"type":"string"},"line_item_id":{"type":"string"},"order_id":{"type":"string"},"variant_id":{"type":"string","nullable":true},"stock_location_id":{"type":"string","nullable":true},"quantity":{"type":"number"},"expires_at":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","stock_level_id","line_item_id","order_id","variant_id","stock_location_id","quantity","expires_at","active","created_at","updated_at"],"x-typelizer":true},"StockTransfer":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"reference":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"source_location_id":{"type":"string","nullable":true},"destination_location_id":{"type":"string","nullable":true},"source_location":{"$ref":"#/components/schemas/StockLocation"},"destination_location":{"$ref":"#/components/schemas/StockLocation"}},"required":["id","number","reference","metadata","created_at","updated_at","source_location_id","destination_location_id"],"x-typelizer":true},"StoreCredit":{"type":"object","properties":{"id":{"type":"string"},"amount":{"type":"string"},"amount_used":{"type":"string"},"amount_remaining":{"type":"string"},"display_amount":{"type":"string"},"display_amount_used":{"type":"string"},"display_amount_remaining":{"type":"string"},"currency":{"type":"string"},"memo":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"customer_id":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true}},"required":["id","amount","amount_used","amount_remaining","display_amount","display_amount_used","display_amount_remaining","currency","memo","metadata","created_at","updated_at","customer_id","created_by_id"],"x-typelizer":true},"Store":{"type":"object","properties":{"id":{"type":"string"},"metadata":{"type":"object"},"name":{"type":"string"},"code":{"type":"string"},"preferred_storefront_url":{"type":"string","nullable":true},"default_currency":{"type":"string"},"default_locale":{"type":"string"},"default_country_code":{"type":"string","nullable":true},"mail_from_address":{"type":"string","nullable":true},"customer_support_email":{"type":"string","nullable":true},"new_order_notifications_email":{"type":"string","nullable":true},"preferred_send_consumer_transactional_emails":{"type":"boolean"},"preferred_admin_locale":{"type":"string","nullable":true},"preferred_timezone":{"type":"string"},"preferred_weight_unit":{"type":"string"},"preferred_unit_system":{"type":"string"},"preferred_storefront_access":{"type":"string"},"preferred_guest_checkout":{"type":"boolean"},"preferred_company_field_enabled":{"type":"boolean"},"preferred_address_requires_company":{"type":"boolean"},"preferred_address_requires_phone":{"type":"boolean"},"preferred_capture_method":{"type":"string"},"preferred_track_inventory_levels":{"type":"boolean"},"preferred_stock_reservations_enabled":{"type":"boolean"},"preferred_tax_using_ship_address":{"type":"boolean"},"preferred_track_price_history":{"type":"boolean"},"preferred_show_products_without_price":{"type":"boolean"},"preferred_disable_sku_validation":{"type":"boolean"},"preferred_order_routing_strategy":{"type":"string"},"preferred_pricing_provider":{"type":"string"},"preferred_inventory_provider":{"type":"string"},"preferred_pricing_provider_failure_policy":{"type":"string"},"preferred_inventory_provider_failure_policy":{"type":"string"},"preferred_payout_provider":{"type":"string","nullable":true},"preferred_default_payouts_schedule_interval":{"type":"string"},"preferred_default_minimum_payout_amount":{"type":"number"},"preferred_document_number_format":{"type":"string"},"preferred_order_number_prefix":{"type":"string"},"preferred_order_number_suffix":{"type":"string"},"preferred_order_number_sequence_start":{"type":"number"},"preferred_limit_digital_download_count":{"type":"boolean"},"preferred_digital_asset_authorized_clicks":{"type":"number"},"preferred_limit_digital_download_days":{"type":"boolean"},"preferred_digital_asset_authorized_days":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"order_number_sequence_started":{"type":"boolean"},"url":{"type":"string"},"api_url":{"type":"string"},"setup_tasks":{"type":"array","items":{"$ref":"#/components/schemas/SetupTask"}},"supported_currencies":{"type":"array","items":{"type":"string"}},"supported_locales":{"type":"array","items":{"type":"string"}},"available_locales":{"type":"array","items":{"type":"string"}},"logo_url":{"type":"string","nullable":true},"mailer_logo_url":{"type":"string","nullable":true}},"required":["id","metadata","name","code","preferred_storefront_url","default_currency","default_locale","default_country_code","mail_from_address","customer_support_email","new_order_notifications_email","preferred_send_consumer_transactional_emails","preferred_admin_locale","preferred_timezone","preferred_weight_unit","preferred_unit_system","preferred_storefront_access","preferred_guest_checkout","preferred_company_field_enabled","preferred_address_requires_company","preferred_address_requires_phone","preferred_capture_method","preferred_track_inventory_levels","preferred_stock_reservations_enabled","preferred_tax_using_ship_address","preferred_track_price_history","preferred_show_products_without_price","preferred_disable_sku_validation","preferred_order_routing_strategy","preferred_pricing_provider","preferred_inventory_provider","preferred_pricing_provider_failure_policy","preferred_inventory_provider_failure_policy","preferred_payout_provider","preferred_default_payouts_schedule_interval","preferred_default_minimum_payout_amount","preferred_document_number_format","preferred_order_number_prefix","preferred_order_number_suffix","preferred_order_number_sequence_start","preferred_limit_digital_download_count","preferred_digital_asset_authorized_clicks","preferred_limit_digital_download_days","preferred_digital_asset_authorized_days","created_at","updated_at","order_number_sequence_started","url","api_url","setup_tasks","supported_currencies","supported_locales","available_locales","logo_url","mailer_logo_url"],"x-typelizer":true},"TaxCategory":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"tax_code":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"is_default":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","name","tax_code","description","is_default","created_at","updated_at"],"x-typelizer":true},"TaxExemptionCertificate":{"type":"object","properties":{"id":{"type":"string"},"certificate_number":{"type":"string"},"reason_code":{"type":"string"},"status":{"type":"string"},"issuing_authority":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true},"issued_at":{"type":"string"},"expires_at":{"type":"string"},"verified_at":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"company_id":{"type":"string"},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"active":{"type":"boolean"},"lapsed":{"type":"boolean"},"can_be_deleted":{"type":"boolean"},"document_filename":{"type":"string","nullable":true},"document_byte_size":{"type":"number","nullable":true},"document_url":{"type":"string","nullable":true}},"required":["id","certificate_number","reason_code","status","issuing_authority","metadata","issued_at","expires_at","verified_at","created_at","updated_at","company_id","country_code","state_code","active","lapsed","can_be_deleted","document_filename","document_byte_size","document_url"],"x-typelizer":true},"TaxIdentifier":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"value":{"type":"string"},"validation_status":{"type":"string","nullable":true},"validation_evidence":{"type":"object","nullable":true},"source":{"type":"string","nullable":true},"validated_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"validatable":{"type":"boolean"},"customer_id":{"type":"string","nullable":true},"cart_id":{"type":"string","nullable":true},"order_id":{"type":"string","nullable":true}},"required":["id","kind","value","validation_status","validation_evidence","source","validated_at","created_at","updated_at","validatable","customer_id","cart_id","order_id"],"x-typelizer":true},"TaxLine":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"included":{"type":"boolean"},"rate":{"type":"string"},"tax_rate_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true},"fee_id":{"type":"string","nullable":true},"amount":{"type":"string"},"display_amount":{"type":"string"},"provider_id":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true},"taxability_reason":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"data":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","label","included","rate","tax_rate_id","line_item_id","fulfillment_id","fee_id","amount","display_amount","provider_id","metadata","taxability_reason","country_code","state_code","data","created_at","updated_at"],"x-typelizer":true},"TaxRate":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"included_in_price":{"type":"boolean"},"show_rate_in_label":{"type":"boolean"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"deleted_at":{"type":"string","nullable":true},"amount":{"type":"string"},"amount_percentage":{"type":"number","nullable":true},"tax_category_id":{"type":"string","nullable":true},"store_id":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true}},"required":["id","name","included_in_price","show_rate_in_label","metadata","created_at","updated_at","deleted_at","amount","amount_percentage","tax_category_id","store_id","country_code","state_code"],"x-typelizer":true},"Variant":{"type":"object","properties":{"id":{"type":"string"},"product_id":{"type":"string"},"sku":{"type":"string","nullable":true},"options_text":{"type":"string"},"track_inventory":{"type":"boolean"},"media_count":{"type":"number"},"preorder_ships_at":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true},"purchasable":{"type":"boolean"},"in_stock":{"type":"boolean"},"backorderable":{"type":"boolean"},"preorder":{"type":"boolean"},"weight":{"type":"number","nullable":true},"height":{"type":"number","nullable":true},"width":{"type":"number","nullable":true},"depth":{"type":"number","nullable":true},"minimum_order_quantity":{"type":"number","nullable":true},"order_multiple":{"type":"number","nullable":true},"purchase_unit":{"type":"string","nullable":true},"units_per_carton":{"type":"number","nullable":true},"price":{"$ref":"#/components/schemas/Price"},"original_price":{"allOf":[{"$ref":"#/components/schemas/Price"}],"nullable":true},"seller_id":{"type":"string","nullable":true},"seller":{"$ref":"#/components/schemas/Seller"},"primary_media":{"$ref":"#/components/schemas/Media"},"media":{"type":"array","items":{"$ref":"#/components/schemas/Media"}},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}},"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"prior_price":{"allOf":[{"$ref":"#/components/schemas/PriceHistory"}],"nullable":true},"external_references":{"type":"object"},"metadata":{"type":"object"},"position":{"type":"number"},"cost_price":{"type":"string","nullable":true},"cost_currency":{"type":"string","nullable":true},"barcode":{"type":"string","nullable":true},"backorder_limit":{"type":"number","nullable":true},"hs_code":{"type":"string","nullable":true},"country_of_origin":{"type":"string","nullable":true},"customs_description":{"type":"string","nullable":true},"carton_weight":{"type":"string","nullable":true},"cartons_per_pallet":{"type":"number","nullable":true},"deleted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"preorderable":{"type":"boolean"},"tax_category_id":{"type":"string","nullable":true},"weight_unit":{"type":"string","nullable":true},"dimensions_unit":{"type":"string","nullable":true},"carton_package_type_id":{"type":"string","nullable":true},"units_per_pallet":{"type":"number","nullable":true},"available_stock":{"type":"number","nullable":true},"reserved_quantity":{"type":"number"},"total_on_hand":{"type":"number","nullable":true},"product_name":{"type":"string"},"delivery_profile_id":{"type":"string","nullable":true},"prices":{"type":"array","items":{"$ref":"#/components/schemas/Price"}},"stock_levels":{"type":"array","items":{"$ref":"#/components/schemas/StockLevel"}}},"required":["id","product_id","sku","options_text","track_inventory","media_count","preorder_ships_at","thumbnail_url","purchasable","in_stock","backorderable","preorder","weight","height","width","depth","minimum_order_quantity","order_multiple","purchase_unit","units_per_carton","price","original_price","seller_id","option_values","external_references","metadata","position","cost_price","cost_currency","barcode","backorder_limit","hs_code","country_of_origin","customs_description","carton_weight","cartons_per_pallet","deleted_at","created_at","updated_at","preorderable","tax_category_id","weight_unit","dimensions_unit","carton_package_type_id","units_per_pallet","available_stock","reserved_quantity","total_on_hand","product_name","delivery_profile_id"],"x-typelizer":true},"WebhookDelivery":{"type":"object","properties":{"id":{"type":"string"},"event_name":{"type":"string"},"event_id":{"type":"string","nullable":true},"response_code":{"type":"number","nullable":true},"execution_time":{"type":"number","nullable":true},"error_type":{"type":"string","nullable":true},"request_errors":{"type":"string","nullable":true},"response_body":{"type":"string","nullable":true},"success":{"type":"boolean","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivered_at":{"type":"string","nullable":true},"payload":{"type":"object"},"webhook_endpoint_id":{"type":"string"},"webhook_endpoint_url":{"type":"string"}},"required":["id","event_name","event_id","response_code","execution_time","error_type","request_errors","response_body","success","created_at","updated_at","delivered_at","payload","webhook_endpoint_id","webhook_endpoint_url"],"x-typelizer":true},"WebhookEndpoint":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","nullable":true},"url":{"type":"string"},"active":{"type":"boolean"},"subscriptions":{"type":"array","items":{"type":"string"}},"disabled_reason":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"disabled_at":{"type":"string","nullable":true},"secret_key":{"type":"string","nullable":true},"last_delivery_at":{"type":"string","nullable":true},"recent_delivery_count":{"type":"number"},"recent_failure_count":{"type":"number"},"total_delivery_count":{"type":"number"},"successful_delivery_count":{"type":"number"},"failed_delivery_count":{"type":"number"}},"required":["id","name","url","active","subscriptions","disabled_reason","created_at","updated_at","disabled_at","secret_key","last_delivery_at","recent_delivery_count","recent_failure_count","total_delivery_count","successful_delivery_count","failed_delivery_count"],"x-typelizer":true}}}}\ No newline at end of filediff --git a/packages/dashboard-core/src/api-client.ts b/packages/dashboard-core/src/api-client.tsindex 06edfecfcf..86214445be 100644--- a/packages/dashboard-core/src/api-client.ts+++ b/packages/dashboard-core/src/api-client.ts@@ -152,13 +152,14 @@ export interface PanelApiClient {list(params?: Record<string, unknown>): Promise<{ data: PanelDeliveryProfile[] }>}/**- * The store's packaging vocabulary. Read by the variant editor to offer- * the carton a product is packed into; the panel passes `kind` through so- * only cartons are listed.+ * The packaging this panel can see: the boxes parcels ship in, the cartons+ * products are packed into, the pallets a wholesale order leaves on.+ *+ * `list` alone is enough for the variant editor's carton picker, which is+ * why the write methods are optional — a panel that only needs the picker+ * registers `list` and the packaging settings page is simply not routed.*/- packageTypes?: {- list(params?: Record<string, unknown>): Promise<{ data: PanelPackageType[] }>- }+ packageTypes?: PanelPackageTypeReads | PanelPackageTypeWrites/*** Headers a file download must carry beyond the bearer token.*@@ -286,6 +287,87 @@ export interface PanelPackageType extends PanelNamedRecord {width?: string | nullheight?: string | nulldimensions_unit?: string | null+ /** The empty package's own weight, added to every quote. */+ weight?: string | null+ max_weight?: string | null+ weight_unit?: string | null+ /** Cubic meters, derived; null until every side is measured. */+ volume?: string | null+ /** The box this owner's parcels are quoted with — one per owner. */+ default?: boolean+ /**+ * False on a row this panel may read but not change: the seller panel lists+ * the marketplace's packaging so a seller knows what they can pack into,+ * and every write against it is refused. Absent on the operator's own+ * serializer, where every row is theirs, so the page treats undefined as+ * editable.+ */+ editable?: boolean+ /** Whose packaging this is; null is the marketplace's own. */+ seller_id?: string | null+ seller_name?: string | null+ created_at?: string+ updated_at?: string+}++/**+ * Measurements written back for a package type. Every field optional: the+ * form sends the whole shape on create, and a partial one when a single+ * measurement changes.+ */+export interface PanelPackageTypeParams {+ name?: string+ /**+ * Narrow rather than `string`, because both SDKs validate the vocabulary at+ * the type level and a widened contract would not assign to either.+ */+ kind?: PanelPackageTypeKind+ length?: number | null+ width?: number | null+ height?: number | null+ dimensions_unit?: PanelPackageDimensionUnit | null+ weight?: number | null+ max_weight?: number | null+ weight_unit?: PanelPackageWeightUnit | null+ default?: boolean+ /**+ * Not nullable: both SDKs take a merge, so clearing a key is sending the+ * object without it rather than sending null.+ */+ metadata?: Record<string, unknown>+}++/**+ * Enough for the variant editor's carton picker: a panel that only needs the+ * picker registers this and never routes to the packaging settings page.+ */+export interface PanelPackageTypeReads {+ list(params?: Record<string, unknown>): Promise<{ data: PanelPackageType[]; meta?: unknown }>+}++/**+ * What the packaging settings page needs. Required rather than optional, so a+ * panel that routes to the page while registering reads only fails to+ * compile instead of rendering a page whose every write throws.+ */+export interface PanelPackageTypeWrites extends PanelPackageTypeReads {+ get(id: string): Promise<PanelPackageType>+ create(params: PanelPackageTypeCreateParams): Promise<PanelPackageType>+ update(id: string, params: PanelPackageTypeParams): Promise<PanelPackageType>+ delete?(id: string): Promise<void>+}++export type PanelPackageTypeKind = 'box' | 'envelope' | 'carton' | 'pallet' | 'container'+export type PanelPackageDimensionUnit = 'mm' | 'cm' | 'in' | 'ft'+export type PanelPackageWeightUnit = 'g' | 'kg' | 'lb' | 'oz'++/**+ * A new row must say what it is and what to call it — packaging without+ * either cannot exist, and neither SDK makes them optional.+ */+export type PanelPackageTypeCreateParams = PanelPackageTypeParams & {+ name: string+ kind: PanelPackageTypeKind}/**diff --git a/packages/dashboard-core/src/hooks/use-package-types.ts b/packages/dashboard-core/src/hooks/use-package-types.tsnew file mode 100644index 0000000000..c32a0d9c7d--- /dev/null+++ b/packages/dashboard-core/src/hooks/use-package-types.ts@@ -0,0 +1,132 @@+import type { PaginationMeta } from '@spree/dashboard-ui'+import { useQuery, useQueryClient } from '@tanstack/react-query'+import i18n from 'i18next'+import {+ getApiClient,+ type PanelPackageType,+ type PanelPackageTypeCreateParams,+ type PanelPackageTypeParams,+ type PanelPackageTypeWrites,+} from '../api-client'+import { useResourceKey, useResourceKeyBuilder } from '../lib/query-keys'+import { useResourceMutation } from './use-resource-mutation'++/**+ * The registered panel's package-type resource.+ *+ * Throws rather than answering undefined: every hook here is only reachable+ * from the packaging page, and a panel that routes to it without registering+ * the resource is misconfigured — failing at the call site says so far more+ * clearly than a handful of "cannot read property of undefined" errors.+ */+function resource() {+ const packageTypes = getApiClient().packageTypes+ if (!packageTypes) {+ throw new Error(+ '@spree/dashboard-core: this panel registered no `packageTypes` resource, so the ' ++ 'package-types page cannot load. Add one in setApiClient(), or drop the route.',+ )+ }+ return packageTypes+}++/**+ * The same resource narrowed to the writing shape.+ *+ * The narrowing is checked once here rather than at each call site: the page+ * only renders its sheets when `canWritePackageTypes()` is true, and the+ * panel's registration is what makes that so.+ */+function writableResource(): PanelPackageTypeWrites {+ const packageTypes = resource()+ if (!('create' in packageTypes)) {+ throw new Error(+ '@spree/dashboard-core: this panel registered `packageTypes` reads only, so packaging ' ++ 'cannot be written. Register get/create/update, or drop the settings route.',+ )+ }+ return packageTypes+}++export function usePackageType(id: string | undefined) {+ return useQuery({+ queryKey: useResourceKey('package-types', id ?? 'noop'),+ queryFn: () => writableResource().get(id as string),+ enabled: !!id,+ })+}++export function useCreatePackageType() {+ return useResourceMutation<PanelPackageType, Error, PanelPackageTypeCreateParams>({+ mutationFn: (params) => writableResource().create(params),+ invalidate: [['package-types'], ['panel-form-carton-package-types']],+ successMessage: i18n.t('admin.package_types.messages.added'),+ errorMessage: i18n.t('admin.errors.failed_to_create'),+ })+}++export function useUpdatePackageType(id: string) {+ return useResourceMutation<PanelPackageType, Error, PanelPackageTypeParams>({+ mutationFn: (params) => writableResource().update(id, params),+ invalidate: [['package-types'], ['package-types', id], ['panel-form-carton-package-types']],+ successMessage: i18n.t('admin.package_types.messages.updated'),+ errorMessage: i18n.t('admin.errors.failed_to_update'),+ })+}++export function useDeletePackageType() {+ const queryClient = useQueryClient()+ const buildKey = useResourceKeyBuilder()++ return useResourceMutation<void, Error, string>({+ mutationFn: (id) => {+ const remove = writableResource().delete+ if (!remove) throw new Error('This panel cannot delete package types.')+ return remove(id)+ },+ invalidate: [['package-types'], ['panel-form-carton-package-types']],+ successMessage: i18n.t('admin.package_types.messages.deleted'),+ errorMessage: i18n.t('admin.errors.failed_to_delete'),+ onSuccess: (_data, id) => {+ queryClient.removeQueries({ queryKey: buildKey('package-types', id) })+ },+ })+}++/**+ * Whether this panel's API can write packaging at all. A panel registering+ * only `list` gets the variant editor's carton picker and no settings page,+ * so the page hides everything that would write.+ */+export function canWritePackageTypes(): boolean {+ const packageTypes = getApiClient().packageTypes+ if (packageTypes === undefined) return false++ // All three, not just `create`: the page renders Edit off this answer, and+ // a plain JavaScript host can register a partial object the write shape's+ // type would have refused.+ return ['get', 'create', 'update'].every((method) => method in packageTypes)+}++/** Whether this panel's API offers deletion, which not every one does. */+export function canDeletePackageTypes(): boolean {+ const packageTypes = getApiClient().packageTypes+ return packageTypes !== undefined && 'delete' in packageTypes+}++/**+ * One page of packaging, for `ResourceTable`'s own query. Not a hook — the+ * table calls it with the search params it has already parsed.+ */+export function listPackageTypes(params: Record<string, unknown>) {+ // `owner: 'mine'` — the settings page shows what this panel's principal+ // owns, never another owner's rows. On the operator's panel every row is+ // theirs and the param is ignored; on a seller's it hides the+ // marketplace's shared packaging, which the seller reads through the+ // variant editor's carton picker instead. A mixed list read as "packaging+ // is configured" while the seller had recorded none.+ return resource().list({ ...params, owner: 'mine' }) as Promise<{+ data: PanelPackageType[]+ meta: PaginationMeta+ }>+}diff --git a/packages/dashboard-core/src/index.ts b/packages/dashboard-core/src/index.tsindex a068e7e8cf..dbe74a0236 100644--- a/packages/dashboard-core/src/index.ts+++ b/packages/dashboard-core/src/index.ts@@ -62,6 +62,7 @@ export * from './hooks/use-export'export * from './hooks/use-global-search'export * from './hooks/use-host-form'export * from './hooks/use-import'+export * from './hooks/use-package-types'export * from './hooks/use-resource-mutation'export * from './hooks/use-stock-locations'export * from './hooks/use-switch-admin-locale'@@ -104,6 +105,7 @@ export * from './lib/slot-registry'export * from './lib/table-registry'export { ensureTimestampColumns } from './lib/timestamp-columns'export * from './lib/type-labels'+export * from './pages/package-types'export * from './pages/stock-locations'// ---------------------------------------------------------------------------// Plugin facade — re-exported for convenience; same API as `/plugin` subpath@@ -128,4 +130,5 @@ export * from './providers/permission-provider'export * from './providers/sticky-header-provider'export * from './providers/store-provider'export * from './providers/tenant-provider'+export * from './schemas/package-type'export * from './schemas/stock-location'diff --git a/packages/dashboard-core/src/locales/ar.json b/packages/dashboard-core/src/locales/ar.jsonindex 112f82fb50..08e8b8944b 100644--- a/packages/dashboard-core/src/locales/ar.json+++ b/packages/dashboard-core/src/locales/ar.json@@ -624,6 +624,45 @@"name": {"label": "الاسم"},+ "package_type": {+ "name": {+ "label": "الاسم"+ },+ "kind": {+ "label": "النوع",+ "help": "الكرتونة وحدها يمكن أن تكون تغليف المنتج."+ },+ "length": {+ "label": "الطول"+ },+ "width": {+ "label": "العرض"+ },+ "height": {+ "label": "الارتفاع"+ },+ "dimensions_unit": {+ "label": "الوحدة"+ },+ "dimensions": {+ "help": "تُستخدم للوزن الحجمي للناقل وللأمتار المكعبة في فئات الشحن."+ },+ "weight": {+ "label": "الوزن فارغًا",+ "help": "التغليف نفسه، يُضاف إلى محتواه."+ },+ "max_weight": {+ "label": "أقصى وزن",+ "help": "ما يمكنه حمله."+ },+ "weight_unit": {+ "label": "الوحدة"+ },+ "default": {+ "label": "العلبة الافتراضية",+ "help": "العلبة التي تُحسب على أساسها أسعار شحن طرودك. علبة افتراضية واحدة في كل مرة."+ }+ },"number": {"label": "الرقم"},@@ -989,12 +1028,46 @@"tax_category_saved": "تم حفظ فئة الضريبة","updated": "تم التحديث"},+ "package_types": {+ "table_title": "أنواع التغليف",+ "search_placeholder": "ابحث عن تغليف",+ "empty": "لا يوجد تغليف بعد. أضف صندوق الشحن، والكراتين والمنصات التي تغادر بها طلبات الجملة.",+ "add_cta": "إضافة نوع تغليف",+ "default_badge": "افتراضي",+ "edit_sheet_title": "نوع التغليف",+ "create_description": "علبة أو كرتونة أو منصة نقالة أو حاوية تُعبأ فيها السلع.",+ "edit_description": "المنتجات المعبأة في هذه الكرتونة تتبع مقاساتها، فتعديل واحد يصحّحها جميعًا.",+ "dimensions_column": "الأبعاد",+ "volume_column": "الحجم",+ "kinds": {+ "box": "صندوق",+ "envelope": "ظرف",+ "carton": "كرتونة",+ "pallet": "منصة",+ "container": "حاوية"+ },+ "messages": {+ "added": "تمت إضافة نوع التغليف",+ "updated": "تم تحديث نوع التغليف",+ "deleted": "تم حذف نوع التغليف"+ },+ "delete_confirm": {+ "title": "حذف نوع التغليف؟",+ "message": "سيتم حذف {{name}}. يجب أولًا إعادة تعبئة المنتجات المعبأة فيه."+ },+ "validation": {+ "non_negative": "يجب أن يكون صفرًا أو أكثر"+ }+ },"pages": {"settings": {"stock_locations": {"add_sheet_title": "إضافة موقع المخزون","edit_sheet_title": "تحرير موقع المخزون","search_placeholder": "البحث عن مواقع المخزون…"+ },+ "package_types": {+ "add_sheet_title": "إضافة نوع تغليف"}},"products": {diff --git a/packages/dashboard-core/src/locales/de.json b/packages/dashboard-core/src/locales/de.jsonindex d0fdf84d6d..0800342367 100644--- a/packages/dashboard-core/src/locales/de.json+++ b/packages/dashboard-core/src/locales/de.json@@ -624,6 +624,45 @@"name": {"label": "Name"},+ "package_type": {+ "name": {+ "label": "Name"+ },+ "kind": {+ "label": "Art",+ "help": "Nur ein Umkarton kann die Verpackung eines Produkts sein."+ },+ "length": {+ "label": "Länge"+ },+ "width": {+ "label": "Breite"+ },+ "height": {+ "label": "Höhe"+ },+ "dimensions_unit": {+ "label": "Einheit"+ },+ "dimensions": {+ "help": "Für das Volumengewicht des Carriers und die Kubikmeter der Frachtstufen."+ },+ "weight": {+ "label": "Leergewicht",+ "help": "Die Verpackung selbst, zusätzlich zum Inhalt."+ },+ "max_weight": {+ "label": "Max. Gewicht",+ "help": "Was sie tragen kann."+ },+ "weight_unit": {+ "label": "Einheit"+ },+ "default": {+ "label": "Standardverpackung",+ "help": "Die Verpackung, auf der Ihre Paketangebote basieren. Nur eine Standardverpackung gleichzeitig."+ }+ },"number": {"label": "Nummer"},@@ -989,12 +1028,46 @@"tax_category_saved": "Steuerkategorie gespeichert","updated": "Aktualisiert"},+ "package_types": {+ "table_title": "Verpackungsarten",+ "search_placeholder": "Verpackung suchen",+ "empty": "Noch keine Verpackung. Legen Sie Ihren Versandkarton an sowie die Kartons und Paletten für Großbestellungen.",+ "add_cta": "Verpackungsart hinzufügen",+ "default_badge": "Standard",+ "edit_sheet_title": "Verpackungsart",+ "create_description": "Ein Karton, eine Kiste, eine Palette oder ein Container, in den Waren gepackt werden.",+ "edit_description": "Produkte in diesem Karton übernehmen seine Maße — eine Änderung korrigiert alle.",+ "dimensions_column": "Maße",+ "volume_column": "Volumen",+ "kinds": {+ "box": "Karton",+ "envelope": "Umschlag",+ "carton": "Umkarton",+ "pallet": "Palette",+ "container": "Container"+ },+ "messages": {+ "added": "Verpackungsart hinzugefügt",+ "updated": "Verpackungsart aktualisiert",+ "deleted": "Verpackungsart gelöscht"+ },+ "delete_confirm": {+ "title": "Verpackungsart löschen?",+ "message": "{{name}} wird entfernt. Darin verpackte Produkte müssen zuerst umgepackt werden."+ },+ "validation": {+ "non_negative": "muss null oder größer sein"+ }+ },"pages": {"settings": {"stock_locations": {"add_sheet_title": "Lagerstandort hinzufügen","edit_sheet_title": "Lagerstandort bearbeiten","search_placeholder": "Lagerstandorte suchen…"+ },+ "package_types": {+ "add_sheet_title": "Verpackungsart hinzufügen"}},"products": {diff --git a/packages/dashboard-core/src/locales/en.json b/packages/dashboard-core/src/locales/en.jsonindex f14a7b209e..f3ddeb1857 100644--- a/packages/dashboard-core/src/locales/en.json+++ b/packages/dashboard-core/src/locales/en.json@@ -626,6 +626,45 @@"name": {"label": "Name"},+ "package_type": {+ "name": {+ "label": "Name"+ },+ "kind": {+ "label": "Kind",+ "help": "Only a carton can be the packaging a product is packed into."+ },+ "length": {+ "label": "Length"+ },+ "width": {+ "label": "Width"+ },+ "height": {+ "label": "Height"+ },+ "dimensions_unit": {+ "label": "Unit"+ },+ "dimensions": {+ "help": "Used for carrier dimensional weight, and for the cubic meters freight tiers compare."+ },+ "weight": {+ "label": "Empty weight",+ "help": "The packaging itself, added to what it holds."+ },+ "max_weight": {+ "label": "Max weight",+ "help": "What it can carry."+ },+ "weight_unit": {+ "label": "Unit"+ },+ "default": {+ "label": "Default box",+ "help": "The packaging your parcel quotes are built on. One default at a time."+ }+ },"number": {"label": "Number"},@@ -991,12 +1030,46 @@"tax_category_saved": "Tax category saved","updated": "Updated"},+ "package_types": {+ "table_title": "Package types",+ "search_placeholder": "Search packaging",+ "empty": "No packaging yet. Add the box you ship in, and the cartons and pallets wholesale orders leave on.",+ "add_cta": "Add package type",+ "default_badge": "Default",+ "edit_sheet_title": "Package type",+ "create_description": "A box, carton, pallet or container goods are packed into.",+ "edit_description": "Products packed into this carton follow its measurements, so one edit corrects them all.",+ "dimensions_column": "Dimensions",+ "volume_column": "Volume",+ "kinds": {+ "box": "Box",+ "envelope": "Envelope",+ "carton": "Carton",+ "pallet": "Pallet",+ "container": "Container"+ },+ "messages": {+ "added": "Package type added",+ "updated": "Package type updated",+ "deleted": "Package type deleted"+ },+ "delete_confirm": {+ "title": "Delete package type?",+ "message": "{{name}} will be removed. Products packed into it must be repacked first."+ },+ "validation": {+ "non_negative": "must be zero or more"+ }+ },"pages": {"settings": {"stock_locations": {"add_sheet_title": "Add stock location","edit_sheet_title": "Edit stock location","search_placeholder": "Search stock locations…"+ },+ "package_types": {+ "add_sheet_title": "Add package type"}},"products": {diff --git a/packages/dashboard-core/src/locales/fr.json b/packages/dashboard-core/src/locales/fr.jsonindex f1f668ddde..25fc9fb9a8 100644--- a/packages/dashboard-core/src/locales/fr.json+++ b/packages/dashboard-core/src/locales/fr.json@@ -624,6 +624,45 @@"name": {"label": "Nom"},+ "package_type": {+ "name": {+ "label": "Nom"+ },+ "kind": {+ "label": "Type",+ "help": "Seul un carton maître peut être l'emballage d'un produit."+ },+ "length": {+ "label": "Longueur"+ },+ "width": {+ "label": "Largeur"+ },+ "height": {+ "label": "Hauteur"+ },+ "dimensions_unit": {+ "label": "Unité"+ },+ "dimensions": {+ "help": "Utilisées pour le poids volumétrique et pour les mètres cubes des paliers de fret."+ },+ "weight": {+ "label": "Poids à vide",+ "help": "L'emballage lui-même, ajouté à son contenu."+ },+ "max_weight": {+ "label": "Poids max.",+ "help": "Ce qu'il peut porter."+ },+ "weight_unit": {+ "label": "Unité"+ },+ "default": {+ "label": "Emballage par défaut",+ "help": "L'emballage sur lequel vos tarifs de colis sont calculés. Un seul par défaut à la fois."+ }+ },"number": {"label": "Numéro"},@@ -989,12 +1028,46 @@"tax_category_saved": "Catégorie de taxe enregistrée","updated": "Mis à jour"},+ "package_types": {+ "table_title": "Types d'emballage",+ "search_placeholder": "Rechercher un emballage",+ "empty": "Aucun emballage. Ajoutez votre carton d'expédition, ainsi que les cartons et palettes des commandes en gros.",+ "add_cta": "Ajouter un type d'emballage",+ "default_badge": "Par défaut",+ "edit_sheet_title": "Type d'emballage",+ "create_description": "Une boîte, un carton, une palette ou un conteneur dans lequel les marchandises sont emballées.",+ "edit_description": "Les produits emballés dans ce carton suivent ses dimensions : une modification les corrige tous.",+ "dimensions_column": "Dimensions",+ "volume_column": "Volume",+ "kinds": {+ "box": "Carton",+ "envelope": "Enveloppe",+ "carton": "Carton maître",+ "pallet": "Palette",+ "container": "Conteneur"+ },+ "messages": {+ "added": "Type d'emballage ajouté",+ "updated": "Type d'emballage mis à jour",+ "deleted": "Type d'emballage supprimé"+ },+ "delete_confirm": {+ "title": "Supprimer ce type d'emballage ?",+ "message": "{{name}} sera supprimé. Les produits qui y sont emballés doivent d'abord être reconditionnés."+ },+ "validation": {+ "non_negative": "doit être supérieur ou égal à zéro"+ }+ },"pages": {"settings": {"stock_locations": {"add_sheet_title": "Ajouter un emplacement de stock","edit_sheet_title": "Modifier l'emplacement de stock","search_placeholder": "Rechercher des emplacements de stock…"+ },+ "package_types": {+ "add_sheet_title": "Ajouter un type d'emballage"}},"products": {diff --git a/packages/dashboard-core/src/locales/pl.json b/packages/dashboard-core/src/locales/pl.jsonindex fe593365c3..98f93655c8 100644--- a/packages/dashboard-core/src/locales/pl.json+++ b/packages/dashboard-core/src/locales/pl.json@@ -625,6 +625,45 @@"name": {"label": "Nazwa"},+ "package_type": {+ "name": {+ "label": "Nazwa"+ },+ "kind": {+ "label": "Rodzaj",+ "help": "Tylko karton zbiorczy może być opakowaniem produktu."+ },+ "length": {+ "label": "Długość"+ },+ "width": {+ "label": "Szerokość"+ },+ "height": {+ "label": "Wysokość"+ },+ "dimensions_unit": {+ "label": "Jednostka"+ },+ "dimensions": {+ "help": "Do wagi objętościowej przewoźnika i metrów sześciennych progów frachtowych."+ },+ "weight": {+ "label": "Waga pustego",+ "help": "Samo opakowanie, doliczane do zawartości."+ },+ "max_weight": {+ "label": "Maks. waga",+ "help": "Ile może unieść."+ },+ "weight_unit": {+ "label": "Jednostka"+ },+ "default": {+ "label": "Domyślne opakowanie",+ "help": "Opakowanie, na którym opierają się wyceny Twoich przesyłek. Tylko jedno domyślne naraz."+ }+ },"number": {"label": "Numer"},@@ -990,12 +1029,46 @@"tax_category_saved": "Zapisano kategorię podatkową","updated": "Zaktualizowano"},+ "package_types": {+ "table_title": "Rodzaje opakowań",+ "search_placeholder": "Szukaj opakowania",+ "empty": "Brak opakowań. Dodaj karton wysyłkowy oraz kartony i palety dla zamówień hurtowych.",+ "add_cta": "Dodaj rodzaj opakowania",+ "default_badge": "Domyślne",+ "edit_sheet_title": "Rodzaj opakowania",+ "create_description": "Pudełko, karton, paleta lub kontener, w które pakowane są towary.",+ "edit_description": "Produkty pakowane w ten karton przyjmują jego wymiary — jedna zmiana poprawia wszystkie.",+ "dimensions_column": "Wymiary",+ "volume_column": "Objętość",+ "kinds": {+ "box": "Karton",+ "envelope": "Koperta",+ "carton": "Karton zbiorczy",+ "pallet": "Paleta",+ "container": "Kontener"+ },+ "messages": {+ "added": "Dodano rodzaj opakowania",+ "updated": "Zaktualizowano rodzaj opakowania",+ "deleted": "Usunięto rodzaj opakowania"+ },+ "delete_confirm": {+ "title": "Usunąć rodzaj opakowania?",+ "message": "{{name}} zostanie usunięty. Produkty w nim zapakowane trzeba najpierw przepakować."+ },+ "validation": {+ "non_negative": "musi wynosić zero lub więcej"+ }+ },"pages": {"settings": {"stock_locations": {"add_sheet_title": "Dodaj lokalizację magazynową","edit_sheet_title": "Edytuj lokalizację magazynową","search_placeholder": "Szukaj lokalizacji magazynowych…"+ },+ "package_types": {+ "add_sheet_title": "Dodaj rodzaj opakowania"}},"products": {diff --git a/packages/dashboard-core/src/locales/zh-CN.json b/packages/dashboard-core/src/locales/zh-CN.jsonindex 1998a906b1..050ca9d07e 100644--- a/packages/dashboard-core/src/locales/zh-CN.json+++ b/packages/dashboard-core/src/locales/zh-CN.json@@ -624,6 +624,45 @@"name": {"label": "名称"},+ "package_type": {+ "name": {+ "label": "名称"+ },+ "kind": {+ "label": "类型",+ "help": "只有外箱可以作为商品的包装。"+ },+ "length": {+ "label": "长"+ },+ "width": {+ "label": "宽"+ },+ "height": {+ "label": "高"+ },+ "dimensions_unit": {+ "label": "单位"+ },+ "dimensions": {+ "help": "用于承运商的体积重量,以及运费档位比较的立方米。"+ },+ "weight": {+ "label": "空重",+ "help": "包装本身的重量,计入所装货物之外。"+ },+ "max_weight": {+ "label": "最大承重",+ "help": "可承载的重量。"+ },+ "weight_unit": {+ "label": "单位"+ },+ "default": {+ "label": "默认包装",+ "help": "您的包裹报价所依据的包装。同一时间只能有一个默认包装。"+ }+ },"number": {"label": "编号"},@@ -989,12 +1028,46 @@"tax_category_saved": "税收类别已保存","updated": "已更新"},+ "package_types": {+ "table_title": "包装类型",+ "search_placeholder": "搜索包装",+ "empty": "尚无包装。请添加发货纸箱,以及批发订单使用的外箱和托盘。",+ "add_cta": "添加包装类型",+ "default_badge": "默认",+ "edit_sheet_title": "包装类型",+ "create_description": "用于装载商品的箱、纸箱、托盘或集装箱。",+ "edit_description": "装入此外箱的商品沿用其尺寸,修改一次即可全部更正。",+ "dimensions_column": "尺寸",+ "volume_column": "体积",+ "kinds": {+ "box": "纸箱",+ "envelope": "信封袋",+ "carton": "外箱",+ "pallet": "托盘",+ "container": "集装箱"+ },+ "messages": {+ "added": "已添加包装类型",+ "updated": "已更新包装类型",+ "deleted": "已删除包装类型"+ },+ "delete_confirm": {+ "title": "删除包装类型?",+ "message": "将删除 {{name}}。装入其中的商品需先重新包装。"+ },+ "validation": {+ "non_negative": "必须大于或等于零"+ }+ },"pages": {"settings": {"stock_locations": {"add_sheet_title": "添加库存位置","edit_sheet_title": "编辑库存位置","search_placeholder": "搜索库存位置…"+ },+ "package_types": {+ "add_sheet_title": "添加包装类型"}},"products": {diff --git a/packages/dashboard-core/src/pages/package-types.tsx b/packages/dashboard-core/src/pages/package-types.tsxnew file mode 100644index 0000000000..8be14eb7f1--- /dev/null+++ b/packages/dashboard-core/src/pages/package-types.tsx@@ -0,0 +1,484 @@+import { zodResolver } from '@hookform/resolvers/zod'+import {+ Button,+ Field,+ FieldDescription,+ FieldError,+ FieldGroup,+ FieldLabel,+ Input,+ RowActions,+ Select,+ SelectContent,+ SelectItem,+ SelectTrigger,+ SelectValue,+ Sheet,+ SheetContent,+ SheetDescription,+ SheetFooter,+ SheetHeader,+ SheetTitle,+ Switch,+ useConfirm,+ useRowClickBridge,+} from '@spree/dashboard-ui'+import { PlusIcon } from '@spree/dashboard-ui/icons'+import { useNavigate } from '@tanstack/react-router'+import { useEffect } from 'react'+import { Controller, type UseFormReturn, useForm } from 'react-hook-form'+import { useTranslation } from 'react-i18next'+import { z } from 'zod/v4'+import type { PanelPackageType } from '../api-client'+import { Can } from '../components/can'+import { ResourceTable, resourceSearchSchema } from '../components/resource-table'+import {+ canDeletePackageTypes,+ canWritePackageTypes,+ listPackageTypes,+ useCreatePackageType,+ useDeletePackageType,+ usePackageType,+ useUpdatePackageType,+} from '../hooks/use-package-types'+import { mapSpreeErrorsToForm } from '../lib/form-errors'+import { Subject } from '../lib/permissions'+import { usePermissions } from '../providers/permission-provider'+import {+ PACKAGE_DIMENSION_UNITS,+ PACKAGE_TYPE_DEFAULTS,+ PACKAGE_TYPE_KINDS,+ PACKAGE_WEIGHT_UNITS,+ type PackageTypeFormValues,+ packageTypeFormSchema,+ packageTypeFormValuesToParams,+ packageTypeToFormValues,+} from '../schemas/package-type'+import '../tables/package-types'++/**+ * Adds `?edit=<id>` and `?new=1` on top of the standard table search schema,+ * so the create and edit sheets can be deep-linked.+ *+ * Exported because each app owns its own route file — the route path differs+ * per panel (`/$storeId/settings/...` against `/$sellerId/settings/...`) and+ * TanStack's file routes are generated per app — while everything the page+ * *does* lives here.+ */+export const packageTypesSearchSchema = resourceSearchSchema.extend({+ edit: z.string().optional(),+ new: z.coerce.boolean().optional(),+})++export type PackageTypesSearch = z.infer<typeof packageTypesSearchSchema>++/**+ * Manage the packaging this panel can see: the boxes parcels ship in, the+ * cartons products are packed into, the pallets a wholesale order leaves on.+ *+ * Shared by the operator's dashboard and the marketplace seller panel. The+ * scoping is server-side — the operator's API answers with every row in the+ * store and a seller's with their own plus the marketplace's shared+ * vocabulary — so this page renders whatever it is given+ * (docs/plans/6.0-seller-package-types.md).+ *+ * One row can be listed but not written: a seller sees the marketplace's+ * packaging so they know what they may pack into, and it reports+ * `editable: false`. The operator's serializer carries no such field because+ * every row there is theirs, so an absent flag reads as editable.+ */+function noop() {}++export function PackageTypesPage({ search }: { search: PackageTypesSearch }) {+ const { t } = useTranslation()+ const navigate = useNavigate()+ const confirm = useConfirm()+ const deleteMutation = useDeletePackageType()+ const { permissions } = usePermissions()++ // A panel may register `packageTypes.list` alone for the variant editor's+ // carton picker. Reading it here keeps this page honest on such a panel:+ // no add button, no row actions, and no sheet whose save could not work.+ const writable = canWritePackageTypes()++ // Neither sheet opens on a read-only panel. No mutual exclusion needed:+ // openCreate strips `edit` and openEdit strips `new`, so a link can only+ // carry one.+ const isCreating = writable && !!search.new+ const editId = writable ? search.edit : undefined++ function closeSheet() {+ navigate({+ search: (prev: Record<string, unknown>) => {+ const { edit: _e, new: _n, ...rest } = prev+ return rest as never+ },+ })+ }++ function openCreate() {+ navigate({+ search: (prev: Record<string, unknown>) => {+ const { edit: _e, ...rest } = prev+ return { ...rest, new: true } as never+ },+ })+ }++ function openEdit(id: string) {+ navigate({+ search: (prev: Record<string, unknown>) => {+ const { new: _n, ...rest } = prev+ return { ...rest, edit: id } as never+ },+ })+ }++ // Guarded on `writable` as well: on a read-only panel no sheet can open, so+ // a click would only push an `edit` param nothing consumes or clears.+ useRowClickBridge('data-package-type-id', writable ? openEdit : noop)++ async function handleDelete(packageType: PanelPackageType) {+ const ok = await confirm({+ title: t('admin.package_types.delete_confirm.title'),+ message: t('admin.package_types.delete_confirm.message', { name: packageType.name }),+ variant: 'destructive',+ confirmLabel: t('admin.actions.delete'),+ })+ if (!ok) return+ await deleteMutation.mutateAsync(packageType.id).catch(() => undefined)+ }++ return (+ <>+ <ResourceTable<PanelPackageType>+ tableKey="package-types"+ queryKey="package-types"+ queryFn={listPackageTypes}+ searchParams={search}+ rowActions={(packageType) => {+ // A marketplace row in a seller's list is read-only, so it gets no+ // actions at all rather than actions that 404 on click. Same for+ // every row when this panel's client registered reads only.+ if (packageType.editable === false || !writable) return null++ return (+ <RowActions+ actions={[+ {+ key: 'edit',+ visible: permissions.can('update', Subject.PackageType),+ onSelect: () => openEdit(packageType.id),+ },+ {+ key: 'delete',+ destructive: true,+ visible:+ canDeletePackageTypes() && permissions.can('destroy', Subject.PackageType),+ disabled: deleteMutation.isPending,+ onSelect: () => handleDelete(packageType),+ },+ ]}+ />+ )+ }}+ actions={+ writable ? (+ <Can I="create" a={Subject.PackageType}>+ <Button size="sm" className="h-[2.125rem]" onClick={openCreate}>+ <PlusIcon className="size-4" />+ {t('admin.package_types.add_cta')}+ </Button>+ </Can>+ ) : null+ }+ />++ {isCreating && <CreatePackageTypeSheet open onOpenChange={(o) => !o && closeSheet()} />}+ {editId && <EditPackageTypeSheet id={editId} open onOpenChange={(o) => !o && closeSheet()} />}+ </>+ )+}++function CreatePackageTypeSheet({+ open,+ onOpenChange,+}: {+ open: boolean+ onOpenChange: (open: boolean) => void+}) {+ const { t } = useTranslation()+ const createMutation = useCreatePackageType()+ const form = useForm<PackageTypeFormValues>({+ resolver: zodResolver(packageTypeFormSchema),+ defaultValues: PACKAGE_TYPE_DEFAULTS,+ })++ async function onSubmit(values: PackageTypeFormValues) {+ try {+ await createMutation.mutateAsync(packageTypeFormValuesToParams(values))+ form.reset(PACKAGE_TYPE_DEFAULTS)+ onOpenChange(false)+ } catch (err) {+ if (!mapSpreeErrorsToForm(err, form.setError)) throw err+ }+ }++ return (+ <Sheet+ open={open}+ onOpenChange={(next) => {+ if (!next) form.reset(PACKAGE_TYPE_DEFAULTS)+ onOpenChange(next)+ }}+ >+ <SheetContent>+ <SheetHeader>+ <SheetTitle>{t('admin.pages.settings.package_types.add_sheet_title')}</SheetTitle>+ <SheetDescription>{t('admin.package_types.create_description')}</SheetDescription>+ </SheetHeader>+ <form onSubmit={form.handleSubmit(onSubmit)} className="flex min-h-0 flex-1 flex-col">+ <div className="flex flex-1 flex-col gap-4 overflow-y-auto p-4">+ <PackageTypeFormFields form={form} />+ </div>+ <SheetFooter>+ <Button type="submit" disabled={createMutation.isPending}>+ {t('admin.actions.save')}+ </Button>+ </SheetFooter>+ </form>+ </SheetContent>+ </Sheet>+ )+}++function EditPackageTypeSheet({+ id,+ open,+ onOpenChange,+}: {+ id: string+ open: boolean+ onOpenChange: (open: boolean) => void+}) {+ const { t } = useTranslation()+ const { data: packageType } = usePackageType(id)+ const updateMutation = useUpdatePackageType(id)+ // A pasted link can name a row this panel may read but not write — the+ // marketplace's packaging in a seller's panel. Closing rather than+ // rendering a form whose save could only 404.+ const readOnly = packageType?.editable === false+ const form = useForm<PackageTypeFormValues>({+ resolver: zodResolver(packageTypeFormSchema),+ defaultValues: PACKAGE_TYPE_DEFAULTS,+ values: packageType ? packageTypeToFormValues(packageType) : undefined,+ })++ async function onSubmit(values: PackageTypeFormValues) {+ try {+ await updateMutation.mutateAsync(packageTypeFormValuesToParams(values))+ onOpenChange(false)+ } catch (err) {+ if (!mapSpreeErrorsToForm(err, form.setError)) throw err+ }+ }++ useEffect(() => {+ if (readOnly) onOpenChange(false)+ }, [readOnly, onOpenChange])++ if (readOnly) return null++ return (+ <Sheet open={open} onOpenChange={onOpenChange}>+ <SheetContent>+ <SheetHeader>+ <SheetTitle>{packageType?.name ?? t('admin.package_types.edit_sheet_title')}</SheetTitle>+ <SheetDescription>{t('admin.package_types.edit_description')}</SheetDescription>+ </SheetHeader>+ <form onSubmit={form.handleSubmit(onSubmit)} className="flex min-h-0 flex-1 flex-col">+ <div className="flex flex-1 flex-col gap-4 overflow-y-auto p-4">+ <PackageTypeFormFields form={form} />+ </div>+ <SheetFooter>+ <Button type="submit" disabled={updateMutation.isPending}>+ {t('admin.actions.save')}+ </Button>+ </SheetFooter>+ </form>+ </SheetContent>+ </Sheet>+ )+}++function PackageTypeFormFields({ form }: { form: UseFormReturn<PackageTypeFormValues> }) {+ const { t } = useTranslation()+ const errors = form.formState.errors++ return (+ <FieldGroup>+ <Field>+ <FieldLabel htmlFor="package-type-name">+ {t('admin.fields.package_type.name.label')}+ </FieldLabel>+ <Input id="package-type-name" {...form.register('name')} aria-invalid={!!errors.name} />+ <FieldError errors={[errors.name]} />+ </Field>++ <Field>+ <FieldLabel htmlFor="package-type-kind">+ {t('admin.fields.package_type.kind.label')}+ </FieldLabel>+ <Controller+ control={form.control}+ name="kind"+ render={({ field }) => {+ const options = PACKAGE_TYPE_KINDS.map((kind) => ({+ value: kind,+ label: t(`admin.package_types.kinds.${kind}`),+ }))+ return (+ <Select items={options} value={field.value} onValueChange={field.onChange}>+ <SelectTrigger id="package-type-kind">+ <SelectValue />+ </SelectTrigger>+ <SelectContent>+ {options.map((option) => (+ <SelectItem key={option.value} value={option.value}>+ {option.label}+ </SelectItem>+ ))}+ </SelectContent>+ </Select>+ )+ }}+ />+ <FieldDescription>{t('admin.fields.package_type.kind.help')}</FieldDescription>+ </Field>++ <div className="grid grid-cols-[1fr_1fr_1fr_110px] gap-3">+ {(['length', 'width', 'height'] as const).map((side) => (+ <Field key={side}>+ <FieldLabel htmlFor={`package-type-${side}`}>+ {t(`admin.fields.package_type.${side}.label`)}+ </FieldLabel>+ <Input+ id={`package-type-${side}`}+ type="number"+ min="0"+ step="0.01"+ aria-invalid={!!errors[side]}+ {...form.register(side)}+ />+ <FieldError errors={[errors[side]]} />+ </Field>+ ))}+ <UnitField+ form={form}+ name="dimensions_unit"+ units={PACKAGE_DIMENSION_UNITS}+ label={t('admin.fields.package_type.dimensions_unit.label')}+ />+ </div>+ <FieldDescription>{t('admin.fields.package_type.dimensions.help')}</FieldDescription>++ <div className="grid grid-cols-[1fr_1fr_110px] gap-3">+ <Field>+ <FieldLabel htmlFor="package-type-weight">+ {t('admin.fields.package_type.weight.label')}+ </FieldLabel>+ <Input+ id="package-type-weight"+ type="number"+ min="0"+ step="0.01"+ aria-invalid={!!errors.weight}+ {...form.register('weight')}+ />+ <FieldError errors={[errors.weight]} />+ <FieldDescription>{t('admin.fields.package_type.weight.help')}</FieldDescription>+ </Field>+ <Field>+ <FieldLabel htmlFor="package-type-max-weight">+ {t('admin.fields.package_type.max_weight.label')}+ </FieldLabel>+ <Input+ id="package-type-max-weight"+ type="number"+ min="0"+ step="0.01"+ aria-invalid={!!errors.max_weight}+ {...form.register('max_weight')}+ />+ <FieldError errors={[errors.max_weight]} />+ <FieldDescription>{t('admin.fields.package_type.max_weight.help')}</FieldDescription>+ </Field>+ <UnitField+ form={form}+ name="weight_unit"+ units={PACKAGE_WEIGHT_UNITS}+ label={t('admin.fields.package_type.weight_unit.label')}+ />+ </div>++ <Field>+ <div className="flex items-start justify-between gap-4">+ <FieldLabel htmlFor="package-type-default" className="cursor-pointer">+ {t('admin.fields.package_type.default.label')}+ </FieldLabel>+ <Controller+ control={form.control}+ name="default"+ render={({ field }) => (+ <Switch+ id="package-type-default"+ checked={!!field.value}+ onCheckedChange={field.onChange}+ />+ )}+ />+ </div>+ <FieldDescription>{t('admin.fields.package_type.default.help')}</FieldDescription>+ </Field>+ </FieldGroup>+ )+}++function UnitField({+ form,+ name,+ units,+ label,+}: {+ form: UseFormReturn<PackageTypeFormValues>+ name: 'dimensions_unit' | 'weight_unit'+ units: readonly string[]+ label: string+}) {+ return (+ <Field>+ <FieldLabel htmlFor={`package-type-${name}`}>{label}</FieldLabel>+ <Controller+ control={form.control}+ name={name}+ render={({ field }) => {+ const options = units.map((unit) => ({ value: unit, label: unit }))+ return (+ <Select items={options} value={field.value ?? ''} onValueChange={field.onChange}>+ <SelectTrigger id={`package-type-${name}`}>+ <SelectValue />+ </SelectTrigger>+ <SelectContent>+ {options.map((option) => (+ <SelectItem key={option.value} value={option.value}>+ {option.label}+ </SelectItem>+ ))}+ </SelectContent>+ </Select>+ )+ }}+ />+ </Field>+ )+}diff --git a/packages/dashboard-core/src/products/use-product-form-data.ts b/packages/dashboard-core/src/products/use-product-form-data.tsindex c4fc3a5636..c853b3950f 100644--- a/packages/dashboard-core/src/products/use-product-form-data.ts+++ b/packages/dashboard-core/src/products/use-product-form-data.ts@@ -153,6 +153,10 @@ export function useFormCartonPackageTypes() {(await client.packageTypes?.list({ limit: 100, kind_eq: 'carton' })) ?? { data: [] },enabled: supported,staleTime: FIVE_MINUTES,+ // The seller endpoint returns their own cartons before the+ // marketplace's, so the 100-row ceiling cuts the shared vocabulary rather+ // than the seller's own measurements. Ordered there rather than here+ // because the page is taken before anything client-side could reorder it.})return { ...query, supported }diff --git a/packages/dashboard-core/src/schemas/package-type.ts b/packages/dashboard-core/src/schemas/package-type.tsnew file mode 100644index 0000000000..a5d9107851--- /dev/null+++ b/packages/dashboard-core/src/schemas/package-type.ts@@ -0,0 +1,95 @@+import { requiredMessage } from '@spree/dashboard-ui'+import i18n from 'i18next'+import { z } from 'zod/v4'+import type { PanelPackageType, PanelPackageTypeCreateParams } from '../api-client'++// The vocabulary the server validates against; typing anything else could+// only fail on save.+export const PACKAGE_TYPE_KINDS = ['box', 'envelope', 'carton', 'pallet', 'container'] as const+export const PACKAGE_DIMENSION_UNITS = ['mm', 'cm', 'in', 'ft'] as const+export const PACKAGE_WEIGHT_UNITS = ['g', 'kg', 'lb', 'oz'] as const++export type PackageTypeKind = (typeof PACKAGE_TYPE_KINDS)[number]+export type PackageDimensionUnit = (typeof PACKAGE_DIMENSION_UNITS)[number]+export type PackageWeightUnit = (typeof PACKAGE_WEIGHT_UNITS)[number]++// Blank is how a merchant says "not measured", so every number is optional+// and an empty string reaches the API as null rather than zero — a box+// recorded as zero long, zero wide is not the same as one nobody measured.+const optionalNumber = z+ .union([z.string(), z.number()])+ .optional()+ // `NaN >= 0` is already false, so the comparison alone rejects garbage.+ .refine((value) => value === '' || value === undefined || Number(value) >= 0, {+ error: () => i18n.t('admin.package_types.validation.non_negative'),+ })++export const packageTypeFormSchema = z.object({+ name: z+ .string()+ .trim()+ .min(1, { error: requiredMessage('package_type.name') }),+ kind: z.enum(PACKAGE_TYPE_KINDS),+ length: optionalNumber,+ width: optionalNumber,+ height: optionalNumber,+ dimensions_unit: z.enum(PACKAGE_DIMENSION_UNITS).optional(),+ weight: optionalNumber,+ max_weight: optionalNumber,+ weight_unit: z.enum(PACKAGE_WEIGHT_UNITS).optional(),+ default: z.boolean().optional(),+})++export type PackageTypeFormValues = z.input<typeof packageTypeFormSchema>++export const PACKAGE_TYPE_DEFAULTS: PackageTypeFormValues = {+ name: '',+ kind: 'box',+ length: '',+ width: '',+ height: '',+ dimensions_unit: 'cm',+ weight: '',+ max_weight: '',+ weight_unit: 'kg',+ default: false,+}++/**+ * Blank erases a measurement, so it has to reach the API as an explicit null;+ * undefined would leave whatever was recorded before untouched.+ */+export function packageTypeFormValuesToParams(+ values: PackageTypeFormValues,+): PanelPackageTypeCreateParams {+ const measurement = (value: string | number | undefined) =>+ value === '' || value === undefined ? null : Number(value)++ return {+ name: values.name,+ kind: values.kind,+ length: measurement(values.length),+ width: measurement(values.width),+ height: measurement(values.height),+ weight: measurement(values.weight),+ max_weight: measurement(values.max_weight),+ dimensions_unit: values.dimensions_unit,+ weight_unit: values.weight_unit,+ default: values.default,+ }+}++export function packageTypeToFormValues(packageType: PanelPackageType): PackageTypeFormValues {+ return {+ name: packageType.name,+ kind: (packageType.kind ?? 'box') as PackageTypeKind,+ length: packageType.length ?? '',+ width: packageType.width ?? '',+ height: packageType.height ?? '',+ dimensions_unit: (packageType.dimensions_unit ?? 'cm') as PackageDimensionUnit,+ weight: packageType.weight ?? '',+ max_weight: packageType.max_weight ?? '',+ weight_unit: (packageType.weight_unit ?? 'kg') as PackageWeightUnit,+ default: packageType.default ?? false,+ }+}diff --git a/packages/dashboard-core/src/tables/package-types.tsx b/packages/dashboard-core/src/tables/package-types.tsxnew file mode 100644index 0000000000..eddeb4f7b6--- /dev/null+++ b/packages/dashboard-core/src/tables/package-types.tsx@@ -0,0 +1,72 @@+import { RelativeTime, ResourceNameCell } from '@spree/dashboard-ui'+import { PackageIcon } from '@spree/dashboard-ui/icons'+import i18n from 'i18next'+import type { PanelPackageType } from '../api-client'+import { defineTable } from '../lib/table-registry'++defineTable<PanelPackageType>('package-types', {+ title: i18n.t('admin.package_types.table_title'),+ searchParam: 'name_cont',+ searchPlaceholder: i18n.t('admin.package_types.search_placeholder'),+ defaultSort: { field: 'name', direction: 'asc' },+ emptyIcon: <PackageIcon className="size-8 text-muted-foreground" />,+ emptyMessage: i18n.t('admin.package_types.empty'),+ columns: [+ {+ key: 'name',+ label: i18n.t('admin.fields.package_type.name.label'),+ sortable: true,+ default: true,+ render: (packageType) => (+ <ResourceNameCell+ id={packageType.id}+ // Omitted on a row this panel may read but not write, so the row+ // click bridge never opens an edit sheet whose save could only+ // 404. A seller sees the marketplace's packaging to know what they+ // may pack into; it is not theirs to change.+ dataAttr={packageType.editable === false ? undefined : 'data-package-type-id'}+ name={packageType.name}+ // This owner's own box, called out because every parcel quote from+ // their warehouse is built on it.+ secondary={packageType.default ? i18n.t('admin.package_types.default_badge') : undefined}+ />+ ),+ },+ {+ key: 'kind',+ label: i18n.t('admin.fields.package_type.kind.label'),+ sortable: true,+ default: true,+ render: (packageType) => i18n.t(`admin.package_types.kinds.${packageType.kind}`),+ },+ {+ key: 'dimensions',+ label: i18n.t('admin.package_types.dimensions_column'),+ default: true,+ className: 'text-sm text-muted-foreground whitespace-nowrap',+ // Three numbers mean nothing without the unit they were measured in —+ // the same figures read as inches or centimetres differ sixteenfold by+ // volume, which is what the freight tiers compare.+ render: (packageType) =>+ packageType.length && packageType.width && packageType.height+ ? `${packageType.length} × ${packageType.width} × ${packageType.height} ${packageType.dimensions_unit}`+ : '—',+ },+ {+ key: 'volume',+ label: i18n.t('admin.package_types.volume_column'),+ className: 'text-sm text-muted-foreground whitespace-nowrap',+ render: (packageType) =>+ packageType.volume ? `${Number(packageType.volume).toFixed(3)} m³` : '—',+ },+ {+ key: 'created_at',+ label: i18n.t('admin.fields.created_at.label'),+ sortable: true,+ filterable: true,+ filterType: 'date',+ className: 'text-sm text-muted-foreground whitespace-nowrap',+ render: (packageType) => <RelativeTime iso={packageType.created_at} />,+ },+ ],+})diff --git a/packages/dashboard-ui/src/spree/resource-name-cell.tsx b/packages/dashboard-ui/src/spree/resource-name-cell.tsxindex 1bc1eef751..89d3191d76 100644--- a/packages/dashboard-ui/src/spree/resource-name-cell.tsx+++ b/packages/dashboard-ui/src/spree/resource-name-cell.tsx@@ -4,8 +4,15 @@ import { cn } from '../lib/utils'interface ResourceNameCellProps {/** Resource identifier, mirrored into the bridge data attribute. */id: string- /** Data attribute the `useRowClickBridge` listener targets (e.g. `data-payment-method-id`). */- dataAttr: `data-${string}`+ /**+ * Data attribute the `useRowClickBridge` listener targets (e.g.+ * `data-payment-method-id`).+ *+ * Omit it for a row that must not be opened — a record this panel may read+ * but not write. The cell then renders as plain text rather than a button+ * that looks clickable and does nothing.+ */+ dataAttr?: `data-${string}`/** Primary text — the resource's display name. */name: ReactNode/** Optional secondary line. Falsy values render nothing. */@@ -31,14 +38,24 @@ export function ResourceNameCell({secondary,nameClassName,}: ResourceNameCellProps) {+ const content = (+ <>+ <span className={cn('font-medium', nameClassName)}>{name}</span>+ {secondary && <span className="text-xs text-muted-foreground">{secondary}</span>}+ </>+ )++ if (!dataAttr) {+ return <div className="flex h-full w-full flex-col items-start text-left">{content}</div>+ }+return (<buttontype="button"{...{ [dataAttr]: id }}className="flex h-full w-full cursor-pointer flex-col items-start rounded text-left focus-visible:outline-none">- <span className={cn('font-medium', nameClassName)}>{name}</span>- {secondary && <span className="text-xs text-muted-foreground">{secondary}</span>}+ {content}</button>)}diff --git a/packages/dashboard/e2e/seller-package-types.spec.ts b/packages/dashboard/e2e/seller-package-types.spec.tsnew file mode 100644index 0000000000..472a5c9767--- /dev/null+++ b/packages/dashboard/e2e/seller-package-types.spec.ts@@ -0,0 +1,137 @@+import { expect, test } from '@playwright/test'+import { login } from './helpers'++// The seller panel is its own app on its own origin (see playwright.config.ts).+const SELLER_PANEL = `http://localhost:${process.env.E2E_SELLER_VITE_PORT || '5175'}`++/**+ * Creates a seller, invites someone, and accepts on the panel — returning the+ * signed-in seller page. The invitation flow has its own spec; this is the+ * precondition for anything a seller does afterwards.+ */+async function signInAsNewSeller(+ page: import('@playwright/test').Page,+ browser: import('@playwright/test').Browser,+) {+ const creds = await login(page)+ const suffix = Date.now()+ const sellerName = `E2E Packaging Seller ${suffix}`++ await page.goto(`/${creds.store_id}/sellers`)+ await page.getByRole('button', { name: /add seller/i }).click()+ await page.locator('#name').fill(sellerName)+ await page.getByRole('button', { name: /create seller/i }).click()+ await expect(page.getByRole('heading', { name: sellerName })).toBeVisible({ timeout: 15_000 })++ await page+ .getByRole('button', { name: /^invite$/i })+ .first()+ .click()+ await page.locator('#invite-email').fill(`e2e-packaging-${suffix}@example.com`)++ const [listResponse] = await Promise.all([+ page.waitForResponse(+ (res) =>+ /\/api\/v3\/admin\/sellers\/[^/]+\/invitations$/.test(res.url()) &&+ res.request().method() === 'GET' &&+ res.status() === 200,+ { timeout: 20_000 },+ ),+ page.getByRole('button', { name: /send invitation/i }).click(),+ ])+ const { data } = (await listResponse.json()) as { data: Array<{ acceptance_url: string }> }+ const acceptancePath = data[0].acceptance_url.replace(/^https?:\/\/[^/]+/, '')++ const context = await browser.newContext()+ const sellerPage = await context.newPage()+ await sellerPage.goto(`${SELLER_PANEL}${acceptancePath}`)+ await expect(sellerPage.getByLabel(/^password$/i)).toBeVisible({ timeout: 20_000 })+ await sellerPage.getByLabel(/first name/i).fill('Pat')+ await sellerPage.getByLabel(/last name/i).fill('Carlson')+ await sellerPage.getByLabel(/^password$/i).fill('e2e-password-123')+ await sellerPage.getByLabel(/confirm password/i).fill('e2e-password-123')+ await sellerPage.getByRole('button', { name: /accept|create account|join/i }).click()+ await expect(sellerPage).not.toHaveURL(/accept-invitation/, { timeout: 20_000 })++ return { context, sellerPage, sellerName }+}++test.describe('seller packaging', () => {+ // Creating a seller, inviting, accepting, then walking two panel pages does+ // not fit the suite's default budget — the preamble alone is four round+ // trips before this spec's own subject starts.+ test.slow()++ test('a seller records the box they ship in and the requirement completes', async ({+ page,+ browser,+ }) => {+ const { context, sellerPage } = await signInAsNewSeller(page, browser)++ try {+ const boxName = `E2E Mailer ${Date.now()}`++ // Navigated by clicking rather than by a built URL: acceptance lands on+ // the panel root and the seller id only appears in the path once the+ // panel has resolved which seller this user acts for. A hand-built path+ // races that and sends requests carrying no seller header.+ // "Setup" is what the panel calls the onboarding checklist in its nav+ // and its heading.+ const goToSetup = async () => {+ await sellerPage.getByRole('link', { name: /setup/i }).first().click()+ await expect(sellerPage.getByRole('heading', { name: /^setup$/i })).toBeVisible({+ timeout: 20_000,+ })+ }++ // The shipping-box requirement starts outstanding: a new seller has+ // recorded nothing to ship in.+ await goToSetup()+ await expect(sellerPage.getByText(/shipping box/i).first()).toBeVisible({ timeout: 20_000 })++ // Recording it: the page is reachable from settings, and a fully+ // measured default box is what the requirement asks for.+ await sellerPage+ .getByRole('link', { name: /^settings$/i })+ .first()+ .click()+ await sellerPage+ .getByRole('link', { name: /package types/i })+ .first()+ .click()+ await expect(sellerPage.getByRole('button', { name: /add package type/i })).toBeVisible({+ timeout: 20_000,+ })++ await sellerPage.getByRole('button', { name: /add package type/i }).click()+ await sellerPage.locator('#package-type-name').fill(boxName)+ await sellerPage.locator('#package-type-length').fill('30')+ await sellerPage.locator('#package-type-width').fill('20')+ await sellerPage.locator('#package-type-height').fill('15')+ await sellerPage.locator('#package-type-weight').fill('0.4')+ // A Switch renders as role=switch; the id is on the control, not a+ // clickable input.+ await sellerPage.getByRole('switch', { name: /default box/i }).click()+ await sellerPage.getByRole('button', { name: /^save$/i }).click()++ // It is the seller's own row afterwards, marked as their default.+ await expect(sellerPage.getByText(boxName)).toBeVisible({ timeout: 20_000 })++ // Which is what turns the requirement complete — the same evaluator the+ // operator reads, so this is the whole point of the feature.+ //+ // Reloaded rather than navigated: the checklist was fetched before the+ // box existed, and the packaging page has no reason to invalidate+ // another page's query, so clicking back to it would assert against the+ // cached answer.+ await goToSetup()+ await sellerPage.reload()+ await expect(sellerPage.getByRole('heading', { name: /^setup$/i })).toBeVisible({+ timeout: 20_000,+ })+ await expect(sellerPage.getByText(/1 of 7 done/i)).toBeVisible({ timeout: 20_000 })+ } finally {+ await context.close()+ }+ })+})diff --git a/packages/dashboard/src/api-client-setup.test.ts b/packages/dashboard/src/api-client-setup.test.tsnew file mode 100644index 0000000000..a44191184a--- /dev/null+++ b/packages/dashboard/src/api-client-setup.test.ts@@ -0,0 +1,45 @@+import { describe, expect, it } from 'vitest'++/**+ * The operator's packaging page is shared with the seller panel, and every+ * write on it goes through the client registered here. Registering `list`+ * alone still renders a page — the add button and row actions just vanish —+ * so a dropped method is invisible until someone tries to save. That is the+ * regression this file exists for; it happened once already.+ *+ * The contract cannot catch it. `packageTypes` is a union of a read shape and+ * a write shape precisely so a picker-only panel can register reads alone,+ * and nothing in the client type knows which routes a panel mounts — a+ * reads-only registration typechecks cleanly (verified).+ *+ * Asserted against the source rather than a built client because building one+ * needs a live SDK and a session, and what goes wrong here is a missing line.+ */+describe('the panel client registration', () => {+ const source = new URL('./api-client-setup.ts', import.meta.url)++ async function read() {+ const { readFile } = await import('node:fs/promises')+ return readFile(source, 'utf8')+ }++ it('registers every packaging method the shared settings page calls', async () => {+ const text = await read()+ const block = text.match(/packageTypes:\s*\{[\s\S]*?\n {2}\},/)?.[0]++ expect(block, 'no packageTypes registration found').toBeTruthy()+ for (const method of ['list', 'get', 'create', 'update', 'delete']) {+ expect(block, `packageTypes.${method} is not registered`).toContain(`${method}:`)+ }+ })++ it('registers every stock-location method that page calls', async () => {+ const text = await read()+ const block = text.match(/stockLocations:\s*\{[\s\S]*?\n {2}\},/)?.[0]++ expect(block, 'no stockLocations registration found').toBeTruthy()+ for (const method of ['list', 'get', 'create', 'update']) {+ expect(block, `stockLocations.${method} is not registered`).toContain(`${method}:`)+ }+ })+})diff --git a/packages/dashboard/src/api-client-setup.ts b/packages/dashboard/src/api-client-setup.tsindex a6b49af921..ff8fce5178 100644--- a/packages/dashboard/src/api-client-setup.ts+++ b/packages/dashboard/src/api-client-setup.ts@@ -66,7 +66,15 @@ setApiClient({},taxCategories: { list: (params) => adminClient.taxCategories.list(params) },deliveryProfiles: { list: (params) => adminClient.deliveryProfiles.list(params) },- packageTypes: { list: (params) => adminClient.packageTypes.list(params) },+ // Writes as well as reads: the packaging settings page is shared with the+ // seller panel, and its create/edit/delete go through this registration.+ packageTypes: {+ list: (params) => adminClient.packageTypes.list(params),+ get: (id) => adminClient.packageTypes.get(id),+ create: (params) => adminClient.packageTypes.create(params),+ update: (id, params) => adminClient.packageTypes.update(id, params),+ delete: (id) => adminClient.packageTypes.delete(id),+ },deleteProductMedia: (productId, mediaId) => adminClient.products.media.delete(productId, mediaId),mediaLibrary: { list: (params) => adminClient.media.list(params) },markets: { list: (params) => adminClient.markets.list(params) },diff --git a/packages/dashboard/src/hooks/use-package-types.ts b/packages/dashboard/src/hooks/use-package-types.tsdeleted file mode 100644index 10bfd06857..0000000000--- a/packages/dashboard/src/hooks/use-package-types.ts+++ /dev/null@@ -1,54 +0,0 @@-import type {- PackageType,- PackageTypeCreateParams,- PackageTypeUpdateParams,-} from '@spree/admin-sdk'-import {- adminClient,- useResourceKey,- useResourceKeyBuilder,- useResourceMutation,-} from '@spree/dashboard-core'-import { useQuery, useQueryClient } from '@tanstack/react-query'-import i18n from 'i18next'--export function usePackageType(id: string | undefined) {- return useQuery({- queryKey: useResourceKey('package-types', id ?? 'noop'),- queryFn: () => adminClient.packageTypes.get(id as string),- enabled: !!id,- })-}--export function useCreatePackageType() {- return useResourceMutation<PackageType, Error, PackageTypeCreateParams>({- mutationFn: (params) => adminClient.packageTypes.create(params),- invalidate: [['package-types']],- successMessage: i18n.t('admin.package_types.messages.added'),- errorMessage: i18n.t('admin.errors.failed_to_create'),- })-}--export function useUpdatePackageType(id: string) {- return useResourceMutation<PackageType, Error, PackageTypeUpdateParams>({- mutationFn: (params) => adminClient.packageTypes.update(id, params),- invalidate: [['package-types'], ['package-types', id]],- successMessage: i18n.t('admin.package_types.messages.updated'),- errorMessage: i18n.t('admin.errors.failed_to_update'),- })-}--export function useDeletePackageType() {- const queryClient = useQueryClient()- const buildKey = useResourceKeyBuilder()-- return useResourceMutation<void, Error, string>({- mutationFn: (id) => adminClient.packageTypes.delete(id),- invalidate: [['package-types']],- successMessage: i18n.t('admin.package_types.messages.deleted'),- errorMessage: i18n.t('admin.errors.failed_to_delete'),- onSuccess: (_data, id) => {- queryClient.removeQueries({ queryKey: buildKey('package-types', id) })- },- })-}diff --git a/packages/dashboard/src/locales/ar.json b/packages/dashboard/src/locales/ar.jsonindex 9f95237af9..15eca85e4c 100644--- a/packages/dashboard/src/locales/ar.json+++ b/packages/dashboard/src/locales/ar.json@@ -2375,8 +2375,8 @@"label": "الوحدة"},"default": {- "label": "صندوق المتجر الافتراضي",- "help": "أساس كل تسعيرة طرد. واحد فقط لكل متجر."+ "label": "العلبة الافتراضية",+ "help": "العلبة التي تُحسب على أساسها أسعار شحن طرودك. علبة افتراضية واحدة في كل مرة."}}},@@ -5240,9 +5240,9 @@"search_placeholder": "ابحث عن تغليف","empty": "لا يوجد تغليف بعد. أضف صندوق الشحن، والكراتين والمنصات التي تغادر بها طلبات الجملة.","add_cta": "إضافة نوع تغليف",- "default_badge": "افتراضي المتجر",+ "default_badge": "افتراضي","edit_sheet_title": "نوع التغليف",- "create_description": "صندوق أو كرتونة أو منصة أو حاوية يعبّئ فيها هذا المتجر بضاعته.",+ "create_description": "علبة أو كرتونة أو منصة نقالة أو حاوية تُعبأ فيها السلع.","edit_description": "المنتجات المعبأة في هذه الكرتونة تتبع مقاساتها، فتعديل واحد يصحّحها جميعًا.","dimensions_column": "الأبعاد","volume_column": "الحجم",@@ -5264,6 +5264,12 @@},"validation": {"non_negative": "يجب أن يكون صفرًا أو أكثر"+ },+ "columns": {+ "seller": "المالك"+ },+ "owner": {+ "marketplace": "السوق"}}}diff --git a/packages/dashboard/src/locales/de.json b/packages/dashboard/src/locales/de.jsonindex 412344ac34..368ba88a2d 100644--- a/packages/dashboard/src/locales/de.json+++ b/packages/dashboard/src/locales/de.json@@ -2357,8 +2357,8 @@"label": "Einheit"},"default": {- "label": "Standardkarton des Shops",- "help": "Grundlage jeder Paketberechnung. Nur einer pro Shop."+ "label": "Standardverpackung",+ "help": "Die Verpackung, auf der Ihre Paketangebote basieren. Nur eine Standardverpackung gleichzeitig."}}},@@ -5218,9 +5218,9 @@"search_placeholder": "Verpackung suchen","empty": "Noch keine Verpackung. Legen Sie Ihren Versandkarton an sowie die Kartons und Paletten für Großbestellungen.","add_cta": "Verpackungsart hinzufügen",- "default_badge": "Standard des Shops",+ "default_badge": "Standard","edit_sheet_title": "Verpackungsart",- "create_description": "Ein Karton, eine Palette oder ein Container, in den dieser Shop Ware packt.",+ "create_description": "Ein Karton, eine Kiste, eine Palette oder ein Container, in den Waren gepackt werden.","edit_description": "Produkte in diesem Karton übernehmen seine Maße — eine Änderung korrigiert alle.","dimensions_column": "Maße","volume_column": "Volumen",@@ -5242,6 +5242,12 @@},"validation": {"non_negative": "muss null oder größer sein"+ },+ "columns": {+ "seller": "Inhaber"+ },+ "owner": {+ "marketplace": "Marktplatz"}}}diff --git a/packages/dashboard/src/locales/en.json b/packages/dashboard/src/locales/en.jsonindex 896b8cc0db..674e2c58e3 100644--- a/packages/dashboard/src/locales/en.json+++ b/packages/dashboard/src/locales/en.json@@ -2357,8 +2357,8 @@"label": "Unit"},"default": {- "label": "Store default box",- "help": "The packaging every parcel quote is built on. Only one per store."+ "label": "Default box",+ "help": "The packaging your parcel quotes are built on. One default at a time."}}},@@ -5218,9 +5218,9 @@"search_placeholder": "Search packaging","empty": "No packaging yet. Add the box you ship in, and the cartons and pallets wholesale orders leave on.","add_cta": "Add package type",- "default_badge": "Store default",+ "default_badge": "Default","edit_sheet_title": "Package type",- "create_description": "A box, carton, pallet or container this store packs goods into.",+ "create_description": "A box, carton, pallet or container goods are packed into.","edit_description": "Products packed into this carton follow its measurements, so one edit corrects them all.","dimensions_column": "Dimensions","volume_column": "Volume",@@ -5242,6 +5242,12 @@},"validation": {"non_negative": "must be zero or more"+ },+ "columns": {+ "seller": "Owner"+ },+ "owner": {+ "marketplace": "Marketplace"}}}diff --git a/packages/dashboard/src/locales/fr.json b/packages/dashboard/src/locales/fr.jsonindex 5d0433b2a4..8e6fa2a6d6 100644--- a/packages/dashboard/src/locales/fr.json+++ b/packages/dashboard/src/locales/fr.json@@ -2357,8 +2357,8 @@"label": "Unité"},"default": {- "label": "Carton par défaut",- "help": "La base de chaque cotation colis. Un seul par boutique."+ "label": "Emballage par défaut",+ "help": "L'emballage sur lequel vos tarifs de colis sont calculés. Un seul par défaut à la fois."}}},@@ -5220,7 +5220,7 @@"add_cta": "Ajouter un type d'emballage","default_badge": "Par défaut","edit_sheet_title": "Type d'emballage",- "create_description": "Un carton, une palette ou un conteneur dans lequel cette boutique emballe ses produits.",+ "create_description": "Une boîte, un carton, une palette ou un conteneur dans lequel les marchandises sont emballées.","edit_description": "Les produits emballés dans ce carton suivent ses dimensions : une modification les corrige tous.","dimensions_column": "Dimensions","volume_column": "Volume",@@ -5242,6 +5242,12 @@},"validation": {"non_negative": "doit être supérieur ou égal à zéro"+ },+ "columns": {+ "seller": "Propriétaire"+ },+ "owner": {+ "marketplace": "Place de marché"}}}diff --git a/packages/dashboard/src/locales/pl.json b/packages/dashboard/src/locales/pl.jsonindex 630796ea63..04b67323c7 100644--- a/packages/dashboard/src/locales/pl.json+++ b/packages/dashboard/src/locales/pl.json@@ -2375,8 +2375,8 @@"label": "Jednostka"},"default": {- "label": "Domyślny karton sklepu",- "help": "Podstawa każdej wyceny paczki. Tylko jeden na sklep."+ "label": "Domyślne opakowanie",+ "help": "Opakowanie, na którym opierają się wyceny Twoich przesyłek. Tylko jedno domyślne naraz."}}},@@ -5276,9 +5276,9 @@"search_placeholder": "Szukaj opakowania","empty": "Brak opakowań. Dodaj karton wysyłkowy oraz kartony i palety dla zamówień hurtowych.","add_cta": "Dodaj rodzaj opakowania",- "default_badge": "Domyślne sklepu",+ "default_badge": "Domyślne","edit_sheet_title": "Rodzaj opakowania",- "create_description": "Karton, paleta lub kontener, w który ten sklep pakuje towar.",+ "create_description": "Pudełko, karton, paleta lub kontener, w które pakowane są towary.","edit_description": "Produkty pakowane w ten karton przyjmują jego wymiary — jedna zmiana poprawia wszystkie.","dimensions_column": "Wymiary","volume_column": "Objętość",@@ -5300,6 +5300,12 @@},"validation": {"non_negative": "musi wynosić zero lub więcej"+ },+ "columns": {+ "seller": "Właściciel"+ },+ "owner": {+ "marketplace": "Marketplace"}}}diff --git a/packages/dashboard/src/locales/zh-CN.json b/packages/dashboard/src/locales/zh-CN.jsonindex 54cf0cfc66..9ff6ef2a5c 100644--- a/packages/dashboard/src/locales/zh-CN.json+++ b/packages/dashboard/src/locales/zh-CN.json@@ -2352,8 +2352,8 @@"label": "单位"},"default": {- "label": "店铺默认纸箱",- "help": "所有包裹报价的基础。每个店铺仅一个。"+ "label": "默认包装",+ "help": "您的包裹报价所依据的包装。同一时间只能有一个默认包装。"}}},@@ -5209,9 +5209,9 @@"search_placeholder": "搜索包装","empty": "尚无包装。请添加发货纸箱,以及批发订单使用的外箱和托盘。","add_cta": "添加包装类型",- "default_badge": "店铺默认",+ "default_badge": "默认","edit_sheet_title": "包装类型",- "create_description": "本店用于装载商品的纸箱、外箱、托盘或集装箱。",+ "create_description": "用于装载商品的箱、纸箱、托盘或集装箱。","edit_description": "装入此外箱的商品沿用其尺寸,修改一次即可全部更正。","dimensions_column": "尺寸","volume_column": "体积",@@ -5233,6 +5233,12 @@},"validation": {"non_negative": "必须大于或等于零"+ },+ "columns": {+ "seller": "所有者"+ },+ "owner": {+ "marketplace": "市场平台"}}}diff --git a/packages/dashboard/src/routes/_authenticated/$storeId/settings/package-types.tsx b/packages/dashboard/src/routes/_authenticated/$storeId/settings/package-types.tsxindex bd9829f142..e1794f2625 100644--- a/packages/dashboard/src/routes/_authenticated/$storeId/settings/package-types.tsx+++ b/packages/dashboard/src/routes/_authenticated/$storeId/settings/package-types.tsx@@ -1,495 +1,25 @@-import { zodResolver } from '@hookform/resolvers/zod'-import type { PackageType, PackageTypeCreateParams } from '@spree/admin-sdk'-import {- adminClient,- Can,- i18n,- mapSpreeErrorsToForm,- ResourceTable,- resourceSearchSchema,- Subject,- usePermissions,-} from '@spree/dashboard-core'-import {- Button,- Field,- FieldDescription,- FieldError,- FieldGroup,- FieldLabel,- Input,- RowActions,- requiredMessage,- Select,- SelectContent,- SelectItem,- SelectTrigger,- SelectValue,- Sheet,- SheetContent,- SheetDescription,- SheetFooter,- SheetHeader,- SheetTitle,- Switch,- useConfirm,- useRowClickBridge,-} from '@spree/dashboard-ui'-import { PlusIcon } from '@spree/dashboard-ui/icons'-import { createFileRoute, useNavigate } from '@tanstack/react-router'-import { Controller, type UseFormReturn, useForm } from 'react-hook-form'-import { useTranslation } from 'react-i18next'-import { z } from 'zod/v4'-import {- useCreatePackageType,- useDeletePackageType,- usePackageType,- useUpdatePackageType,-} from '../../../../hooks/use-package-types'+import { PackageTypesPage, packageTypesSearchSchema } from '@spree/dashboard-core'+import { createFileRoute } from '@tanstack/react-router'+import type { z } from 'zod/v4'+// Adds the seller column to the shared table — operator-only, see the file.import '../../../../tables/package-types'-// The vocabulary the server validates against; typing anything else could-// only fail on save.-const KINDS = ['box', 'envelope', 'carton', 'pallet', 'container'] as const-const DIMENSION_UNITS = ['mm', 'cm', 'in', 'ft'] as const-const WEIGHT_UNITS = ['g', 'kg', 'lb', 'oz'] as const--// Blank is how a merchant says "not measured", so every number is optional-// and an empty string reaches the API as null rather than zero — a box-// recorded as zero long, zero wide is not the same as one nobody measured.-const optionalNumber = z- .union([z.string(), z.number()])- .optional()- .refine(- (value) =>- value === '' || value === undefined || (!Number.isNaN(Number(value)) && Number(value) >= 0),- {- error: () => i18n.t('admin.package_types.validation.non_negative'),- },- )--const packageTypeFormSchema = z.object({- name: z- .string()- .trim()- .min(1, { error: requiredMessage('package_type.name') }),- kind: z.enum(KINDS),- length: optionalNumber,- width: optionalNumber,- height: optionalNumber,- dimensions_unit: z.enum(DIMENSION_UNITS).optional(),- weight: optionalNumber,- max_weight: optionalNumber,- weight_unit: z.enum(WEIGHT_UNITS).optional(),- default: z.boolean().optional(),-})--type PackageTypeFormValues = z.input<typeof packageTypeFormSchema>--// Blank erases a measurement, so it has to reach the API as an explicit null;-// undefined would leave whatever was recorded before untouched.-function toParams(values: PackageTypeFormValues): PackageTypeCreateParams {- const measurement = (value: string | number | undefined) =>- value === '' || value === undefined ? null : Number(value)-- return {- name: values.name,- kind: values.kind,- length: measurement(values.length),- width: measurement(values.width),- height: measurement(values.height),- weight: measurement(values.weight),- max_weight: measurement(values.max_weight),- dimensions_unit: values.dimensions_unit,- weight_unit: values.weight_unit,- default: values.default,- }-}--const DEFAULT_VALUES: PackageTypeFormValues = {- name: '',- kind: 'box',- length: '',- width: '',- height: '',- dimensions_unit: 'cm',- weight: '',- max_weight: '',- weight_unit: 'kg',- default: false,-}--const packageTypesSearchSchema = resourceSearchSchema.extend({- edit: z.string().optional(),- new: z.coerce.boolean().optional(),-})-export const Route = createFileRoute('/_authenticated/$storeId/settings/package-types')({validateSearch: packageTypesSearchSchema,- component: PackageTypesPage,+ component: PackageTypesRoute,})-function PackageTypesPage() {- const { t } = useTranslation()+/**+ * The page itself lives in `@spree/dashboard-core` so the marketplace seller+ * panel renders the same one. What stays here is the route (paths differ per+ * panel, and file routes are generated per app) and the owner column, which+ * only the operator's list needs.+ */+function PackageTypesRoute() {+ // Cast: the inferred search type unions with the parent layout's shape,+ // which does not know about our `edit`/`new` keys. The runtime schema is+ // still the source of truth — this gets past the parent-union narrowing.const search = Route.useSearch() as z.infer<typeof packageTypesSearchSchema>- const navigate = useNavigate()- const confirm = useConfirm()- const deleteMutation = useDeletePackageType()- const { permissions } = usePermissions()-- const isCreating = !!search.new- const editId = isCreating ? undefined : search.edit-- const closeSheet = () =>- navigate({- search: (prev: Record<string, unknown>) => {- const { edit: _e, new: _n, ...rest } = prev- return rest as never- },- })-- const openCreate = () =>- navigate({- search: (prev: Record<string, unknown>) => {- const { edit: _e, ...rest } = prev- return { ...rest, new: true } as never- },- })-- const openEdit = (id: string) =>- navigate({- search: (prev: Record<string, unknown>) => {- const { new: _n, ...rest } = prev- return { ...rest, edit: id } as never- },- })-- useRowClickBridge('data-package-type-id', openEdit)-- async function handleDelete(packageType: PackageType) {- const ok = await confirm({- title: t('admin.package_types.delete_confirm.title'),- message: t('admin.package_types.delete_confirm.message', { name: packageType.name }),- variant: 'destructive',- confirmLabel: t('admin.actions.delete'),- })- if (!ok) return- await deleteMutation.mutateAsync(packageType.id).catch(() => undefined)- }-- return (- <>- <ResourceTable<PackageType>- tableKey="package-types"- queryKey="package-types"- queryFn={(params) => adminClient.packageTypes.list(params)}- searchParams={search}- rowActions={(packageType) => (- <RowActions- actions={[- { key: 'edit', onSelect: () => openEdit(packageType.id) },- {- key: 'delete',- destructive: true,- visible: permissions.can('destroy', Subject.PackageType),- disabled: deleteMutation.isPending,- onSelect: () => handleDelete(packageType),- },- ]}- />- )}- actions={- <Can I="create" a={Subject.PackageType}>- <Button size="sm" className="h-[2.125rem]" onClick={openCreate}>- <PlusIcon className="size-4" />- {t('admin.package_types.add_cta')}- </Button>- </Can>- }- />-- {isCreating && <CreatePackageTypeSheet open onOpenChange={(o) => !o && closeSheet()} />}- {editId && <EditPackageTypeSheet id={editId} open onOpenChange={(o) => !o && closeSheet()} />}- </>- )-}--function CreatePackageTypeSheet({- open,- onOpenChange,-}: {- open: boolean- onOpenChange: (open: boolean) => void-}) {- const { t } = useTranslation()- const createMutation = useCreatePackageType()- const form = useForm<PackageTypeFormValues>({- resolver: zodResolver(packageTypeFormSchema),- defaultValues: DEFAULT_VALUES,- })-- async function onSubmit(values: PackageTypeFormValues) {- try {- await createMutation.mutateAsync(toParams(values))- form.reset(DEFAULT_VALUES)- onOpenChange(false)- } catch (err) {- if (!mapSpreeErrorsToForm(err, form.setError)) throw err- }- }-- return (- <Sheet- open={open}- onOpenChange={(next) => {- if (!next) form.reset(DEFAULT_VALUES)- onOpenChange(next)- }}- >- <SheetContent>- <SheetHeader>- <SheetTitle>{t('admin.pages.settings.package_types.add_sheet_title')}</SheetTitle>- <SheetDescription>{t('admin.package_types.create_description')}</SheetDescription>- </SheetHeader>- <form onSubmit={form.handleSubmit(onSubmit)} className="flex min-h-0 flex-1 flex-col">- <div className="flex flex-1 flex-col gap-4 overflow-y-auto p-4">- <PackageTypeFormFields form={form} />- </div>- <SheetFooter>- <Button type="submit" disabled={createMutation.isPending}>- {t('admin.actions.save')}- </Button>- </SheetFooter>- </form>- </SheetContent>- </Sheet>- )-}--function EditPackageTypeSheet({- id,- open,- onOpenChange,-}: {- id: string- open: boolean- onOpenChange: (open: boolean) => void-}) {- const { t } = useTranslation()- const { data: packageType } = usePackageType(id)- const updateMutation = useUpdatePackageType(id)- const form = useForm<PackageTypeFormValues>({- resolver: zodResolver(packageTypeFormSchema),- defaultValues: DEFAULT_VALUES,- values: packageType- ? {- name: packageType.name,- kind: packageType.kind as (typeof KINDS)[number],- length: packageType.length ?? '',- width: packageType.width ?? '',- height: packageType.height ?? '',- dimensions_unit: packageType.dimensions_unit as (typeof DIMENSION_UNITS)[number],- weight: packageType.weight ?? '',- max_weight: packageType.max_weight ?? '',- weight_unit: packageType.weight_unit as (typeof WEIGHT_UNITS)[number],- default: packageType.default,- }- : undefined,- })-- async function onSubmit(values: PackageTypeFormValues) {- try {- await updateMutation.mutateAsync(toParams(values))- onOpenChange(false)- } catch (err) {- if (!mapSpreeErrorsToForm(err, form.setError)) throw err- }- }-- return (- <Sheet open={open} onOpenChange={onOpenChange}>- <SheetContent>- <SheetHeader>- <SheetTitle>{packageType?.name ?? t('admin.package_types.edit_sheet_title')}</SheetTitle>- <SheetDescription>{t('admin.package_types.edit_description')}</SheetDescription>- </SheetHeader>- <form onSubmit={form.handleSubmit(onSubmit)} className="flex min-h-0 flex-1 flex-col">- <div className="flex flex-1 flex-col gap-4 overflow-y-auto p-4">- <PackageTypeFormFields form={form} />- </div>- <SheetFooter>- <Button type="submit" disabled={updateMutation.isPending}>- {t('admin.actions.save')}- </Button>- </SheetFooter>- </form>- </SheetContent>- </Sheet>- )-}--function PackageTypeFormFields({ form }: { form: UseFormReturn<PackageTypeFormValues> }) {- const { t } = useTranslation()- const errors = form.formState.errors-- return (- <FieldGroup>- <Field>- <FieldLabel htmlFor="package-type-name">- {t('admin.fields.package_type.name.label')}- </FieldLabel>- <Input id="package-type-name" {...form.register('name')} aria-invalid={!!errors.name} />- <FieldError errors={[errors.name]} />- </Field>-- <Field>- <FieldLabel htmlFor="package-type-kind">- {t('admin.fields.package_type.kind.label')}- </FieldLabel>- <Controller- control={form.control}- name="kind"- render={({ field }) => {- const options = KINDS.map((kind) => ({- value: kind,- label: t(`admin.package_types.kinds.${kind}`),- }))- return (- <Select items={options} value={field.value} onValueChange={field.onChange}>- <SelectTrigger id="package-type-kind">- <SelectValue />- </SelectTrigger>- <SelectContent>- {options.map((option) => (- <SelectItem key={option.value} value={option.value}>- {option.label}- </SelectItem>- ))}- </SelectContent>- </Select>- )- }}- />- <FieldDescription>{t('admin.fields.package_type.kind.help')}</FieldDescription>- </Field>-- <div className="grid grid-cols-[1fr_1fr_1fr_110px] gap-3">- {(['length', 'width', 'height'] as const).map((side) => (- <Field key={side}>- <FieldLabel htmlFor={`package-type-${side}`}>- {t(`admin.fields.package_type.${side}.label`)}- </FieldLabel>- <Input- id={`package-type-${side}`}- type="number"- min="0"- step="0.01"- {...form.register(side)}- />- </Field>- ))}- <UnitField- form={form}- name="dimensions_unit"- units={DIMENSION_UNITS}- label={t('admin.fields.package_type.dimensions_unit.label')}- />- </div>- <FieldDescription>{t('admin.fields.package_type.dimensions.help')}</FieldDescription>-- <div className="grid grid-cols-[1fr_1fr_110px] gap-3">- <Field>- <FieldLabel htmlFor="package-type-weight">- {t('admin.fields.package_type.weight.label')}- </FieldLabel>- <Input- id="package-type-weight"- type="number"- min="0"- step="0.01"- {...form.register('weight')}- />- <FieldDescription>{t('admin.fields.package_type.weight.help')}</FieldDescription>- </Field>- <Field>- <FieldLabel htmlFor="package-type-max-weight">- {t('admin.fields.package_type.max_weight.label')}- </FieldLabel>- <Input- id="package-type-max-weight"- type="number"- min="0"- step="0.01"- {...form.register('max_weight')}- />- <FieldDescription>{t('admin.fields.package_type.max_weight.help')}</FieldDescription>- </Field>- <UnitField- form={form}- name="weight_unit"- units={WEIGHT_UNITS}- label={t('admin.fields.package_type.weight_unit.label')}- />- </div>-- <Field>- <div className="flex items-start justify-between gap-4">- <FieldLabel htmlFor="package-type-default" className="cursor-pointer">- {t('admin.fields.package_type.default.label')}- </FieldLabel>- <Controller- control={form.control}- name="default"- render={({ field }) => (- <Switch- id="package-type-default"- checked={!!field.value}- onCheckedChange={field.onChange}- />- )}- />- </div>- <FieldDescription>{t('admin.fields.package_type.default.help')}</FieldDescription>- </Field>- </FieldGroup>- )-}-function UnitField({- form,- name,- units,- label,-}: {- form: UseFormReturn<PackageTypeFormValues>- name: 'dimensions_unit' | 'weight_unit'- units: readonly string[]- label: string-}) {- return (- <Field>- <FieldLabel htmlFor={`package-type-${name}`}>{label}</FieldLabel>- <Controller- control={form.control}- name={name}- render={({ field }) => {- const options = units.map((unit) => ({ value: unit, label: unit }))- return (- <Select items={options} value={field.value ?? ''} onValueChange={field.onChange}>- <SelectTrigger id={`package-type-${name}`}>- <SelectValue />- </SelectTrigger>- <SelectContent>- {options.map((option) => (- <SelectItem key={option.value} value={option.value}>- {option.label}- </SelectItem>- ))}- </SelectContent>- </Select>- )- }}- />- </Field>- )+ return <PackageTypesPage search={search} />}diff --git a/packages/dashboard/src/tables/package-types.tsx b/packages/dashboard/src/tables/package-types.tsxindex 344ecb9579..d2d897db07 100644--- a/packages/dashboard/src/tables/package-types.tsx+++ b/packages/dashboard/src/tables/package-types.tsx@@ -1,68 +1,41 @@import type { PackageType } from '@spree/admin-sdk'-import { defineTable } from '@spree/dashboard-core'-import { RelativeTime, ResourceNameCell } from '@spree/dashboard-ui'-import { PackageIcon } from '@spree/dashboard-ui/icons'+import { tables } from '@spree/dashboard-core'+import { Badge } from '@spree/dashboard-ui'import i18n from 'i18next'+import { sellerAutocompleteProps } from '../hooks/use-sellers'-defineTable<PackageType>('package-types', {- title: i18n.t('admin.package_types.table_title'),- searchParam: 'name_cont',- searchPlaceholder: i18n.t('admin.package_types.search_placeholder'),- defaultSort: { field: 'name', direction: 'asc' },- emptyIcon: <PackageIcon className="size-8 text-muted-foreground" />,- emptyMessage: i18n.t('admin.package_types.empty'),- columns: [- {- key: 'name',- label: i18n.t('admin.fields.package_type.name.label'),- sortable: true,- default: true,- render: (packageType) => (- <ResourceNameCell- id={packageType.id}- dataAttr="data-package-type-id"- name={packageType.name}- // The store's own box, called out because every parcel quote is- // built on it.- secondary={packageType.default ? i18n.t('admin.package_types.default_badge') : undefined}- />- ),- },- {- key: 'kind',- label: i18n.t('admin.fields.package_type.kind.label'),- sortable: true,- default: true,- render: (packageType) => i18n.t(`admin.package_types.kinds.${packageType.kind}`),- },- {- key: 'dimensions',- label: i18n.t('admin.package_types.dimensions_column'),- default: true,- className: 'text-sm text-muted-foreground whitespace-nowrap',- // Three numbers mean nothing without the unit they were measured in —- // the same figures read as inches or centimetres differ sixteenfold by- // volume, which is what the freight tiers compare.- render: (packageType) =>- packageType.length && packageType.width && packageType.height- ? `${packageType.length} × ${packageType.width} × ${packageType.height} ${packageType.dimensions_unit}`- : '—',- },- {- key: 'volume',- label: i18n.t('admin.package_types.volume_column'),- className: 'text-sm text-muted-foreground whitespace-nowrap',- render: (packageType) =>- packageType.volume ? `${Number(packageType.volume).toFixed(3)} m³` : '—',- },- {- key: 'created_at',- label: i18n.t('admin.fields.created_at.label'),- sortable: true,- filterable: true,- filterType: 'date',- className: 'text-sm text-muted-foreground whitespace-nowrap',- render: (packageType) => <RelativeTime iso={packageType.created_at} />,- },- ],+/**+ * Adds one column to the shared package-types table: whose packaging a row is.+ *+ * It belongs to the operator alone. On a marketplace their list holds the+ * marketplace's own boxes and every seller's together, and without this the+ * two are indistinguishable — while in a seller's panel the list is their own+ * rows plus the marketplace's, which the read-only rows already say.+ *+ * A column added to the shared definition rather than a second table: the+ * registry exists for exactly this, and a fork would have to be kept in step+ * with the original by hand.+ */+tables['package-types'].addColumn<PackageType>({+ key: 'seller_id',+ label: i18n.t('admin.package_types.columns.seller'),+ default: true,+ filterable: true,+ filterType: 'resource',+ // `seller_id` — whitelisted on PackageType alongside the `seller`+ // association, so the filter narrows to one or more sellers.+ //+ // It cannot yet ask for "the marketplace's own" (a null owner): the+ // resource filter emits ids only, and asking for NULL needs a scope and a+ // filter type neither this table nor the stock-locations column beside it+ // has. The column still labels those rows, so they are readable if not+ // filterable.+ ransackAttribute: 'seller_id',+ filterResource: sellerAutocompleteProps('package-type-seller-picker'),+ render: (packageType) =>+ packageType.seller_name ? (+ <Badge variant="outline">{packageType.seller_name}</Badge>+ ) : (+ i18n.t('admin.package_types.owner.marketplace')+ ),})diff --git a/packages/seller-dashboard-starter/src/routeTree.gen.ts b/packages/seller-dashboard-starter/src/routeTree.gen.tsindex e6541b2fcd..defb90a8bf 100644--- a/packages/seller-dashboard-starter/src/routeTree.gen.ts+++ b/packages/seller-dashboard-starter/src/routeTree.gen.ts@@ -26,6 +26,7 @@ import { Route as OrdersIndexRouteImport } from './../../seller-dashboard/src/roimport { Route as SettingsTeamRouteImport } from './../../seller-dashboard/src/routes/_authenticated/$sellerId/settings/team'import { Route as SettingsStockLocationsRouteImport } from './../../seller-dashboard/src/routes/_authenticated/$sellerId/settings/stock-locations'import { Route as SettingsPoliciesRouteImport } from './../../seller-dashboard/src/routes/_authenticated/$sellerId/settings/policies'+import { Route as SettingsPackageTypesRouteImport } from './../../seller-dashboard/src/routes/_authenticated/$sellerId/settings/package-types'import { Route as SettingsDeliveryMethodsRouteImport } from './../../seller-dashboard/src/routes/_authenticated/$sellerId/settings/delivery-methods'import { Route as ProductsNewRouteImport } from './../../seller-dashboard/src/routes/_authenticated/$sellerId/products/new'import { Route as ProductsProductIdRouteImport } from './../../seller-dashboard/src/routes/_authenticated/$sellerId/products/$productId'@@ -116,6 +117,11 @@ const SettingsPoliciesRoute = SettingsPoliciesRouteImport.update({path: '/policies',getParentRoute: () => SettingsRoute,} as any)+const SettingsPackageTypesRoute = SettingsPackageTypesRouteImport.update({+ id: '/package-types',+ path: '/package-types',+ getParentRoute: () => SettingsRoute,+} as any)const SettingsDeliveryMethodsRoute = SettingsDeliveryMethodsRouteImport.update({id: '/delivery-methods',path: '/delivery-methods',@@ -152,6 +158,7 @@ export interface FileRoutesByFullPath {'/$sellerId/products/$productId': typeof ProductsProductIdRoute'/$sellerId/products/new': typeof ProductsNewRoute'/$sellerId/settings/delivery-methods': typeof SettingsDeliveryMethodsRoute+ '/$sellerId/settings/package-types': typeof SettingsPackageTypesRoute'/$sellerId/settings/policies': typeof SettingsPoliciesRoute'/$sellerId/settings/stock-locations': typeof SettingsStockLocationsRoute'/$sellerId/settings/team': typeof SettingsTeamRoute@@ -172,6 +179,7 @@ export interface FileRoutesByTo {'/$sellerId/products/$productId': typeof ProductsProductIdRoute'/$sellerId/products/new': typeof ProductsNewRoute'/$sellerId/settings/delivery-methods': typeof SettingsDeliveryMethodsRoute+ '/$sellerId/settings/package-types': typeof SettingsPackageTypesRoute'/$sellerId/settings/policies': typeof SettingsPoliciesRoute'/$sellerId/settings/stock-locations': typeof SettingsStockLocationsRoute'/$sellerId/settings/team': typeof SettingsTeamRoute@@ -196,6 +204,7 @@ export interface FileRoutesById {'/_authenticated/$sellerId/products/$productId': typeof ProductsProductIdRoute'/_authenticated/$sellerId/products/new': typeof ProductsNewRoute'/_authenticated/$sellerId/settings/delivery-methods': typeof SettingsDeliveryMethodsRoute+ '/_authenticated/$sellerId/settings/package-types': typeof SettingsPackageTypesRoute'/_authenticated/$sellerId/settings/policies': typeof SettingsPoliciesRoute'/_authenticated/$sellerId/settings/stock-locations': typeof SettingsStockLocationsRoute'/_authenticated/$sellerId/settings/team': typeof SettingsTeamRoute@@ -220,6 +229,7 @@ export interface FileRouteTypes {| '/$sellerId/products/$productId'| '/$sellerId/products/new'| '/$sellerId/settings/delivery-methods'+ | '/$sellerId/settings/package-types'| '/$sellerId/settings/policies'| '/$sellerId/settings/stock-locations'| '/$sellerId/settings/team'@@ -240,6 +250,7 @@ export interface FileRouteTypes {| '/$sellerId/products/$productId'| '/$sellerId/products/new'| '/$sellerId/settings/delivery-methods'+ | '/$sellerId/settings/package-types'| '/$sellerId/settings/policies'| '/$sellerId/settings/stock-locations'| '/$sellerId/settings/team'@@ -263,6 +274,7 @@ export interface FileRouteTypes {| '/_authenticated/$sellerId/products/$productId'| '/_authenticated/$sellerId/products/new'| '/_authenticated/$sellerId/settings/delivery-methods'+ | '/_authenticated/$sellerId/settings/package-types'| '/_authenticated/$sellerId/settings/policies'| '/_authenticated/$sellerId/settings/stock-locations'| '/_authenticated/$sellerId/settings/team'@@ -400,6 +412,13 @@ declare module '@tanstack/react-router' {preLoaderRoute: typeof SettingsPoliciesRouteImportparentRoute: typeof SettingsRoute}+ '/_authenticated/$sellerId/settings/package-types': {+ id: '/_authenticated/$sellerId/settings/package-types'+ path: '/package-types'+ fullPath: '/$sellerId/settings/package-types'+ preLoaderRoute: typeof SettingsPackageTypesRouteImport+ parentRoute: typeof SettingsRoute+ }'/_authenticated/$sellerId/settings/delivery-methods': {id: '/_authenticated/$sellerId/settings/delivery-methods'path: '/delivery-methods'@@ -433,6 +452,7 @@ declare module '@tanstack/react-router' {interface SettingsRouteChildren {SettingsDeliveryMethodsRoute: typeof SettingsDeliveryMethodsRoute+ SettingsPackageTypesRoute: typeof SettingsPackageTypesRouteSettingsPoliciesRoute: typeof SettingsPoliciesRouteSettingsStockLocationsRoute: typeof SettingsStockLocationsRouteSettingsTeamRoute: typeof SettingsTeamRoute@@ -441,6 +461,7 @@ interface SettingsRouteChildren {const SettingsRouteChildren: SettingsRouteChildren = {SettingsDeliveryMethodsRoute: SettingsDeliveryMethodsRoute,+ SettingsPackageTypesRoute: SettingsPackageTypesRoute,SettingsPoliciesRoute: SettingsPoliciesRoute,SettingsStockLocationsRoute: SettingsStockLocationsRoute,SettingsTeamRoute: SettingsTeamRoute,diff --git a/packages/seller-dashboard/src/api-client.ts b/packages/seller-dashboard/src/api-client.tsindex 39076eca2a..83827b62b1 100644--- a/packages/seller-dashboard/src/api-client.ts+++ b/packages/seller-dashboard/src/api-client.ts@@ -126,6 +126,17 @@ export function createSellerApiClient({get: (id) => sellerClient().productTypes.get(id),},deliveryProfiles: { list: (params) => sellerClient().deliveryProfiles.list(params) },+ // What this seller packs into: their own boxes and cartons, plus the+ // marketplace's shared packaging, which the API lists read-only. Backs+ // both the packaging settings page and the variant editor's carton+ // picker (docs/plans/6.0-seller-package-types.md).+ packageTypes: {+ list: (params) => sellerClient().packageTypes.list(params),+ get: (id) => sellerClient().packageTypes.get(id),+ create: (params) => sellerClient().packageTypes.create(params),+ update: (id, params) => sellerClient().packageTypes.update(id, params),+ delete: (id) => sellerClient().packageTypes.delete(id),+ },})return clientdiff --git a/packages/seller-dashboard/src/locales/en.json b/packages/seller-dashboard/src/locales/en.jsonindex 743ca1a2e9..6853d3c5fb 100644--- a/packages/seller-dashboard/src/locales/en.json+++ b/packages/seller-dashboard/src/locales/en.json@@ -302,7 +302,8 @@"settings": "Settings","sign_out": "Sign out","team": "Team",- "delivery_methods": "Delivery methods"+ "delivery_methods": "Delivery methods",+ "package_types": "Package types"},"onboarding": {"accept_terms": "Accept the terms",diff --git a/packages/seller-dashboard/src/nav/settings.ts b/packages/seller-dashboard/src/nav/settings.tsindex 691f86492d..dc20481a8a 100644--- a/packages/seller-dashboard/src/nav/settings.ts+++ b/packages/seller-dashboard/src/nav/settings.ts@@ -1,5 +1,11 @@import { i18n, settingsNav } from '@spree/dashboard-core'-import { ScrollTextIcon, TruckIcon, UsersRoundIcon, WarehouseIcon } from '@spree/dashboard-ui/icons'+import {+ PackageIcon,+ ScrollTextIcon,+ TruckIcon,+ UsersRoundIcon,+ WarehouseIcon,+} from '@spree/dashboard-ui/icons'// The panel's settings rail, registered into the same registry the operator's// dashboard writes to — so a marketplace adds, removes or reorders entries@@ -53,6 +59,21 @@ settingsNav.add({subject: 'Spree::DeliveryMethod',})+// What this seller packs their goods into. Beside the other two because the+// three answer one question together: where the goods are, how they leave,+// and what they leave in (docs/plans/6.0-seller-package-types.md).+settingsNav.add({+ key: 'settings.package-types',+ label: i18n.t('nav.package_types'),+ path: '/package-types',+ icon: PackageIcon,+ group: 'fulfillment',+ position: 300,+ // The seller-branch subject the API's `/me` serializes. A member without+ // packaging permission never sees the entry.+ subject: 'Spree::PackageType',+})+// Who runs this seller. Under settings rather than in the main rail, matching// where the operator's dashboard puts its own staff page: managing people is// configuration, not day-to-day selling.diff --git a/packages/seller-dashboard/src/pages/onboarding.tsx b/packages/seller-dashboard/src/pages/onboarding.tsxindex 6dec7eb16b..ce3f2a7b71 100644--- a/packages/seller-dashboard/src/pages/onboarding.tsx+++ b/packages/seller-dashboard/src/pages/onboarding.tsx@@ -494,6 +494,10 @@ function panelRoute(kind: string): string | undefined {return '/$sellerId/profile'case 'policy':return '/$sellerId/settings/policies'+ case 'delivery_method':+ return '/$sellerId/settings/delivery-methods'+ case 'package_type':+ return '/$sellerId/settings/package-types'// `required_custom_fields` is not here: it renders its own fields inline,// so a link away would offer a second, worse route to the same thing.//diff --git a/packages/seller-dashboard/src/routeTree.gen.ts b/packages/seller-dashboard/src/routeTree.gen.tsindex 8dab7d7cc9..7ec2f094d5 100644--- a/packages/seller-dashboard/src/routeTree.gen.ts+++ b/packages/seller-dashboard/src/routeTree.gen.ts@@ -26,6 +26,7 @@ import { Route as OrdersIndexRouteImport } from './routes/_authenticated/$sellerimport { Route as SettingsTeamRouteImport } from './routes/_authenticated/$sellerId/settings/team'import { Route as SettingsStockLocationsRouteImport } from './routes/_authenticated/$sellerId/settings/stock-locations'import { Route as SettingsPoliciesRouteImport } from './routes/_authenticated/$sellerId/settings/policies'+import { Route as SettingsPackageTypesRouteImport } from './routes/_authenticated/$sellerId/settings/package-types'import { Route as SettingsDeliveryMethodsRouteImport } from './routes/_authenticated/$sellerId/settings/delivery-methods'import { Route as ProductsNewRouteImport } from './routes/_authenticated/$sellerId/products/new'import { Route as ProductsProductIdRouteImport } from './routes/_authenticated/$sellerId/products/$productId'@@ -116,6 +117,11 @@ const SettingsPoliciesRoute = SettingsPoliciesRouteImport.update({path: '/policies',getParentRoute: () => SettingsRoute,} as any)+const SettingsPackageTypesRoute = SettingsPackageTypesRouteImport.update({+ id: '/package-types',+ path: '/package-types',+ getParentRoute: () => SettingsRoute,+} as any)const SettingsDeliveryMethodsRoute = SettingsDeliveryMethodsRouteImport.update({id: '/delivery-methods',path: '/delivery-methods',@@ -152,6 +158,7 @@ export interface FileRoutesByFullPath {'/$sellerId/products/$productId': typeof ProductsProductIdRoute'/$sellerId/products/new': typeof ProductsNewRoute'/$sellerId/settings/delivery-methods': typeof SettingsDeliveryMethodsRoute+ '/$sellerId/settings/package-types': typeof SettingsPackageTypesRoute'/$sellerId/settings/policies': typeof SettingsPoliciesRoute'/$sellerId/settings/stock-locations': typeof SettingsStockLocationsRoute'/$sellerId/settings/team': typeof SettingsTeamRoute@@ -172,6 +179,7 @@ export interface FileRoutesByTo {'/$sellerId/products/$productId': typeof ProductsProductIdRoute'/$sellerId/products/new': typeof ProductsNewRoute'/$sellerId/settings/delivery-methods': typeof SettingsDeliveryMethodsRoute+ '/$sellerId/settings/package-types': typeof SettingsPackageTypesRoute'/$sellerId/settings/policies': typeof SettingsPoliciesRoute'/$sellerId/settings/stock-locations': typeof SettingsStockLocationsRoute'/$sellerId/settings/team': typeof SettingsTeamRoute@@ -196,6 +204,7 @@ export interface FileRoutesById {'/_authenticated/$sellerId/products/$productId': typeof ProductsProductIdRoute'/_authenticated/$sellerId/products/new': typeof ProductsNewRoute'/_authenticated/$sellerId/settings/delivery-methods': typeof SettingsDeliveryMethodsRoute+ '/_authenticated/$sellerId/settings/package-types': typeof SettingsPackageTypesRoute'/_authenticated/$sellerId/settings/policies': typeof SettingsPoliciesRoute'/_authenticated/$sellerId/settings/stock-locations': typeof SettingsStockLocationsRoute'/_authenticated/$sellerId/settings/team': typeof SettingsTeamRoute@@ -220,6 +229,7 @@ export interface FileRouteTypes {| '/$sellerId/products/$productId'| '/$sellerId/products/new'| '/$sellerId/settings/delivery-methods'+ | '/$sellerId/settings/package-types'| '/$sellerId/settings/policies'| '/$sellerId/settings/stock-locations'| '/$sellerId/settings/team'@@ -240,6 +250,7 @@ export interface FileRouteTypes {| '/$sellerId/products/$productId'| '/$sellerId/products/new'| '/$sellerId/settings/delivery-methods'+ | '/$sellerId/settings/package-types'| '/$sellerId/settings/policies'| '/$sellerId/settings/stock-locations'| '/$sellerId/settings/team'@@ -263,6 +274,7 @@ export interface FileRouteTypes {| '/_authenticated/$sellerId/products/$productId'| '/_authenticated/$sellerId/products/new'| '/_authenticated/$sellerId/settings/delivery-methods'+ | '/_authenticated/$sellerId/settings/package-types'| '/_authenticated/$sellerId/settings/policies'| '/_authenticated/$sellerId/settings/stock-locations'| '/_authenticated/$sellerId/settings/team'@@ -400,6 +412,13 @@ declare module '@tanstack/react-router' {preLoaderRoute: typeof SettingsPoliciesRouteImportparentRoute: typeof SettingsRoute}+ '/_authenticated/$sellerId/settings/package-types': {+ id: '/_authenticated/$sellerId/settings/package-types'+ path: '/package-types'+ fullPath: '/$sellerId/settings/package-types'+ preLoaderRoute: typeof SettingsPackageTypesRouteImport+ parentRoute: typeof SettingsRoute+ }'/_authenticated/$sellerId/settings/delivery-methods': {id: '/_authenticated/$sellerId/settings/delivery-methods'path: '/delivery-methods'@@ -433,6 +452,7 @@ declare module '@tanstack/react-router' {interface SettingsRouteChildren {SettingsDeliveryMethodsRoute: typeof SettingsDeliveryMethodsRoute+ SettingsPackageTypesRoute: typeof SettingsPackageTypesRouteSettingsPoliciesRoute: typeof SettingsPoliciesRouteSettingsStockLocationsRoute: typeof SettingsStockLocationsRouteSettingsTeamRoute: typeof SettingsTeamRoute@@ -441,6 +461,7 @@ interface SettingsRouteChildren {const SettingsRouteChildren: SettingsRouteChildren = {SettingsDeliveryMethodsRoute: SettingsDeliveryMethodsRoute,+ SettingsPackageTypesRoute: SettingsPackageTypesRoute,SettingsPoliciesRoute: SettingsPoliciesRoute,SettingsStockLocationsRoute: SettingsStockLocationsRoute,SettingsTeamRoute: SettingsTeamRoute,diff --git a/packages/seller-dashboard/src/routes/_authenticated/$sellerId/settings/package-types.tsx b/packages/seller-dashboard/src/routes/_authenticated/$sellerId/settings/package-types.tsxnew file mode 100644index 0000000000..7549345889--- /dev/null+++ b/packages/seller-dashboard/src/routes/_authenticated/$sellerId/settings/package-types.tsx@@ -0,0 +1,21 @@+import { PackageTypesPage, packageTypesSearchSchema } from '@spree/dashboard-core'+import { createFileRoute } from '@tanstack/react-router'+import type { z } from 'zod/v4'++export const Route = createFileRoute('/_authenticated/$sellerId/settings/package-types')({+ validateSearch: packageTypesSearchSchema,+ component: PackageTypesRoute,+})++/**+ * The same page the operator's dashboard renders, against this seller's own+ * packaging — the Seller API scopes it, so nothing here has to.+ *+ * No owner column: the list is this seller's rows plus the marketplace's+ * shared packaging, and the read-only rows already say which is which.+ */+function PackageTypesRoute() {+ const search = Route.useSearch() as z.infer<typeof packageTypesSearchSchema>++ return <PackageTypesPage search={search} />+}diff --git a/packages/seller-sdk/src/index.ts b/packages/seller-sdk/src/index.tsindex d58e9642c0..7c8cf4f916 100644--- a/packages/seller-sdk/src/index.ts+++ b/packages/seller-sdk/src/index.ts@@ -17,6 +17,7 @@ export type {MeResponse,OnboardingResponse,OrderAddressParams,+ PackageTypeParams,PermissionRule,ProductParams,ProfileUpdateParams,diff --git a/packages/seller-sdk/src/seller-client.ts b/packages/seller-sdk/src/seller-client.tsindex 368f529ea8..8d19de122e 100644--- a/packages/seller-sdk/src/seller-client.ts+++ b/packages/seller-sdk/src/seller-client.ts@@ -14,6 +14,7 @@ import type {ImportRow,Invitation,Order,+ PackageType,Policy,Product,ProductType,@@ -1108,6 +1109,55 @@ export class SellerClient {}),}+ /**+ * What this seller packs their goods into: the boxes their parcels ship in,+ * the cartons their products are packed into, the pallets a wholesale order+ * leaves on.+ *+ * The listing carries the marketplace's own packaging alongside the+ * seller's, so a seller can pack into the operator's standard cartons+ * rather than re-measuring them. Those rows report `editable: false` and+ * are refused by every write.+ */+ readonly packageTypes = {+ list: (+ params?: ListParams & { owner?: 'mine' } & Record<string, unknown>,+ options?: RequestOptions,+ ): Promise<PaginatedResponse<PackageType>> => {+ // `owner` is a plain query param the controller reads directly, so it+ // is lifted out before the Ransack transform, which would otherwise+ // send it as `q[owner]` and the filter would silently do nothing.+ const { owner, ...listParams } = params ?? {}++ return this.request<PaginatedResponse<PackageType>>('GET', '/package_types', {+ ...options,+ params: {+ ...(params ? transformListParams(listParams) : {}),+ ...(owner ? { owner } : {}),+ },+ })+ },++ get: (id: string, options?: RequestOptions): Promise<PackageType> =>+ this.request<PackageType>('GET', `/package_types/${id}`, options),++ create: (params: PackageTypeParams, options?: RequestOptions): Promise<PackageType> =>+ this.request<PackageType>('POST', '/package_types', { ...options, body: params }),++ update: (+ id: string,+ params: PackageTypeParams,+ options?: RequestOptions,+ ): Promise<PackageType> =>+ this.request<PackageType>('PATCH', `/package_types/${id}`, {+ ...options,+ body: params,+ }),++ delete: (id: string, options?: RequestOptions): Promise<void> =>+ this.request<void>('DELETE', `/package_types/${id}`, options),+ }+/*** This seller's own policy documents — their returns policy, shipping* policy, whatever the marketplace asks them to publish.@@ -1326,6 +1376,25 @@ export interface DeliveryMethodRuleType {preference_schema: DeliveryPreferenceField[]}+/**+ * Measurements a seller records for their own packaging. `default` marks the+ * box their parcels are quoted with — one per seller, so it never displaces+ * the marketplace's.+ */+export interface PackageTypeParams {+ name?: string+ kind?: string+ length?: string | number | null+ width?: string | number | null+ height?: string | number | null+ dimensions_unit?: string | null+ weight?: string | number | null+ max_weight?: string | number | null+ weight_unit?: string | null+ default?: boolean+ metadata?: Record<string, unknown>+}+export interface StockLocationParams {name?: stringcompany?: string | nulldiff --git a/packages/seller-sdk/src/types/generated/PackageType.ts b/packages/seller-sdk/src/types/generated/PackageType.tsnew file mode 100644index 0000000000..ad92b55676--- /dev/null+++ b/packages/seller-sdk/src/types/generated/PackageType.ts@@ -0,0 +1,24 @@+// Typelizer digest 1c6ca1b0d4abaf43f61a41a6cdec1ff8+//+// DO NOT MODIFY: This file was automatically generated by Typelizer.++type PackageType = {+ id: string;+ name: string;+ kind: string;+ length: string | null;+ width: string | null;+ height: string | null;+ weight: string | null;+ max_weight: string | null;+ default: boolean;+ metadata: Record<string, unknown> | null;+ created_at: string;+ updated_at: string;+ dimensions_unit: string;+ weight_unit: string;+ volume: string | null;+ editable: boolean;+}++export default PackageType;diff --git a/packages/seller-sdk/src/types/generated/index.ts b/packages/seller-sdk/src/types/generated/index.tsindex 9a1a09b773..3c3fdddeee 100644--- a/packages/seller-sdk/src/types/generated/index.ts+++ b/packages/seller-sdk/src/types/generated/index.ts@@ -1,4 +1,4 @@-// Typelizer digest a94a938bb67ba4ce4555b3944e9992fe+// Typelizer digest 8136083cbe216215b1c2145e4583d32b//// DO NOT MODIFY: This file was automatically generated by Typelizer.export type { default as Address } from './Address'@@ -28,6 +28,7 @@ export type { default as Invitation } from './Invitation'export type { default as Media } from './Media'export type { default as OrderLineItem } from './OrderLineItem'export type { default as Order } from './Order'+export type { default as PackageType } from './PackageType'export type { default as Policy } from './Policy'export type { default as Product } from './Product'export type { default as ProductSubmission } from './ProductSubmission'diff --git a/spree/api/app/controllers/spree/api/v3/admin/package_types_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/package_types_controller.rbindex 71cf70a889..95bd768e3f 100644--- a/spree/api/app/controllers/spree/api/v3/admin/package_types_controller.rb+++ b/spree/api/app/controllers/spree/api/v3/admin/package_types_controller.rb@@ -3,10 +3,16 @@ module Spreemodule V3module Admin# The store's packaging vocabulary. Marking one row default makes it- # the box every parcel quote is built on; the model demotes whichever- # row held the flag before.+ # the box the store's own parcel quotes are built on; the model+ # demotes whichever row held the flag before.+ #+ # On a marketplace this lists every row in the store, the operator's+ # and each seller's, so `q[seller_id_eq]` narrows it to one owner. A+ # row the operator writes here is the marketplace's: `seller_id` is+ # not writable, and a seller's own packaging is theirs to edit through+ # the seller API (docs/plans/6.0-seller-package-types.md).class PackageTypesController < ResourceController- scoped_resource :settings+ scoped_resource :package_typesprotected@@ -18,6 +24,10 @@ module SpreeSpree.api.admin_package_type_serializerend+ def collection_includes+ [:seller]+ end+def resource_permitted_attributes[:name, :kind, :length, :width, :height, :dimensions_unit,:weight, :max_weight, :weight_unit, :default, { metadata: {} }]diff --git a/spree/api/app/controllers/spree/api/v3/seller/package_types_controller.rb b/spree/api/app/controllers/spree/api/v3/seller/package_types_controller.rbnew file mode 100644index 0000000000..8d0652374d--- /dev/null+++ b/spree/api/app/controllers/spree/api/v3/seller/package_types_controller.rb@@ -0,0 +1,100 @@+module Spree+ module Api+ module V3+ module Seller+ # What this seller packs their goods into: the boxes their parcels+ # ship in, the cartons their products are packed into, the pallets a+ # wholesale order leaves on (docs/plans/6.0-seller-package-types.md).+ #+ # The listing also carries the marketplace's own packaging, so a+ # seller can pack into the operator's standard cartons rather than+ # re-measuring them. Those rows are read-only: `find_resource` roots+ # writes in the seller's own packaging, so a marketplace row's id is a+ # 404 on every action but `show`.+ #+ # Marking a row default makes it the box this seller's parcels are+ # quoted with — one default per owner, so it never displaces the+ # marketplace's.+ class PackageTypesController < Seller::ResourceController+ scoped_resource :package_types++ protected++ def model_class+ Spree::PackageType+ end++ def serializer_class+ Spree.api.seller_package_type_serializer+ end++ # Reading shows the seller's own packaging plus the marketplace's —+ # the same set their variants may reference, so a carton picker can+ # ask "what can I pack into" rather than only "what have I+ # measured".+ #+ # `owner=mine` narrows it to the seller's own rows. The packaging+ # settings page asks for that, because a list mixing both owners+ # reads as "packaging is configured" while the seller has recorded+ # nothing — the shipping-box requirement then looks broken rather+ # than outstanding. Not a Ransack predicate: `available_to_seller`+ # composes with `.or()`, so a filter on `seller_id` widens back out+ # to the whole condition instead of narrowing it.+ def scope+ rows = current_store.package_types+ rows = params[:owner] == 'mine' ? rows.for_seller(current_seller) : rows.available_to_seller(current_seller)+ rows.preload_associations_lazily+ end++ # Writes root in the seller's own rows, so the marketplace's+ # packaging cannot be edited or deleted through this branch.+ def resource_scope+ current_seller.package_types+ end++ def find_resource+ action_name == 'show' ? super : resource_scope.find_by_prefix_id!(params[:id])+ end++ # No DISTINCT, so the owner ordering below is legal on PostgreSQL:+ # it rejects an ORDER BY expression that is not in the select list+ # of a SELECT DISTINCT, and `available_to_seller` makes the query+ # distinct through `.or()`. Nothing here needs it — one table, no+ # joins, so no row can appear twice.+ def collection_distinct?+ false+ end++ # The seller's own rows before the marketplace's, then by name.+ #+ # This list holds two owners' packaging, so it has roughly twice as+ # much to fit under the 100-row page limit as the operator's does.+ # Ordering here rather than in the client is what makes the limit+ # cut the shared rows instead of the seller's own measurements —+ # the page is taken before anything client-side can reorder it.+ # Ransack cannot express it: it drops the direction on `seller_id`,+ # and NULLs sort first ascending.+ #+ # Skipped when the caller asked for its own order.+ def apply_collection_sort(collection)+ return collection if params[:sort].present?++ collection.order(+ Arel.sql('CASE WHEN seller_id IS NULL THEN 1 ELSE 0 END'),+ Spree::PackageType.arel_table[:name].asc+ )+ end++ # The same set the operator's controller permits — a seller measures+ # their own packaging, so every field on the shared form is theirs+ # to set. `seller_id` is deliberately absent: ownership comes from+ # the authenticated seller, never the payload.+ def resource_permitted_attributes+ [:name, :kind, :length, :width, :height, :dimensions_unit,+ :weight, :max_weight, :weight_unit, :default, { metadata: {} }]+ end+ end+ end+ end+ end+enddiff --git a/spree/api/app/serializers/spree/api/v3/admin/package_type_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/package_type_serializer.rbindex d7ceed8d0a..891b49f24e 100644--- a/spree/api/app/serializers/spree/api/v3/admin/package_type_serializer.rb+++ b/spree/api/app/serializers/spree/api/v3/admin/package_type_serializer.rb@@ -17,6 +17,8 @@ module Spreeweight_unit: :string,volume: [:string, nullable: true],default: :boolean,+ seller_id: [:string, nullable: true],+ seller_name: [:string, nullable: true],metadata: ['Record<string, unknown> | null']attributes :name, :kind, :length, :width, :height, :weight, :max_weight,@@ -33,6 +35,17 @@ module Spree# figure their rules are compared against. Null until every side is# measured.attribute :volume, &:volume++ # Whose packaging this is: a seller's own, or (null) the+ # marketplace's shared vocabulary+ # (docs/plans/6.0-seller-package-types.md).+ attribute :seller_id do |package_type|+ package_type.seller&.prefixed_id+ end++ attribute :seller_name do |package_type|+ package_type.seller&.name+ endendendenddiff --git a/spree/api/app/serializers/spree/api/v3/seller/package_type_serializer.rb b/spree/api/app/serializers/spree/api/v3/seller/package_type_serializer.rbnew file mode 100644index 0000000000..6deb5b5377--- /dev/null+++ b/spree/api/app/serializers/spree/api/v3/seller/package_type_serializer.rb@@ -0,0 +1,52 @@+module Spree+ module Api+ module V3+ module Seller+ # What a seller packs their goods into: their own boxes, cartons and+ # pallets, and the marketplace's shared packaging they may also use.+ #+ # Declared on `BaseSerializer` rather than on a store twin because+ # there is none — a shopper never picks their packaging, so package+ # types exist on the back-office surfaces only.+ #+ # `editable` is what the panel renders a marketplace row read-only by,+ # mirroring the seller's delivery method serializer: a seller sees the+ # operator's cartons so they know what they can pack into, and the API+ # refuses to write them (docs/plans/6.0-seller-package-types.md).+ class PackageTypeSerializer < V3::BaseSerializer+ typelize name: :string,+ kind: :string,+ length: [:string, nullable: true],+ width: [:string, nullable: true],+ height: [:string, nullable: true],+ dimensions_unit: :string,+ weight: [:string, nullable: true],+ max_weight: [:string, nullable: true],+ weight_unit: :string,+ volume: [:string, nullable: true],+ default: :boolean,+ editable: :boolean,+ metadata: ['Record<string, unknown> | null']++ attributes :name, :kind, :length, :width, :height, :weight, :max_weight,+ :default, :metadata++ attributes created_at: :iso8601, updated_at: :iso8601++ # Both units read through their fallbacks, so a row that never set+ # one still tells the seller what its numbers mean.+ attribute :dimensions_unit, &:dimensions_unit+ attribute :weight_unit, &:weight_unit++ attribute :volume, &:volume++ # False for a marketplace row: listed so the seller knows what they+ # can pack into, and not theirs to change.+ attribute :editable do |package_type|+ package_type.seller_id.present?+ end+ end+ end+ end+ end+enddiff --git a/spree/api/config/routes.rb b/spree/api/config/routes.rbindex 2de42235dd..ca6bd4337d 100644--- a/spree/api/config/routes.rb+++ b/spree/api/config/routes.rb@@ -1012,6 +1012,11 @@ Spree::Core::Engine.add_routes doendend+ # What this seller packs into. The listing carries the marketplace's+ # own packaging alongside the seller's; only the seller's own can be+ # written (docs/plans/6.0-seller-package-types.md).+ resources :package_types+# No destroy: a location holds stock levels and is named on historical# fulfillments, so a seller retires one by deactivating it.resources :stock_locations, only: [:index, :show, :create, :update]diff --git a/spree/api/lib/spree/api/dependencies.rb b/spree/api/lib/spree/api/dependencies.rbindex 722f7722b3..75aa7d5e68 100644--- a/spree/api/lib/spree/api/dependencies.rb+++ b/spree/api/lib/spree/api/dependencies.rb@@ -205,6 +205,7 @@ module Spreeseller_claim_serializer: 'Spree::Api::V3::Seller::ClaimSerializer',seller_claim_line_item_serializer: 'Spree::Api::V3::Seller::ClaimLineItemSerializer',seller_reason_serializer: 'Spree::Api::V3::Seller::ReasonSerializer',+ seller_package_type_serializer: 'Spree::Api::V3::Seller::PackageTypeSerializer',seller_stock_location_serializer: 'Spree::Api::V3::Seller::StockLocationSerializer',seller_requirement_custom_field_serializer: 'Spree::Api::V3::Seller::RequirementCustomFieldSerializer',seller_tax_identifier_serializer: 'Spree::Api::V3::Seller::TaxIdentifierSerializer',diff --git a/spree/api/spec/controllers/spree/api/v3/admin/package_types_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/package_types_controller_spec.rbindex faa0f79629..5122074c65 100644--- a/spree/api/spec/controllers/spree/api/v3/admin/package_types_controller_spec.rb+++ b/spree/api/spec/controllers/spree/api/v3/admin/package_types_controller_spec.rb@@ -58,6 +58,49 @@ RSpec.describe Spree::Api::V3::Admin::PackageTypesController, type: :controllerto change(Spree::PackageType, :count).by(-1)end+ # The operator sees every owner's packaging in their store, so the list has+ # to say whose each row is and narrow to one owner on request+ # (docs/plans/6.0-seller-package-types.md).+ describe 'a marketplace with sellers' do+ let(:seller) { create(:seller, :approved, store: store) }+ let!(:sellers_box) { create(:package_type, store: store, seller: seller, name: 'Seller mailer') }++ it 'lists every owner’s packaging' do+ get :index, as: :json++ expect(json_response['data'].pluck('name')).to include('Master carton', 'Seller mailer')+ end++ it 'names the owner of each row' do+ get :show, params: { id: sellers_box.prefixed_id }, as: :json++ expect(json_response['seller_id']).to eq(seller.prefixed_id)+ expect(json_response['seller_name']).to eq(seller.name)+ end++ it 'reads the marketplace’s own rows as unowned' do+ get :show, params: { id: carton.prefixed_id }, as: :json++ expect(json_response['seller_id']).to be_nil+ expect(json_response['seller_name']).to be_nil+ end++ it 'narrows the list to one seller' do+ get :index, params: { q: { seller_id_eq: seller.id } }, as: :json++ expect(json_response['data'].pluck('name')).to contain_exactly('Seller mailer')+ end++ # A row the operator writes is the marketplace's: ownership is not+ # something the payload gets to claim.+ it 'ignores a seller_id in the payload' do+ post :create, params: { name: 'Operator box', kind: 'box', seller_id: seller.prefixed_id }, as: :json++ expect(response).to have_http_status(:created)+ expect(Spree::PackageType.find_by(name: 'Operator box').seller_id).to be_nil+ end+ end+it 'cannot reach another store package type' doforeign = create(:carton_package_type, store: create(:store))diff --git a/spree/api/spec/controllers/spree/api/v3/admin/sellers_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/sellers_controller_spec.rbindex 61426e99f0..c89f543973 100644--- a/spree/api/spec/controllers/spree/api/v3/admin/sellers_controller_spec.rb+++ b/spree/api/spec/controllers/spree/api/v3/admin/sellers_controller_spec.rb@@ -347,4 +347,29 @@ RSpec.describe Spree::Api::V3::Admin::SellersController, type: :controller doexpect(product.reload.seller_id).to be_nilendend+ # The onboarding checklist renders for every row, and the shipping-box kind+ # reads a has_one. Reading it through the association keeps that one batched+ # load for the whole page; a per-seller query would scale with page size+ # (docs/plans/6.0-seller-package-types.md).+ describe 'the onboarding checklist on a page of sellers' do+ it 'reads every seller’s box in one query' do+ store.seller_requirements.destroy_all+ Spree::SellerRequirement.provision_defaults(store)+ 4.times do |index|+ seller = create(:seller, :approved, store: store, name: "Box Seller #{index}")+ create(:package_type, :measured_default_box, store: store, seller: seller)+ end++ queries = []+ subscription = ActiveSupport::Notifications.subscribe('sql.active_record') do |*, payload|+ queries << payload[:sql] unless payload[:name].to_s.match?(/SCHEMA|TRANSACTION/)+ end+ get :index, as: :json+ ActiveSupport::Notifications.unsubscribe(subscription)++ expect(response).to have_http_status(:ok)+ expect(queries.grep(/spree_package_types/).size).to eq(1)+ end+ end+enddiff --git a/spree/api/spec/controllers/spree/api/v3/seller/package_types_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/seller/package_types_controller_spec.rbnew file mode 100644index 0000000000..10eb44bf9b--- /dev/null+++ b/spree/api/spec/controllers/spree/api/v3/seller/package_types_controller_spec.rb@@ -0,0 +1,242 @@+require 'spec_helper'++# A seller measures their own packaging and reads the marketplace's, so the+# isolation to check is in both directions: another seller's boxes must be+# invisible, and the operator's must be readable but never writable+# (docs/plans/6.0-seller-package-types.md).+RSpec.describe Spree::Api::V3::Seller::PackageTypesController, type: :controller do+ render_views++ include_context 'API v3 Seller'++ # A role holding only the packaging keys, so the catalog entry is what+ # actually lets these requests through — a broad role would pass even if+ # `package_types` had never been registered.+ let(:seller_role) do+ create(:role, name: 'Seller', resource: seller, permissions: %w[read_package_types write_package_types])+ end++ let(:token) do+ Spree::Api::V3::TestingSupport.generate_jwt(+ seller_user, audience: Spree::Api::V3::JwtAuthentication::JWT_AUDIENCE_SELLER+ )+ end++ let!(:mine) do+ create(:package_type, store: store, seller: seller, name: 'My Mailer', default: true,+ length: 30, width: 20, height: 15, weight: 0.4)+ end+ let(:other_seller) { create(:seller, :approved, store: store) }+ let!(:theirs) { create(:package_type, store: store, seller: other_seller, name: 'Their Mailer') }+ let!(:marketplace) { create(:carton_package_type, store: store, name: 'Marketplace Carton') }++ before do+ request.headers['Authorization'] = "Bearer #{token}"+ request.headers['X-Spree-Seller-Id'] = seller.prefixed_id+ end++ describe 'GET #index' do+ it "lists this seller's packaging and the marketplace's, never another seller's" do+ get :index, as: :json++ expect(response).to have_http_status(:ok)+ names = json_response['data'].pluck('name')+ expect(names).to include('My Mailer', 'Marketplace Carton')+ expect(names).not_to include('Their Mailer')+ end++ # The seller's own rows come first, so the page limit cuts the shared+ # vocabulary rather than the seller's own measurements — which is what+ # the variant editor's carton picker depends on.+ it 'lists the seller’s own packaging before the marketplace’s' do+ # Names chosen so alphabetical order would put them the other way round.+ create(:carton_package_type, store: store, name: 'AAA marketplace carton')+ create(:carton_package_type, store: store, seller: seller, name: 'ZZZ my carton')++ get :index, params: { kind_eq: 'carton' }, as: :json++ owners = json_response['data'].map { |row| row['editable'] }+ expect(owners).to eq(owners.sort_by { |editable| editable ? 0 : 1 })+ expect(json_response['data'].pluck('name')).to include('ZZZ my carton', 'AAA marketplace carton')+ end++ it 'honours an explicit sort instead' do+ create(:carton_package_type, store: store, name: 'AAA marketplace carton')+ create(:carton_package_type, store: store, seller: seller, name: 'ZZZ my carton')++ get :index, params: { kind_eq: 'carton', sort: 'name' }, as: :json++ expect(json_response['data'].pluck('name').first).to eq('AAA marketplace carton')+ end++ # The settings page asks for this: a list mixing both owners reads as+ # "packaging is configured" while the seller has recorded nothing, which+ # makes the shipping-box requirement look broken rather than outstanding.+ it 'narrows to the seller’s own packaging on request' do+ get :index, params: { owner: 'mine' }, as: :json++ expect(json_response['data'].pluck('name')).to contain_exactly('My Mailer')+ end++ # What the panel renders a marketplace row read-only by.+ it 'marks only the seller’s own rows editable' do+ get :index, as: :json++ editable = json_response['data'].to_h { |row| [row['name'], row['editable']] }+ expect(editable).to eq('My Mailer' => true, 'Marketplace Carton' => false)+ end+ end++ describe 'GET #show' do+ it 'finds its own' do+ get :show, params: { id: mine.prefixed_id }, as: :json++ expect(response).to have_http_status(:ok)+ expect(json_response['name']).to eq('My Mailer')+ end++ # Readable so a seller can see what they may pack into.+ it "finds the marketplace's" do+ get :show, params: { id: marketplace.prefixed_id }, as: :json++ expect(response).to have_http_status(:ok)+ expect(json_response['editable']).to be(false)+ end++ # 404 rather than 403: the caller must not learn whether it exists.+ it "404s on another seller's" do+ get :show, params: { id: theirs.prefixed_id }, as: :json++ expect(response).to have_http_status(:not_found)+ end+ end++ describe 'POST #create' do+ it 'creates one owned by this seller' do+ post :create, params: { name: 'Second Mailer', kind: 'box' }, as: :json++ expect(response).to have_http_status(:created)+ created = Spree::PackageType.find_by(name: 'Second Mailer')+ expect(created.seller).to eq(seller)+ expect(created.store).to eq(store)+ end++ # The payload does not get to say whose it is.+ it 'ignores a seller_id in the payload' do+ post :create, params: { name: 'Third Mailer', kind: 'box', seller_id: other_seller.prefixed_id }, as: :json++ expect(Spree::PackageType.find_by(name: 'Third Mailer').seller).to eq(seller)+ end++ # Each owner names their own packaging, so the marketplace's name is free.+ it 'allows the name the marketplace already uses' do+ post :create, params: { name: 'Marketplace Carton', kind: 'carton' }, as: :json++ expect(response).to have_http_status(:created)+ expect(Spree::PackageType.where(name: 'Marketplace Carton').count).to eq(2)+ end++ it 'accepts every field the shared form sends' do+ post :create, params: {+ name: 'Measured Box', kind: 'carton',+ length: 40, width: 30, height: 25, dimensions_unit: 'cm',+ weight: 1.2, max_weight: 20, weight_unit: 'kg',+ default: false, metadata: { supplier: 'Acme' }+ }, as: :json++ expect(response).to have_http_status(:created)+ created = Spree::PackageType.find_by(name: 'Measured Box')+ expect(created.attributes.symbolize_keys.slice(+ :kind, :dimensions_unit, :weight_unit+ )).to eq(kind: 'carton', dimensions_unit: 'cm', weight_unit: 'kg')+ expect([created.length, created.width, created.height, created.weight, created.max_weight].map(&:to_f)).+ to eq([40.0, 30.0, 25.0, 1.2, 20.0])+ expect(created.metadata).to eq('supplier' => 'Acme')+ end++ # One default per owner: promoting the seller's box must not take the+ # marketplace's away.+ it 'leaves the marketplace default alone when marking its own default' do+ marketplace.update!(default: true)++ post :create, params: { name: 'New Default', kind: 'box', default: true }, as: :json++ expect(response).to have_http_status(:created)+ expect(marketplace.reload).to be_default+ expect(mine.reload).not_to be_default+ end+ end++ describe 'PATCH #update' do+ it 'updates its own' do+ patch :update, params: { id: mine.prefixed_id, name: 'Renamed Mailer' }, as: :json++ expect(response).to have_http_status(:ok)+ expect(mine.reload.name).to eq('Renamed Mailer')+ end++ it "404s on another seller's" do+ patch :update, params: { id: theirs.prefixed_id, name: 'Hijacked' }, as: :json++ expect(response).to have_http_status(:not_found)+ expect(theirs.reload.name).to eq('Their Mailer')+ end++ # Readable through show, and still not theirs to change.+ it "404s on the marketplace's" do+ patch :update, params: { id: marketplace.prefixed_id, name: 'Hijacked' }, as: :json++ expect(response).to have_http_status(:not_found)+ expect(marketplace.reload.name).to eq('Marketplace Carton')+ end+ end++ describe 'DELETE #destroy' do+ it 'deletes its own' do+ spare = create(:package_type, store: store, seller: seller, name: 'Spare')++ delete :destroy, params: { id: spare.prefixed_id }, as: :json++ expect(response).to have_http_status(:no_content)+ expect(Spree::PackageType.where(id: spare.id)).not_to exist+ end++ it "404s on the marketplace's" do+ delete :destroy, params: { id: marketplace.prefixed_id }, as: :json++ expect(response).to have_http_status(:not_found)+ expect(Spree::PackageType.where(id: marketplace.id)).to exist+ end++ # Deleting it would leave this seller's parcels quoted with the+ # marketplace's box without anything saying so.+ it 'refuses its own default box' do+ delete :destroy, params: { id: mine.prefixed_id }, as: :json++ expect(response).to have_http_status(:unprocessable_content)+ expect(Spree::PackageType.where(id: mine.id)).to exist+ end+ end++ describe 'without the packaging permission' do+ let(:seller_role) { create(:role, name: 'Seller', resource: seller, permissions: %w[read_orders]) }++ it 'is forbidden' do+ get :index, as: :json++ expect(response).to have_http_status(:forbidden)+ end+ end++ # A store the seller does not belong to must be unreachable by id, not+ # merely filtered out of the listing.+ describe 'cross-store isolation' do+ it '404s on a package type from another store' do+ foreign = create(:package_type, store: create(:store), name: 'Foreign Box')++ get :show, params: { id: foreign.prefixed_id }, as: :json++ expect(response).to have_http_status(:not_found)+ end+ end+enddiff --git a/spree/api/spec/integration/spree/api/v3/admin/package_types_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/package_types_spec.rbindex 1eece044b7..151df10d36 100644--- a/spree/api/spec/integration/spree/api/v3/admin/package_types_spec.rb+++ b/spree/api/spec/integration/spree/api/v3/admin/package_types_spec.rb@@ -25,7 +25,7 @@ RSpec.describe 'Admin Package Types API', type: :request, swagger_doc: 'api-refevolume rules compare against. It is null until all three sides aremeasured.DESC- admin_scope :read, :settings+ admin_scope :read, :package_typesadmin_sdk_example 'package-types/list'@@ -76,7 +76,7 @@ RSpec.describe 'Admin Package Types API', type: :request, swagger_doc: 'api-refeA variant references a `carton`-kind row to say what it is packedinto; other kinds are the merchant's own vocabulary.DESC- admin_scope :write, :settings+ admin_scope :write, :package_typesadmin_sdk_example 'package-types/create'@@ -134,7 +134,7 @@ RSpec.describe 'Admin Package Types API', type: :request, swagger_doc: 'api-refeproduces 'application/json'security [api_key: [], bearer_auth: []]description 'Returns a single package type by prefixed ID.'- admin_scope :read, :settings+ admin_scope :read, :package_typesadmin_sdk_example 'package-types/get'@@ -170,7 +170,7 @@ RSpec.describe 'Admin Package Types API', type: :request, swagger_doc: 'api-refeproduces 'application/json'security [api_key: [], bearer_auth: []]description 'Updates a package type. Every product packed in it follows the new geometry.'- admin_scope :write, :settings+ admin_scope :write, :package_typesadmin_sdk_example 'package-types/update'@@ -213,7 +213,7 @@ RSpec.describe 'Admin Package Types API', type: :request, swagger_doc: 'api-refeRemoves a kind of packaging. Refused while any variant is packed intoit — repack those products first.DESC- admin_scope :write, :settings+ admin_scope :write, :package_typesadmin_sdk_example 'package-types/delete'diff --git a/spree/api/spec/integration/spree/api/v3/seller/package_types_spec.rb b/spree/api/spec/integration/spree/api/v3/seller/package_types_spec.rbnew file mode 100644index 0000000000..f8e6b96215--- /dev/null+++ b/spree/api/spec/integration/spree/api/v3/seller/package_types_spec.rb@@ -0,0 +1,222 @@+# frozen_string_literal: true++require 'swagger_helper'++RSpec.describe 'Seller Package Types API', type: :request, swagger_doc: 'api-reference/seller.yaml' do+ include_context 'API v3 Seller'++ let(:seller_role) do+ create(:role, name: 'Seller', resource: seller, permissions: %w[read_package_types write_package_types])+ end++ let!(:package_type) do+ create(:package_type, store: store, seller: seller, name: 'Standard mailer', default: true,+ length: 30, width: 20, height: 15, weight: 0.4)+ end+ let!(:marketplace_carton) { create(:carton_package_type, store: store, name: 'Marketplace carton') }++ path '/api/v3/seller/package_types' do+ get 'List package types' do+ tags 'Package Types'+ produces 'application/json'+ security [bearer_auth: []]+ description <<~DESC+ What this seller packs their goods into: the boxes their parcels ship+ in, the cartons their products are packed into, the pallets a+ wholesale order leaves on.++ The list carries the marketplace's own packaging alongside the+ seller's, so a seller can pack into the operator's standard cartons+ rather than measuring them again. Those rows report `editable: false`+ and are refused by every write.++ The row marked `default` is the box this seller's parcels are quoted+ with — its size and weight are added to every rate.+ DESC++ parameter name: 'X-Spree-Seller-Id', in: :header, type: :string, required: true+ parameter name: :owner, in: :query, type: :string, required: false, enum: ['mine'],+ description: "Narrows the list to the seller's own packaging, leaving out the marketplace's shared rows"+ parameter name: :page, in: :query, type: :integer, required: false, description: 'Page number'+ parameter name: :limit, in: :query, type: :integer, required: false, description: 'Records per page (max 100)'++ response '200', 'package types listed' do+ let(:Authorization) { "Bearer #{seller_jwt_token}" }+ let(:'X-Spree-Seller-Id') { seller.prefixed_id }++ schema type: :object,+ properties: {+ data: { type: :array, items: { '$ref' => '#/components/schemas/PackageType' } },+ meta: { '$ref' => '#/components/schemas/PaginationMeta' }+ },+ required: %w[data meta]++ run_test! do |response|+ data = JSON.parse(response.body)['data']+ expect(data.map { |item| item['id'] }).to include(package_type.prefixed_id, marketplace_carton.prefixed_id)+ end+ end+ end++ post 'Create a package type' do+ tags 'Package Types'+ consumes 'application/json'+ produces 'application/json'+ security [bearer_auth: []]+ description <<~DESC+ Records a piece of the seller's own packaging. Marking it `default`+ makes it the box their parcels are quoted with, and demotes whichever+ of their rows held the flag before — the marketplace's default is a+ different owner's row and is left alone.+ DESC++ parameter name: 'X-Spree-Seller-Id', in: :header, type: :string, required: true+ parameter name: :body, in: :body, required: true, schema: {+ type: :object,+ properties: {+ name: { type: :string },+ kind: { type: :string, enum: Spree::PackageType::KINDS },+ length: { type: :number, nullable: true },+ width: { type: :number, nullable: true },+ height: { type: :number, nullable: true },+ dimensions_unit: { type: :string, nullable: true },+ weight: { type: :number, nullable: true, description: "The empty package's own weight, added to every quote" },+ max_weight: { type: :number, nullable: true },+ weight_unit: { type: :string, nullable: true },+ default: { type: :boolean },+ metadata: { type: :object, nullable: true }+ },+ required: %w[name kind]+ }++ response '201', 'package type created' do+ let(:Authorization) { "Bearer #{seller_jwt_token}" }+ let(:'X-Spree-Seller-Id') { seller.prefixed_id }+ let(:body) do+ { name: 'Large mailer', kind: 'box', length: 40, width: 30, height: 20,+ dimensions_unit: 'cm', weight: 0.6, weight_unit: 'kg' }+ end++ schema '$ref' => '#/components/schemas/PackageType'++ run_test! do |response|+ data = JSON.parse(response.body)+ expect(data['kind']).to eq('box')+ expect(data['editable']).to be(true)+ end+ end++ response '422', 'validation error' do+ let(:Authorization) { "Bearer #{seller_jwt_token}" }+ let(:'X-Spree-Seller-Id') { seller.prefixed_id }+ let(:body) { { name: 'Crate', kind: 'crate' } }++ schema '$ref' => '#/components/schemas/ErrorResponse'++ run_test!+ end+ end+ end++ path '/api/v3/seller/package_types/{id}' do+ parameter name: :id, in: :path, type: :string, required: true, description: 'Package type ID'++ get 'Get a package type' do+ tags 'Package Types'+ produces 'application/json'+ security [bearer_auth: []]+ description <<~DESC+ Returns one package type by prefixed ID — the seller's own, or a+ marketplace row they may pack into.+ DESC++ parameter name: 'X-Spree-Seller-Id', in: :header, type: :string, required: true++ response '200', 'package type found' do+ let(:Authorization) { "Bearer #{seller_jwt_token}" }+ let(:'X-Spree-Seller-Id') { seller.prefixed_id }+ let(:id) { package_type.prefixed_id }++ schema '$ref' => '#/components/schemas/PackageType'++ run_test! do |response|+ expect(JSON.parse(response.body)['id']).to eq(package_type.prefixed_id)+ end+ end++ response '404', 'package type not found' do+ let(:Authorization) { "Bearer #{seller_jwt_token}" }+ let(:'X-Spree-Seller-Id') { seller.prefixed_id }+ let(:id) { 'pkgtype_nonexistent' }++ schema '$ref' => '#/components/schemas/ErrorResponse'++ run_test!+ end+ end++ patch 'Update a package type' do+ tags 'Package Types'+ consumes 'application/json'+ produces 'application/json'+ security [bearer_auth: []]+ description <<~DESC+ Changes the seller's own packaging. A marketplace row is not theirs to+ edit and answers 404.+ DESC++ parameter name: 'X-Spree-Seller-Id', in: :header, type: :string, required: true+ parameter name: :body, in: :body, required: true, schema: {+ type: :object,+ properties: {+ name: { type: :string },+ kind: { type: :string, enum: Spree::PackageType::KINDS },+ length: { type: :number, nullable: true },+ width: { type: :number, nullable: true },+ height: { type: :number, nullable: true },+ dimensions_unit: { type: :string, nullable: true },+ weight: { type: :number, nullable: true },+ max_weight: { type: :number, nullable: true },+ weight_unit: { type: :string, nullable: true },+ default: { type: :boolean },+ metadata: { type: :object, nullable: true }+ }+ }++ response '200', 'package type updated' do+ let(:Authorization) { "Bearer #{seller_jwt_token}" }+ let(:'X-Spree-Seller-Id') { seller.prefixed_id }+ let(:id) { package_type.prefixed_id }+ let(:body) { { max_weight: 25 } }++ schema '$ref' => '#/components/schemas/PackageType'++ run_test! do |response|+ expect(JSON.parse(response.body)['max_weight'].to_d).to eq(25)+ end+ end+ end++ delete 'Delete a package type' do+ tags 'Package Types'+ produces 'application/json'+ security [bearer_auth: []]+ description <<~DESC+ Retires one of the seller's own package types. The default box is+ refused — name another default first, or every parcel silently falls+ back to the marketplace's box.+ DESC++ parameter name: 'X-Spree-Seller-Id', in: :header, type: :string, required: true++ response '204', 'package type deleted' do+ let(:Authorization) { "Bearer #{seller_jwt_token}" }+ let(:'X-Spree-Seller-Id') { seller.prefixed_id }+ let(:spare) { create(:package_type, store: store, seller: seller, name: 'Spare mailer') }+ let(:id) { spare.prefixed_id }++ run_test!+ end+ end+ end+enddiff --git a/spree/core/app/models/spree/package_type.rb b/spree/core/app/models/spree/package_type.rbindex 52a9214a2e..d8a42b558c 100644--- a/spree/core/app/models/spree/package_type.rb+++ b/spree/core/app/models/spree/package_type.rb@@ -20,19 +20,31 @@ module Spreebelongs_to :store, class_name: 'Spree::Store'+ # Whose packaging this is. Nil is the marketplace's own row — the shared+ # vocabulary every seller may pack into — and a seller's rows are theirs+ # alone (docs/plans/6.0-seller-package-types.md).+ #+ # `with_deleted` for the reason a delivery method's owner is: a seller is+ # paranoid and this association deliberately survives one, because a nil+ # `seller_id` IS the marketplace's row. Releasing a departed seller's rows+ # would hand the operator a second default box.+ belongs_to :seller, -> { with_deleted }, class_name: 'Spree::Seller', optional: true,+ inverse_of: :package_types+has_many :variants, class_name: 'Spree::Variant', foreign_key: :carton_package_type_id,inverse_of: :carton_package_type, dependent: :restrict_with_error- validates :name, presence: true, uniqueness: { scope: spree_base_uniqueness_scope + [:store_id] }+ validates :name, presence: true,+ uniqueness: { scope: spree_base_uniqueness_scope + [:store_id, :seller_id] }validates :kind, inclusion: { in: KINDS }validates :dimensions_unit, inclusion: { in: Spree::Variant::DIMENSION_UNITS }, allow_blank: truevalidates :weight_unit, inclusion: { in: Spree::Variant::WEIGHT_UNITS }, allow_blank: truevalidates :length, :width, :height, :weight, :max_weight,numericality: { greater_than_or_equal_to: 0, allow_nil: true }- # Demote any prior default in the same transaction so the partial unique- # index ("one default per store") never sees two TRUE rows, and MySQL —- # which cannot enforce that index — arrives at the same place.+ # Demote the owner's prior default in the same transaction so the partial+ # unique index ("one default per owner") never sees two TRUE rows, and+ # MySQL — which cannot enforce that index — arrives at the same place.validate :kind_cannot_leave_the_products_packed_in_it, on: :updatebefore_save :demote_other_defaults, if: -> { default? && will_save_change_to_default? }validate :default_cannot_be_given_up, on: :update@@ -44,6 +56,34 @@ module Spreescope :cartons, -> { where(kind: 'carton') }+ # The marketplace's own packaging, and one seller's.+ scope :first_party, -> { where(seller_id: nil) }+ scope :for_seller, ->(seller) { where(seller_id: seller.respond_to?(:id) ? seller.id : seller) }+ # One owner's rows within one store — the unit the default flag belongs+ # to. Named as `Spree::StockLocation` names it, since it does the same job+ # there for the same reason.+ scope :owned_by, ->(store_id:, seller_id:) { where(store_id: store_id, seller_id: seller_id) }++ # Everything a seller may pack into: their own rows plus the+ # marketplace's, which they read but never write. A nil seller is the+ # operator, who packs into their own rows only.+ #+ # @param seller [Spree::Seller, nil]+ scope :available_to_seller, ->(seller) {+ seller.nil? ? first_party : for_seller(seller).or(first_party)+ }++ # Whether the given owner may pack into this row: their own, or the+ # marketplace's shared vocabulary. The Ruby twin of `available_to_seller`,+ # so the validation and the scope cannot drift apart on what "mine or the+ # marketplace's" means.+ #+ # @param owner_seller_id [Integer, nil] nil is the operator+ # @return [Boolean]+ def available_to_seller?(owner_seller_id)+ seller_id.nil? || seller_id == owner_seller_id+ end+# The one kind anything branches on: a variant may only be packed into a# carton. The rest of the vocabulary is the merchant's to name and read.#@@ -52,7 +92,10 @@ module Spreekind == 'carton'end- self.whitelisted_ransackable_attributes = %w[name kind default]+ # `seller_id` is what the operator's list filters by to see one seller's+ # packaging, or (blank) the marketplace's own.+ self.whitelisted_ransackable_attributes = %w[name kind default seller_id]+ self.whitelisted_ransackable_associations = %w[seller]# The unit the geometry is expressed in, falling back to what the store's# unit system implies — the same fallback a variant's dimensions take.@@ -128,13 +171,21 @@ module Spree# instead; that demotes this one in the same save.def default_cannot_be_given_upreturn unless default_changed? && default_was && !default?- return if self.class.where(store_id: store_id, default: true).where.not(id: id).exists?+ return if other_defaults.exists?errors.add(:default, :cannot_be_given_up)enddef demote_other_defaults- self.class.where(store_id: store_id, default: true).where.not(id: id).update_all(default: false)+ other_defaults.update_all(default: false)+ end++ # The other rows competing for this row's default flag: the same owner's,+ # in the same store. The operator and each seller hold one default box+ # apiece, so promoting a seller's box must not demote the marketplace's.+ def other_defaults+ self.class.owned_by(store_id: store_id, seller_id: seller_id).+ where(default: true).where.not(id: id)endendenddiff --git a/spree/core/app/models/spree/seller.rb b/spree/core/app/models/spree/seller.rbindex c5d9ee1cfc..05fb396161 100644--- a/spree/core/app/models/spree/seller.rb+++ b/spree/core/app/models/spree/seller.rb@@ -118,6 +118,22 @@ module Spreehas_many :delivery_methods, class_name: 'Spree::DeliveryMethod', dependent: nil,inverse_of: :seller+ # What this seller packs their goods into: their own boxes, cartons and+ # pallets, beside the marketplace's shared vocabulary they may also use+ # (docs/plans/6.0-seller-package-types.md).+ #+ # `dependent: nil` for the same reason as delivery methods above: a nil+ # `seller_id` IS the marketplace's row, so nullifying a departed seller's+ # rows would give the operator a second default box and start quoting this+ # seller's tare on first-party parcels.+ has_many :package_types, class_name: 'Spree::PackageType', dependent: nil,+ inverse_of: :seller++ # The box this seller's parcels are quoted with. Nil until they record+ # one, and `Stock::Package` then falls back to the marketplace's.+ has_one :default_package_type, -> { where(default: true) }, class_name: 'Spree::PackageType',+ dependent: nil, inverse_of: :seller+# The seller's tax registrations — the VAT number the commission invoice# needs, with the validation verdict and evidence the model carries.#diff --git a/spree/core/app/models/spree/seller_requirement.rb b/spree/core/app/models/spree/seller_requirement.rbindex 2982f1046d..2e637d4d63 100644--- a/spree/core/app/models/spree/seller_requirement.rb+++ b/spree/core/app/models/spree/seller_requirement.rb@@ -64,6 +64,7 @@ module SpreeSpree::SellerRequirements::BillingAddressSpree::SellerRequirements::ReturnsAddressSpree::SellerRequirements::DeliveryMethod+ Spree::SellerRequirements::PackageTypeSpree::SellerRequirements::MinimumProducts].freezediff --git a/spree/core/app/models/spree/seller_requirements/package_type.rb b/spree/core/app/models/spree/seller_requirements/package_type.rbnew file mode 100644index 0000000000..f86d71c70b--- /dev/null+++ b/spree/core/app/models/spree/seller_requirements/package_type.rb@@ -0,0 +1,40 @@+# frozen_string_literal: true++module Spree+ module SellerRequirements+ # The seller has told the marketplace what they ship in. Without it their+ # parcels are quoted with the marketplace's box, which is the wrong size+ # and the wrong tare for anyone shipping from their own warehouse — a+ # quote that is wrong rather than missing, so nothing at checkout reveals+ # it (docs/plans/6.0-seller-package-types.md).+ #+ # Measurements, not merely a row: a default box with blank sides quotes+ # the goods alone, which is the silent under-pricing the package type's+ # own guards exist to prevent.+ #+ # Deliberately not satisfied by the marketplace's box, unlike the+ # delivery-method kind beside it: a seller quoting through the operator's+ # shared rates still packs and posts their own parcel. An operator who+ # ships everything themselves switches this requirement off.+ class PackageType < Spree::SellerRequirement+ MEASUREMENTS = %i[length width height weight].freeze++ # Read through the association rather than queried, so the operator's+ # seller list costs one batched load for the whole page instead of a+ # query per row — `ar_lazy_preload` groups it into a single+ # `seller_id IN (...)` once the checklist renders for several sellers,+ # which a `.exists?` per seller would defeat.+ #+ # The trade-off: a caller that loaded this association before the box+ # was recorded reads the cached answer. Neither gate workflow touches+ # it, and the evaluator is told never to trust a preload it merely+ # happens to find, so that needs a caller going out of its way.+ def met_by_seller?(seller)+ box = seller.default_package_type+ return false if box.nil?++ MEASUREMENTS.all? { |measurement| box.public_send(measurement).to_d.positive? }+ end+ end+ end+enddiff --git a/spree/core/app/models/spree/stock/package.rb b/spree/core/app/models/spree/stock/package.rbindex d955816865..f3c51fd9fa 100644--- a/spree/core/app/models/spree/stock/package.rb+++ b/spree/core/app/models/spree/stock/package.rb@@ -200,13 +200,22 @@ module Spreeprivate- # The store's default box.+ # The box this package is quoted with: the seller's own, falling back to+ # the marketplace's.+ #+ # A package's seller is its stock location's — the derivation used+ # everywhere else — so a parcel leaving a seller's warehouse takes that+ # seller's tare and dimensions. The fallback keeps checkout whole for a+ # seller who has not recorded a box yet; the `PackageType` onboarding+ # requirement is what asks them to+ # (docs/plans/6.0-seller-package-types.md).## @return [Spree::PackageType, nil]def default_package_typereturn @default_package_type if defined?(@default_package_type)- @default_package_type = owner&.store&.default_package_type+ @default_package_type = stock_location&.seller&.default_package_type ||+ owner&.store&.default_package_typeend# The box's own weight, converted into the unit the contents arediff --git a/spree/core/app/models/spree/store.rb b/spree/core/app/models/spree/store.rbindex 7646754dda..f51c83173b 100644--- a/spree/core/app/models/spree/store.rb+++ b/spree/core/app/models/spree/store.rb@@ -238,8 +238,12 @@ module Spree# through an association so it is loaded once per store rather than once# per package quoted.has_many :package_types, class_name: 'Spree::PackageType', dependent: :destroy, inverse_of: :store- has_one :default_package_type, -> { where(default: true) }, class_name: 'Spree::PackageType',- inverse_of: :store+ # The marketplace's own default box. A seller's default is read through+ # the seller (docs/plans/6.0-seller-package-types.md) — without the+ # `seller_id` filter this would answer with whichever owner's row loaded+ # first.+ has_one :default_package_type, -> { where(default: true, seller_id: nil) },+ class_name: 'Spree::PackageType', inverse_of: :storehas_many :promotions, class_name: 'Spree::Promotion', dependent: :nullifyhas_many :tax_categories, class_name: 'Spree::TaxCategory', dependent: :destroy, inverse_of: :storediff --git a/spree/core/app/models/spree/variant.rb b/spree/core/app/models/spree/variant.rbindex 15c4f911bf..bf5bc9486a 100644--- a/spree/core/app/models/spree/variant.rb+++ b/spree/core/app/models/spree/variant.rb@@ -1200,14 +1200,19 @@ module Spreeerrors.add(:delivery_profile, :invalid)end- # Same guard as the delivery profile above: a carton belonging to another- # store must never be reachable by id.+ # Same guard as the delivery profile above, widened to ownership: a carton+ # must belong to this store, and be either the marketplace's shared+ # vocabulary or this variant's own seller's. Another seller's carton must+ # never be reachable by id — its measurements would feed this variant's+ # freight rollups (docs/plans/6.0-seller-package-types.md).def carton_package_type_must_belong_to_storereturn if self[:carton_package_type_id].nil?store = product&.storereturn if store.nil?- return if association(:carton_package_type).reader&.store_id == store.id++ carton = association(:carton_package_type).reader+ return if carton&.store_id == store.id && carton.available_to_seller?(resolved_seller_id)errors.add(:carton_package_type, :invalid)enddiff --git a/spree/core/app/services/spree/imports/row_processors/product_variant.rb b/spree/core/app/services/spree/imports/row_processors/product_variant.rbindex 0c32826cab..f8c117d0b2 100644--- a/spree/core/app/services/spree/imports/row_processors/product_variant.rb+++ b/spree/core/app/services/spree/imports/row_processors/product_variant.rb@@ -224,7 +224,13 @@ module Spreedef prepare_cartoncarton_name = attributes['carton'].stripcached_lookup(:carton_package_type, carton_name) do- store.package_types.find_by(name: carton_name, kind: 'carton')+ # A seller's import reaches their own cartons and the+ # marketplace's, ordered so their own row wins when both owners+ # named a carton the same way — a seller's spreadsheet means their+ # own measurements. An operator's import sees the marketplace's.+ store.package_types.cartons.available_to_seller(seller).+ order(Arel.sql('CASE WHEN seller_id IS NULL THEN 1 ELSE 0 END')).+ find_by(name: carton_name)endenddiff --git a/spree/core/config/locales/en.yml b/spree/core/config/locales/en.ymlindex 2cd8d94479..6073196bcf 100644--- a/spree/core/config/locales/en.yml+++ b/spree/core/config/locales/en.yml@@ -1740,6 +1740,9 @@ en:operator_review:description: The marketplace checks this by hand before approving youname: Manual check+ package_type:+ description: Tell us the size and weight of the box you ship orders in+ name: Shipping boxpolicy:description: Publish a policy with this namename: Seller policydiff --git a/spree/core/db/migrate/20260908000001_add_seller_to_spree_package_types.rb b/spree/core/db/migrate/20260908000001_add_seller_to_spree_package_types.rbnew file mode 100644index 0000000000..b7424416bb--- /dev/null+++ b/spree/core/db/migrate/20260908000001_add_seller_to_spree_package_types.rb@@ -0,0 +1,78 @@+class AddSellerToSpreePackageTypes < ActiveRecord::Migration[8.1]+ MARKETPLACE_NAME_INDEX = 'index_spree_package_types_marketplace_name'.freeze+ SELLER_NAME_INDEX = 'index_spree_package_types_seller_name'.freeze+ MARKETPLACE_DEFAULT_INDEX = 'index_spree_package_types_marketplace_default'.freeze+ SELLER_DEFAULT_INDEX = 'index_spree_package_types_seller_default'.freeze+ STORE_NAME_INDEX = 'index_spree_package_types_on_store_and_name'.freeze+ DEFAULT_PER_STORE_INDEX = 'index_spree_package_types_default_per_store'.freeze++ def change+ # Whose packaging this is: a seller's own boxes and cartons, or (nil) the+ # marketplace's — the shared vocabulary every seller may pack into.+ add_reference :spree_package_types, :seller, null: true++ # Two indexes where there was one, because a nullable column inside a+ # unique index constrains nothing for the rows where it is null: the+ # marketplace's rows all share a NULL seller_id, and NULLs compare+ # distinct. MySQL has no partial indexes, so there the seller rows are+ # covered (they carry no NULL) and the marketplace's fall back to the+ # model validation — the arrangement the default flag already has.+ #+ # Spelled out per direction so the change rolls back: an index removed by+ # name alone cannot be inferred in reverse.+ reversible do |dir|+ dir.up { split_indexes_by_owner }+ dir.down { restore_store_wide_indexes }+ end+ end++ private++ def split_indexes_by_owner+ remove_index :spree_package_types, name: STORE_NAME_INDEX++ if supports_partial_index?+ add_index :spree_package_types, [:store_id, :name], unique: true,+ where: 'seller_id IS NULL', name: MARKETPLACE_NAME_INDEX+ add_index :spree_package_types, [:store_id, :seller_id, :name], unique: true,+ where: 'seller_id IS NOT NULL', name: SELLER_NAME_INDEX++ remove_index :spree_package_types, name: DEFAULT_PER_STORE_INDEX+ add_index :spree_package_types, :store_id, unique: true,+ where: '"default" = TRUE AND seller_id IS NULL', name: MARKETPLACE_DEFAULT_INDEX+ add_index :spree_package_types, [:store_id, :seller_id], unique: true,+ where: '"default" = TRUE AND seller_id IS NOT NULL', name: SELLER_DEFAULT_INDEX+ else+ add_index :spree_package_types, [:store_id, :seller_id, :name], unique: true,+ name: SELLER_NAME_INDEX+ end+ end++ # Rolling back means going back to one default and one name per store, so a+ # store holding a seller's packaging cannot satisfy either. Drop those rows+ # first: they are unreachable without the column this migration adds.+ def restore_store_wide_indexes+ execute("DELETE FROM spree_package_types WHERE seller_id IS NOT NULL")++ if supports_partial_index?+ remove_index :spree_package_types, name: SELLER_DEFAULT_INDEX+ remove_index :spree_package_types, name: MARKETPLACE_DEFAULT_INDEX+ add_index :spree_package_types, :store_id, unique: true,+ where: '"default" = TRUE', name: DEFAULT_PER_STORE_INDEX++ remove_index :spree_package_types, name: SELLER_NAME_INDEX+ remove_index :spree_package_types, name: MARKETPLACE_NAME_INDEX+ else+ remove_index :spree_package_types, name: SELLER_NAME_INDEX+ end++ add_index :spree_package_types, [:store_id, :name], unique: true, name: STORE_NAME_INDEX+ end++ # `Spree.mysql?` rather than a fresh adapter check: it matches Trilogy too,+ # which Rails reports as "Trilogy", and a hand-rolled /mysql/i test would+ # take the partial-index branch there and fail on a database that has none.+ def supports_partial_index?+ !Spree.mysql?+ end+enddiff --git a/spree/core/db/sample_data/fulfillment.rb b/spree/core/db/sample_data/fulfillment.rbindex 8284cd7a07..b67e5a1395 100644--- a/spree/core/db/sample_data/fulfillment.rb+++ b/spree/core/db/sample_data/fulfillment.rb@@ -42,7 +42,11 @@ end{ name: 'Master carton', kind: 'carton', length: 40, width: 30, height: 25, weight: 0.4, max_weight: 20 },{ name: 'Euro pallet', kind: 'pallet', length: 120, width: 80, height: 15, weight: 25, max_weight: 1_500 }].each do |attributes|- store.package_types.where(name: attributes[:name]).first_or_create! do |package_type|+ # `first_party`, because on a marketplace the store's packaging includes+ # every seller's: a seller who named a carton the same way would make this+ # seeder skip the marketplace's own, leaving the demo freight setup reading+ # that seller's measurements.+ store.package_types.first_party.where(name: attributes[:name]).first_or_create! do |package_type|package_type.assign_attributes(attributes.merge(dimensions_unit: 'cm', weight_unit: 'kg'))endenddiff --git a/spree/core/lib/spree/core/engine.rb b/spree/core/lib/spree/core/engine.rbindex 584879861b..13546f3e76 100644--- a/spree/core/lib/spree/core/engine.rb+++ b/spree/core/lib/spree/core/engine.rb@@ -377,6 +377,7 @@ module SpreeSpree::SellerRequirements::BillingAddress,Spree::SellerRequirements::ReturnsAddress,Spree::SellerRequirements::DeliveryMethod,+ Spree::SellerRequirements::PackageType,Spree::SellerRequirements::MinimumProducts,Spree::SellerRequirements::PayoutAccount,Spree::SellerRequirements::RequiredCustomFields,diff --git a/spree/core/lib/spree/core/permission_configuration.rb b/spree/core/lib/spree/core/permission_configuration.rbindex 73e00c93a3..a362172673 100644--- a/spree/core/lib/spree/core/permission_configuration.rb+++ b/spree/core/lib/spree/core/permission_configuration.rb@@ -386,7 +386,7 @@ module Spreeregister_resource(:settings, group: :settings, subjects: -> {[Spree::Store, Spree::PaymentMethod, Spree::Gateway,Spree::DeliveryZone, Spree::DeliveryZoneMember,- Spree::StockLocation, Spree::DeliveryProfile, Spree::PackageType,+ Spree::StockLocation, Spree::DeliveryProfile,Spree::Market, Spree::TaxCategory, Spree::TaxRate, Spree::AllowedOrigin,Spree::RefundReason, Spree::ReturnReason, Spree::ClaimReason,Spree::OrderCancellationReason, Spree::Channel,@@ -403,6 +403,14 @@ module Spreeregister_resource(:delivery_methods, group: :settings, audiences: %i[seller], subjects: -> {[Spree::DeliveryMethod, Spree::DeliveryMethodRule, Spree::DeliveryMethodService]})+ # What goods are packed into: the marketplace's boxes and cartons, and+ # each seller's own. Its own resource rather than part of `settings` for+ # the same reason `delivery_methods` is — a seller owns their packaging+ # and `settings` is never seller-grantable+ # (docs/plans/6.0-seller-package-types.md).+ register_resource(:package_types, group: :settings, audiences: %i[seller], subjects: -> {+ [Spree::PackageType]+ })register_resource(:webhooks, group: :settings, subjects: -> {[Spree::WebhookEndpoint, Spree::WebhookDelivery]})diff --git a/spree/core/lib/spree/testing_support/factories/package_type_factory.rb b/spree/core/lib/spree/testing_support/factories/package_type_factory.rbindex b602016c12..df0f809ffb 100644--- a/spree/core/lib/spree/testing_support/factories/package_type_factory.rb+++ b/spree/core/lib/spree/testing_support/factories/package_type_factory.rb@@ -15,6 +15,16 @@ FactoryBot.define domax_weight { 20 }end+ # A default box with every measurement the parcel quote needs — what the+ # `PackageType` onboarding requirement asks a seller for.+ trait :measured_default_box do+ default { true }+ length { 30 }+ width { 20 }+ height { 15 }+ weight { 0.4 }+ end+factory :pallet_package_type dokind { 'pallet' }sequence(:name) { |n| "Pallet #{n}" }diff --git a/spree/core/lib/spree/testing_support/factories/seller_requirement_factory.rb b/spree/core/lib/spree/testing_support/factories/seller_requirement_factory.rbindex 4a1e40e5aa..1012cf7304 100644--- a/spree/core/lib/spree/testing_support/factories/seller_requirement_factory.rb+++ b/spree/core/lib/spree/testing_support/factories/seller_requirement_factory.rb@@ -29,6 +29,10 @@ FactoryBot.define dotype { 'Spree::SellerRequirements::DeliveryMethod' }end+ factory :package_type_requirement, class: Spree::SellerRequirements::PackageType do+ type { 'Spree::SellerRequirements::PackageType' }+ end+factory :required_custom_fields_requirement, class: Spree::SellerRequirements::RequiredCustomFields dotype { 'Spree::SellerRequirements::RequiredCustomFields' }enddiff --git a/spree/core/spec/lib/spree/core/permission_configuration_spec.rb b/spree/core/spec/lib/spree/core/permission_configuration_spec.rbindex de334bbb25..226a87a01a 100644--- a/spree/core/spec/lib/spree/core/permission_configuration_spec.rb+++ b/spree/core/spec/lib/spree/core/permission_configuration_spec.rb@@ -69,10 +69,19 @@ RSpec.describe Spree::PermissionConfiguration doit 'opens the seller-facing core resources to sellers' doexpect(configuration.grantable_keys(:seller)).to include('read_products', 'write_products', 'read_orders', 'write_orders',- 'read_fulfillments', 'write_fulfillments', 'read_stock', 'write_stock', 'read_dashboard'+ 'read_fulfillments', 'write_fulfillments', 'read_stock', 'write_stock', 'read_dashboard',+ 'read_package_types', 'write_package_types')end+ # Packaging left `settings` precisely so a seller could hold it: a seller+ # owns their own boxes, and `settings` is never seller-grantable+ # (docs/plans/6.0-seller-package-types.md).+ it 'keeps package types out of the settings resource' do+ expect(configuration.resource(:settings).subjects).not_to include(Spree::PackageType)+ expect(configuration.resource(:package_types).subjects).to include(Spree::PackageType)+ end+it 'never opens the operator-only resources to sellers' doexpect(configuration.grantable_keys(:seller)).not_to include('read_settings', 'write_settings', 'read_staff', 'write_staff',diff --git a/spree/core/spec/models/spree/package_type_spec.rb b/spree/core/spec/models/spree/package_type_spec.rbindex cfc9a2b38d..b5eee69e94 100644--- a/spree/core/spec/models/spree/package_type_spec.rb+++ b/spree/core/spec/models/spree/package_type_spec.rb@@ -2,6 +2,7 @@ require 'spec_helper'RSpec.describe Spree::PackageType, type: :model dolet(:store) { @default_store }+ let(:seller) { create(:seller, store: store) }describe 'validations' doit 'refuses a kind outside the vocabulary' do@@ -24,6 +25,66 @@ RSpec.describe Spree::PackageType, type: :model doexpect(other).to be_validend++ # Each owner names their own packaging: a seller calling their carton+ # what the marketplace calls theirs is not a collision.+ it 'allows a seller the name the marketplace already uses' do+ create(:package_type, store: store, name: 'Master carton')+ sellers_own = build(:package_type, store: store, seller: seller, name: 'Master carton')++ expect(sellers_own).to be_valid+ end++ it 'refuses a duplicate name within one seller' do+ create(:package_type, store: store, seller: seller, name: 'Master carton')+ duplicate = build(:package_type, store: store, seller: seller, name: 'Master carton')++ expect(duplicate).not_to be_valid+ end++ it 'allows two sellers the same name' do+ create(:package_type, store: store, seller: seller, name: 'Master carton')+ other = build(:package_type, store: store, seller: create(:seller, store: store), name: 'Master carton')++ expect(other).to be_valid+ end+ end++ describe 'ownership' do+ let!(:marketplace_box) { create(:package_type, store: store) }+ let!(:sellers_box) { create(:package_type, store: store, seller: seller) }+ let!(:other_sellers_box) { create(:package_type, store: store, seller: create(:seller, store: store)) }++ it 'reads the marketplace’s own rows' do+ expect(described_class.first_party).to contain_exactly(marketplace_box)+ end++ it 'reads one seller’s rows' do+ expect(described_class.for_seller(seller)).to contain_exactly(sellers_box)+ end++ it 'takes an id as well as a record' do+ expect(described_class.for_seller(seller.id)).to contain_exactly(sellers_box)+ end++ # A seller packs into their own packaging and the marketplace's shared+ # vocabulary, never another seller's.+ it 'offers a seller their own rows and the marketplace’s' do+ expect(described_class.available_to_seller(seller)).to contain_exactly(marketplace_box, sellers_box)+ end++ it 'offers the operator the marketplace’s rows alone' do+ expect(described_class.available_to_seller(nil)).to contain_exactly(marketplace_box)+ end++ # A nil seller_id IS the marketplace's row, so releasing a departed+ # seller's rows would hand the operator a second default box.+ it 'keeps a departed seller’s rows pointing at them' do+ seller.destroy++ expect(sellers_box.reload.seller_id).to eq(seller.id)+ expect(sellers_box.seller).to eq(seller)+ endenddescribe 'the store default' do@@ -43,6 +104,36 @@ RSpec.describe Spree::PackageType, type: :model doexpect(other_default.reload).to be_defaultend++ # The operator holds one default box and each seller holds their own, so+ # promoting a seller's box must not take the marketplace's away.+ it 'leaves the marketplace default alone when a seller names theirs' do+ marketplace_default = create(:package_type, store: store, default: true)+ sellers_default = create(:package_type, store: store, seller: seller, default: true)++ expect(marketplace_default.reload).to be_default+ expect(sellers_default.reload).to be_default+ expect(store.reload.default_package_type).to eq(marketplace_default)+ expect(seller.reload.default_package_type).to eq(sellers_default)+ end++ it 'demotes only the same seller’s previous default' do+ first = create(:package_type, store: store, seller: seller, default: true)+ second = create(:package_type, store: store, seller: seller, default: true)+ other_seller = create(:seller, store: store)+ other_sellers_default = create(:package_type, store: store, seller: other_seller, default: true)++ expect(first.reload).not_to be_default+ expect(second.reload).to be_default+ expect(other_sellers_default.reload).to be_default+ end++ it 'reads the marketplace’s box through the store, never a seller’s' do+ sellers_only_default = create(:package_type, store: store, seller: seller, default: true)++ expect(store.reload.default_package_type).to be_nil+ expect(seller.reload.default_package_type).to eq(sellers_only_default)+ endenddescribe '#volume' do@@ -113,6 +204,16 @@ RSpec.describe Spree::PackageType, type: :model doexpect(first.reload).not_to be_defaultend++ # The marketplace's box is not a replacement for the seller's: it is a+ # different owner's row, so it cannot stand in as "another default".+ it 'refuses a seller’s only default even when the marketplace has one' do+ create(:package_type, store: store, default: true)+ sellers_default = create(:package_type, store: store, seller: seller, default: true)++ expect(sellers_default.update(default: false)).to be(false)+ expect(sellers_default.errors[:default]).to be_present+ endenddescribe 'changing kind' dodiff --git a/spree/core/spec/models/spree/seller_requirement_spec.rb b/spree/core/spec/models/spree/seller_requirement_spec.rbindex 4908a736ca..de5d27a805 100644--- a/spree/core/spec/models/spree/seller_requirement_spec.rb+++ b/spree/core/spec/models/spree/seller_requirement_spec.rb@@ -151,6 +151,7 @@ RSpec.describe Spree::SellerRequirement, type: :model doSpree::SellerRequirements::BillingAddress,Spree::SellerRequirements::ReturnsAddress,Spree::SellerRequirements::DeliveryMethod,+ Spree::SellerRequirements::PackageType,Spree::SellerRequirements::MinimumProducts])diff --git a/spree/core/spec/models/spree/seller_requirements_spec.rb b/spree/core/spec/models/spree/seller_requirements_spec.rbindex 6703016dfb..a0abc517e8 100644--- a/spree/core/spec/models/spree/seller_requirements_spec.rb+++ b/spree/core/spec/models/spree/seller_requirements_spec.rb@@ -230,6 +230,56 @@ RSpec.describe 'seller requirement kinds', type: :model doendend+ # Measurements, not merely a row: a default box with blank sides quotes the+ # goods alone (docs/plans/6.0-seller-package-types.md).+ describe Spree::SellerRequirements::PackageType do+ let(:requirement) { create(:package_type_requirement, store: store) }++ it 'is unmet while the seller has recorded no box' do+ expect(requirement.satisfied?(seller)).to be false+ end++ it 'is met by a fully measured default box of the seller’s own' do+ create(:package_type, :measured_default_box, store: store, seller: seller)++ expect(requirement.satisfied?(seller.reload)).to be true+ end++ it 'is not met by a box the seller has not marked default' do+ create(:package_type, :measured_default_box, store: store, seller: seller, default: false)++ expect(requirement.satisfied?(seller.reload)).to be false+ end++ # A seller quoting through the marketplace's shared rates still packs and+ # posts their own parcel, so the operator's box does not answer for them.+ it 'is not met by the marketplace’s own box' do+ create(:package_type, :measured_default_box, store: store)++ expect(requirement.satisfied?(seller.reload)).to be false+ end++ it 'is not met by another seller’s box' do+ create(:package_type, :measured_default_box, store: store, seller: create(:seller, store: store))++ expect(requirement.satisfied?(seller.reload)).to be false+ end++ %i[length width height weight].each do |measurement|+ it "is not met while #{measurement} is blank" do+ create(:package_type, :measured_default_box, store: store, seller: seller, measurement => nil)++ expect(requirement.satisfied?(seller.reload)).to be false+ end++ it "is not met while #{measurement} is zero" do+ create(:package_type, :measured_default_box, store: store, seller: seller, measurement => 0)++ expect(requirement.satisfied?(seller.reload)).to be false+ end+ end+ end+describe Spree::SellerRequirements::RequiredCustomFields dolet(:requirement) { create(:required_custom_fields_requirement, store: store) }diff --git a/spree/core/spec/models/spree/stock/package_spec.rb b/spree/core/spec/models/spree/stock/package_spec.rbindex 586f7ca929..e92584c26d 100644--- a/spree/core/spec/models/spree/stock/package_spec.rb+++ b/spree/core/spec/models/spree/stock/package_spec.rb@@ -129,6 +129,47 @@ module Spreeendend+ # A parcel leaving a seller's warehouse is theirs to measure: the+ # marketplace's box is the wrong size and the wrong tare for it+ # (docs/plans/6.0-seller-package-types.md).+ describe 'a package from a seller’s warehouse' do+ let(:seller) { create(:seller, store: order.store) }+ let(:stock_location) { build(:stock_location, store: order.store, seller: seller) }++ before { subject.add build_inventory_unit }++ it 'is quoted with the seller’s own box' do+ create(:package_type, store: order.store, default: true, weight: 2.5, weight_unit: 'lb',+ length: 12, width: 9, height: 4, dimensions_unit: 'in')+ create(:package_type, store: order.store, seller: seller, default: true,+ weight: 1, weight_unit: 'lb',+ length: 20, width: 16, height: 8, dimensions_unit: 'in')++ expect(subject.weight).to eq(26)+ expect(subject.dimensions).to eq(length: 20.0, width: 16.0, height: 8.0)+ end++ # A seller who has not recorded a box yet must not lose the tare+ # altogether; the onboarding requirement is what asks them for one.+ it 'falls back to the marketplace’s box when the seller has none' do+ create(:package_type, store: order.store, default: true, weight: 2.5, weight_unit: 'lb',+ length: 12, width: 9, height: 4, dimensions_unit: 'in')++ expect(subject.weight).to eq(27.5)+ expect(subject.dimensions).to eq(length: 12.0, width: 9.0, height: 4.0)+ end++ it 'never reads another seller’s box' do+ other_seller = create(:seller, store: order.store)+ create(:package_type, store: order.store, seller: other_seller, default: true,+ weight: 9, weight_unit: 'lb', length: 40, width: 40, height: 40,+ dimensions_unit: 'in')++ expect(subject.weight).to eq(25)+ expect(subject.dimensions).to be_nil+ end+ end+describe '#dimensions' doit 'is nil until the store has a fully measured default package' dosubject.add build_inventory_unitdiff --git a/spree/core/spec/models/spree/variant/shared_catalog_spec.rb b/spree/core/spec/models/spree/variant/shared_catalog_spec.rbindex 4b809ed011..782c974990 100644--- a/spree/core/spec/models/spree/variant/shared_catalog_spec.rb+++ b/spree/core/spec/models/spree/variant/shared_catalog_spec.rb@@ -128,6 +128,64 @@ describe Spree::Variant, type: :model doendend+ # Cartons are the same two-owner vocabulary as the packaging they describe:+ # the marketplace's are shared, a seller's are theirs alone. Another+ # seller's carton must never be reachable by id — its measurements would+ # feed this variant's freight rollups+ # (docs/plans/6.0-seller-package-types.md).+ describe 'which carton a variant may be packed into' do+ let(:owned) { create(:product, store: store, seller: seller) }+ let(:master) { create(:product, store: store) }++ it 'accepts the marketplace’s carton on a seller’s variant' do+ carton = create(:carton_package_type, store: store)+ variant = build(:variant, product: owned, carton_package_type: carton)++ expect(variant).to be_valid+ end++ it 'accepts the seller’s own carton' do+ carton = create(:carton_package_type, store: store, seller: seller)+ variant = build(:variant, product: owned, carton_package_type: carton)++ expect(variant).to be_valid+ end++ it 'refuses another seller’s carton' do+ carton = create(:carton_package_type, store: store, seller: other_seller)+ variant = build(:variant, product: owned, carton_package_type: carton)++ expect(variant).not_to be_valid+ expect(variant.errors[:carton_package_type]).to be_present+ end++ # A row on a master product carries its own seller, so the check reads+ # the resolved owner rather than the product's.+ it 'refuses another seller’s carton on a master product row' do+ carton = create(:carton_package_type, store: store, seller: other_seller)+ variant = build(:variant, product: master, seller: seller, carton_package_type: carton)++ expect(variant).not_to be_valid+ expect(variant.errors[:carton_package_type]).to be_present+ end++ it 'refuses a seller’s carton on the operator’s own variant' do+ carton = create(:carton_package_type, store: store, seller: seller)+ variant = build(:variant, product: master, carton_package_type: carton)++ expect(variant).not_to be_valid+ expect(variant.errors[:carton_package_type]).to be_present+ end++ it 'refuses a carton from another store' do+ carton = create(:carton_package_type, store: create(:store))+ variant = build(:variant, product: owned, carton_package_type: carton)++ expect(variant).not_to be_valid+ expect(variant.errors[:carton_package_type]).to be_present+ end+ end+describe 'SKU uniqueness' dolet(:product) { create(:product, store: store) }let(:other_product) { create(:product, store: store) }diff --git a/spree/core/spec/services/spree/imports/row_processors/product_variant_spec.rb b/spree/core/spec/services/spree/imports/row_processors/product_variant_spec.rbindex 3f8e19b885..fe26bd30b1 100644--- a/spree/core/spec/services/spree/imports/row_processors/product_variant_spec.rb+++ b/spree/core/spec/services/spree/imports/row_processors/product_variant_spec.rb@@ -118,6 +118,30 @@ RSpec.describe Spree::Imports::RowProcessors::ProductVariant, type: :service doexpect(product.default_variant.carton_package_type).to be_nilendend++ # A seller's spreadsheet names their own cartons and the marketplace's+ # shared ones, never another seller's+ # (docs/plans/6.0-seller-package-types.md).+ context 'when a seller imports' do+ let(:seller) { create(:seller, store: store) }+ let(:import) { create(:product_import, store: store, seller: seller) }++ it 'packs into the marketplace’s carton when the seller has none of that name' do+ expect(product.default_variant.carton_package_type).to eq(carton)+ end++ it 'prefers the seller’s own carton over a marketplace carton of the same name' do+ sellers_own = create(:package_type, store: store, seller: seller, kind: 'carton', name: 'Large carton')++ expect(product.default_variant.carton_package_type).to eq(sellers_own)+ end++ it 'leaves the variant unpacked rather than reaching for another seller’s carton' do+ carton.update!(seller: create(:seller, store: store))++ expect(product.default_variant.carton_package_type).to be_nil+ end+ endendcontext 'when importing a product row' do