{ "openapi": "3.1.0", "info": { "title": "Sign Customiser API Documentation", "description": "", "version": "1.0.0" }, "servers": [ { "url": "https://web.signcustomiser.com" } ], "tags": [ { "name": "Analytics", "description": "" }, { "name": "Custom integrations", "description": "" }, { "name": "Customisers", "description": "" }, { "name": "Legacy", "description": "" }, { "name": "Orders", "description": "" }, { "name": "Pricing", "description": "" }, { "name": "Products", "description": "" }, { "name": "Store", "description": "" }, { "name": "Stores", "description": "" }, { "name": "Webhooks", "description": "" } ], "components": { "securitySchemes": { "default": { "type": "http", "scheme": "bearer", "description": "You can retrieve your token by visiting your dashboard and clicking Generate API token." } } }, "security": [ { "default": [] } ], "paths": { "/api/v3/analytics/summary": { "parameters": [], "get": { "summary": "Get an analytics summary\n\nReturn bounded operational totals for the authenticated Store. Orders,\nmodern products, and native-currency revenue are counted over complete UTC\ncalendar days. Revenue remains in integer minor units and is never\nconverted or combined across currencies. Malformed stored currency codes\nappear honestly in one null-currency bucket. Customer details, provider\ndata, and legacy ProductCache rows are excluded. Requires\n`analytics:read`; this operation is read-only and safe to retry.\n\n`end_date` is the inclusive final day and must be before the current UTC\ndate. It defaults to yesterday. `period` defaults to `30d`. The response\nreports the half-open query bounds `[starts_at, ends_before)`. Correct a\n422 using the reported parameter, replace a key after 401, add the scope\nafter 403, and retry 429 responses after `retry_after` seconds.", "operationId": "getAnAnalyticsSummaryReturnBoundedOperationalTotalsForTheAuthenticatedStoreOrdersModernProductsAndNativeCurrencyRevenueAreCountedOverCompleteUTCCalendarDaysRevenueRemainsInIntegerMinorUnitsAndIsNeverConvertedOrCombinedAcrossCurrenciesMalformedStoredCurrencyCodesAppearHonestlyInOneNullCurrencyBucketCustomerDetailsProviderDataAndLegacyProductCacheRowsAreExcludedRequiresanalyticsreadThisOperationIsReadOnlyAndSafeToRetryendDateIsTheInclusiveFinalDayAndMustBeBeforeTheCurrentUTCDateItDefaultsToYesterdayperiodDefaultsTo30dTheResponseReportsTheHalfOpenQueryBoundsstartsAtEndsBeforeCorrectA422UsingTheReportedParameterReplaceAKeyAfter401AddTheScopeAfter403AndRetry429ResponsesAfterretryAfterSeconds", "description": "", "parameters": [ { "in": "query", "name": "period", "description": "Closed set of supported complete-day reporting periods.", "example": "30d", "required": false, "schema": { "type": "string", "description": "Closed set of supported complete-day reporting periods.", "example": "30d", "enum": [ "7d", "30d", "90d", "365d" ] } }, { "in": "query", "name": "end_date", "description": "Inclusive final UTC date in YYYY-MM-DD format. Defaults to the previous UTC day.", "example": "2026-07-19", "required": false, "schema": { "type": "string", "description": "Inclusive final UTC date in YYYY-MM-DD format. Defaults to the previous UTC day.", "example": "2026-07-19" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "data": { "object": "analytics_summary", "period": "30d", "starts_at": "2026-06-20T00:00:00Z", "ends_before": "2026-07-20T00:00:00Z", "order_count": 18, "product_count": 21, "revenue": [ { "currency": "AUD", "amount": 248900, "order_count": 16 }, { "currency": "NZD", "amount": 31100, "order_count": 2 } ] }, "links": { "self": "https://web.signcustomiser.com/api/v3/analytics/summary?period=30d&end_date=2026-07-19", "documentation": "https://www.signcustomiser.com/help/api/" }, "meta": { "api_version": "v3", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } }, "properties": { "data": { "type": "object", "properties": { "object": { "type": "string", "example": "analytics_summary" }, "period": { "type": "string", "example": "30d", "description": "The closed reporting-period input used for this summary.", "enum": [ "7d", "30d", "90d", "365d" ] }, "starts_at": { "type": "string", "example": "2026-06-20T00:00:00Z" }, "ends_before": { "type": "string", "example": "2026-07-20T00:00:00Z" }, "order_count": { "type": "integer", "example": 18 }, "product_count": { "type": "integer", "example": 21 }, "revenue": { "type": "array", "example": [ { "currency": "AUD", "amount": 248900, "order_count": 16 }, { "currency": "NZD", "amount": 31100, "order_count": 2 } ], "items": { "type": "object", "properties": { "currency": { "type": [ "string", "null" ], "example": "AUD", "description": "ISO 4217 currency, or null for malformed historical currency data." }, "amount": { "type": "integer", "example": 248900 }, "order_count": { "type": "integer", "example": 16 } }, "required": [ "currency", "amount", "order_count" ] } } }, "required": [ "object", "period", "starts_at", "ends_before", "order_count", "product_count", "revenue" ] }, "links": { "type": "object", "properties": { "self": { "type": "string", "example": "https://web.signcustomiser.com/api/v3/analytics/summary?period=30d&end_date=2026-07-19" }, "documentation": { "type": "string", "example": "https://www.signcustomiser.com/help/api/" } } }, "meta": { "type": "object", "properties": { "api_version": { "type": "string", "example": "v3" }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/missing_api_key", "title": "Missing API key", "status": 401, "code": "missing_api_key", "detail": "Provide a store API key as a bearer token.", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/missing_api_key" }, "title": { "type": "string", "example": "Missing API key" }, "status": { "type": "integer", "example": 401 }, "code": { "type": "string", "example": "missing_api_key" }, "detail": { "type": "string", "example": "Provide a store API key as a bearer token." }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/insufficient_scope", "title": "Insufficient scope", "status": 403, "code": "insufficient_scope", "detail": "This operation requires the analytics:read scope.", "required_scopes": [ "analytics:read" ], "granted_scopes": [], "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/insufficient_scope" }, "title": { "type": "string", "example": "Insufficient scope" }, "status": { "type": "integer", "example": 403 }, "code": { "type": "string", "example": "insufficient_scope" }, "detail": { "type": "string", "example": "This operation requires the analytics:read scope." }, "required_scopes": { "type": "array", "example": [ "analytics:read" ], "items": { "type": "string" } }, "granted_scopes": { "type": "array", "example": [] }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } }, "422": { "description": "Invalid reporting period", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/invalid_parameter", "title": "Invalid query parameter", "status": 422, "code": "invalid_parameter", "detail": "The period parameter must be one of: 7d, 30d, 90d, 365d.", "errors": [ { "parameter": "period", "code": "unsupported_value", "detail": "The period parameter is unsupported.", "allowed_values": [ "7d", "30d", "90d", "365d" ] } ], "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/invalid_parameter" }, "title": { "type": "string", "example": "Invalid query parameter" }, "status": { "type": "integer", "example": 422 }, "code": { "type": "string", "example": "invalid_parameter" }, "detail": { "type": "string", "example": "The period parameter must be one of: 7d, 30d, 90d, 365d." }, "errors": { "type": "array", "example": [ { "parameter": "period", "code": "unsupported_value", "detail": "The period parameter is unsupported.", "allowed_values": [ "7d", "30d", "90d", "365d" ] } ], "items": { "type": "object", "properties": { "parameter": { "type": "string", "example": "period" }, "code": { "type": "string", "example": "unsupported_value" }, "detail": { "type": "string", "example": "The period parameter is unsupported." }, "allowed_values": { "type": "array", "example": [ "7d", "30d", "90d", "365d" ], "items": { "type": "string" } } } } }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/rate_limited", "title": "Too many requests", "status": 429, "code": "rate_limited", "detail": "You have exceeded the request limit for this API key.", "retry_after": 60, "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/rate_limited" }, "title": { "type": "string", "example": "Too many requests" }, "status": { "type": "integer", "example": 429 }, "code": { "type": "string", "example": "rate_limited" }, "detail": { "type": "string", "example": "You have exceeded the request limit for this API key." }, "retry_after": { "type": "integer", "example": 60 }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } } }, "tags": [ "Analytics" ] } }, "/api/v2/orders": { "parameters": [], "post": { "summary": "Create an order\n\nStep 2 of the custom integration flow. After your server handles the `product:created`\ncallback and returns an `external_id`, send the completed order from your\necommerce platform. Each `products[].external_id` value must match a product ID\nyou previously returned during product creation.", "operationId": "createAnOrderStep2OfTheCustomIntegrationFlowAfterYourServerHandlesTheproductcreatedCallbackAndReturnsAnexternalIdSendTheCompletedOrderFromYourEcommercePlatformEachproductsexternalIdValueMustMatchAProductIDYouPreviouslyReturnedDuringProductCreation", "description": "", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "order": { "order_id": 1, "external_id": "order-123456", "external_order_number": "SC-1001", "currency": "USD", "shipping_line": "Standard Shipping", "products": [ { "external_id": "product-987654321", "quantity": 2, "price": 2999 } ] } }, "properties": { "order": { "type": "object", "properties": { "order_id": { "type": "integer", "example": 1 }, "external_id": { "type": "string", "example": "order-123456" }, "external_order_number": { "type": "string", "example": "SC-1001" }, "currency": { "type": "string", "example": "USD" }, "shipping_line": { "type": "string", "example": "Standard Shipping" }, "products": { "type": "array", "example": [ { "external_id": "product-987654321", "quantity": 2, "price": 2999 } ], "items": { "type": "object", "properties": { "external_id": { "type": "string", "example": "product-987654321" }, "quantity": { "type": "integer", "example": 2 }, "price": { "type": "integer", "example": 2999 } } } } } } } } } } } }, "tags": [ "Custom integrations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "integration_id": { "type": "integer", "description": "The Sign Customiser integration ID that owns the order.", "example": 42 }, "external_id": { "type": "string", "description": "Your platform's internal order ID.", "example": "order-123456" }, "external_order_number": { "type": "string", "description": "The human-readable order number shown to customers.", "example": "SC-1001" }, "currency": { "type": [ "string", "null" ], "description": "The order currency.", "example": "USD" }, "billing_address": { "type": "object", "description": "The billing address for the order.", "example": [], "properties": { "first_name": { "type": "string", "description": "The billing first name.", "example": "John" }, "last_name": { "type": "string", "description": "The billing last name.", "example": "Smith" }, "email": { "type": "string", "description": "The billing email address.", "example": "customer@example.com" }, "phone": { "type": [ "string", "null" ], "description": "The billing phone number.", "example": "+1 555-123-4567" }, "address_1": { "type": "string", "description": "The first billing address line.", "example": "123 Main St" }, "address_2": { "type": [ "string", "null" ], "description": "The second billing address line.", "example": "Suite 4" }, "city": { "type": "string", "description": "The billing city.", "example": "Los Angeles" }, "province": { "type": "string", "description": "The billing province or state.", "example": "CA" }, "postcode": { "type": "string", "description": "The billing postcode or ZIP code.", "example": "90001" }, "country": { "type": "string", "description": "The billing country code.", "example": "US" } } }, "shipping_address": { "type": "object", "description": "The shipping address for the order.", "example": [], "properties": { "first_name": { "type": "string", "description": "The shipping first name.", "example": "John" }, "last_name": { "type": "string", "description": "The shipping last name.", "example": "Smith" }, "address_1": { "type": "string", "description": "The first shipping address line.", "example": "123 Main St" }, "address_2": { "type": [ "string", "null" ], "description": "The second shipping address line.", "example": "Suite 4" }, "city": { "type": "string", "description": "The shipping city.", "example": "Los Angeles" }, "province": { "type": "string", "description": "The shipping province or state.", "example": "CA" }, "postcode": { "type": "string", "description": "The shipping postcode or ZIP code.", "example": "90001" }, "country": { "type": "string", "description": "The shipping country code.", "example": "US" } } }, "shipping_line": { "type": "string", "description": "The selected shipping method.", "example": "Standard Shipping" }, "customer": { "type": "object", "description": "Customer details for the order.", "example": [], "properties": { "first_name": { "type": [ "string", "null" ], "description": "The customer's first name.", "example": "John" }, "last_name": { "type": [ "string", "null" ], "description": "The customer's last name.", "example": "Smith" }, "email": { "type": [ "string", "null" ], "description": "The customer's email address.", "example": "customer@example.com" }, "phone": { "type": [ "string", "null" ], "description": "The customer's phone number.", "example": "+1 555-123-4567" } } }, "products": { "type": "array", "description": "The line items in the order.", "example": [ { "external_id": "product-987654321", "quantity": 2, "price": 2999 } ], "items": { "type": "string" } } }, "required": [ "integration_id", "external_id", "external_order_number", "products" ] } } } } } }, "/api/v2/customisers": { "parameters": [], "get": { "summary": "List customisers\n\nGet all customisers for the current organisation.", "operationId": "listCustomisersGetAllCustomisersForTheCurrentOrganisation", "description": "", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "customisers": [ { "customiser_id": 1, "name": "Storefront neon sign", "price_type": "FIXED_WIDTH", "product": "NEON", "selection_type": "SINGLE", "active": true, "created_at": "2024-01-01T00:00:00.000000Z", "updated_at": "2024-01-01T00:00:00.000000Z" } ] }, "properties": { "customisers": { "type": "array", "example": [ { "customiser_id": 1, "name": "Storefront neon sign", "price_type": "FIXED_WIDTH", "product": "NEON", "selection_type": "SINGLE", "active": true, "created_at": "2024-01-01T00:00:00.000000Z", "updated_at": "2024-01-01T00:00:00.000000Z" } ], "items": { "type": "object", "properties": { "customiser_id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Storefront neon sign" }, "price_type": { "type": "string", "example": "FIXED_WIDTH" }, "product": { "type": "string", "example": "NEON" }, "selection_type": { "type": "string", "example": "SINGLE" }, "active": { "type": "boolean", "example": true }, "created_at": { "type": "string", "example": "2024-01-01T00:00:00.000000Z" }, "updated_at": { "type": "string", "example": "2024-01-01T00:00:00.000000Z" } } } } } } } } } }, "tags": [ "Customisers" ] } }, "/api/v2/customisers/{customiser}": { "parameters": [ { "in": "path", "name": "customiser", "description": "The customiser ID.", "example": "1", "required": true, "schema": { "type": "integer" } } ], "get": { "summary": "Get a customiser\n\nRetrieve a single customiser.", "operationId": "getACustomiserRetrieveASingleCustomiser", "description": "", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "customiser": { "customiser_id": 1, "name": "Storefront neon sign", "price_type": "FIXED_WIDTH", "product": "NEON", "selection_type": "SINGLE", "active": true, "created_at": "2024-01-01T00:00:00.000000Z", "updated_at": "2024-01-01T00:00:00.000000Z" } }, "properties": { "customiser": { "type": "object", "properties": { "customiser_id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Storefront neon sign" }, "price_type": { "type": "string", "example": "FIXED_WIDTH" }, "product": { "type": "string", "example": "NEON" }, "selection_type": { "type": "string", "example": "SINGLE" }, "active": { "type": "boolean", "example": true }, "created_at": { "type": "string", "example": "2024-01-01T00:00:00.000000Z" }, "updated_at": { "type": "string", "example": "2024-01-01T00:00:00.000000Z" } } } } } } } } }, "tags": [ "Customisers" ] } }, "/api/v3/customisers": { "parameters": [], "get": { "summary": "List customisers\n\nList the store's customisers — the configurable sign products shoppers\ndesign on the storefront. Call this to discover what the store sells and\nto find the integer `id` used by every per-customiser operation. Each\nitem reports the customiser's pricing model (`simple_letter`,\n`advanced_letter` or `frame_fit`, with a human display name), its\n`sign_category` and `product_family`, its styling `selection_mode`\n(`single_style` styles the whole sign as one unit; `per_word` lets the\nshopper style each word), and whether it is `active` on the storefront.\nThe operation is read-only, has no side effects, and is always safe to\nretry. Requires the `customisers:read` scope; results are always limited\nto the store the API key belongs to.\n\nResults are paginated: `data` holds up to `limit` customisers in\ncreation order (oldest first, stable across pages). While\n`pagination.has_more` is true, fetch the next page by requesting\n`links.next` — or by passing `pagination.next_cursor` as the `cursor`\nparameter with the same filters. Cursors are opaque and server-owned:\nsend them back unchanged, never construct or edit one. A cursor is only\nvalid for the exact filter combination it was issued with; changing\nfilters (or altering the cursor) yields a 422 problem with code\n`invalid_cursor` — restart from the first page by dropping the cursor.\nUnsupported filters or parameters are rejected with a 422 problem\nrather than ignored, so a typo can never silently change meaning.\n\nA 401 problem means the key is missing, invalid, or expired. A 403\nproblem with code `insufficient_scope` means the key is valid but lacks\n`customisers:read`; its `required_scopes` and `granted_scopes` members\nsay which scope is missing. A 429 problem means too many requests: wait\n`retry_after` seconds, then retry. Error responses use RFC 9457\nproblem+json with a machine-readable `code`, a documentation link in\n`type`, and a `request_id` to quote when contacting support.", "operationId": "listCustomisersListTheStoresCustomisersTheConfigurableSignProductsShoppersDesignOnTheStorefrontCallThisToDiscoverWhatTheStoreSellsAndToFindTheIntegeridUsedByEveryPerCustomiserOperationEachItemReportsTheCustomisersPricingModelsimpleLetteradvancedLetterOrframeFitWithAHumanDisplayNameItssignCategoryAndproductFamilyItsStylingselectionModesingleStyleStylesTheWholeSignAsOneUnitperWordLetsTheShopperStyleEachWordAndWhetherItIsactiveOnTheStorefrontTheOperationIsReadOnlyHasNoSideEffectsAndIsAlwaysSafeToRetryRequiresThecustomisersreadScopeResultsAreAlwaysLimitedToTheStoreTheAPIKeyBelongsToResultsArePaginateddataHoldsUpTolimitCustomisersInCreationOrderoldestFirstStableAcrossPagesWhilepaginationhasMoreIsTrueFetchTheNextPageByRequestinglinksnextOrByPassingpaginationnextCursorAsThecursorParameterWithTheSameFiltersCursorsAreOpaqueAndServerOwnedSendThemBackUnchangedNeverConstructOrEditOneACursorIsOnlyValidForTheExactFilterCombinationItWasIssuedWithChangingFiltersorAlteringTheCursorYieldsA422ProblemWithCodeinvalidCursorRestartFromTheFirstPageByDroppingTheCursorUnsupportedFiltersOrParametersAreRejectedWithA422ProblemRatherThanIgnoredSoATypoCanNeverSilentlyChangeMeaningA401ProblemMeansTheKeyIsMissingInvalidOrExpiredA403ProblemWithCodeinsufficientScopeMeansTheKeyIsValidButLackscustomisersreadItsrequiredScopesAndgrantedScopesMembersSayWhichScopeIsMissingA429ProblemMeansTooManyRequestsWaitretryAfterSecondsThenRetryErrorResponsesUseRFC9457Problem+jsonWithAMachineReadablecodeADocumentationLinkIntypeAndArequestIdToQuoteWhenContactingSupport", "description": "", "parameters": [ { "in": "query", "name": "limit", "description": "How many customisers to return per page,\nbetween 1 and 100. Defaults to 20.", "example": 2, "required": false, "schema": { "type": "integer", "description": "How many customisers to return per page,\nbetween 1 and 100. Defaults to 20.", "example": 2 } }, { "in": "query", "name": "cursor", "description": "The opaque `pagination.next_cursor` value from\nthe previous page. Omit it for the first page, and keep every other\nparameter identical between pages.", "example": null, "required": false, "schema": { "type": "string", "description": "The opaque `pagination.next_cursor` value from\nthe previous page. Omit it for the first page, and keep every other\nparameter identical between pages.", "example": null } }, { "in": "query", "name": "filter[active]", "description": "Only return customisers that are\n(`true`) or are not (`false`) live on the storefront.", "example": "true", "required": false, "schema": { "type": "string", "description": "Only return customisers that are\n(`true`) or are not (`false`) live on the storefront.", "example": "true" } }, { "in": "query", "name": "filter[pricing_model]", "description": "Only return customisers using\nthis pricing model. One of `simple_letter`, `advanced_letter` or\n`frame_fit`.", "example": "simple_letter", "required": false, "schema": { "type": "string", "description": "Only return customisers using\nthis pricing model. One of `simple_letter`, `advanced_letter` or\n`frame_fit`.", "example": "simple_letter" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "data": [ { "object": "customiser", "id": 42, "name": "Neon sign builder", "active": true, "pricing_model": "simple_letter", "pricing_model_display_name": "Simple Letter", "sign_category": "neon", "product_family": "neon", "selection_mode": "single_style", "created_at": "2026-01-12T03:14:15Z", "updated_at": "2026-06-01T22:09:41Z" }, { "object": "customiser", "id": 57, "name": "Metal letters", "active": true, "pricing_model": "advanced_letter", "pricing_model_display_name": "Advanced Letter", "sign_category": "metal_channel_letter", "product_family": "channel_letter", "selection_mode": "per_word", "created_at": "2026-02-03T11:00:00Z", "updated_at": "2026-06-14T09:27:03Z" } ], "pagination": { "has_more": true, "next_cursor": "eyJ2IjoxLCJhIjo1NywiZiI6IjZiOGY0YTJjOWQxZTBiN2EifQ.uLXovDLxjWFeqIhqbqcyIA" }, "links": { "self": "https://web.signcustomiser.com/api/v3/customisers?limit=2", "documentation": "https://www.signcustomiser.com/help/api/", "next": "https://web.signcustomiser.com/api/v3/customisers?limit=2&cursor=eyJ2IjoxLCJhIjo1NywiZiI6IjZiOGY0YTJjOWQxZTBiN2EifQ.uLXovDLxjWFeqIhqbqcyIA" }, "meta": { "api_version": "v3", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } }, "properties": { "data": { "type": "array", "example": [ { "object": "customiser", "id": 42, "name": "Neon sign builder", "active": true, "pricing_model": "simple_letter", "pricing_model_display_name": "Simple Letter", "sign_category": "neon", "product_family": "neon", "selection_mode": "single_style", "created_at": "2026-01-12T03:14:15Z", "updated_at": "2026-06-01T22:09:41Z" }, { "object": "customiser", "id": 57, "name": "Metal letters", "active": true, "pricing_model": "advanced_letter", "pricing_model_display_name": "Advanced Letter", "sign_category": "metal_channel_letter", "product_family": "channel_letter", "selection_mode": "per_word", "created_at": "2026-02-03T11:00:00Z", "updated_at": "2026-06-14T09:27:03Z" } ], "description": "The page of customiser objects, in creation order (oldest first). Each entry has the same shape as the show operation response — see GET /api/v3/customisers/{customiser} for per-field documentation.", "items": { "type": "object", "properties": { "object": { "type": "string", "example": "customiser" }, "id": { "type": "integer", "example": 42 }, "name": { "type": "string", "example": "Neon sign builder" }, "active": { "type": "boolean", "example": true }, "pricing_model": { "type": "string", "example": "simple_letter" }, "pricing_model_display_name": { "type": "string", "example": "Simple Letter" }, "sign_category": { "type": "string", "example": "neon" }, "product_family": { "type": "string", "example": "neon" }, "selection_mode": { "type": "string", "example": "single_style" }, "created_at": { "type": "string", "example": "2026-01-12T03:14:15Z" }, "updated_at": { "type": "string", "example": "2026-06-01T22:09:41Z" } } } }, "pagination": { "type": "object", "properties": { "has_more": { "type": "boolean", "example": true, "description": "Whether more customisers exist after this page. When true, follow links.next (or pass pagination.next_cursor as the cursor parameter) to fetch the next page." }, "next_cursor": { "type": [ "string", "null" ], "example": "eyJ2IjoxLCJhIjo1NywiZiI6IjZiOGY0YTJjOWQxZTBiN2EifQ.uLXovDLxjWFeqIhqbqcyIA", "description": "The opaque cursor for the next page, or null on the final page. Send it back unchanged with identical filters; never construct or edit a cursor." } }, "required": [ "has_more", "next_cursor" ] }, "links": { "type": "object", "properties": { "self": { "type": "string", "example": "https://web.signcustomiser.com/api/v3/customisers?limit=2" }, "documentation": { "type": "string", "example": "https://www.signcustomiser.com/help/api/" }, "next": { "type": "string", "example": "https://web.signcustomiser.com/api/v3/customisers?limit=2&cursor=eyJ2IjoxLCJhIjo1NywiZiI6IjZiOGY0YTJjOWQxZTBiN2EifQ.uLXovDLxjWFeqIhqbqcyIA" } } }, "meta": { "type": "object", "properties": { "api_version": { "type": "string", "example": "v3" }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } }, "required": [ "data" ] } } } }, "401": { "description": "Missing API key", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/missing_api_key", "title": "Missing API key", "status": 401, "code": "missing_api_key", "detail": "Provide a store API key as a bearer token: Authorization: Bearer . Keys are created in the merchant admin under Integrate → API Tokens.", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/missing_api_key" }, "title": { "type": "string", "example": "Missing API key" }, "status": { "type": "integer", "example": 401 }, "code": { "type": "string", "example": "missing_api_key" }, "detail": { "type": "string", "example": "Provide a store API key as a bearer token: Authorization: Bearer . Keys are created in the merchant admin under Integrate → API Tokens." }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/insufficient_scope", "title": "Insufficient scope", "status": 403, "code": "insufficient_scope", "detail": "This operation requires the customisers:read scope, but the API key grants the following scopes: store:read. Create a key that includes the required scope in the merchant admin under Integrate → API Tokens.", "required_scopes": [ "customisers:read" ], "granted_scopes": [ "store:read" ], "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/insufficient_scope" }, "title": { "type": "string", "example": "Insufficient scope" }, "status": { "type": "integer", "example": 403 }, "code": { "type": "string", "example": "insufficient_scope" }, "detail": { "type": "string", "example": "This operation requires the customisers:read scope, but the API key grants the following scopes: store:read. Create a key that includes the required scope in the merchant admin under Integrate → API Tokens." }, "required_scopes": { "type": "array", "example": [ "customisers:read" ], "items": { "type": "string" } }, "granted_scopes": { "type": "array", "example": [ "store:read" ], "items": { "type": "string" } }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "oneOf": [ { "description": "Invalid cursor", "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/invalid_cursor", "title": "Invalid cursor", "status": 422, "code": "invalid_cursor", "detail": "The cursor is not one this API issued. Cursors are opaque: send the pagination.next_cursor value from a previous response back unchanged, or restart pagination by repeating the request without a cursor.", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/invalid_cursor" }, "title": { "type": "string", "example": "Invalid cursor" }, "status": { "type": "integer", "example": 422 }, "code": { "type": "string", "example": "invalid_cursor" }, "detail": { "type": "string", "example": "The cursor is not one this API issued. Cursors are opaque: send the pagination.next_cursor value from a previous response back unchanged, or restart pagination by repeating the request without a cursor." }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } }, { "description": "Unknown filter", "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/unknown_filter", "title": "Unknown filter", "status": 422, "code": "unknown_filter", "detail": "The request includes filters this endpoint does not support: status. Supported filters: active, pricing_model.", "errors": [ { "parameter": "filter[status]", "code": "unknown_filter", "detail": "The filter \"status\" is not supported by this endpoint." } ], "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/unknown_filter" }, "title": { "type": "string", "example": "Unknown filter" }, "status": { "type": "integer", "example": 422 }, "code": { "type": "string", "example": "unknown_filter" }, "detail": { "type": "string", "example": "The request includes filters this endpoint does not support: status. Supported filters: active, pricing_model." }, "errors": { "type": "array", "example": [ { "parameter": "filter[status]", "code": "unknown_filter", "detail": "The filter \"status\" is not supported by this endpoint." } ], "items": { "type": "object", "properties": { "parameter": { "type": "string", "example": "filter[status]" }, "code": { "type": "string", "example": "unknown_filter" }, "detail": { "type": "string", "example": "The filter \"status\" is not supported by this endpoint." } } } }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } }, { "description": "Unsupported filter value", "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/invalid_parameter", "title": "Invalid query parameter", "status": 422, "code": "invalid_parameter", "detail": "The filter[pricing_model] value is not a supported pricing model.", "errors": [ { "parameter": "filter[pricing_model]", "code": "unsupported_value", "detail": "The filter[pricing_model] value is not a supported pricing model.", "allowed_values": [ "simple_letter", "advanced_letter", "frame_fit" ] } ], "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/invalid_parameter" }, "title": { "type": "string", "example": "Invalid query parameter" }, "status": { "type": "integer", "example": 422 }, "code": { "type": "string", "example": "invalid_parameter" }, "detail": { "type": "string", "example": "The filter[pricing_model] value is not a supported pricing model." }, "errors": { "type": "array", "example": [ { "parameter": "filter[pricing_model]", "code": "unsupported_value", "detail": "The filter[pricing_model] value is not a supported pricing model.", "allowed_values": [ "simple_letter", "advanced_letter", "frame_fit" ] } ], "items": { "type": "object", "properties": { "parameter": { "type": "string", "example": "filter[pricing_model]" }, "code": { "type": "string", "example": "unsupported_value" }, "detail": { "type": "string", "example": "The filter[pricing_model] value is not a supported pricing model." }, "allowed_values": { "type": "array", "example": [ "simple_letter", "advanced_letter", "frame_fit" ], "items": { "type": "string" } } } } }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/rate_limited", "title": "Too many requests", "status": 429, "code": "rate_limited", "detail": "You have exceeded the request limit for this API key. Wait 60 seconds, then retry.", "retry_after": 60, "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/rate_limited" }, "title": { "type": "string", "example": "Too many requests" }, "status": { "type": "integer", "example": 429 }, "code": { "type": "string", "example": "rate_limited" }, "detail": { "type": "string", "example": "You have exceeded the request limit for this API key. Wait 60 seconds, then retry." }, "retry_after": { "type": "integer", "example": 60 }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } } }, "tags": [ "Customisers" ] } }, "/api/v3/customisers/{customiser_id}": { "parameters": [ { "in": "path", "name": "customiser_id", "description": "The customiser id, from the list operation.", "example": "1", "required": true, "schema": { "type": "integer" } } ], "get": { "summary": "Get a customiser\n\nRetrieve one customiser by its integer `id` (as returned by the list\noperation). The response reports the customiser's pricing model\n(`simple_letter`, `advanced_letter` or `frame_fit`, with a human display\nname), its `sign_category` and `product_family`, its styling\n`selection_mode`, and whether it is `active` on the storefront. The\noperation is read-only, has no side effects, and is always safe to\nretry. Requires the `customisers:read` scope.\n\nA 404 problem with code `resource_not_found` means the customiser does\nnot exist on the store your API key belongs to — use the list operation\nto discover valid ids; ids from another store are indistinguishable\nfrom unknown ids. A 401 problem means the key is missing, invalid, or\nexpired. A 403 problem with code `insufficient_scope` means the key is\nvalid but lacks `customisers:read`. A 429 problem means too many\nrequests: wait `retry_after` seconds, then retry. Error responses use\nRFC 9457 problem+json with a machine-readable `code`, a documentation\nlink in `type`, and a `request_id` to quote when contacting support.", "operationId": "getACustomiserRetrieveOneCustomiserByItsIntegeridasReturnedByTheListOperationTheResponseReportsTheCustomisersPricingModelsimpleLetteradvancedLetterOrframeFitWithAHumanDisplayNameItssignCategoryAndproductFamilyItsStylingselectionModeAndWhetherItIsactiveOnTheStorefrontTheOperationIsReadOnlyHasNoSideEffectsAndIsAlwaysSafeToRetryRequiresThecustomisersreadScopeA404ProblemWithCoderesourceNotFoundMeansTheCustomiserDoesNotExistOnTheStoreYourAPIKeyBelongsToUseTheListOperationToDiscoverValidIdsIdsFromAnotherStoreAreIndistinguishableFromUnknownIdsA401ProblemMeansTheKeyIsMissingInvalidOrExpiredA403ProblemWithCodeinsufficientScopeMeansTheKeyIsValidButLackscustomisersreadA429ProblemMeansTooManyRequestsWaitretryAfterSecondsThenRetryErrorResponsesUseRFC9457Problem+jsonWithAMachineReadablecodeADocumentationLinkIntypeAndArequestIdToQuoteWhenContactingSupport", "description": "", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "data": { "object": "customiser", "id": 42, "name": "Neon sign builder", "active": true, "pricing_model": "simple_letter", "pricing_model_display_name": "Simple Letter", "sign_category": "neon", "product_family": "neon", "selection_mode": "single_style", "created_at": "2026-01-12T03:14:15Z", "updated_at": "2026-06-01T22:09:41Z" }, "links": { "self": "https://web.signcustomiser.com/api/v3/customisers/42", "documentation": "https://www.signcustomiser.com/help/api/" }, "meta": { "api_version": "v3", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } }, "properties": { "data": { "type": "object", "properties": { "object": { "type": "string", "example": "customiser", "description": "The resource type discriminator. Always \"customiser\" for this endpoint (closed set).", "enum": [ "customiser" ] }, "id": { "type": "integer", "example": 42, "description": "The customiser id used in every per-customiser operation path." }, "name": { "type": [ "string", "null" ], "example": "Neon sign builder", "description": "The merchant-chosen customiser name, or null when unnamed." }, "active": { "type": "boolean", "example": true, "description": "Whether the customiser is live on the storefront." }, "pricing_model": { "type": "string", "example": "simple_letter", "description": "How the customiser prices signs: simple_letter (priced per letter at a fixed sign width), advanced_letter (priced from the material length of each letter), or frame_fit (priced by frame area). This set is expected to grow — tolerate unknown values. Stores that used the retired fixed-height model before it was withdrawn report the read-only value legacy_fixed_height; it is never accepted as input.", "enum": [ "simple_letter", "advanced_letter", "frame_fit", "legacy_fixed_height" ] }, "pricing_model_display_name": { "type": "string", "example": "Simple Letter", "description": "The pricing model's human display name (e.g. \"Simple Letter\"). Display only — parse pricing_model, never this label." }, "sign_category": { "type": [ "string", "null" ], "example": "neon", "description": "The kind of sign the customiser sells, or null when not set. One of: neon, acrylic_channel_letter, metal_channel_letter, metal_cut_out, stencil, lightbox, wood_letter, aluminium_plate, braille_sign, wood_frame. This set is expected to grow — tolerate unknown values.", "enum": [ "neon", "acrylic_channel_letter", "metal_channel_letter", "metal_cut_out", "stencil", "lightbox", "wood_letter", "aluminium_plate", "braille_sign", "wood_frame", null ] }, "product_family": { "type": [ "string", "null" ], "example": "neon", "description": "The manufacturing family the sign belongs to, or null when not set. One of: neon, channel_letter, metal_cut_out. This set is expected to grow — tolerate unknown values.", "enum": [ "neon", "channel_letter", "metal_cut_out", null ] }, "selection_mode": { "type": "string", "example": "single_style", "description": "How shoppers style the sign text (closed set): single_style applies one style to the whole sign; per_word lets the shopper style each word.", "enum": [ "single_style", "per_word" ] }, "created_at": { "type": "string", "example": "2026-01-12T03:14:15Z", "description": "When the customiser was created, ISO 8601 UTC." }, "updated_at": { "type": "string", "example": "2026-06-01T22:09:41Z", "description": "When the customiser configuration last changed, ISO 8601 UTC." } }, "required": [ "object", "id", "name", "active", "pricing_model", "pricing_model_display_name", "sign_category", "product_family", "selection_mode", "created_at", "updated_at" ] }, "links": { "type": "object", "properties": { "self": { "type": "string", "example": "https://web.signcustomiser.com/api/v3/customisers/42" }, "documentation": { "type": "string", "example": "https://www.signcustomiser.com/help/api/" } } }, "meta": { "type": "object", "properties": { "api_version": { "type": "string", "example": "v3" }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } } } }, "401": { "description": "Missing API key", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/missing_api_key", "title": "Missing API key", "status": 401, "code": "missing_api_key", "detail": "Provide a store API key as a bearer token: Authorization: Bearer . Keys are created in the merchant admin under Integrate → API Tokens.", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/missing_api_key" }, "title": { "type": "string", "example": "Missing API key" }, "status": { "type": "integer", "example": 401 }, "code": { "type": "string", "example": "missing_api_key" }, "detail": { "type": "string", "example": "Provide a store API key as a bearer token: Authorization: Bearer . Keys are created in the merchant admin under Integrate → API Tokens." }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/insufficient_scope", "title": "Insufficient scope", "status": 403, "code": "insufficient_scope", "detail": "This operation requires the customisers:read scope, but the API key grants the following scopes: store:read. Create a key that includes the required scope in the merchant admin under Integrate → API Tokens.", "required_scopes": [ "customisers:read" ], "granted_scopes": [ "store:read" ], "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/insufficient_scope" }, "title": { "type": "string", "example": "Insufficient scope" }, "status": { "type": "integer", "example": 403 }, "code": { "type": "string", "example": "insufficient_scope" }, "detail": { "type": "string", "example": "This operation requires the customisers:read scope, but the API key grants the following scopes: store:read. Create a key that includes the required scope in the merchant admin under Integrate → API Tokens." }, "required_scopes": { "type": "array", "example": [ "customisers:read" ], "items": { "type": "string" } }, "granted_scopes": { "type": "array", "example": [ "store:read" ], "items": { "type": "string" } }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } }, "404": { "description": "Unknown customiser", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/resource_not_found", "title": "Resource not found", "status": 404, "code": "resource_not_found", "detail": "The requested resource does not exist or does not belong to the authenticated store.", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/resource_not_found" }, "title": { "type": "string", "example": "Resource not found" }, "status": { "type": "integer", "example": 404 }, "code": { "type": "string", "example": "resource_not_found" }, "detail": { "type": "string", "example": "The requested resource does not exist or does not belong to the authenticated store." }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } }, "422": { "description": "Unknown query parameter", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/unknown_parameter", "title": "Unknown query parameter", "status": 422, "code": "unknown_parameter", "detail": "The request includes query parameters this endpoint does not support: include. This endpoint accepts no query parameters.", "errors": [ { "parameter": "include", "code": "unknown_parameter", "detail": "The query parameter \"include\" is not supported by this endpoint." } ], "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/unknown_parameter" }, "title": { "type": "string", "example": "Unknown query parameter" }, "status": { "type": "integer", "example": 422 }, "code": { "type": "string", "example": "unknown_parameter" }, "detail": { "type": "string", "example": "The request includes query parameters this endpoint does not support: include. This endpoint accepts no query parameters." }, "errors": { "type": "array", "example": [ { "parameter": "include", "code": "unknown_parameter", "detail": "The query parameter \"include\" is not supported by this endpoint." } ], "items": { "type": "object", "properties": { "parameter": { "type": "string", "example": "include" }, "code": { "type": "string", "example": "unknown_parameter" }, "detail": { "type": "string", "example": "The query parameter \"include\" is not supported by this endpoint." } } } }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/rate_limited", "title": "Too many requests", "status": 429, "code": "rate_limited", "detail": "You have exceeded the request limit for this API key. Wait 60 seconds, then retry.", "retry_after": 60, "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/rate_limited" }, "title": { "type": "string", "example": "Too many requests" }, "status": { "type": "integer", "example": 429 }, "code": { "type": "string", "example": "rate_limited" }, "detail": { "type": "string", "example": "You have exceeded the request limit for this API key. Wait 60 seconds, then retry." }, "retry_after": { "type": "integer", "example": 60 }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } } }, "tags": [ "Customisers" ] } }, "/api/orders": { "parameters": [], "post": { "summary": "Create a legacy order\n\nDeprecated. Use `POST /api/v2/orders` for new integrations.", "operationId": "createALegacyOrderDeprecatedUsePOSTapiv2ordersForNewIntegrations", "description": "", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "ok": true }, "properties": { "ok": { "type": "boolean", "example": true } } } } } } }, "tags": [ "Legacy" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "order_id": { "type": "string", "description": "Your platform's internal order ID.", "example": "123456" }, "order_number": { "type": "string", "description": "The human-readable order number.", "example": "SC-1001" }, "order_total": { "type": "number", "description": "The total order value.", "example": 86.34 }, "order_currency": { "type": "string", "description": "The order currency.", "example": "USD" }, "email": { "type": [ "string", "null" ], "description": "The customer's email address.", "example": "customer@example.com" }, "products": { "type": "array", "description": "The products in the order.", "example": [ "architecto" ], "items": { "type": "string" } }, "shipping_address": { "type": [ "object", "null" ], "description": "The shipping address for the order.", "example": [], "properties": { "name": { "type": [ "string", "null" ], "description": "The recipient name.", "example": "John Smith" }, "phone": { "type": [ "string", "null" ], "description": "The recipient phone number.", "example": "+1 555-123-4567" }, "address1": { "type": [ "string", "null" ], "description": "The first shipping address line.", "example": "123 Main St" }, "address2": { "type": [ "string", "null" ], "description": "The second shipping address line.", "example": "Suite 4" }, "city": { "type": [ "string", "null" ], "description": "The shipping city.", "example": "Los Angeles" }, "province": { "type": [ "string", "null" ], "description": "The shipping province or state.", "example": "CA" }, "country": { "type": [ "string", "null" ], "description": "The shipping country code.", "example": "US" }, "zip": { "type": [ "string", "null" ], "description": "The shipping postcode or ZIP code.", "example": "90001" } } }, "shipping_line": { "type": [ "string", "null" ], "description": "The selected shipping method.", "example": "Express" } }, "required": [ "order_id", "order_number", "products" ] } } } } } }, "/api/customisers/{customiser}/products": { "parameters": [ { "in": "path", "name": "customiser", "description": "The Sign Customiser ID tied to this product.", "example": "42", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "Sync a legacy product\n\nDeprecated. Use the current custom integration flow for new builds.", "operationId": "syncALegacyProductDeprecatedUseTheCurrentCustomIntegrationFlowForNewBuilds", "description": "", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "ok": true }, "properties": { "ok": { "type": "boolean", "example": true } } } } } } }, "tags": [ "Legacy" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "product_id": { "type": "string", "description": "Your platform's product ID.", "example": "product-987654321" }, "cart": { "type": "object", "description": "The legacy cart payload captured from the customiser.", "example": [], "properties": {} }, "price_breakdown": { "type": "object", "description": "The price breakdown captured during product creation.", "example": [], "properties": {} }, "custom_background_path": { "type": [ "string", "null" ], "description": "The cropped custom background URL.", "example": "https://cdn.example.com/bg.jpg" }, "custom_background_original_path": { "type": [ "string", "null" ], "description": "The original custom background URL.", "example": "https://cdn.example.com/bg-original.jpg" }, "product_type_paths": { "type": [ "object", "null" ], "description": "Product type image URLs keyed by letter part.", "example": [], "properties": {} }, "logo_original_path": { "type": [ "string", "null" ], "description": "The original uploaded logo URL.", "example": "https://cdn.example.com/logo.png" } }, "required": [ "product_id", "cart", "price_breakdown" ] } } } } } }, "/api/v3/orders": { "parameters": [], "get": { "summary": "List orders\n\nList orders accepted and stored by Sign Customiser for the authenticated\nStore, newest first. `received` means only that the order was accepted\ninto Sign Customiser; it does not claim payment, manufacturing,\nfulfilment, shipping, refund, or cancellation state. `line_item_count`\ncounts modern products only. Legacy cached products remain available to\nthe established CSV export but are deliberately absent from v3 order\nprojections and do not match `filter[customiser_id]`.\n\nFollow `links.next` while `pagination.has_more` is true. Cursors are\nopaque and are valid only with the exact filters that issued them.\nUnsupported parameters and filters are rejected rather than ignored.\nRequires `orders:read`; results are always scoped to the Store belonging\nto the API key. This read is safe to retry.", "operationId": "listOrdersListOrdersAcceptedAndStoredBySignCustomiserForTheAuthenticatedStoreNewestFirstreceivedMeansOnlyThatTheOrderWasAcceptedIntoSignCustomiserItDoesNotClaimPaymentManufacturingFulfilmentShippingRefundOrCancellationStatelineItemCountCountsModernProductsOnlyLegacyCachedProductsRemainAvailableToTheEstablishedCSVExportButAreDeliberatelyAbsentFromV3OrderProjectionsAndDoNotMatchfiltercustomiserIdFollowlinksnextWhilepaginationhasMoreIsTrueCursorsAreOpaqueAndAreValidOnlyWithTheExactFiltersThatIssuedThemUnsupportedParametersAndFiltersAreRejectedRatherThanIgnoredRequiresordersreadResultsAreAlwaysScopedToTheStoreBelongingToTheAPIKeyThisReadIsSafeToRetry", "description": "", "parameters": [ { "in": "query", "name": "filter[status]", "description": "Order acceptance status. This set is expected to grow; tolerate unknown response values.", "example": "received", "required": false, "schema": { "type": "string", "description": "Order acceptance status. This set is expected to grow; tolerate unknown response values.", "example": "received", "enum": [ "received" ] } }, { "in": "query", "name": "limit", "description": "Number of orders per page, from 1 to 100. Defaults to 20.", "example": 20, "required": false, "schema": { "type": "integer", "description": "Number of orders per page, from 1 to 100. Defaults to 20.", "example": 20 } }, { "in": "query", "name": "cursor", "description": "The opaque pagination.next_cursor from the previous page.", "example": null, "required": false, "schema": { "type": "string", "description": "The opaque pagination.next_cursor from the previous page.", "example": null } }, { "in": "query", "name": "filter[created_from]", "description": "Include orders created on or after this UTC date (YYYY-MM-DD).", "example": "2026-07-01", "required": false, "schema": { "type": "string", "description": "Include orders created on or after this UTC date (YYYY-MM-DD).", "example": "2026-07-01" } }, { "in": "query", "name": "filter[created_to]", "description": "Include orders created on or before this UTC date (YYYY-MM-DD).", "example": "2026-07-19", "required": false, "schema": { "type": "string", "description": "Include orders created on or before this UTC date (YYYY-MM-DD).", "example": "2026-07-19" } }, { "in": "query", "name": "filter[customiser_id]", "description": "Include orders with a modern line item from this customiser.", "example": 42, "required": false, "schema": { "type": "integer", "description": "Include orders with a modern line item from this customiser.", "example": 42 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "data": [ { "object": "order", "id": 123, "store_order_id": "gid://shopify/Order/1001", "store_order_number": "#1001", "status": "received", "status_display_name": "Received", "total_amount": 31900, "currency": "AUD", "line_item_count": 2, "created_at": "2026-07-18T02:15:00Z", "updated_at": "2026-07-18T02:16:00Z" } ], "pagination": { "has_more": false, "next_cursor": null }, "links": { "self": "https://web.signcustomiser.com/api/v3/orders", "documentation": "https://www.signcustomiser.com/help/api/", "next": null }, "meta": { "api_version": "v3", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } }, "properties": { "data": { "type": "array", "example": [ { "object": "order", "id": 123, "store_order_id": "gid://shopify/Order/1001", "store_order_number": "#1001", "status": "received", "status_display_name": "Received", "total_amount": 31900, "currency": "AUD", "line_item_count": 2, "created_at": "2026-07-18T02:15:00Z", "updated_at": "2026-07-18T02:16:00Z" } ], "description": "The page of order summaries. Each status uses the expected-to-grow enum documented by the show operation.", "items": { "type": "object", "properties": { "object": { "type": "string", "example": "order" }, "id": { "type": "integer", "example": 123 }, "store_order_id": { "type": "string", "example": "gid://shopify/Order/1001" }, "store_order_number": { "type": "string", "example": "#1001" }, "status": { "type": "string", "example": "received", "description": "The order record status. This set is expected to grow; tolerate unknown values.", "enum": [ "received" ] }, "status_display_name": { "type": "string", "example": "Received" }, "total_amount": { "type": "integer", "example": 31900 }, "currency": { "type": "string", "example": "AUD" }, "line_item_count": { "type": "integer", "example": 2 }, "created_at": { "type": "string", "example": "2026-07-18T02:15:00Z" }, "updated_at": { "type": "string", "example": "2026-07-18T02:16:00Z" } }, "required": [ "status" ] } }, "pagination": { "type": "object", "properties": { "has_more": { "type": "boolean", "example": false }, "next_cursor": { "type": [ "string", "null" ], "example": null } } }, "links": { "type": "object", "properties": { "self": { "type": "string", "example": "https://web.signcustomiser.com/api/v3/orders" }, "documentation": { "type": "string", "example": "https://www.signcustomiser.com/help/api/" }, "next": { "type": [ "string", "null" ], "example": null } } }, "meta": { "type": "object", "properties": { "api_version": { "type": "string", "example": "v3" }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } }, "required": [ "data" ] } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/missing_api_key", "title": "Missing API key", "status": 401, "code": "missing_api_key", "detail": "Provide a store API key as a bearer token.", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/missing_api_key" }, "title": { "type": "string", "example": "Missing API key" }, "status": { "type": "integer", "example": 401 }, "code": { "type": "string", "example": "missing_api_key" }, "detail": { "type": "string", "example": "Provide a store API key as a bearer token." }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/insufficient_scope", "title": "Insufficient scope", "status": 403, "code": "insufficient_scope", "detail": "This operation requires the orders:read scope.", "required_scopes": [ "orders:read" ], "granted_scopes": [], "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/insufficient_scope" }, "title": { "type": "string", "example": "Insufficient scope" }, "status": { "type": "integer", "example": 403 }, "code": { "type": "string", "example": "insufficient_scope" }, "detail": { "type": "string", "example": "This operation requires the orders:read scope." }, "required_scopes": { "type": "array", "example": [ "orders:read" ], "items": { "type": "string" } }, "granted_scopes": { "type": "array", "example": [] }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } }, "422": { "description": "Invalid filter or cursor", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/invalid_parameter", "title": "Invalid query parameter", "status": 422, "code": "invalid_parameter", "detail": "The filter[created_from] value must be a valid date in YYYY-MM-DD format, interpreted in UTC.", "errors": [ { "parameter": "filter[created_from]", "code": "invalid_parameter", "detail": "The filter[created_from] value must be a valid date in YYYY-MM-DD format, interpreted in UTC." } ], "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/invalid_parameter" }, "title": { "type": "string", "example": "Invalid query parameter" }, "status": { "type": "integer", "example": 422 }, "code": { "type": "string", "example": "invalid_parameter" }, "detail": { "type": "string", "example": "The filter[created_from] value must be a valid date in YYYY-MM-DD format, interpreted in UTC." }, "errors": { "type": "array", "example": [ { "parameter": "filter[created_from]", "code": "invalid_parameter", "detail": "The filter[created_from] value must be a valid date in YYYY-MM-DD format, interpreted in UTC." } ], "items": { "type": "object", "properties": { "parameter": { "type": "string", "example": "filter[created_from]" }, "code": { "type": "string", "example": "invalid_parameter" }, "detail": { "type": "string", "example": "The filter[created_from] value must be a valid date in YYYY-MM-DD format, interpreted in UTC." } } } }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/rate_limited", "title": "Too many requests", "status": 429, "code": "rate_limited", "detail": "You have exceeded the request limit for this API key.", "retry_after": 60, "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/rate_limited" }, "title": { "type": "string", "example": "Too many requests" }, "status": { "type": "integer", "example": 429 }, "code": { "type": "string", "example": "rate_limited" }, "detail": { "type": "string", "example": "You have exceeded the request limit for this API key." }, "retry_after": { "type": "integer", "example": 60 }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } } }, "tags": [ "Orders" ] }, "post": { "summary": "Create an order\n\nStore one order received from an enabled custom integration for the\nauthenticated Store. Every `product_id` must be a modern product created\nthrough the same integration and Store. The 201 response means Sign\nCustomiser committed the order; it does not claim payment, manufacturing,\nfulfilment, shipping, refund, or cancellation state. Requires\n`orders:write`.\n\n`total_amount` is the integration's external grand total in integer minor\nunits. Sign Customiser separately derives its app total from the stored\nunit prices and quantities, so callers cannot override the platform fee\nbasis. `currency` must equal the Store and every referenced product\ncurrency. Customer and address values are optional snapshots; request\npayloads are never retained as raw JSON.\n\nSign Customiser durably schedules the established manufacturer order\nemails, order analytics, order-created webhook, and onboarding\nsynchronisation with the order. Manufacturer recipients and analytics\nevents have independent retry units. A queue publishing failure rolls the\norder back. Delivery by external providers is asynchronous. Repeating the\nexact method, path, body, credential, and `Idempotency-Key` replays the\noriginal 201 response and does not schedule those effects again. Retry a 409\n`idempotency_key_in_flight` with the same key after `retry_after`; use the\noriginal body or a new key for an idempotency conflict. This v3 operation\nrejects a `store_order_id` already present for the integration and\nserialises concurrent v3 creations. During migration, do not send the same\nlogical order through legacy and v3 writes in parallel.", "operationId": "createAnOrderStoreOneOrderReceivedFromAnEnabledCustomIntegrationForTheAuthenticatedStoreEveryproductIdMustBeAModernProductCreatedThroughTheSameIntegrationAndStoreThe201ResponseMeansSignCustomiserCommittedTheOrderItDoesNotClaimPaymentManufacturingFulfilmentShippingRefundOrCancellationStateRequiresorderswritetotalAmountIsTheIntegrationsExternalGrandTotalInIntegerMinorUnitsSignCustomiserSeparatelyDerivesItsAppTotalFromTheStoredUnitPricesAndQuantitiesSoCallersCannotOverrideThePlatformFeeBasiscurrencyMustEqualTheStoreAndEveryReferencedProductCurrencyCustomerAndAddressValuesAreOptionalSnapshotsRequestPayloadsAreNeverRetainedAsRawJSONSignCustomiserDurablySchedulesTheEstablishedManufacturerOrderEmailsOrderAnalyticsOrderCreatedWebhookAndOnboardingSynchronisationWithTheOrderManufacturerRecipientsAndAnalyticsEventsHaveIndependentRetryUnitsAQueuePublishingFailureRollsTheOrderBackDeliveryByExternalProvidersIsAsynchronousRepeatingTheExactMethodPathBodyCredentialAndIdempotencyKeyReplaysTheOriginal201ResponseAndDoesNotScheduleThoseEffectsAgainRetryA409idempotencyKeyInFlightWithTheSameKeyAfterretryAfterUseTheOriginalBodyOrANewKeyForAnIdempotencyConflictThisV3OperationRejectsAstoreOrderIdAlreadyPresentForTheIntegrationAndSerialisesConcurrentV3CreationsDuringMigrationDoNotSendTheSameLogicalOrderThroughLegacyAndV3WritesInParallel", "description": "", "parameters": [ { "in": "header", "name": "Idempotency-Key", "description": "", "example": "11da2e11-24ca-41ae-99cc-f88c87d2a645", "schema": { "type": "string" }, "required": true } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "data": { "object": "order", "id": 123, "store_order_id": "ext-order-1001", "store_order_number": "#1001", "status": "received", "status_display_name": "Received", "total_amount": 25800, "currency": "AUD", "shipping_method": "Express", "customer": { "first_name": "Ada", "last_name": "Lovelace", "email": "ada@example.com", "phone": "+61 400 000 001" }, "billing_address": { "first_name": "Ada", "last_name": "Lovelace", "company": null, "address_1": "1 Example Street", "address_2": null, "city": "Adelaide", "province": "SA", "postcode": "5000", "country": "AU", "email": null, "phone": null }, "shipping_address": { "first_name": "Ada", "last_name": "Lovelace", "company": null, "address_1": "1 Example Street", "address_2": null, "city": "Adelaide", "province": "SA", "postcode": "5000", "country": "AU", "email": null, "phone": null }, "line_items": [ { "object": "order_line_item", "id": 731, "store_product_id": "ext-product-1001", "customiser_id": 42, "title": "Custom neon sign", "quantity": 2, "unit_price_amount": 12900, "currency": "AUD", "preview_image_url": null, "width_cm": 80.5, "height_cm": 31.5, "length_cm": 2.5 } ], "created_at": "2026-07-19T09:20:00Z", "updated_at": "2026-07-19T09:20:00Z" }, "links": { "self": "https://web.signcustomiser.com/api/v3/orders/123", "documentation": "https://www.signcustomiser.com/help/api/" }, "meta": { "api_version": "v3", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } }, "properties": { "data": { "type": "object", "properties": { "object": { "type": "string", "example": "order" }, "id": { "type": "integer", "example": 123 }, "store_order_id": { "type": "string", "example": "ext-order-1001" }, "store_order_number": { "type": "string", "example": "#1001" }, "status": { "type": "string", "example": "received", "description": "The order record status. This set is expected to grow; tolerate unknown values.", "enum": [ "received" ] }, "status_display_name": { "type": "string", "example": "Received" }, "total_amount": { "type": "integer", "example": 25800 }, "currency": { "type": [ "string", "null" ], "example": "AUD" }, "shipping_method": { "type": [ "string", "null" ], "example": "Express" }, "customer": { "type": [ "object", "null" ], "properties": { "first_name": { "type": [ "string", "null" ], "example": "Ada" }, "last_name": { "type": [ "string", "null" ], "example": "Lovelace" }, "email": { "type": [ "string", "null" ], "example": "ada@example.com" }, "phone": { "type": [ "string", "null" ], "example": "+61 400 000 001" } }, "required": [ "first_name", "last_name", "email", "phone" ] }, "billing_address": { "type": [ "object", "null" ], "properties": { "first_name": { "type": [ "string", "null" ], "example": "Ada" }, "last_name": { "type": [ "string", "null" ], "example": "Lovelace" }, "company": { "type": [ "string", "null" ], "example": null }, "address_1": { "type": [ "string", "null" ], "example": "1 Example Street" }, "address_2": { "type": [ "string", "null" ], "example": null }, "city": { "type": [ "string", "null" ], "example": "Adelaide" }, "province": { "type": [ "string", "null" ], "example": "SA" }, "postcode": { "type": [ "string", "null" ], "example": "5000" }, "country": { "type": [ "string", "null" ], "example": "AU" }, "email": { "type": [ "string", "null" ], "example": null }, "phone": { "type": [ "string", "null" ], "example": null } }, "required": [ "first_name", "last_name", "company", "address_1", "address_2", "city", "province", "postcode", "country", "email", "phone" ] }, "shipping_address": { "type": [ "object", "null" ], "properties": { "first_name": { "type": [ "string", "null" ], "example": "Ada" }, "last_name": { "type": [ "string", "null" ], "example": "Lovelace" }, "company": { "type": [ "string", "null" ], "example": null }, "address_1": { "type": [ "string", "null" ], "example": "1 Example Street" }, "address_2": { "type": [ "string", "null" ], "example": null }, "city": { "type": [ "string", "null" ], "example": "Adelaide" }, "province": { "type": [ "string", "null" ], "example": "SA" }, "postcode": { "type": [ "string", "null" ], "example": "5000" }, "country": { "type": [ "string", "null" ], "example": "AU" }, "email": { "type": [ "string", "null" ], "example": null }, "phone": { "type": [ "string", "null" ], "example": null } }, "required": [ "first_name", "last_name", "company", "address_1", "address_2", "city", "province", "postcode", "country", "email", "phone" ] }, "line_items": { "type": "array", "example": [ { "object": "order_line_item", "id": 731, "store_product_id": "ext-product-1001", "customiser_id": 42, "title": "Custom neon sign", "quantity": 2, "unit_price_amount": 12900, "currency": "AUD", "preview_image_url": null, "width_cm": 80.5, "height_cm": 31.5, "length_cm": 2.5 } ], "items": { "type": "object", "properties": { "object": { "type": "string", "example": "order_line_item" }, "id": { "type": "integer", "example": 731 }, "store_product_id": { "type": [ "string", "null" ], "example": "ext-product-1001" }, "customiser_id": { "type": "integer", "example": 42 }, "title": { "type": [ "string", "null" ], "example": "Custom neon sign" }, "quantity": { "type": "integer", "example": 2 }, "unit_price_amount": { "type": "integer", "example": 12900 }, "currency": { "type": [ "string", "null" ], "example": "AUD" }, "preview_image_url": { "type": [ "string", "null" ], "example": null }, "width_cm": { "type": [ "number", "null" ], "example": 80.5 }, "height_cm": { "type": [ "number", "null" ], "example": 31.5 }, "length_cm": { "type": [ "number", "null" ], "example": 2.5 } }, "required": [ "object", "id", "store_product_id", "customiser_id", "title", "quantity", "unit_price_amount", "currency", "preview_image_url", "width_cm", "height_cm", "length_cm" ] } }, "created_at": { "type": [ "string", "null" ], "example": "2026-07-19T09:20:00Z" }, "updated_at": { "type": [ "string", "null" ], "example": "2026-07-19T09:20:00Z" } }, "required": [ "object", "id", "store_order_id", "store_order_number", "status", "status_display_name", "total_amount", "currency", "shipping_method", "customer", "billing_address", "shipping_address", "line_items", "created_at", "updated_at" ] }, "links": { "type": "object", "properties": { "self": { "type": "string", "example": "https://web.signcustomiser.com/api/v3/orders/123" }, "documentation": { "type": "string", "example": "https://www.signcustomiser.com/help/api/" } }, "required": [ "self", "documentation" ] }, "meta": { "type": "object", "properties": { "api_version": { "type": "string", "example": "v3" }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } }, "required": [ "api_version", "request_id" ] } }, "required": [ "data", "links", "meta" ] } } } }, "400": { "description": "Missing idempotency key", "content": { "application/problem+json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/missing_idempotency_key", "title": "Missing idempotency key", "status": 400, "code": "missing_idempotency_key", "detail": "Provide an Idempotency-Key header for this write operation.", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/missing_idempotency_key" }, "title": { "type": "string", "example": "Missing idempotency key" }, "status": { "type": "integer", "example": 400 }, "code": { "type": "string", "example": "missing_idempotency_key" }, "detail": { "type": "string", "example": "Provide an Idempotency-Key header for this write operation." }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } }, "required": [ "type", "title", "status", "code", "detail", "request_id" ] } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/missing_api_key", "title": "Missing API key", "status": 401, "code": "missing_api_key", "detail": "Provide a store API key as a bearer token.", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/missing_api_key" }, "title": { "type": "string", "example": "Missing API key" }, "status": { "type": "integer", "example": 401 }, "code": { "type": "string", "example": "missing_api_key" }, "detail": { "type": "string", "example": "Provide a store API key as a bearer token." }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } }, "required": [ "type", "title", "status", "code", "detail", "request_id" ] } } } }, "403": { "description": "Insufficient scope", "content": { "application/problem+json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/insufficient_scope", "title": "Insufficient scope", "status": 403, "code": "insufficient_scope", "detail": "This operation requires the orders:write scope.", "required_scopes": [ "orders:write" ], "granted_scopes": [ "orders:read" ], "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/insufficient_scope" }, "title": { "type": "string", "example": "Insufficient scope" }, "status": { "type": "integer", "example": 403 }, "code": { "type": "string", "example": "insufficient_scope" }, "detail": { "type": "string", "example": "This operation requires the orders:write scope." }, "required_scopes": { "type": "array", "example": [ "orders:write" ], "items": { "type": "string" } }, "granted_scopes": { "type": "array", "example": [ "orders:read" ], "items": { "type": "string" } }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } }, "required": [ "type", "title", "status", "code", "detail", "request_id" ] } } } }, "404": { "description": "Unknown or foreign resource", "content": { "application/problem+json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/resource_not_found", "title": "Resource not found", "status": 404, "code": "resource_not_found", "detail": "The requested resource does not exist or does not belong to the authenticated store.", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/resource_not_found" }, "title": { "type": "string", "example": "Resource not found" }, "status": { "type": "integer", "example": 404 }, "code": { "type": "string", "example": "resource_not_found" }, "detail": { "type": "string", "example": "The requested resource does not exist or does not belong to the authenticated store." }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } }, "required": [ "type", "title", "status", "code", "detail", "request_id" ] } } } }, "409": { "description": "External order already exists", "content": { "application/problem+json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/store_order_id_conflict", "title": "Store order ID conflict", "status": 409, "code": "store_order_id_conflict", "detail": "This integration has already created an order with the supplied store_order_id. Retry the original request with its original Idempotency-Key, or use a new store_order_id.", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/store_order_id_conflict" }, "title": { "type": "string", "example": "Store order ID conflict" }, "status": { "type": "integer", "example": 409 }, "code": { "type": "string", "example": "store_order_id_conflict" }, "detail": { "type": "string", "example": "This integration has already created an order with the supplied store_order_id. Retry the original request with its original Idempotency-Key, or use a new store_order_id." }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } }, "required": [ "type", "title", "status", "code", "detail", "request_id" ] } } } }, "413": { "description": "Request body too large", "content": { "application/problem+json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/request_too_large", "title": "Request too large", "status": 413, "code": "request_too_large", "detail": "The request body must not exceed 2 MiB.", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/request_too_large" }, "title": { "type": "string", "example": "Request too large" }, "status": { "type": "integer", "example": 413 }, "code": { "type": "string", "example": "request_too_large" }, "detail": { "type": "string", "example": "The request body must not exceed 2 MiB." }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } }, "required": [ "type", "title", "status", "code", "detail", "request_id" ] } } } }, "422": { "description": "Invalid request field", "content": { "application/problem+json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/validation_failed", "title": "Validation failed", "status": 422, "code": "validation_failed", "detail": "One or more request fields are invalid.", "errors": [ { "parameter": "line_items.0.product_id", "pointer": "/line_items/0/product_id", "code": "currency_mismatch", "detail": "The product currency must match the order and Store currency." } ], "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/validation_failed" }, "title": { "type": "string", "example": "Validation failed" }, "status": { "type": "integer", "example": 422 }, "code": { "type": "string", "example": "validation_failed" }, "detail": { "type": "string", "example": "One or more request fields are invalid." }, "errors": { "type": "array", "example": [ { "parameter": "line_items.0.product_id", "pointer": "/line_items/0/product_id", "code": "currency_mismatch", "detail": "The product currency must match the order and Store currency." } ], "items": { "type": "object", "properties": { "parameter": { "type": "string", "example": "line_items.0.product_id" }, "pointer": { "type": "string", "example": "/line_items/0/product_id" }, "code": { "type": "string", "example": "currency_mismatch" }, "detail": { "type": "string", "example": "The product currency must match the order and Store currency." } } } }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } }, "required": [ "type", "title", "status", "code", "detail", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/rate_limited", "title": "Too many requests", "status": 429, "code": "rate_limited", "detail": "You have exceeded the request limit for this API key.", "retry_after": 60, "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/rate_limited" }, "title": { "type": "string", "example": "Too many requests" }, "status": { "type": "integer", "example": 429 }, "code": { "type": "string", "example": "rate_limited" }, "detail": { "type": "string", "example": "You have exceeded the request limit for this API key." }, "retry_after": { "type": "integer", "example": 60 }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } }, "required": [ "type", "title", "status", "code", "detail", "request_id" ] } } } } }, "tags": [ "Orders" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "integration_id": { "type": "integer", "description": "Enabled custom integration id belonging to the Store.", "example": 17 }, "store_order_id": { "type": "string", "description": "Stable order id in the integration.", "example": "ext-order-1001" }, "store_order_number": { "type": "string", "description": "Display order number in the integration.", "example": "#1001" }, "total_amount": { "type": "integer", "description": "External grand total in minor currency units.", "example": 25800 }, "currency": { "type": "string", "description": "Uppercase ISO 4217 Store currency.", "example": "AUD" }, "shipping_method": { "type": [ "string", "null" ], "description": "Nullable shipping method snapshot.", "example": "Express" }, "customer": { "type": [ "object", "null" ], "description": "Nullable customer snapshot.", "example": { "first_name": "Ada", "last_name": "Lovelace", "email": "ada@example.com", "phone": "+61 400 000 001" }, "properties": { "first_name": { "type": [ "string", "null" ], "description": "Nullable first name.", "example": "Ada" }, "last_name": { "type": [ "string", "null" ], "description": "Nullable last name.", "example": "Lovelace" }, "email": { "type": [ "string", "null" ], "description": "Nullable RFC email address.", "example": "ada@example.com" }, "phone": { "type": [ "string", "null" ], "description": "Nullable phone number.", "example": "+61 400 000 001" } }, "additionalProperties": false }, "billing_address": { "type": [ "object", "null" ], "description": "Nullable billing address snapshot.", "example": { "first_name": "Ada", "last_name": "Lovelace", "address_1": "1 Example Street", "city": "Adelaide", "province": "SA", "postcode": "5000", "country": "AU" }, "properties": { "first_name": { "type": [ "string", "null" ], "description": "Nullable first name.", "example": "Ada" }, "last_name": { "type": [ "string", "null" ], "description": "Nullable last name.", "example": "Lovelace" }, "company": { "type": [ "string", "null" ], "description": "Nullable company.", "example": "Analytical Engines Ltd" }, "address_1": { "type": [ "string", "null" ], "description": "Nullable first address line.", "example": "1 Example Street" }, "address_2": { "type": [ "string", "null" ], "description": "Nullable second address line.", "example": "Suite 2" }, "city": { "type": [ "string", "null" ], "description": "Nullable city.", "example": "Adelaide" }, "province": { "type": [ "string", "null" ], "description": "Nullable state or province.", "example": "SA" }, "postcode": { "type": [ "string", "null" ], "description": "Nullable postcode.", "example": "5000" }, "country": { "type": [ "string", "null" ], "description": "Nullable uppercase ISO 3166-1 alpha-2 country code.", "example": "AU" }, "email": { "type": [ "string", "null" ], "description": "Nullable address contact email.", "example": "ada@example.com" }, "phone": { "type": [ "string", "null" ], "description": "Nullable address contact phone.", "example": "+61 400 000 001" } }, "additionalProperties": false }, "shipping_address": { "type": [ "object", "null" ], "description": "Nullable shipping address snapshot.", "example": { "first_name": "Ada", "last_name": "Lovelace", "address_1": "1 Example Street", "city": "Adelaide", "province": "SA", "postcode": "5000", "country": "AU" }, "properties": { "first_name": { "type": [ "string", "null" ], "description": "Nullable first name.", "example": "Ada" }, "last_name": { "type": [ "string", "null" ], "description": "Nullable last name.", "example": "Lovelace" }, "company": { "type": [ "string", "null" ], "description": "Nullable company.", "example": "Analytical Engines Ltd" }, "address_1": { "type": [ "string", "null" ], "description": "Nullable first address line.", "example": "1 Example Street" }, "address_2": { "type": [ "string", "null" ], "description": "Nullable second address line.", "example": "Suite 2" }, "city": { "type": [ "string", "null" ], "description": "Nullable city.", "example": "Adelaide" }, "province": { "type": [ "string", "null" ], "description": "Nullable state or province.", "example": "SA" }, "postcode": { "type": [ "string", "null" ], "description": "Nullable postcode.", "example": "5000" }, "country": { "type": [ "string", "null" ], "description": "Nullable uppercase ISO 3166-1 alpha-2 country code.", "example": "AU" }, "email": { "type": [ "string", "null" ], "description": "Nullable address contact email.", "example": "ada@example.com" }, "phone": { "type": [ "string", "null" ], "description": "Nullable address contact phone.", "example": "+61 400 000 001" } }, "additionalProperties": false }, "line_items": { "type": "array", "description": "One to 100 unique modern products and quantities.", "example": [ { "product_id": 731, "quantity": 2 } ], "items": { "type": "object", "properties": { "product_id": { "type": "integer", "description": "Product id returned by the product write operation.", "example": 731 }, "quantity": { "type": "integer", "description": "Quantity from 1 to 10,000.", "example": 2 } }, "required": [ "product_id", "quantity" ], "additionalProperties": false } } }, "required": [ "integration_id", "store_order_id", "store_order_number", "total_amount", "currency", "line_items" ], "additionalProperties": false } } } } } }, "/api/v3/orders/export": { "parameters": [], "post": { "summary": "Queue an order CSV export\n\nQueue the established CSV export for an inclusive UTC creation-date\nrange. The email recipient is the authenticated Store's contact email\nand cannot be overridden. The range may contain at most 366 days and\n1,000 orders, and its estimated CSV size must stay within the export\nceiling; choose a shorter range when either bound is exceeded. Unlike the\nv3 read projection, the frozen CSV contract still includes cached legacy\norder rows. Requires `orders:write`. Supply an `Idempotency-Key`;\nreplaying the same request does not queue or email a second export.", "operationId": "queueAnOrderCSVExportQueueTheEstablishedCSVExportForAnInclusiveUTCCreationDateRangeTheEmailRecipientIsTheAuthenticatedStoresContactEmailAndCannotBeOverriddenTheRangeMayContainAtMost366DaysAnd1000OrdersAndItsEstimatedCSVSizeMustStayWithinTheExportCeilingChooseAShorterRangeWhenEitherBoundIsExceededUnlikeTheV3ReadProjectionTheFrozenCSVContractStillIncludesCachedLegacyOrderRowsRequiresorderswriteSupplyAnIdempotencyKeyReplayingTheSameRequestDoesNotQueueOrEmailASecondExport", "description": "", "parameters": [ { "in": "header", "name": "Idempotency-Key", "description": "", "example": "11da2e11-24ca-41ae-99cc-f88c87d2a645", "schema": { "type": "string" } } ], "responses": { "202": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "data": { "object": "order_export", "status": "queued", "recipient_email": "orders@example.com", "created_from": "2026-07-01", "created_to": "2026-07-19" }, "links": { "self": "https://web.signcustomiser.com/api/v3/orders/export", "documentation": "https://www.signcustomiser.com/help/api/" }, "meta": { "api_version": "v3", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } }, "properties": { "data": { "type": "object", "properties": { "object": { "type": "string", "example": "order_export" }, "status": { "type": "string", "example": "queued" }, "recipient_email": { "type": "string", "example": "orders@example.com" }, "created_from": { "type": "string", "example": "2026-07-01" }, "created_to": { "type": "string", "example": "2026-07-19" } } }, "links": { "type": "object", "properties": { "self": { "type": "string", "example": "https://web.signcustomiser.com/api/v3/orders/export" }, "documentation": { "type": "string", "example": "https://www.signcustomiser.com/help/api/" } } }, "meta": { "type": "object", "properties": { "api_version": { "type": "string", "example": "v3" }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } } } }, "400": { "description": "Malformed JSON", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/malformed_json", "title": "Malformed JSON", "status": 400, "code": "malformed_json", "detail": "The request body is not valid JSON.", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/malformed_json" }, "title": { "type": "string", "example": "Malformed JSON" }, "status": { "type": "integer", "example": 400 }, "code": { "type": "string", "example": "malformed_json" }, "detail": { "type": "string", "example": "The request body is not valid JSON." }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/missing_api_key", "title": "Missing API key", "status": 401, "code": "missing_api_key", "detail": "Provide a store API key as a bearer token.", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/missing_api_key" }, "title": { "type": "string", "example": "Missing API key" }, "status": { "type": "integer", "example": 401 }, "code": { "type": "string", "example": "missing_api_key" }, "detail": { "type": "string", "example": "Provide a store API key as a bearer token." }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/insufficient_scope", "title": "Insufficient scope", "status": 403, "code": "insufficient_scope", "detail": "This operation requires the orders:write scope.", "required_scopes": [ "orders:write" ], "granted_scopes": [ "orders:read" ], "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/insufficient_scope" }, "title": { "type": "string", "example": "Insufficient scope" }, "status": { "type": "integer", "example": 403 }, "code": { "type": "string", "example": "insufficient_scope" }, "detail": { "type": "string", "example": "This operation requires the orders:write scope." }, "required_scopes": { "type": "array", "example": [ "orders:write" ], "items": { "type": "string" } }, "granted_scopes": { "type": "array", "example": [ "orders:read" ], "items": { "type": "string" } }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } }, "409": { "description": "Idempotency conflict", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/idempotency_key_conflict", "title": "Idempotency key conflict", "status": 409, "code": "idempotency_key_conflict", "detail": "This Idempotency-Key was already used for a different request body on this operation.", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/idempotency_key_conflict" }, "title": { "type": "string", "example": "Idempotency key conflict" }, "status": { "type": "integer", "example": 409 }, "code": { "type": "string", "example": "idempotency_key_conflict" }, "detail": { "type": "string", "example": "This Idempotency-Key was already used for a different request body on this operation." }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } }, "422": { "description": "Invalid or oversized export", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/export_too_large", "title": "Order export too large", "status": 422, "code": "export_too_large", "detail": "The selected range exceeds an order or estimated CSV size limit. Choose a shorter range and try again.", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/export_too_large" }, "title": { "type": "string", "example": "Order export too large" }, "status": { "type": "integer", "example": 422 }, "code": { "type": "string", "example": "export_too_large" }, "detail": { "type": "string", "example": "The selected range exceeds an order or estimated CSV size limit. Choose a shorter range and try again." }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } }, "429": { "description": "Export rate limited", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/rate_limited", "title": "Too many requests", "status": 429, "code": "rate_limited", "detail": "You have exceeded the request limit for this API key.", "retry_after": 600, "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/rate_limited" }, "title": { "type": "string", "example": "Too many requests" }, "status": { "type": "integer", "example": 429 }, "code": { "type": "string", "example": "rate_limited" }, "detail": { "type": "string", "example": "You have exceeded the request limit for this API key." }, "retry_after": { "type": "integer", "example": 600 }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } } }, "tags": [ "Orders" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "created_from": { "type": "string", "description": "First included UTC date, in YYYY-MM-DD format.", "example": "2026-07-01" }, "created_to": { "type": "string", "description": "Last included UTC date, in YYYY-MM-DD format.", "example": "2026-07-19" } }, "required": [ "created_from", "created_to" ] } } } } } }, "/api/v3/orders/{order_id}": { "parameters": [ { "in": "path", "name": "order_id", "description": "The order id returned by the list operation.", "example": "123", "required": true, "schema": { "type": "integer" } } ], "get": { "summary": "Show an order\n\nReturn one Store-scoped order with customer and address snapshots plus\nits modern line items. Cached legacy products are never serialised; an\nolder cached-only order therefore returns an empty `line_items` array.\nMoney uses integer minor units with an explicit currency, dimensions are\ncentimetres, and timestamps are ISO 8601 UTC. Requires `orders:read` and\nis safe to retry.", "operationId": "showAnOrderReturnOneStoreScopedOrderWithCustomerAndAddressSnapshotsPlusItsModernLineItemsCachedLegacyProductsAreNeverSerialisedAnOlderCachedOnlyOrderThereforeReturnsAnEmptylineItemsArrayMoneyUsesIntegerMinorUnitsWithAnExplicitCurrencyDimensionsAreCentimetresAndTimestampsAreISO8601UTCRequiresordersreadAndIsSafeToRetry", "description": "", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "data": { "object": "order", "id": 123, "store_order_id": "gid://shopify/Order/1001", "store_order_number": "#1001", "status": "received", "status_display_name": "Received", "total_amount": 31900, "currency": "AUD", "shipping_method": "Express", "customer": { "first_name": "Ada", "last_name": "Lovelace", "email": "ada@example.com", "phone": "+61 400 000 001" }, "billing_address": { "first_name": "Ada", "last_name": "Lovelace", "company": null, "address_1": "1 Example Street", "address_2": null, "city": "Adelaide", "province": "SA", "postcode": "5000", "country": "AU", "email": "ada@example.com", "phone": "+61 400 000 001" }, "shipping_address": { "first_name": "Ada", "last_name": "Lovelace", "company": null, "address_1": "1 Example Street", "address_2": null, "city": "Adelaide", "province": "SA", "postcode": "5000", "country": "AU", "email": "ada@example.com", "phone": "+61 400 000 001" }, "line_items": [ { "object": "order_line_item", "id": 77, "store_product_id": "gid://shopify/Product/77", "customiser_id": 42, "title": "Custom neon sign", "quantity": 2, "unit_price_amount": 15950, "currency": "AUD", "preview_image_url": "https://cdn.example.com/sign.png", "width_cm": 80.5, "height_cm": 30.25, "length_cm": 2 } ], "created_at": "2026-07-18T02:15:00Z", "updated_at": "2026-07-18T02:16:00Z" }, "links": { "self": "https://web.signcustomiser.com/api/v3/orders/123", "documentation": "https://www.signcustomiser.com/help/api/" }, "meta": { "api_version": "v3", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } }, "properties": { "data": { "type": "object", "properties": { "object": { "type": "string", "example": "order" }, "id": { "type": "integer", "example": 123 }, "store_order_id": { "type": "string", "example": "gid://shopify/Order/1001" }, "store_order_number": { "type": "string", "example": "#1001" }, "status": { "type": "string", "example": "received", "description": "The order record status. This set is expected to grow; tolerate unknown values.", "enum": [ "received" ] }, "status_display_name": { "type": "string", "example": "Received" }, "total_amount": { "type": "integer", "example": 31900 }, "currency": { "type": [ "string", "null" ], "example": "AUD", "description": "The ISO 4217 currency captured for the order, or null when the stored order has no valid currency code." }, "shipping_method": { "type": [ "string", "null" ], "example": "Express" }, "customer": { "type": [ "object", "null" ], "properties": { "first_name": { "type": [ "string", "null" ], "example": "Ada" }, "last_name": { "type": [ "string", "null" ], "example": "Lovelace" }, "email": { "type": [ "string", "null" ], "example": "ada@example.com" }, "phone": { "type": [ "string", "null" ], "example": "+61 400 000 001" } }, "required": [ "first_name", "last_name", "email", "phone" ] }, "billing_address": { "type": [ "object", "null" ], "properties": { "first_name": { "type": [ "string", "null" ], "example": "Ada" }, "last_name": { "type": [ "string", "null" ], "example": "Lovelace" }, "company": { "type": [ "string", "null" ], "example": null }, "address_1": { "type": [ "string", "null" ], "example": "1 Example Street" }, "address_2": { "type": [ "string", "null" ], "example": null }, "city": { "type": [ "string", "null" ], "example": "Adelaide" }, "province": { "type": [ "string", "null" ], "example": "SA" }, "postcode": { "type": [ "string", "null" ], "example": "5000" }, "country": { "type": [ "string", "null" ], "example": "AU" }, "email": { "type": [ "string", "null" ], "example": "ada@example.com" }, "phone": { "type": [ "string", "null" ], "example": "+61 400 000 001" } }, "required": [ "first_name", "last_name", "company", "address_1", "address_2", "city", "province", "postcode", "country", "email", "phone" ] }, "shipping_address": { "type": [ "object", "null" ], "properties": { "first_name": { "type": [ "string", "null" ], "example": "Ada" }, "last_name": { "type": [ "string", "null" ], "example": "Lovelace" }, "company": { "type": [ "string", "null" ], "example": null }, "address_1": { "type": [ "string", "null" ], "example": "1 Example Street" }, "address_2": { "type": [ "string", "null" ], "example": null }, "city": { "type": [ "string", "null" ], "example": "Adelaide" }, "province": { "type": [ "string", "null" ], "example": "SA" }, "postcode": { "type": [ "string", "null" ], "example": "5000" }, "country": { "type": [ "string", "null" ], "example": "AU" }, "email": { "type": [ "string", "null" ], "example": "ada@example.com" }, "phone": { "type": [ "string", "null" ], "example": "+61 400 000 001" } }, "required": [ "first_name", "last_name", "company", "address_1", "address_2", "city", "province", "postcode", "country", "email", "phone" ] }, "line_items": { "type": "array", "example": [ { "object": "order_line_item", "id": 77, "store_product_id": "gid://shopify/Product/77", "customiser_id": 42, "title": "Custom neon sign", "quantity": 2, "unit_price_amount": 15950, "currency": "AUD", "preview_image_url": "https://cdn.example.com/sign.png", "width_cm": 80.5, "height_cm": 30.25, "length_cm": 2 } ], "items": { "type": "object", "properties": { "object": { "type": "string", "example": "order_line_item" }, "id": { "type": "integer", "example": 77 }, "store_product_id": { "type": [ "string", "null" ], "example": "gid://shopify/Product/77" }, "customiser_id": { "type": "integer", "example": 42 }, "title": { "type": [ "string", "null" ], "example": "Custom neon sign" }, "quantity": { "type": "integer", "example": 2 }, "unit_price_amount": { "type": "integer", "example": 15950 }, "currency": { "type": [ "string", "null" ], "example": "AUD" }, "preview_image_url": { "type": [ "string", "null" ], "example": "https://cdn.example.com/sign.png" }, "width_cm": { "type": [ "number", "null" ], "example": 80.5 }, "height_cm": { "type": [ "number", "null" ], "example": 30.25 }, "length_cm": { "type": [ "number", "null" ], "example": 2 } }, "required": [ "object", "id", "store_product_id", "customiser_id", "title", "quantity", "unit_price_amount", "currency", "preview_image_url", "width_cm", "height_cm", "length_cm" ] } }, "created_at": { "type": [ "string", "null" ], "example": "2026-07-18T02:15:00Z" }, "updated_at": { "type": [ "string", "null" ], "example": "2026-07-18T02:16:00Z" } }, "required": [ "object", "id", "store_order_id", "store_order_number", "status", "status_display_name", "total_amount", "currency", "shipping_method", "customer", "billing_address", "shipping_address", "line_items", "created_at", "updated_at" ] }, "links": { "type": "object", "properties": { "self": { "type": "string", "example": "https://web.signcustomiser.com/api/v3/orders/123" }, "documentation": { "type": "string", "example": "https://www.signcustomiser.com/help/api/" } }, "required": [ "self", "documentation" ] }, "meta": { "type": "object", "properties": { "api_version": { "type": "string", "example": "v3" }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } }, "required": [ "api_version", "request_id" ] } }, "required": [ "data", "links", "meta" ] } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/missing_api_key", "title": "Missing API key", "status": 401, "code": "missing_api_key", "detail": "Provide a store API key as a bearer token.", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/missing_api_key" }, "title": { "type": "string", "example": "Missing API key" }, "status": { "type": "integer", "example": 401 }, "code": { "type": "string", "example": "missing_api_key" }, "detail": { "type": "string", "example": "Provide a store API key as a bearer token." }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/insufficient_scope", "title": "Insufficient scope", "status": 403, "code": "insufficient_scope", "detail": "This operation requires the orders:read scope.", "required_scopes": [ "orders:read" ], "granted_scopes": [], "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/insufficient_scope" }, "title": { "type": "string", "example": "Insufficient scope" }, "status": { "type": "integer", "example": 403 }, "code": { "type": "string", "example": "insufficient_scope" }, "detail": { "type": "string", "example": "This operation requires the orders:read scope." }, "required_scopes": { "type": "array", "example": [ "orders:read" ], "items": { "type": "string" } }, "granted_scopes": { "type": "array", "example": [] }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } }, "404": { "description": "Unknown or foreign order", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/resource_not_found", "title": "Resource not found", "status": 404, "code": "resource_not_found", "detail": "The requested resource does not exist or does not belong to the authenticated store.", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/resource_not_found" }, "title": { "type": "string", "example": "Resource not found" }, "status": { "type": "integer", "example": 404 }, "code": { "type": "string", "example": "resource_not_found" }, "detail": { "type": "string", "example": "The requested resource does not exist or does not belong to the authenticated store." }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } }, "422": { "description": "Unknown query parameter", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/unknown_parameter", "title": "Unknown query parameter", "status": 422, "code": "unknown_parameter", "detail": "This endpoint accepts no query parameters.", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/unknown_parameter" }, "title": { "type": "string", "example": "Unknown query parameter" }, "status": { "type": "integer", "example": 422 }, "code": { "type": "string", "example": "unknown_parameter" }, "detail": { "type": "string", "example": "This endpoint accepts no query parameters." }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/rate_limited", "title": "Too many requests", "status": 429, "code": "rate_limited", "detail": "You have exceeded the request limit for this API key.", "retry_after": 60, "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/rate_limited" }, "title": { "type": "string", "example": "Too many requests" }, "status": { "type": "integer", "example": 429 }, "code": { "type": "string", "example": "rate_limited" }, "detail": { "type": "string", "example": "You have exceeded the request limit for this API key." }, "retry_after": { "type": "integer", "example": 60 }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } } }, "tags": [ "Orders" ] } }, "/api/v3/orders/{order_id}/resend": { "parameters": [ { "in": "path", "name": "order_id", "description": "The order id returned by the list operation.", "example": "123", "required": true, "schema": { "type": "integer" } } ], "post": { "summary": "Queue an order email resend\n\nQueue the established order email again for the manufacturer recipient\nconfigured by the Store. The operation accepts no request fields: a\ncaller cannot choose or override any recipient. Requires `orders:write`.\nSupply a unique `Idempotency-Key` for each logical resend; retrying the\nsame body and key replays the 202 response without queuing another email.\nDistinct attempts are limited to two per API key per minute.", "operationId": "queueAnOrderEmailResendQueueTheEstablishedOrderEmailAgainForTheManufacturerRecipientConfiguredByTheStoreTheOperationAcceptsNoRequestFieldsACallerCannotChooseOrOverrideAnyRecipientRequiresorderswriteSupplyAUniqueIdempotencyKeyForEachLogicalResendRetryingTheSameBodyAndKeyReplaysThe202ResponseWithoutQueuingAnotherEmailDistinctAttemptsAreLimitedToTwoPerAPIKeyPerMinute", "description": "", "parameters": [ { "in": "header", "name": "Idempotency-Key", "description": "", "example": "8cde76ce-10e9-4fc2-9d31-93af24277e9f", "schema": { "type": "string" } } ], "responses": { "202": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "data": { "object": "order_email_resend", "order_id": 123, "status": "queued" }, "links": { "self": "https://web.signcustomiser.com/api/v3/orders/123/resend", "documentation": "https://www.signcustomiser.com/help/api/" }, "meta": { "api_version": "v3", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } }, "properties": { "data": { "type": "object", "properties": { "object": { "type": "string", "example": "order_email_resend" }, "order_id": { "type": "integer", "example": 123 }, "status": { "type": "string", "example": "queued" } } }, "links": { "type": "object", "properties": { "self": { "type": "string", "example": "https://web.signcustomiser.com/api/v3/orders/123/resend" }, "documentation": { "type": "string", "example": "https://www.signcustomiser.com/help/api/" } } }, "meta": { "type": "object", "properties": { "api_version": { "type": "string", "example": "v3" }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } } } }, "400": { "description": "Malformed JSON", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/invalid_json", "title": "Invalid JSON", "status": 400, "code": "invalid_json", "detail": "The request body must be valid JSON.", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/invalid_json" }, "title": { "type": "string", "example": "Invalid JSON" }, "status": { "type": "integer", "example": 400 }, "code": { "type": "string", "example": "invalid_json" }, "detail": { "type": "string", "example": "The request body must be valid JSON." }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/missing_api_key", "title": "Missing API key", "status": 401, "code": "missing_api_key", "detail": "Provide a store API key as a bearer token.", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/missing_api_key" }, "title": { "type": "string", "example": "Missing API key" }, "status": { "type": "integer", "example": 401 }, "code": { "type": "string", "example": "missing_api_key" }, "detail": { "type": "string", "example": "Provide a store API key as a bearer token." }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/insufficient_scope", "title": "Insufficient scope", "status": 403, "code": "insufficient_scope", "detail": "This operation requires the orders:write scope.", "required_scopes": [ "orders:write" ], "granted_scopes": [ "orders:read" ], "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/insufficient_scope" }, "title": { "type": "string", "example": "Insufficient scope" }, "status": { "type": "integer", "example": 403 }, "code": { "type": "string", "example": "insufficient_scope" }, "detail": { "type": "string", "example": "This operation requires the orders:write scope." }, "required_scopes": { "type": "array", "example": [ "orders:write" ], "items": { "type": "string" } }, "granted_scopes": { "type": "array", "example": [ "orders:read" ], "items": { "type": "string" } }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } }, "404": { "description": "Unknown or foreign order", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/resource_not_found", "title": "Resource not found", "status": 404, "code": "resource_not_found", "detail": "The requested resource does not exist or does not belong to the authenticated store.", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/resource_not_found" }, "title": { "type": "string", "example": "Resource not found" }, "status": { "type": "integer", "example": 404 }, "code": { "type": "string", "example": "resource_not_found" }, "detail": { "type": "string", "example": "The requested resource does not exist or does not belong to the authenticated store." }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } }, "409": { "description": "Idempotency conflict", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/idempotency_key_conflict", "title": "Idempotency key conflict", "status": 409, "code": "idempotency_key_conflict", "detail": "This Idempotency-Key was already used for a different request body on this operation.", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/idempotency_key_conflict" }, "title": { "type": "string", "example": "Idempotency key conflict" }, "status": { "type": "integer", "example": 409 }, "code": { "type": "string", "example": "idempotency_key_conflict" }, "detail": { "type": "string", "example": "This Idempotency-Key was already used for a different request body on this operation." }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } }, "422": { "description": "Unknown request field", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/unknown_field", "title": "Unknown request field", "status": 422, "code": "unknown_field", "detail": "This operation accepts no request fields.", "errors": [ { "parameter": "recipient", "code": "unknown_field", "detail": "The request field recipient is not supported by this endpoint." } ], "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/unknown_field" }, "title": { "type": "string", "example": "Unknown request field" }, "status": { "type": "integer", "example": 422 }, "code": { "type": "string", "example": "unknown_field" }, "detail": { "type": "string", "example": "This operation accepts no request fields." }, "errors": { "type": "array", "example": [ { "parameter": "recipient", "code": "unknown_field", "detail": "The request field recipient is not supported by this endpoint." } ], "items": { "type": "object", "properties": { "parameter": { "type": "string", "example": "recipient" }, "code": { "type": "string", "example": "unknown_field" }, "detail": { "type": "string", "example": "The request field recipient is not supported by this endpoint." } } } }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } }, "429": { "description": "Resend rate limited", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/rate_limited", "title": "Too many requests", "status": 429, "code": "rate_limited", "detail": "You have exceeded the request limit for this API key.", "retry_after": 60, "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/rate_limited" }, "title": { "type": "string", "example": "Too many requests" }, "status": { "type": "integer", "example": 429 }, "code": { "type": "string", "example": "rate_limited" }, "detail": { "type": "string", "example": "You have exceeded the request limit for this API key." }, "retry_after": { "type": "integer", "example": 60 }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } } }, "tags": [ "Orders" ] } }, "/api/v2/customisers/{customiser}/pricing": { "parameters": [ { "in": "path", "name": "customiser", "description": "The customiser ID.", "example": "1", "required": true, "schema": { "type": "integer" } } ], "get": { "summary": "Get customiser pricing\n\nRetrieve all pricing configuration for a customiser.\n\nThe `pricing_model` value is the internal enum name for the customiser's\npricing model. The current product names are: `FIXED_WIDTH` is the Simple\nLetter Model, `MATERIAL_LENGTH` is the Advanced Letter Model, and\n`FRAME_FIT` is the Frame Fit Model. `FIXED_HEIGHT` is the deprecated\nlegacy Fixed Height Model and is rejected with a 422 — the supported\nfixed-height sizing path is the Simple Letter Model (`FIXED_WIDTH`) with a\n`HEIGHT` height strategy on its sizes.\n\nError responses always include a human-readable `message` field.\nValidation failures also include an `errors` object keyed by field path.", "operationId": "getCustomiserPricingRetrieveAllPricingConfigurationForACustomiserThepricingModelValueIsTheInternalEnumNameForTheCustomisersPricingModelTheCurrentProductNamesAreFIXEDWIDTHIsTheSimpleLetterModelMATERIALLENGTHIsTheAdvancedLetterModelAndFRAMEFITIsTheFrameFitModelFIXEDHEIGHTIsTheDeprecatedLegacyFixedHeightModelAndIsRejectedWithA422TheSupportedFixedHeightSizingPathIsTheSimpleLetterModelFIXEDWIDTHWithAHEIGHTHeightStrategyOnItsSizesErrorResponsesAlwaysIncludeAHumanReadablemessageFieldValidationFailuresAlsoIncludeAnerrorsObjectKeyedByFieldPath", "description": "", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "pricing": { "customiser_id": 1, "pricing_model": "FIXED_WIDTH", "value_units": { "base_price": "minor_currency_units", "letter_price": "minor_currency_units", "price_per_letter": "minor_currency_units", "price_per_cm": "currency_units_per_cm", "price_per_sq_cm": "currency_units_per_sq_cm_or_weight_unit" }, "sizes": [], "base_pricing": { "mode": "included_in_price_lists", "rows": [] }, "price_lists": [] } }, "properties": { "pricing": { "type": "object", "properties": { "customiser_id": { "type": "integer", "example": 1 }, "pricing_model": { "type": "string", "example": "FIXED_WIDTH" }, "value_units": { "type": "object", "properties": { "base_price": { "type": "string", "example": "minor_currency_units" }, "letter_price": { "type": "string", "example": "minor_currency_units" }, "price_per_letter": { "type": "string", "example": "minor_currency_units" }, "price_per_cm": { "type": "string", "example": "currency_units_per_cm" }, "price_per_sq_cm": { "type": "string", "example": "currency_units_per_sq_cm_or_weight_unit" } } }, "sizes": { "type": "array", "example": [] }, "base_pricing": { "type": "object", "properties": { "mode": { "type": "string", "example": "included_in_price_lists" }, "rows": { "type": "array", "example": [] } } }, "price_lists": { "type": "array", "example": [] } } } } } } } }, "401": { "description": "Missing or invalid API token", "content": { "application/json": { "schema": { "type": "object", "example": { "message": "" }, "properties": { "message": { "type": "string", "example": "" } } } } } }, "403": { "description": "Customiser belongs to another store", "content": { "application/json": { "schema": { "type": "object", "example": { "message": "This action is unauthorized." }, "properties": { "message": { "type": "string", "example": "This action is unauthorized." } } } } } }, "404": { "description": "Unknown customiser ID", "content": { "application/json": { "schema": { "type": "object", "example": { "message": "No query results for model [App\\Models\\Customiser] 1" }, "properties": { "message": { "type": "string", "example": "No query results for model [App\\Models\\Customiser] 1" } } } } } }, "422": { "description": "Deprecated FIXED_HEIGHT customiser", "content": { "application/json": { "schema": { "type": "object", "example": { "message": "FIXED_HEIGHT pricing is not supported by this endpoint." }, "properties": { "message": { "type": "string", "example": "FIXED_HEIGHT pricing is not supported by this endpoint." } } } } } } }, "tags": [ "Pricing" ] }, "put": { "summary": "Update customiser pricing\n\nReplace all pricing configuration for a customiser.\n\nThis is a full replacement: sizes and price-list rows omitted from the\npayload are deleted. A replacement that would delete size or price-list\nrecords still referenced by fonts or settings is rejected with a 409 and\nno changes are applied.\n\nThe `pricing_model` value is the internal enum name for the customiser's\npricing model. The current product names are: `FIXED_WIDTH` is the Simple\nLetter Model, `MATERIAL_LENGTH` is the Advanced Letter Model, and\n`FRAME_FIT` is the Frame Fit Model. This endpoint cannot switch a\ncustomiser to a different pricing model, and the deprecated `FIXED_HEIGHT`\nlegacy model is rejected with a 422.\n\nError responses always include a human-readable `message` field.\nValidation failures also include an `errors` object keyed by field path.", "operationId": "updateCustomiserPricingReplaceAllPricingConfigurationForACustomiserThisIsAFullReplacementSizesAndPriceListRowsOmittedFromThePayloadAreDeletedAReplacementThatWouldDeleteSizeOrPriceListRecordsStillReferencedByFontsOrSettingsIsRejectedWithA409AndNoChangesAreAppliedThepricingModelValueIsTheInternalEnumNameForTheCustomisersPricingModelTheCurrentProductNamesAreFIXEDWIDTHIsTheSimpleLetterModelMATERIALLENGTHIsTheAdvancedLetterModelAndFRAMEFITIsTheFrameFitModelThisEndpointCannotSwitchACustomiserToADifferentPricingModelAndTheDeprecatedFIXEDHEIGHTLegacyModelIsRejectedWithA422ErrorResponsesAlwaysIncludeAHumanReadablemessageFieldValidationFailuresAlsoIncludeAnerrorsObjectKeyedByFieldPath", "description": "", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "pricing": { "customiser_id": 1, "pricing_model": "FIXED_WIDTH", "value_units": { "base_price": "minor_currency_units", "letter_price": "minor_currency_units", "price_per_letter": "minor_currency_units", "price_per_cm": "currency_units_per_cm", "price_per_sq_cm": "currency_units_per_sq_cm_or_weight_unit" }, "sizes": [], "base_pricing": { "mode": "included_in_price_lists", "rows": [] }, "price_lists": [] } }, "properties": { "pricing": { "type": "object", "properties": { "customiser_id": { "type": "integer", "example": 1 }, "pricing_model": { "type": "string", "example": "FIXED_WIDTH" }, "value_units": { "type": "object", "properties": { "base_price": { "type": "string", "example": "minor_currency_units" }, "letter_price": { "type": "string", "example": "minor_currency_units" }, "price_per_letter": { "type": "string", "example": "minor_currency_units" }, "price_per_cm": { "type": "string", "example": "currency_units_per_cm" }, "price_per_sq_cm": { "type": "string", "example": "currency_units_per_sq_cm_or_weight_unit" } } }, "sizes": { "type": "array", "example": [] }, "base_pricing": { "type": "object", "properties": { "mode": { "type": "string", "example": "included_in_price_lists" }, "rows": { "type": "array", "example": [] } } }, "price_lists": { "type": "array", "example": [] } } } } } } } }, "401": { "description": "Missing or invalid API token", "content": { "application/json": { "schema": { "type": "object", "example": { "message": "" }, "properties": { "message": { "type": "string", "example": "" } } } } } }, "403": { "description": "Customiser belongs to another store", "content": { "application/json": { "schema": { "type": "object", "example": { "message": "This action is unauthorized." }, "properties": { "message": { "type": "string", "example": "This action is unauthorized." } } } } } }, "404": { "description": "Unknown customiser ID", "content": { "application/json": { "schema": { "type": "object", "example": { "message": "No query results for model [App\\Models\\Customiser] 1" }, "properties": { "message": { "type": "string", "example": "No query results for model [App\\Models\\Customiser] 1" } } } } } }, "409": { "description": "Replacement would delete referenced records", "content": { "application/json": { "schema": { "type": "object", "example": { "message": "Cannot delete sizes that are still referenced by fonts." }, "properties": { "message": { "type": "string", "example": "Cannot delete sizes that are still referenced by fonts." } } } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "type": "object", "example": { "message": "The pricing.sizes field must be present.", "errors": { "pricing.sizes": [ "The pricing.sizes field must be present." ] } }, "properties": { "message": { "type": "string", "example": "The pricing.sizes field must be present." }, "errors": { "type": "object", "properties": { "pricing.sizes": { "type": "array", "example": [ "The pricing.sizes field must be present." ], "items": { "type": "string" } } } } } } } } } }, "tags": [ "Pricing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pricing": { "type": "object", "description": "The replacement pricing configuration.", "example": [], "properties": { "pricing_model": { "type": [ "string", "null" ], "description": "Optional guard. When provided it must match the customiser's current pricing model: FIXED_WIDTH (Simple Letter Model), MATERIAL_LENGTH (Advanced Letter Model), or FRAME_FIT (Frame Fit Model). This endpoint cannot switch a customiser to a different model; the deprecated FIXED_HEIGHT legacy model is rejected.", "example": "FIXED_WIDTH" }, "sizes": { "type": "array", "description": "Size records.", "example": [ [] ], "items": { "type": "object", "properties": { "size_id": { "type": [ "integer", "null" ], "description": "", "example": 1 }, "client_key": { "type": [ "string", "null" ], "description": "Must be at least 1 character.", "example": "small" }, "name": { "type": "string", "description": "", "example": "Small" }, "description": { "type": [ "string", "null" ], "description": "", "example": "Up to 50cm wide" }, "sort_order": { "type": [ "integer", "null" ], "description": "", "example": 1 }, "char_limit": { "type": [ "integer", "null" ], "description": "Must be at least 0.", "example": 20 }, "line_limit": { "type": [ "integer", "null" ], "description": "Must be at least 1. Must not be greater than 10.", "example": 3 }, "min_char": { "type": [ "integer", "null" ], "description": "Must be at least 0.", "example": 1 }, "width_cm": { "type": [ "number", "null" ], "description": "Must be at least 0.", "example": 50 }, "height_cm": { "type": [ "number", "null" ], "description": "Must be at least 0.", "example": null }, "line_height_cm": { "type": [ "number", "null" ], "description": "Must be at least 0.", "example": 12 }, "height_strategy": { "type": [ "string", "null" ], "description": "", "example": "WIDTH", "enum": [ "WIDTH", "HEIGHT", "DYNAMIC", "FIXED", null ] }, "height_measurement_mode": { "type": [ "string", "null" ], "description": "", "example": "LINE_HEIGHT", "enum": [ "LINE_HEIGHT", "LETTER_HEIGHT", null ] }, "width_multiplier": { "type": [ "number", "null" ], "description": "", "example": null }, "length_cm": { "type": [ "number", "null" ], "description": "Must be at least 0.", "example": null } }, "required": [ "name" ] } }, "base_pricing": { "type": "object", "description": "Base pricing settings.", "example": [], "properties": { "mode": { "type": "string", "description": "", "example": "included_in_price_lists" }, "rows": { "type": "array", "description": "", "example": [ [] ], "items": { "type": "object", "properties": { "size_id": { "type": [ "integer", "null" ], "description": "", "example": 1 }, "size_key": { "type": [ "string", "null" ], "description": "", "example": null }, "base_price": { "type": [ "object", "null" ], "description": "Fixed-width base price by line. For material length and frame fit this field is a number.", "example": { "line_1": 1000, "line_2": 1200, "line_3": 1400 }, "properties": {} }, "width_limit_cm": { "type": [ "number", "null" ], "description": "Must be at least 0.", "example": 100 }, "height_limit_cm": { "type": [ "number", "null" ], "description": "Must be at least 0.", "example": 50 }, "length_limit_cm": { "type": [ "number", "null" ], "description": "Must be at least 0.", "example": null } } } } }, "required": [ "mode", "rows" ] }, "price_lists": { "type": "array", "description": "Price lists.", "example": [ [] ], "items": { "type": "object", "properties": { "pricing_id": { "type": [ "integer", "null" ], "description": "", "example": 10 }, "name": { "type": "string", "description": "", "example": "Standard" }, "letter_pricing_method": { "type": [ "string", "null" ], "description": "", "example": "material_length", "enum": [ "material_length", "fixed_letter", null ] }, "shipping": { "type": [ "object", "null" ], "description": "", "example": null, "properties": { "calculation": { "type": [ "string", "null" ], "description": "", "example": "physical", "enum": [ "physical", "volumetric", null ] }, "volumetric_divisor": { "type": [ "number", "null" ], "description": "", "example": null }, "add_weight_to_product": { "type": [ "boolean", "null" ], "description": "", "example": false } } }, "rows": { "type": "array", "description": "", "example": [ [] ], "items": { "type": "object", "properties": { "size_id": { "type": [ "integer", "null" ], "description": "", "example": 1 }, "size_key": { "type": [ "string", "null" ], "description": "", "example": null }, "base_price": { "type": [ "object", "null" ], "description": "Fixed-width base price by line. For material length and frame fit this field is a number.", "example": { "line_1": 1000, "line_2": 1200, "line_3": 1400 }, "properties": {} }, "letter_price": { "type": [ "object", "null" ], "description": "Fixed-width letter price by line.", "example": { "line_1": 100, "line_2": 120, "line_3": 140 }, "properties": {} }, "price_per_cm": { "type": [ "number", "null" ], "description": "Must be at least 0.", "example": 0.5 }, "price_per_letter": { "type": [ "number", "null" ], "description": "Must be at least 0.", "example": null }, "max_price_multiplier": { "type": [ "number", "null" ], "description": "Must be at least 0.", "example": 3 }, "width_limit_cm": { "type": [ "number", "null" ], "description": "Must be at least 0.", "example": 100 }, "height_limit_cm": { "type": [ "number", "null" ], "description": "Must be at least 0.", "example": 50 }, "length_limit_cm": { "type": [ "number", "null" ], "description": "Must be at least 0.", "example": null }, "price_per_sq_cm": { "type": [ "number", "null" ], "description": "Must be at least 0.", "example": 0.05 }, "fixed_length_cm": { "type": [ "number", "null" ], "description": "Must be at least 0.", "example": null }, "width_modifier": { "type": [ "number", "null" ], "description": "", "example": 1 }, "height_modifier": { "type": [ "number", "null" ], "description": "", "example": 1 }, "length_modifier": { "type": [ "number", "null" ], "description": "", "example": 1 } } } } }, "required": [ "name", "rows" ] } }, "sheet_pricing": { "type": [ "object", "null" ], "description": "", "example": null, "properties": { "pricings": { "type": "array", "description": "", "example": [ [] ], "items": { "type": "object", "properties": { "cmLimitWidth": { "type": "number", "description": "", "example": 4326.41688 }, "cmLimitHeight": { "type": "number", "description": "", "example": 4326.41688 }, "basePrice": { "type": "integer", "description": "Must be at least 0.", "example": 77 }, "pricePerSqCm": { "type": "number", "description": "Must be at least 0.", "example": 8 } }, "required": [ "cmLimitWidth", "cmLimitHeight", "basePrice", "pricePerSqCm" ] } } }, "required": [ "pricings" ] } }, "required": [ "sizes", "base_pricing", "price_lists" ] } }, "required": [ "pricing" ] } } } } } }, "/api/v3/customisers/{customiser_id}/pricing": { "parameters": [ { "in": "path", "name": "customiser_id", "description": "The customiser id, from the list customisers operation.", "example": "1", "required": true, "schema": { "type": "integer" } } ], "get": { "summary": "Get customiser pricing\n\nRetrieve the customiser's full pricing configuration as one canonical\ndocument. The document's shape follows its `pricing_model`:\n`simple_letter` prices per letter at fixed sign widths (sizes carry a\n`sizing_strategy` of `fixed_width` or `fixed_height` and a\n`height_measurement_mode` of `line_height` or `letter_height`, price\nlist rows carry per-line `base_price`/`letter_price` objects, and an\noptional `sheet_pricing` section adds backing-sheet bands);\n`advanced_letter` prices from material length (price lists carry a\n`letter_pricing_method` of `material_length` or `fixed_letter`, a\n`shipping` configuration, and rows with rates and dimension limits);\n`frame_fit` prices by frame area (exactly one price list with\narea-rate rows). Amount fields (`base_price`, `letter_price` lines,\n`price_per_letter`) are integer minor units of `currency`; the rate\nfields `price_per_cm` and `price_per_sq_cm` are decimal major currency\nunits per centimetre (or square centimetre); dimensions are\ncentimetres in `_cm` fields. `currency` is the store's configured ISO\n4217 currency, or null on Shopify-backed stores that leave the\nstorefront currency in charge. The operation is read-only, has no side\neffects, and is always safe to retry. Requires the `pricing:read`\nscope; use this document as the base for `PATCH`/`PUT` writes and the\nvalidate dry-run.\n\nA 404 problem with code `resource_not_found` means the customiser does\nnot exist on the store your API key belongs to. A 422 problem with\ncode `legacy_pricing_model` means the customiser still uses the\nretired fixed-height pricing model, which has no pricing document on\nthis API (its replacement is `simple_letter` with `fixed_height`\nsizing). A 401 problem means the key is missing, invalid, or expired;\na 403 problem with code `insufficient_scope` means the key lacks\n`pricing:read`; a 429 problem means too many requests — wait\n`retry_after` seconds, then retry. Error responses use RFC 9457\nproblem+json with a machine-readable `code` and a `request_id` to\nquote when contacting support.", "operationId": "getCustomiserPricingRetrieveTheCustomisersFullPricingConfigurationAsOneCanonicalDocumentTheDocumentsShapeFollowsItspricingModelsimpleLetterPricesPerLetterAtFixedSignWidthssizesCarryAsizingStrategyOffixedWidthOrfixedHeightAndAheightMeasurementModeOflineHeightOrletterHeightPriceListRowsCarryPerLinebasePriceletterPriceObjectsAndAnOptionalsheetPricingSectionAddsBackingSheetBandsadvancedLetterPricesFromMaterialLengthpriceListsCarryAletterPricingMethodOfmaterialLengthOrfixedLetterAshippingConfigurationAndRowsWithRatesAndDimensionLimitsframeFitPricesByFrameAreaexactlyOnePriceListWithAreaRateRowsAmountFieldsbasePriceletterPriceLinespricePerLetterAreIntegerMinorUnitsOfcurrencyTheRateFieldspricePerCmAndpricePerSqCmAreDecimalMajorCurrencyUnitsPerCentimetreorSquareCentimetreDimensionsAreCentimetresInCmFieldscurrencyIsTheStoresConfiguredISO4217CurrencyOrNullOnShopifyBackedStoresThatLeaveTheStorefrontCurrencyInChargeTheOperationIsReadOnlyHasNoSideEffectsAndIsAlwaysSafeToRetryRequiresThepricingreadScopeUseThisDocumentAsTheBaseForPATCHPUTWritesAndTheValidateDryRunA404ProblemWithCoderesourceNotFoundMeansTheCustomiserDoesNotExistOnTheStoreYourAPIKeyBelongsToA422ProblemWithCodelegacyPricingModelMeansTheCustomiserStillUsesTheRetiredFixedHeightPricingModelWhichHasNoPricingDocumentOnThisAPIitsReplacementIssimpleLetterWithfixedHeightSizingA401ProblemMeansTheKeyIsMissingInvalidOrExpiredA403ProblemWithCodeinsufficientScopeMeansTheKeyLackspricingreadA429ProblemMeansTooManyRequestsWaitretryAfterSecondsThenRetryErrorResponsesUseRFC9457Problem+jsonWithAMachineReadablecodeAndArequestIdToQuoteWhenContactingSupport", "description": "", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "oneOf": [ { "description": "simple_letter customiser", "type": "object", "example": { "data": { "object": "customiser_pricing", "customiser_id": 42, "pricing_model": "simple_letter", "pricing_model_display_name": "Simple Letter", "currency": "USD", "sizes": [ { "size_id": 7, "client_key": null, "name": "Small", "description": "Up to 50cm wide", "sort_order": 1, "char_limit": 20, "line_limit": 3, "min_char": 1, "width_cm": 50, "height_cm": null, "line_height_cm": 12, "width_multiplier": null, "length_cm": null, "sizing_strategy": "fixed_width", "height_measurement_mode": "line_height" } ], "base_pricing": { "mode": "single_base_price_by_size", "rows": [ { "size_id": 7, "size_key": null, "base_price": { "line_1": 900, "line_2": 1000, "line_3": 1100 } } ] }, "price_lists": [ { "price_list_id": 10, "name": "Standard", "rows": [ { "size_id": 7, "size_key": null, "base_price": { "line_1": 1000, "line_2": 1200, "line_3": 1400 }, "letter_price": { "line_1": 100, "line_2": 120, "line_3": 140 } } ] } ], "sheet_pricing": { "rows": [ { "width_limit_cm": 100, "height_limit_cm": 60, "base_price": 2000, "price_per_sq_cm": 1.5 } ] } }, "links": { "self": "https://web.signcustomiser.com/api/v3/customisers/42/pricing", "documentation": "https://www.signcustomiser.com/help/api/" }, "meta": { "api_version": "v3", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } }, "properties": { "data": { "type": "object", "properties": { "object": { "type": "string", "example": "customiser_pricing", "description": "The resource type discriminator. Always \"customiser_pricing\" for this endpoint (closed set).", "enum": [ "customiser_pricing" ] }, "customiser_id": { "type": "integer", "example": 42, "description": "The customiser this pricing document belongs to." }, "pricing_model": { "type": "string", "example": "simple_letter", "description": "How the customiser prices signs (closed set for this document): simple_letter, advanced_letter or frame_fit. The document's shape follows this value. Read-only: pricing models cannot be switched through this endpoint, and customisers on the retired fixed-height model return a legacy_pricing_model problem instead of a document.", "enum": [ "simple_letter", "advanced_letter", "frame_fit" ] }, "pricing_model_display_name": { "type": "string", "example": "Simple Letter", "description": "The pricing model's human display name (e.g. \"Simple Letter\"). Display only — parse pricing_model, never this label." }, "currency": { "type": [ "string", "null" ], "example": "USD", "description": "The store's configured ISO 4217 currency for every amount in the document, or null when the store has not configured one (possible on Shopify-backed stores, where the Shopify storefront currency governs). Read-only." }, "sizes": { "type": "array", "example": [ { "size_id": 7, "client_key": null, "name": "Small", "description": "Up to 50cm wide", "sort_order": 1, "char_limit": 20, "line_limit": 3, "min_char": 1, "width_cm": 50, "height_cm": null, "line_height_cm": 12, "width_multiplier": null, "length_cm": null, "sizing_strategy": "fixed_width", "height_measurement_mode": "line_height" } ], "description": "The customiser's sizes in display order. Every size reports the same key set; fields that do not apply to the pricing model are null. Common fields: size_id (integer), client_key (write-side correlation key, always null on reads), name, description, sort_order, min_char. simple_letter sizes use char_limit, line_limit, width_cm, line_height_cm, sizing_strategy (closed set: fixed_width, fixed_height — how the sign scales; internal legacy spellings never appear) and height_measurement_mode (closed set: line_height, letter_height). advanced_letter sizes use width_multiplier. frame_fit sizes use width_cm, height_cm, char_limit, min_char and length_cm. Dimensions are centimetres.", "items": { "type": "object", "properties": { "size_id": { "type": "integer", "example": 7 }, "client_key": { "type": [ "string", "null" ], "example": null }, "name": { "type": "string", "example": "Small" }, "description": { "type": "string", "example": "Up to 50cm wide" }, "sort_order": { "type": "integer", "example": 1 }, "char_limit": { "type": "integer", "example": 20 }, "line_limit": { "type": "integer", "example": 3 }, "min_char": { "type": "integer", "example": 1 }, "width_cm": { "type": "integer", "example": 50 }, "height_cm": { "type": [ "string", "null" ], "example": null }, "line_height_cm": { "type": "integer", "example": 12 }, "width_multiplier": { "type": [ "string", "null" ], "example": null }, "length_cm": { "type": [ "string", "null" ], "example": null }, "sizing_strategy": { "type": "string", "example": "fixed_width" }, "height_measurement_mode": { "type": "string", "example": "line_height" } } } }, "base_pricing": { "type": "object", "properties": { "mode": { "type": "string", "example": "single_base_price_by_size", "description": "The base pricing mode (closed set): included_in_price_lists, single_base_price_by_size (simple_letter only), single_base_price_by_size_boundary (advanced_letter and frame_fit only).", "enum": [ "included_in_price_lists", "single_base_price_by_size", "single_base_price_by_size_boundary" ] }, "rows": { "type": "array", "example": [ { "size_id": 7, "size_key": null, "base_price": { "line_1": 900, "line_2": 1000, "line_3": 1100 } } ], "items": { "type": "object", "properties": { "size_id": { "type": "integer", "example": 7 }, "size_key": { "type": [ "string", "null" ], "example": null }, "base_price": { "type": "object", "properties": { "line_1": { "type": "integer", "example": 900 }, "line_2": { "type": "integer", "example": 1000 }, "line_3": { "type": "integer", "example": 1100 } } } } } } }, "required": [ "mode" ], "description": "The base price configuration. mode is a closed set: included_in_price_lists (base prices live inside price list rows; rows is empty), single_base_price_by_size (simple_letter only: one base price per size, rows carry size_id/size_key and per-line base_price), or single_base_price_by_size_boundary (advanced_letter and frame_fit: rows carry base_price in minor units with width_limit_cm/height_limit_cm boundaries)." }, "price_lists": { "type": "array", "example": [ { "price_list_id": 10, "name": "Standard", "rows": [ { "size_id": 7, "size_key": null, "base_price": { "line_1": 1000, "line_2": 1200, "line_3": 1400 }, "letter_price": { "line_1": 100, "line_2": 120, "line_3": 140 } } ] } ], "description": "The customiser's price lists — merchants attach each font (and icon set) to one of these lists, which is how different letter styles price differently; the attachment itself is managed outside this document. Each list has price_list_id (integer), name, and rows. simple_letter rows reference a size (size_id or size_key) and carry per-line base_price and letter_price objects keyed line_1 to line_10 in integer minor units (lines beyond the configured limit are null). advanced_letter lists add letter_pricing_method (closed set: material_length — priced per centimetre of material via price_per_cm; fixed_letter — priced per letter via price_per_letter in minor units) and a shipping object (calculation closed set: physical, volumetric; volumetric_divisor; add_weight_to_product), with rows carrying base_price (minor units), rates, max_price_multiplier, and dimension limits in centimetres. frame_fit has exactly one list whose rows carry base_price (minor units), price_per_sq_cm (decimal major units per square centimetre), dimension limits, and modifier fields. price_per_cm and price_per_sq_cm are decimal major currency units — they are rates, not amounts.", "items": { "type": "object", "properties": { "price_list_id": { "type": "integer", "example": 10 }, "name": { "type": "string", "example": "Standard" }, "rows": { "type": "array", "example": [ { "size_id": 7, "size_key": null, "base_price": { "line_1": 1000, "line_2": 1200, "line_3": 1400 }, "letter_price": { "line_1": 100, "line_2": 120, "line_3": 140 } } ], "items": { "type": "object", "properties": { "size_id": { "type": "integer", "example": 7 }, "size_key": { "type": [ "string", "null" ], "example": null }, "base_price": { "type": "object", "properties": { "line_1": { "type": "integer", "example": 1000 }, "line_2": { "type": "integer", "example": 1200 }, "line_3": { "type": "integer", "example": 1400 } } }, "letter_price": { "type": "object", "properties": { "line_1": { "type": "integer", "example": 100 }, "line_2": { "type": "integer", "example": 120 }, "line_3": { "type": "integer", "example": 140 } } } } } } } } }, "sheet_pricing": { "type": [ "object", "null" ], "properties": { "rows": { "type": "array", "example": [ { "width_limit_cm": 100, "height_limit_cm": 60, "base_price": 2000, "price_per_sq_cm": 1.5 } ], "items": { "type": "object", "properties": { "width_limit_cm": { "type": "integer", "example": 100 }, "height_limit_cm": { "type": "integer", "example": 60 }, "base_price": { "type": "integer", "example": 2000 }, "price_per_sq_cm": { "type": "number", "example": 1.5 } } } } }, "description": "simple_letter only: the optional backing-sheet pricing section, or null when not configured (the key is absent entirely on other pricing models). rows carry width_limit_cm and height_limit_cm band boundaries, base_price in integer minor units, and price_per_sq_cm as a decimal major-unit rate." } }, "required": [ "object", "customiser_id", "pricing_model", "pricing_model_display_name", "currency", "sizes", "base_pricing", "price_lists", "sheet_pricing" ] }, "links": { "type": "object", "properties": { "self": { "type": "string", "example": "https://web.signcustomiser.com/api/v3/customisers/42/pricing" }, "documentation": { "type": "string", "example": "https://www.signcustomiser.com/help/api/" } } }, "meta": { "type": "object", "properties": { "api_version": { "type": "string", "example": "v3" }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } }, { "description": "advanced_letter customiser", "type": "object", "example": { "data": { "object": "customiser_pricing", "customiser_id": 57, "pricing_model": "advanced_letter", "pricing_model_display_name": "Advanced Letter", "currency": "USD", "sizes": [ { "size_id": 12, "client_key": null, "name": "Default", "description": null, "sort_order": 1, "char_limit": null, "line_limit": null, "min_char": 1, "width_cm": null, "height_cm": null, "line_height_cm": null, "width_multiplier": 1.5, "length_cm": null, "sizing_strategy": null, "height_measurement_mode": null } ], "base_pricing": { "mode": "included_in_price_lists", "rows": [] }, "price_lists": [ { "price_list_id": 21, "name": "Material", "letter_pricing_method": "material_length", "shipping": { "calculation": "physical", "volumetric_divisor": null, "add_weight_to_product": true }, "rows": [ { "base_price": 1000, "width_limit_cm": 100, "height_limit_cm": 50, "length_limit_cm": null, "price_per_sq_cm": null, "fixed_length_cm": null, "width_modifier": null, "height_modifier": null, "length_modifier": null, "max_price_multiplier": 3, "price_per_cm": 0.5, "price_per_letter": null } ] } ] }, "links": { "self": "https://web.signcustomiser.com/api/v3/customisers/57/pricing", "documentation": "https://www.signcustomiser.com/help/api/" }, "meta": { "api_version": "v3", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } }, "properties": { "data": { "type": "object", "properties": { "object": { "type": "string", "example": "customiser_pricing", "description": "The resource type discriminator. Always \"customiser_pricing\" for this endpoint (closed set).", "enum": [ "customiser_pricing" ] }, "customiser_id": { "type": "integer", "example": 57, "description": "The customiser this pricing document belongs to." }, "pricing_model": { "type": "string", "example": "advanced_letter", "description": "How the customiser prices signs (closed set for this document): simple_letter, advanced_letter or frame_fit. The document's shape follows this value. Read-only: pricing models cannot be switched through this endpoint, and customisers on the retired fixed-height model return a legacy_pricing_model problem instead of a document.", "enum": [ "simple_letter", "advanced_letter", "frame_fit" ] }, "pricing_model_display_name": { "type": "string", "example": "Advanced Letter", "description": "The pricing model's human display name (e.g. \"Simple Letter\"). Display only — parse pricing_model, never this label." }, "currency": { "type": [ "string", "null" ], "example": "USD", "description": "The store's configured ISO 4217 currency for every amount in the document, or null when the store has not configured one (possible on Shopify-backed stores, where the Shopify storefront currency governs). Read-only." }, "sizes": { "type": "array", "example": [ { "size_id": 12, "client_key": null, "name": "Default", "description": null, "sort_order": 1, "char_limit": null, "line_limit": null, "min_char": 1, "width_cm": null, "height_cm": null, "line_height_cm": null, "width_multiplier": 1.5, "length_cm": null, "sizing_strategy": null, "height_measurement_mode": null } ], "description": "The customiser's sizes in display order. Every size reports the same key set; fields that do not apply to the pricing model are null. Common fields: size_id (integer), client_key (write-side correlation key, always null on reads), name, description, sort_order, min_char. simple_letter sizes use char_limit, line_limit, width_cm, line_height_cm, sizing_strategy (closed set: fixed_width, fixed_height — how the sign scales; internal legacy spellings never appear) and height_measurement_mode (closed set: line_height, letter_height). advanced_letter sizes use width_multiplier. frame_fit sizes use width_cm, height_cm, char_limit, min_char and length_cm. Dimensions are centimetres.", "items": { "type": "object", "properties": { "size_id": { "type": "integer", "example": 12 }, "client_key": { "type": [ "string", "null" ], "example": null }, "name": { "type": "string", "example": "Default" }, "description": { "type": [ "string", "null" ], "example": null }, "sort_order": { "type": "integer", "example": 1 }, "char_limit": { "type": [ "string", "null" ], "example": null }, "line_limit": { "type": [ "string", "null" ], "example": null }, "min_char": { "type": "integer", "example": 1 }, "width_cm": { "type": [ "string", "null" ], "example": null }, "height_cm": { "type": [ "string", "null" ], "example": null }, "line_height_cm": { "type": [ "string", "null" ], "example": null }, "width_multiplier": { "type": "number", "example": 1.5 }, "length_cm": { "type": [ "string", "null" ], "example": null }, "sizing_strategy": { "type": [ "string", "null" ], "example": null }, "height_measurement_mode": { "type": [ "string", "null" ], "example": null } } } }, "base_pricing": { "type": "object", "properties": { "mode": { "type": "string", "example": "included_in_price_lists", "description": "The base pricing mode (closed set): included_in_price_lists, single_base_price_by_size (simple_letter only), single_base_price_by_size_boundary (advanced_letter and frame_fit only).", "enum": [ "included_in_price_lists", "single_base_price_by_size", "single_base_price_by_size_boundary" ] }, "rows": { "type": "array", "example": [] } }, "required": [ "mode" ], "description": "The base price configuration. mode is a closed set: included_in_price_lists (base prices live inside price list rows; rows is empty), single_base_price_by_size (simple_letter only: one base price per size, rows carry size_id/size_key and per-line base_price), or single_base_price_by_size_boundary (advanced_letter and frame_fit: rows carry base_price in minor units with width_limit_cm/height_limit_cm boundaries)." }, "price_lists": { "type": "array", "example": [ { "price_list_id": 21, "name": "Material", "letter_pricing_method": "material_length", "shipping": { "calculation": "physical", "volumetric_divisor": null, "add_weight_to_product": true }, "rows": [ { "base_price": 1000, "width_limit_cm": 100, "height_limit_cm": 50, "length_limit_cm": null, "price_per_sq_cm": null, "fixed_length_cm": null, "width_modifier": null, "height_modifier": null, "length_modifier": null, "max_price_multiplier": 3, "price_per_cm": 0.5, "price_per_letter": null } ] } ], "description": "The customiser's price lists — merchants attach each font (and icon set) to one of these lists, which is how different letter styles price differently; the attachment itself is managed outside this document. Each list has price_list_id (integer), name, and rows. simple_letter rows reference a size (size_id or size_key) and carry per-line base_price and letter_price objects keyed line_1 to line_10 in integer minor units (lines beyond the configured limit are null). advanced_letter lists add letter_pricing_method (closed set: material_length — priced per centimetre of material via price_per_cm; fixed_letter — priced per letter via price_per_letter in minor units) and a shipping object (calculation closed set: physical, volumetric; volumetric_divisor; add_weight_to_product), with rows carrying base_price (minor units), rates, max_price_multiplier, and dimension limits in centimetres. frame_fit has exactly one list whose rows carry base_price (minor units), price_per_sq_cm (decimal major units per square centimetre), dimension limits, and modifier fields. price_per_cm and price_per_sq_cm are decimal major currency units — they are rates, not amounts.", "items": { "type": "object", "properties": { "price_list_id": { "type": "integer", "example": 21 }, "name": { "type": "string", "example": "Material" }, "letter_pricing_method": { "type": "string", "example": "material_length" }, "shipping": { "type": "object", "properties": { "calculation": { "type": "string", "example": "physical" }, "volumetric_divisor": { "type": [ "string", "null" ], "example": null }, "add_weight_to_product": { "type": "boolean", "example": true } } }, "rows": { "type": "array", "example": [ { "base_price": 1000, "width_limit_cm": 100, "height_limit_cm": 50, "length_limit_cm": null, "price_per_sq_cm": null, "fixed_length_cm": null, "width_modifier": null, "height_modifier": null, "length_modifier": null, "max_price_multiplier": 3, "price_per_cm": 0.5, "price_per_letter": null } ], "items": { "type": "object", "properties": { "base_price": { "type": "integer", "example": 1000 }, "width_limit_cm": { "type": "integer", "example": 100 }, "height_limit_cm": { "type": "integer", "example": 50 }, "length_limit_cm": { "type": [ "string", "null" ], "example": null }, "price_per_sq_cm": { "type": [ "string", "null" ], "example": null }, "fixed_length_cm": { "type": [ "string", "null" ], "example": null }, "width_modifier": { "type": [ "string", "null" ], "example": null }, "height_modifier": { "type": [ "string", "null" ], "example": null }, "length_modifier": { "type": [ "string", "null" ], "example": null }, "max_price_multiplier": { "type": "integer", "example": 3 }, "price_per_cm": { "type": "number", "example": 0.5 }, "price_per_letter": { "type": [ "string", "null" ], "example": null } } } } } } } }, "required": [ "object", "customiser_id", "pricing_model", "pricing_model_display_name", "currency", "sizes", "base_pricing", "price_lists" ] }, "links": { "type": "object", "properties": { "self": { "type": "string", "example": "https://web.signcustomiser.com/api/v3/customisers/57/pricing" }, "documentation": { "type": "string", "example": "https://www.signcustomiser.com/help/api/" } } }, "meta": { "type": "object", "properties": { "api_version": { "type": "string", "example": "v3" }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } }, { "description": "frame_fit customiser", "type": "object", "example": { "data": { "object": "customiser_pricing", "customiser_id": 63, "pricing_model": "frame_fit", "pricing_model_display_name": "Frame Fit", "currency": "GBP", "sizes": [ { "size_id": 19, "client_key": null, "name": "A2", "description": null, "sort_order": 1, "char_limit": null, "line_limit": null, "min_char": 1, "width_cm": 59.4, "height_cm": 42, "line_height_cm": null, "width_multiplier": null, "length_cm": null, "sizing_strategy": null, "height_measurement_mode": null } ], "base_pricing": { "mode": "included_in_price_lists", "rows": [] }, "price_lists": [ { "price_list_id": 33, "name": "Frame pricing", "shipping": { "calculation": "physical", "volumetric_divisor": null, "add_weight_to_product": false }, "rows": [ { "base_price": 7500, "width_limit_cm": 120, "height_limit_cm": 90, "length_limit_cm": null, "price_per_sq_cm": 0.022, "fixed_length_cm": null, "width_modifier": null, "height_modifier": null, "length_modifier": null } ] } ] }, "links": { "self": "https://web.signcustomiser.com/api/v3/customisers/63/pricing", "documentation": "https://www.signcustomiser.com/help/api/" }, "meta": { "api_version": "v3", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } }, "properties": { "data": { "type": "object", "properties": { "object": { "type": "string", "example": "customiser_pricing", "description": "The resource type discriminator. Always \"customiser_pricing\" for this endpoint (closed set).", "enum": [ "customiser_pricing" ] }, "customiser_id": { "type": "integer", "example": 63, "description": "The customiser this pricing document belongs to." }, "pricing_model": { "type": "string", "example": "frame_fit", "description": "How the customiser prices signs (closed set for this document): simple_letter, advanced_letter or frame_fit. The document's shape follows this value. Read-only: pricing models cannot be switched through this endpoint, and customisers on the retired fixed-height model return a legacy_pricing_model problem instead of a document.", "enum": [ "simple_letter", "advanced_letter", "frame_fit" ] }, "pricing_model_display_name": { "type": "string", "example": "Frame Fit", "description": "The pricing model's human display name (e.g. \"Simple Letter\"). Display only — parse pricing_model, never this label." }, "currency": { "type": [ "string", "null" ], "example": "GBP", "description": "The store's configured ISO 4217 currency for every amount in the document, or null when the store has not configured one (possible on Shopify-backed stores, where the Shopify storefront currency governs). Read-only." }, "sizes": { "type": "array", "example": [ { "size_id": 19, "client_key": null, "name": "A2", "description": null, "sort_order": 1, "char_limit": null, "line_limit": null, "min_char": 1, "width_cm": 59.4, "height_cm": 42, "line_height_cm": null, "width_multiplier": null, "length_cm": null, "sizing_strategy": null, "height_measurement_mode": null } ], "description": "The customiser's sizes in display order. Every size reports the same key set; fields that do not apply to the pricing model are null. Common fields: size_id (integer), client_key (write-side correlation key, always null on reads), name, description, sort_order, min_char. simple_letter sizes use char_limit, line_limit, width_cm, line_height_cm, sizing_strategy (closed set: fixed_width, fixed_height — how the sign scales; internal legacy spellings never appear) and height_measurement_mode (closed set: line_height, letter_height). advanced_letter sizes use width_multiplier. frame_fit sizes use width_cm, height_cm, char_limit, min_char and length_cm. Dimensions are centimetres.", "items": { "type": "object", "properties": { "size_id": { "type": "integer", "example": 19 }, "client_key": { "type": [ "string", "null" ], "example": null }, "name": { "type": "string", "example": "A2" }, "description": { "type": [ "string", "null" ], "example": null }, "sort_order": { "type": "integer", "example": 1 }, "char_limit": { "type": [ "string", "null" ], "example": null }, "line_limit": { "type": [ "string", "null" ], "example": null }, "min_char": { "type": "integer", "example": 1 }, "width_cm": { "type": "number", "example": 59.4 }, "height_cm": { "type": "integer", "example": 42 }, "line_height_cm": { "type": [ "string", "null" ], "example": null }, "width_multiplier": { "type": [ "string", "null" ], "example": null }, "length_cm": { "type": [ "string", "null" ], "example": null }, "sizing_strategy": { "type": [ "string", "null" ], "example": null }, "height_measurement_mode": { "type": [ "string", "null" ], "example": null } } } }, "base_pricing": { "type": "object", "properties": { "mode": { "type": "string", "example": "included_in_price_lists", "description": "The base pricing mode (closed set): included_in_price_lists, single_base_price_by_size (simple_letter only), single_base_price_by_size_boundary (advanced_letter and frame_fit only).", "enum": [ "included_in_price_lists", "single_base_price_by_size", "single_base_price_by_size_boundary" ] }, "rows": { "type": "array", "example": [] } }, "required": [ "mode" ], "description": "The base price configuration. mode is a closed set: included_in_price_lists (base prices live inside price list rows; rows is empty), single_base_price_by_size (simple_letter only: one base price per size, rows carry size_id/size_key and per-line base_price), or single_base_price_by_size_boundary (advanced_letter and frame_fit: rows carry base_price in minor units with width_limit_cm/height_limit_cm boundaries)." }, "price_lists": { "type": "array", "example": [ { "price_list_id": 33, "name": "Frame pricing", "shipping": { "calculation": "physical", "volumetric_divisor": null, "add_weight_to_product": false }, "rows": [ { "base_price": 7500, "width_limit_cm": 120, "height_limit_cm": 90, "length_limit_cm": null, "price_per_sq_cm": 0.022, "fixed_length_cm": null, "width_modifier": null, "height_modifier": null, "length_modifier": null } ] } ], "description": "The customiser's price lists — merchants attach each font (and icon set) to one of these lists, which is how different letter styles price differently; the attachment itself is managed outside this document. Each list has price_list_id (integer), name, and rows. simple_letter rows reference a size (size_id or size_key) and carry per-line base_price and letter_price objects keyed line_1 to line_10 in integer minor units (lines beyond the configured limit are null). advanced_letter lists add letter_pricing_method (closed set: material_length — priced per centimetre of material via price_per_cm; fixed_letter — priced per letter via price_per_letter in minor units) and a shipping object (calculation closed set: physical, volumetric; volumetric_divisor; add_weight_to_product), with rows carrying base_price (minor units), rates, max_price_multiplier, and dimension limits in centimetres. frame_fit has exactly one list whose rows carry base_price (minor units), price_per_sq_cm (decimal major units per square centimetre), dimension limits, and modifier fields. price_per_cm and price_per_sq_cm are decimal major currency units — they are rates, not amounts.", "items": { "type": "object", "properties": { "price_list_id": { "type": "integer", "example": 33 }, "name": { "type": "string", "example": "Frame pricing" }, "shipping": { "type": "object", "properties": { "calculation": { "type": "string", "example": "physical" }, "volumetric_divisor": { "type": [ "string", "null" ], "example": null }, "add_weight_to_product": { "type": "boolean", "example": false } } }, "rows": { "type": "array", "example": [ { "base_price": 7500, "width_limit_cm": 120, "height_limit_cm": 90, "length_limit_cm": null, "price_per_sq_cm": 0.022, "fixed_length_cm": null, "width_modifier": null, "height_modifier": null, "length_modifier": null } ], "items": { "type": "object", "properties": { "base_price": { "type": "integer", "example": 7500 }, "width_limit_cm": { "type": "integer", "example": 120 }, "height_limit_cm": { "type": "integer", "example": 90 }, "length_limit_cm": { "type": [ "string", "null" ], "example": null }, "price_per_sq_cm": { "type": "number", "example": 0.022 }, "fixed_length_cm": { "type": [ "string", "null" ], "example": null }, "width_modifier": { "type": [ "string", "null" ], "example": null }, "height_modifier": { "type": [ "string", "null" ], "example": null }, "length_modifier": { "type": [ "string", "null" ], "example": null } } } } } } } }, "required": [ "object", "customiser_id", "pricing_model", "pricing_model_display_name", "currency", "sizes", "base_pricing", "price_lists" ] }, "links": { "type": "object", "properties": { "self": { "type": "string", "example": "https://web.signcustomiser.com/api/v3/customisers/63/pricing" }, "documentation": { "type": "string", "example": "https://www.signcustomiser.com/help/api/" } } }, "meta": { "type": "object", "properties": { "api_version": { "type": "string", "example": "v3" }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } ] } } } }, "401": { "description": "Missing API key", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/missing_api_key", "title": "Missing API key", "status": 401, "code": "missing_api_key", "detail": "Provide a store API key as a bearer token: Authorization: Bearer . Keys are created in the merchant admin under Integrate → API Tokens.", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/missing_api_key" }, "title": { "type": "string", "example": "Missing API key" }, "status": { "type": "integer", "example": 401 }, "code": { "type": "string", "example": "missing_api_key" }, "detail": { "type": "string", "example": "Provide a store API key as a bearer token: Authorization: Bearer . Keys are created in the merchant admin under Integrate → API Tokens." }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/insufficient_scope", "title": "Insufficient scope", "status": 403, "code": "insufficient_scope", "detail": "This operation requires the pricing:read scope, but the API key grants the following scopes: store:read. Create a key that includes the required scope in the merchant admin under Integrate → API Tokens.", "required_scopes": [ "pricing:read" ], "granted_scopes": [ "store:read" ], "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/insufficient_scope" }, "title": { "type": "string", "example": "Insufficient scope" }, "status": { "type": "integer", "example": 403 }, "code": { "type": "string", "example": "insufficient_scope" }, "detail": { "type": "string", "example": "This operation requires the pricing:read scope, but the API key grants the following scopes: store:read. Create a key that includes the required scope in the merchant admin under Integrate → API Tokens." }, "required_scopes": { "type": "array", "example": [ "pricing:read" ], "items": { "type": "string" } }, "granted_scopes": { "type": "array", "example": [ "store:read" ], "items": { "type": "string" } }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } }, "404": { "description": "Unknown customiser", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/resource_not_found", "title": "Resource not found", "status": 404, "code": "resource_not_found", "detail": "The requested resource does not exist or does not belong to the authenticated store.", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/resource_not_found" }, "title": { "type": "string", "example": "Resource not found" }, "status": { "type": "integer", "example": 404 }, "code": { "type": "string", "example": "resource_not_found" }, "detail": { "type": "string", "example": "The requested resource does not exist or does not belong to the authenticated store." }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } }, "422": { "description": "Retired pricing model", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/legacy_pricing_model", "title": "Legacy pricing model", "status": 422, "code": "legacy_pricing_model", "detail": "This customiser uses the retired fixed-height pricing model (legacy_fixed_height), which has no pricing document on this API. Recreate the customiser as simple_letter with a fixed_height sizing strategy on its sizes to manage its pricing here.", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/legacy_pricing_model" }, "title": { "type": "string", "example": "Legacy pricing model" }, "status": { "type": "integer", "example": 422 }, "code": { "type": "string", "example": "legacy_pricing_model" }, "detail": { "type": "string", "example": "This customiser uses the retired fixed-height pricing model (legacy_fixed_height), which has no pricing document on this API. Recreate the customiser as simple_letter with a fixed_height sizing strategy on its sizes to manage its pricing here." }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/rate_limited", "title": "Too many requests", "status": 429, "code": "rate_limited", "detail": "You have exceeded the request limit for this API key. Wait 60 seconds, then retry.", "retry_after": 60, "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/rate_limited" }, "title": { "type": "string", "example": "Too many requests" }, "status": { "type": "integer", "example": 429 }, "code": { "type": "string", "example": "rate_limited" }, "detail": { "type": "string", "example": "You have exceeded the request limit for this API key. Wait 60 seconds, then retry." }, "retry_after": { "type": "integer", "example": 60 }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } } }, "tags": [ "Pricing" ] }, "put": { "summary": "Replace customiser pricing\n\nReplace the customiser's entire pricing configuration with the request\nbody — the full canonical document, exactly as the read operation\nreturns it (no envelope). This is an explicit full replacement: sizes\nand price lists omitted from the document are deleted (each carries its\nid — size_id, price_list_id — to update in place; omit the id to create\na new record, and use a size client_key with row size_key references to\nlink rows to sizes created in the same request). For partial updates\nprefer PATCH; to check a document without persisting anything use the\nvalidate operation. The read-only descriptor fields (object,\ncustomiser_id, pricing_model, pricing_model_display_name, currency) may\nbe echoed back unchanged but can never be changed here — in particular\nthe pricing model cannot be switched. Field semantics, units, and the\nper-model document shapes are documented on the read operation.\nRequires the `pricing:write` scope.\n\nA successful replacement immediately reprices the storefront: the\ncustomiser's cached configuration is invalidated and translated\nlanguage content is resynchronised. Send an `Idempotency-Key` header\n(1-255 visible ASCII characters, e.g. a UUID) to make the write safe\nto retry: repeating the same key with the same body replays the\noriginal response (marked `Idempotency-Replay: true`) without\nexecuting again; the same key with a different body is a 409 problem\nwith code `idempotency_key_conflict`; keys are retained for at least\n24 hours and are scoped to your credential, the HTTP method, and the\npath.\n\nValidation failures are 422 problems: `validation_failed` lists every\nfield error in `errors[]` with a JSON `pointer` and, for enum\nviolations, the `allowed_values`; `unknown_field` means the document\ncontains fields outside the schema (fix the pointers listed — nothing\nis ever silently ignored); `legacy_pricing_model` means the customiser\nstill uses the retired fixed-height model. A 409 problem with code\n`resource_in_use` means the document omits sizes or price lists that\nfonts or settings still reference — keep them in the document or\ndetach them first. A 400 problem means the body is not valid JSON or\nthe `Idempotency-Key` header is malformed. 401/403/404/429 behave as\non the read operation.", "operationId": "replaceCustomiserPricingReplaceTheCustomisersEntirePricingConfigurationWithTheRequestBodyTheFullCanonicalDocumentExactlyAsTheReadOperationReturnsItnoEnvelopeThisIsAnExplicitFullReplacementSizesAndPriceListsOmittedFromTheDocumentAreDeletedeachCarriesItsIdSizeIdPriceListIdToUpdateInPlaceOmitTheIdToCreateANewRecordAndUseASizeClientKeyWithRowSizeKeyReferencesToLinkRowsToSizesCreatedInTheSameRequestForPartialUpdatesPreferPATCHToCheckADocumentWithoutPersistingAnythingUseTheValidateOperationTheReadOnlyDescriptorFieldsobjectCustomiserIdPricingModelPricingModelDisplayNameCurrencyMayBeEchoedBackUnchangedButCanNeverBeChangedHereInParticularThePricingModelCannotBeSwitchedFieldSemanticsUnitsAndThePerModelDocumentShapesAreDocumentedOnTheReadOperationRequiresThepricingwriteScopeASuccessfulReplacementImmediatelyRepricesTheStorefrontTheCustomisersCachedConfigurationIsInvalidatedAndTranslatedLanguageContentIsResynchronisedSendAnIdempotencyKeyHeader1255VisibleASCIICharactersEgAUUIDToMakeTheWriteSafeToRetryRepeatingTheSameKeyWithTheSameBodyReplaysTheOriginalResponsemarkedIdempotencyReplayTrueWithoutExecutingAgainTheSameKeyWithADifferentBodyIsA409ProblemWithCodeidempotencyKeyConflictKeysAreRetainedForAtLeast24HoursAndAreScopedToYourCredentialTheHTTPMethodAndThePathValidationFailuresAre422ProblemsvalidationFailedListsEveryFieldErrorInerrorsWithAJSONpointerAndForEnumViolationsTheallowedValuesunknownFieldMeansTheDocumentContainsFieldsOutsideTheSchemafixThePointersListedNothingIsEverSilentlyIgnoredlegacyPricingModelMeansTheCustomiserStillUsesTheRetiredFixedHeightModelA409ProblemWithCoderesourceInUseMeansTheDocumentOmitsSizesOrPriceListsThatFontsOrSettingsStillReferenceKeepThemInTheDocumentOrDetachThemFirstA400ProblemMeansTheBodyIsNotValidJSONOrTheIdempotencyKeyHeaderIsMalformed401403404429BehaveAsOnTheReadOperation", "description": "", "responses": { "200": { "description": "Replaced document", "content": { "application/json": { "schema": { "type": "object", "example": { "data": { "object": "customiser_pricing", "customiser_id": 42, "pricing_model": "simple_letter", "pricing_model_display_name": "Simple Letter", "currency": "USD", "sizes": [ { "size_id": 7, "client_key": null, "name": "Small", "description": "Up to 50cm wide", "sort_order": 1, "char_limit": 20, "line_limit": 3, "min_char": 1, "width_cm": 50, "height_cm": null, "line_height_cm": 12, "width_multiplier": null, "length_cm": null, "sizing_strategy": "fixed_width", "height_measurement_mode": "line_height" } ], "base_pricing": { "mode": "included_in_price_lists", "rows": [] }, "price_lists": [ { "price_list_id": 10, "name": "Standard", "rows": [ { "size_id": 7, "size_key": null, "base_price": { "line_1": 1000, "line_2": 1200, "line_3": 1400 }, "letter_price": { "line_1": 100, "line_2": 120, "line_3": 140 } } ] } ], "sheet_pricing": null }, "links": { "self": "https://web.signcustomiser.com/api/v3/customisers/42/pricing", "documentation": "https://www.signcustomiser.com/help/api/" }, "meta": { "api_version": "v3", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } }, "properties": { "data": { "type": "object", "properties": { "object": { "type": "string", "example": "customiser_pricing" }, "customiser_id": { "type": "integer", "example": 42 }, "pricing_model": { "type": "string", "example": "simple_letter" }, "pricing_model_display_name": { "type": "string", "example": "Simple Letter" }, "currency": { "type": "string", "example": "USD" }, "sizes": { "type": "array", "example": [ { "size_id": 7, "client_key": null, "name": "Small", "description": "Up to 50cm wide", "sort_order": 1, "char_limit": 20, "line_limit": 3, "min_char": 1, "width_cm": 50, "height_cm": null, "line_height_cm": 12, "width_multiplier": null, "length_cm": null, "sizing_strategy": "fixed_width", "height_measurement_mode": "line_height" } ], "items": { "type": "object", "properties": { "size_id": { "type": "integer", "example": 7 }, "client_key": { "type": [ "string", "null" ], "example": null }, "name": { "type": "string", "example": "Small" }, "description": { "type": "string", "example": "Up to 50cm wide" }, "sort_order": { "type": "integer", "example": 1 }, "char_limit": { "type": "integer", "example": 20 }, "line_limit": { "type": "integer", "example": 3 }, "min_char": { "type": "integer", "example": 1 }, "width_cm": { "type": "integer", "example": 50 }, "height_cm": { "type": [ "string", "null" ], "example": null }, "line_height_cm": { "type": "integer", "example": 12 }, "width_multiplier": { "type": [ "string", "null" ], "example": null }, "length_cm": { "type": [ "string", "null" ], "example": null }, "sizing_strategy": { "type": "string", "example": "fixed_width" }, "height_measurement_mode": { "type": "string", "example": "line_height" } } } }, "base_pricing": { "type": "object", "properties": { "mode": { "type": "string", "example": "included_in_price_lists" }, "rows": { "type": "array", "example": [] } } }, "price_lists": { "type": "array", "example": [ { "price_list_id": 10, "name": "Standard", "rows": [ { "size_id": 7, "size_key": null, "base_price": { "line_1": 1000, "line_2": 1200, "line_3": 1400 }, "letter_price": { "line_1": 100, "line_2": 120, "line_3": 140 } } ] } ], "items": { "type": "object", "properties": { "price_list_id": { "type": "integer", "example": 10 }, "name": { "type": "string", "example": "Standard" }, "rows": { "type": "array", "example": [ { "size_id": 7, "size_key": null, "base_price": { "line_1": 1000, "line_2": 1200, "line_3": 1400 }, "letter_price": { "line_1": 100, "line_2": 120, "line_3": 140 } } ], "items": { "type": "object", "properties": { "size_id": { "type": "integer", "example": 7 }, "size_key": { "type": [ "string", "null" ], "example": null }, "base_price": { "type": "object", "properties": { "line_1": { "type": "integer", "example": 1000 }, "line_2": { "type": "integer", "example": 1200 }, "line_3": { "type": "integer", "example": 1400 } } }, "letter_price": { "type": "object", "properties": { "line_1": { "type": "integer", "example": 100 }, "line_2": { "type": "integer", "example": 120 }, "line_3": { "type": "integer", "example": 140 } } } } } } } } }, "sheet_pricing": { "type": [ "string", "null" ], "example": null } } }, "links": { "type": "object", "properties": { "self": { "type": "string", "example": "https://web.signcustomiser.com/api/v3/customisers/42/pricing" }, "documentation": { "type": "string", "example": "https://www.signcustomiser.com/help/api/" } } }, "meta": { "type": "object", "properties": { "api_version": { "type": "string", "example": "v3" }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } } } }, "400": { "description": "Malformed JSON body", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/malformed_json", "title": "Malformed JSON", "status": 400, "code": "malformed_json", "detail": "The request body is not valid JSON: Syntax error.", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/malformed_json" }, "title": { "type": "string", "example": "Malformed JSON" }, "status": { "type": "integer", "example": 400 }, "code": { "type": "string", "example": "malformed_json" }, "detail": { "type": "string", "example": "The request body is not valid JSON: Syntax error." }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } }, "401": { "description": "Missing API key", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/missing_api_key", "title": "Missing API key", "status": 401, "code": "missing_api_key", "detail": "Provide a store API key as a bearer token: Authorization: Bearer . Keys are created in the merchant admin under Integrate → API Tokens.", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/missing_api_key" }, "title": { "type": "string", "example": "Missing API key" }, "status": { "type": "integer", "example": 401 }, "code": { "type": "string", "example": "missing_api_key" }, "detail": { "type": "string", "example": "Provide a store API key as a bearer token: Authorization: Bearer . Keys are created in the merchant admin under Integrate → API Tokens." }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/insufficient_scope", "title": "Insufficient scope", "status": 403, "code": "insufficient_scope", "detail": "This operation requires the pricing:write scope, but the API key grants the following scopes: pricing:read. Create a key that includes the required scope in the merchant admin under Integrate → API Tokens.", "required_scopes": [ "pricing:write" ], "granted_scopes": [ "pricing:read" ], "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/insufficient_scope" }, "title": { "type": "string", "example": "Insufficient scope" }, "status": { "type": "integer", "example": 403 }, "code": { "type": "string", "example": "insufficient_scope" }, "detail": { "type": "string", "example": "This operation requires the pricing:write scope, but the API key grants the following scopes: pricing:read. Create a key that includes the required scope in the merchant admin under Integrate → API Tokens." }, "required_scopes": { "type": "array", "example": [ "pricing:write" ], "items": { "type": "string" } }, "granted_scopes": { "type": "array", "example": [ "pricing:read" ], "items": { "type": "string" } }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } }, "404": { "description": "Unknown customiser", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/resource_not_found", "title": "Resource not found", "status": 404, "code": "resource_not_found", "detail": "The requested resource does not exist or does not belong to the authenticated store.", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/resource_not_found" }, "title": { "type": "string", "example": "Resource not found" }, "status": { "type": "integer", "example": 404 }, "code": { "type": "string", "example": "resource_not_found" }, "detail": { "type": "string", "example": "The requested resource does not exist or does not belong to the authenticated store." }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "oneOf": [ { "description": "Records still referenced", "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/resource_in_use", "title": "Resource in use", "status": 409, "code": "resource_in_use", "detail": "The document omits sizes that fonts still reference, so the write would delete records in use. Keep those sizes in the document, or update the fonts that reference them first.", "errors": [ { "pointer": "/sizes", "code": "resource_in_use", "detail": "The document omits sizes that fonts still reference, so the write would delete records in use. Keep those sizes in the document, or update the fonts that reference them first." } ], "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/resource_in_use" }, "title": { "type": "string", "example": "Resource in use" }, "status": { "type": "integer", "example": 409 }, "code": { "type": "string", "example": "resource_in_use" }, "detail": { "type": "string", "example": "The document omits sizes that fonts still reference, so the write would delete records in use. Keep those sizes in the document, or update the fonts that reference them first." }, "errors": { "type": "array", "example": [ { "pointer": "/sizes", "code": "resource_in_use", "detail": "The document omits sizes that fonts still reference, so the write would delete records in use. Keep those sizes in the document, or update the fonts that reference them first." } ], "items": { "type": "object", "properties": { "pointer": { "type": "string", "example": "/sizes" }, "code": { "type": "string", "example": "resource_in_use" }, "detail": { "type": "string", "example": "The document omits sizes that fonts still reference, so the write would delete records in use. Keep those sizes in the document, or update the fonts that reference them first." } } } }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } }, { "description": "Idempotency key conflict", "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/idempotency_key_conflict", "title": "Idempotency key conflict", "status": 409, "code": "idempotency_key_conflict", "detail": "This Idempotency-Key was already used for a different request body on this operation. An idempotency key identifies one exact request: retry the original body to replay its response, or send the new body with a fresh key.", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/idempotency_key_conflict" }, "title": { "type": "string", "example": "Idempotency key conflict" }, "status": { "type": "integer", "example": 409 }, "code": { "type": "string", "example": "idempotency_key_conflict" }, "detail": { "type": "string", "example": "This Idempotency-Key was already used for a different request body on this operation. An idempotency key identifies one exact request: retry the original body to replay its response, or send the new body with a fresh key." }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "oneOf": [ { "description": "Validation failed", "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/validation_failed", "title": "Validation failed", "status": 422, "code": "validation_failed", "detail": "The request payload failed validation. Correct the fields listed in errors and retry.", "errors": [ { "pointer": "/sizes/0/sizing_strategy", "code": "unsupported_value", "detail": "The selected sizes.0.sizing_strategy is invalid.", "allowed_values": [ "fixed_width", "fixed_height" ] } ], "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/validation_failed" }, "title": { "type": "string", "example": "Validation failed" }, "status": { "type": "integer", "example": 422 }, "code": { "type": "string", "example": "validation_failed" }, "detail": { "type": "string", "example": "The request payload failed validation. Correct the fields listed in errors and retry." }, "errors": { "type": "array", "example": [ { "pointer": "/sizes/0/sizing_strategy", "code": "unsupported_value", "detail": "The selected sizes.0.sizing_strategy is invalid.", "allowed_values": [ "fixed_width", "fixed_height" ] } ], "items": { "type": "object", "properties": { "pointer": { "type": "string", "example": "/sizes/0/sizing_strategy" }, "code": { "type": "string", "example": "unsupported_value" }, "detail": { "type": "string", "example": "The selected sizes.0.sizing_strategy is invalid." }, "allowed_values": { "type": "array", "example": [ "fixed_width", "fixed_height" ], "items": { "type": "string" } } } } }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } }, { "description": "Unknown field", "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/unknown_field", "title": "Unknown field", "status": 422, "code": "unknown_field", "detail": "The document contains fields this resource does not define: /sheet_pricing/pricings. Unknown fields are rejected rather than ignored so a typo can never silently change meaning.", "errors": [ { "pointer": "/sheet_pricing/pricings", "code": "unknown_field", "detail": "The field \"pricings\" is not part of the pricing document." } ], "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/unknown_field" }, "title": { "type": "string", "example": "Unknown field" }, "status": { "type": "integer", "example": 422 }, "code": { "type": "string", "example": "unknown_field" }, "detail": { "type": "string", "example": "The document contains fields this resource does not define: /sheet_pricing/pricings. Unknown fields are rejected rather than ignored so a typo can never silently change meaning." }, "errors": { "type": "array", "example": [ { "pointer": "/sheet_pricing/pricings", "code": "unknown_field", "detail": "The field \"pricings\" is not part of the pricing document." } ], "items": { "type": "object", "properties": { "pointer": { "type": "string", "example": "/sheet_pricing/pricings" }, "code": { "type": "string", "example": "unknown_field" }, "detail": { "type": "string", "example": "The field \"pricings\" is not part of the pricing document." } } } }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/rate_limited", "title": "Too many requests", "status": 429, "code": "rate_limited", "detail": "You have exceeded the request limit for this API key. Wait 60 seconds, then retry.", "retry_after": 60, "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/rate_limited" }, "title": { "type": "string", "example": "Too many requests" }, "status": { "type": "integer", "example": 429 }, "code": { "type": "string", "example": "rate_limited" }, "detail": { "type": "string", "example": "You have exceeded the request limit for this API key. Wait 60 seconds, then retry." }, "retry_after": { "type": "integer", "example": 60 }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } } }, "tags": [ "Pricing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "description": "Optional echo of the document type. Must be \"customiser_pricing\" when present.", "example": "customiser_pricing" }, "customiser_id": { "type": "integer", "description": "Optional echo of the customiser id. Must match the path when present.", "example": 42 }, "pricing_model": { "type": "string", "description": "Optional echo of the pricing model (read-only guard — the model cannot be switched; one of simple_letter, advanced_letter, frame_fit).", "example": "simple_letter" }, "pricing_model_display_name": { "type": "string", "description": "Optional echo of the display name. Must match when present.", "example": "Simple Letter" }, "currency": { "type": "string", "description": "Optional echo of the store currency (read-only guard). Must match when present.", "example": "USD" }, "sizes": { "type": "array", "description": "The complete size collection. Sizes omitted from it are deleted (refused with a 409 while fonts still reference them).", "example": [ [] ], "items": { "type": "object", "properties": { "size_id": { "type": "integer", "description": "The id of an existing size to update. Omit (or null) to create a new size.", "example": 7 }, "client_key": { "type": "string", "description": "A correlation key for a newly created size, referenced by row size_key values in the same request. Must be unique across sizes.", "example": "small" }, "name": { "type": "string", "description": "The size's display name.", "example": "Small" }, "description": { "type": "string", "description": "The size's description.", "example": "Up to 50cm wide" }, "sort_order": { "type": "integer", "description": "Display position (defaults to the array order).", "example": 1 }, "char_limit": { "type": "integer", "description": "simple_letter and frame_fit: maximum characters.", "example": 20 }, "line_limit": { "type": "integer", "description": "simple_letter only: maximum lines (1-10).", "example": 3 }, "min_char": { "type": "integer", "description": "Minimum characters.", "example": 1 }, "width_cm": { "type": "number", "description": "simple_letter and frame_fit: the size's width in centimetres.", "example": 50 }, "height_cm": { "type": "number", "description": "frame_fit: the size's height in centimetres.", "example": null }, "line_height_cm": { "type": "number", "description": "simple_letter: the per-line height in centimetres.", "example": 12 }, "sizing_strategy": { "type": "string", "description": "simple_letter only: how the sign scales. One of fixed_width (the width is fixed, height follows the text) or fixed_height (the height is fixed, width follows the text).", "example": "fixed_width" }, "height_measurement_mode": { "type": "string", "description": "simple_letter only: what the per-line value measures. One of line_height or letter_height.", "example": "line_height" }, "width_multiplier": { "type": "number", "description": "advanced_letter only (required there): multiplies the rendered width into material length. Ignored-as-default elsewhere.", "example": null }, "length_cm": { "type": "number", "description": "frame_fit: optional depth in centimetres.", "example": null } }, "required": [ "name" ] } }, "base_pricing": { "type": "object", "description": "The base pricing configuration.", "example": [], "properties": { "mode": { "type": "string", "description": "One of included_in_price_lists, single_base_price_by_size (simple_letter only), single_base_price_by_size_boundary (advanced_letter and frame_fit only).", "example": "included_in_price_lists" }, "rows": { "type": "array", "description": "The base price rows (empty for included_in_price_lists).", "example": [], "items": { "type": "object", "properties": { "size_id": { "type": "integer", "description": "simple_letter: the size this row prices (or use size_key).", "example": 7 }, "size_key": { "type": "string", "description": "simple_letter: the client_key of a size created in this request.", "example": null }, "base_price": { "type": "object", "description": "simple_letter: per-line non-negative amounts in integer minor units keyed line_1..line_10. For the boundary mode this field is a single integer amount instead.", "example": { "line_1": 900, "line_2": 1000, "line_3": 1100 }, "properties": {} }, "width_limit_cm": { "type": "number", "description": "Boundary mode: the width boundary in centimetres.", "example": null }, "height_limit_cm": { "type": "number", "description": "Boundary mode: the height boundary in centimetres.", "example": null }, "length_limit_cm": { "type": "number", "description": "Boundary mode: the length boundary in centimetres.", "example": null } } } } }, "required": [ "mode", "rows" ] }, "price_lists": { "type": "array", "description": "The complete price list collection. Lists omitted from it are deleted (refused with a 409 while fonts or settings still reference them). frame_fit requires exactly one list.", "example": [ [] ], "items": { "type": "object", "properties": { "price_list_id": { "type": "integer", "description": "The id of an existing price list to update. Omit (or null) to create a new list.", "example": 10 }, "name": { "type": "string", "description": "The price list's name.", "example": "Standard" }, "letter_pricing_method": { "type": "string", "description": "advanced_letter only (required there): material_length or fixed_letter.", "example": null }, "shipping": { "type": "object", "description": "advanced_letter and frame_fit (required there): the shipping configuration.", "example": [], "properties": { "calculation": { "type": "string", "description": "physical or volumetric.", "example": null }, "volumetric_divisor": { "type": "integer", "description": "Required for volumetric: the positive integer that divides width × height × length.", "example": null }, "add_weight_to_product": { "type": "boolean", "description": "Volumetric: emit the volumetric figure as product weight instead of a shipping charge.", "example": null } } }, "rows": { "type": "array", "description": "The list's pricing rows.", "example": [ [] ], "items": { "type": "object", "properties": { "size_id": { "type": "integer", "description": "simple_letter: the size this row prices (or use size_key).", "example": 7 }, "size_key": { "type": "string", "description": "simple_letter: the client_key of a size created in this request.", "example": null }, "base_price": { "type": "object", "description": "simple_letter: per-line non-negative amounts in integer minor units keyed line_1..line_10 (advanced_letter and frame_fit rows use a single integer amount instead).", "example": { "line_1": 1000, "line_2": 1200, "line_3": 1400 }, "properties": {} }, "letter_price": { "type": "object", "description": "simple_letter: per-letter per-line non-negative amounts in integer minor units keyed line_1..line_10.", "example": { "line_1": 100, "line_2": 120, "line_3": 140 }, "properties": {} }, "price_per_cm": { "type": "number", "description": "advanced_letter material_length: decimal major currency units per centimetre of material.", "example": null }, "price_per_letter": { "type": "integer", "description": "advanced_letter fixed_letter: integer minor units per letter.", "example": null }, "max_price_multiplier": { "type": "number", "description": "advanced_letter: optional cap multiplier.", "example": null }, "width_limit_cm": { "type": "number", "description": "The row's width band boundary in centimetres.", "example": null }, "height_limit_cm": { "type": "number", "description": "The row's height band boundary in centimetres.", "example": null }, "length_limit_cm": { "type": "number", "description": "The row's length band boundary in centimetres.", "example": null }, "price_per_sq_cm": { "type": "number", "description": "frame_fit: decimal major currency units per square centimetre.", "example": null }, "fixed_length_cm": { "type": "number", "description": "Advanced rows: fixed material length override in centimetres.", "example": null }, "width_modifier": { "type": "number", "description": "Shipping dimension modifier in centimetres.", "example": null }, "height_modifier": { "type": "number", "description": "Shipping dimension modifier in centimetres.", "example": null }, "length_modifier": { "type": "number", "description": "Shipping dimension modifier in centimetres.", "example": null } } } } }, "required": [ "name", "rows" ] } }, "sheet_pricing": { "type": "object", "description": "simple_letter only: the backing-sheet pricing section, or null to remove it.", "example": [], "properties": { "rows": { "type": "array", "description": "The sheet bands.", "example": [ [] ], "items": { "type": "object", "properties": { "width_limit_cm": { "type": "number", "description": "The band's width boundary in centimetres.", "example": null }, "height_limit_cm": { "type": "number", "description": "The band's height boundary in centimetres.", "example": null }, "base_price": { "type": "integer", "description": "The band's base amount in integer minor units.", "example": null }, "price_per_sq_cm": { "type": "number", "description": "Decimal major currency units per square centimetre.", "example": null } }, "required": [ "width_limit_cm", "height_limit_cm", "base_price", "price_per_sq_cm" ] } } } } }, "required": [ "sizes", "base_pricing", "price_lists" ] } } } } }, "patch": { "summary": "Update customiser pricing\n\nPartially update the customiser's pricing with a JSON Merge Patch\n(RFC 7396) of the canonical document: the request body is a JSON\nobject containing only the properties to change. Properties omitted\nfrom the patch are unchanged; a null value removes a property (for\nexample `{\"sheet_pricing\": null}` removes the backing-sheet section);\narrays are replaced wholesale — to change one size or price list row,\nsend the complete new array (each entry carrying its size_id or\nprice_list_id to update in place). A merge patch can never edit one\narray element by itself. The patched result is validated and persisted\nas a full replacement, so the field rules, read-only descriptor\nguards, deletion semantics, and error catalogue are exactly those of\nthe replace operation; field semantics and per-model document shapes\nare documented on the read operation. An empty object `{}` is a valid\nno-op. Requires the `pricing:write` scope.\n\nA successful update immediately reprices the storefront: the\ncustomiser's cached configuration is invalidated and translated\nlanguage content is resynchronised. Send an `Idempotency-Key` header\n(1-255 visible ASCII characters, e.g. a UUID) to make the write safe\nto retry: repeating the same key with the same body replays the\noriginal response (marked `Idempotency-Replay: true`) without\nexecuting again; the same key with a different body is a 409 problem\nwith code `idempotency_key_conflict`; keys are retained for at least\n24 hours and are scoped to your credential, the HTTP method, and the\npath.\n\nA 422 problem with code `invalid_document` means the patch body is not\na JSON object. All other failures match the replace operation:\n`validation_failed` (pointers into the patched document plus\n`allowed_values` on enum violations), `unknown_field`,\n`legacy_pricing_model`, 409 `resource_in_use`, 409 idempotency\nconflicts, 400 `malformed_json`, and 401/403/404/429.", "operationId": "updateCustomiserPricingPartiallyUpdateTheCustomisersPricingWithAJSONMergePatchRFC7396OfTheCanonicalDocumentTheRequestBodyIsAJSONObjectContainingOnlyThePropertiesToChangePropertiesOmittedFromThePatchAreUnchangedANullValueRemovesAPropertyforExamplesheetPricingNullRemovesTheBackingSheetSectionArraysAreReplacedWholesaleToChangeOneSizeOrPriceListRowSendTheCompleteNewArrayeachEntryCarryingItsSizeIdOrPriceListIdToUpdateInPlaceAMergePatchCanNeverEditOneArrayElementByItselfThePatchedResultIsValidatedAndPersistedAsAFullReplacementSoTheFieldRulesReadOnlyDescriptorGuardsDeletionSemanticsAndErrorCatalogueAreExactlyThoseOfTheReplaceOperationFieldSemanticsAndPerModelDocumentShapesAreDocumentedOnTheReadOperationAnEmptyObjectIsAValidNoOpRequiresThepricingwriteScopeASuccessfulUpdateImmediatelyRepricesTheStorefrontTheCustomisersCachedConfigurationIsInvalidatedAndTranslatedLanguageContentIsResynchronisedSendAnIdempotencyKeyHeader1255VisibleASCIICharactersEgAUUIDToMakeTheWriteSafeToRetryRepeatingTheSameKeyWithTheSameBodyReplaysTheOriginalResponsemarkedIdempotencyReplayTrueWithoutExecutingAgainTheSameKeyWithADifferentBodyIsA409ProblemWithCodeidempotencyKeyConflictKeysAreRetainedForAtLeast24HoursAndAreScopedToYourCredentialTheHTTPMethodAndThePathA422ProblemWithCodeinvalidDocumentMeansThePatchBodyIsNotAJSONObjectAllOtherFailuresMatchTheReplaceOperationvalidationFailedpointersIntoThePatchedDocumentPlusallowedValuesOnEnumViolationsunknownFieldlegacyPricingModel409resourceInUse409IdempotencyConflicts400malformedJsonAnd401403404429", "description": "", "responses": { "200": { "description": "Patched document", "content": { "application/json": { "schema": { "type": "object", "example": { "data": { "object": "customiser_pricing", "customiser_id": 42, "pricing_model": "simple_letter", "pricing_model_display_name": "Simple Letter", "currency": "USD", "sizes": [ { "size_id": 7, "client_key": null, "name": "Small", "description": "Up to 50cm wide", "sort_order": 1, "char_limit": 20, "line_limit": 3, "min_char": 1, "width_cm": 50, "height_cm": null, "line_height_cm": 12, "width_multiplier": null, "length_cm": null, "sizing_strategy": "fixed_width", "height_measurement_mode": "line_height" } ], "base_pricing": { "mode": "included_in_price_lists", "rows": [] }, "price_lists": [ { "price_list_id": 10, "name": "Standard", "rows": [ { "size_id": 7, "size_key": null, "base_price": { "line_1": 1000, "line_2": 1200, "line_3": 1400 }, "letter_price": { "line_1": 100, "line_2": 120, "line_3": 140 } } ] } ], "sheet_pricing": null }, "links": { "self": "https://web.signcustomiser.com/api/v3/customisers/42/pricing", "documentation": "https://www.signcustomiser.com/help/api/" }, "meta": { "api_version": "v3", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } }, "properties": { "data": { "type": "object", "properties": { "object": { "type": "string", "example": "customiser_pricing" }, "customiser_id": { "type": "integer", "example": 42 }, "pricing_model": { "type": "string", "example": "simple_letter" }, "pricing_model_display_name": { "type": "string", "example": "Simple Letter" }, "currency": { "type": "string", "example": "USD" }, "sizes": { "type": "array", "example": [ { "size_id": 7, "client_key": null, "name": "Small", "description": "Up to 50cm wide", "sort_order": 1, "char_limit": 20, "line_limit": 3, "min_char": 1, "width_cm": 50, "height_cm": null, "line_height_cm": 12, "width_multiplier": null, "length_cm": null, "sizing_strategy": "fixed_width", "height_measurement_mode": "line_height" } ], "items": { "type": "object", "properties": { "size_id": { "type": "integer", "example": 7 }, "client_key": { "type": [ "string", "null" ], "example": null }, "name": { "type": "string", "example": "Small" }, "description": { "type": "string", "example": "Up to 50cm wide" }, "sort_order": { "type": "integer", "example": 1 }, "char_limit": { "type": "integer", "example": 20 }, "line_limit": { "type": "integer", "example": 3 }, "min_char": { "type": "integer", "example": 1 }, "width_cm": { "type": "integer", "example": 50 }, "height_cm": { "type": [ "string", "null" ], "example": null }, "line_height_cm": { "type": "integer", "example": 12 }, "width_multiplier": { "type": [ "string", "null" ], "example": null }, "length_cm": { "type": [ "string", "null" ], "example": null }, "sizing_strategy": { "type": "string", "example": "fixed_width" }, "height_measurement_mode": { "type": "string", "example": "line_height" } } } }, "base_pricing": { "type": "object", "properties": { "mode": { "type": "string", "example": "included_in_price_lists" }, "rows": { "type": "array", "example": [] } } }, "price_lists": { "type": "array", "example": [ { "price_list_id": 10, "name": "Standard", "rows": [ { "size_id": 7, "size_key": null, "base_price": { "line_1": 1000, "line_2": 1200, "line_3": 1400 }, "letter_price": { "line_1": 100, "line_2": 120, "line_3": 140 } } ] } ], "items": { "type": "object", "properties": { "price_list_id": { "type": "integer", "example": 10 }, "name": { "type": "string", "example": "Standard" }, "rows": { "type": "array", "example": [ { "size_id": 7, "size_key": null, "base_price": { "line_1": 1000, "line_2": 1200, "line_3": 1400 }, "letter_price": { "line_1": 100, "line_2": 120, "line_3": 140 } } ], "items": { "type": "object", "properties": { "size_id": { "type": "integer", "example": 7 }, "size_key": { "type": [ "string", "null" ], "example": null }, "base_price": { "type": "object", "properties": { "line_1": { "type": "integer", "example": 1000 }, "line_2": { "type": "integer", "example": 1200 }, "line_3": { "type": "integer", "example": 1400 } } }, "letter_price": { "type": "object", "properties": { "line_1": { "type": "integer", "example": 100 }, "line_2": { "type": "integer", "example": 120 }, "line_3": { "type": "integer", "example": 140 } } } } } } } } }, "sheet_pricing": { "type": [ "string", "null" ], "example": null } } }, "links": { "type": "object", "properties": { "self": { "type": "string", "example": "https://web.signcustomiser.com/api/v3/customisers/42/pricing" }, "documentation": { "type": "string", "example": "https://www.signcustomiser.com/help/api/" } } }, "meta": { "type": "object", "properties": { "api_version": { "type": "string", "example": "v3" }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } } } }, "400": { "description": "Malformed JSON body", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/malformed_json", "title": "Malformed JSON", "status": 400, "code": "malformed_json", "detail": "The request body is not valid JSON: Syntax error.", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/malformed_json" }, "title": { "type": "string", "example": "Malformed JSON" }, "status": { "type": "integer", "example": 400 }, "code": { "type": "string", "example": "malformed_json" }, "detail": { "type": "string", "example": "The request body is not valid JSON: Syntax error." }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } }, "401": { "description": "Missing API key", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/missing_api_key", "title": "Missing API key", "status": 401, "code": "missing_api_key", "detail": "Provide a store API key as a bearer token: Authorization: Bearer . Keys are created in the merchant admin under Integrate → API Tokens.", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/missing_api_key" }, "title": { "type": "string", "example": "Missing API key" }, "status": { "type": "integer", "example": 401 }, "code": { "type": "string", "example": "missing_api_key" }, "detail": { "type": "string", "example": "Provide a store API key as a bearer token: Authorization: Bearer . Keys are created in the merchant admin under Integrate → API Tokens." }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/insufficient_scope", "title": "Insufficient scope", "status": 403, "code": "insufficient_scope", "detail": "This operation requires the pricing:write scope, but the API key grants the following scopes: pricing:read. Create a key that includes the required scope in the merchant admin under Integrate → API Tokens.", "required_scopes": [ "pricing:write" ], "granted_scopes": [ "pricing:read" ], "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/insufficient_scope" }, "title": { "type": "string", "example": "Insufficient scope" }, "status": { "type": "integer", "example": 403 }, "code": { "type": "string", "example": "insufficient_scope" }, "detail": { "type": "string", "example": "This operation requires the pricing:write scope, but the API key grants the following scopes: pricing:read. Create a key that includes the required scope in the merchant admin under Integrate → API Tokens." }, "required_scopes": { "type": "array", "example": [ "pricing:write" ], "items": { "type": "string" } }, "granted_scopes": { "type": "array", "example": [ "pricing:read" ], "items": { "type": "string" } }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } }, "404": { "description": "Unknown customiser", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/resource_not_found", "title": "Resource not found", "status": 404, "code": "resource_not_found", "detail": "The requested resource does not exist or does not belong to the authenticated store.", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/resource_not_found" }, "title": { "type": "string", "example": "Resource not found" }, "status": { "type": "integer", "example": 404 }, "code": { "type": "string", "example": "resource_not_found" }, "detail": { "type": "string", "example": "The requested resource does not exist or does not belong to the authenticated store." }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } }, "409": { "description": "Idempotency key conflict", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/idempotency_key_conflict", "title": "Idempotency key conflict", "status": 409, "code": "idempotency_key_conflict", "detail": "This Idempotency-Key was already used for a different request body on this operation. An idempotency key identifies one exact request: retry the original body to replay its response, or send the new body with a fresh key.", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/idempotency_key_conflict" }, "title": { "type": "string", "example": "Idempotency key conflict" }, "status": { "type": "integer", "example": 409 }, "code": { "type": "string", "example": "idempotency_key_conflict" }, "detail": { "type": "string", "example": "This Idempotency-Key was already used for a different request body on this operation. An idempotency key identifies one exact request: retry the original body to replay its response, or send the new body with a fresh key." }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "oneOf": [ { "description": "Patch is not an object", "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/invalid_document", "title": "Invalid document", "status": 422, "code": "invalid_document", "detail": "The merge patch must be a JSON object containing the pricing document properties to change (RFC 7396): omitted properties are unchanged, null removes a property, and arrays replace the current value wholesale.", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/invalid_document" }, "title": { "type": "string", "example": "Invalid document" }, "status": { "type": "integer", "example": 422 }, "code": { "type": "string", "example": "invalid_document" }, "detail": { "type": "string", "example": "The merge patch must be a JSON object containing the pricing document properties to change (RFC 7396): omitted properties are unchanged, null removes a property, and arrays replace the current value wholesale." }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } }, { "description": "Validation failed", "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/validation_failed", "title": "Validation failed", "status": 422, "code": "validation_failed", "detail": "The request payload failed validation. Correct the fields listed in errors and retry.", "errors": [ { "pointer": "/base_pricing", "code": "required", "detail": "The base pricing field is required." } ], "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/validation_failed" }, "title": { "type": "string", "example": "Validation failed" }, "status": { "type": "integer", "example": 422 }, "code": { "type": "string", "example": "validation_failed" }, "detail": { "type": "string", "example": "The request payload failed validation. Correct the fields listed in errors and retry." }, "errors": { "type": "array", "example": [ { "pointer": "/base_pricing", "code": "required", "detail": "The base pricing field is required." } ], "items": { "type": "object", "properties": { "pointer": { "type": "string", "example": "/base_pricing" }, "code": { "type": "string", "example": "required" }, "detail": { "type": "string", "example": "The base pricing field is required." } } } }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/rate_limited", "title": "Too many requests", "status": 429, "code": "rate_limited", "detail": "You have exceeded the request limit for this API key. Wait 60 seconds, then retry.", "retry_after": 60, "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/rate_limited" }, "title": { "type": "string", "example": "Too many requests" }, "status": { "type": "integer", "example": 429 }, "code": { "type": "string", "example": "rate_limited" }, "detail": { "type": "string", "example": "You have exceeded the request limit for this API key. Wait 60 seconds, then retry." }, "retry_after": { "type": "integer", "example": 60 }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } } }, "tags": [ "Pricing" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "base_pricing": { "type": "object", "description": "The properties of the pricing document to change — any subset of the canonical document (see the replace operation for the full field list). This example switches the base pricing mode.", "example": { "mode": "included_in_price_lists" }, "properties": {} } } } } } } } }, "/api/v3/customisers/{customiser_id}/pricing/validate": { "parameters": [ { "in": "path", "name": "customiser_id", "description": "The customiser id, from the list customisers operation.", "example": "1", "required": true, "schema": { "type": "integer" } } ], "post": { "summary": "Validate customiser pricing\n\nDry-run a pricing replacement without persisting anything. The request\nbody is the full canonical document, exactly as the replace operation\naccepts it, and the response is exactly what that replace would\nproduce: on an invalid document, the identical 422 problem\n(`validation_failed` with pointers and `allowed_values`,\n`unknown_field`, or `legacy_pricing_model`); on a document whose\nomissions would delete referenced records, the identical 409\n`resource_in_use` problem; and on a valid document, a 200\n`pricing_validation` confirmation — the same validation code path\nruns, only persistence is skipped. Nothing is written, no caches are\ntouched, and no idempotency key is consumed, so the operation is\nalways safe to repeat. To dry-run a PATCH, fetch the document, apply\nyour merge patch locally (RFC 7396), and validate the result.\nRequires the `pricing:write` scope (it is the write's dry-run twin).\n\nA 400 problem means the body is not valid JSON; a 422 problem with\ncode `invalid_document` means the body is not a JSON object.\n401/403/404/429 behave as on the read operation.", "operationId": "validateCustomiserPricingDryRunAPricingReplacementWithoutPersistingAnythingTheRequestBodyIsTheFullCanonicalDocumentExactlyAsTheReplaceOperationAcceptsItAndTheResponseIsExactlyWhatThatReplaceWouldProduceOnAnInvalidDocumentTheIdentical422ProblemvalidationFailedWithPointersAndallowedValuesunknownFieldOrlegacyPricingModelOnADocumentWhoseOmissionsWouldDeleteReferencedRecordsTheIdentical409resourceInUseProblemAndOnAValidDocumentA200pricingValidationConfirmationTheSameValidationCodePathRunsOnlyPersistenceIsSkippedNothingIsWrittenNoCachesAreTouchedAndNoIdempotencyKeyIsConsumedSoTheOperationIsAlwaysSafeToRepeatToDryRunAPATCHFetchTheDocumentApplyYourMergePatchLocallyRFC7396AndValidateTheResultRequiresThepricingwriteScopeitIsTheWritesDryRunTwinA400ProblemMeansTheBodyIsNotValidJSONA422ProblemWithCodeinvalidDocumentMeansTheBodyIsNotAJSONObject401403404429BehaveAsOnTheReadOperation", "description": "", "responses": { "200": { "description": "Document is valid", "content": { "application/json": { "schema": { "type": "object", "example": { "data": { "object": "pricing_validation", "customiser_id": 42, "valid": true }, "links": { "self": "https://web.signcustomiser.com/api/v3/customisers/42/pricing/validate", "documentation": "https://www.signcustomiser.com/help/api/" }, "meta": { "api_version": "v3", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } }, "properties": { "data": { "type": "object", "properties": { "object": { "type": "string", "example": "pricing_validation", "description": "The resource type discriminator. Always \"pricing_validation\" for this endpoint (closed set).", "enum": [ "pricing_validation" ] }, "customiser_id": { "type": "integer", "example": 42, "description": "The customiser the document was validated against." }, "valid": { "type": "boolean", "example": true, "description": "Always true — an invalid document returns the write's error response instead of a 200." } }, "required": [ "object", "customiser_id", "valid" ] }, "links": { "type": "object", "properties": { "self": { "type": "string", "example": "https://web.signcustomiser.com/api/v3/customisers/42/pricing/validate" }, "documentation": { "type": "string", "example": "https://www.signcustomiser.com/help/api/" } } }, "meta": { "type": "object", "properties": { "api_version": { "type": "string", "example": "v3" }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } } } }, "400": { "description": "Malformed JSON body", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/malformed_json", "title": "Malformed JSON", "status": 400, "code": "malformed_json", "detail": "The request body is not valid JSON: Syntax error.", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/malformed_json" }, "title": { "type": "string", "example": "Malformed JSON" }, "status": { "type": "integer", "example": 400 }, "code": { "type": "string", "example": "malformed_json" }, "detail": { "type": "string", "example": "The request body is not valid JSON: Syntax error." }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } }, "401": { "description": "Missing API key", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/missing_api_key", "title": "Missing API key", "status": 401, "code": "missing_api_key", "detail": "Provide a store API key as a bearer token: Authorization: Bearer . Keys are created in the merchant admin under Integrate → API Tokens.", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/missing_api_key" }, "title": { "type": "string", "example": "Missing API key" }, "status": { "type": "integer", "example": 401 }, "code": { "type": "string", "example": "missing_api_key" }, "detail": { "type": "string", "example": "Provide a store API key as a bearer token: Authorization: Bearer . Keys are created in the merchant admin under Integrate → API Tokens." }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/insufficient_scope", "title": "Insufficient scope", "status": 403, "code": "insufficient_scope", "detail": "This operation requires the pricing:write scope, but the API key grants the following scopes: pricing:read. Create a key that includes the required scope in the merchant admin under Integrate → API Tokens.", "required_scopes": [ "pricing:write" ], "granted_scopes": [ "pricing:read" ], "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/insufficient_scope" }, "title": { "type": "string", "example": "Insufficient scope" }, "status": { "type": "integer", "example": 403 }, "code": { "type": "string", "example": "insufficient_scope" }, "detail": { "type": "string", "example": "This operation requires the pricing:write scope, but the API key grants the following scopes: pricing:read. Create a key that includes the required scope in the merchant admin under Integrate → API Tokens." }, "required_scopes": { "type": "array", "example": [ "pricing:write" ], "items": { "type": "string" } }, "granted_scopes": { "type": "array", "example": [ "pricing:read" ], "items": { "type": "string" } }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } }, "404": { "description": "Unknown customiser", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/resource_not_found", "title": "Resource not found", "status": 404, "code": "resource_not_found", "detail": "The requested resource does not exist or does not belong to the authenticated store.", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/resource_not_found" }, "title": { "type": "string", "example": "Resource not found" }, "status": { "type": "integer", "example": 404 }, "code": { "type": "string", "example": "resource_not_found" }, "detail": { "type": "string", "example": "The requested resource does not exist or does not belong to the authenticated store." }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } }, "409": { "description": "Records still referenced", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/resource_in_use", "title": "Resource in use", "status": 409, "code": "resource_in_use", "detail": "The document omits sizes that fonts still reference, so the write would delete records in use. Keep those sizes in the document, or update the fonts that reference them first.", "errors": [ { "pointer": "/sizes", "code": "resource_in_use", "detail": "The document omits sizes that fonts still reference, so the write would delete records in use. Keep those sizes in the document, or update the fonts that reference them first." } ], "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/resource_in_use" }, "title": { "type": "string", "example": "Resource in use" }, "status": { "type": "integer", "example": 409 }, "code": { "type": "string", "example": "resource_in_use" }, "detail": { "type": "string", "example": "The document omits sizes that fonts still reference, so the write would delete records in use. Keep those sizes in the document, or update the fonts that reference them first." }, "errors": { "type": "array", "example": [ { "pointer": "/sizes", "code": "resource_in_use", "detail": "The document omits sizes that fonts still reference, so the write would delete records in use. Keep those sizes in the document, or update the fonts that reference them first." } ], "items": { "type": "object", "properties": { "pointer": { "type": "string", "example": "/sizes" }, "code": { "type": "string", "example": "resource_in_use" }, "detail": { "type": "string", "example": "The document omits sizes that fonts still reference, so the write would delete records in use. Keep those sizes in the document, or update the fonts that reference them first." } } } }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/validation_failed", "title": "Validation failed", "status": 422, "code": "validation_failed", "detail": "The request payload failed validation. Correct the fields listed in errors and retry.", "errors": [ { "pointer": "/sizes/0/sizing_strategy", "code": "unsupported_value", "detail": "The selected sizes.0.sizing_strategy is invalid.", "allowed_values": [ "fixed_width", "fixed_height" ] } ], "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/validation_failed" }, "title": { "type": "string", "example": "Validation failed" }, "status": { "type": "integer", "example": 422 }, "code": { "type": "string", "example": "validation_failed" }, "detail": { "type": "string", "example": "The request payload failed validation. Correct the fields listed in errors and retry." }, "errors": { "type": "array", "example": [ { "pointer": "/sizes/0/sizing_strategy", "code": "unsupported_value", "detail": "The selected sizes.0.sizing_strategy is invalid.", "allowed_values": [ "fixed_width", "fixed_height" ] } ], "items": { "type": "object", "properties": { "pointer": { "type": "string", "example": "/sizes/0/sizing_strategy" }, "code": { "type": "string", "example": "unsupported_value" }, "detail": { "type": "string", "example": "The selected sizes.0.sizing_strategy is invalid." }, "allowed_values": { "type": "array", "example": [ "fixed_width", "fixed_height" ], "items": { "type": "string" } } } } }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/rate_limited", "title": "Too many requests", "status": 429, "code": "rate_limited", "detail": "You have exceeded the request limit for this API key. Wait 60 seconds, then retry.", "retry_after": 60, "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/rate_limited" }, "title": { "type": "string", "example": "Too many requests" }, "status": { "type": "integer", "example": 429 }, "code": { "type": "string", "example": "rate_limited" }, "detail": { "type": "string", "example": "You have exceeded the request limit for this API key. Wait 60 seconds, then retry." }, "retry_after": { "type": "integer", "example": 60 }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } } }, "tags": [ "Pricing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sizes": { "type": "array", "description": "The full pricing document to check — the same body a replace operation would take (see that operation for the complete field list).", "example": [], "items": { "type": "object" } }, "base_pricing": { "type": "object", "description": "The base pricing configuration under test.", "example": { "mode": "included_in_price_lists", "rows": [] }, "properties": {} }, "price_lists": { "type": "array", "description": "The price lists under test.", "example": [], "items": { "type": "object" } } }, "required": [ "sizes", "base_pricing", "price_lists" ] } } } } } }, "/api/v3/products": { "parameters": [], "get": { "summary": "List products\n\nList the authenticated Store's modern products in descending creation\norder. Legacy ProductCache rows are excluded because they have a separate,\npotentially colliding identity. Each item contains integer minor-unit\nprices, the Store currency when valid, and ISO 8601 UTC timestamps. This\nread-only operation requires `products:read` and is safe to retry. A\nproduct `title` may contain customer-entered sign content, so protect API\nkeys with this scope accordingly.\n\nFollow `links.next` while `pagination.has_more` is true. Cursors are\nopaque and must be returned unchanged. No filters are supported. A 401\nmeans the API key is missing or invalid, 403 means it lacks the scope,\n422 means a parameter or cursor is invalid, and 429 should be retried\nafter the response's `retry_after` seconds.", "operationId": "listProductsListTheAuthenticatedStoresModernProductsInDescendingCreationOrderLegacyProductCacheRowsAreExcludedBecauseTheyHaveASeparatePotentiallyCollidingIdentityEachItemContainsIntegerMinorUnitPricesTheStoreCurrencyWhenValidAndISO8601UTCTimestampsThisReadOnlyOperationRequiresproductsreadAndIsSafeToRetryAProducttitleMayContainCustomerEnteredSignContentSoProtectAPIKeysWithThisScopeAccordinglyFollowlinksnextWhilepaginationhasMoreIsTrueCursorsAreOpaqueAndMustBeReturnedUnchangedNoFiltersAreSupportedA401MeansTheAPIKeyIsMissingOrInvalid403MeansItLacksTheScope422MeansAParameterOrCursorIsInvalidAnd429ShouldBeRetriedAfterTheResponsesretryAfterSeconds", "description": "", "parameters": [ { "in": "query", "name": "limit", "description": "Products per page, from 1 to 100. Defaults to 20.", "example": 2, "required": false, "schema": { "type": "integer", "description": "Products per page, from 1 to 100. Defaults to 20.", "example": 2 } }, { "in": "query", "name": "cursor", "description": "Opaque cursor from the previous page.", "example": null, "required": false, "schema": { "type": "string", "description": "Opaque cursor from the previous page.", "example": null } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "data": [ { "object": "product", "id": 731, "customiser_id": 42, "title": "Custom neon sign", "price_amount": 12900, "compare_at_amount": 14900, "currency": "AUD", "image_url": "https://cdn.example.com/products/731.png", "created_at": "2026-07-18T03:14:15Z", "updated_at": "2026-07-18T03:16:10Z" } ], "pagination": { "has_more": false, "next_cursor": null }, "links": { "self": "https://web.signcustomiser.com/api/v3/products", "documentation": "https://www.signcustomiser.com/help/api/", "next": null }, "meta": { "api_version": "v3", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } }, "properties": { "data": { "type": "array", "example": [ { "object": "product", "id": 731, "customiser_id": 42, "title": "Custom neon sign", "price_amount": 12900, "compare_at_amount": 14900, "currency": "AUD", "image_url": "https://cdn.example.com/products/731.png", "created_at": "2026-07-18T03:14:15Z", "updated_at": "2026-07-18T03:16:10Z" } ], "items": { "type": "object", "properties": { "object": { "type": "string", "example": "product" }, "id": { "type": "integer", "example": 731 }, "customiser_id": { "type": "integer", "example": 42 }, "title": { "type": [ "string", "null" ], "example": "Custom neon sign" }, "price_amount": { "type": "integer", "example": 12900 }, "compare_at_amount": { "type": [ "integer", "null" ], "example": 14900 }, "currency": { "type": [ "string", "null" ], "example": "AUD" }, "image_url": { "type": [ "string", "null" ], "example": "https://cdn.example.com/products/731.png" }, "created_at": { "type": [ "string", "null" ], "example": "2026-07-18T03:14:15Z" }, "updated_at": { "type": [ "string", "null" ], "example": "2026-07-18T03:16:10Z" } }, "required": [ "object", "id", "customiser_id", "title", "price_amount", "compare_at_amount", "currency", "image_url", "created_at", "updated_at" ] } }, "pagination": { "type": "object", "properties": { "has_more": { "type": "boolean", "example": false }, "next_cursor": { "type": [ "string", "null" ], "example": null } } }, "links": { "type": "object", "properties": { "self": { "type": "string", "example": "https://web.signcustomiser.com/api/v3/products" }, "documentation": { "type": "string", "example": "https://www.signcustomiser.com/help/api/" }, "next": { "type": [ "string", "null" ], "example": null } } }, "meta": { "type": "object", "properties": { "api_version": { "type": "string", "example": "v3" }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/missing_api_key", "title": "Missing API key", "status": 401, "code": "missing_api_key", "detail": "Provide a store API key as a bearer token.", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/missing_api_key" }, "title": { "type": "string", "example": "Missing API key" }, "status": { "type": "integer", "example": 401 }, "code": { "type": "string", "example": "missing_api_key" }, "detail": { "type": "string", "example": "Provide a store API key as a bearer token." }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/insufficient_scope", "title": "Insufficient scope", "status": 403, "code": "insufficient_scope", "detail": "This operation requires the products:read scope.", "required_scopes": [ "products:read" ], "granted_scopes": [], "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/insufficient_scope" }, "title": { "type": "string", "example": "Insufficient scope" }, "status": { "type": "integer", "example": 403 }, "code": { "type": "string", "example": "insufficient_scope" }, "detail": { "type": "string", "example": "This operation requires the products:read scope." }, "required_scopes": { "type": "array", "example": [ "products:read" ], "items": { "type": "string" } }, "granted_scopes": { "type": "array", "example": [] }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } }, "422": { "description": "Invalid parameter or cursor", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/invalid_parameter", "title": "Invalid query parameter", "status": 422, "code": "invalid_parameter", "detail": "The limit parameter must be an integer between 1 and 100.", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/invalid_parameter" }, "title": { "type": "string", "example": "Invalid query parameter" }, "status": { "type": "integer", "example": 422 }, "code": { "type": "string", "example": "invalid_parameter" }, "detail": { "type": "string", "example": "The limit parameter must be an integer between 1 and 100." }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/rate_limited", "title": "Too many requests", "status": 429, "code": "rate_limited", "detail": "You have exceeded the request limit for this API key.", "retry_after": 60, "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/rate_limited" }, "title": { "type": "string", "example": "Too many requests" }, "status": { "type": "integer", "example": 429 }, "code": { "type": "string", "example": "rate_limited" }, "detail": { "type": "string", "example": "You have exceeded the request limit for this API key." }, "retry_after": { "type": "integer", "example": 60 }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } } }, "tags": [ "Products" ] } }, "/api/v3/products/{product_id}": { "parameters": [ { "in": "path", "name": "product_id", "description": "Product id returned by the list operation.", "example": "731", "required": true, "schema": { "type": "integer" } } ], "get": { "summary": "Show a product\n\nReturn one modern product owned by the authenticated Store, including\ndimensions and safe public artwork URLs. `title` and `description` are\nStore product metadata and may contain customer-entered sign content, so\nprotect keys with `products:read`. ProductCache history, raw node data,\nprovider payloads, underlying upload paths, upload/contact names, tokens,\nand emails are never exposed. The operation is read-only.\nUnknown and foreign ids return the same 404. Remove unknown query\nparameters after a 422. Retry 429 responses after `retry_after` seconds.", "operationId": "showAProductReturnOneModernProductOwnedByTheAuthenticatedStoreIncludingDimensionsAndSafePublicArtworkURLstitleAnddescriptionAreStoreProductMetadataAndMayContainCustomerEnteredSignContentSoProtectKeysWithproductsreadProductCacheHistoryRawNodeDataProviderPayloadsUnderlyingUploadPathsUploadcontactNamesTokensAndEmailsAreNeverExposedTheOperationIsReadOnlyUnknownAndForeignIdsReturnTheSame404RemoveUnknownQueryParametersAfterA422Retry429ResponsesAfterretryAfterSeconds", "description": "", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "data": { "object": "product", "id": 731, "customiser_id": 42, "title": "Custom neon sign", "price_amount": 12900, "compare_at_amount": 14900, "currency": "AUD", "image_url": "https://cdn.example.com/products/731.png", "created_at": "2026-07-18T03:14:15Z", "updated_at": "2026-07-18T03:16:10Z", "description": "Made to order.", "width_cm": 80.5, "height_cm": 31.5, "length_cm": 2.5, "artwork": { "svg_url": "https://cdn.example.com/design.svg", "eps_url": "https://cdn.example.com/design.eps", "illustrator_pdf_url": "https://cdn.example.com/design.pdf" } }, "links": { "self": "https://web.signcustomiser.com/api/v3/products/731", "documentation": "https://www.signcustomiser.com/help/api/" }, "meta": { "api_version": "v3", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } }, "properties": { "data": { "type": "object", "properties": { "object": { "type": "string", "example": "product" }, "id": { "type": "integer", "example": 731 }, "customiser_id": { "type": "integer", "example": 42 }, "title": { "type": [ "string", "null" ], "example": "Custom neon sign" }, "price_amount": { "type": "integer", "example": 12900 }, "compare_at_amount": { "type": [ "integer", "null" ], "example": 14900 }, "currency": { "type": [ "string", "null" ], "example": "AUD" }, "image_url": { "type": [ "string", "null" ], "example": "https://cdn.example.com/products/731.png" }, "created_at": { "type": [ "string", "null" ], "example": "2026-07-18T03:14:15Z" }, "updated_at": { "type": [ "string", "null" ], "example": "2026-07-18T03:16:10Z" }, "description": { "type": [ "string", "null" ], "example": "Made to order." }, "width_cm": { "type": [ "number", "null" ], "example": 80.5 }, "height_cm": { "type": [ "number", "null" ], "example": 31.5 }, "length_cm": { "type": [ "number", "null" ], "example": 2.5 }, "artwork": { "type": [ "object", "null" ], "properties": { "svg_url": { "type": [ "string", "null" ], "example": "https://cdn.example.com/design.svg" }, "eps_url": { "type": [ "string", "null" ], "example": "https://cdn.example.com/design.eps" }, "illustrator_pdf_url": { "type": [ "string", "null" ], "example": "https://cdn.example.com/design.pdf" } }, "required": [ "svg_url", "eps_url", "illustrator_pdf_url" ] } }, "required": [ "object", "id", "customiser_id", "title", "price_amount", "compare_at_amount", "currency", "image_url", "created_at", "updated_at", "description", "width_cm", "height_cm", "length_cm", "artwork" ] }, "links": { "type": "object", "properties": { "self": { "type": "string", "example": "https://web.signcustomiser.com/api/v3/products/731" }, "documentation": { "type": "string", "example": "https://www.signcustomiser.com/help/api/" } } }, "meta": { "type": "object", "properties": { "api_version": { "type": "string", "example": "v3" }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/missing_api_key", "title": "Missing API key", "status": 401, "code": "missing_api_key", "detail": "Provide a store API key as a bearer token.", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/missing_api_key" }, "title": { "type": "string", "example": "Missing API key" }, "status": { "type": "integer", "example": 401 }, "code": { "type": "string", "example": "missing_api_key" }, "detail": { "type": "string", "example": "Provide a store API key as a bearer token." }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/insufficient_scope", "title": "Insufficient scope", "status": 403, "code": "insufficient_scope", "detail": "This operation requires the products:read scope.", "required_scopes": [ "products:read" ], "granted_scopes": [], "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/insufficient_scope" }, "title": { "type": "string", "example": "Insufficient scope" }, "status": { "type": "integer", "example": 403 }, "code": { "type": "string", "example": "insufficient_scope" }, "detail": { "type": "string", "example": "This operation requires the products:read scope." }, "required_scopes": { "type": "array", "example": [ "products:read" ], "items": { "type": "string" } }, "granted_scopes": { "type": "array", "example": [] }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } }, "404": { "description": "Unknown or foreign product", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/resource_not_found", "title": "Resource not found", "status": 404, "code": "resource_not_found", "detail": "The requested resource does not exist or does not belong to the authenticated store.", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/resource_not_found" }, "title": { "type": "string", "example": "Resource not found" }, "status": { "type": "integer", "example": 404 }, "code": { "type": "string", "example": "resource_not_found" }, "detail": { "type": "string", "example": "The requested resource does not exist or does not belong to the authenticated store." }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } }, "422": { "description": "Unknown query parameter", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/unknown_parameter", "title": "Unknown query parameter", "status": 422, "code": "unknown_parameter", "detail": "This endpoint accepts no query parameters.", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/unknown_parameter" }, "title": { "type": "string", "example": "Unknown query parameter" }, "status": { "type": "integer", "example": 422 }, "code": { "type": "string", "example": "unknown_parameter" }, "detail": { "type": "string", "example": "This endpoint accepts no query parameters." }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/rate_limited", "title": "Too many requests", "status": 429, "code": "rate_limited", "detail": "You have exceeded the request limit for this API key.", "retry_after": 60, "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/rate_limited" }, "title": { "type": "string", "example": "Too many requests" }, "status": { "type": "integer", "example": 429 }, "code": { "type": "string", "example": "rate_limited" }, "detail": { "type": "string", "example": "You have exceeded the request limit for this API key." }, "retry_after": { "type": "integer", "example": 60 }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } } }, "tags": [ "Products" ] } }, "/api/v3/products/{product_id}/selections": { "parameters": [ { "in": "path", "name": "product_id", "description": "Product id returned by the list operation.", "example": "731", "required": true, "schema": { "type": "integer" } } ], "get": { "summary": "Show product selections\n\nReturn the Store-local option ids captured for a modern product. Stable\ninteger `value` fields are separate from merchant-editable\n`display_name` labels. Canonical axes include `letter_type` and\n`support_finish`; the latter may report `finish_kind` and `colour_hex`.\nLookups are restricted to the product customiser, so stale or foreign\noption ids become null or are omitted. Requires `products:read` and has no\nside effects. Unknown and foreign product ids share one 404 response.", "operationId": "showProductSelectionsReturnTheStoreLocalOptionIdsCapturedForAModernProductStableIntegervalueFieldsAreSeparateFromMerchantEditabledisplayNameLabelsCanonicalAxesIncludeletterTypeAndsupportFinishTheLatterMayReportfinishKindAndcolourHexLookupsAreRestrictedToTheProductCustomiserSoStaleOrForeignOptionIdsBecomeNullOrAreOmittedRequiresproductsreadAndHasNoSideEffectsUnknownAndForeignProductIdsShareOne404Response", "description": "", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "data": { "object": "product_selections", "product_id": 731, "letter_type": { "value": 18, "display_name": "Front and halo lit" }, "size": { "value": 9, "display_name": "Medium", "width_cm": 80.5, "height_cm": 31.5, "length_cm": 2.5 }, "support": { "value": 4, "display_name": "Cut to shape" }, "support_finish": { "value": 27, "display_name": "Gloss black", "finish_kind": "colour", "colour_hex": "#111111" }, "jacket": { "value": 3, "display_name": "White jacket" }, "mounting": { "value": 6, "display_name": "Wall mounted" }, "mounting_colour": { "value": 7, "display_name": "Black" }, "backlight": { "value": 8, "display_name": "Warm white" }, "material": { "value": 9, "display_name": "Acrylic" }, "colours": [ { "value": 12, "display_name": "Warm white" } ], "fonts": [ { "value": 5, "display_name": "Signature" } ] }, "links": { "self": "https://web.signcustomiser.com/api/v3/products/731/selections", "documentation": "https://www.signcustomiser.com/help/api/" }, "meta": { "api_version": "v3", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } }, "properties": { "data": { "type": "object", "properties": { "object": { "type": "string", "example": "product_selections" }, "product_id": { "type": "integer", "example": 731 }, "letter_type": { "type": [ "object", "null" ], "properties": { "value": { "type": "integer", "example": 18 }, "display_name": { "type": [ "string", "null" ], "example": "Front and halo lit" } }, "required": [ "value", "display_name" ] }, "size": { "type": [ "object", "null" ], "properties": { "value": { "type": "integer", "example": 9 }, "display_name": { "type": [ "string", "null" ], "example": "Medium" }, "width_cm": { "type": [ "number", "null" ], "example": 80.5 }, "height_cm": { "type": [ "number", "null" ], "example": 31.5 }, "length_cm": { "type": [ "number", "null" ], "example": 2.5 } }, "required": [ "value", "display_name", "width_cm", "height_cm", "length_cm" ] }, "support": { "type": [ "object", "null" ], "properties": { "value": { "type": "integer", "example": 4 }, "display_name": { "type": [ "string", "null" ], "example": "Cut to shape" } }, "required": [ "value", "display_name" ] }, "support_finish": { "type": [ "object", "null" ], "properties": { "value": { "type": "integer", "example": 27 }, "display_name": { "type": [ "string", "null" ], "example": "Gloss black" }, "finish_kind": { "type": [ "string", "null" ], "example": "colour", "description": "The finish kind. This set is expected to grow; tolerate unknown values.", "enum": [ "colour", "texture", null ] }, "colour_hex": { "type": [ "string", "null" ], "example": "#111111" } }, "required": [ "value", "display_name", "finish_kind", "colour_hex" ] }, "jacket": { "type": [ "object", "null" ], "properties": { "value": { "type": "integer", "example": 3 }, "display_name": { "type": [ "string", "null" ], "example": "White jacket" } }, "required": [ "value", "display_name" ] }, "mounting": { "type": [ "object", "null" ], "properties": { "value": { "type": "integer", "example": 6 }, "display_name": { "type": [ "string", "null" ], "example": "Wall mounted" } }, "required": [ "value", "display_name" ] }, "mounting_colour": { "type": [ "object", "null" ], "properties": { "value": { "type": "integer", "example": 7 }, "display_name": { "type": [ "string", "null" ], "example": "Black" } }, "required": [ "value", "display_name" ] }, "backlight": { "type": [ "object", "null" ], "properties": { "value": { "type": "integer", "example": 8 }, "display_name": { "type": [ "string", "null" ], "example": "Warm white" } }, "required": [ "value", "display_name" ] }, "material": { "type": [ "object", "null" ], "properties": { "value": { "type": "integer", "example": 9 }, "display_name": { "type": [ "string", "null" ], "example": "Acrylic" } }, "required": [ "value", "display_name" ] }, "colours": { "type": "array", "example": [ { "value": 12, "display_name": "Warm white" } ], "items": { "type": "object", "properties": { "value": { "type": "integer", "example": 12 }, "display_name": { "type": [ "string", "null" ], "example": "Warm white" } }, "required": [ "value", "display_name" ] } }, "fonts": { "type": "array", "example": [ { "value": 5, "display_name": "Signature" } ], "items": { "type": "object", "properties": { "value": { "type": "integer", "example": 5 }, "display_name": { "type": [ "string", "null" ], "example": "Signature" } }, "required": [ "value", "display_name" ] } } }, "required": [ "object", "product_id", "letter_type", "size", "support", "support_finish", "jacket", "mounting", "mounting_colour", "backlight", "material", "colours", "fonts" ] }, "links": { "type": "object", "properties": { "self": { "type": "string", "example": "https://web.signcustomiser.com/api/v3/products/731/selections" }, "documentation": { "type": "string", "example": "https://www.signcustomiser.com/help/api/" } } }, "meta": { "type": "object", "properties": { "api_version": { "type": "string", "example": "v3" }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/missing_api_key", "title": "Missing API key", "status": 401, "code": "missing_api_key", "detail": "Provide a store API key as a bearer token.", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/missing_api_key" }, "title": { "type": "string", "example": "Missing API key" }, "status": { "type": "integer", "example": 401 }, "code": { "type": "string", "example": "missing_api_key" }, "detail": { "type": "string", "example": "Provide a store API key as a bearer token." }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/insufficient_scope", "title": "Insufficient scope", "status": 403, "code": "insufficient_scope", "detail": "This operation requires the products:read scope.", "required_scopes": [ "products:read" ], "granted_scopes": [], "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/insufficient_scope" }, "title": { "type": "string", "example": "Insufficient scope" }, "status": { "type": "integer", "example": 403 }, "code": { "type": "string", "example": "insufficient_scope" }, "detail": { "type": "string", "example": "This operation requires the products:read scope." }, "required_scopes": { "type": "array", "example": [ "products:read" ], "items": { "type": "string" } }, "granted_scopes": { "type": "array", "example": [] }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } }, "404": { "description": "Unknown or foreign product", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/resource_not_found", "title": "Resource not found", "status": 404, "code": "resource_not_found", "detail": "The requested resource does not exist or does not belong to the authenticated store.", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/resource_not_found" }, "title": { "type": "string", "example": "Resource not found" }, "status": { "type": "integer", "example": 404 }, "code": { "type": "string", "example": "resource_not_found" }, "detail": { "type": "string", "example": "The requested resource does not exist or does not belong to the authenticated store." }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } }, "422": { "description": "Unknown query parameter", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/unknown_parameter", "title": "Unknown query parameter", "status": 422, "code": "unknown_parameter", "detail": "This endpoint accepts no query parameters.", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/unknown_parameter" }, "title": { "type": "string", "example": "Unknown query parameter" }, "status": { "type": "integer", "example": 422 }, "code": { "type": "string", "example": "unknown_parameter" }, "detail": { "type": "string", "example": "This endpoint accepts no query parameters." }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/rate_limited", "title": "Too many requests", "status": 429, "code": "rate_limited", "detail": "You have exceeded the request limit for this API key.", "retry_after": 60, "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/rate_limited" }, "title": { "type": "string", "example": "Too many requests" }, "status": { "type": "integer", "example": 429 }, "code": { "type": "string", "example": "rate_limited" }, "detail": { "type": "string", "example": "You have exceeded the request limit for this API key." }, "retry_after": { "type": "integer", "example": 60 }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } } }, "tags": [ "Products" ] } }, "/api/v3/customisers/{customiser_id}/products": { "parameters": [ { "in": "path", "name": "customiser_id", "description": "Store customiser receiving the product.", "example": "1", "required": true, "schema": { "type": "integer" } } ], "post": { "summary": "Synchronise a product\n\nStore one product created by an enabled custom integration for the\nauthenticated Store and customiser. The response returns the modern\nproduct id used by order line items. Sign Customiser also creates a\nprivate compatibility projection for the established manufacturer email\nand export paths. This inbound operation never downloads remote artwork,\ncalls the integration callback, or emits the product-created webhook.\nRequires `products:write`.\n\n`integration_id` must identify an enabled custom integration belonging to\nthe Store. `store_product_id` is the integration's stable external id. This\nv3 operation rejects an id already present in the Store and serialises\nconcurrent v3 synchronisations. During migration, do not send the same\nlogical product through legacy and v3 writes in parallel. Money is integer\nminor units and `currency` must equal the Store currency. Artwork\nreferences must be credential-free HTTPS URLs no longer than 255\ncharacters; they are stored as references and are not fetched during this\nrequest.\n\nSend a unique `Idempotency-Key` for each logical product. Repeating the\nexact method, path, body, credential, and key replays the original 201\nresponse with `Idempotency-Replay: true` and does not create another\nproduct. A 409 `idempotency_key_in_flight` is safe to retry with the same\nkey after `retry_after`; a key/body conflict needs a new key or the original\nbody. Correct every pointer reported by a 422 before retrying.", "operationId": "synchroniseAProductStoreOneProductCreatedByAnEnabledCustomIntegrationForTheAuthenticatedStoreAndCustomiserTheResponseReturnsTheModernProductIdUsedByOrderLineItemsSignCustomiserAlsoCreatesAPrivateCompatibilityProjectionForTheEstablishedManufacturerEmailAndExportPathsThisInboundOperationNeverDownloadsRemoteArtworkCallsTheIntegrationCallbackOrEmitsTheProductCreatedWebhookRequiresproductswriteintegrationIdMustIdentifyAnEnabledCustomIntegrationBelongingToTheStorestoreProductIdIsTheIntegrationsStableExternalIdThisV3OperationRejectsAnIdAlreadyPresentInTheStoreAndSerialisesConcurrentV3SynchronisationsDuringMigrationDoNotSendTheSameLogicalProductThroughLegacyAndV3WritesInParallelMoneyIsIntegerMinorUnitsAndcurrencyMustEqualTheStoreCurrencyArtworkReferencesMustBeCredentialFreeHTTPSURLsNoLongerThan255CharactersTheyAreStoredAsReferencesAndAreNotFetchedDuringThisRequestSendAUniqueIdempotencyKeyForEachLogicalProductRepeatingTheExactMethodPathBodyCredentialAndKeyReplaysTheOriginal201ResponseWithIdempotencyReplayTrueAndDoesNotCreateAnotherProductA409idempotencyKeyInFlightIsSafeToRetryWithTheSameKeyAfterretryAfterAKeybodyConflictNeedsANewKeyOrTheOriginalBodyCorrectEveryPointerReportedByA422BeforeRetrying", "description": "", "parameters": [ { "in": "header", "name": "Idempotency-Key", "description": "", "example": "8cde76ce-10e9-4fc2-9d31-93af24277e9f", "schema": { "type": "string" }, "required": true } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "data": { "object": "product", "id": 731, "customiser_id": 42, "title": "Custom neon sign", "price_amount": 12900, "compare_at_amount": 14900, "currency": "AUD", "image_url": null, "created_at": "2026-07-19T09:15:00Z", "updated_at": "2026-07-19T09:15:00Z", "description": "Made to order.", "width_cm": 80.5, "height_cm": 31.5, "length_cm": 2.5, "artwork": null }, "links": { "self": "https://web.signcustomiser.com/api/v3/products/731", "documentation": "https://www.signcustomiser.com/help/api/" }, "meta": { "api_version": "v3", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } }, "properties": { "data": { "type": "object", "properties": { "object": { "type": "string", "example": "product" }, "id": { "type": "integer", "example": 731 }, "customiser_id": { "type": "integer", "example": 42 }, "title": { "type": [ "string", "null" ], "example": "Custom neon sign" }, "price_amount": { "type": "integer", "example": 12900 }, "compare_at_amount": { "type": [ "integer", "null" ], "example": 14900 }, "currency": { "type": [ "string", "null" ], "example": "AUD" }, "image_url": { "type": [ "string", "null" ], "example": null }, "created_at": { "type": [ "string", "null" ], "example": "2026-07-19T09:15:00Z" }, "updated_at": { "type": [ "string", "null" ], "example": "2026-07-19T09:15:00Z" }, "description": { "type": [ "string", "null" ], "example": "Made to order." }, "width_cm": { "type": [ "number", "null" ], "example": 80.5 }, "height_cm": { "type": [ "number", "null" ], "example": 31.5 }, "length_cm": { "type": [ "number", "null" ], "example": 2.5 }, "artwork": { "type": [ "object", "null" ], "example": null } }, "required": [ "object", "id", "customiser_id", "title", "price_amount", "compare_at_amount", "currency", "image_url", "created_at", "updated_at", "description", "width_cm", "height_cm", "length_cm", "artwork" ] }, "links": { "type": "object", "properties": { "self": { "type": "string", "example": "https://web.signcustomiser.com/api/v3/products/731" }, "documentation": { "type": "string", "example": "https://www.signcustomiser.com/help/api/" } }, "required": [ "self", "documentation" ] }, "meta": { "type": "object", "properties": { "api_version": { "type": "string", "example": "v3" }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } }, "required": [ "api_version", "request_id" ] } }, "required": [ "data", "links", "meta" ] } } } }, "400": { "description": "Missing idempotency key", "content": { "application/problem+json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/missing_idempotency_key", "title": "Missing idempotency key", "status": 400, "code": "missing_idempotency_key", "detail": "Provide an Idempotency-Key header for this write operation.", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/missing_idempotency_key" }, "title": { "type": "string", "example": "Missing idempotency key" }, "status": { "type": "integer", "example": 400 }, "code": { "type": "string", "example": "missing_idempotency_key" }, "detail": { "type": "string", "example": "Provide an Idempotency-Key header for this write operation." }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } }, "required": [ "type", "title", "status", "code", "detail", "request_id" ] } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/missing_api_key", "title": "Missing API key", "status": 401, "code": "missing_api_key", "detail": "Provide a store API key as a bearer token.", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/missing_api_key" }, "title": { "type": "string", "example": "Missing API key" }, "status": { "type": "integer", "example": 401 }, "code": { "type": "string", "example": "missing_api_key" }, "detail": { "type": "string", "example": "Provide a store API key as a bearer token." }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } }, "required": [ "type", "title", "status", "code", "detail", "request_id" ] } } } }, "403": { "description": "Insufficient scope", "content": { "application/problem+json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/insufficient_scope", "title": "Insufficient scope", "status": 403, "code": "insufficient_scope", "detail": "This operation requires the products:write scope.", "required_scopes": [ "products:write" ], "granted_scopes": [ "products:read" ], "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/insufficient_scope" }, "title": { "type": "string", "example": "Insufficient scope" }, "status": { "type": "integer", "example": 403 }, "code": { "type": "string", "example": "insufficient_scope" }, "detail": { "type": "string", "example": "This operation requires the products:write scope." }, "required_scopes": { "type": "array", "example": [ "products:write" ], "items": { "type": "string" } }, "granted_scopes": { "type": "array", "example": [ "products:read" ], "items": { "type": "string" } }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } }, "required": [ "type", "title", "status", "code", "detail", "request_id" ] } } } }, "404": { "description": "Unknown or foreign resource", "content": { "application/problem+json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/resource_not_found", "title": "Resource not found", "status": 404, "code": "resource_not_found", "detail": "The requested resource does not exist or does not belong to the authenticated store.", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/resource_not_found" }, "title": { "type": "string", "example": "Resource not found" }, "status": { "type": "integer", "example": 404 }, "code": { "type": "string", "example": "resource_not_found" }, "detail": { "type": "string", "example": "The requested resource does not exist or does not belong to the authenticated store." }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } }, "required": [ "type", "title", "status", "code", "detail", "request_id" ] } } } }, "409": { "description": "External product already exists", "content": { "application/problem+json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/store_product_id_conflict", "title": "Store product ID conflict", "status": 409, "code": "store_product_id_conflict", "detail": "This Store has already synchronised a product with the supplied store_product_id. Retry the original request with its original Idempotency-Key, or use a new store_product_id.", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/store_product_id_conflict" }, "title": { "type": "string", "example": "Store product ID conflict" }, "status": { "type": "integer", "example": 409 }, "code": { "type": "string", "example": "store_product_id_conflict" }, "detail": { "type": "string", "example": "This Store has already synchronised a product with the supplied store_product_id. Retry the original request with its original Idempotency-Key, or use a new store_product_id." }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } }, "required": [ "type", "title", "status", "code", "detail", "request_id" ] } } } }, "413": { "description": "Request body too large", "content": { "application/problem+json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/request_too_large", "title": "Request too large", "status": 413, "code": "request_too_large", "detail": "The request body must not exceed 2 MiB.", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/request_too_large" }, "title": { "type": "string", "example": "Request too large" }, "status": { "type": "integer", "example": 413 }, "code": { "type": "string", "example": "request_too_large" }, "detail": { "type": "string", "example": "The request body must not exceed 2 MiB." }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } }, "required": [ "type", "title", "status", "code", "detail", "request_id" ] } } } }, "422": { "description": "Invalid request field", "content": { "application/problem+json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/validation_failed", "title": "Validation failed", "status": 422, "code": "validation_failed", "detail": "One or more request fields are invalid.", "errors": [ { "parameter": "currency", "pointer": "/currency", "code": "invalid_field", "detail": "The currency must match the authenticated Store currency." } ], "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/validation_failed" }, "title": { "type": "string", "example": "Validation failed" }, "status": { "type": "integer", "example": 422 }, "code": { "type": "string", "example": "validation_failed" }, "detail": { "type": "string", "example": "One or more request fields are invalid." }, "errors": { "type": "array", "example": [ { "parameter": "currency", "pointer": "/currency", "code": "invalid_field", "detail": "The currency must match the authenticated Store currency." } ], "items": { "type": "object", "properties": { "parameter": { "type": "string", "example": "currency" }, "pointer": { "type": "string", "example": "/currency" }, "code": { "type": "string", "example": "invalid_field" }, "detail": { "type": "string", "example": "The currency must match the authenticated Store currency." } } } }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } }, "required": [ "type", "title", "status", "code", "detail", "request_id" ] } } } }, "429": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/rate_limited", "title": "Too many requests", "status": 429, "code": "rate_limited", "detail": "You have exceeded the request limit for this API key.", "retry_after": 60, "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/rate_limited" }, "title": { "type": "string", "example": "Too many requests" }, "status": { "type": "integer", "example": 429 }, "code": { "type": "string", "example": "rate_limited" }, "detail": { "type": "string", "example": "You have exceeded the request limit for this API key." }, "retry_after": { "type": "integer", "example": 60 }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } }, "required": [ "type", "title", "status", "code", "detail", "request_id" ] } } } } }, "tags": [ "Products" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "integration_id": { "type": "integer", "description": "Enabled custom integration id belonging to the Store.", "example": 17 }, "store_product_id": { "type": "string", "description": "Stable product id in the integration.", "example": "ext-product-1001" }, "title": { "type": "string", "description": "Product title.", "example": "Custom neon sign" }, "description": { "type": [ "string", "null" ], "description": "Product description, up to 10,000 characters.", "example": "Made to order." }, "price_amount": { "type": "integer", "description": "Unit price in minor currency units.", "example": 12900 }, "compare_at_amount": { "type": [ "integer", "null" ], "description": "Nullable comparison price in minor units; when supplied it cannot be lower than price_amount.", "example": 14900 }, "currency": { "type": "string", "description": "Uppercase ISO 4217 Store currency.", "example": "AUD" }, "width_cm": { "type": [ "number", "null" ], "description": "Nullable finished width in centimetres.", "example": 80.5 }, "height_cm": { "type": [ "number", "null" ], "description": "Nullable finished height in centimetres.", "example": 31.5 }, "length_cm": { "type": [ "number", "null" ], "description": "Nullable finished depth or length in centimetres.", "example": 2.5 }, "customisations": { "type": [ "array", "null" ], "description": "Nullable canonical customer selections; keys must be unique snake_case strings.", "example": [ { "key": "sign_text", "label": "Sign text", "value": "Hello" } ], "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Stable snake_case selection key. `size_cm` and `size_in` cannot be combined with first-class dimensions.", "example": "sign_text" }, "label": { "type": "string", "description": "Human-readable selection label.", "example": "Sign text" }, "value": { "type": "string", "description": "Captured selection value.", "example": "Hello" } }, "required": [ "key", "label", "value" ], "additionalProperties": false } }, "artwork": { "type": [ "object", "null" ], "description": "Nullable artwork references.", "example": { "preview_image_url": "https://cdn.example.com/sign.png", "svg_url": "https://cdn.example.com/sign.svg" }, "properties": { "preview_image_url": { "type": [ "string", "null" ], "description": "Nullable HTTPS customer preview URL.", "example": "https://cdn.example.com/sign.png" }, "outline_image_url": { "type": [ "string", "null" ], "description": "Nullable HTTPS outline preview URL.", "example": "https://cdn.example.com/sign-outline.png" }, "svg_url": { "type": [ "string", "null" ], "description": "Nullable HTTPS SVG artwork URL.", "example": "https://cdn.example.com/sign.svg" }, "eps_url": { "type": [ "string", "null" ], "description": "Nullable HTTPS EPS artwork URL.", "example": "https://cdn.example.com/sign.eps" }, "illustrator_pdf_url": { "type": [ "string", "null" ], "description": "Nullable HTTPS Illustrator PDF URL.", "example": "https://cdn.example.com/sign.pdf" }, "dxf_url": { "type": [ "string", "null" ], "description": "Nullable HTTPS DXF artwork URL.", "example": "https://cdn.example.com/sign.dxf" }, "custom_background_url": { "type": [ "string", "null" ], "description": "Nullable HTTPS processed custom background URL.", "example": "https://cdn.example.com/background.png" }, "custom_background_original_url": { "type": [ "string", "null" ], "description": "Nullable HTTPS original custom background URL.", "example": "https://cdn.example.com/background-original.png" }, "source_file_url": { "type": [ "string", "null" ], "description": "Nullable HTTPS source artwork URL.", "example": "https://cdn.example.com/source.ai" } }, "additionalProperties": false } }, "required": [ "integration_id", "store_product_id", "title", "price_amount", "currency" ], "additionalProperties": false } } } } } }, "/api/v3/stores/me/subscription": { "parameters": [], "get": { "summary": "Get the Store subscription\n\nReturn the authenticated Store's current local subscription projection.\nThe same provider-neutral contract covers Universal and Shopify Stores,\nwith a stable machine `plan`, separate display name, billing interval,\nrenewal intent, and known trial or end timestamps. Status is expected to\ngrow. Provider ids, payment details, test flags, customer details, and raw\nprovider objects are never exposed or fetched. Requires `store:read`; this\noperation is read-only and safe to retry.\n\nThis endpoint accepts no query parameters. A 401 means the key is missing\nor invalid. A 403 means it lacks `store:read`; create a correctly scoped\nkey. Remove parameters after a 422. Retry a 429 after `retry_after`\nseconds.", "operationId": "getTheStoreSubscriptionReturnTheAuthenticatedStoresCurrentLocalSubscriptionProjectionTheSameProviderNeutralContractCoversUniversalAndShopifyStoresWithAStableMachineplanSeparateDisplayNameBillingIntervalRenewalIntentAndKnownTrialOrEndTimestampsStatusIsExpectedToGrowProviderIdsPaymentDetailsTestFlagsCustomerDetailsAndRawProviderObjectsAreNeverExposedOrFetchedRequiresstorereadThisOperationIsReadOnlyAndSafeToRetryThisEndpointAcceptsNoQueryParametersA401MeansTheKeyIsMissingOrInvalidA403MeansItLacksstorereadCreateACorrectlyScopedKeyRemoveParametersAfterA422RetryA429AfterretryAfterSeconds", "description": "", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "data": { "object": "subscription", "status": "active", "plan": "seed", "plan_display_name": "Seed", "billing_interval": "monthly", "recurring": true, "trial_ends_at": null, "ends_at": null }, "links": { "self": "https://web.signcustomiser.com/api/v3/stores/me/subscription", "documentation": "https://www.signcustomiser.com/help/api/" }, "meta": { "api_version": "v3", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } }, "properties": { "data": { "type": "object", "properties": { "object": { "type": "string", "example": "subscription" }, "status": { "type": "string", "example": "active", "description": "Current provider-neutral subscription status. This set is expected to grow; tolerate unknown values.", "enum": [ "none", "trialing", "active", "past_due", "incomplete", "unpaid", "cancelling", "cancelled", "unknown" ] }, "plan": { "type": [ "string", "null" ], "example": "seed", "description": "Lowercase Store plan identifier, or null. Plan identifiers are expected to grow; tolerate unknown values." }, "plan_display_name": { "type": [ "string", "null" ], "example": "Seed" }, "billing_interval": { "type": [ "string", "null" ], "example": "monthly", "description": "Closed billing interval when a local Plan is known.", "enum": [ "monthly", "yearly", null ] }, "recurring": { "type": "boolean", "example": true }, "trial_ends_at": { "type": [ "string", "null" ], "example": null }, "ends_at": { "type": [ "string", "null" ], "example": null } }, "required": [ "object", "status", "plan", "plan_display_name", "billing_interval", "recurring", "trial_ends_at", "ends_at" ] }, "links": { "type": "object", "properties": { "self": { "type": "string", "example": "https://web.signcustomiser.com/api/v3/stores/me/subscription" }, "documentation": { "type": "string", "example": "https://www.signcustomiser.com/help/api/" } } }, "meta": { "type": "object", "properties": { "api_version": { "type": "string", "example": "v3" }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/missing_api_key", "title": "Missing API key", "status": 401, "code": "missing_api_key", "detail": "Provide a store API key as a bearer token.", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/missing_api_key" }, "title": { "type": "string", "example": "Missing API key" }, "status": { "type": "integer", "example": 401 }, "code": { "type": "string", "example": "missing_api_key" }, "detail": { "type": "string", "example": "Provide a store API key as a bearer token." }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/insufficient_scope", "title": "Insufficient scope", "status": 403, "code": "insufficient_scope", "detail": "This operation requires the store:read scope.", "required_scopes": [ "store:read" ], "granted_scopes": [], "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/insufficient_scope" }, "title": { "type": "string", "example": "Insufficient scope" }, "status": { "type": "integer", "example": 403 }, "code": { "type": "string", "example": "insufficient_scope" }, "detail": { "type": "string", "example": "This operation requires the store:read scope." }, "required_scopes": { "type": "array", "example": [ "store:read" ], "items": { "type": "string" } }, "granted_scopes": { "type": "array", "example": [] }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } }, "422": { "description": "Unknown query parameter", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/unknown_parameter", "title": "Unknown query parameter", "status": 422, "code": "unknown_parameter", "detail": "This endpoint accepts no query parameters.", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/unknown_parameter" }, "title": { "type": "string", "example": "Unknown query parameter" }, "status": { "type": "integer", "example": 422 }, "code": { "type": "string", "example": "unknown_parameter" }, "detail": { "type": "string", "example": "This endpoint accepts no query parameters." }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/rate_limited", "title": "Too many requests", "status": 429, "code": "rate_limited", "detail": "You have exceeded the request limit for this API key.", "retry_after": 60, "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/rate_limited" }, "title": { "type": "string", "example": "Too many requests" }, "status": { "type": "integer", "example": 429 }, "code": { "type": "string", "example": "rate_limited" }, "detail": { "type": "string", "example": "You have exceeded the request limit for this API key." }, "retry_after": { "type": "integer", "example": 60 }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } } }, "tags": [ "Store" ] } }, "/api/v3/stores/me": { "parameters": [], "get": { "summary": "Get the authenticated store\n\nIdentify the store your API key belongs to. Call this first: it confirms\nthe key works, tells you which store you are operating on, whether the\nstore runs on the `shopify` or `universal` platform, its current\nsubscription plan, and the scopes your key grants — so you know which\noperations are available before calling them. The operation is\nread-only, has no side effects, and is always safe to retry. Requires\nthe `store:read` scope.\n\nAuthenticate every request with a store API key sent as a bearer token\n(`Authorization: Bearer `); keys are created in the merchant\nadmin under Integrate → API Tokens with a chosen set of scopes and an\noptional expiry. A 401 problem response means the key is missing,\ninvalid, or expired — create or re-copy the key. A 403 problem response\nwith code `insufficient_scope` means the key is valid but lacks a\nrequired scope: the problem's `required_scopes` and `granted_scopes`\nmembers say which scope is missing and what the key can do; create a\nkey that includes the required scope. A 429 problem response means too\nmany requests: wait `retry_after` seconds, then retry. Error responses\nuse RFC 9457 problem+json: machine-readable `code`, a documentation\nlink in `type`, and a `request_id` to quote when contacting support.", "operationId": "getTheAuthenticatedStoreIdentifyTheStoreYourAPIKeyBelongsToCallThisFirstItConfirmsTheKeyWorksTellsYouWhichStoreYouAreOperatingOnWhetherTheStoreRunsOnTheshopifyOruniversalPlatformItsCurrentSubscriptionPlanAndTheScopesYourKeyGrantsSoYouKnowWhichOperationsAreAvailableBeforeCallingThemTheOperationIsReadOnlyHasNoSideEffectsAndIsAlwaysSafeToRetryRequiresThestorereadScopeAuthenticateEveryRequestWithAStoreAPIKeySentAsABearerTokenAuthorizationBearerapiKeyKeysAreCreatedInTheMerchantAdminUnderIntegrateAPITokensWithAChosenSetOfScopesAndAnOptionalExpiryA401ProblemResponseMeansTheKeyIsMissingInvalidOrExpiredCreateOrReCopyTheKeyA403ProblemResponseWithCodeinsufficientScopeMeansTheKeyIsValidButLacksARequiredScopeTheProblemsrequiredScopesAndgrantedScopesMembersSayWhichScopeIsMissingAndWhatTheKeyCanDoCreateAKeyThatIncludesTheRequiredScopeA429ProblemResponseMeansTooManyRequestsWaitretryAfterSecondsThenRetryErrorResponsesUseRFC9457Problem+jsonMachineReadablecodeADocumentationLinkIntypeAndArequestIdToQuoteWhenContactingSupport", "description": "", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "data": { "object": "store", "id": 1, "name": "Demo Signs", "platform": "universal", "plan": "starter", "scopes": [ "store:read", "pricing:read", "pricing:write" ], "created_at": "2026-01-12T03:14:15Z" }, "links": { "self": "https://web.signcustomiser.com/api/v3/stores/me", "documentation": "https://www.signcustomiser.com/help/api/" }, "meta": { "api_version": "v3", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } }, "properties": { "data": { "type": "object", "properties": { "object": { "type": "string", "example": "store", "description": "The resource type discriminator. Always \"store\" for this endpoint (closed set).", "enum": [ "store" ] }, "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Demo Signs" }, "platform": { "type": "string", "example": "universal", "description": "The platform the store runs on (closed set).", "enum": [ "shopify", "universal" ] }, "plan": { "type": [ "string", "null" ], "example": "starter", "description": "Lowercase subscription plan identifier, or null when the store has no active plan. This set is expected to grow — tolerate unknown values." }, "scopes": { "type": "array", "example": [ "store:read", "pricing:read", "pricing:write" ], "description": "The scopes the authenticated API key grants, from the closed catalogue: customisers:read, customisers:write, pricing:read, pricing:write, products:read, products:write, orders:read, orders:write, webhooks:read, webhooks:write, store:read, analytics:read. Full-access legacy keys report every scope.", "items": { "type": "string" } }, "created_at": { "type": "string", "example": "2026-01-12T03:14:15Z" } }, "required": [ "object", "platform", "plan", "scopes" ] }, "links": { "type": "object", "properties": { "self": { "type": "string", "example": "https://web.signcustomiser.com/api/v3/stores/me" }, "documentation": { "type": "string", "example": "https://www.signcustomiser.com/help/api/" } } }, "meta": { "type": "object", "properties": { "api_version": { "type": "string", "example": "v3" }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "oneOf": [ { "description": "Missing API key", "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/missing_api_key", "title": "Missing API key", "status": 401, "code": "missing_api_key", "detail": "Provide a store API key as a bearer token: Authorization: Bearer . Keys are created in the merchant admin under Integrate → API Tokens.", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/missing_api_key" }, "title": { "type": "string", "example": "Missing API key" }, "status": { "type": "integer", "example": 401 }, "code": { "type": "string", "example": "missing_api_key" }, "detail": { "type": "string", "example": "Provide a store API key as a bearer token: Authorization: Bearer . Keys are created in the merchant admin under Integrate → API Tokens." }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } }, { "description": "Invalid API key", "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/invalid_api_key", "title": "Invalid API key", "status": 401, "code": "invalid_api_key", "detail": "The bearer token is not a valid store API key. Check the value, or create a new key in the merchant admin under Integrate → API Tokens.", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/invalid_api_key" }, "title": { "type": "string", "example": "Invalid API key" }, "status": { "type": "integer", "example": 401 }, "code": { "type": "string", "example": "invalid_api_key" }, "detail": { "type": "string", "example": "The bearer token is not a valid store API key. Check the value, or create a new key in the merchant admin under Integrate → API Tokens." }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } }, { "description": "Expired API key", "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/expired_api_key", "title": "Expired API key", "status": 401, "code": "expired_api_key", "detail": "This store API key has passed its expiry date and can no longer be used. Create a replacement key in the merchant admin under Integrate → API Tokens.", "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/expired_api_key" }, "title": { "type": "string", "example": "Expired API key" }, "status": { "type": "integer", "example": 401 }, "code": { "type": "string", "example": "expired_api_key" }, "detail": { "type": "string", "example": "This store API key has passed its expiry date and can no longer be used. Create a replacement key in the merchant admin under Integrate → API Tokens." }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } ] } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/insufficient_scope", "title": "Insufficient scope", "status": 403, "code": "insufficient_scope", "detail": "This operation requires the store:read scope, but the API key grants the following scopes: pricing:read. Create a key that includes the required scope in the merchant admin under Integrate → API Tokens.", "required_scopes": [ "store:read" ], "granted_scopes": [ "pricing:read" ], "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/insufficient_scope" }, "title": { "type": "string", "example": "Insufficient scope" }, "status": { "type": "integer", "example": 403 }, "code": { "type": "string", "example": "insufficient_scope" }, "detail": { "type": "string", "example": "This operation requires the store:read scope, but the API key grants the following scopes: pricing:read. Create a key that includes the required scope in the merchant admin under Integrate → API Tokens." }, "required_scopes": { "type": "array", "example": [ "store:read" ], "items": { "type": "string" } }, "granted_scopes": { "type": "array", "example": [ "pricing:read" ], "items": { "type": "string" } }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } }, "422": { "description": "Unknown query parameter", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/unknown_parameter", "title": "Unknown query parameter", "status": 422, "code": "unknown_parameter", "detail": "The request includes query parameters this endpoint does not support: filter. This endpoint accepts no query parameters.", "errors": [ { "parameter": "filter", "code": "unknown_parameter", "detail": "The query parameter \"filter\" is not supported by this endpoint." } ], "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/unknown_parameter" }, "title": { "type": "string", "example": "Unknown query parameter" }, "status": { "type": "integer", "example": 422 }, "code": { "type": "string", "example": "unknown_parameter" }, "detail": { "type": "string", "example": "The request includes query parameters this endpoint does not support: filter. This endpoint accepts no query parameters." }, "errors": { "type": "array", "example": [ { "parameter": "filter", "code": "unknown_parameter", "detail": "The query parameter \"filter\" is not supported by this endpoint." } ], "items": { "type": "object", "properties": { "parameter": { "type": "string", "example": "filter" }, "code": { "type": "string", "example": "unknown_parameter" }, "detail": { "type": "string", "example": "The query parameter \"filter\" is not supported by this endpoint." } } } }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "example": { "type": "https://www.signcustomiser.com/help/api/problems/rate_limited", "title": "Too many requests", "status": 429, "code": "rate_limited", "detail": "You have exceeded the request limit for this API key. Wait 60 seconds, then retry.", "retry_after": 60, "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" }, "properties": { "type": { "type": "string", "example": "https://www.signcustomiser.com/help/api/problems/rate_limited" }, "title": { "type": "string", "example": "Too many requests" }, "status": { "type": "integer", "example": 429 }, "code": { "type": "string", "example": "rate_limited" }, "detail": { "type": "string", "example": "You have exceeded the request limit for this API key. Wait 60 seconds, then retry." }, "retry_after": { "type": "integer", "example": 60 }, "request_id": { "type": "string", "example": "req_01jz9x2k7c8f3m5n6p7q8r9s0t" } } } } } } }, "tags": [ "Stores" ] } }, "/api/v2/webhooks": { "parameters": [], "get": { "summary": "List all webhooks\n\nGet a list of all webhooks for the current organisation.", "operationId": "listAllWebhooksGetAListOfAllWebhooksForTheCurrentOrganisation", "description": "", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "webhooks": [ { "webhook_id": 1, "topic": "product:created", "url": "https://example.com/webhook", "status": "active", "secret": "abc123...", "meta": {}, "created_at": "2024-01-01T00:00:00.000000Z", "updated_at": "2024-01-01T00:00:00.000000Z" } ] }, "properties": { "webhooks": { "type": "array", "example": [ { "webhook_id": 1, "topic": "product:created", "url": "https://example.com/webhook", "status": "active", "secret": "abc123...", "meta": [], "created_at": "2024-01-01T00:00:00.000000Z", "updated_at": "2024-01-01T00:00:00.000000Z" } ], "items": { "type": "object", "properties": { "webhook_id": { "type": "integer", "example": 1 }, "topic": { "type": "string", "example": "product:created" }, "url": { "type": "string", "example": "https://example.com/webhook" }, "status": { "type": "string", "example": "active" }, "secret": { "type": "string", "example": "abc123..." }, "meta": { "type": "object", "properties": {} }, "created_at": { "type": "string", "example": "2024-01-01T00:00:00.000000Z" }, "updated_at": { "type": "string", "example": "2024-01-01T00:00:00.000000Z" } } } } } } } } } }, "tags": [ "Webhooks" ] }, "post": { "summary": "Create a new webhook\n\nRegister a new webhook endpoint to receive event notifications.", "operationId": "createANewWebhookRegisterANewWebhookEndpointToReceiveEventNotifications", "description": "", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "webhook": { "webhook_id": 1, "topic": "product:created", "url": "https://example.com/webhook", "status": "active", "secret": "abc123...", "meta": {}, "created_at": "2024-01-01T00:00:00.000000Z", "updated_at": "2024-01-01T00:00:00.000000Z" } }, "properties": { "webhook": { "type": "object", "properties": { "webhook_id": { "type": "integer", "example": 1 }, "topic": { "type": "string", "example": "product:created" }, "url": { "type": "string", "example": "https://example.com/webhook" }, "status": { "type": "string", "example": "active" }, "secret": { "type": "string", "example": "abc123..." }, "meta": { "type": "object", "properties": {} }, "created_at": { "type": "string", "example": "2024-01-01T00:00:00.000000Z" }, "updated_at": { "type": "string", "example": "2024-01-01T00:00:00.000000Z" } } } } } } } } }, "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "topic": { "type": "string", "description": "The event topic to subscribe to. Must be one of: product:created, order:created, form:submitted.", "example": "product:created" }, "url": { "type": "string", "description": "The URL where webhook payloads will be sent. Must be a valid URL.", "example": "https://example.com/webhook" }, "meta": { "type": [ "object", "null" ], "description": "Optional metadata to store with the webhook.", "example": [], "properties": { "source": { "type": "string", "description": "", "example": null } } } }, "required": [ "topic", "url" ] } } } } } }, "/api/v2/webhooks/{webhook_id}": { "parameters": [ { "in": "path", "name": "webhook_id", "description": "The ID of the webhook.", "example": "1", "required": true, "schema": { "type": "integer" } } ], "get": { "summary": "Get a single webhook\n\nRetrieve details for a specific webhook.", "operationId": "getASingleWebhookRetrieveDetailsForASpecificWebhook", "description": "", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "webhook": { "webhook_id": 1, "topic": "product:created", "url": "https://example.com/webhook", "status": "active", "secret": "abc123...", "meta": {}, "created_at": "2024-01-01T00:00:00.000000Z", "updated_at": "2024-01-01T00:00:00.000000Z" } }, "properties": { "webhook": { "type": "object", "properties": { "webhook_id": { "type": "integer", "example": 1 }, "topic": { "type": "string", "example": "product:created" }, "url": { "type": "string", "example": "https://example.com/webhook" }, "status": { "type": "string", "example": "active" }, "secret": { "type": "string", "example": "abc123..." }, "meta": { "type": "object", "properties": {} }, "created_at": { "type": "string", "example": "2024-01-01T00:00:00.000000Z" }, "updated_at": { "type": "string", "example": "2024-01-01T00:00:00.000000Z" } } } } } } } } }, "tags": [ "Webhooks" ] }, "put": { "summary": "Update a webhook\n\nUpdate an existing webhook's topic, URL, or metadata.", "operationId": "updateAWebhookUpdateAnExistingWebhooksTopicURLOrMetadata", "description": "", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "webhook": { "webhook_id": 1, "topic": "order:created", "url": "https://example.com/webhook-updated", "status": "active", "secret": "abc123...", "meta": {}, "created_at": "2024-01-01T00:00:00.000000Z", "updated_at": "2024-01-02T00:00:00.000000Z" } }, "properties": { "webhook": { "type": "object", "properties": { "webhook_id": { "type": "integer", "example": 1 }, "topic": { "type": "string", "example": "order:created" }, "url": { "type": "string", "example": "https://example.com/webhook-updated" }, "status": { "type": "string", "example": "active" }, "secret": { "type": "string", "example": "abc123..." }, "meta": { "type": "object", "properties": {} }, "created_at": { "type": "string", "example": "2024-01-01T00:00:00.000000Z" }, "updated_at": { "type": "string", "example": "2024-01-02T00:00:00.000000Z" } } } } } } } } }, "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "topic": { "type": "string", "description": "The event topic to subscribe to. Must be one of: product:created, order:created, form:submitted.", "example": "product:created" }, "url": { "type": "string", "description": "The URL where webhook payloads will be sent. Must be a valid URL.", "example": "https://example.com/webhook" }, "meta": { "type": [ "object", "null" ], "description": "Optional metadata to store with the webhook.", "example": [], "properties": { "source": { "type": "string", "description": "", "example": null } } } }, "required": [ "topic", "url" ] } } } } }, "delete": { "summary": "Delete a webhook\n\nRemove a webhook subscription.", "operationId": "deleteAWebhookRemoveAWebhookSubscription", "description": "", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "success": true }, "properties": { "success": { "type": "boolean", "example": true } } } } } } }, "tags": [ "Webhooks" ] } }, "/api/v2/webhook-examples/{topic}": { "parameters": [ { "in": "path", "name": "topic", "description": "The webhook topic to get examples for. Must be one of: product:created, order:created, form:submitted.", "example": "product:created", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Webhook payload examples\n\nRetrieve example webhook payloads for a specific topic. If data exists for the current organisation, real data will be used. Otherwise, example data is returned.", "operationId": "webhookPayloadExamplesRetrieveExampleWebhookPayloadsForASpecificTopicIfDataExistsForTheCurrentOrganisationRealDataWillBeUsedOtherwiseExampleDataIsReturned", "description": "", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "oneOf": [ { "description": "Product Created", "type": "object", "example": { "product": { "product_id": 1, "title": "Custom Neon: Hello World", "description": "Text: Hello World\nColour: Red\nFont: Comics", "description_html": "

