{"openapi":"3.1.2","jsonSchemaDialect":"https://json-schema.org/draft/2020-12/schema","info":{"title":"Personmade API","version":"1.0.0","summary":"Organization-scoped product source-of-truth API.","description":"Organization-scoped CRUD for the canonical sellable catalog, Etsy/Shopify/Personmade listing projections, location inventory, immutable order lines, fulfillment, private assets, and append-only activity.","license":{"name":"Proprietary","identifier":"LicenseRef-Proprietary"}},"servers":[{"url":"https://www.personmade.club/api/v1","description":"This Personmade origin"}],"tags":[{"name":"Product types","description":"Reusable context and listing templates for product families."},{"name":"Products","description":"Draft and approved products within the organization catalog. A product type must be approved before products can be filed under it."},{"name":"Catalog","description":"Up to three ordered option axes and explicit sparse variants with canonical fulfillment, supply, shipping, and inventory rules."},{"name":"Shop policies","description":"Canonical shipping profiles, destination rates, return policies, and the remote ids connected shops use for them."},{"name":"Etsy mirrors","description":"Durable Etsy publication relationships. Personmade owns canonical fields; each mirror owns only Etsy-specific choices."},{"name":"Personalization","description":"Buyer input that does not create inventory variants."},{"name":"Catalog media","description":"Reviewed product, listing, and variant asset selections pinned to source bytes."},{"name":"Inventory","description":"Location-aware append-only quantities and time-bounded reservations."},{"name":"Listing projections","description":"Variant subsets, remote mappings, and immutable provider-typed desired revisions."},{"name":"Order lines","description":"Immutable product, option, personalization, price, and fulfillment snapshots."},{"name":"Fulfillment lines","description":"Line-level fulfilled quantities for physical and digital order lines."},{"name":"Connections","description":"Organization-owned Etsy, Shopify, and extensible storefront connections with encrypted credential storage."},{"name":"Listings","description":"Etsy, Shopify, and Personmade publication identities with separate observed payloads."},{"name":"Orders","description":"Multi-line Etsy, Shopify, and Personmade order headers."},{"name":"Fulfillments","description":"One or more fulfillment records for each order."},{"name":"Assets","description":"Private source artwork, photos, and working files, all owned by a product."},{"name":"Activity","description":"Append-only mutation history for reconciliation."}],"security":[{"bearerAuth":[]}],"paths":{"/product-types":{"get":{"tags":["Product types"],"summary":"List product types","operationId":"listProductTypes","description":"Returns up to 500 records in newest-first order.","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ProductType"}}}}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Product types"],"summary":"Create a product type","operationId":"createProductType","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductTypeInput"}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ProductType"}}}}}},"400":{"description":"Malformed request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/product-types/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Record UUID.","schema":{"type":"string","format":"uuid"}}],"get":{"tags":["Product types"],"summary":"Get a product type","operationId":"getProductType","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ProductType"}}}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["Product types"],"summary":"Update selected product type fields","operationId":"updateProductType","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductTypeInputPatch"}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ProductType"}}}}}},"400":{"description":"Malformed request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"tags":["Product types"],"summary":"Update supplied product type fields","operationId":"putProductType","description":"PUT currently has the same partial-update semantics as PATCH.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductTypeInputPatch"}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ProductType"}}}}}},"400":{"description":"Malformed request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Product types"],"summary":"Delete a product type","operationId":"deleteProductType","responses":{"204":{"description":"Deleted."},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/products":{"get":{"tags":["Products"],"summary":"List products","operationId":"listProducts","description":"Returns up to 500 records in newest-first order.","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}}}}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Products"],"summary":"Create a product","operationId":"createProduct","description":"A product type must be approved before products can be filed under it.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductInput"}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Product"}}}}}},"400":{"description":"Malformed request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed. A product type must be approved before products can be filed under it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/products/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Record UUID.","schema":{"type":"string","format":"uuid"}}],"get":{"tags":["Products"],"summary":"Get a product","operationId":"getProduct","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Product"}}}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["Products"],"summary":"Update selected product fields","operationId":"updateProduct","description":"A product type must be approved before products can be filed under it.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductInputPatch"}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Product"}}}}}},"400":{"description":"Malformed request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed. A product type must be approved before products can be filed under it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"tags":["Products"],"summary":"Update supplied product fields","operationId":"putProduct","description":"PUT currently has the same partial-update semantics as PATCH. A product type must be approved before products can be filed under it.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductInputPatch"}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Product"}}}}}},"400":{"description":"Malformed request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed. A product type must be approved before products can be filed under it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Products"],"summary":"Delete a product","operationId":"deleteProduct","responses":{"204":{"description":"Deleted."},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/listings":{"get":{"tags":["Listings"],"summary":"List listings","operationId":"listListings","description":"Returns up to 500 records in newest-first order.","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Listing"}}}}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Listings"],"summary":"Create a listing","operationId":"createListing","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingInput"}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Listing"}}}}}},"400":{"description":"Malformed request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/listings/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Record UUID.","schema":{"type":"string","format":"uuid"}}],"get":{"tags":["Listings"],"summary":"Get a listing","operationId":"getListing","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Listing"}}}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["Listings"],"summary":"Update selected listing fields","operationId":"updateListing","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingInputPatch"}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Listing"}}}}}},"400":{"description":"Malformed request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"tags":["Listings"],"summary":"Update supplied listing fields","operationId":"putListing","description":"PUT currently has the same partial-update semantics as PATCH.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingInputPatch"}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Listing"}}}}}},"400":{"description":"Malformed request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Listings"],"summary":"Delete a listing","operationId":"deleteListing","responses":{"204":{"description":"Deleted."},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/orders":{"get":{"tags":["Orders"],"summary":"List orders","operationId":"listOrders","description":"Returns up to 500 records in newest-first order.","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Order"}}}}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Orders"],"summary":"Create an order","operationId":"createOrder","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderInput"}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Order"}}}}}},"400":{"description":"Malformed request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/orders/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Record UUID.","schema":{"type":"string","format":"uuid"}}],"get":{"tags":["Orders"],"summary":"Get an order","operationId":"getOrder","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Order"}}}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["Orders"],"summary":"Update selected order fields","operationId":"updateOrder","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderInputPatch"}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Order"}}}}}},"400":{"description":"Malformed request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"tags":["Orders"],"summary":"Update supplied order fields","operationId":"putOrder","description":"PUT currently has the same partial-update semantics as PATCH.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderInputPatch"}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Order"}}}}}},"400":{"description":"Malformed request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Orders"],"summary":"Delete an order","operationId":"deleteOrder","responses":{"204":{"description":"Deleted."},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fulfillments":{"get":{"tags":["Fulfillments"],"summary":"List fulfillments","operationId":"listFulfillments","description":"Returns up to 500 records in newest-first order.","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Fulfillment"}}}}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Fulfillments"],"summary":"Create a fulfillment","operationId":"createFulfillment","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FulfillmentInput"}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Fulfillment"}}}}}},"400":{"description":"Malformed request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fulfillments/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Record UUID.","schema":{"type":"string","format":"uuid"}}],"get":{"tags":["Fulfillments"],"summary":"Get a fulfillment","operationId":"getFulfillment","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Fulfillment"}}}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["Fulfillments"],"summary":"Update selected fulfillment fields","operationId":"updateFulfillment","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FulfillmentInputPatch"}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Fulfillment"}}}}}},"400":{"description":"Malformed request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"tags":["Fulfillments"],"summary":"Update supplied fulfillment fields","operationId":"putFulfillment","description":"PUT currently has the same partial-update semantics as PATCH.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FulfillmentInputPatch"}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Fulfillment"}}}}}},"400":{"description":"Malformed request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Fulfillments"],"summary":"Delete a fulfillment","operationId":"deleteFulfillment","responses":{"204":{"description":"Deleted."},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/product-types/{id}/approve":{"parameters":[{"name":"id","in":"path","required":true,"description":"Record UUID.","schema":{"type":"string","format":"uuid"}}],"post":{"tags":["Product types"],"summary":"Approve a product type","operationId":"approveProductType","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ProductType"}}}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/product-types/{productTypeId}/etsy-configuration":{"parameters":[{"name":"productTypeId","in":"path","required":true,"description":"Product type UUID.","schema":{"type":"string","format":"uuid"}}],"get":{"tags":["Product types"],"summary":"Read reusable Etsy configuration","operationId":"getEtsyProductTypeConfiguration","description":"Returns the Etsy values inherited by this product type's mirrors, including per-shop shipping, return, and processing profile ids.","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/EtsyProductTypeConfiguration"}}}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"tags":["Product types"],"summary":"Create or replace reusable Etsy configuration","operationId":"putEtsyProductTypeConfiguration","description":"Validates the category and variation mappings with Etsy, saves all type-owned mirror values, and synchronizes existing automatic mirrors.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EtsyProductTypeConfigurationInput"}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/EtsyProductTypeConfiguration"}}}}}},"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/EtsyProductTypeConfiguration"}}}}}},"400":{"description":"Malformed request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/products/{id}/approve":{"parameters":[{"name":"id","in":"path","required":true,"description":"Record UUID.","schema":{"type":"string","format":"uuid"}}],"post":{"tags":["Products"],"summary":"Approve a product after it has at least 2 product photos","operationId":"approveProduct","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Product"}}}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/products/{id}/unapprove":{"parameters":[{"name":"id","in":"path","required":true,"description":"Record UUID.","schema":{"type":"string","format":"uuid"}}],"post":{"tags":["Products"],"summary":"Return an approved product to draft","operationId":"unapproveProduct","description":"Clears the approval. The product keeps its photos, listings, and catalog data; a product that is already a draft is a 409.","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Product"}}}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/products/{id}/assets":{"parameters":[{"name":"id","in":"path","required":true,"description":"Record UUID.","schema":{"type":"string","format":"uuid"}}],"post":{"tags":["Assets"],"summary":"Upload a product asset","operationId":"uploadProductAsset","description":"Streams a raw binary body to private storage. Maximum size is 100 MB, rejected from Content-Length before the body is read when the client declares it. Product photos are selected for storefront publishing by default; other asset kinds remain private.","parameters":[{"name":"kind","in":"query","required":true,"schema":{"type":"string","enum":["product_photo","source","sketch","other"]}},{"name":"X-Filename","in":"header","required":true,"schema":{"type":"string","maxLength":180}}],"requestBody":{"required":true,"content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}},"image/*":{"schema":{"type":"string","format":"binary"}},"video/*":{"schema":{"type":"string","format":"binary"}}}},"responses":{"201":{"description":"Uploaded.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Asset"}}}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Asset exceeds 100 MB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/assets":{"get":{"tags":["Assets"],"summary":"List asset metadata","operationId":"listAssets","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Asset"}}}}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/assets/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Record UUID.","schema":{"type":"string","format":"uuid"}}],"get":{"tags":["Assets"],"summary":"Download an asset","operationId":"downloadAsset","description":"Always an attachment of type application/octet-stream, whatever the upload claimed: the stored content type is catalogue metadata, never a rendering instruction. Use /assets/{id}/view to display an image or video instead.","responses":{"200":{"description":"The private file.","headers":{"Content-Disposition":{"schema":{"type":"string"}},"ETag":{"schema":{"type":"string"}}},"content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["Assets"],"summary":"Rename an asset","operationId":"renameAsset","description":"The filename is the only writable field. The stored object keeps the key it was written under.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssetRename"}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Asset"}}}}}},"400":{"description":"Malformed request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Assets"],"summary":"Delete an asset and its stored file","operationId":"deleteAsset","responses":{"204":{"description":"Deleted."},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/assets/{id}/view":{"parameters":[{"name":"id","in":"path","required":true,"description":"Record UUID.","schema":{"type":"string","format":"uuid"}}],"get":{"tags":["Assets"],"summary":"View an asset inline","operationId":"viewAsset","description":"Serves the object under its own content type, for displaying it rather than saving it. Only PNG, JPEG, GIF, WebP, AVIF, MP4, WebM, Ogg and QuickTime are served that way, always with nosniff and a sandboxing CSP; every other type falls back to the same attachment download as /assets/{id}. Answers Range requests so a video can seek, and conditional requests with a 304 so a preview is fetched once.","parameters":[{"name":"size","in":"query","required":false,"description":"`thumb` returns the 640px copy beside the file, making one from the original the first time it is asked for. A format that cannot be transformed, or a transform that fails, falls back to the full file.","schema":{"type":"string","enum":["thumb"]}}],"responses":{"200":{"description":"The private file, under its stored content type.","headers":{"Content-Disposition":{"schema":{"type":"string"}},"Accept-Ranges":{"schema":{"type":"string"}},"ETag":{"schema":{"type":"string"}}},"content":{"image/*":{"schema":{"type":"string","format":"binary"}},"video/*":{"schema":{"type":"string","format":"binary"}},"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"206":{"description":"The requested byte range of an inline media file."},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/assets/{id}/watermarked":{"parameters":[{"name":"id","in":"path","required":true,"description":"Record UUID.","schema":{"type":"string","format":"uuid"}}],"get":{"tags":["Assets"],"summary":"Download a watermarked copy","operationId":"downloadWatermarkedAsset","description":"Asks Cloudflare Images to tile Personmade's proof mark over an eligible JPEG, PNG, or WebP and returns the WebP immediately. The private original remains unchanged and no derivative is stored.","responses":{"200":{"description":"The current private watermarked WebP, served as an attachment.","headers":{"Content-Disposition":{"schema":{"type":"string"}}},"content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/events":{"get":{"tags":["Activity"],"summary":"List the latest 500 app events","operationId":"listEvents","description":"Returns the append-only activity stream in newest-first order.","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AppEvent"}}}}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/connections":{"get":{"tags":["Connections"],"summary":"List organization marketplace connections","operationId":"listMarketplaceConnections","description":"Returns safe connection metadata and a credentials_configured flag. Credential values are never returned.","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MarketplaceConnection"}}}}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Connections"],"summary":"Create an organization marketplace connection","operationId":"createMarketplaceConnection","description":"Accepts organization-owned credentials, encrypts them before D1 storage, and excludes them from the response and activity event.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceConnectionInput"}}}},"responses":{"201":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/MarketplaceConnection"}}}}}},"400":{"description":"Malformed request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/connections/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Record UUID.","schema":{"type":"string","format":"uuid"}}],"get":{"tags":["Connections"],"summary":"Read safe marketplace connection metadata","operationId":"getMarketplaceConnection","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/MarketplaceConnection"}}}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["Connections"],"summary":"Update connection metadata or replace credentials","operationId":"updateMarketplaceConnection","description":"Omit credentials to keep the encrypted values. Supplying credentials replaces the full encrypted credential object.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceConnectionUpdate"}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/MarketplaceConnection"}}}}}},"400":{"description":"Malformed request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Connections"],"summary":"Delete an unlinked marketplace connection","operationId":"deleteMarketplaceConnection","description":"A connection still used by a listing cannot be deleted.","responses":{"204":{"description":"Deleted."},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/connections/{id}/disconnect":{"parameters":[{"name":"id","in":"path","required":true,"description":"Record UUID.","schema":{"type":"string","format":"uuid"}}],"post":{"tags":["Connections"],"summary":"Disconnect and erase organization credentials","operationId":"disconnectMarketplaceConnection","description":"Erases the encrypted credential material while preserving safe account identity and listing mappings for history and reconnection.","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/MarketplaceConnection"}}}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/connections/{connectionId}/etsy-policies":{"parameters":[{"name":"connectionId","in":"path","required":true,"description":"Active Etsy connection UUID.","schema":{"type":"string","format":"uuid"}}],"get":{"tags":["Product types"],"summary":"Read shipping, return, and processing profiles from Etsy","operationId":"readEtsyPolicies","description":"Returns the real shop policy and processing-profile ids used to configure an Etsy product type for this connection. It refreshes the Etsy access token when necessary.","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/EtsyPolicies"}}}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/connections/{connectionId}/etsy-configuration-choices":{"parameters":[{"name":"connectionId","in":"path","required":true,"description":"Active Etsy connection UUID.","schema":{"type":"string","format":"uuid"}},{"name":"taxonomy_id","in":"query","required":false,"schema":{"type":"integer","minimum":1},"description":"Include variation properties supported by this Etsy taxonomy node."}],"get":{"tags":["Product types"],"summary":"Read Etsy categories and variation properties","operationId":"readEtsyConfigurationChoices","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/EtsyConfigurationChoices"}}}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/products/{productId}/etsy-mirrors":{"parameters":[{"name":"productId","in":"path","required":true,"description":"Canonical product UUID.","schema":{"type":"string","format":"uuid"}}],"get":{"tags":["Etsy mirrors"],"summary":"List a product's Etsy mirrors","operationId":"listEtsyMirrors","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EtsyMirror"}}}}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Etsy mirrors"],"summary":"Create and synchronize an Etsy mirror","operationId":"createEtsyMirror","description":"Persists the optional tag override and inherits all other Etsy choices from the product type. It adopts and updates a compatible Etsy listing already linked to this product; otherwise it creates a draft.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EtsyMirrorInput"}}}},"responses":{"201":{"description":"Mirror created by adopting an existing Etsy listing or creating a new Etsy draft.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/EtsyMirror"}}}}}},"400":{"description":"Malformed request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/etsy-mirrors/{listingId}":{"parameters":[{"name":"listingId","in":"path","required":true,"description":"Mirror listing UUID.","schema":{"type":"string","format":"uuid"}}],"patch":{"tags":["Etsy mirrors"],"summary":"Change Etsy-only choices","operationId":"updateEtsyMirror","description":"Only tags and synchronization can differ from the product type.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EtsyMirrorUpdate"}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/EtsyMirror"}}}}}},"400":{"description":"Malformed request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/etsy-mirrors/{listingId}/sync":{"parameters":[{"name":"listingId","in":"path","required":true,"description":"Mirror listing UUID.","schema":{"type":"string","format":"uuid"}}],"post":{"tags":["Etsy mirrors"],"summary":"Send canonical product state to Etsy now","operationId":"syncEtsyMirror","description":"Uses the latest product-type Etsy configuration and retains only the mirror's tag override and synchronization setting.","responses":{"200":{"description":"Synchronized remote listing identity and URL.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/shipping-profiles":{"get":{"tags":["Shop policies"],"summary":"List canonical shipping profiles","operationId":"listShippingProfiles","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ShippingProfile"}}}}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Shop policies"],"summary":"Create a canonical shipping profile","operationId":"createShippingProfile","description":"A profile owns its origin and processing window. Add destination prices through its rates collection.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShippingProfileInput"}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ShippingProfile"}}}}}},"400":{"description":"Malformed request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/shipping-profiles/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Record UUID.","schema":{"type":"string","format":"uuid"}}],"patch":{"tags":["Shop policies"],"summary":"Update a shipping profile","operationId":"updateShippingProfile","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShippingProfileInputPatch"}}}},"responses":{"200":{"description":"Updated.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ShippingProfile"}}}}}},"400":{"description":"Malformed request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Shop policies"],"summary":"Delete an unused shipping profile","operationId":"deleteShippingProfile","description":"A profile referenced by a variant cannot be deleted.","responses":{"204":{"description":"Deleted."},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/shipping-profiles/{profileId}/rates":{"parameters":[{"name":"profileId","in":"path","required":true,"description":"Shipping-profile UUID.","schema":{"type":"string","format":"uuid"}}],"get":{"tags":["Shop policies"],"summary":"List a shipping profile's destination rates","operationId":"listShippingRates","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ShippingRate"}}}}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Shop policies"],"summary":"Add a destination rate","operationId":"createShippingRate","description":"A profile can have one everywhere rate and one rate for each country.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShippingRateInput"}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ShippingRate"}}}}}},"400":{"description":"Malformed request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/shipping-rates/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Record UUID.","schema":{"type":"string","format":"uuid"}}],"delete":{"tags":["Shop policies"],"summary":"Delete a shipping rate","operationId":"deleteShippingRate","responses":{"204":{"description":"Deleted."},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/return-policies":{"get":{"tags":["Shop policies"],"summary":"List canonical return policies","operationId":"listReturnPolicies","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ReturnPolicy"}}}}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Shop policies"],"summary":"Create a canonical return policy","operationId":"createReturnPolicy","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnPolicyInput"}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ReturnPolicy"}}}}}},"400":{"description":"Malformed request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/return-policies/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Record UUID.","schema":{"type":"string","format":"uuid"}}],"patch":{"tags":["Shop policies"],"summary":"Update a return policy","operationId":"updateReturnPolicy","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnPolicyInputPatch"}}}},"responses":{"200":{"description":"Updated.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ReturnPolicy"}}}}}},"400":{"description":"Malformed request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Shop policies"],"summary":"Delete an unused return policy","operationId":"deleteReturnPolicy","description":"A policy referenced by a product cannot be deleted.","responses":{"204":{"description":"Deleted."},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/shipping-profile-mappings":{"get":{"tags":["Shop policies"],"summary":"List shipping profile marketplace mappings","operationId":"listShippingProfileMappings","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ShippingProfileMapping"}}}}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"tags":["Shop policies"],"summary":"Create or replace a shipping profile marketplace mapping","operationId":"putShippingProfileMapping","description":"Upserts the remote id for one canonical policy and connection. Remote ids are read from the marketplace account, not invented per listing.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShippingProfileMappingInput"}}}},"responses":{"200":{"description":"Updated.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ShippingProfileMapping"}}}}}},"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ShippingProfileMapping"}}}}}},"400":{"description":"Malformed request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/shipping-profile-mappings/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Record UUID.","schema":{"type":"string","format":"uuid"}}],"delete":{"tags":["Shop policies"],"summary":"Delete a shipping-profile marketplace mapping","operationId":"deleteShippingProfileMapping","responses":{"204":{"description":"Deleted."},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/return-policy-mappings":{"get":{"tags":["Shop policies"],"summary":"List return policy marketplace mappings","operationId":"listReturnPolicyMappings","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ReturnPolicyMapping"}}}}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"tags":["Shop policies"],"summary":"Create or replace a return policy marketplace mapping","operationId":"putReturnPolicyMapping","description":"Upserts the remote id for one canonical policy and connection. Remote ids are read from the marketplace account, not invented per listing.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnPolicyMappingInput"}}}},"responses":{"200":{"description":"Updated.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ReturnPolicyMapping"}}}}}},"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ReturnPolicyMapping"}}}}}},"400":{"description":"Malformed request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/return-policy-mappings/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Record UUID.","schema":{"type":"string","format":"uuid"}}],"delete":{"tags":["Shop policies"],"summary":"Delete a return-policy marketplace mapping","operationId":"deleteReturnPolicyMapping","responses":{"204":{"description":"Deleted."},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/products/{productId}/catalog":{"parameters":[{"name":"productId","in":"path","required":true,"description":"Product UUID.","schema":{"type":"string","format":"uuid"}}],"get":{"tags":["Catalog"],"summary":"Read the complete canonical product","operationId":"getProductCatalog","description":"Returns the product's return-policy reference, ordered options and values, explicit sparse variants with supply and shipping fields, personalization, reviewed media, and inventory items. A product without visible options still returns its one stable default variant.","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ProductCatalog"}}}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/products/{productId}/options":{"parameters":[{"name":"productId","in":"path","required":true,"description":"Product UUID.","schema":{"type":"string","format":"uuid"}}],"post":{"tags":["Catalog"],"summary":"Add an ordered option axis","operationId":"createProductOption","description":"A product can have zero to three axes. Existing variants atomically select the first supplied value, so no active variant is left invalid.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogOptionInput"}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/CatalogRecord"}}}}}},"400":{"description":"Malformed request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/product-options/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Record UUID.","schema":{"type":"string","format":"uuid"}}],"patch":{"tags":["Catalog"],"summary":"Rename or reorder an option axis","operationId":"updateProductOption","description":"Reordering also rebuilds every canonical variant selection key atomically.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogOptionPatch"}}}},"responses":{"200":{"description":"Updated.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/CatalogRecord"}}}}}},"400":{"description":"Malformed request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Catalog"],"summary":"Remove an option axis","operationId":"deleteProductOption","description":"Rejected if removing the axis would create duplicate variant combinations.","responses":{"204":{"description":"Deleted."},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/product-options/{optionId}/values":{"parameters":[{"name":"optionId","in":"path","required":true,"description":"Product-option UUID.","schema":{"type":"string","format":"uuid"}}],"post":{"tags":["Catalog"],"summary":"Add an option value","operationId":"createProductOptionValue","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptionValueInput"}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/CatalogRecord"}}}}}},"400":{"description":"Malformed request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/product-option-values/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Record UUID.","schema":{"type":"string","format":"uuid"}}],"patch":{"tags":["Catalog"],"summary":"Rename or reorder an option value","operationId":"updateProductOptionValue","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptionValueInput"}}}},"responses":{"200":{"description":"Updated.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/CatalogRecord"}}}}}},"400":{"description":"Malformed request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Catalog"],"summary":"Remove an unused option value","operationId":"deleteProductOptionValue","description":"A value selected by any variant cannot be removed.","responses":{"204":{"description":"Deleted."},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/products/{productId}/variants":{"parameters":[{"name":"productId","in":"path","required":true,"description":"Product UUID.","schema":{"type":"string","format":"uuid"}}],"post":{"tags":["Catalog"],"summary":"Create one explicit purchasable variant","operationId":"createProductVariant","description":"Sparse combinations are valid and no Cartesian product is generated. The complete selected combination must be unique within the product.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VariantInput"}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/CatalogRecord"}}}}}},"400":{"description":"Malformed request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/product-variants/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Record UUID.","schema":{"type":"string","format":"uuid"}}],"patch":{"tags":["Catalog"],"summary":"Update a variant or its complete selection","operationId":"updateProductVariant","description":"Variant UUID is stable identity; SKU is nullable, repeatable merchant data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VariantInput"}}}},"responses":{"200":{"description":"Updated.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/CatalogRecord"}}}}}},"400":{"description":"Malformed request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Catalog"],"summary":"Remove an unmapped variant","operationId":"deleteProductVariant","description":"Every product must keep at least one explicit variant.","responses":{"204":{"description":"Deleted."},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/product-variants/{id}/media":{"parameters":[{"name":"id","in":"path","required":true,"description":"Record UUID.","schema":{"type":"string","format":"uuid"}}],"put":{"tags":["Catalog media"],"summary":"Replace a variant's ordered asset associations","operationId":"replaceVariantMedia","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VariantMediaInput"}}}},"responses":{"200":{"description":"Updated.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/CatalogRecord"}}}}}},"400":{"description":"Malformed request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/products/{productId}/customizations":{"parameters":[{"name":"productId","in":"path","required":true,"description":"Product UUID.","schema":{"type":"string","format":"uuid"}}],"post":{"tags":["Personalization"],"summary":"Add buyer personalization","operationId":"createProductCustomization","description":"Personalization does not create variants. Canonical kinds are text, single_select, and file; provider validators apply narrower provider limits.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomizationInput"}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/CatalogRecord"}}}}}},"400":{"description":"Malformed request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/product-customizations/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Record UUID.","schema":{"type":"string","format":"uuid"}}],"patch":{"tags":["Personalization"],"summary":"Update buyer personalization","operationId":"updateProductCustomization","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomizationInput"}}}},"responses":{"200":{"description":"Updated.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/CatalogRecord"}}}}}},"400":{"description":"Malformed request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Personalization"],"summary":"Remove buyer personalization","operationId":"deleteProductCustomization","responses":{"204":{"description":"Deleted."},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/product-customizations/{customizationId}/choices":{"parameters":[{"name":"customizationId","in":"path","required":true,"description":"Customization UUID.","schema":{"type":"string","format":"uuid"}}],"post":{"tags":["Personalization"],"summary":"Add a single-select choice","operationId":"createCustomizationChoice","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptionValueInput"}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/CatalogRecord"}}}}}},"400":{"description":"Malformed request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/product-customization-choices/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Record UUID.","schema":{"type":"string","format":"uuid"}}],"patch":{"tags":["Personalization"],"summary":"Update a single-select choice","operationId":"updateCustomizationChoice","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptionValueInput"}}}},"responses":{"200":{"description":"Updated.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/CatalogRecord"}}}}}},"400":{"description":"Malformed request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Personalization"],"summary":"Remove a single-select choice","operationId":"deleteCustomizationChoice","responses":{"204":{"description":"Deleted."},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/products/{productId}/media":{"parameters":[{"name":"productId","in":"path","required":true,"description":"Product UUID.","schema":{"type":"string","format":"uuid"}}],"get":{"tags":["Catalog media"],"summary":"List reviewed product media","operationId":"listProductMedia","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CatalogRecord"}}}}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Catalog media"],"summary":"Select reviewed product media","operationId":"createProductMedia","description":"The source ETag or checksum pins the reviewed bytes.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MediaSelectionInput"}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/CatalogRecord"}}}}}},"400":{"description":"Malformed request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/product-media/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Record UUID.","schema":{"type":"string","format":"uuid"}}],"delete":{"tags":["Catalog media"],"summary":"Remove product media selection","operationId":"deleteProductMedia","responses":{"204":{"description":"Deleted."},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/inventory-locations":{"get":{"tags":["Inventory"],"summary":"List inventory locations","operationId":"listInventoryLocations","description":"Every organization has one required active default location.","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CatalogRecord"}}}}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Inventory"],"summary":"Create an inventory location","operationId":"createInventoryLocation","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryLocationInput"}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/CatalogRecord"}}}}}},"400":{"description":"Malformed request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/inventory-locations/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Record UUID.","schema":{"type":"string","format":"uuid"}}],"patch":{"tags":["Inventory"],"summary":"Update an inventory location","operationId":"updateInventoryLocation","description":"The required default location cannot be deactivated or removed.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryLocationInput"}}}},"responses":{"200":{"description":"Updated.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/CatalogRecord"}}}}}},"400":{"description":"Malformed request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Inventory"],"summary":"Delete an unused non-default location","operationId":"deleteInventoryLocation","responses":{"204":{"description":"Deleted."},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/inventory-items":{"get":{"tags":["Inventory"],"summary":"List product inventory items","operationId":"listInventoryItems","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CatalogRecord"}}}}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Inventory"],"summary":"Create a product inventory item","operationId":"createInventoryItem","description":"Several variants can reference one stock identity; this does not add bundle semantics.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryItemInput"}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/CatalogRecord"}}}}}},"400":{"description":"Malformed request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/inventory-items/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Record UUID.","schema":{"type":"string","format":"uuid"}}],"patch":{"tags":["Inventory"],"summary":"Update inventory policy","operationId":"updateInventoryItem","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryItemInput"}}}},"responses":{"200":{"description":"Updated.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/CatalogRecord"}}}}}},"400":{"description":"Malformed request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Inventory"],"summary":"Delete an unused inventory item","operationId":"deleteInventoryItem","responses":{"204":{"description":"Deleted."},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/inventory-adjustments":{"get":{"tags":["Inventory"],"summary":"List the append-only inventory ledger","operationId":"listInventoryAdjustments","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CatalogRecord"}}}}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Inventory"],"summary":"Append an inventory quantity adjustment","operationId":"createInventoryAdjustment","description":"Source plus idempotency_key is unique per organization.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryAdjustmentInput"}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/CatalogRecord"}}}}}},"400":{"description":"Malformed request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/inventory-reservations":{"get":{"tags":["Inventory"],"summary":"List inventory reservations","operationId":"listInventoryReservations","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CatalogRecord"}}}}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Inventory"],"summary":"Hold available quantity for a checkout","operationId":"createInventoryReservation","description":"Active, unexpired reservations reduce availability.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryReservationInput"}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/CatalogRecord"}}}}}},"400":{"description":"Malformed request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/inventory-reservations/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Record UUID.","schema":{"type":"string","format":"uuid"}}],"patch":{"tags":["Inventory"],"summary":"Release or commit an active reservation","operationId":"updateInventoryReservation","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReservationStateInput"}}}},"responses":{"200":{"description":"Updated.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/CatalogRecord"}}}}}},"400":{"description":"Malformed request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/inventory-availability":{"get":{"tags":["Inventory"],"summary":"Read ledger availability minus live reservations","operationId":"listInventoryAvailability","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CatalogRecord"}}}}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/listings/{listingId}/revisions":{"parameters":[{"name":"listingId","in":"path","required":true,"description":"Listing UUID.","schema":{"type":"string","format":"uuid"}}],"get":{"tags":["Listing projections"],"summary":"List immutable desired revisions","operationId":"listListingRevisions","description":"Observed listing_data remains separate.","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CatalogRecord"}}}}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Listing projections"],"summary":"Create a numbered provider-typed desired revision","operationId":"createListingRevision","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingRevisionInput"}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/CatalogRecord"}}}}}},"400":{"description":"Malformed request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/listing-revisions/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Record UUID.","schema":{"type":"string","format":"uuid"}}],"patch":{"tags":["Listing projections"],"summary":"Edit or approve a draft revision","operationId":"updateListingRevision","description":"Approved revisions cannot be changed or deleted.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingRevisionInput"}}}},"responses":{"200":{"description":"Updated.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/CatalogRecord"}}}}}},"400":{"description":"Malformed request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/orders/{orderId}/lines":{"parameters":[{"name":"orderId","in":"path","required":true,"description":"Order UUID.","schema":{"type":"string","format":"uuid"}}],"get":{"tags":["Order lines"],"summary":"List immutable order-line snapshots","operationId":"listOrderLines","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CatalogRecord"}}}}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Order lines"],"summary":"Create an immutable order-line snapshot","operationId":"createOrderLine","description":"Selected options and buyer personalization are preserved separately from the stable variant reference.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderLineInput"}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/CatalogRecord"}}}}}},"400":{"description":"Malformed request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fulfillments/{fulfillmentId}/lines":{"parameters":[{"name":"fulfillmentId","in":"path","required":true,"description":"Fulfillment UUID.","schema":{"type":"string","format":"uuid"}}],"get":{"tags":["Fulfillment lines"],"summary":"List fulfilled order-line quantities","operationId":"listFulfillmentLines","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CatalogRecord"}}}}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Fulfillment lines"],"summary":"Apply a fulfilled quantity to one order line","operationId":"createFulfillmentLine","description":"Total fulfilled quantity cannot exceed the order-line quantity.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FulfillmentLineInput"}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/CatalogRecord"}}}}}},"400":{"description":"Malformed request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record not found in the key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"Personmade organization API key (pms_…)","description":"Organization owners generate named keys in Settings, where they stay visible to owners for copying later."}},"schemas":{"ProductTypeInput":{"type":"object","additionalProperties":false,"required":["name"],"properties":{"name":{"type":"string","minLength":1,"maxLength":120},"description":{"type":"string"},"product_context":{"type":"string"},"listing_description_template":{"type":"string"},"default_supply_policy":{"type":"string","enum":["stocked","made_to_order","made_to_request"],"default":"made_to_order","description":"Default supply rule for variants in this product family."},"default_fulfillment_kind":{"type":"string","enum":["physical","digital"],"default":"physical","description":"Default delivery shape for variants in this product family."},"default_shipping_profile_id":{"type":["string","null"],"format":"uuid","description":"Default canonical shipping profile for physical variants."},"default_return_policy_id":{"type":["string","null"],"format":"uuid","description":"Default canonical return policy for products in this family."}}},"ProductInput":{"type":"object","additionalProperties":false,"required":["product_type_id","name"],"properties":{"product_type_id":{"type":"string","format":"uuid","description":"A product type must be approved before products can be filed under it."},"name":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string"},"return_policy_id":{"type":["string","null"],"format":"uuid","description":"Canonical return policy under which this product is sold."}}},"ShippingProfileInput":{"type":"object","additionalProperties":false,"required":["name","origin_country"],"properties":{"name":{"type":"string","minLength":1,"maxLength":120},"origin_country":{"type":"string","pattern":"^[A-Za-z]{2}$","description":"ISO 3166-1 alpha-2 origin country; normalized to uppercase."},"origin_postal_code":{"type":"string","maxLength":40,"default":""},"processing_min_days":{"type":"integer","minimum":0,"default":0},"processing_max_days":{"type":"integer","minimum":0,"default":0,"description":"Must be greater than or equal to processing_min_days."}}},"ShippingRateInput":{"type":"object","additionalProperties":false,"required":["first_item_minor","currency"],"properties":{"destination_scope":{"type":"string","enum":["everywhere","country"],"default":"everywhere"},"destination_country":{"type":["string","null"],"pattern":"^[A-Za-z]{2}$","description":"Required for country scope, normalized to uppercase, and null for everywhere scope."},"first_item_minor":{"type":"integer","minimum":0},"additional_item_minor":{"type":"integer","minimum":0,"default":0},"currency":{"type":"string","pattern":"^[A-Z]{3}$","description":"Uppercase ISO 4217 currency code."},"delivery_min_days":{"type":"integer","minimum":0,"default":0},"delivery_max_days":{"type":"integer","minimum":0,"default":0,"description":"Must be greater than or equal to delivery_min_days."}}},"ReturnPolicyInput":{"type":"object","additionalProperties":false,"required":["name"],"properties":{"name":{"type":"string","minLength":1,"maxLength":120},"accepts_returns":{"type":"boolean","default":false},"accepts_exchanges":{"type":"boolean","default":false},"return_deadline_days":{"type":["integer","null"],"enum":[7,14,21,30,45,60,90,null],"description":"Required when returns or exchanges are accepted."}}},"ShippingProfileMappingInput":{"type":"object","additionalProperties":false,"required":["shipping_profile_id","connection_id","remote_id"],"properties":{"shipping_profile_id":{"type":"string","format":"uuid"},"connection_id":{"type":"string","format":"uuid"},"remote_id":{"type":"string","minLength":1,"maxLength":200}}},"ReturnPolicyMappingInput":{"type":"object","additionalProperties":false,"required":["return_policy_id","connection_id","remote_id"],"properties":{"return_policy_id":{"type":"string","format":"uuid"},"connection_id":{"type":"string","format":"uuid"},"remote_id":{"type":"string","minLength":1,"maxLength":200}}},"EtsyProductTypeConfigurationInput":{"type":"object","additionalProperties":false,"required":["taxonomy_id","who_made","when_made","is_supply","should_auto_renew","is_taxable","default_tags","materials","properties","policies"],"properties":{"taxonomy_id":{"type":"integer","minimum":1},"who_made":{"type":"string","enum":["i_did","someone_else","collective"]},"when_made":{"type":"string","enum":["made_to_order","2020_2026"]},"is_supply":{"type":"boolean"},"should_auto_renew":{"type":"boolean"},"is_taxable":{"type":"boolean"},"default_tags":{"type":"array","maxItems":13,"uniqueItems":true,"items":{"type":"string","minLength":1,"maxLength":20},"description":"Tags copied into a new mirror. Tags are the only product-type value a mirror can override."},"materials":{"type":"array","maxItems":13,"uniqueItems":true,"items":{"type":"string","minLength":1,"maxLength":45},"description":"Etsy materials inherited by every mirror of this product type."},"properties":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["option_key","property_id"],"properties":{"option_key":{"type":"string","minLength":1,"maxLength":80},"property_id":{"type":"integer","minimum":1}}},"description":"Exactly one Etsy variation property for each semantic option key used by products of this type."},"policies":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["connection_id","remote_shipping_profile_id","remote_return_policy_id"],"properties":{"connection_id":{"type":"string","format":"uuid"},"remote_shipping_profile_id":{"type":["string","null"],"pattern":"^[1-9][0-9]*$"},"remote_return_policy_id":{"type":["string","null"],"pattern":"^[1-9][0-9]*$"},"remote_readiness_state_id":{"type":["string","null"],"pattern":"^[1-9][0-9]*$","description":"Etsy processing profile required by physical listings."}}},"description":"The complete Etsy shop-policy selection for this product type. Omitted connection rows are removed."}}},"ListingInput":{"type":"object","additionalProperties":false,"required":["product_id","platform"],"properties":{"product_id":{"type":"string","format":"uuid"},"platform":{"type":"string","enum":["etsy","shopify","personmade"]},"connection_id":{"type":["string","null"],"format":"uuid"},"remote_listing_id":{"type":["string","null"]},"listing_data":{"type":"object","additionalProperties":true,"default":{},"description":"Raw source data preserved as a JSON object."},"url":{"type":"string","maxLength":2000,"default":"","description":"Remote URL. Leave empty until the marketplace creates the record.","examples":["https://www.etsy.com/listing/123"]}}},"EtsyMirrorInput":{"type":"object","additionalProperties":false,"required":["connection_id","fulfillment_kind","location_ids"],"properties":{"connection_id":{"type":"string","format":"uuid"},"fulfillment_kind":{"type":"string","enum":["physical","digital","mixed"],"description":"Etsy projection shape. Mixed keeps physical and manually fulfilled digital buyer choices in one physical Etsy listing."},"tags":{"type":"array","maxItems":13,"uniqueItems":true,"items":{"type":"string","minLength":1,"maxLength":20},"description":"Optional per-mirror override. Omit it to copy the product type's default Etsy tags."},"location_ids":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","format":"uuid"}},"auto_sync":{"type":"boolean","default":true,"description":"When true, later canonical product changes overwrite the Etsy listing."}}},"EtsyMirrorUpdate":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"tags":{"type":"array","maxItems":13,"uniqueItems":true,"items":{"type":"string","minLength":1,"maxLength":20}},"auto_sync":{"type":"boolean"},"sync":{"type":"boolean","default":true,"description":"Send the updated mirror to Etsy in this request."}}},"OrderInput":{"type":"object","additionalProperties":false,"required":["platform","amount","placed_at"],"properties":{"listing_id":{"type":["string","null"],"format":"uuid"},"product_id":{"type":["string","null"],"format":"uuid"},"platform":{"type":"string","enum":["etsy","shopify","personmade"]},"status":{"type":"string","enum":["pending","authorized","paid","cancelled","refunded"],"default":"pending"},"currency":{"type":"string","pattern":"^[A-Z]{3}$","default":"USD","description":"ISO 4217 currency code shared by every line."},"order_data":{"type":"object","additionalProperties":true,"default":{},"description":"Raw source data preserved as a JSON object."},"amount":{"type":"integer","minimum":0,"description":"Order total in USD cents."},"placed_at":{"oneOf":[{"type":"integer","format":"int64","description":"Milliseconds since the Unix epoch.","examples":[1787509980000]},{"type":"string","format":"date-time","examples":["2026-08-24T16:30:00Z"]}],"description":"Actual order time in UTC, as Unix epoch milliseconds or an RFC 3339 date-time ending in Z."}}},"FulfillmentInput":{"type":"object","additionalProperties":false,"required":["order_id","fulfilled_at"],"properties":{"order_id":{"type":"string","format":"uuid"},"fulfilled_at":{"oneOf":[{"type":"integer","format":"int64","description":"Milliseconds since the Unix epoch.","examples":[1787509980000]},{"type":"string","format":"date-time","examples":["2026-08-24T16:30:00Z"]}],"description":"Fulfillment time in UTC, as Unix epoch milliseconds or an RFC 3339 date-time ending in Z."},"fulfillment_data":{"type":"object","additionalProperties":true,"default":{},"description":"Raw source data preserved as a JSON object."},"notes":{"type":"string"}}},"MarketplaceConnectionInput":{"type":"object","additionalProperties":false,"required":["provider","name","auth_method"],"properties":{"provider":{"type":"string","pattern":"^[a-z0-9][a-z0-9_-]{0,49}$","description":"Extensible storefront-provider slug, such as etsy or shopify."},"name":{"type":"string","minLength":1,"maxLength":120},"auth_method":{"type":"string","enum":["oauth2","api_key","access_token","custom"]},"external_account_id":{"type":["string","null"],"maxLength":500},"external_account_name":{"type":["string","null"],"maxLength":500},"scopes":{"type":"array","uniqueItems":true,"items":{"type":"string","minLength":1,"maxLength":100}},"configuration":{"type":"object","additionalProperties":true,"description":"Non-secret provider or OAuth-broker configuration."},"credentials":{"type":"object","minProperties":1,"maxProperties":64,"additionalProperties":{"type":"string","minLength":1,"maxLength":10000},"writeOnly":true,"description":"Organization-owned provider credentials. Values are encrypted at rest and are never returned or copied into activity events."}}},"MarketplaceConnectionUpdate":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"name":{"type":"string","minLength":1,"maxLength":120},"auth_method":{"type":"string","enum":["oauth2","api_key","access_token","custom"]},"status":{"type":"string","enum":["configured","active","error"],"description":"Use the disconnect action to erase credentials and enter disconnected state atomically."},"external_account_id":{"type":["string","null"],"maxLength":500},"external_account_name":{"type":["string","null"],"maxLength":500},"scopes":{"type":"array","uniqueItems":true,"items":{"type":"string","minLength":1,"maxLength":100}},"configuration":{"type":"object","additionalProperties":true,"description":"Non-secret provider or OAuth-broker configuration."},"credentials":{"type":"object","minProperties":1,"additionalProperties":{"type":"string","minLength":1,"maxLength":10000},"writeOnly":true}}},"CatalogOptionInput":{"type":"object","additionalProperties":false,"required":["name","values"],"properties":{"name":{"type":"string","minLength":1,"maxLength":120},"values":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","minLength":1,"maxLength":120}}}},"CatalogOptionPatch":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"name":{"type":"string","minLength":1,"maxLength":120},"position":{"type":"integer","minimum":0,"maximum":2}}},"OptionValueInput":{"type":"object","additionalProperties":false,"required":["label"],"properties":{"label":{"type":"string","minLength":1,"maxLength":120},"position":{"type":"integer","minimum":0}}},"VariantInput":{"type":"object","additionalProperties":false,"required":["selections","price_minor","currency","fulfillment_kind"],"description":"One explicit sparse combination. Exactly one value id must be supplied for each product option id. SKU is nullable and need not be unique.","properties":{"active":{"type":"boolean","default":true},"sku":{"type":["string","null"]},"barcode":{"type":["string","null"]},"price_minor":{"type":"integer","minimum":0},"compare_at_price_minor":{"type":["integer","null"],"minimum":0,"description":"When present, must be greater than price_minor."},"currency":{"type":"string","pattern":"^[A-Z]{3}$","description":"Uppercase ISO 4217 currency code."},"fulfillment_kind":{"type":"string","enum":["physical","digital"]},"tax_code":{"type":["string","null"]},"weight_grams":{"type":["integer","null"],"minimum":0},"length_mm":{"type":["integer","null"],"minimum":0},"width_mm":{"type":["integer","null"],"minimum":0},"height_mm":{"type":["integer","null"],"minimum":0},"inventory_item_id":{"type":["string","null"],"format":"uuid","description":"Required only when supply_policy is stocked; forbidden for other supply policies."},"supply_policy":{"type":"string","enum":["stocked","made_to_order","made_to_request"],"default":"made_to_order","description":"stocked uses the inventory ledger, made_to_order uses made_to_order_limit, and made_to_request is not directly purchasable."},"made_to_order_limit":{"type":["integer","null"],"minimum":1,"default":999,"description":"Required only for made_to_order supply; null for stocked and made_to_request."},"shipping_profile_id":{"type":["string","null"],"format":"uuid","description":"Canonical shipping profile for a physical variant. Digital variants must use null."},"selections":{"type":"object","minProperties":0,"additionalProperties":{"type":"string","format":"uuid"},"description":"Map of product_option id to product_option_value id."}}},"CustomizationInput":{"type":"object","additionalProperties":false,"required":["kind","prompt"],"properties":{"kind":{"type":"string","enum":["text","single_select","file"]},"prompt":{"type":"string","minLength":1,"maxLength":1000},"instructions":{"type":"string","maxLength":10000},"required":{"type":"boolean"},"position":{"type":"integer","minimum":0},"min_length":{"type":["integer","null"],"minimum":0},"max_length":{"type":["integer","null"],"minimum":1},"max_files":{"type":["integer","null"],"minimum":1},"max_file_bytes":{"type":["integer","null"],"minimum":1},"choices":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","minLength":1,"maxLength":500}}}},"MediaSelectionInput":{"type":"object","additionalProperties":false,"required":["asset_id","source_etag"],"properties":{"asset_id":{"type":"string","format":"uuid"},"source_etag":{"type":"string","minLength":1,"maxLength":500,"description":"Reviewed source checksum or ETag pinned into publication."}}},"VariantMediaInput":{"type":"object","additionalProperties":false,"required":["asset_ids"],"properties":{"asset_ids":{"type":"array","uniqueItems":true,"items":{"type":"string","format":"uuid"}}}},"InventoryLocationInput":{"type":"object","additionalProperties":false,"required":["name"],"properties":{"name":{"type":"string","minLength":1,"maxLength":120},"active":{"type":"boolean"}}},"InventoryItemInput":{"type":"object","additionalProperties":false,"required":["product_id","name"],"properties":{"product_id":{"type":"string","format":"uuid"},"name":{"type":"string","minLength":1,"maxLength":200},"tracking_policy":{"type":"string","enum":["tracked","untracked"]},"oversell_policy":{"type":"string","enum":["deny","allow"]}}},"InventoryAdjustmentInput":{"type":"object","additionalProperties":false,"required":["inventory_item_id","location_id","quantity_delta","source","idempotency_key"],"description":"Append-only ledger entry. It cannot be patched or deleted.","properties":{"inventory_item_id":{"type":"string","format":"uuid"},"location_id":{"type":"string","format":"uuid"},"quantity_delta":{"type":"integer","not":{"const":0}},"source":{"type":"string","minLength":1},"reason":{"type":"string"},"order_line_id":{"type":["string","null"],"format":"uuid"},"idempotency_key":{"type":"string","minLength":1}}},"InventoryReservationInput":{"type":"object","additionalProperties":false,"required":["inventory_item_id","location_id","quantity","checkout_id","idempotency_key","expires_at"],"properties":{"inventory_item_id":{"type":"string","format":"uuid"},"location_id":{"type":"string","format":"uuid"},"quantity":{"type":"integer","minimum":1},"checkout_id":{"type":"string","minLength":1},"order_line_id":{"type":["string","null"],"format":"uuid"},"idempotency_key":{"type":"string","minLength":1},"expires_at":{"type":"integer","format":"int64","description":"Milliseconds since the Unix epoch.","examples":[1787509980000]}}},"ReservationStateInput":{"type":"object","additionalProperties":false,"required":["state"],"properties":{"state":{"type":"string","enum":["released","committed"]}}},"ListingRevisionInput":{"type":"object","additionalProperties":false,"required":["input_digest","provider","schema_version","manifest"],"description":"Provider-typed desired state. An approved revision is immutable and remains separate from listing_data observations.","properties":{"input_digest":{"type":"string","minLength":1},"provider":{"type":"string","enum":["etsy","shopify","personmade"]},"schema_version":{"type":"integer","minimum":1},"manifest":{"type":"object","additionalProperties":true,"default":{},"description":"Raw source data preserved as a JSON object."},"state":{"type":"string","enum":["draft","approved"],"default":"draft"}}},"OrderLineInput":{"type":"object","additionalProperties":false,"required":["product_name","option_snapshot","personalization_snapshot","quantity","fulfillment_kind","unit_price_minor","total_minor","currency"],"description":"Immutable line snapshot. Personalization answers are returned here but omitted from broad app-event payloads.","properties":{"variant_id":{"type":["string","null"],"format":"uuid"},"listing_variant_id":{"type":["string","null"],"format":"uuid"},"remote_line_id":{"type":["string","null"]},"product_name":{"type":"string","minLength":1},"option_snapshot":{"type":"object","additionalProperties":true,"default":{},"description":"Raw source data preserved as a JSON object."},"personalization_snapshot":{"type":"object","additionalProperties":true,"default":{},"description":"Raw source data preserved as a JSON object."},"sku_snapshot":{"type":["string","null"]},"quantity":{"type":"integer","minimum":1},"fulfillment_kind":{"type":"string","enum":["physical","digital"]},"unit_price_minor":{"type":"integer","minimum":0},"discount_minor":{"type":"integer","minimum":0},"tax_minor":{"type":"integer","minimum":0},"shipping_minor":{"type":"integer","minimum":0},"total_minor":{"type":"integer","minimum":0},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}}},"FulfillmentLineInput":{"type":"object","additionalProperties":false,"required":["order_line_id","quantity"],"properties":{"order_line_id":{"type":"string","format":"uuid"},"quantity":{"type":"integer","minimum":1}}},"ProductTypeInputPatch":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","minLength":1,"maxLength":120},"description":{"type":"string"},"product_context":{"type":"string"},"listing_description_template":{"type":"string"},"default_supply_policy":{"type":"string","enum":["stocked","made_to_order","made_to_request"],"default":"made_to_order","description":"Default supply rule for variants in this product family."},"default_fulfillment_kind":{"type":"string","enum":["physical","digital"],"default":"physical","description":"Default delivery shape for variants in this product family."},"default_shipping_profile_id":{"type":["string","null"],"format":"uuid","description":"Default canonical shipping profile for physical variants."},"default_return_policy_id":{"type":["string","null"],"format":"uuid","description":"Default canonical return policy for products in this family."}},"minProperties":1},"ProductInputPatch":{"type":"object","additionalProperties":false,"properties":{"product_type_id":{"type":"string","format":"uuid","description":"A product type must be approved before products can be filed under it."},"name":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string"},"return_policy_id":{"type":["string","null"],"format":"uuid","description":"Canonical return policy under which this product is sold."}},"minProperties":1},"ShippingProfileInputPatch":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","minLength":1,"maxLength":120},"origin_country":{"type":"string","pattern":"^[A-Za-z]{2}$","description":"ISO 3166-1 alpha-2 origin country; normalized to uppercase."},"origin_postal_code":{"type":"string","maxLength":40,"default":""},"processing_min_days":{"type":"integer","minimum":0,"default":0},"processing_max_days":{"type":"integer","minimum":0,"default":0,"description":"Must be greater than or equal to processing_min_days."}},"minProperties":1},"ShippingRateInputPatch":{"type":"object","additionalProperties":false,"properties":{"destination_scope":{"type":"string","enum":["everywhere","country"],"default":"everywhere"},"destination_country":{"type":["string","null"],"pattern":"^[A-Za-z]{2}$","description":"Required for country scope, normalized to uppercase, and null for everywhere scope."},"first_item_minor":{"type":"integer","minimum":0},"additional_item_minor":{"type":"integer","minimum":0,"default":0},"currency":{"type":"string","pattern":"^[A-Z]{3}$","description":"Uppercase ISO 4217 currency code."},"delivery_min_days":{"type":"integer","minimum":0,"default":0},"delivery_max_days":{"type":"integer","minimum":0,"default":0,"description":"Must be greater than or equal to delivery_min_days."}},"minProperties":1},"ReturnPolicyInputPatch":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","minLength":1,"maxLength":120},"accepts_returns":{"type":"boolean","default":false},"accepts_exchanges":{"type":"boolean","default":false},"return_deadline_days":{"type":["integer","null"],"enum":[7,14,21,30,45,60,90,null],"description":"Required when returns or exchanges are accepted."}},"minProperties":1},"ShippingProfileMappingInputPatch":{"type":"object","additionalProperties":false,"properties":{"shipping_profile_id":{"type":"string","format":"uuid"},"connection_id":{"type":"string","format":"uuid"},"remote_id":{"type":"string","minLength":1,"maxLength":200}},"minProperties":1},"ReturnPolicyMappingInputPatch":{"type":"object","additionalProperties":false,"properties":{"return_policy_id":{"type":"string","format":"uuid"},"connection_id":{"type":"string","format":"uuid"},"remote_id":{"type":"string","minLength":1,"maxLength":200}},"minProperties":1},"EtsyProductTypeConfigurationInputPatch":{"type":"object","additionalProperties":false,"properties":{"taxonomy_id":{"type":"integer","minimum":1},"who_made":{"type":"string","enum":["i_did","someone_else","collective"]},"when_made":{"type":"string","enum":["made_to_order","2020_2026"]},"is_supply":{"type":"boolean"},"should_auto_renew":{"type":"boolean"},"is_taxable":{"type":"boolean"},"default_tags":{"type":"array","maxItems":13,"uniqueItems":true,"items":{"type":"string","minLength":1,"maxLength":20},"description":"Tags copied into a new mirror. Tags are the only product-type value a mirror can override."},"materials":{"type":"array","maxItems":13,"uniqueItems":true,"items":{"type":"string","minLength":1,"maxLength":45},"description":"Etsy materials inherited by every mirror of this product type."},"properties":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["option_key","property_id"],"properties":{"option_key":{"type":"string","minLength":1,"maxLength":80},"property_id":{"type":"integer","minimum":1}}},"description":"Exactly one Etsy variation property for each semantic option key used by products of this type."},"policies":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["connection_id","remote_shipping_profile_id","remote_return_policy_id"],"properties":{"connection_id":{"type":"string","format":"uuid"},"remote_shipping_profile_id":{"type":["string","null"],"pattern":"^[1-9][0-9]*$"},"remote_return_policy_id":{"type":["string","null"],"pattern":"^[1-9][0-9]*$"},"remote_readiness_state_id":{"type":["string","null"],"pattern":"^[1-9][0-9]*$","description":"Etsy processing profile required by physical listings."}}},"description":"The complete Etsy shop-policy selection for this product type. Omitted connection rows are removed."}},"minProperties":1},"ListingInputPatch":{"type":"object","additionalProperties":false,"properties":{"product_id":{"type":"string","format":"uuid"},"platform":{"type":"string","enum":["etsy","shopify","personmade"]},"connection_id":{"type":["string","null"],"format":"uuid"},"remote_listing_id":{"type":["string","null"]},"listing_data":{"type":"object","additionalProperties":true,"default":{},"description":"Raw source data preserved as a JSON object."},"url":{"type":"string","maxLength":2000,"default":"","description":"Remote URL. Leave empty until the marketplace creates the record.","examples":["https://www.etsy.com/listing/123"]}},"minProperties":1},"EtsyMirrorInputPatch":{"type":"object","additionalProperties":false,"properties":{"connection_id":{"type":"string","format":"uuid"},"fulfillment_kind":{"type":"string","enum":["physical","digital","mixed"],"description":"Etsy projection shape. Mixed keeps physical and manually fulfilled digital buyer choices in one physical Etsy listing."},"tags":{"type":"array","maxItems":13,"uniqueItems":true,"items":{"type":"string","minLength":1,"maxLength":20},"description":"Optional per-mirror override. Omit it to copy the product type's default Etsy tags."},"location_ids":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","format":"uuid"}},"auto_sync":{"type":"boolean","default":true,"description":"When true, later canonical product changes overwrite the Etsy listing."}},"minProperties":1},"EtsyMirrorUpdatePatch":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"tags":{"type":"array","maxItems":13,"uniqueItems":true,"items":{"type":"string","minLength":1,"maxLength":20}},"auto_sync":{"type":"boolean"},"sync":{"type":"boolean","default":true,"description":"Send the updated mirror to Etsy in this request."}}},"OrderInputPatch":{"type":"object","additionalProperties":false,"properties":{"listing_id":{"type":["string","null"],"format":"uuid"},"product_id":{"type":["string","null"],"format":"uuid"},"platform":{"type":"string","enum":["etsy","shopify","personmade"]},"status":{"type":"string","enum":["pending","authorized","paid","cancelled","refunded"],"default":"pending"},"currency":{"type":"string","pattern":"^[A-Z]{3}$","default":"USD","description":"ISO 4217 currency code shared by every line."},"order_data":{"type":"object","additionalProperties":true,"default":{},"description":"Raw source data preserved as a JSON object."},"amount":{"type":"integer","minimum":0,"description":"Order total in USD cents."},"placed_at":{"oneOf":[{"type":"integer","format":"int64","description":"Milliseconds since the Unix epoch.","examples":[1787509980000]},{"type":"string","format":"date-time","examples":["2026-08-24T16:30:00Z"]}],"description":"Actual order time in UTC, as Unix epoch milliseconds or an RFC 3339 date-time ending in Z."}},"minProperties":1},"FulfillmentInputPatch":{"type":"object","additionalProperties":false,"properties":{"order_id":{"type":"string","format":"uuid"},"fulfilled_at":{"oneOf":[{"type":"integer","format":"int64","description":"Milliseconds since the Unix epoch.","examples":[1787509980000]},{"type":"string","format":"date-time","examples":["2026-08-24T16:30:00Z"]}],"description":"Fulfillment time in UTC, as Unix epoch milliseconds or an RFC 3339 date-time ending in Z."},"fulfillment_data":{"type":"object","additionalProperties":true,"default":{},"description":"Raw source data preserved as a JSON object."},"notes":{"type":"string"}},"minProperties":1},"MarketplaceConnectionInputPatch":{"type":"object","additionalProperties":false,"properties":{"provider":{"type":"string","pattern":"^[a-z0-9][a-z0-9_-]{0,49}$","description":"Extensible storefront-provider slug, such as etsy or shopify."},"name":{"type":"string","minLength":1,"maxLength":120},"auth_method":{"type":"string","enum":["oauth2","api_key","access_token","custom"]},"external_account_id":{"type":["string","null"],"maxLength":500},"external_account_name":{"type":["string","null"],"maxLength":500},"scopes":{"type":"array","uniqueItems":true,"items":{"type":"string","minLength":1,"maxLength":100}},"configuration":{"type":"object","additionalProperties":true,"description":"Non-secret provider or OAuth-broker configuration."},"credentials":{"type":"object","minProperties":1,"maxProperties":64,"additionalProperties":{"type":"string","minLength":1,"maxLength":10000},"writeOnly":true,"description":"Organization-owned provider credentials. Values are encrypted at rest and are never returned or copied into activity events."}},"minProperties":1},"MarketplaceConnectionUpdatePatch":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"name":{"type":"string","minLength":1,"maxLength":120},"auth_method":{"type":"string","enum":["oauth2","api_key","access_token","custom"]},"status":{"type":"string","enum":["configured","active","error"],"description":"Use the disconnect action to erase credentials and enter disconnected state atomically."},"external_account_id":{"type":["string","null"],"maxLength":500},"external_account_name":{"type":["string","null"],"maxLength":500},"scopes":{"type":"array","uniqueItems":true,"items":{"type":"string","minLength":1,"maxLength":100}},"configuration":{"type":"object","additionalProperties":true,"description":"Non-secret provider or OAuth-broker configuration."},"credentials":{"type":"object","minProperties":1,"additionalProperties":{"type":"string","minLength":1,"maxLength":10000},"writeOnly":true}}},"CatalogOptionInputPatch":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","minLength":1,"maxLength":120},"values":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","minLength":1,"maxLength":120}}},"minProperties":1},"CatalogOptionPatchPatch":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"name":{"type":"string","minLength":1,"maxLength":120},"position":{"type":"integer","minimum":0,"maximum":2}}},"OptionValueInputPatch":{"type":"object","additionalProperties":false,"properties":{"label":{"type":"string","minLength":1,"maxLength":120},"position":{"type":"integer","minimum":0}},"minProperties":1},"VariantInputPatch":{"type":"object","additionalProperties":false,"description":"One explicit sparse combination. Exactly one value id must be supplied for each product option id. SKU is nullable and need not be unique.","properties":{"active":{"type":"boolean","default":true},"sku":{"type":["string","null"]},"barcode":{"type":["string","null"]},"price_minor":{"type":"integer","minimum":0},"compare_at_price_minor":{"type":["integer","null"],"minimum":0,"description":"When present, must be greater than price_minor."},"currency":{"type":"string","pattern":"^[A-Z]{3}$","description":"Uppercase ISO 4217 currency code."},"fulfillment_kind":{"type":"string","enum":["physical","digital"]},"tax_code":{"type":["string","null"]},"weight_grams":{"type":["integer","null"],"minimum":0},"length_mm":{"type":["integer","null"],"minimum":0},"width_mm":{"type":["integer","null"],"minimum":0},"height_mm":{"type":["integer","null"],"minimum":0},"inventory_item_id":{"type":["string","null"],"format":"uuid","description":"Required only when supply_policy is stocked; forbidden for other supply policies."},"supply_policy":{"type":"string","enum":["stocked","made_to_order","made_to_request"],"default":"made_to_order","description":"stocked uses the inventory ledger, made_to_order uses made_to_order_limit, and made_to_request is not directly purchasable."},"made_to_order_limit":{"type":["integer","null"],"minimum":1,"default":999,"description":"Required only for made_to_order supply; null for stocked and made_to_request."},"shipping_profile_id":{"type":["string","null"],"format":"uuid","description":"Canonical shipping profile for a physical variant. Digital variants must use null."},"selections":{"type":"object","minProperties":0,"additionalProperties":{"type":"string","format":"uuid"},"description":"Map of product_option id to product_option_value id."}},"minProperties":1},"CustomizationInputPatch":{"type":"object","additionalProperties":false,"properties":{"kind":{"type":"string","enum":["text","single_select","file"]},"prompt":{"type":"string","minLength":1,"maxLength":1000},"instructions":{"type":"string","maxLength":10000},"required":{"type":"boolean"},"position":{"type":"integer","minimum":0},"min_length":{"type":["integer","null"],"minimum":0},"max_length":{"type":["integer","null"],"minimum":1},"max_files":{"type":["integer","null"],"minimum":1},"max_file_bytes":{"type":["integer","null"],"minimum":1},"choices":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","minLength":1,"maxLength":500}}},"minProperties":1},"MediaSelectionInputPatch":{"type":"object","additionalProperties":false,"properties":{"asset_id":{"type":"string","format":"uuid"},"source_etag":{"type":"string","minLength":1,"maxLength":500,"description":"Reviewed source checksum or ETag pinned into publication."}},"minProperties":1},"VariantMediaInputPatch":{"type":"object","additionalProperties":false,"properties":{"asset_ids":{"type":"array","uniqueItems":true,"items":{"type":"string","format":"uuid"}}},"minProperties":1},"InventoryLocationInputPatch":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","minLength":1,"maxLength":120},"active":{"type":"boolean"}},"minProperties":1},"InventoryItemInputPatch":{"type":"object","additionalProperties":false,"properties":{"product_id":{"type":"string","format":"uuid"},"name":{"type":"string","minLength":1,"maxLength":200},"tracking_policy":{"type":"string","enum":["tracked","untracked"]},"oversell_policy":{"type":"string","enum":["deny","allow"]}},"minProperties":1},"InventoryAdjustmentInputPatch":{"type":"object","additionalProperties":false,"description":"Append-only ledger entry. It cannot be patched or deleted.","properties":{"inventory_item_id":{"type":"string","format":"uuid"},"location_id":{"type":"string","format":"uuid"},"quantity_delta":{"type":"integer","not":{"const":0}},"source":{"type":"string","minLength":1},"reason":{"type":"string"},"order_line_id":{"type":["string","null"],"format":"uuid"},"idempotency_key":{"type":"string","minLength":1}},"minProperties":1},"InventoryReservationInputPatch":{"type":"object","additionalProperties":false,"properties":{"inventory_item_id":{"type":"string","format":"uuid"},"location_id":{"type":"string","format":"uuid"},"quantity":{"type":"integer","minimum":1},"checkout_id":{"type":"string","minLength":1},"order_line_id":{"type":["string","null"],"format":"uuid"},"idempotency_key":{"type":"string","minLength":1},"expires_at":{"type":"integer","format":"int64","description":"Milliseconds since the Unix epoch.","examples":[1787509980000]}},"minProperties":1},"ReservationStateInputPatch":{"type":"object","additionalProperties":false,"properties":{"state":{"type":"string","enum":["released","committed"]}},"minProperties":1},"ListingRevisionInputPatch":{"type":"object","additionalProperties":false,"description":"Provider-typed desired state. An approved revision is immutable and remains separate from listing_data observations.","properties":{"input_digest":{"type":"string","minLength":1},"provider":{"type":"string","enum":["etsy","shopify","personmade"]},"schema_version":{"type":"integer","minimum":1},"manifest":{"type":"object","additionalProperties":true,"default":{},"description":"Raw source data preserved as a JSON object."},"state":{"type":"string","enum":["draft","approved"],"default":"draft"}},"minProperties":1},"OrderLineInputPatch":{"type":"object","additionalProperties":false,"description":"Immutable line snapshot. Personalization answers are returned here but omitted from broad app-event payloads.","properties":{"variant_id":{"type":["string","null"],"format":"uuid"},"listing_variant_id":{"type":["string","null"],"format":"uuid"},"remote_line_id":{"type":["string","null"]},"product_name":{"type":"string","minLength":1},"option_snapshot":{"type":"object","additionalProperties":true,"default":{},"description":"Raw source data preserved as a JSON object."},"personalization_snapshot":{"type":"object","additionalProperties":true,"default":{},"description":"Raw source data preserved as a JSON object."},"sku_snapshot":{"type":["string","null"]},"quantity":{"type":"integer","minimum":1},"fulfillment_kind":{"type":"string","enum":["physical","digital"]},"unit_price_minor":{"type":"integer","minimum":0},"discount_minor":{"type":"integer","minimum":0},"tax_minor":{"type":"integer","minimum":0},"shipping_minor":{"type":"integer","minimum":0},"total_minor":{"type":"integer","minimum":0},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"minProperties":1},"FulfillmentLineInputPatch":{"type":"object","additionalProperties":false,"properties":{"order_line_id":{"type":"string","format":"uuid"},"quantity":{"type":"integer","minimum":1}},"minProperties":1},"AssetRename":{"type":"object","additionalProperties":false,"required":["filename"],"properties":{"filename":{"type":"string","minLength":1,"maxLength":180,"description":"Characters outside [a-zA-Z0-9._ -] are replaced with underscores."}}},"ProductType":{"type":"object","additionalProperties":false,"required":["name","id","default_supply_policy","default_fulfillment_kind","default_shipping_profile_id","default_return_policy_id","approved_at","created_at","updated_at"],"properties":{"name":{"type":"string","minLength":1,"maxLength":120},"description":{"type":"string"},"product_context":{"type":"string"},"listing_description_template":{"type":"string"},"default_supply_policy":{"type":"string","enum":["stocked","made_to_order","made_to_request"]},"default_fulfillment_kind":{"type":"string","enum":["physical","digital"]},"default_shipping_profile_id":{"type":["string","null"],"format":"uuid"},"default_return_policy_id":{"type":["string","null"],"format":"uuid"},"id":{"type":"string","format":"uuid"},"approved_at":{"type":["integer","null"],"format":"int64","description":"Milliseconds since the Unix epoch, or null."},"created_at":{"type":"integer","format":"int64","description":"Milliseconds since the Unix epoch.","examples":[1787509980000]},"updated_at":{"type":"integer","format":"int64","description":"Milliseconds since the Unix epoch.","examples":[1787509980000]}}},"EtsyProductTypeConfiguration":{"type":"object","additionalProperties":false,"required":["taxonomy_id","who_made","when_made","is_supply","should_auto_renew","is_taxable","default_tags","materials","properties","policies","product_type_id","created_at","updated_at"],"properties":{"taxonomy_id":{"type":"integer","minimum":1},"who_made":{"type":"string","enum":["i_did","someone_else","collective"]},"when_made":{"type":"string","enum":["made_to_order","2020_2026"]},"is_supply":{"type":"boolean"},"should_auto_renew":{"type":"boolean"},"is_taxable":{"type":"boolean"},"default_tags":{"type":"array","maxItems":13,"uniqueItems":true,"items":{"type":"string","minLength":1,"maxLength":20},"description":"Tags copied into a new mirror. Tags are the only product-type value a mirror can override."},"materials":{"type":"array","maxItems":13,"uniqueItems":true,"items":{"type":"string","minLength":1,"maxLength":45},"description":"Etsy materials inherited by every mirror of this product type."},"properties":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["option_key","property_id"],"properties":{"option_key":{"type":"string","minLength":1,"maxLength":80},"property_id":{"type":"integer","minimum":1}}},"description":"Exactly one Etsy variation property for each semantic option key used by products of this type."},"policies":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["connection_id","remote_shipping_profile_id","remote_return_policy_id"],"properties":{"connection_id":{"type":"string","format":"uuid"},"remote_shipping_profile_id":{"type":["string","null"],"pattern":"^[1-9][0-9]*$"},"remote_return_policy_id":{"type":["string","null"],"pattern":"^[1-9][0-9]*$"},"remote_readiness_state_id":{"type":["string","null"],"pattern":"^[1-9][0-9]*$","description":"Etsy processing profile required by physical listings."}}},"description":"The complete Etsy shop-policy selection for this product type. Omitted connection rows are removed."},"product_type_id":{"type":"string","format":"uuid"},"created_at":{"type":"integer","format":"int64","description":"Milliseconds since the Unix epoch.","examples":[1787509980000]},"updated_at":{"type":"integer","format":"int64","description":"Milliseconds since the Unix epoch.","examples":[1787509980000]}}},"EtsyConfigurationChoices":{"type":"object","additionalProperties":false,"required":["categories","variation_properties"],"properties":{"categories":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["id","path"],"properties":{"id":{"type":"integer","minimum":1},"path":{"type":"string"}}}},"variation_properties":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["id","name"],"properties":{"id":{"type":"integer","minimum":1},"name":{"type":"string"}}}}}},"Product":{"type":"object","additionalProperties":false,"required":["product_type_id","name","id","description","return_policy_id","approved_at","created_at","updated_at"],"properties":{"product_type_id":{"type":"string","format":"uuid","description":"A product type must be approved before products can be filed under it."},"name":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string"},"return_policy_id":{"type":["string","null"],"format":"uuid"},"id":{"type":"string","format":"uuid"},"approved_at":{"type":["integer","null"],"format":"int64","description":"Milliseconds since the Unix epoch, or null."},"created_at":{"type":"integer","format":"int64","description":"Milliseconds since the Unix epoch.","examples":[1787509980000]},"updated_at":{"type":"integer","format":"int64","description":"Milliseconds since the Unix epoch.","examples":[1787509980000]}}},"ShippingProfile":{"type":"object","additionalProperties":false,"required":["id","name","origin_country","origin_postal_code","processing_min_days","processing_max_days","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"origin_country":{"type":"string","pattern":"^[A-Z]{2}$"},"origin_postal_code":{"type":"string"},"processing_min_days":{"type":"integer","minimum":0},"processing_max_days":{"type":"integer","minimum":0},"created_at":{"type":"integer","format":"int64","description":"Milliseconds since the Unix epoch.","examples":[1787509980000]},"updated_at":{"type":"integer","format":"int64","description":"Milliseconds since the Unix epoch.","examples":[1787509980000]}}},"ShippingRate":{"type":"object","additionalProperties":false,"required":["id","shipping_profile_id","destination_scope","destination_country","first_item_minor","additional_item_minor","currency","delivery_min_days","delivery_max_days","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid"},"shipping_profile_id":{"type":"string","format":"uuid"},"destination_scope":{"type":"string","enum":["everywhere","country"]},"destination_country":{"type":["string","null"],"pattern":"^[A-Z]{2}$"},"first_item_minor":{"type":"integer","minimum":0},"additional_item_minor":{"type":"integer","minimum":0},"currency":{"type":"string","pattern":"^[A-Z]{3}$","description":"Uppercase ISO 4217 currency code."},"delivery_min_days":{"type":"integer","minimum":0},"delivery_max_days":{"type":"integer","minimum":0},"created_at":{"type":"integer","format":"int64","description":"Milliseconds since the Unix epoch.","examples":[1787509980000]},"updated_at":{"type":"integer","format":"int64","description":"Milliseconds since the Unix epoch.","examples":[1787509980000]}}},"ReturnPolicy":{"type":"object","additionalProperties":false,"required":["id","name","accepts_returns","accepts_exchanges","return_deadline_days","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"accepts_returns":{"type":"integer","enum":[0,1],"description":"D1 boolean: 1 when returns are accepted."},"accepts_exchanges":{"type":"integer","enum":[0,1],"description":"D1 boolean: 1 when exchanges are accepted."},"return_deadline_days":{"type":["integer","null"],"enum":[7,14,21,30,45,60,90,null]},"created_at":{"type":"integer","format":"int64","description":"Milliseconds since the Unix epoch.","examples":[1787509980000]},"updated_at":{"type":"integer","format":"int64","description":"Milliseconds since the Unix epoch.","examples":[1787509980000]}}},"ShippingProfileMapping":{"type":"object","additionalProperties":false,"required":["id","shipping_profile_id","connection_id","remote_id","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid"},"shipping_profile_id":{"type":"string","format":"uuid"},"connection_id":{"type":"string","format":"uuid"},"remote_id":{"type":"string"},"created_at":{"type":"integer","format":"int64","description":"Milliseconds since the Unix epoch.","examples":[1787509980000]},"updated_at":{"type":"integer","format":"int64","description":"Milliseconds since the Unix epoch.","examples":[1787509980000]}}},"ReturnPolicyMapping":{"type":"object","additionalProperties":false,"required":["id","return_policy_id","connection_id","remote_id","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid"},"return_policy_id":{"type":"string","format":"uuid"},"connection_id":{"type":"string","format":"uuid"},"remote_id":{"type":"string"},"created_at":{"type":"integer","format":"int64","description":"Milliseconds since the Unix epoch.","examples":[1787509980000]},"updated_at":{"type":"integer","format":"int64","description":"Milliseconds since the Unix epoch.","examples":[1787509980000]}}},"ProductVariant":{"type":"object","additionalProperties":false,"required":["id","product_id","active","sku","barcode","price_minor","compare_at_price_minor","currency","fulfillment_kind","tax_code","weight_grams","length_mm","width_mm","height_mm","inventory_item_id","supply_policy","made_to_order_limit","shipping_profile_id","selections","asset_ids","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid"},"product_id":{"type":"string","format":"uuid"},"active":{"type":"integer","enum":[0,1]},"sku":{"type":["string","null"]},"barcode":{"type":["string","null"]},"price_minor":{"type":"integer","minimum":0},"compare_at_price_minor":{"type":["integer","null"],"minimum":0},"currency":{"type":"string","pattern":"^[A-Z]{3}$","description":"Uppercase ISO 4217 currency code."},"fulfillment_kind":{"type":"string","enum":["physical","digital"]},"tax_code":{"type":["string","null"]},"weight_grams":{"type":["integer","null"],"minimum":0},"length_mm":{"type":["integer","null"],"minimum":0},"width_mm":{"type":["integer","null"],"minimum":0},"height_mm":{"type":["integer","null"],"minimum":0},"inventory_item_id":{"type":["string","null"],"format":"uuid"},"supply_policy":{"type":"string","enum":["stocked","made_to_order","made_to_request"]},"made_to_order_limit":{"type":["integer","null"],"minimum":1},"shipping_profile_id":{"type":["string","null"],"format":"uuid"},"selections":{"type":"object","additionalProperties":{"type":"string","format":"uuid"}},"asset_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"created_at":{"type":"integer","format":"int64","description":"Milliseconds since the Unix epoch.","examples":[1787509980000]},"updated_at":{"type":"integer","format":"int64","description":"Milliseconds since the Unix epoch.","examples":[1787509980000]}}},"ProductCatalog":{"type":"object","additionalProperties":false,"required":["id","product_type_id","name","description","return_policy_id","approved_at","created_at","updated_at","keywords","materials","options","variants","customizations","media","inventory_items"],"properties":{"id":{"type":"string","format":"uuid"},"product_type_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string"},"return_policy_id":{"type":["string","null"],"format":"uuid"},"approved_at":{"type":["integer","null"],"format":"int64","description":"Milliseconds since the Unix epoch, or null."},"created_at":{"type":"integer","format":"int64","description":"Milliseconds since the Unix epoch.","examples":[1787509980000]},"updated_at":{"type":"integer","format":"int64","description":"Milliseconds since the Unix epoch.","examples":[1787509980000]},"options":{"type":"array","items":{"$ref":"#/components/schemas/CatalogRecord"},"description":"Ordered option axes with their ordered values."},"keywords":{"type":"array","items":{"type":"string"},"description":"Canonical product search language, before any destination limits are applied."},"materials":{"type":"array","items":{"type":"string"},"description":"Canonical product materials, before any destination limits are applied."},"variants":{"type":"array","items":{"$ref":"#/components/schemas/ProductVariant"}},"customizations":{"type":"array","items":{"$ref":"#/components/schemas/CatalogRecord"}},"media":{"type":"array","items":{"$ref":"#/components/schemas/CatalogRecord"}},"inventory_items":{"type":"array","items":{"$ref":"#/components/schemas/CatalogRecord"}}}},"Listing":{"type":"object","additionalProperties":false,"required":["product_id","platform","id","mirror_key","created_at","updated_at"],"properties":{"product_id":{"type":"string","format":"uuid"},"platform":{"type":"string","enum":["etsy","shopify","personmade"]},"connection_id":{"type":["string","null"],"format":"uuid"},"remote_listing_id":{"type":["string","null"]},"listing_data":{"type":"object","additionalProperties":true,"default":{},"description":"Raw source data preserved as a JSON object."},"url":{"type":"string","maxLength":2000,"default":"","description":"Remote URL. Leave empty until the marketplace creates the record.","examples":["https://www.etsy.com/listing/123"]},"id":{"type":"string","format":"uuid"},"mirror_key":{"type":"string","enum":["","physical","digital"],"description":"Internal channel key used when one product needs separate physical and digital mirrors."},"created_at":{"type":"integer","format":"int64","description":"Milliseconds since the Unix epoch.","examples":[1787509980000]},"updated_at":{"type":"integer","format":"int64","description":"Milliseconds since the Unix epoch.","examples":[1787509980000]}}},"EtsyMirror":{"type":"object","additionalProperties":false,"required":["listing_id","product_id","connection_id","fulfillment_kind","tags","materials","remote_shipping_profile_id","remote_return_policy_id","remote_readiness_state_id","auto_sync","last_sync_at","last_sync_error","created_at","updated_at"],"properties":{"listing_id":{"type":"string","format":"uuid"},"product_id":{"type":"string","format":"uuid"},"connection_id":{"type":"string","format":"uuid"},"fulfillment_kind":{"type":"string","enum":["physical","digital","mixed"],"description":"Etsy projection shape. Mixed keeps physical and manually fulfilled digital buyer choices in one physical Etsy listing."},"tags":{"type":"array","items":{"type":"string"},"description":"The mirror's tag override. When an existing Etsy listing is adopted, its observed tags are preserved if this value is omitted."},"materials":{"type":"array","items":{"type":"string"},"description":"Effective materials read from the product type."},"remote_shipping_profile_id":{"type":["string","null"],"description":"Effective Etsy shipping profile id read from this product type and connection."},"remote_return_policy_id":{"type":["string","null"],"description":"Effective Etsy return policy id read from this product type and connection."},"remote_readiness_state_id":{"type":["string","null"],"description":"Effective Etsy processing profile id read from this product type and connection."},"auto_sync":{"type":"boolean"},"last_sync_at":{"type":["integer","null"],"format":"int64","description":"Milliseconds since the Unix epoch, or null."},"last_sync_error":{"type":["string","null"]},"remote_listing_id":{"type":"string","description":"Present on create after Etsy assigns the draft identity."},"adopted_existing":{"type":"boolean","description":"Present on create. True when Personmade reused the Etsy listing already linked to this product."},"created_at":{"type":"integer","format":"int64","description":"Milliseconds since the Unix epoch.","examples":[1787509980000]},"updated_at":{"type":"integer","format":"int64","description":"Milliseconds since the Unix epoch.","examples":[1787509980000]}}},"EtsyPolicies":{"type":"object","additionalProperties":false,"required":["shop_id","shipping_profiles","return_policies","readiness_state_definitions"],"properties":{"shop_id":{"type":"string"},"shipping_profiles":{"type":"array","items":{"type":"object","additionalProperties":true}},"return_policies":{"type":"array","items":{"type":"object","additionalProperties":true}},"readiness_state_definitions":{"type":"array","items":{"type":"object","additionalProperties":true}}}},"Order":{"type":"object","required":["id","platform","order_data","amount","placed_at","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid"},"listing_id":{"type":["string","null"],"format":"uuid"},"product_id":{"type":["string","null"],"format":"uuid"},"platform":{"type":"string","enum":["etsy","shopify","personmade"]},"order_data":{"type":"object","additionalProperties":true,"default":{},"description":"Raw source data preserved as a JSON object."},"amount":{"type":"integer","minimum":0,"description":"Order total in USD cents."},"placed_at":{"type":"integer","format":"int64","description":"Milliseconds since the Unix epoch.","examples":[1787509980000]},"created_at":{"type":"integer","format":"int64","description":"Milliseconds since the Unix epoch.","examples":[1787509980000]},"updated_at":{"type":"integer","format":"int64","description":"Milliseconds since the Unix epoch.","examples":[1787509980000]}}},"Fulfillment":{"type":"object","required":["id","order_id","fulfilled_at","fulfillment_data","notes","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid"},"order_id":{"type":"string","format":"uuid"},"fulfilled_at":{"type":"integer","format":"int64","description":"Milliseconds since the Unix epoch.","examples":[1787509980000]},"fulfillment_data":{"type":"object","additionalProperties":true,"default":{},"description":"Raw source data preserved as a JSON object."},"notes":{"type":"string"},"created_at":{"type":"integer","format":"int64","description":"Milliseconds since the Unix epoch.","examples":[1787509980000]},"updated_at":{"type":"integer","format":"int64","description":"Milliseconds since the Unix epoch.","examples":[1787509980000]}}},"Asset":{"type":"object","required":["id","product_id","kind","filename","content_type","size_bytes","notes","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"product_id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["product_photo","source","sketch","other"]},"filename":{"type":"string"},"content_type":{"type":"string"},"size_bytes":{"type":"integer","minimum":1,"maximum":104857600},"notes":{"type":"string"},"created_at":{"type":"integer","format":"int64","description":"Milliseconds since the Unix epoch.","examples":[1787509980000]},"watermarked_url":{"type":["string","null"],"format":"uri","description":"Where to GET this asset's on-demand watermarked copy, or null for a format that cannot be watermarked."}}},"MarketplaceConnection":{"type":"object","required":["id","provider","name","auth_method","status","scopes","configuration","credentials_configured","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid"},"provider":{"type":"string"},"name":{"type":"string"},"auth_method":{"type":"string","enum":["oauth2","api_key","access_token","custom"]},"status":{"type":"string","enum":["disconnected","configured","active","error"]},"external_account_id":{"type":["string","null"]},"external_account_name":{"type":["string","null"]},"scopes":{"type":"array","items":{"type":"string"}},"configuration":{"type":"object","additionalProperties":true},"credentials_configured":{"type":"boolean","description":"True when encrypted credential material is present. Credential values are never readable through the API."},"connected_at":{"type":["integer","null"],"format":"int64","description":"Milliseconds since the Unix epoch, or null."},"last_verified_at":{"type":["integer","null"],"format":"int64","description":"Milliseconds since the Unix epoch, or null."},"last_error":{"type":["string","null"]},"created_at":{"type":"integer","format":"int64","description":"Milliseconds since the Unix epoch.","examples":[1787509980000]},"updated_at":{"type":"integer","format":"int64","description":"Milliseconds since the Unix epoch.","examples":[1787509980000]}}},"AppEvent":{"type":"object","required":["id","event_type","subject_type","subject_id","event_data","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"actor_user_id":{"type":["string","null"],"format":"uuid"},"event_type":{"type":"string","examples":["product.created"]},"subject_type":{"type":"string","examples":["product"]},"subject_id":{"type":"string"},"event_data":{"type":"object","additionalProperties":true,"default":{},"description":"Contents of the event. `*.created` carries `values` — the record as written. `*.updated` carries `fields` and `changes`, a `{ from, to }` pair per field that actually moved. `*.deleted` carries `deleted` — a snapshot of the row taken before it was removed. `*.approved` carries the approval, the previous one if any, and the record it applied to. `product.unapproved` carries the approval that was withdrawn. Events made with an API key also carry `api_key_id`."},"created_at":{"type":"integer","format":"int64","description":"Milliseconds since the Unix epoch.","examples":[1787509980000]}}},"CatalogRecord":{"type":"object","additionalProperties":true,"description":"Organization-scoped canonical catalog resource."},"Error":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string"}}}}}}