Text: Hello World

\n

Colour: Red

\n

Font: Comics

", "external_id": "1234", "external_data": {}, "price": 10000, "compare_price": 15000, "customiser_id": 1, "logo_upload_id": null, "product_image_url": "https://d1no4rdxmwcuog.cloudfront.net/default/app-images/demonstration_image_1.jpg", "uploads": [ { "url": "https://d1no4rdxmwcuog.cloudfront.net/default/app-images/demonstration_image_1.jpg", "type": "product_image" } ], "created_at": "2024-01-01T00:00:00.000000Z", "updated_at": "2024-01-01T00:00:00.000000Z" } }, "properties": { "product": { "type": "object", "properties": { "product_id": { "type": "integer", "example": 1 }, "title": { "type": "string", "example": "Custom Neon: Hello World" }, "description": { "type": "string", "example": "Text: Hello World\nColour: Red\nFont: Comics" }, "description_html": { "type": "string", "example": "

Text: Hello World

\n

Colour: Red

\n

Font: Comics

" }, "external_id": { "type": "string", "example": "1234" }, "external_data": { "type": "object", "properties": {} }, "price": { "type": "integer", "example": 10000 }, "compare_price": { "type": "integer", "example": 15000 }, "customiser_id": { "type": "integer", "example": 1 }, "logo_upload_id": { "type": [ "string", "null" ], "example": null }, "product_image_url": { "type": "string", "example": "https://d1no4rdxmwcuog.cloudfront.net/default/app-images/demonstration_image_1.jpg" }, "uploads": { "type": "array", "example": [ { "url": "https://d1no4rdxmwcuog.cloudfront.net/default/app-images/demonstration_image_1.jpg", "type": "product_image" } ], "items": { "type": "object", "properties": { "url": { "type": "string", "example": "https://d1no4rdxmwcuog.cloudfront.net/default/app-images/demonstration_image_1.jpg" }, "type": { "type": "string", "example": "product_image" } } } }, "created_at": { "type": "string", "example": "2024-01-01T00:00:00.000000Z" }, "updated_at": { "type": "string", "example": "2024-01-01T00:00:00.000000Z" } } } } }, { "description": "Order Created", "type": "object", "example": { "order": { "order_id": 1, "order_number": 4, "external_order_number": "SIGN-12345", "external_id": "12345", "order_total": 120000, "app_total": 100000, "currency": "USD", "shipping_line": "ground", "billing_address": { "first_name": "John", "last_name": "Doe", "company": "Acme", "address_1": "123 Fake Street", "address_2": "Unit 456", "city": "Brisbane", "state": "Queensland", "postcode": "4000", "country": "Australia", "phone": "123456789", "email": "john@example.com", "created_at": "2025-10-22T00:55:09+00:00", "updated_at": "2025-10-22T00:55:09+00:00" }, "shipping_address": { "first_name": "John", "last_name": "Doe", "company": "Acme", "address_1": "123 Fake Street", "address_2": "Unit 456", "city": "Brisbane", "state": "Queensland", "postcode": "4000", "country": "Australia", "phone": "123456789", "email": "john@example.com", "created_at": "2025-10-22T00:55:09+00:00", "updated_at": "2025-10-22T00:55:09+00:00" }, "customer": { "first_name": "John", "last_name": "Doe", "phone": "123456789", "email": "john@example.com", "external_id": "1234", "created_at": "2025-10-22T00:55:09+00:00", "updated_at": "2025-10-22T00:55:09+00:00" }, "products": [ { "product_image_url": "https://d1no4rdxmwcuog.cloudfront.net/default/app-images/demonstration_image_1.jpg", "product_id": 1, "title": "Custom Neon: Hello World", "description": "Text: Hello World\nColour: Red\nFont: Comics", "description_html": "

Text: Hello World

\n

Colour: Red

\n

Font: Comics

", "external_id": "1234", "external_data": [], "price": 10000, "compare_price": 15000, "customiser_id": 1, "logo_upload_id": null, "uploads": [ { "url": "https://d1no4rdxmwcuog.cloudfront.net/default/app-images/demonstration_image_1.jpg", "path": "app-images/demonstration_image_1.jpg", "type": "product_image" } ], "created_at": "2025-10-22T00:55:09+00:00", "updated_at": "2025-10-22T00:55:09+00:00" } ], "created_at": "2025-10-22T00:55:09+00:00", "updated_at": "2025-10-22T00:55:09+00:00" } }, "properties": { "order": { "type": "object", "properties": { "order_id": { "type": "integer", "example": 1 }, "order_number": { "type": "integer", "example": 4 }, "external_order_number": { "type": "string", "example": "SIGN-12345" }, "external_id": { "type": "string", "example": "12345" }, "order_total": { "type": "integer", "example": 120000 }, "app_total": { "type": "integer", "example": 100000 }, "currency": { "type": "string", "example": "USD" }, "shipping_line": { "type": "string", "example": "ground" }, "billing_address": { "type": "object", "properties": { "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Doe" }, "company": { "type": "string", "example": "Acme" }, "address_1": { "type": "string", "example": "123 Fake Street" }, "address_2": { "type": "string", "example": "Unit 456" }, "city": { "type": "string", "example": "Brisbane" }, "state": { "type": "string", "example": "Queensland" }, "postcode": { "type": "string", "example": "4000" }, "country": { "type": "string", "example": "Australia" }, "phone": { "type": "string", "example": "123456789" }, "email": { "type": "string", "example": "john@example.com" }, "created_at": { "type": "string", "example": "2025-10-22T00:55:09+00:00" }, "updated_at": { "type": "string", "example": "2025-10-22T00:55:09+00:00" } } }, "shipping_address": { "type": "object", "properties": { "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Doe" }, "company": { "type": "string", "example": "Acme" }, "address_1": { "type": "string", "example": "123 Fake Street" }, "address_2": { "type": "string", "example": "Unit 456" }, "city": { "type": "string", "example": "Brisbane" }, "state": { "type": "string", "example": "Queensland" }, "postcode": { "type": "string", "example": "4000" }, "country": { "type": "string", "example": "Australia" }, "phone": { "type": "string", "example": "123456789" }, "email": { "type": "string", "example": "john@example.com" }, "created_at": { "type": "string", "example": "2025-10-22T00:55:09+00:00" }, "updated_at": { "type": "string", "example": "2025-10-22T00:55:09+00:00" } } }, "customer": { "type": "object", "properties": { "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Doe" }, "phone": { "type": "string", "example": "123456789" }, "email": { "type": "string", "example": "john@example.com" }, "external_id": { "type": "string", "example": "1234" }, "created_at": { "type": "string", "example": "2025-10-22T00:55:09+00:00" }, "updated_at": { "type": "string", "example": "2025-10-22T00:55:09+00:00" } } }, "products": { "type": "array", "example": [ { "product_image_url": "https://d1no4rdxmwcuog.cloudfront.net/default/app-images/demonstration_image_1.jpg", "product_id": 1, "title": "Custom Neon: Hello World", "description": "Text: Hello World\nColour: Red\nFont: Comics", "description_html": "

Text: Hello World

\n

Colour: Red

\n

Font: Comics

", "external_id": "1234", "external_data": [], "price": 10000, "compare_price": 15000, "customiser_id": 1, "logo_upload_id": null, "uploads": [ { "url": "https://d1no4rdxmwcuog.cloudfront.net/default/app-images/demonstration_image_1.jpg", "path": "app-images/demonstration_image_1.jpg", "type": "product_image" } ], "created_at": "2025-10-22T00:55:09+00:00", "updated_at": "2025-10-22T00:55:09+00:00" } ], "items": { "type": "object", "properties": { "product_image_url": { "type": "string", "example": "https://d1no4rdxmwcuog.cloudfront.net/default/app-images/demonstration_image_1.jpg" }, "product_id": { "type": "integer", "example": 1 }, "title": { "type": "string", "example": "Custom Neon: Hello World" }, "description": { "type": "string", "example": "Text: Hello World\nColour: Red\nFont: Comics" }, "description_html": { "type": "string", "example": "

Text: Hello World

\n

Colour: Red

\n

Font: Comics

" }, "external_id": { "type": "string", "example": "1234" }, "external_data": { "type": "array", "example": [] }, "price": { "type": "integer", "example": 10000 }, "compare_price": { "type": "integer", "example": 15000 }, "customiser_id": { "type": "integer", "example": 1 }, "logo_upload_id": { "type": [ "string", "null" ], "example": null }, "uploads": { "type": "array", "example": [ { "url": "https://d1no4rdxmwcuog.cloudfront.net/default/app-images/demonstration_image_1.jpg", "path": "app-images/demonstration_image_1.jpg", "type": "product_image" } ], "items": { "type": "object", "properties": { "url": { "type": "string", "example": "https://d1no4rdxmwcuog.cloudfront.net/default/app-images/demonstration_image_1.jpg" }, "path": { "type": "string", "example": "app-images/demonstration_image_1.jpg" }, "type": { "type": "string", "example": "product_image" } } } }, "created_at": { "type": "string", "example": "2025-10-22T00:55:09+00:00" }, "updated_at": { "type": "string", "example": "2025-10-22T00:55:09+00:00" } } } }, "created_at": { "type": "string", "example": "2025-10-22T00:55:09+00:00" }, "updated_at": { "type": "string", "example": "2025-10-22T00:55:09+00:00" } } } } }, { "description": "Form Submitted", "type": "object", "example": { "form_submission": { "submission_number": 1234, "type": "custom_form_submission", "form": { "form_id": 1, "customiser_id": 1, "label": "Custom Design Form", "description": "Lorem ipsum dolor", "email": "test@test.com", "subject": "My Custom Email Subject", "created_at": "2024-01-01T00:00:00.000000Z", "updated_at": "2024-01-01T00:00:00.000000Z" }, "responses": [ { "field_id": "abcd1234", "value": "test@test.com", "name": "Your Email", "input_type": "EMAIL" } ], "created_at": "2024-01-01T00:00:00.000000Z" } }, "properties": { "form_submission": { "type": "object", "properties": { "submission_number": { "type": "integer", "example": 1234 }, "type": { "type": "string", "example": "custom_form_submission" }, "form": { "type": "object", "properties": { "form_id": { "type": "integer", "example": 1 }, "customiser_id": { "type": "integer", "example": 1 }, "label": { "type": "string", "example": "Custom Design Form" }, "description": { "type": "string", "example": "Lorem ipsum dolor" }, "email": { "type": "string", "example": "test@test.com" }, "subject": { "type": "string", "example": "My Custom Email Subject" }, "created_at": { "type": "string", "example": "2024-01-01T00:00:00.000000Z" }, "updated_at": { "type": "string", "example": "2024-01-01T00:00:00.000000Z" } } }, "responses": { "type": "array", "example": [ { "field_id": "abcd1234", "value": "test@test.com", "name": "Your Email", "input_type": "EMAIL" } ], "items": { "type": "object", "properties": { "field_id": { "type": "string", "example": "abcd1234" }, "value": { "type": "string", "example": "test@test.com" }, "name": { "type": "string", "example": "Your Email" }, "input_type": { "type": "string", "example": "EMAIL" } } } }, "created_at": { "type": "string", "example": "2024-01-01T00:00:00.000000Z" } } } } } ] } } } } }, "tags": [ "Webhooks" ] } } }, "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "webhooks": { "productCreated": { "post": { "description": "Use this as the product creation callback for custom integrations. When a customer finishes a design, Sign Customiser POSTs this payload to the create-product URL configured on your custom integration. Verify the signature, create the product in your own platform, then return a 200 JSON response containing the `external_id` you will later send in `POST /api/v2/orders`.", "operationId": "receiveProductCreated", "parameters": [ { "description": "Unix timestamp used when generating the delivery signature.", "example": "1704067200", "in": "header", "name": "x-webhook-timestamp", "required": true, "schema": { "type": "string" } }, { "description": "SHA-256 HMAC signature for the product:created payload.", "example": "YOUR_GENERATED_SIGNATURE", "in": "header", "name": "x-webhook-signature", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "product": { "product_id": 1, "title": "Custom Neon: Hello World", "description": "Text: Hello World\nColour: Red\nFont: Comics", "description_html": "

Text: Hello World

\n

Colour: Red

\n

Font: Comics

", "external_id": "1234", "external_data": {}, "price": 10000, "compare_price": 15000, "customiser_id": 1, "logo_upload_id": null, "product_image_url": "https://d1no4rdxmwcuog.cloudfront.net/default/app-images/demonstration_image_1.jpg", "uploads": [ { "url": "https://d1no4rdxmwcuog.cloudfront.net/default/app-images/demonstration_image_1.jpg", "type": "product_image" } ], "created_at": "2024-01-01T00:00:00.000000Z", "updated_at": "2024-01-01T00:00:00.000000Z" } }, "schema": { "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Return your platform product ID", "content": { "application/json": { "example": { "external_id": "your-product-id-123" }, "schema": { "type": "object" } } } } }, "summary": "Product created" } }, "orderCreated": { "post": { "description": "Delivered when Sign Customiser records a completed order for your organisation.", "operationId": "receiveOrderCreated", "parameters": [ { "description": "Unix timestamp used when generating the delivery signature.", "example": "1704067200", "in": "header", "name": "x-webhook-timestamp", "required": true, "schema": { "type": "string" } }, { "description": "SHA-256 HMAC signature for the order:created payload.", "example": "YOUR_GENERATED_SIGNATURE", "in": "header", "name": "x-webhook-signature", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "order": { "order_id": 1, "order_number": 4, "external_order_number": "SIGN-12345", "external_id": "12345", "order_total": 120000, "app_total": 100000, "currency": "USD", "shipping_line": "ground", "billing_address": { "first_name": "John", "last_name": "Doe", "company": "Acme", "address_1": "123 Fake Street", "address_2": "Unit 456", "city": "Brisbane", "state": "Queensland", "postcode": "4000", "country": "Australia", "phone": "123456789", "email": "john@example.com", "created_at": "2025-10-22T00:55:09+00:00", "updated_at": "2025-10-22T00:55:09+00:00" }, "shipping_address": { "first_name": "John", "last_name": "Doe", "company": "Acme", "address_1": "123 Fake Street", "address_2": "Unit 456", "city": "Brisbane", "state": "Queensland", "postcode": "4000", "country": "Australia", "phone": "123456789", "email": "john@example.com", "created_at": "2025-10-22T00:55:09+00:00", "updated_at": "2025-10-22T00:55:09+00:00" }, "customer": { "first_name": "John", "last_name": "Doe", "phone": "123456789", "email": "john@example.com", "external_id": "1234", "created_at": "2025-10-22T00:55:09+00:00", "updated_at": "2025-10-22T00:55:09+00:00" }, "products": [ { "product_image_url": "https://d1no4rdxmwcuog.cloudfront.net/default/app-images/demonstration_image_1.jpg", "product_id": 1, "title": "Custom Neon: Hello World", "description": "Text: Hello World\nColour: Red\nFont: Comics", "description_html": "

Text: Hello World

\n

Colour: Red

\n

Font: Comics

", "external_id": "1234", "external_data": [], "price": 10000, "compare_price": 15000, "customiser_id": 1, "logo_upload_id": null, "uploads": [ { "url": "https://d1no4rdxmwcuog.cloudfront.net/default/app-images/demonstration_image_1.jpg", "path": "app-images/demonstration_image_1.jpg", "type": "product_image" } ], "created_at": "2025-10-22T00:55:09+00:00", "updated_at": "2025-10-22T00:55:09+00:00" } ], "created_at": "2025-10-22T00:55:09+00:00", "updated_at": "2025-10-22T00:55:09+00:00" } }, "schema": { "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Acknowledge delivery", "content": { "application/json": { "example": { "ok": true }, "schema": { "type": "object" } } } } }, "summary": "Order created" } }, "formSubmitted": { "post": { "description": "Delivered when a customer submits a Sign Customiser form workflow.", "operationId": "receiveFormSubmitted", "parameters": [ { "description": "Unix timestamp used when generating the delivery signature.", "example": "1704067200", "in": "header", "name": "x-webhook-timestamp", "required": true, "schema": { "type": "string" } }, { "description": "SHA-256 HMAC signature for the form:submitted payload.", "example": "YOUR_GENERATED_SIGNATURE", "in": "header", "name": "x-webhook-signature", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "form_submission": { "submission_number": 1234, "type": "custom_form_submission", "form": { "form_id": 1, "customiser_id": 1, "label": "Custom Design Form", "description": "Lorem ipsum dolor", "email": "test@test.com", "subject": "My Custom Email Subject", "created_at": "2024-01-01T00:00:00.000000Z", "updated_at": "2024-01-01T00:00:00.000000Z" }, "responses": [ { "field_id": "abcd1234", "value": "test@test.com", "name": "Your Email", "input_type": "EMAIL" } ], "created_at": "2024-01-01T00:00:00.000000Z" } }, "schema": { "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Acknowledge delivery", "content": { "application/json": { "example": { "ok": true }, "schema": { "type": "object" } } } } }, "summary": "Form submitted" } } } }