{ "openapi": "3.1.0", "info": { "title": "Filemonk API v2 (Beta)", "version": "2.0.0-beta", "description": "Filemonk's action-driven, AI-native external API for digital product delivery: orders and their downloads, files (assets), digital products, licence keys, customers, settings and the account. Every action is self-describing (`description`, `aliases`, `notes`, JSON request schema) and also reachable via the `/help` manifest, `skill.md` and `llms.txt`, and through the MCP server (`search`, `execute_read`, `execute_write`). Lists take `page` (1-based) and `per_page` (default 50, max 200) and answer `{ \"data\": [...], \"meta\": { \"total_count\", \"page\", \"per_page\", \"total_pages\" } }`. **Public beta** — actions and schemas may change before GA. All endpoints require the `X-Auth-Token` API key (or the same key as a Bearer token).", "contact": { "name": "Filemonk Support", "email": "support@filemonk.io", "url": "https://app.filemonk.io" } }, "servers": [ { "url": "https://app.filemonk.io/api/v2/external", "description": "Production" } ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "tags": [ { "name": "Account", "description": "The shop the key belongs to, its plan, limits and usage." }, { "name": "Analytics", "description": "Order and download counters from the home page." }, { "name": "Assets", "description": "Files, links and licence-key files in the library." }, { "name": "Customers", "description": "Buyers Filemonk delivered to, and their email opt-out." }, { "name": "Digital Products", "description": "Shopify products or variants with files attached, their delivery, pre-order and update-email settings." }, { "name": "Download Logs", "description": "Every download, with the order, file and client." }, { "name": "Emails", "description": "Every email Filemonk sent and how far it got." }, { "name": "Exports", "description": "CSV exports emailed to the shop." }, { "name": "Imports", "description": "Bulk CSV imports of historic orders." }, { "name": "Licence Tags", "description": "Pools of licence keys, by tag." }, { "name": "Licences", "description": "Licence keys: add, import, check, move and delete." }, { "name": "Orders", "description": "Orders, their files and downloads, access, licence keys and download emails." }, { "name": "Settings", "description": "Every setting of the Settings page, read whole and changed by deep-partial PATCH." } ], "paths": { "/account": { "get": { "operationId": "get_account", "summary": "Read", "description": "The shop this API key belongs to: its domain, name, contact email, currency and time zone, the Filemonk plan it is on with the plan's limits (orders per cycle, file count, storage and bandwidth, in bytes), and the current billing cycle's usage (bytes uploaded, bytes downloaded, paid orders). Read-only; nothing about charges or money.", "tags": [ "Account" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "shopify_domain", "name", "email", "currency", "time_zone", "plan", "usage", "created_at" ], "properties": { "id": { "type": [ "string", "null" ] }, "shopify_domain": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "currency": { "type": [ "string", "null" ] }, "time_zone": { "type": [ "string", "null" ] }, "plan": { "type": "object", "required": [ "name", "type", "order_limit", "asset_count_limit", "asset_storage_bytes", "bandwidth_bytes" ], "properties": { "name": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "order_limit": { "type": [ "integer", "null" ] }, "asset_count_limit": { "type": [ "integer", "null" ] }, "asset_storage_bytes": { "type": [ "integer", "null" ] }, "bandwidth_bytes": {} } }, "usage": { "type": "object", "required": [ "uploaded_bytes", "bandwidth_used_bytes", "orders_count" ], "properties": { "uploaded_bytes": { "type": [ "integer", "null" ] }, "bandwidth_used_bytes": { "type": [ "integer", "null" ] }, "orders_count": { "type": [ "integer", "null" ] } } }, "created_at": { "type": [ "string", "null" ] } } }, "example": { "id": "acdfd70d-145e-4151-b88a-ce77a4108b43", "shopify_domain": "example-store.myshopify.com", "name": "Example Store", "email": "shopper@example.com", "currency": "INR", "time_zone": "America/New_York", "plan": { "name": "pro_per_order", "type": "pro", "order_limit": 2500, "asset_count_limit": 10000, "asset_storage_bytes": 1000000000000, "bandwidth_bytes": null }, "usage": { "uploaded_bytes": 217370, "bandwidth_used_bytes": 800900, "orders_count": 3 }, "created_at": "2025-03-04T13:34:39Z" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "my account", "my plan", "which plan am I on", "usage", "how much storage have I used", "bandwidth used", "orders this month", "shop details", "whose key is this" ] } }, "/analytics": { "get": { "operationId": "get_analytics", "summary": "Read", "description": "The home page counters: orders delivered and files downloaded, for all time or this calendar month (period=all_time|this_month).", "tags": [ "Analytics" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object", "required": [ "period", "orders_count", "downloads_count" ], "properties": { "period": { "type": [ "string", "null" ] }, "orders_count": { "type": [ "integer", "null" ] }, "downloads_count": { "type": [ "integer", "null" ] } } }, "example": { "period": "all_time", "orders_count": 48, "downloads_count": 18 } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "how many orders this month", "download count", "store stats", "analytics" ], "parameters": [ { "name": "period", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "all_time", "this_month" ] }, "example": "all_time" } ] } }, "/assets": { "post": { "operationId": "post_assets", "summary": "Create", "description": "Add a file to the library, as the Files page's Add does. type is file (a stored upload), link (an absolute url, such as https://…, to an external page or download) or licence_key (a pool of keys). A file answers with upload: {url, method, headers, expires_at}; PUT the file's bytes there within the hour, nothing else is needed. An AI assistant that can't send the bytes itself (in a chat) should ask the merchant to upload the file on the Files page instead. watermark.enabled applies to PDFs; licence_keys.autogenerate mints keys on demand, licence_keys.tags names the pools the file draws from.\n\n**Note:** A stored file counts against the plan's file and storage quota from this call (402-style quota errors come back as 422 with code). Nothing is linked to a product until POST /digital_products/:id/files/attach.", "tags": [ "Assets" ], "responses": { "200": { "description": "Success — the resource already existed; here it is.", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "201": { "description": "Created — the new resource.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "name", "filename", "extension", "content_type", "byte_size", "url", "url_expires_at", "watermark", "licence_keys", "usage", "digital_products", "recent_orders", "created_at", "updated_at", "upload" ], "properties": { "id": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "filename": { "type": [ "string", "null" ] }, "extension": { "type": [ "string", "null" ] }, "content_type": { "type": [ "string", "null" ] }, "byte_size": { "type": [ "integer", "null" ] }, "url": {}, "url_expires_at": {}, "watermark": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": [ "boolean", "null" ] } } }, "licence_keys": { "type": "object", "required": [ "autogenerate", "tags" ], "properties": { "autogenerate": { "type": [ "boolean", "null" ] }, "tags": { "type": "array" } } }, "usage": { "type": "object", "required": [ "digital_products_count", "orders_count" ], "properties": { "digital_products_count": { "type": [ "integer", "null" ] }, "orders_count": { "type": [ "integer", "null" ] } } }, "digital_products": { "type": "array" }, "recent_orders": { "type": "array" }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] }, "upload": { "type": "object", "required": [ "url", "method", "headers", "expires_at" ], "properties": { "url": { "type": [ "string", "null" ] }, "method": { "type": [ "string", "null" ] }, "headers": { "type": "object", "required": [ "Content-Type" ], "properties": { "Content-Type": { "type": [ "string", "null" ] } } }, "expires_at": { "type": [ "string", "null" ] } } } } }, "example": { "id": "e2b7727e-45ad-42b7-b842-cc4615205b10", "type": "file", "name": "guide.pdf", "filename": "guide.pdf", "extension": "pdf", "content_type": "application/pdf", "byte_size": 1048576, "url": null, "url_expires_at": null, "watermark": { "enabled": true }, "licence_keys": { "autogenerate": false, "tags": [] }, "usage": { "digital_products_count": 0, "orders_count": 0 }, "digital_products": [], "recent_orders": [], "created_at": "2026-10-30T16:49:38Z", "updated_at": "2026-10-30T16:49:38Z", "upload": { "url": "https://files.filemonk.io/uploads/5f3e9c1a/guide.pdf?X-Amz-Expires=3600&X-Amz-Signature=3f6c…", "method": "PUT", "headers": { "Content-Type": "application/pdf" }, "expires_at": "2026-10-31T00:10:00Z" } }, "examples": { "upload_pdf": { "summary": "Upload a PDF with a watermark", "value": { "id": "e2b7727e-45ad-42b7-b842-cc4615205b10", "type": "file", "name": "guide.pdf", "filename": "guide.pdf", "extension": "pdf", "content_type": "application/pdf", "byte_size": 1048576, "url": null, "url_expires_at": null, "watermark": { "enabled": true }, "licence_keys": { "autogenerate": false, "tags": [] }, "usage": { "digital_products_count": 0, "orders_count": 0 }, "digital_products": [], "recent_orders": [], "created_at": "2026-10-30T16:49:38Z", "updated_at": "2026-10-30T16:49:38Z", "upload": { "url": "https://files.filemonk.io/uploads/5f3e9c1a/guide.pdf?X-Amz-Expires=3600&X-Amz-Signature=3f6c…", "method": "PUT", "headers": { "Content-Type": "application/pdf" }, "expires_at": "2026-10-31T00:10:00Z" } } }, "add_link": { "summary": "Add a link to an external download", "value": { "id": "e2b7727e-45ad-42b7-b842-cc4615205b10", "type": "link", "name": "Watercolour course videos", "filename": "watercolour-course-videos.zip", "extension": "zip", "content_type": "application/zip", "byte_size": 0, "url": "https://cdn.example.com/watercolour-course-videos.zip", "url_expires_at": null, "watermark": { "enabled": false }, "licence_keys": { "autogenerate": false, "tags": [] }, "usage": { "digital_products_count": 0, "orders_count": 0 }, "digital_products": [], "recent_orders": [], "created_at": "2026-10-30T16:49:38Z", "updated_at": "2026-10-30T16:49:38Z", "upload": { "url": "https://files.filemonk.io/uploads/5f3e9c1a/guide.pdf?X-Amz-Expires=3600&X-Amz-Signature=3f6c…", "method": "PUT", "headers": { "Content-Type": "application/pdf" }, "expires_at": "2026-10-31T00:10:00Z" } } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "upload a file", "add a file", "add a link", "create a licence key file", "new file", "add a download" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": {}, "name": {}, "url": {}, "file": {}, "watermark": {}, "licence_keys": {} }, "required": [ "type" ] }, "example": { "type": "file", "name": "Beginner's Guide", "file": { "filename": "guide.pdf", "byte_size": 1048576, "content_type": "application/pdf" }, "watermark": { "enabled": true } }, "examples": { "upload_pdf": { "summary": "Upload a PDF with a watermark", "description": "Answers with an upload URL; PUT the file's bytes there within the hour.", "value": { "type": "file", "name": "Beginner's Guide", "file": { "filename": "guide.pdf", "byte_size": 1048576, "content_type": "application/pdf" }, "watermark": { "enabled": true } } }, "add_link": { "summary": "Add a link to an external download", "description": "Nothing is uploaded: buyers get the link.", "value": { "type": "link", "name": "Watercolour course videos", "url": "https://cdn.example.com/watercolour-course-videos.zip" } } } } } } }, "get": { "operationId": "get_assets", "summary": "List", "description": "List the shop's files, links and licence-key assets alphabetically, paginated (page, per_page up to 200). type narrows to file, link or licence_key; search matches the file name the way the Files page search does; licence_tag narrows licence-key assets to one tag. Each row carries how many digital products and orders use it.", "tags": [ "Assets" ], "responses": { "200": { "description": "Success — one page of rows.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "type", "name", "filename", "content_type", "byte_size", "watermark", "licence_keys", "usage", "created_at" ], "properties": { "id": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "filename": { "type": [ "string", "null" ] }, "content_type": { "type": [ "string", "null" ] }, "byte_size": { "type": [ "integer", "null" ] }, "watermark": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": [ "boolean", "null" ] } } }, "licence_keys": { "type": "object", "required": [ "tags" ], "properties": { "tags": { "type": "array" } } }, "usage": { "type": "object", "required": [ "digital_products_count", "orders_count" ], "properties": { "digital_products_count": { "type": [ "integer", "null" ] }, "orders_count": { "type": [ "integer", "null" ] } } }, "created_at": { "type": [ "string", "null" ] } } } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "example": { "data": [ { "id": "e2b7727e-45ad-42b7-b842-cc4615205b10", "type": "link", "name": "ebook-2026", "filename": "ebook-2026.zip", "content_type": "application/zip", "byte_size": 0, "watermark": { "enabled": false }, "licence_keys": { "tags": [] }, "usage": { "digital_products_count": 2, "orders_count": 0 }, "created_at": "2026-10-30T16:49:38Z" } ], "meta": { "total_count": 6, "page": 1, "per_page": 50, "total_pages": 1 } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "list files", "uploaded files", "find a file", "which files are unused", "licence key files" ], "parameters": [ { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "file", "link", "licence_key" ] }, "example": "file" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "description": "1-based page number." }, "example": 1, "description": "1-based page number." }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50, "description": "Rows per page, max 200." }, "example": 50, "description": "Rows per page, max 200." }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "example": "string" }, { "name": "licence_tag", "in": "query", "required": false, "schema": { "type": "string" }, "example": "ebook-2026" } ] } }, "/assets/{id}": { "delete": { "operationId": "delete_assets_id", "summary": "Delete", "description": "Delete a file from the library, as the Files page's Delete does: it leaves every digital product and order it was on, and the stored body is purged. Destructive: send it first without `confirm`. Nothing changes and the 409 `confirmation_required` says what would. Tell the merchant, ask, and resend with `confirm: true` only after they agree. For more than one, use POST /assets/bulk_delete, which previews the counts; don't call this in a loop.\n\n**Note:** Permanent. Buyers lose the file. Without confirm: true nothing is deleted: 409 confirmation_required says how many digital products and orders it is on (GET /assets/:id/linked_orders lists them).", "tags": [ "Assets" ], "responses": { "200": { "description": "Success — the write completed; the body is the updated resource.", "content": { "application/json": { "schema": { "type": "object", "required": [ "deleted", "id" ], "properties": { "deleted": { "type": [ "boolean", "null" ] }, "id": { "type": [ "string", "null" ] } } }, "example": { "deleted": true, "id": "e2b7727e-45ad-42b7-b842-cc4615205b10" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "delete file", "remove file", "delete this upload", "remove the link" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "confirm", "in": "query", "required": false, "schema": { "type": "string" }, "example": "string" } ] }, "get": { "operationId": "get_assets_id", "summary": "Read", "description": "One file in full: name, size and type, a one-hour signed download url for stored files (url_expires_at says when it stops working), watermark and licence-key settings, the digital products it belongs to (with folder) and the last five orders that received it.", "tags": [ "Assets" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "name", "filename", "extension", "content_type", "byte_size", "url", "url_expires_at", "watermark", "licence_keys", "usage", "digital_products", "recent_orders", "created_at", "updated_at" ], "properties": { "id": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "filename": { "type": [ "string", "null" ] }, "extension": { "type": [ "string", "null" ] }, "content_type": { "type": [ "string", "null" ] }, "byte_size": { "type": [ "integer", "null" ] }, "url": { "type": [ "string", "null" ] }, "url_expires_at": {}, "watermark": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": [ "boolean", "null" ] } } }, "licence_keys": { "type": "object", "required": [ "autogenerate", "tags" ], "properties": { "autogenerate": { "type": [ "boolean", "null" ] }, "tags": { "type": "array" } } }, "usage": { "type": "object", "required": [ "digital_products_count", "orders_count" ], "properties": { "digital_products_count": { "type": [ "integer", "null" ] }, "orders_count": { "type": [ "integer", "null" ] } } }, "digital_products": { "type": "array", "items": { "type": "object", "required": [ "id", "scope", "shopify_product_id", "shopify_variant_id", "title", "variant_title", "sku", "files_count", "preorder", "delivery", "exists_on_shopify", "updated_at", "folder" ], "properties": { "id": { "type": [ "string", "null" ] }, "scope": { "type": [ "string", "null" ] }, "shopify_product_id": { "type": [ "string", "null" ] }, "shopify_variant_id": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "variant_title": { "type": [ "string", "null" ] }, "sku": { "type": [ "string", "null" ] }, "files_count": { "type": [ "integer", "null" ] }, "preorder": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": [ "boolean", "null" ] } } }, "delivery": { "type": "object", "required": [ "attach_to_every_order" ], "properties": { "attach_to_every_order": { "type": [ "boolean", "null" ] } } }, "exists_on_shopify": {}, "updated_at": { "type": [ "string", "null" ] }, "folder": {} } } }, "recent_orders": { "type": "array" }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } } }, "example": { "id": "e2b7727e-45ad-42b7-b842-cc4615205b10", "type": "link", "name": "ebook-2026", "filename": "ebook-2026.zip", "extension": "zip", "content_type": "application/zip", "byte_size": 0, "url": "https://example.com/ebook-2026.zip", "url_expires_at": null, "watermark": { "enabled": false }, "licence_keys": { "autogenerate": false, "tags": [] }, "usage": { "digital_products_count": 2, "orders_count": 0 }, "digital_products": [ { "id": "f5f278c8-4a92-48a3-bc40-216468b9bccd", "scope": "variant", "shopify_product_id": "gid://shopify/Product/9642107207975", "shopify_variant_id": "gid://shopify/ProductVariant/49417715843367", "title": "Watercolour Course", "variant_title": "xs / blue / water", "sku": "ae8ea669-7bd1-4afd-b200-a7b75777b46a", "files_count": 2, "preorder": { "enabled": false }, "delivery": { "attach_to_every_order": false }, "exists_on_shopify": null, "updated_at": "2026-10-30T16:55:48Z", "folder": null }, { "id": "4d08443e-549b-44c8-afee-c3836d767e7c", "scope": "product", "shopify_product_id": "gid://shopify/Product/9642103537959", "shopify_variant_id": null, "title": "The Draft Snowboard", "variant_title": null, "sku": null, "files_count": 2, "preorder": { "enabled": false }, "delivery": { "attach_to_every_order": false }, "exists_on_shopify": null, "updated_at": "2026-10-30T16:56:48Z", "folder": "Extras" } ], "recent_orders": [], "created_at": "2026-10-30T16:49:38Z", "updated_at": "2026-10-30T16:49:38Z" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "show file", "file details", "download a file", "which products use this file", "who got this file" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "patch": { "operationId": "patch_assets_id", "summary": "Update", "description": "Change a link's or licence key's name, a link's url, watermark.enabled or licence_keys (autogenerate, tags), as the Files page's edit does. Deep partial: only the fields sent change. A stored file's name is its filename: rename it by replacing the file with POST /assets/:id/replace.\n\n**Note:** Fields that don't apply to the file's type (url on a stored file or licence key, watermark on a link, licence_keys on anything but a licence key) are a 422. Like the Files page, an edit does not re-stamp copies already watermarked for past orders; replacing the file does.", "tags": [ "Assets" ], "responses": { "200": { "description": "Success — the write completed; the body is the updated resource.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "name", "filename", "extension", "content_type", "byte_size", "url", "url_expires_at", "watermark", "licence_keys", "usage", "digital_products", "recent_orders", "created_at", "updated_at" ], "properties": { "id": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "filename": { "type": [ "string", "null" ] }, "extension": { "type": [ "string", "null" ] }, "content_type": { "type": [ "string", "null" ] }, "byte_size": { "type": [ "integer", "null" ] }, "url": { "type": [ "string", "null" ] }, "url_expires_at": {}, "watermark": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": [ "boolean", "null" ] } } }, "licence_keys": { "type": "object", "required": [ "autogenerate", "tags" ], "properties": { "autogenerate": { "type": [ "boolean", "null" ] }, "tags": { "type": "array" } } }, "usage": { "type": "object", "required": [ "digital_products_count", "orders_count" ], "properties": { "digital_products_count": { "type": [ "integer", "null" ] }, "orders_count": { "type": [ "integer", "null" ] } } }, "digital_products": { "type": "array", "items": { "type": "object", "required": [ "id", "scope", "shopify_product_id", "shopify_variant_id", "title", "variant_title", "sku", "files_count", "preorder", "delivery", "exists_on_shopify", "updated_at", "folder" ], "properties": { "id": { "type": [ "string", "null" ] }, "scope": { "type": [ "string", "null" ] }, "shopify_product_id": { "type": [ "string", "null" ] }, "shopify_variant_id": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "variant_title": { "type": [ "string", "null" ] }, "sku": { "type": [ "string", "null" ] }, "files_count": { "type": [ "integer", "null" ] }, "preorder": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": [ "boolean", "null" ] } } }, "delivery": { "type": "object", "required": [ "attach_to_every_order" ], "properties": { "attach_to_every_order": { "type": [ "boolean", "null" ] } } }, "exists_on_shopify": {}, "updated_at": { "type": [ "string", "null" ] }, "folder": {} } } }, "recent_orders": { "type": "array" }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } } }, "example": { "id": "e2b7727e-45ad-42b7-b842-cc4615205b10", "type": "link", "name": "Beginner's Guide (2026 edition)", "filename": "ebook-2026.zip", "extension": "zip", "content_type": "application/zip", "byte_size": 0, "url": "https://example.com/ebook-2026.zip", "url_expires_at": null, "watermark": { "enabled": true }, "licence_keys": { "autogenerate": false, "tags": [] }, "usage": { "digital_products_count": 2, "orders_count": 0 }, "digital_products": [ { "id": "f5f278c8-4a92-48a3-bc40-216468b9bccd", "scope": "variant", "shopify_product_id": "gid://shopify/Product/9642107207975", "shopify_variant_id": "gid://shopify/ProductVariant/49417715843367", "title": "Watercolour Course", "variant_title": "xs / blue / water", "sku": "ae8ea669-7bd1-4afd-b200-a7b75777b46a", "files_count": 2, "preorder": { "enabled": false }, "delivery": { "attach_to_every_order": false }, "exists_on_shopify": null, "updated_at": "2026-10-30T16:55:48Z", "folder": null }, { "id": "4d08443e-549b-44c8-afee-c3836d767e7c", "scope": "product", "shopify_product_id": "gid://shopify/Product/9642103537959", "shopify_variant_id": null, "title": "The Draft Snowboard", "variant_title": null, "sku": null, "files_count": 2, "preorder": { "enabled": false }, "delivery": { "attach_to_every_order": false }, "exists_on_shopify": null, "updated_at": "2026-10-30T16:56:48Z", "folder": "Extras" } ], "recent_orders": [], "created_at": "2026-10-30T16:49:38Z", "updated_at": "2026-10-30T16:49:38Z" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "turn on watermark for a file", "change licence key tags", "edit file", "update the link url", "set file to autogenerate keys" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": {}, "url": {}, "watermark": {}, "licence_keys": {} } }, "example": { "name": "Beginner's Guide (2026 edition)", "watermark": { "enabled": true } } } } } } }, "/assets/{id}/linked_orders": { "get": { "operationId": "get_assets_id_linked_orders", "summary": "Linked Orders", "description": "Which orders and digital products a file is on, as the Files page checks before Delete: the orders that can download it now (newest first, up to 50) and the digital products that deliver it.\n\n**Note:** Read-only. Deleting the file (DELETE /assets/:id) takes it away from every order listed here.", "tags": [ "Assets" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "name", "has_linked_orders", "orders_count", "orders", "digital_products" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "has_linked_orders": { "type": [ "boolean", "null" ] }, "orders_count": { "type": [ "integer", "null" ] }, "orders": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "email", "created_at" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] } } } }, "digital_products": { "type": "array", "items": { "type": "object", "required": [ "id", "title", "variant_title" ], "properties": { "id": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "variant_title": {} } } } } }, "example": { "id": "e2b7727e-45ad-42b7-b842-cc4615205b10", "name": "guide.pdf", "has_linked_orders": true, "orders_count": 1, "orders": [ { "id": "3f1c2b8e-5a7d-4e19-9c61-2b8d0f4a7c55", "name": "#1042", "email": "buyer@example.com", "created_at": "2026-10-28T14:02:11Z" } ], "digital_products": [ { "id": "7ea3c05d-6f29-42b6-b24f-43260caeaa32", "title": "Watercolour Course", "variant_title": null } ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "is this file on any orders", "who has this file", "linked orders for file", "check before deleting file" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/assets/{id}/replace": { "post": { "operationId": "post_assets_id_replace", "summary": "Replace", "description": "Swap the stored body of a file for a new version, keeping its id, products and orders, as the Files page's Replace does. Answers with upload: {url, method, headers, expires_at}; PUT the new body there within the hour.\n\n**Note:** Stored files only (type file). Every watermarked copy is invalidated and re-stamped on next download.", "tags": [ "Assets" ], "responses": { "200": { "description": "Success — the write completed; the body is the updated resource.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "name", "filename", "extension", "content_type", "byte_size", "url", "url_expires_at", "watermark", "licence_keys", "usage", "digital_products", "recent_orders", "created_at", "updated_at", "upload" ], "properties": { "id": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "filename": { "type": [ "string", "null" ] }, "extension": { "type": [ "string", "null" ] }, "content_type": { "type": [ "string", "null" ] }, "byte_size": { "type": [ "integer", "null" ] }, "url": {}, "url_expires_at": {}, "watermark": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": [ "boolean", "null" ] } } }, "licence_keys": { "type": "object", "required": [ "autogenerate", "tags" ], "properties": { "autogenerate": { "type": [ "boolean", "null" ] }, "tags": { "type": "array" } } }, "usage": { "type": "object", "required": [ "digital_products_count", "orders_count" ], "properties": { "digital_products_count": { "type": [ "integer", "null" ] }, "orders_count": { "type": [ "integer", "null" ] } } }, "digital_products": { "type": "array" }, "recent_orders": { "type": "array" }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] }, "upload": { "type": "object", "required": [ "url", "method", "headers", "expires_at" ], "properties": { "url": { "type": [ "string", "null" ] }, "method": { "type": [ "string", "null" ] }, "headers": { "type": "object", "required": [ "Content-Type" ], "properties": { "Content-Type": { "type": [ "string", "null" ] } } }, "expires_at": { "type": [ "string", "null" ] } } } } }, "example": { "id": "e2b7727e-45ad-42b7-b842-cc4615205b10", "type": "file", "name": "guide.pdf", "filename": "guide.pdf", "extension": "pdf", "content_type": "application/pdf", "byte_size": 1048576, "url": null, "url_expires_at": null, "watermark": { "enabled": true }, "licence_keys": { "autogenerate": false, "tags": [] }, "usage": { "digital_products_count": 0, "orders_count": 0 }, "digital_products": [], "recent_orders": [], "created_at": "2026-10-30T16:49:38Z", "updated_at": "2026-10-30T16:49:38Z", "upload": { "url": "https://files.filemonk.io/uploads/5f3e9c1a/guide.pdf?X-Amz-Expires=3600&X-Amz-Signature=3f6c…", "method": "PUT", "headers": { "Content-Type": "application/pdf" }, "expires_at": "2026-10-31T00:10:00Z" } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "replace file", "upload a new version", "swap the file", "update the pdf" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "filename": {}, "byte_size": { "type": "integer" }, "content_type": {} }, "required": [ "filename", "byte_size" ] }, "example": { "filename": "guide-v2.pdf", "byte_size": 2097152, "content_type": "application/pdf" } } } } } }, "/assets/bulk_delete": { "post": { "operationId": "post_assets_bulk_delete", "summary": "Bulk Delete", "description": "Delete several files at once (ids), as the Files page's bulk Delete does. Answers with the ids deleted and the ids that matched nothing. Destructive: send it first without `confirm`. Nothing changes and the 409 `confirmation_required` says what would. Tell the merchant, ask, and resend with `confirm: true` only after they agree.\n\n**Note:** Permanent; each file leaves every product and order it was on. Without confirm: true nothing is deleted: 409 confirmation_required names the files that would go.", "tags": [ "Assets" ], "responses": { "200": { "description": "Success — the write completed; the body is the updated resource.", "content": { "application/json": { "schema": { "type": "object", "required": [ "deleted", "missing" ], "properties": { "deleted": { "type": "array", "items": { "type": [ "string", "null" ] } }, "missing": { "type": "array" } } }, "example": { "deleted": [ "e2b7727e-45ad-42b7-b842-cc4615205b10" ], "missing": [] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "delete these files", "bulk delete files", "remove several files" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string" } }, "confirm": {} }, "required": [ "ids" ] }, "example": { "ids": [ "e2b7727e-45ad-42b7-b842-cc4615205b10" ], "confirm": true } } } } } }, "/customers": { "get": { "operationId": "get_customers", "summary": "List", "description": "List customers Filemonk has delivered to, newest first, paginated (page, per_page up to 200), each with how many orders they have. search matches email, phone or name; email matches exactly; unsubscribed=true narrows to buyers who opted out of the merchant's emails.", "tags": [ "Customers" ], "responses": { "200": { "description": "Success — one page of rows.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "shopify_customer_id", "email", "phone", "first_name", "last_name", "orders_count", "marketing", "created_at", "updated_at" ], "properties": { "id": { "type": [ "string", "null" ] }, "shopify_customer_id": { "type": [ "string", "null" ] }, "email": {}, "phone": {}, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "orders_count": { "type": [ "integer", "null" ] }, "marketing": { "type": "object", "required": [ "unsubscribed", "unsubscribed_at" ], "properties": { "unsubscribed": { "type": [ "boolean", "null" ] }, "unsubscribed_at": {} } }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } } } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "example": { "data": [ { "id": "ca5b4abc-63b1-4e29-be0a-12acb35908c5", "shopify_customer_id": "gid://shopify/Customer/10296813191463", "email": null, "phone": null, "first_name": "Jane", "last_name": "Doe", "orders_count": 1, "marketing": { "unsubscribed": false, "unsubscribed_at": null }, "created_at": "2026-10-26T14:19:29Z", "updated_at": "2026-10-26T14:19:29Z" } ], "meta": { "total_count": 8, "page": 1, "per_page": 50, "total_pages": 1 } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "list customers", "find a customer by email", "unsubscribed customers", "repeat buyers" ], "parameters": [ { "name": "unsubscribed", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ] }, "example": "true" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "description": "1-based page number." }, "example": 1, "description": "1-based page number." }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50, "description": "Rows per page, max 200." }, "example": 50, "description": "Rows per page, max 200." }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "example": "string" }, { "name": "email", "in": "query", "required": false, "schema": { "type": "string" }, "example": "shopper@example.com" } ] } }, "/customers/{id}": { "get": { "operationId": "get_customers_id", "summary": "Read", "description": "One customer by Filemonk id or Shopify Customer gid or id: contact details, order count and whether they unsubscribed from the merchant's emails.", "tags": [ "Customers" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "shopify_customer_id", "email", "phone", "first_name", "last_name", "orders_count", "marketing", "created_at", "updated_at" ], "properties": { "id": { "type": [ "string", "null" ] }, "shopify_customer_id": { "type": [ "string", "null" ] }, "email": {}, "phone": {}, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "orders_count": { "type": [ "integer", "null" ] }, "marketing": { "type": "object", "required": [ "unsubscribed", "unsubscribed_at" ], "properties": { "unsubscribed": { "type": [ "boolean", "null" ] }, "unsubscribed_at": {} } }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } } }, "example": { "id": "ca5b4abc-63b1-4e29-be0a-12acb35908c5", "shopify_customer_id": "gid://shopify/Customer/10296813191463", "email": null, "phone": null, "first_name": "Jane", "last_name": "Doe", "orders_count": 1, "marketing": { "unsubscribed": false, "unsubscribed_at": null }, "created_at": "2026-10-26T14:19:29Z", "updated_at": "2026-10-26T14:19:29Z" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "show customer", "look up customer", "has this customer unsubscribed" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "patch": { "operationId": "patch_customers_id", "summary": "Update", "description": "Opt a customer out of, or back into, the merchant's emails (marketing.unsubscribed), as the unsubscribe link in those emails does. :id is Filemonk's id or a Shopify Customer gid or id.\n\n**Note:** Delivery emails for new orders still go out; this covers the product-update emails. Like the unsubscribe link, it changes every customer of the shop with the same email address.", "tags": [ "Customers" ], "responses": { "200": { "description": "Success — the write completed; the body is the updated resource.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "shopify_customer_id", "email", "phone", "first_name", "last_name", "orders_count", "marketing", "created_at", "updated_at" ], "properties": { "id": { "type": [ "string", "null" ] }, "shopify_customer_id": { "type": [ "string", "null" ] }, "email": {}, "phone": {}, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "orders_count": { "type": [ "integer", "null" ] }, "marketing": { "type": "object", "required": [ "unsubscribed", "unsubscribed_at" ], "properties": { "unsubscribed": { "type": [ "boolean", "null" ] }, "unsubscribed_at": { "type": [ "string", "null" ] } } }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } } }, "example": { "id": "ca5b4abc-63b1-4e29-be0a-12acb35908c5", "shopify_customer_id": "gid://shopify/Customer/10296813191463", "email": null, "phone": null, "first_name": "Jane", "last_name": "Doe", "orders_count": 1, "marketing": { "unsubscribed": true, "unsubscribed_at": "2026-10-30T23:10:00Z" }, "created_at": "2026-10-26T14:19:29Z", "updated_at": "2026-10-26T14:19:29Z" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "unsubscribe customer", "resubscribe customer", "stop emailing this customer", "opt customer back in" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "marketing": {} }, "required": [ "marketing" ] }, "example": { "marketing": { "unsubscribed": true } } } } } } }, "/customers/{id}/orders": { "get": { "operationId": "get_customers_id_orders", "summary": "Orders", "description": "The orders Filemonk delivered for one customer, newest first, paginated, as order summaries.", "tags": [ "Customers" ], "responses": { "200": { "description": "Success — one page of rows.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "shopify_order_id", "name", "ordered_at", "customer", "total", "status", "access", "delivery", "line_items_count", "created_at" ], "properties": { "id": { "type": [ "string", "null" ] }, "shopify_order_id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "ordered_at": { "type": [ "string", "null" ] }, "customer": { "type": "object", "required": [ "email", "first_name", "last_name" ], "properties": { "email": {}, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] } } }, "total": { "type": "object", "required": [ "amount", "currency" ], "properties": { "amount": { "type": [ "string", "null" ] }, "currency": { "type": [ "string", "null" ] } } }, "status": { "type": "object", "required": [ "financial", "flagged_as_fraud" ], "properties": { "financial": { "type": [ "string", "null" ] }, "flagged_as_fraud": { "type": [ "boolean", "null" ] } } }, "access": { "type": "object", "required": [ "state", "downloads_count" ], "properties": { "state": { "type": [ "string", "null" ] }, "downloads_count": { "type": [ "integer", "null" ] } } }, "delivery": { "type": "object", "required": [ "email_sent_at" ], "properties": { "email_sent_at": {} } }, "line_items_count": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ] } } } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "example": { "data": [ { "id": "b18e92ce-3ce8-467e-983c-f60ccd421300", "shopify_order_id": "gid://shopify/Order/7555375628583", "name": "#1078", "ordered_at": "2026-10-26T14:19:16Z", "customer": { "email": null, "first_name": "Jane", "last_name": "Doe" }, "total": { "amount": "357.51", "currency": "INR" }, "status": { "financial": "paid", "flagged_as_fraud": false }, "access": { "state": "active", "downloads_count": 0 }, "delivery": { "email_sent_at": null }, "line_items_count": 1, "created_at": "2026-10-26T14:19:29Z" } ], "meta": { "total_count": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "orders of a customer", "what has this customer bought", "customer purchase history" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "description": "1-based page number." }, "example": 1, "description": "1-based page number." }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50, "description": "Rows per page, max 200." }, "example": 50, "description": "Rows per page, max 200." } ] } }, "/digital_products": { "post": { "operationId": "post_digital_products", "summary": "Create", "description": "Make a Shopify product or one of its variants a digital product, as the Products page's Add does: give shopify_product_id (whole product) or shopify_variant_id (one variant; add shopify_product_id too unless Filemonk already knows the variant), the files to deliver as files: [{id, folder}], and optionally delivery.message, delivery.attach_to_every_order, preorder {enabled, launch_at, email {subject, heading, description}} (enabling a pre-order needs launch_at and delivery.message) and update_email {subject, body}.\n\n**Note:** preorder.enabled: true needs preorder.launch_at at least two hours ahead and a delivery.message (422 naming the missing field otherwise). 404 when Shopify has no such product or variant in this store. 409 when the product or variant already is a digital product (PATCH it instead). Buyers of existing orders are not emailed; use POST /digital_products/:id/notify_buyers.", "tags": [ "Digital Products" ], "responses": { "200": { "description": "Success — the resource already existed; here it is.", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "201": { "description": "Created — the new resource.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "scope", "shopify_product_id", "shopify_variant_id", "title", "variant_title", "sku", "exists_on_shopify", "files", "folders", "delivery", "preorder", "update_email", "orders_count", "created_at", "updated_at" ], "properties": { "id": { "type": [ "string", "null" ] }, "scope": { "type": [ "string", "null" ] }, "shopify_product_id": { "type": [ "string", "null" ] }, "shopify_variant_id": {}, "title": { "type": [ "string", "null" ] }, "variant_title": {}, "sku": {}, "exists_on_shopify": {}, "files": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "type", "byte_size", "folder" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "byte_size": { "type": [ "integer", "null" ] }, "folder": {} } } }, "folders": { "type": "array" }, "delivery": { "type": "object", "required": [ "message", "attach_to_every_order" ], "properties": { "message": {}, "attach_to_every_order": { "type": [ "boolean", "null" ] } } }, "preorder": { "type": "object", "required": [ "enabled", "launch_at", "released", "email" ], "properties": { "enabled": { "type": [ "boolean", "null" ] }, "launch_at": {}, "released": { "type": [ "boolean", "null" ] }, "email": { "type": "object", "required": [ "subject", "heading", "description" ], "properties": { "subject": {}, "heading": {}, "description": {} } } } }, "update_email": { "type": "object", "required": [ "subject", "body" ], "properties": { "subject": {}, "body": {} } }, "orders_count": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } } }, "example": { "id": "7ea3c05d-6f29-42b6-b24f-43260caeaa32", "scope": "product", "shopify_product_id": "gid://shopify/Product/9642107044135", "shopify_variant_id": null, "title": "Watercolour Course", "variant_title": null, "sku": null, "exists_on_shopify": null, "files": [ { "id": "7ea42f2a-6dbe-459c-b8a4-27b0eb823e52", "name": "price-list.csv", "type": "file", "byte_size": 100634, "folder": null }, { "id": "96fbe30b-c819-4cb8-9666-814c0c8853f1", "name": "Beginner's Guide.pdf", "type": "file", "byte_size": 116711, "folder": null } ], "folders": [], "delivery": { "message": null, "attach_to_every_order": false }, "preorder": { "enabled": false, "launch_at": null, "released": true, "email": { "subject": null, "heading": null, "description": null } }, "update_email": { "subject": null, "body": null }, "orders_count": 46, "created_at": "2025-05-31T13:37:52Z", "updated_at": "2025-05-31T13:37:52Z" }, "examples": { "whole_product": { "summary": "Deliver files for a whole product", "value": { "id": "7ea3c05d-6f29-42b6-b24f-43260caeaa32", "scope": "product", "shopify_product_id": "gid://shopify/Product/9642107044135", "shopify_variant_id": null, "title": "Watercolour Course", "variant_title": null, "sku": null, "exists_on_shopify": null, "files": [ { "id": "7ea42f2a-6dbe-459c-b8a4-27b0eb823e52", "name": "price-list.csv", "type": "file", "byte_size": 100634, "folder": null }, { "id": "96fbe30b-c819-4cb8-9666-814c0c8853f1", "name": "Beginner's Guide.pdf", "type": "file", "byte_size": 116711, "folder": null } ], "folders": [], "delivery": { "message": null, "attach_to_every_order": false }, "preorder": { "enabled": false, "launch_at": null, "released": true, "email": { "subject": null, "heading": null, "description": null } }, "update_email": { "subject": null, "body": null }, "orders_count": 46, "created_at": "2025-05-31T13:37:52Z", "updated_at": "2025-05-31T13:37:52Z" } }, "one_variant": { "summary": "Deliver files for one variant", "value": { "id": "7ea3c05d-6f29-42b6-b24f-43260caeaa32", "scope": "variant", "shopify_product_id": "gid://shopify/Product/9642107207975", "shopify_variant_id": "gid://shopify/ProductVariant/49417715843367", "title": "Watercolour Course", "variant_title": "xs / blue / water", "sku": null, "exists_on_shopify": null, "files": [ { "id": "7ea42f2a-6dbe-459c-b8a4-27b0eb823e52", "name": "price-list.csv", "type": "file", "byte_size": 100634, "folder": null }, { "id": "96fbe30b-c819-4cb8-9666-814c0c8853f1", "name": "Beginner's Guide.pdf", "type": "file", "byte_size": 116711, "folder": null } ], "folders": [], "delivery": { "message": null, "attach_to_every_order": false }, "preorder": { "enabled": false, "launch_at": null, "released": true, "email": { "subject": null, "heading": null, "description": null } }, "update_email": { "subject": null, "body": null }, "orders_count": 0, "created_at": "2025-05-31T13:37:52Z", "updated_at": "2025-05-31T13:37:52Z" } }, "preorder": { "summary": "Sell it as a pre-order", "value": { "id": "7ea3c05d-6f29-42b6-b24f-43260caeaa32", "scope": "product", "shopify_product_id": "gid://shopify/Product/9642107044135", "shopify_variant_id": null, "title": "Watercolour Course", "variant_title": null, "sku": null, "exists_on_shopify": null, "files": [ { "id": "7ea42f2a-6dbe-459c-b8a4-27b0eb823e52", "name": "price-list.csv", "type": "file", "byte_size": 100634, "folder": null }, { "id": "96fbe30b-c819-4cb8-9666-814c0c8853f1", "name": "Beginner's Guide.pdf", "type": "file", "byte_size": 116711, "folder": null } ], "folders": [], "delivery": { "message": "Thanks for pre-ordering! Your files arrive on launch day.", "attach_to_every_order": false }, "preorder": { "enabled": true, "launch_at": "2026-12-01T09:00:00Z", "released": false, "email": { "subject": null, "heading": null, "description": null } }, "update_email": { "subject": null, "body": null }, "orders_count": 0, "created_at": "2025-05-31T13:37:52Z", "updated_at": "2025-05-31T13:37:52Z" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "add digital product", "attach files to a product", "make this product digital", "set up delivery for a variant", "new digital product" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "shopify_product_id": {}, "shopify_variant_id": {}, "files": {}, "delivery": {}, "preorder": {}, "update_email": {} } }, "example": { "shopify_product_id": "gid://shopify/Product/9642107044135", "files": [ { "id": "e2b7727e-45ad-42b7-b842-cc4615205b10", "folder": "Extras" } ], "delivery": { "message": "Thanks for your order! Your files are below.", "attach_to_every_order": false } }, "examples": { "whole_product": { "summary": "Deliver files for a whole product", "value": { "shopify_product_id": "gid://shopify/Product/9642107044135", "files": [ { "id": "e2b7727e-45ad-42b7-b842-cc4615205b10", "folder": "Extras" } ], "delivery": { "message": "Thanks for your order! Your files are below.", "attach_to_every_order": false } } }, "one_variant": { "summary": "Deliver files for one variant", "value": { "shopify_product_id": "gid://shopify/Product/9642107207975", "shopify_variant_id": "gid://shopify/ProductVariant/49417715843367", "files": [ { "id": "e2b7727e-45ad-42b7-b842-cc4615205b10" } ] } }, "preorder": { "summary": "Sell it as a pre-order", "description": "launch_at must be at least two hours ahead, and a pre-order needs delivery.message.", "value": { "shopify_product_id": "gid://shopify/Product/9642107044135", "files": [ { "id": "e2b7727e-45ad-42b7-b842-cc4615205b10" } ], "delivery": { "message": "Thanks for pre-ordering! Your files arrive on launch day." }, "preorder": { "enabled": true, "launch_at": "2026-12-01T09:00:00Z" } } } } } } } }, "get": { "operationId": "get_digital_products", "summary": "List", "description": "List the digital products (Shopify products or variants with files attached in Filemonk), by product title, paginated (page, per_page up to 200). search matches title, variant title or SKU the way the Products page search does; scope is product or variant; shopify_product_id / shopify_variant_id narrow to one Shopify product or variant; preorder and attach_to_every_order take true or false.", "tags": [ "Digital Products" ], "responses": { "200": { "description": "Success — one page of rows.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "scope", "shopify_product_id", "shopify_variant_id", "title", "variant_title", "sku", "files_count", "preorder", "delivery", "exists_on_shopify", "updated_at" ], "properties": { "id": { "type": [ "string", "null" ] }, "scope": { "type": [ "string", "null" ] }, "shopify_product_id": { "type": [ "string", "null" ] }, "shopify_variant_id": {}, "title": { "type": [ "string", "null" ] }, "variant_title": {}, "sku": {}, "files_count": { "type": [ "integer", "null" ] }, "preorder": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": [ "boolean", "null" ] } } }, "delivery": { "type": "object", "required": [ "attach_to_every_order" ], "properties": { "attach_to_every_order": { "type": [ "boolean", "null" ] } } }, "exists_on_shopify": {}, "updated_at": { "type": [ "string", "null" ] } } } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "example": { "data": [ { "id": "7ea3c05d-6f29-42b6-b24f-43260caeaa32", "scope": "product", "shopify_product_id": "gid://shopify/Product/9642107044135", "shopify_variant_id": null, "title": "Watercolour Course", "variant_title": null, "sku": null, "files_count": 2, "preorder": { "enabled": false }, "delivery": { "attach_to_every_order": false }, "exists_on_shopify": null, "updated_at": "2025-05-31T13:37:52Z" } ], "meta": { "total_count": 6, "page": 1, "per_page": 50, "total_pages": 1 } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "list digital products", "which products deliver files", "products with pre-orders", "find the digital product for a variant", "products attached to every order" ], "parameters": [ { "name": "scope", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "product", "variant" ] }, "example": "product" }, { "name": "preorder", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ] }, "example": "true" }, { "name": "attach_to_every_order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ] }, "example": "true" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "description": "1-based page number." }, "example": 1, "description": "1-based page number." }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50, "description": "Rows per page, max 200." }, "example": 50, "description": "Rows per page, max 200." }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "example": "string" }, { "name": "shopify_product_id", "in": "query", "required": false, "schema": { "type": "string" }, "example": "gid://shopify/Product/78000000001" }, { "name": "shopify_variant_id", "in": "query", "required": false, "schema": { "type": "string" }, "example": "gid://shopify/ProductVariant/45000000001" } ] } }, "/digital_products/{id}": { "delete": { "operationId": "delete_digital_products_id", "summary": "Delete", "description": "Stop delivering files for this product or variant, as the Products page's Delete does. The files stay in the library; the Shopify product is untouched. Destructive: send it first without `confirm`. Nothing changes and the 409 `confirmation_required` says what would. Tell the merchant, ask, and resend with `confirm: true` only after they agree.\n\n**Note:** Permanent: existing buyers lose the download for this product. Without confirm: true nothing is deleted: 409 confirmation_required says how many files and orders it covers.", "tags": [ "Digital Products" ], "responses": { "200": { "description": "Success — the write completed; the body is the updated resource.", "content": { "application/json": { "schema": { "type": "object", "required": [ "deleted", "id" ], "properties": { "deleted": { "type": [ "boolean", "null" ] }, "id": { "type": [ "string", "null" ] } } }, "example": { "deleted": true, "id": "7ea3c05d-6f29-42b6-b24f-43260caeaa32" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "delete digital product", "remove files from product", "stop delivering this product" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "confirm", "in": "query", "required": false, "schema": { "type": "string" }, "example": "string" } ] }, "get": { "operationId": "get_digital_products_id", "summary": "Read", "description": "One digital product in full: the Shopify product or variant it belongs to, every file with its folder, delivery message, pre-order and update-email settings, and how many orders received it. :id is Filemonk's id or a Shopify ProductVariant / Product gid or id.", "tags": [ "Digital Products" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "scope", "shopify_product_id", "shopify_variant_id", "title", "variant_title", "sku", "exists_on_shopify", "files", "folders", "delivery", "preorder", "update_email", "orders_count", "created_at", "updated_at" ], "properties": { "id": { "type": [ "string", "null" ] }, "scope": { "type": [ "string", "null" ] }, "shopify_product_id": { "type": [ "string", "null" ] }, "shopify_variant_id": {}, "title": { "type": [ "string", "null" ] }, "variant_title": {}, "sku": {}, "exists_on_shopify": {}, "files": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "type", "byte_size", "folder" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "byte_size": { "type": [ "integer", "null" ] }, "folder": {} } } }, "folders": { "type": "array" }, "delivery": { "type": "object", "required": [ "message", "attach_to_every_order" ], "properties": { "message": {}, "attach_to_every_order": { "type": [ "boolean", "null" ] } } }, "preorder": { "type": "object", "required": [ "enabled", "launch_at", "released", "email" ], "properties": { "enabled": { "type": [ "boolean", "null" ] }, "launch_at": {}, "released": { "type": [ "boolean", "null" ] }, "email": { "type": "object", "required": [ "subject", "heading", "description" ], "properties": { "subject": {}, "heading": {}, "description": {} } } } }, "update_email": { "type": "object", "required": [ "subject", "body" ], "properties": { "subject": {}, "body": {} } }, "orders_count": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } } }, "example": { "id": "7ea3c05d-6f29-42b6-b24f-43260caeaa32", "scope": "product", "shopify_product_id": "gid://shopify/Product/9642107044135", "shopify_variant_id": null, "title": "Watercolour Course", "variant_title": null, "sku": null, "exists_on_shopify": null, "files": [ { "id": "7ea42f2a-6dbe-459c-b8a4-27b0eb823e52", "name": "price-list.csv", "type": "file", "byte_size": 100634, "folder": null }, { "id": "96fbe30b-c819-4cb8-9666-814c0c8853f1", "name": "Beginner's Guide.pdf", "type": "file", "byte_size": 116711, "folder": null } ], "folders": [], "delivery": { "message": null, "attach_to_every_order": false }, "preorder": { "enabled": false, "launch_at": null, "released": true, "email": { "subject": null, "heading": null, "description": null } }, "update_email": { "subject": null, "body": null }, "orders_count": 46, "created_at": "2025-05-31T13:37:52Z", "updated_at": "2025-05-31T13:37:52Z" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "show digital product", "files attached to a product", "pre-order settings of a product", "what does this variant deliver" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "patch": { "operationId": "patch_digital_products_id", "summary": "Update", "description": "Change a digital product's files or settings, as the product page does. Deep partial: delivery.message, delivery.attach_to_every_order, preorder.*, update_email.* change only when sent; files: [{id, folder}] replaces the whole file list and folders (add or remove single files with POST /digital_products/:id/files/attach and /detach instead). Enabling a pre-order needs preorder.launch_at and a delivery.message, sent now or already saved.\n\n**Note:** preorder.launch_at must be at least two hours ahead (422 naming the field otherwise). The Shopify product or variant cannot be changed; make a new digital product.", "tags": [ "Digital Products" ], "responses": { "200": { "description": "Success — the write completed; the body is the updated resource.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "scope", "shopify_product_id", "shopify_variant_id", "title", "variant_title", "sku", "exists_on_shopify", "files", "folders", "delivery", "preorder", "update_email", "orders_count", "created_at", "updated_at" ], "properties": { "id": { "type": [ "string", "null" ] }, "scope": { "type": [ "string", "null" ] }, "shopify_product_id": { "type": [ "string", "null" ] }, "shopify_variant_id": {}, "title": { "type": [ "string", "null" ] }, "variant_title": {}, "sku": {}, "exists_on_shopify": {}, "files": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "type", "byte_size", "folder" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "byte_size": { "type": [ "integer", "null" ] }, "folder": {} } } }, "folders": { "type": "array" }, "delivery": { "type": "object", "required": [ "message", "attach_to_every_order" ], "properties": { "message": {}, "attach_to_every_order": { "type": [ "boolean", "null" ] } } }, "preorder": { "type": "object", "required": [ "enabled", "launch_at", "released", "email" ], "properties": { "enabled": { "type": [ "boolean", "null" ] }, "launch_at": {}, "released": { "type": [ "boolean", "null" ] }, "email": { "type": "object", "required": [ "subject", "heading", "description" ], "properties": { "subject": {}, "heading": {}, "description": {} } } } }, "update_email": { "type": "object", "required": [ "subject", "body" ], "properties": { "subject": {}, "body": {} } }, "orders_count": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } } }, "example": { "id": "7ea3c05d-6f29-42b6-b24f-43260caeaa32", "scope": "product", "shopify_product_id": "gid://shopify/Product/9642107044135", "shopify_variant_id": null, "title": "Watercolour Course", "variant_title": null, "sku": null, "exists_on_shopify": null, "files": [ { "id": "7ea42f2a-6dbe-459c-b8a4-27b0eb823e52", "name": "price-list.csv", "type": "file", "byte_size": 100634, "folder": null }, { "id": "96fbe30b-c819-4cb8-9666-814c0c8853f1", "name": "Beginner's Guide.pdf", "type": "file", "byte_size": 116711, "folder": null } ], "folders": [], "delivery": { "message": null, "attach_to_every_order": false }, "preorder": { "enabled": false, "launch_at": null, "released": true, "email": { "subject": null, "heading": null, "description": null } }, "update_email": { "subject": null, "body": null }, "orders_count": 46, "created_at": "2025-05-31T13:37:52Z", "updated_at": "2025-05-31T13:37:52Z" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "edit digital product", "change delivery message", "enable pre-order", "set launch date", "move file into folder", "update the product's files" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "files": {}, "delivery": {}, "preorder": {}, "update_email": {} } }, "example": { "delivery": { "message": "Thanks for your order! Your files are below." }, "preorder": { "enabled": true, "launch_at": "2026-12-01T09:00:00Z" } } } } } } }, "/digital_products/{id}/files/attach": { "post": { "operationId": "post_digital_products_id_files_attach", "summary": "Files Attach", "description": "Add files (asset_ids) to a digital product, optionally inside a folder on the download page, as the product page's Add files does. Files already on it are left as they are.\n\n**Note:** Buyers who already have the product get the new file on their download page at once; no email is sent.", "tags": [ "Digital Products" ], "responses": { "200": { "description": "Success — the write completed; the body is the updated resource.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "scope", "shopify_product_id", "shopify_variant_id", "title", "variant_title", "sku", "exists_on_shopify", "files", "folders", "delivery", "preorder", "update_email", "orders_count", "created_at", "updated_at" ], "properties": { "id": { "type": [ "string", "null" ] }, "scope": { "type": [ "string", "null" ] }, "shopify_product_id": { "type": [ "string", "null" ] }, "shopify_variant_id": {}, "title": { "type": [ "string", "null" ] }, "variant_title": {}, "sku": {}, "exists_on_shopify": {}, "files": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "type", "byte_size", "folder" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "byte_size": { "type": [ "integer", "null" ] }, "folder": {} } } }, "folders": { "type": "array" }, "delivery": { "type": "object", "required": [ "message", "attach_to_every_order" ], "properties": { "message": {}, "attach_to_every_order": { "type": [ "boolean", "null" ] } } }, "preorder": { "type": "object", "required": [ "enabled", "launch_at", "released", "email" ], "properties": { "enabled": { "type": [ "boolean", "null" ] }, "launch_at": {}, "released": { "type": [ "boolean", "null" ] }, "email": { "type": "object", "required": [ "subject", "heading", "description" ], "properties": { "subject": {}, "heading": {}, "description": {} } } } }, "update_email": { "type": "object", "required": [ "subject", "body" ], "properties": { "subject": {}, "body": {} } }, "orders_count": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } } }, "example": { "id": "7ea3c05d-6f29-42b6-b24f-43260caeaa32", "scope": "product", "shopify_product_id": "gid://shopify/Product/9642107044135", "shopify_variant_id": null, "title": "Watercolour Course", "variant_title": null, "sku": null, "exists_on_shopify": null, "files": [ { "id": "7ea42f2a-6dbe-459c-b8a4-27b0eb823e52", "name": "price-list.csv", "type": "file", "byte_size": 100634, "folder": null }, { "id": "96fbe30b-c819-4cb8-9666-814c0c8853f1", "name": "Beginner's Guide.pdf", "type": "file", "byte_size": 116711, "folder": null } ], "folders": [], "delivery": { "message": null, "attach_to_every_order": false }, "preorder": { "enabled": false, "launch_at": null, "released": true, "email": { "subject": null, "heading": null, "description": null } }, "update_email": { "subject": null, "body": null }, "orders_count": 46, "created_at": "2025-05-31T13:37:52Z", "updated_at": "2025-05-31T13:37:52Z" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "attach file to product", "add a file to this product", "put files in a folder", "link upload to variant" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "asset_ids": { "type": "array", "items": { "type": "string" } }, "folder": {} }, "required": [ "asset_ids" ] }, "example": { "asset_ids": [ "e2b7727e-45ad-42b7-b842-cc4615205b10" ], "folder": "Extras" } } } } } }, "/digital_products/{id}/files/detach": { "post": { "operationId": "post_digital_products_id_files_detach", "summary": "Files Detach", "description": "Remove files (asset_ids) from a digital product, as the product page's Remove does. The files stay in the library and on any other product. Destructive: send it first without `confirm`. Nothing changes and the 409 `confirmation_required` says what would. Tell the merchant, ask, and resend with `confirm: true` only after they agree.\n\n**Note:** Without confirm: true nothing changes: 409 confirmation_required names the files and how many orders lose them. Attach them again to undo.", "tags": [ "Digital Products" ], "responses": { "200": { "description": "Success — the write completed; the body is the updated resource.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "scope", "shopify_product_id", "shopify_variant_id", "title", "variant_title", "sku", "exists_on_shopify", "files", "folders", "delivery", "preorder", "update_email", "orders_count", "created_at", "updated_at" ], "properties": { "id": { "type": [ "string", "null" ] }, "scope": { "type": [ "string", "null" ] }, "shopify_product_id": { "type": [ "string", "null" ] }, "shopify_variant_id": {}, "title": { "type": [ "string", "null" ] }, "variant_title": {}, "sku": {}, "exists_on_shopify": {}, "files": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "type", "byte_size", "folder" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "byte_size": { "type": [ "integer", "null" ] }, "folder": {} } } }, "folders": { "type": "array" }, "delivery": { "type": "object", "required": [ "message", "attach_to_every_order" ], "properties": { "message": {}, "attach_to_every_order": { "type": [ "boolean", "null" ] } } }, "preorder": { "type": "object", "required": [ "enabled", "launch_at", "released", "email" ], "properties": { "enabled": { "type": [ "boolean", "null" ] }, "launch_at": {}, "released": { "type": [ "boolean", "null" ] }, "email": { "type": "object", "required": [ "subject", "heading", "description" ], "properties": { "subject": {}, "heading": {}, "description": {} } } } }, "update_email": { "type": "object", "required": [ "subject", "body" ], "properties": { "subject": {}, "body": {} } }, "orders_count": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } } }, "example": { "id": "7ea3c05d-6f29-42b6-b24f-43260caeaa32", "scope": "product", "shopify_product_id": "gid://shopify/Product/9642107044135", "shopify_variant_id": null, "title": "Watercolour Course", "variant_title": null, "sku": null, "exists_on_shopify": null, "files": [ { "id": "7ea42f2a-6dbe-459c-b8a4-27b0eb823e52", "name": "price-list.csv", "type": "file", "byte_size": 100634, "folder": null }, { "id": "96fbe30b-c819-4cb8-9666-814c0c8853f1", "name": "Beginner's Guide.pdf", "type": "file", "byte_size": 116711, "folder": null } ], "folders": [], "delivery": { "message": null, "attach_to_every_order": false }, "preorder": { "enabled": false, "launch_at": null, "released": true, "email": { "subject": null, "heading": null, "description": null } }, "update_email": { "subject": null, "body": null }, "orders_count": 46, "created_at": "2025-05-31T13:37:52Z", "updated_at": "2025-05-31T13:37:52Z" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "detach file from product", "remove a file from this product", "unlink upload" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "asset_ids": { "type": "array", "items": { "type": "string" } }, "confirm": {} }, "required": [ "asset_ids" ] }, "example": { "asset_ids": [ "e2b7727e-45ad-42b7-b842-cc4615205b10" ] } } } } } }, "/digital_products/{id}/notify_buyers": { "post": { "operationId": "post_digital_products_id_notify_buyers", "summary": "Notify Buyers", "description": "Email everyone who bought this product that it was updated, with a link to their download page, as the product page's Notify customers does. subject and body default to the product's update_email; save_as_default stores the ones sent for next time.\n\n**Note:** Queued: sends happen in the background to every kept order with the product. 404 when no order has it yet, 422 without a subject and body.", "tags": [ "Digital Products" ], "responses": { "200": { "description": "Success — the write completed; the body is the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "202": { "description": "Accepted — the change was saved and the rest of the work (emails, Shopify sync, a bulk job) continues in the background. The body is the resource snapshot plus `queued: true`; there is nothing to poll.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "scope", "shopify_product_id", "shopify_variant_id", "title", "variant_title", "sku", "exists_on_shopify", "files", "folders", "delivery", "preorder", "update_email", "orders_count", "created_at", "updated_at", "queued", "subject" ], "properties": { "id": { "type": [ "string", "null" ] }, "scope": { "type": [ "string", "null" ] }, "shopify_product_id": { "type": [ "string", "null" ] }, "shopify_variant_id": {}, "title": { "type": [ "string", "null" ] }, "variant_title": {}, "sku": {}, "exists_on_shopify": {}, "files": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "type", "byte_size", "folder" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "byte_size": { "type": [ "integer", "null" ] }, "folder": {} } } }, "folders": { "type": "array" }, "delivery": { "type": "object", "required": [ "message", "attach_to_every_order" ], "properties": { "message": {}, "attach_to_every_order": { "type": [ "boolean", "null" ] } } }, "preorder": { "type": "object", "required": [ "enabled", "launch_at", "released", "email" ], "properties": { "enabled": { "type": [ "boolean", "null" ] }, "launch_at": {}, "released": { "type": [ "boolean", "null" ] }, "email": { "type": "object", "required": [ "subject", "heading", "description" ], "properties": { "subject": {}, "heading": {}, "description": {} } } } }, "update_email": { "type": "object", "required": [ "subject", "body" ], "properties": { "subject": {}, "body": {} } }, "orders_count": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] }, "queued": { "type": [ "boolean", "null" ] }, "subject": { "type": [ "string", "null" ] } } }, "example": { "id": "7ea3c05d-6f29-42b6-b24f-43260caeaa32", "scope": "product", "shopify_product_id": "gid://shopify/Product/9642107044135", "shopify_variant_id": null, "title": "Watercolour Course", "variant_title": null, "sku": null, "exists_on_shopify": null, "files": [ { "id": "7ea42f2a-6dbe-459c-b8a4-27b0eb823e52", "name": "price-list.csv", "type": "file", "byte_size": 100634, "folder": null }, { "id": "96fbe30b-c819-4cb8-9666-814c0c8853f1", "name": "Beginner's Guide.pdf", "type": "file", "byte_size": 116711, "folder": null } ], "folders": [], "delivery": { "message": null, "attach_to_every_order": false }, "preorder": { "enabled": false, "launch_at": null, "released": true, "email": { "subject": null, "heading": null, "description": null } }, "update_email": { "subject": null, "body": null }, "orders_count": 46, "created_at": "2025-05-31T13:37:52Z", "updated_at": "2025-05-31T13:37:52Z", "queued": true, "subject": "Your course has been updated" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "notify buyers", "tell customers the file changed", "send product update email", "email everyone who bought this" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "subject": {}, "body": {}, "save_as_default": {} } }, "example": { "subject": "Your course has been updated", "body": "We added two new chapters. Download the new version from your download page.", "save_as_default": false } } } } } }, "/digital_products/{id}/refresh": { "post": { "operationId": "post_digital_products_id_refresh", "summary": "Refresh", "description": "Ask Shopify for the product's current title, variant title and sku and store them, as opening the product page does. The answer is the digital product with exists_on_shopify filled in: false when Shopify no longer has the product or variant.\n\n**Note:** Calls Shopify. The stored title, variant title and sku are overwritten with Shopify's; nothing else changes, and a deleted product keeps delivering until it is removed in Filemonk (Products page, or DELETE /digital_products/:id over REST).", "tags": [ "Digital Products" ], "responses": { "200": { "description": "Success — the write completed; the body is the updated resource.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "scope", "shopify_product_id", "shopify_variant_id", "title", "variant_title", "sku", "exists_on_shopify", "files", "folders", "delivery", "preorder", "update_email", "orders_count", "created_at", "updated_at" ], "properties": { "id": { "type": [ "string", "null" ] }, "scope": { "type": [ "string", "null" ] }, "shopify_product_id": { "type": [ "string", "null" ] }, "shopify_variant_id": {}, "title": { "type": [ "string", "null" ] }, "variant_title": {}, "sku": {}, "exists_on_shopify": { "type": [ "boolean", "null" ] }, "files": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "type", "byte_size", "folder" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "byte_size": { "type": [ "integer", "null" ] }, "folder": {} } } }, "folders": { "type": "array" }, "delivery": { "type": "object", "required": [ "message", "attach_to_every_order" ], "properties": { "message": {}, "attach_to_every_order": { "type": [ "boolean", "null" ] } } }, "preorder": { "type": "object", "required": [ "enabled", "launch_at", "released", "email" ], "properties": { "enabled": { "type": [ "boolean", "null" ] }, "launch_at": {}, "released": { "type": [ "boolean", "null" ] }, "email": { "type": "object", "required": [ "subject", "heading", "description" ], "properties": { "subject": {}, "heading": {}, "description": {} } } } }, "update_email": { "type": "object", "required": [ "subject", "body" ], "properties": { "subject": {}, "body": {} } }, "orders_count": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } } }, "example": { "id": "7ea3c05d-6f29-42b6-b24f-43260caeaa32", "scope": "product", "shopify_product_id": "gid://shopify/Product/9642107044135", "shopify_variant_id": null, "title": "Watercolour Course", "variant_title": null, "sku": null, "exists_on_shopify": true, "files": [ { "id": "7ea42f2a-6dbe-459c-b8a4-27b0eb823e52", "name": "price-list.csv", "type": "file", "byte_size": 100634, "folder": null }, { "id": "96fbe30b-c819-4cb8-9666-814c0c8853f1", "name": "Beginner's Guide.pdf", "type": "file", "byte_size": 116711, "folder": null } ], "folders": [], "delivery": { "message": null, "attach_to_every_order": false }, "preorder": { "enabled": false, "launch_at": null, "released": true, "email": { "subject": null, "heading": null, "description": null } }, "update_email": { "subject": null, "body": null }, "orders_count": 46, "created_at": "2025-05-31T13:37:52Z", "updated_at": "2025-05-31T13:37:52Z" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/BadGateway" } }, "x-aliases": [ "refresh product from shopify", "is this product still on shopify", "update product title", "check deleted product" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/digital_products/deleted_on_shopify": { "get": { "operationId": "get_digital_products_deleted_on_shopify", "summary": "Deleted On Shopify", "description": "Check a page of digital products against Shopify, as the Products page does when it labels products deleted on Shopify: for each, whether its Shopify product or variant still exists. Same order and paging as GET /digital_products (page, per_page up to 200).\n\n**Note:** Read-only; asks Shopify. A product deleted on Shopify can't be bought, so its digital product only serves past orders; delete it (DELETE /digital_products/:id) only if those buyers should lose it. 502 when Shopify did not answer.", "tags": [ "Digital Products" ], "responses": { "200": { "description": "Success — one page of rows.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "deleted_count", "meta" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "title", "variant_title", "shopify_product_id", "shopify_variant_id", "product_deleted", "variant_deleted", "deleted_on_shopify" ], "properties": { "id": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "variant_title": {}, "shopify_product_id": { "type": [ "string", "null" ] }, "shopify_variant_id": {}, "product_deleted": { "type": [ "boolean", "null" ] }, "variant_deleted": { "type": [ "boolean", "null" ] }, "deleted_on_shopify": { "type": [ "boolean", "null" ] } } } }, "deleted_count": { "type": [ "integer", "null" ] }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "example": { "data": [ { "id": "7ea3c05d-6f29-42b6-b24f-43260caeaa32", "title": "Watercolour Course", "variant_title": null, "shopify_product_id": "gid://shopify/Product/9642107044135", "shopify_variant_id": null, "product_deleted": true, "variant_deleted": false, "deleted_on_shopify": true } ], "deleted_count": 1, "meta": { "total_count": 6, "page": 1, "per_page": 50, "total_pages": 1 } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/BadGateway" } }, "x-aliases": [ "products deleted on shopify", "stale digital products", "which products no longer exist", "clean up deleted products" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "description": "1-based page number." }, "example": 1, "description": "1-based page number." }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50, "description": "Rows per page, max 200." }, "example": 50, "description": "Rows per page, max 200." } ] } }, "/digital_products/lookup": { "get": { "operationId": "get_digital_products_lookup", "summary": "Lookup", "description": "The digital product a Shopify variant would be delivered from: its own variant-level product if one exists, else the product-level one. Takes shopify_variant_id and/or shopify_product_id (gid or numeric). 404 when neither has files configured.", "tags": [ "Digital Products" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "scope", "shopify_product_id", "shopify_variant_id", "title", "variant_title", "sku", "exists_on_shopify", "files", "folders", "delivery", "preorder", "update_email", "orders_count", "created_at", "updated_at" ], "properties": { "id": { "type": [ "string", "null" ] }, "scope": { "type": [ "string", "null" ] }, "shopify_product_id": { "type": [ "string", "null" ] }, "shopify_variant_id": {}, "title": { "type": [ "string", "null" ] }, "variant_title": {}, "sku": {}, "exists_on_shopify": {}, "files": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "type", "byte_size", "folder" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "byte_size": { "type": [ "integer", "null" ] }, "folder": {} } } }, "folders": { "type": "array" }, "delivery": { "type": "object", "required": [ "message", "attach_to_every_order" ], "properties": { "message": {}, "attach_to_every_order": { "type": [ "boolean", "null" ] } } }, "preorder": { "type": "object", "required": [ "enabled", "launch_at", "released", "email" ], "properties": { "enabled": { "type": [ "boolean", "null" ] }, "launch_at": {}, "released": { "type": [ "boolean", "null" ] }, "email": { "type": "object", "required": [ "subject", "heading", "description" ], "properties": { "subject": {}, "heading": {}, "description": {} } } } }, "update_email": { "type": "object", "required": [ "subject", "body" ], "properties": { "subject": {}, "body": {} } }, "orders_count": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } } }, "example": { "id": "7ea3c05d-6f29-42b6-b24f-43260caeaa32", "scope": "product", "shopify_product_id": "gid://shopify/Product/9642107044135", "shopify_variant_id": null, "title": "Watercolour Course", "variant_title": null, "sku": null, "exists_on_shopify": null, "files": [ { "id": "7ea42f2a-6dbe-459c-b8a4-27b0eb823e52", "name": "price-list.csv", "type": "file", "byte_size": 100634, "folder": null }, { "id": "96fbe30b-c819-4cb8-9666-814c0c8853f1", "name": "Beginner's Guide.pdf", "type": "file", "byte_size": 116711, "folder": null } ], "folders": [], "delivery": { "message": null, "attach_to_every_order": false }, "preorder": { "enabled": false, "launch_at": null, "released": true, "email": { "subject": null, "heading": null, "description": null } }, "update_email": { "subject": null, "body": null }, "orders_count": 46, "created_at": "2025-05-31T13:37:52Z", "updated_at": "2025-05-31T13:37:52Z" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "what will this variant deliver", "is this product digital", "digital product for a Shopify variant" ], "parameters": [ { "name": "shopify_variant_id", "in": "query", "required": false, "schema": { "type": "string" }, "example": "gid://shopify/ProductVariant/45000000001" }, { "name": "shopify_product_id", "in": "query", "required": false, "schema": { "type": "string" }, "example": "gid://shopify/Product/78000000001" } ] } }, "/download_logs": { "get": { "operationId": "get_download_logs", "summary": "List", "description": "Every download across the shop, newest first, paginated (page, per_page up to 200). order_id (Filemonk id, Shopify order gid or id, or #name) and asset_id narrow to one order or file; from / to are ISO 8601 bounds on when the download happened.", "tags": [ "Download Logs" ], "responses": { "200": { "description": "Success — one page of rows.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "downloaded_at", "order", "asset", "digital_product_id", "file", "licence_tag", "client", "cdn_provider" ], "properties": { "id": { "type": [ "string", "null" ] }, "downloaded_at": { "type": [ "string", "null" ] }, "order": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } } }, "asset": { "type": "object", "required": [ "id", "name", "type" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] } } }, "digital_product_id": { "type": [ "string", "null" ] }, "file": { "type": "object", "required": [ "filename", "content_type", "byte_size" ], "properties": { "filename": { "type": [ "string", "null" ] }, "content_type": { "type": [ "string", "null" ] }, "byte_size": { "type": [ "integer", "null" ] } } }, "licence_tag": {}, "client": { "type": "object", "required": [ "ip_address", "country_code", "user_agent", "referrer" ], "properties": { "ip_address": { "type": [ "string", "null" ] }, "country_code": {}, "user_agent": { "type": [ "string", "null" ] }, "referrer": { "type": [ "string", "null" ] } } }, "cdn_provider": { "type": [ "string", "null" ] } } } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "example": { "data": [ { "id": "a401ec79-a062-4ab0-96e6-a588931583cc", "downloaded_at": "2026-10-12T19:50:17Z", "order": { "id": "71e9bb0e-1e22-4513-af29-60aceeeb3755", "name": "#1058" }, "asset": { "id": "96fbe30b-c819-4cb8-9666-814c0c8853f1", "name": "Beginner's Guide.pdf", "type": "file" }, "digital_product_id": "7ea3c05d-6f29-42b6-b24f-43260caeaa32", "file": { "filename": "Watercolour Basics Workbook.pdf", "content_type": "application/pdf", "byte_size": 116711 }, "licence_tag": null, "client": { "ip_address": "203.0.113.7", "country_code": null, "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 16_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/16.0 Mobile/15E148 Safari/604.1", "referrer": "https://app.filemonk.io/orders/71e9bb0e-1e22-4513-af29-60aceeeb3755" }, "cdn_provider": "cloudflare" } ], "meta": { "total_count": 18, "page": 1, "per_page": 50, "total_pages": 1 } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "download history", "who downloaded what today", "downloads of a file", "download logs" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "description": "1-based page number." }, "example": 1, "description": "1-based page number." }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50, "description": "Rows per page, max 200." }, "example": 50, "description": "Rows per page, max 200." }, { "name": "order_id", "in": "query", "required": false, "schema": { "type": "string" }, "example": "c3d4e5f6-7a8b-4c9d-8e0f-1a2b3c4d5e6f" }, { "name": "asset_id", "in": "query", "required": false, "schema": { "type": "string" }, "example": "9f1c2a7e-3b4d-4e5f-8a6b-7c8d9e0f1a2b" }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string" }, "example": "string" }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string" }, "example": "string" } ] } }, "/emails": { "get": { "operationId": "get_emails", "summary": "List", "description": "Every email Filemonk sent, newest first, paginated (page, per_page up to 200), with the furthest point each reached. order_id (Filemonk id, Shopify order gid or id, or #name) narrows to one order; kind is delivery, product_update, product_update_test or preorder_release; delivery_status is queued, sent, delivered, opened, clicked, rejected, bounced or complained; from / to are ISO 8601 bounds on when it was sent.", "tags": [ "Emails" ], "responses": { "200": { "description": "Success — one page of rows.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "kind", "to", "from", "order", "status", "timeline", "created_at" ], "properties": { "id": { "type": [ "string", "null" ] }, "kind": { "type": [ "string", "null" ] }, "to": { "type": [ "string", "null" ] }, "from": { "type": [ "string", "null" ] }, "order": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } } }, "status": { "type": [ "string", "null" ] }, "timeline": { "type": "object", "required": [ "sent_at", "delivered_at", "opened_at", "clicked_at", "bounced_at", "rejected_at", "complained_at" ], "properties": { "sent_at": { "type": [ "string", "null" ] }, "delivered_at": { "type": [ "string", "null" ] }, "opened_at": {}, "clicked_at": {}, "bounced_at": {}, "rejected_at": {}, "complained_at": {} } }, "created_at": { "type": [ "string", "null" ] } } } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "example": { "data": [ { "id": "77c81a2e-4221-4a03-b784-221de4b1bf5c", "kind": "delivery", "to": "shopper@example.com", "from": "alerts@example-store.filemonk.io", "order": { "id": "3e84eb8d-e1d9-4e92-a4b2-a419c7f1122f", "name": "#1077" }, "status": "delivered", "timeline": { "sent_at": "2026-10-30T23:02:25Z", "delivered_at": "2026-10-30T23:02:24Z", "opened_at": null, "clicked_at": null, "bounced_at": null, "rejected_at": null, "complained_at": null }, "created_at": "2026-10-30T23:02:24Z" } ], "meta": { "total_count": 37, "page": 1, "per_page": 50, "total_pages": 1 } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "bounced emails", "emails sent today", "did the download emails go out", "email delivery report" ], "parameters": [ { "name": "kind", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "delivery", "product_update", "product_update_test", "preorder_release" ] }, "example": "delivery" }, { "name": "delivery_status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "complained", "bounced", "rejected", "clicked", "opened", "delivered", "sent", "queued" ] }, "example": "complained" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "description": "1-based page number." }, "example": 1, "description": "1-based page number." }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50, "description": "Rows per page, max 200." }, "example": 50, "description": "Rows per page, max 200." }, { "name": "order_id", "in": "query", "required": false, "schema": { "type": "string" }, "example": "c3d4e5f6-7a8b-4c9d-8e0f-1a2b3c4d5e6f" }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string" }, "example": "string" }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string" }, "example": "string" } ] } }, "/exports": { "post": { "operationId": "post_exports", "summary": "Create", "description": "Email the shop a CSV export (type: orders, assets, digital_products or licences; licences take an optional tag), as each page's Export CSV does. The file goes to the shop's email address when it is ready; nothing is returned inline.\n\n**Note:** Queued (202, queued: true). For the data itself use the list endpoints with pagination.", "tags": [ "Exports" ], "responses": { "200": { "description": "Success — the write completed; the body is the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "202": { "description": "Accepted — the change was saved and the rest of the work (emails, Shopify sync, a bulk job) continues in the background. The body is the resource snapshot plus `queued: true`; there is nothing to poll.", "content": { "application/json": { "schema": { "type": "object", "required": [ "queued", "type", "tag", "to" ], "properties": { "queued": { "type": [ "boolean", "null" ] }, "type": { "type": [ "string", "null" ] }, "tag": { "type": [ "string", "null" ] }, "to": { "type": [ "string", "null" ] } } }, "example": { "queued": true, "type": "licences", "tag": "ebook-2026", "to": "owner@example.com" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "export orders to csv", "download all my files as a spreadsheet", "export licence keys", "csv of digital products", "email me an export" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "minLength": 1 }, "tag": {} }, "required": [ "type" ] }, "example": { "type": "licences", "tag": "ebook-2026" } } } } } }, "/imports": { "post": { "operationId": "post_imports", "summary": "Create", "description": "Start a bulk import of historic orders from CSV text (csv), as the bulk import page does. Columns are the page's template (sku, filename, external_url, data_type, link_to_product, custom_product) in that order, or column_mapping {sku: 0, filename: 1, ...} gives the 0-based index of each. data_type is sku or variant_id (blank means sku); link_to_product and custom_product are yes, no or blank. Rows run in the background; follow progress with GET /imports/:id.\n\n**Note:** Only one import runs per shop at a time (409 while one is in progress). Rows that reference unknown files, SKUs or urls are reported as 422 with code validation_warnings and nothing is imported; send proceed_with_warnings: true to import the valid rows and skip the rest.", "tags": [ "Imports" ], "responses": { "200": { "description": "Success — the write completed; the body is the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "202": { "description": "Accepted — the change was saved and the rest of the work (emails, Shopify sync, a bulk job) continues in the background. The body is the resource snapshot plus `queued: true`; there is nothing to poll.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "name", "status", "rows", "completed_at", "created_at", "queued" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "rows": { "type": "object", "required": [ "total", "completed", "failed" ], "properties": { "total": { "type": [ "integer", "null" ] }, "completed": { "type": [ "integer", "null" ] }, "failed": { "type": [ "integer", "null" ] } } }, "completed_at": {}, "created_at": { "type": [ "string", "null" ] }, "queued": { "type": [ "boolean", "null" ] } } }, "example": { "id": "de0d7253-b5ed-42cc-921b-e1d90bf2cd76", "name": "orders-import.csv", "status": "processing", "rows": { "total": 1, "completed": 0, "failed": 0 }, "completed_at": null, "created_at": "2026-10-30T23:03:04Z", "queued": true } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "import orders from csv", "bulk import", "upload a csv of orders", "start an import" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "csv": { "type": "string", "minLength": 1 }, "filename": {}, "column_mapping": {}, "proceed_with_warnings": {} }, "required": [ "csv" ] }, "example": { "csv": "sku,filename,external_url,data_type,link_to_product,custom_product\nWATERCOLOUR-1,guide.pdf,,sku,yes,no\n", "proceed_with_warnings": false } } } } }, "get": { "operationId": "get_imports", "summary": "List", "description": "CSV order imports newest first, paginated, each with its row counts (total, completed, failed) and status: processing until every row is handled, then completed, or failed when no row went through.", "tags": [ "Imports" ], "responses": { "200": { "description": "Success — one page of rows.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "status", "rows", "completed_at", "created_at" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "rows": { "type": "object", "required": [ "total", "completed", "failed" ], "properties": { "total": { "type": [ "integer", "null" ] }, "completed": { "type": [ "integer", "null" ] }, "failed": { "type": [ "integer", "null" ] } } }, "completed_at": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] } } } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "example": { "data": [ { "id": "de0d7253-b5ed-42cc-921b-e1d90bf2cd76", "name": "orders-import.csv", "status": "completed", "rows": { "total": 1, "completed": 1, "failed": 0 }, "completed_at": "2026-10-30T23:03:25Z", "created_at": "2026-10-30T23:03:04Z" } ], "meta": { "total_count": 8, "page": 1, "per_page": 50, "total_pages": 1 } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "list imports", "did my import finish", "import history", "how many rows failed" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "description": "1-based page number." }, "example": 1, "description": "1-based page number." }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50, "description": "Rows per page, max 200." }, "example": 50, "description": "Rows per page, max 200." } ] } }, "/imports/{id}": { "get": { "operationId": "get_imports_id", "summary": "Read", "description": "One CSV import: status, row counts and up to 50 failed rows with the reason each was rejected.", "tags": [ "Imports" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "name", "status", "rows", "completed_at", "created_at", "failed_rows" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "rows": { "type": "object", "required": [ "total", "completed", "failed" ], "properties": { "total": { "type": [ "integer", "null" ] }, "completed": { "type": [ "integer", "null" ] }, "failed": { "type": [ "integer", "null" ] } } }, "completed_at": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] }, "failed_rows": { "type": "array" } } }, "example": { "id": "de0d7253-b5ed-42cc-921b-e1d90bf2cd76", "name": "orders-import.csv", "status": "completed", "rows": { "total": 1, "completed": 1, "failed": 0 }, "completed_at": "2026-10-30T23:03:25Z", "created_at": "2026-10-30T23:03:04Z", "failed_rows": [] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "show import", "why did these rows fail", "import errors" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/imports/preview": { "post": { "operationId": "post_imports_preview", "summary": "Preview", "description": "Check CSV text (csv) before importing it, as the bulk import page's preview and column mapping steps do: the headers, the first rows per column, a suggested column_mapping for POST /imports, and the same row checks the import runs (unknown files, SKUs or urls), without importing anything.\n\n**Note:** Read-only. Send the column_mapping you intend to import with to check those columns; without it the template order (sku, filename, external_url, data_type, link_to_product, custom_product) is checked.", "tags": [ "Imports" ], "responses": { "200": { "description": "Success — the write completed; the body is the updated resource.", "content": { "application/json": { "schema": { "type": "object", "required": [ "headers", "sample_columns", "suggested_column_mapping", "validation" ], "properties": { "headers": { "type": "array", "items": { "type": [ "string", "null" ] } }, "sample_columns": { "type": "object", "required": [ "sku", "filename", "external_url", "data_type", "link_to_product", "custom_product" ], "properties": { "sku": { "type": "array", "items": { "type": [ "string", "null" ] } }, "filename": { "type": "array", "items": { "type": [ "string", "null" ] } }, "external_url": { "type": "array", "items": { "type": [ "string", "null" ] } }, "data_type": { "type": "array", "items": { "type": [ "string", "null" ] } }, "link_to_product": { "type": "array", "items": { "type": [ "string", "null" ] } }, "custom_product": { "type": "array", "items": { "type": [ "string", "null" ] } } } }, "suggested_column_mapping": { "type": "object", "required": [ "sku", "filename", "external_url", "data_type", "link_to_product", "custom_product" ], "properties": { "sku": { "type": [ "integer", "null" ] }, "filename": { "type": [ "integer", "null" ] }, "external_url": { "type": [ "integer", "null" ] }, "data_type": { "type": [ "integer", "null" ] }, "link_to_product": { "type": [ "integer", "null" ] }, "custom_product": { "type": [ "integer", "null" ] } } }, "validation": { "type": "object", "required": [ "total_rows", "valid_rows", "has_warnings", "filename_errors", "variant_errors", "url_errors", "reference_summary" ], "properties": { "total_rows": { "type": [ "integer", "null" ] }, "valid_rows": { "type": [ "integer", "null" ] }, "has_warnings": { "type": [ "boolean", "null" ] }, "filename_errors": { "type": "array" }, "variant_errors": { "type": "array" }, "url_errors": { "type": "array" }, "reference_summary": { "type": "object", "required": [], "properties": {} } } } } }, "example": { "headers": [ "sku", "filename", "external_url", "data_type", "link_to_product", "custom_product" ], "sample_columns": { "sku": [ "WATERCOLOUR-1" ], "filename": [ "guide.pdf" ], "external_url": [ "" ], "data_type": [ "sku" ], "link_to_product": [ "yes" ], "custom_product": [ "no" ] }, "suggested_column_mapping": { "sku": 0, "filename": 1, "external_url": 2, "data_type": 3, "link_to_product": 4, "custom_product": 5 }, "validation": { "total_rows": 1, "valid_rows": 1, "has_warnings": false, "filename_errors": [], "variant_errors": [], "url_errors": [], "reference_summary": {} } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "preview csv import", "check my csv", "validate import file", "map csv columns" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "csv": { "type": "string", "minLength": 1 }, "filename": {}, "column_mapping": {} }, "required": [ "csv" ] }, "example": { "csv": "sku,filename,external_url,data_type,link_to_product,custom_product\nWATERCOLOUR-1,guide.pdf,,sku,yes,no\n" } } } } } }, "/licence_tags": { "get": { "operationId": "get_licence_tags", "summary": "List", "description": "The licence tags the shop's keys and licence-key files use, as the Licence tags page lists them: key counts by status and the digital products each tag supplies. No Tag (uploaded keys without a tag) and Autogenerated are built-in groups, marked virtual. search matches the name.", "tags": [ "Licence Tags" ], "responses": { "200": { "description": "Success — one page of rows.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "totals" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "name", "virtual", "licences", "digital_products" ], "properties": { "name": { "type": [ "string", "null" ] }, "virtual": { "type": [ "boolean", "null" ] }, "licences": { "type": "object", "required": [ "total", "pending", "assigned", "used" ], "properties": { "total": { "type": [ "integer", "null" ] }, "pending": { "type": [ "integer", "null" ] }, "assigned": { "type": [ "integer", "null" ] }, "used": { "type": [ "integer", "null" ] } } }, "digital_products": { "type": "array" } } } }, "meta": { "$ref": "#/components/schemas/PageMeta" }, "totals": { "type": "object", "required": [ "total", "pending", "assigned", "used" ], "properties": { "total": { "type": [ "integer", "null" ] }, "pending": { "type": [ "integer", "null" ] }, "assigned": { "type": [ "integer", "null" ] }, "used": { "type": [ "integer", "null" ] } } } } }, "example": { "data": [ { "name": "ebook-2026", "virtual": false, "licences": { "total": 2, "pending": 2, "assigned": 0, "used": 0 }, "digital_products": [] } ], "meta": { "total_count": 6, "page": 1, "per_page": 50, "total_pages": 1 }, "totals": { "total": 8, "pending": 6, "assigned": 1, "used": 1 } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "list licence tags", "which tag is running out of keys", "keys left per tag", "licence key pools" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "description": "1-based page number." }, "example": 1, "description": "1-based page number." }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50, "description": "Rows per page, max 200." }, "example": 50, "description": "Rows per page, max 200." }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "example": "string" } ] } }, "/licence_tags/{name}": { "delete": { "operationId": "delete_licence_tags_name", "summary": "Delete", "description": "Delete a licence tag with everything in it, as the Licence keys page's Delete tag does: its pending keys and the licence-key files tagged with it. Destructive: send it first without `confirm`. Nothing changes and the 409 `confirmation_required` says what would. Tell the merchant, ask, and resend with `confirm: true` only after they agree.\n\n**Note:** Refused (422) while any key in the tag is assigned or used. No Tag and Autogenerated cannot be deleted. Without confirm: true nothing is deleted: 409 confirmation_required says how many keys would go.", "tags": [ "Licence Tags" ], "responses": { "200": { "description": "Success — the write completed; the body is the updated resource.", "content": { "application/json": { "schema": { "type": "object", "required": [ "deleted", "name" ], "properties": { "deleted": { "type": [ "boolean", "null" ] }, "name": { "type": [ "string", "null" ] } } }, "example": { "deleted": true, "name": "ebook-2026" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "delete tag", "remove licence tag and its keys", "delete key pool" ], "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "confirm", "in": "query", "required": false, "schema": { "type": "string" }, "example": "string" } ] }, "get": { "operationId": "get_licence_tags_name", "summary": "Read", "description": "One licence tag by name (or No Tag / Autogenerated): key counts by status and the digital products whose licence-key files draw from it.", "tags": [ "Licence Tags" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "virtual", "licences", "digital_products" ], "properties": { "name": { "type": [ "string", "null" ] }, "virtual": { "type": [ "boolean", "null" ] }, "licences": { "type": "object", "required": [ "total", "pending", "assigned", "used" ], "properties": { "total": { "type": [ "integer", "null" ] }, "pending": { "type": [ "integer", "null" ] }, "assigned": { "type": [ "integer", "null" ] }, "used": { "type": [ "integer", "null" ] } } }, "digital_products": { "type": "array" } } }, "example": { "name": "ebook-2026", "virtual": false, "licences": { "total": 2, "pending": 2, "assigned": 0, "used": 0 }, "digital_products": [] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "show licence tag", "how many keys are left for this tag", "which products use this tag" ], "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "patch": { "operationId": "patch_licence_tags_name", "summary": "Update", "description": "Rename a licence tag (new_name), as the Licence keys page's Rename tag does: every key and licence-key file of this shop moves to the new name.\n\n**Note:** No Tag and Autogenerated cannot be renamed. 422 when a tag with the new name exists; use POST /licences/move to merge.", "tags": [ "Licence Tags" ], "responses": { "200": { "description": "Success — the write completed; the body is the updated resource.", "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "virtual", "licences", "digital_products" ], "properties": { "name": { "type": [ "string", "null" ] }, "virtual": { "type": [ "boolean", "null" ] }, "licences": { "type": "object", "required": [ "total", "pending", "assigned", "used" ], "properties": { "total": { "type": [ "integer", "null" ] }, "pending": { "type": [ "integer", "null" ] }, "assigned": { "type": [ "integer", "null" ] }, "used": { "type": [ "integer", "null" ] } } }, "digital_products": { "type": "array" } } }, "example": { "name": "ebook-2027", "virtual": false, "licences": { "total": 2, "pending": 2, "assigned": 0, "used": 0 }, "digital_products": [] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "rename tag", "rename licence tag", "change tag name" ], "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "new_name": { "type": "string", "minLength": 1 } }, "required": [ "new_name" ] }, "example": { "new_name": "ebook-2027" } } } } } }, "/licences": { "post": { "operationId": "post_licences", "summary": "Create", "description": "Add licence keys to the pool (keys, one string each), under a tag when given, as the Licence keys page's Add keys does. Orders still waiting for a key from that pool are served right after.\n\n**Note:** Keys already in the shop (and repeats within the request) are skipped and counted in skipped_duplicates; send allow_duplicates: true to add them anyway. Keys are deleted on the Licence keys page (or DELETE /licences/:id over REST).", "tags": [ "Licences" ], "responses": { "200": { "description": "Success — the resource already existed; here it is.", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "201": { "description": "Created — the new resource.", "content": { "application/json": { "schema": { "type": "object", "required": [ "created", "skipped_duplicates", "tag" ], "properties": { "created": { "type": [ "integer", "null" ] }, "skipped_duplicates": { "type": [ "integer", "null" ] }, "tag": { "type": "object", "required": [ "name", "virtual", "licences", "digital_products" ], "properties": { "name": { "type": [ "string", "null" ] }, "virtual": { "type": [ "boolean", "null" ] }, "licences": { "type": "object", "required": [ "total", "pending", "assigned", "used" ], "properties": { "total": { "type": [ "integer", "null" ] }, "pending": { "type": [ "integer", "null" ] }, "assigned": { "type": [ "integer", "null" ] }, "used": { "type": [ "integer", "null" ] } } }, "digital_products": { "type": "array" } } } } }, "example": { "created": 2, "skipped_duplicates": 0, "tag": { "name": "ebook-2026", "virtual": false, "licences": { "total": 2, "pending": 2, "assigned": 0, "used": 0 }, "digital_products": [] } }, "examples": { "add_to_pool": { "summary": "Add keys to a pool", "value": { "created": 2, "skipped_duplicates": 0, "tag": { "name": "ebook-2026", "virtual": false, "licences": { "total": 2, "pending": 2, "assigned": 0, "used": 0 }, "digital_products": [] } } }, "allow_duplicates": { "summary": "Add a key that is already in the shop", "value": { "created": 1, "skipped_duplicates": 0, "tag": { "name": "ebook-2026", "virtual": false, "licences": { "total": 3, "pending": 3, "assigned": 0, "used": 0 }, "digital_products": [] } } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "add licence keys", "upload keys", "paste license keys", "add keys to tag", "top up the key pool" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "keys": { "type": "array", "items": { "type": "string" } }, "allow_duplicates": { "type": "boolean" }, "tag": {} }, "required": [ "keys" ] }, "example": { "keys": [ "ABCD-EFGH-IJKL-0001", "ABCD-EFGH-IJKL-0002" ], "tag": "ebook-2026" }, "examples": { "add_to_pool": { "summary": "Add keys to a pool", "value": { "keys": [ "ABCD-EFGH-IJKL-0001", "ABCD-EFGH-IJKL-0002" ], "tag": "ebook-2026" } }, "allow_duplicates": { "summary": "Add a key that is already in the shop", "description": "Without allow_duplicates the key would be skipped and counted in skipped_duplicates.", "value": { "keys": [ "ABCD-EFGH-IJKL-0001" ], "tag": "ebook-2026", "allow_duplicates": true } } } } } } }, "get": { "operationId": "get_licences", "summary": "List", "description": "List licence keys newest first, paginated (page, per_page up to 200). key_status is pending, assigned or used; source is uploaded or auto_generated; tag narrows to one licence tag (No Tag and Autogenerated are the two built-in groups); search matches part of the key.", "tags": [ "Licences" ], "responses": { "200": { "description": "Success — one page of rows.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "totals" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "key", "source", "status", "tags", "assigned_at", "order", "file", "created_at" ], "properties": { "id": { "type": [ "string", "null" ] }, "key": { "type": [ "string", "null" ] }, "source": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": [ "string", "null" ] } }, "assigned_at": {}, "order": {}, "file": {}, "created_at": { "type": [ "string", "null" ] } } } }, "meta": { "$ref": "#/components/schemas/PageMeta" }, "totals": { "type": "object", "required": [ "total", "pending", "assigned", "used" ], "properties": { "total": { "type": [ "integer", "null" ] }, "pending": { "type": [ "integer", "null" ] }, "assigned": { "type": [ "integer", "null" ] }, "used": { "type": [ "integer", "null" ] } } } } }, "example": { "data": [ { "id": "bcc87d33-c87e-4f39-9cd2-e43250ebc1ed", "key": "ABCD-EFGH-0005", "source": "uploaded", "status": "pending", "tags": [ "ebook-2026" ], "assigned_at": null, "order": null, "file": null, "created_at": "2026-10-30T16:48:56Z" } ], "meta": { "total_count": 8, "page": 1, "per_page": 50, "total_pages": 1 }, "totals": { "total": 8, "pending": 6, "assigned": 1, "used": 1 } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "list licence keys", "unused licence keys", "how many keys are left", "how many licence keys do I have", "licence keys left", "keys for a tag", "find a key" ], "parameters": [ { "name": "key_status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "assigned", "used" ] }, "example": "pending" }, { "name": "source", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "uploaded", "auto_generated" ] }, "example": "uploaded" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "description": "1-based page number." }, "example": 1, "description": "1-based page number." }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50, "description": "Rows per page, max 200." }, "example": 50, "description": "Rows per page, max 200." }, { "name": "tag", "in": "query", "required": false, "schema": { "type": "string" }, "example": "ebook-2026" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "example": "string" } ] } }, "/licences/{id}": { "delete": { "operationId": "delete_licences_id", "summary": "Delete", "description": "Delete one licence key, as the Licence keys page's Delete does. A key on an order is removed from it and the order is marked so no replacement is assigned automatically. Destructive: send it first without `confirm`. Nothing changes and the 409 `confirmation_required` says what would. Tell the merchant, ask, and resend with `confirm: true` only after they agree. For more than one, use POST /licences/bulk_delete, which previews the counts; don't call this in a loop.\n\n**Note:** Without confirm: true nothing is deleted: 409 confirmation_required names the key and its order.", "tags": [ "Licences" ], "responses": { "200": { "description": "Success — the write completed; the body is the updated resource.", "content": { "application/json": { "schema": { "type": "object", "required": [ "deleted", "id" ], "properties": { "deleted": { "type": [ "boolean", "null" ] }, "id": { "type": [ "string", "null" ] } } }, "example": { "deleted": true, "id": "bcc87d33-c87e-4f39-9cd2-e43250ebc1ed" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "delete licence key", "remove a key", "delete this license key" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "confirm", "in": "query", "required": false, "schema": { "type": "string" }, "example": "string" } ] }, "get": { "operationId": "get_licences_id", "summary": "Read", "description": "One licence key by Filemonk id: the key, its status, tags, and the order and licence-key file it was assigned to.", "tags": [ "Licences" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "key", "source", "status", "tags", "assigned_at", "order", "file", "created_at" ], "properties": { "id": { "type": [ "string", "null" ] }, "key": { "type": [ "string", "null" ] }, "source": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": [ "string", "null" ] } }, "assigned_at": {}, "order": {}, "file": {}, "created_at": { "type": [ "string", "null" ] } } }, "example": { "id": "bcc87d33-c87e-4f39-9cd2-e43250ebc1ed", "key": "ABCD-EFGH-0005", "source": "uploaded", "status": "pending", "tags": [ "ebook-2026" ], "assigned_at": null, "order": null, "file": null, "created_at": "2026-10-30T16:48:56Z" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "show licence key", "which order got this key" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "patch": { "operationId": "patch_licences_id", "summary": "Update", "description": "Edit one licence key, as the Licence keys page's edit does: key (the text), key_status (pending, assigned, used) or tags (the whole list). Deep partial.\n\n**Note:** Changing key_status does not touch the order the key is on; use the order's licence endpoints for that.", "tags": [ "Licences" ], "responses": { "200": { "description": "Success — the write completed; the body is the updated resource.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "key", "source", "status", "tags", "assigned_at", "order", "file", "created_at" ], "properties": { "id": { "type": [ "string", "null" ] }, "key": { "type": [ "string", "null" ] }, "source": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": [ "string", "null" ] } }, "assigned_at": {}, "order": {}, "file": {}, "created_at": { "type": [ "string", "null" ] } } }, "example": { "id": "bcc87d33-c87e-4f39-9cd2-e43250ebc1ed", "key": "ABCD-EFGH-0005", "source": "uploaded", "status": "used", "tags": [ "ebook-2026" ], "assigned_at": null, "order": null, "file": null, "created_at": "2026-10-30T16:48:56Z" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "edit licence key", "fix a typo in a key", "mark key as used", "retag one key", "change key status" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": {}, "key_status": {}, "tags": {} } }, "example": { "key_status": "used" } } } } } }, "/licences/bulk_delete": { "post": { "operationId": "post_licences_bulk_delete", "summary": "Bulk Delete", "description": "Delete licence keys in bulk, as the Licence keys page does, one of three ways: ids (a list), {unused: true, tag} (every unassigned key of a tag; include_assigned: true takes the assigned ones too) or {duplicates: true, tag} (keep the oldest pending row per key text, drop the rest). Destructive: send it first without `confirm`. Nothing changes and the 409 `confirmation_required` says what would. Tell the merchant, ask, and resend with `confirm: true` only after they agree.\n\n**Note:** Over 5,000 unused keys the delete runs in the background (202, queued: true); otherwise 200 once the keys are gone. Keys on orders leave the order marked so no replacement is assigned. Without confirm: true nothing is deleted: 409 confirmation_required says how many keys (and how many on orders) would go.", "tags": [ "Licences" ], "responses": { "200": { "description": "Success — the write completed; the body is the updated resource.", "content": { "application/json": { "schema": { "type": "object", "required": [ "deleted", "missing" ], "properties": { "deleted": { "type": "array", "items": { "type": [ "string", "null" ] } }, "missing": { "type": "array" } } }, "example": { "deleted": [ "bcc87d33-c87e-4f39-9cd2-e43250ebc1ed" ], "missing": [] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "202": { "description": "Accepted — the change was saved and the rest of the work (emails, Shopify sync, a bulk job) continues in the background. The body is the resource snapshot plus `queued: true`; there is nothing to poll.", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "delete unused keys", "delete duplicate keys", "bulk delete licence keys", "clear a key pool", "remove these keys" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": {}, "unused": {}, "duplicates": {}, "tag": {}, "include_assigned": {}, "confirm": {} } }, "example": { "ids": [ "bcc87d33-c87e-4f39-9cd2-e43250ebc1ed" ], "confirm": true } } } } } }, "/licences/check": { "post": { "operationId": "post_licences_check", "summary": "Check", "description": "Before adding keys: which of these keys already exist under any of these tags. Answers {duplicates: [key, ...]}; nothing is written.", "tags": [ "Licences" ], "responses": { "200": { "description": "Success — the write completed; the body is the updated resource.", "content": { "application/json": { "schema": { "type": "object", "required": [ "duplicates" ], "properties": { "duplicates": { "type": "array", "items": { "type": [ "string", "null" ] } } } }, "example": { "duplicates": [ "ABCD-EFGH-0005" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "check for duplicate keys", "do these keys already exist", "validate keys before import" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "keys": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "keys", "tags" ] }, "example": { "keys": [ "ABCD-EFGH-IJKL-0001", "ABCD-EFGH-0005" ], "tags": [ "ebook-2026" ] } } } } } }, "/licences/import": { "post": { "operationId": "post_licences_import", "summary": "Import", "description": "Import licence keys from CSV text (csv), as the Licence keys page's Import does. Columns are matched by header: key (Licence Key, License Key or Key), tag (Tag, Tags or Tags linked) and status. Only the key column is required; without a tag column the keys are imported untagged. column_mapping {key, tag, status} gives 0-based column indexes instead. Keys whose status column says assigned or used are skipped.\n\n**Note:** The whole file is rejected (422, one error per bad line) when any row has an empty key, or an empty tag in a tag column; nothing is written then. Up to 5 MB of text.", "tags": [ "Licences" ], "responses": { "200": { "description": "Success — the resource already existed; here it is.", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "201": { "description": "Created — the new resource.", "content": { "application/json": { "schema": { "type": "object", "required": [ "created", "skipped", "sold_skipped", "message" ], "properties": { "created": { "type": [ "integer", "null" ] }, "skipped": { "type": [ "integer", "null" ] }, "sold_skipped": { "type": [ "integer", "null" ] }, "message": { "type": [ "string", "null" ] } } }, "example": { "created": 2, "skipped": 0, "sold_skipped": 0, "message": "2 licence keys imported successfully." } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "import keys from csv", "upload a csv of licence keys", "bulk import license keys" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "csv": { "type": "string", "minLength": 1 }, "column_mapping": {} }, "required": [ "csv" ] }, "example": { "csv": "key,tag\nABCD-EFGH-IJKL-0003,ebook-2026\nABCD-EFGH-IJKL-0004,ebook-2026\n" } } } } } }, "/licences/lookup": { "get": { "operationId": "get_licences_lookup", "summary": "Lookup", "description": "Find a licence key by its exact value (key=XXXX-YYYY): is it one of ours, has it been assigned, and to which order. 404 when the shop has no such key.", "tags": [ "Licences" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "key", "source", "status", "tags", "assigned_at", "order", "file", "created_at" ], "properties": { "id": { "type": [ "string", "null" ] }, "key": { "type": [ "string", "null" ] }, "source": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": [ "string", "null" ] } }, "assigned_at": {}, "order": {}, "file": {}, "created_at": { "type": [ "string", "null" ] } } }, "example": { "id": "bcc87d33-c87e-4f39-9cd2-e43250ebc1ed", "key": "ABCD-EFGH-0005", "source": "uploaded", "status": "pending", "tags": [ "ebook-2026" ], "assigned_at": null, "order": null, "file": null, "created_at": "2026-10-30T16:48:56Z" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "is this licence key valid", "who was this key sent to", "look up a key a customer sent" ], "parameters": [ { "name": "key", "in": "query", "required": true, "schema": { "type": "string" }, "example": "ABCD-EFGH-IJKL-MNOP" } ] } }, "/licences/move": { "post": { "operationId": "post_licences_move", "summary": "Move", "description": "Move licence keys into a tag (to_tag), replacing the tags they had, as the Licence keys page's Move does: either ids (a list) or tag (every key of that tag, No Tag included). to_tag must exist already, or be No Tag to clear tags.", "tags": [ "Licences" ], "responses": { "200": { "description": "Success — the write completed; the body is the updated resource.", "content": { "application/json": { "schema": { "type": "object", "required": [ "moved", "to_tag" ], "properties": { "moved": { "type": [ "integer", "null" ] }, "to_tag": { "type": "object", "required": [ "name", "virtual", "licences", "digital_products" ], "properties": { "name": { "type": [ "string", "null" ] }, "virtual": { "type": [ "boolean", "null" ] }, "licences": { "type": "object", "required": [ "total", "pending", "assigned", "used" ], "properties": { "total": { "type": [ "integer", "null" ] }, "pending": { "type": [ "integer", "null" ] }, "assigned": { "type": [ "integer", "null" ] }, "used": { "type": [ "integer", "null" ] } } }, "digital_products": { "type": "array" } } } } }, "example": { "moved": 1, "to_tag": { "name": "ebook-2027", "virtual": false, "licences": { "total": 2, "pending": 2, "assigned": 0, "used": 0 }, "digital_products": [] } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "move keys to tag", "retag licence keys", "merge tags", "untag keys" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "to_tag": { "type": "string", "minLength": 1 }, "ids": {}, "tag": {} }, "required": [ "to_tag" ] }, "example": { "ids": [ "bcc87d33-c87e-4f39-9cd2-e43250ebc1ed" ], "to_tag": "ebook-2027" } } } } } }, "/orders": { "post": { "operationId": "post_orders", "summary": "Create", "description": "Import one order from Shopify by its order id or gid, as the Orders page's Find order does: Filemonk fetches it, links the digital products it contains and, unless send_email is false, sends the download email. Returns the order in full. Send it first without `confirm`. Nothing changes and the 409 `confirmation_required` says what would. Tell the merchant, ask, and resend with `confirm: true` only after they agree.\n\n**Note:** Previews first: without confirm: true nothing is imported and 409 confirmation_required says what would be linked and who would be emailed. Calls Shopify synchronously. Orders without any linked digital product are rejected (422). An order already in Filemonk is refreshed, not duplicated, and answers 200; a deleted one is restored. 404 when Shopify has no such order; 502 when Shopify did not answer.", "tags": [ "Orders" ], "responses": { "200": { "description": "Success — the resource already existed; here it is.", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "201": { "description": "Created — the new resource.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "shopify_order_id", "name", "confirmation_number", "ordered_at", "customer", "total", "status", "access", "delivery", "line_items", "eu_withdrawal", "shopify_tags", "imported_at", "deleted_at", "created_at", "updated_at" ], "properties": { "id": { "type": [ "string", "null" ] }, "shopify_order_id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "confirmation_number": { "type": [ "string", "null" ] }, "ordered_at": { "type": [ "string", "null" ] }, "customer": { "type": "object", "required": [ "id", "shopify_customer_id", "email", "phone", "first_name", "last_name", "country_code", "locale", "unsubscribed" ], "properties": { "id": { "type": [ "string", "null" ] }, "shopify_customer_id": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "phone": {}, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "country_code": {}, "locale": {}, "unsubscribed": { "type": [ "boolean", "null" ] } } }, "total": { "type": "object", "required": [ "amount", "currency" ], "properties": { "amount": { "type": [ "string", "null" ] }, "currency": { "type": [ "string", "null" ] } } }, "status": { "type": "object", "required": [ "financial", "fulfillment", "cancelled_at", "paid_at", "flagged_as_fraud", "fraud_check_completed", "marked_fulfilled_at", "delivery_conditions_met" ], "properties": { "financial": { "type": [ "string", "null" ] }, "fulfillment": { "type": [ "string", "null" ] }, "cancelled_at": {}, "paid_at": { "type": [ "string", "null" ] }, "flagged_as_fraud": { "type": [ "boolean", "null" ] }, "fraud_check_completed": { "type": [ "boolean", "null" ] }, "marked_fulfilled_at": {}, "delivery_conditions_met": { "type": [ "boolean", "null" ] } } }, "access": { "type": "object", "required": [ "state", "revoked_at", "available_until", "download_reset_at", "downloads_count" ], "properties": { "state": { "type": [ "string", "null" ] }, "revoked_at": {}, "available_until": {}, "download_reset_at": { "type": [ "string", "null" ] }, "downloads_count": { "type": [ "integer", "null" ] } } }, "delivery": { "type": "object", "required": [ "email_sent_at", "delivery_failed_at", "download_page_url", "source" ], "properties": { "email_sent_at": { "type": [ "string", "null" ] }, "delivery_failed_at": {}, "download_page_url": { "type": [ "string", "null" ] }, "source": { "type": [ "string", "null" ] } } }, "line_items": { "type": "array", "items": { "type": "object", "required": [ "id", "digital_product_id", "title", "sku", "quantity", "shopify_line_item_id", "shopify_product_id", "shopify_variant_id", "attached_to_this_order_only", "access", "preorder", "files" ], "properties": { "id": { "type": [ "string", "null" ] }, "digital_product_id": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "sku": { "type": [ "string", "null" ] }, "quantity": { "type": [ "integer", "null" ] }, "shopify_line_item_id": { "type": [ "string", "null" ] }, "shopify_product_id": { "type": [ "string", "null" ] }, "shopify_variant_id": { "type": [ "string", "null" ] }, "attached_to_this_order_only": { "type": [ "boolean", "null" ] }, "access": { "type": "object", "required": [ "revoked", "revoked_at" ], "properties": { "revoked": { "type": [ "boolean", "null" ] }, "revoked_at": {} } }, "preorder": { "type": "object", "required": [ "enabled", "launch_at", "released", "message" ], "properties": { "enabled": { "type": [ "boolean", "null" ] }, "launch_at": {}, "released": { "type": [ "boolean", "null" ] }, "message": {} } }, "files": { "type": "array", "items": { "type": "object", "required": [ "id", "asset", "download_count", "watermark", "licence_keys" ], "properties": { "id": {}, "asset": { "type": "object", "required": [ "id", "name", "type" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] } } }, "download_count": { "type": [ "integer", "null" ] }, "watermark": { "type": "object", "required": [ "enabled", "status" ], "properties": { "enabled": { "type": [ "boolean", "null" ] }, "status": { "type": [ "string", "null" ] } } }, "licence_keys": { "type": "array" } } } } } } }, "eu_withdrawal": { "type": "object", "required": [ "consent_required", "consented_at", "consent_text" ], "properties": { "consent_required": { "type": [ "boolean", "null" ] }, "consented_at": {}, "consent_text": {} } }, "shopify_tags": { "type": "array" }, "imported_at": {}, "deleted_at": {}, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } } }, "example": { "id": "3e84eb8d-e1d9-4e92-a4b2-a419c7f1122f", "shopify_order_id": "gid://shopify/Order/7555375595815", "name": "#1077", "confirmation_number": "H5CZG3GZX", "ordered_at": "2026-10-26T14:19:15Z", "customer": { "id": "b797db3a-cbc3-4643-804f-adf34c7f08d7", "shopify_customer_id": "gid://shopify/Customer/9026290417959", "email": "shopper@example.com", "phone": null, "first_name": "Jane", "last_name": "Doe", "country_code": null, "locale": null, "unsubscribed": false }, "total": { "amount": "1142.89", "currency": "INR" }, "status": { "financial": "paid", "fulfillment": "unfulfilled", "cancelled_at": null, "paid_at": "2026-10-30T21:48:16Z", "flagged_as_fraud": false, "fraud_check_completed": false, "marked_fulfilled_at": null, "delivery_conditions_met": false }, "access": { "state": "active", "revoked_at": null, "available_until": null, "download_reset_at": "2026-10-30T22:19:10Z", "downloads_count": 0 }, "delivery": { "email_sent_at": "2026-10-30T22:34:30Z", "delivery_failed_at": null, "download_page_url": "https://example-store.myshopify.com/apps/filemonk/orders/3e84eb8d-e1d9-4e92-a4b2-a419c7f1122f", "source": "webhook" }, "line_items": [ { "id": "5956bb41-dc65-45d5-b7d7-25f570598468", "digital_product_id": "7ea3c05d-6f29-42b6-b24f-43260caeaa32", "title": "Watercolour Course", "sku": "b0f5fbd0-f231-470f-b3d1-a392e3136a50", "quantity": 2, "shopify_line_item_id": "gid://shopify/LineItem/18329329434919", "shopify_product_id": "gid://shopify/Product/9642107044135", "shopify_variant_id": "gid://shopify/ProductVariant/49417714893095", "attached_to_this_order_only": false, "access": { "revoked": false, "revoked_at": null }, "preorder": { "enabled": false, "launch_at": null, "released": true, "message": null }, "files": [ { "id": null, "asset": { "id": "7ea42f2a-6dbe-459c-b8a4-27b0eb823e52", "name": "price-list.csv", "type": "file" }, "download_count": 0, "watermark": { "enabled": false, "status": "not_required" }, "licence_keys": [] }, { "id": "66e2751c-9812-422c-864d-f8ce6a95c605", "asset": { "id": "96fbe30b-c819-4cb8-9666-814c0c8853f1", "name": "Beginner's Guide.pdf", "type": "file" }, "download_count": 0, "watermark": { "enabled": true, "status": "ready" }, "licence_keys": [] } ] } ], "eu_withdrawal": { "consent_required": false, "consented_at": null, "consent_text": null }, "shopify_tags": [], "imported_at": null, "deleted_at": null, "created_at": "2026-10-26T14:19:29Z", "updated_at": "2026-10-30T22:19:10Z" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/BadGateway" } }, "x-aliases": [ "import order", "add order from shopify", "find order on shopify", "process this order", "deliver an order filemonk missed" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "shopify_order_id": {}, "send_email": {}, "confirm": {} }, "required": [ "shopify_order_id" ] }, "example": { "shopify_order_id": "gid://shopify/Order/7555375595815", "send_email": false } } } } }, "get": { "operationId": "get_orders", "summary": "List", "description": "List the orders Filemonk delivers files for, newest first by ordered_at (when the buyer placed the order; sort=created_at desc orders by when Filemonk recorded it), paginated (page, per_page up to 200). meta.total_count is the number of orders. search matches the order name, email or phone the way the Orders page search does. financial_status filters by Shopify financial status; access by Filemonk's access state (active, revoked, partially_revoked, expired); email, customer_id, shopify_product_id and digital_product_id narrow to one buyer or one product; created_at_min / created_at_max (or from / to) are ISO 8601 bounds on when Filemonk recorded the order. Deleted orders are left out.", "tags": [ "Orders" ], "responses": { "200": { "description": "Success — one page of rows.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "currency", "meta" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "shopify_order_id", "name", "ordered_at", "customer", "total", "status", "access", "delivery", "line_items_count", "created_at" ], "properties": { "id": { "type": [ "string", "null" ] }, "shopify_order_id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "ordered_at": { "type": [ "string", "null" ] }, "customer": { "type": "object", "required": [ "email", "first_name", "last_name" ], "properties": { "email": { "type": [ "string", "null" ] }, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] } } }, "total": { "type": "object", "required": [ "amount", "currency" ], "properties": { "amount": { "type": [ "string", "null" ] }, "currency": { "type": [ "string", "null" ] } } }, "status": { "type": "object", "required": [ "financial", "flagged_as_fraud" ], "properties": { "financial": { "type": [ "string", "null" ] }, "flagged_as_fraud": { "type": [ "boolean", "null" ] } } }, "access": { "type": "object", "required": [ "state", "downloads_count" ], "properties": { "state": { "type": [ "string", "null" ] }, "downloads_count": { "type": [ "integer", "null" ] } } }, "delivery": { "type": "object", "required": [ "email_sent_at" ], "properties": { "email_sent_at": { "type": [ "string", "null" ] } } }, "line_items_count": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ] } } } }, "currency": { "type": [ "string", "null" ] }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "example": { "data": [ { "id": "3e84eb8d-e1d9-4e92-a4b2-a419c7f1122f", "shopify_order_id": "gid://shopify/Order/7555375595815", "name": "#1077", "ordered_at": "2026-10-26T14:19:15Z", "customer": { "email": "shopper@example.com", "first_name": "Jane", "last_name": "Doe" }, "total": { "amount": "1142.89", "currency": "INR" }, "status": { "financial": "paid", "flagged_as_fraud": false }, "access": { "state": "active", "downloads_count": 0 }, "delivery": { "email_sent_at": "2026-10-30T22:34:30Z" }, "line_items_count": 2, "created_at": "2026-10-26T14:19:29Z" } ], "currency": "INR", "meta": { "total_count": 48, "page": 1, "per_page": 50, "total_pages": 1 } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "list orders", "recent orders", "orders for a customer", "who bought this product", "unpaid orders", "orders with access revoked", "search orders" ], "parameters": [ { "name": "financial_status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "authorized", "partially_paid", "paid", "partially_refunded", "refunded", "voided" ] }, "example": "pending" }, { "name": "access", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "revoked", "partially_revoked", "expired" ] }, "example": "active" }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ordered_at desc", "ordered_at asc", "created_at desc", "created_at asc", "name asc", "name desc", "email asc", "email desc", "notified_at asc", "notified_at desc" ] }, "example": "ordered_at desc" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "description": "1-based page number." }, "example": 1, "description": "1-based page number." }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50, "description": "Rows per page, max 200." }, "example": 50, "description": "Rows per page, max 200." }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "example": "string" }, { "name": "email", "in": "query", "required": false, "schema": { "type": "string" }, "example": "shopper@example.com" }, { "name": "customer_id", "in": "query", "required": false, "schema": { "type": "string" }, "example": "string" }, { "name": "shopify_product_id", "in": "query", "required": false, "schema": { "type": "string" }, "example": "gid://shopify/Product/78000000001" }, { "name": "digital_product_id", "in": "query", "required": false, "schema": { "type": "string" }, "example": "2b7d9e0f-1a2b-4c3d-9e5f-6a7b8c9d0e1f" }, { "name": "created_at_min", "in": "query", "required": false, "schema": { "type": "string" }, "example": "2026-07-01T00:00:00Z" }, { "name": "created_at_max", "in": "query", "required": false, "schema": { "type": "string" }, "example": "2026-07-01T00:00:00Z" }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string" }, "example": "string" }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string" }, "example": "string" } ] } }, "/orders/{id}": { "delete": { "operationId": "delete_orders_id", "summary": "Delete", "description": "Delete an order from Filemonk, as the order page's Delete does: it leaves the lists and the buyer's download page stops working. The Shopify order is untouched. Destructive: send it first without `confirm`. Nothing changes and the 409 `confirmation_required` says what would. Tell the merchant, ask, and resend with `confirm: true` only after they agree.\n\n**Note:** Soft delete: the row is kept but no read returns it; importing the order again (POST /orders) restores it. Without confirm: true nothing is deleted: 409 confirmation_required.", "tags": [ "Orders" ], "responses": { "200": { "description": "Success — the write completed; the body is the updated resource.", "content": { "application/json": { "schema": { "type": "object", "required": [ "deleted", "id" ], "properties": { "deleted": { "type": [ "boolean", "null" ] }, "id": { "type": [ "string", "null" ] } } }, "example": { "deleted": true, "id": "3e84eb8d-e1d9-4e92-a4b2-a419c7f1122f" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "delete order", "remove order", "hide this order" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "confirm", "in": "query", "required": false, "schema": { "type": "string" }, "example": "string" } ] }, "get": { "operationId": "get_orders_id", "summary": "Read", "description": "One order in full: the buyer, Shopify statuses, Filemonk's access state and expiry, delivery (download email, download page link), and every line item with its files, watermark state and licence keys. :id is Filemonk's order id, the Shopify order gid or id, or the order name (#1042).", "tags": [ "Orders" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "shopify_order_id", "name", "confirmation_number", "ordered_at", "customer", "total", "status", "access", "delivery", "line_items", "eu_withdrawal", "shopify_tags", "imported_at", "deleted_at", "created_at", "updated_at" ], "properties": { "id": { "type": [ "string", "null" ] }, "shopify_order_id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "confirmation_number": { "type": [ "string", "null" ] }, "ordered_at": { "type": [ "string", "null" ] }, "customer": { "type": "object", "required": [ "id", "shopify_customer_id", "email", "phone", "first_name", "last_name", "country_code", "locale", "unsubscribed" ], "properties": { "id": { "type": [ "string", "null" ] }, "shopify_customer_id": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "phone": {}, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "country_code": {}, "locale": {}, "unsubscribed": { "type": [ "boolean", "null" ] } } }, "total": { "type": "object", "required": [ "amount", "currency" ], "properties": { "amount": { "type": [ "string", "null" ] }, "currency": { "type": [ "string", "null" ] } } }, "status": { "type": "object", "required": [ "financial", "fulfillment", "cancelled_at", "paid_at", "flagged_as_fraud", "fraud_check_completed", "marked_fulfilled_at", "delivery_conditions_met" ], "properties": { "financial": { "type": [ "string", "null" ] }, "fulfillment": { "type": [ "string", "null" ] }, "cancelled_at": {}, "paid_at": { "type": [ "string", "null" ] }, "flagged_as_fraud": { "type": [ "boolean", "null" ] }, "fraud_check_completed": { "type": [ "boolean", "null" ] }, "marked_fulfilled_at": {}, "delivery_conditions_met": { "type": [ "boolean", "null" ] } } }, "access": { "type": "object", "required": [ "state", "revoked_at", "available_until", "download_reset_at", "downloads_count" ], "properties": { "state": { "type": [ "string", "null" ] }, "revoked_at": {}, "available_until": {}, "download_reset_at": { "type": [ "string", "null" ] }, "downloads_count": { "type": [ "integer", "null" ] } } }, "delivery": { "type": "object", "required": [ "email_sent_at", "delivery_failed_at", "download_page_url", "source" ], "properties": { "email_sent_at": { "type": [ "string", "null" ] }, "delivery_failed_at": {}, "download_page_url": { "type": [ "string", "null" ] }, "source": { "type": [ "string", "null" ] } } }, "line_items": { "type": "array", "items": { "type": "object", "required": [ "id", "digital_product_id", "title", "sku", "quantity", "shopify_line_item_id", "shopify_product_id", "shopify_variant_id", "attached_to_this_order_only", "access", "preorder", "files" ], "properties": { "id": { "type": [ "string", "null" ] }, "digital_product_id": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "sku": { "type": [ "string", "null" ] }, "quantity": { "type": [ "integer", "null" ] }, "shopify_line_item_id": { "type": [ "string", "null" ] }, "shopify_product_id": { "type": [ "string", "null" ] }, "shopify_variant_id": { "type": [ "string", "null" ] }, "attached_to_this_order_only": { "type": [ "boolean", "null" ] }, "access": { "type": "object", "required": [ "revoked", "revoked_at" ], "properties": { "revoked": { "type": [ "boolean", "null" ] }, "revoked_at": {} } }, "preorder": { "type": "object", "required": [ "enabled", "launch_at", "released", "message" ], "properties": { "enabled": { "type": [ "boolean", "null" ] }, "launch_at": {}, "released": { "type": [ "boolean", "null" ] }, "message": {} } }, "files": { "type": "array", "items": { "type": "object", "required": [ "id", "asset", "download_count", "watermark", "licence_keys" ], "properties": { "id": {}, "asset": { "type": "object", "required": [ "id", "name", "type" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] } } }, "download_count": { "type": [ "integer", "null" ] }, "watermark": { "type": "object", "required": [ "enabled", "status" ], "properties": { "enabled": { "type": [ "boolean", "null" ] }, "status": { "type": [ "string", "null" ] } } }, "licence_keys": { "type": "array" } } } } } } }, "eu_withdrawal": { "type": "object", "required": [ "consent_required", "consented_at", "consent_text" ], "properties": { "consent_required": { "type": [ "boolean", "null" ] }, "consented_at": {}, "consent_text": {} } }, "shopify_tags": { "type": "array" }, "imported_at": {}, "deleted_at": {}, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } } }, "example": { "id": "3e84eb8d-e1d9-4e92-a4b2-a419c7f1122f", "shopify_order_id": "gid://shopify/Order/7555375595815", "name": "#1077", "confirmation_number": "H5CZG3GZX", "ordered_at": "2026-10-26T14:19:15Z", "customer": { "id": "b797db3a-cbc3-4643-804f-adf34c7f08d7", "shopify_customer_id": "gid://shopify/Customer/9026290417959", "email": "shopper@example.com", "phone": null, "first_name": "Jane", "last_name": "Doe", "country_code": null, "locale": null, "unsubscribed": false }, "total": { "amount": "1142.89", "currency": "INR" }, "status": { "financial": "paid", "fulfillment": "unfulfilled", "cancelled_at": null, "paid_at": "2026-10-30T21:48:16Z", "flagged_as_fraud": false, "fraud_check_completed": false, "marked_fulfilled_at": null, "delivery_conditions_met": false }, "access": { "state": "active", "revoked_at": null, "available_until": null, "download_reset_at": "2026-10-30T22:19:10Z", "downloads_count": 0 }, "delivery": { "email_sent_at": "2026-10-30T22:34:30Z", "delivery_failed_at": null, "download_page_url": "https://example-store.myshopify.com/apps/filemonk/orders/3e84eb8d-e1d9-4e92-a4b2-a419c7f1122f", "source": "webhook" }, "line_items": [ { "id": "5956bb41-dc65-45d5-b7d7-25f570598468", "digital_product_id": "7ea3c05d-6f29-42b6-b24f-43260caeaa32", "title": "Watercolour Course", "sku": "b0f5fbd0-f231-470f-b3d1-a392e3136a50", "quantity": 2, "shopify_line_item_id": "gid://shopify/LineItem/18329329434919", "shopify_product_id": "gid://shopify/Product/9642107044135", "shopify_variant_id": "gid://shopify/ProductVariant/49417714893095", "attached_to_this_order_only": false, "access": { "revoked": false, "revoked_at": null }, "preorder": { "enabled": false, "launch_at": null, "released": true, "message": null }, "files": [ { "id": null, "asset": { "id": "7ea42f2a-6dbe-459c-b8a4-27b0eb823e52", "name": "price-list.csv", "type": "file" }, "download_count": 0, "watermark": { "enabled": false, "status": "not_required" }, "licence_keys": [] }, { "id": "66e2751c-9812-422c-864d-f8ce6a95c605", "asset": { "id": "96fbe30b-c819-4cb8-9666-814c0c8853f1", "name": "Beginner's Guide.pdf", "type": "file" }, "download_count": 0, "watermark": { "enabled": true, "status": "ready" }, "licence_keys": [] } ] } ], "eu_withdrawal": { "consent_required": false, "consented_at": null, "consent_text": null }, "shopify_tags": [], "imported_at": null, "deleted_at": null, "created_at": "2026-10-26T14:19:29Z", "updated_at": "2026-10-30T22:19:10Z" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "show order", "look up order", "order details", "find order by number", "what did this customer get" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "patch": { "operationId": "patch_orders_id", "summary": "Update", "description": "Revoke or restore the buyer's access to the whole order (access.revoked), as the order page's access toggle does. Restoring also clears a fraud flag. Per line item access is PATCH /orders/:id/line_items/:line_item_id; download counters are POST /orders/:id/reset_downloads.\n\n**Note:** Deep partial: only the fields sent are written.", "tags": [ "Orders" ], "responses": { "200": { "description": "Success — the write completed; the body is the updated resource.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "shopify_order_id", "name", "confirmation_number", "ordered_at", "customer", "total", "status", "access", "delivery", "line_items", "eu_withdrawal", "shopify_tags", "imported_at", "deleted_at", "created_at", "updated_at" ], "properties": { "id": { "type": [ "string", "null" ] }, "shopify_order_id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "confirmation_number": { "type": [ "string", "null" ] }, "ordered_at": { "type": [ "string", "null" ] }, "customer": { "type": "object", "required": [ "id", "shopify_customer_id", "email", "phone", "first_name", "last_name", "country_code", "locale", "unsubscribed" ], "properties": { "id": { "type": [ "string", "null" ] }, "shopify_customer_id": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "phone": {}, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "country_code": {}, "locale": {}, "unsubscribed": { "type": [ "boolean", "null" ] } } }, "total": { "type": "object", "required": [ "amount", "currency" ], "properties": { "amount": { "type": [ "string", "null" ] }, "currency": { "type": [ "string", "null" ] } } }, "status": { "type": "object", "required": [ "financial", "fulfillment", "cancelled_at", "paid_at", "flagged_as_fraud", "fraud_check_completed", "marked_fulfilled_at", "delivery_conditions_met" ], "properties": { "financial": { "type": [ "string", "null" ] }, "fulfillment": { "type": [ "string", "null" ] }, "cancelled_at": {}, "paid_at": { "type": [ "string", "null" ] }, "flagged_as_fraud": { "type": [ "boolean", "null" ] }, "fraud_check_completed": { "type": [ "boolean", "null" ] }, "marked_fulfilled_at": {}, "delivery_conditions_met": { "type": [ "boolean", "null" ] } } }, "access": { "type": "object", "required": [ "state", "revoked_at", "available_until", "download_reset_at", "downloads_count" ], "properties": { "state": { "type": [ "string", "null" ] }, "revoked_at": { "type": [ "string", "null" ] }, "available_until": {}, "download_reset_at": { "type": [ "string", "null" ] }, "downloads_count": { "type": [ "integer", "null" ] } } }, "delivery": { "type": "object", "required": [ "email_sent_at", "delivery_failed_at", "download_page_url", "source" ], "properties": { "email_sent_at": { "type": [ "string", "null" ] }, "delivery_failed_at": {}, "download_page_url": { "type": [ "string", "null" ] }, "source": { "type": [ "string", "null" ] } } }, "line_items": { "type": "array", "items": { "type": "object", "required": [ "id", "digital_product_id", "title", "sku", "quantity", "shopify_line_item_id", "shopify_product_id", "shopify_variant_id", "attached_to_this_order_only", "access", "preorder", "files" ], "properties": { "id": { "type": [ "string", "null" ] }, "digital_product_id": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "sku": { "type": [ "string", "null" ] }, "quantity": { "type": [ "integer", "null" ] }, "shopify_line_item_id": { "type": [ "string", "null" ] }, "shopify_product_id": { "type": [ "string", "null" ] }, "shopify_variant_id": { "type": [ "string", "null" ] }, "attached_to_this_order_only": { "type": [ "boolean", "null" ] }, "access": { "type": "object", "required": [ "revoked", "revoked_at" ], "properties": { "revoked": { "type": [ "boolean", "null" ] }, "revoked_at": {} } }, "preorder": { "type": "object", "required": [ "enabled", "launch_at", "released", "message" ], "properties": { "enabled": { "type": [ "boolean", "null" ] }, "launch_at": {}, "released": { "type": [ "boolean", "null" ] }, "message": {} } }, "files": { "type": "array", "items": { "type": "object", "required": [ "id", "asset", "download_count", "watermark", "licence_keys" ], "properties": { "id": {}, "asset": { "type": "object", "required": [ "id", "name", "type" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] } } }, "download_count": { "type": [ "integer", "null" ] }, "watermark": { "type": "object", "required": [ "enabled", "status" ], "properties": { "enabled": { "type": [ "boolean", "null" ] }, "status": { "type": [ "string", "null" ] } } }, "licence_keys": { "type": "array" } } } } } } }, "eu_withdrawal": { "type": "object", "required": [ "consent_required", "consented_at", "consent_text" ], "properties": { "consent_required": { "type": [ "boolean", "null" ] }, "consented_at": {}, "consent_text": {} } }, "shopify_tags": { "type": "array" }, "imported_at": {}, "deleted_at": {}, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } } }, "example": { "id": "3e84eb8d-e1d9-4e92-a4b2-a419c7f1122f", "shopify_order_id": "gid://shopify/Order/7555375595815", "name": "#1077", "confirmation_number": "H5CZG3GZX", "ordered_at": "2026-10-26T14:19:15Z", "customer": { "id": "b797db3a-cbc3-4643-804f-adf34c7f08d7", "shopify_customer_id": "gid://shopify/Customer/9026290417959", "email": "shopper@example.com", "phone": null, "first_name": "Jane", "last_name": "Doe", "country_code": null, "locale": null, "unsubscribed": false }, "total": { "amount": "1142.89", "currency": "INR" }, "status": { "financial": "paid", "fulfillment": "unfulfilled", "cancelled_at": null, "paid_at": "2026-10-30T21:48:16Z", "flagged_as_fraud": false, "fraud_check_completed": false, "marked_fulfilled_at": null, "delivery_conditions_met": false }, "access": { "state": "revoked", "revoked_at": "2026-10-30T23:10:00Z", "available_until": null, "download_reset_at": "2026-10-30T22:19:10Z", "downloads_count": 0 }, "delivery": { "email_sent_at": "2026-10-30T22:34:30Z", "delivery_failed_at": null, "download_page_url": "https://example-store.myshopify.com/apps/filemonk/orders/3e84eb8d-e1d9-4e92-a4b2-a419c7f1122f", "source": "webhook" }, "line_items": [ { "id": "5956bb41-dc65-45d5-b7d7-25f570598468", "digital_product_id": "7ea3c05d-6f29-42b6-b24f-43260caeaa32", "title": "Watercolour Course", "sku": "b0f5fbd0-f231-470f-b3d1-a392e3136a50", "quantity": 2, "shopify_line_item_id": "gid://shopify/LineItem/18329329434919", "shopify_product_id": "gid://shopify/Product/9642107044135", "shopify_variant_id": "gid://shopify/ProductVariant/49417714893095", "attached_to_this_order_only": false, "access": { "revoked": false, "revoked_at": null }, "preorder": { "enabled": false, "launch_at": null, "released": true, "message": null }, "files": [ { "id": null, "asset": { "id": "7ea42f2a-6dbe-459c-b8a4-27b0eb823e52", "name": "price-list.csv", "type": "file" }, "download_count": 0, "watermark": { "enabled": false, "status": "not_required" }, "licence_keys": [] }, { "id": "66e2751c-9812-422c-864d-f8ce6a95c605", "asset": { "id": "96fbe30b-c819-4cb8-9666-814c0c8853f1", "name": "Beginner's Guide.pdf", "type": "file" }, "download_count": 0, "watermark": { "enabled": true, "status": "ready" }, "licence_keys": [] } ] } ], "eu_withdrawal": { "consent_required": false, "consented_at": null, "consent_text": null }, "shopify_tags": [], "imported_at": null, "deleted_at": null, "created_at": "2026-10-26T14:19:29Z", "updated_at": "2026-10-30T22:19:10Z" }, "examples": { "revoke": { "summary": "Revoke the buyer's access", "value": { "id": "3e84eb8d-e1d9-4e92-a4b2-a419c7f1122f", "shopify_order_id": "gid://shopify/Order/7555375595815", "name": "#1077", "confirmation_number": "H5CZG3GZX", "ordered_at": "2026-10-26T14:19:15Z", "customer": { "id": "b797db3a-cbc3-4643-804f-adf34c7f08d7", "shopify_customer_id": "gid://shopify/Customer/9026290417959", "email": "shopper@example.com", "phone": null, "first_name": "Jane", "last_name": "Doe", "country_code": null, "locale": null, "unsubscribed": false }, "total": { "amount": "1142.89", "currency": "INR" }, "status": { "financial": "paid", "fulfillment": "unfulfilled", "cancelled_at": null, "paid_at": "2026-10-30T21:48:16Z", "flagged_as_fraud": false, "fraud_check_completed": false, "marked_fulfilled_at": null, "delivery_conditions_met": false }, "access": { "state": "revoked", "revoked_at": "2026-10-30T23:10:00Z", "available_until": null, "download_reset_at": "2026-10-30T22:19:10Z", "downloads_count": 0 }, "delivery": { "email_sent_at": "2026-10-30T22:34:30Z", "delivery_failed_at": null, "download_page_url": "https://example-store.myshopify.com/apps/filemonk/orders/3e84eb8d-e1d9-4e92-a4b2-a419c7f1122f", "source": "webhook" }, "line_items": [ { "id": "5956bb41-dc65-45d5-b7d7-25f570598468", "digital_product_id": "7ea3c05d-6f29-42b6-b24f-43260caeaa32", "title": "Watercolour Course", "sku": "b0f5fbd0-f231-470f-b3d1-a392e3136a50", "quantity": 2, "shopify_line_item_id": "gid://shopify/LineItem/18329329434919", "shopify_product_id": "gid://shopify/Product/9642107044135", "shopify_variant_id": "gid://shopify/ProductVariant/49417714893095", "attached_to_this_order_only": false, "access": { "revoked": false, "revoked_at": null }, "preorder": { "enabled": false, "launch_at": null, "released": true, "message": null }, "files": [ { "id": null, "asset": { "id": "7ea42f2a-6dbe-459c-b8a4-27b0eb823e52", "name": "price-list.csv", "type": "file" }, "download_count": 0, "watermark": { "enabled": false, "status": "not_required" }, "licence_keys": [] }, { "id": "66e2751c-9812-422c-864d-f8ce6a95c605", "asset": { "id": "96fbe30b-c819-4cb8-9666-814c0c8853f1", "name": "Beginner's Guide.pdf", "type": "file" }, "download_count": 0, "watermark": { "enabled": true, "status": "ready" }, "licence_keys": [] } ] } ], "eu_withdrawal": { "consent_required": false, "consented_at": null, "consent_text": null }, "shopify_tags": [], "imported_at": null, "deleted_at": null, "created_at": "2026-10-26T14:19:29Z", "updated_at": "2026-10-30T22:19:10Z" } }, "restore": { "summary": "Restore access", "value": { "id": "3e84eb8d-e1d9-4e92-a4b2-a419c7f1122f", "shopify_order_id": "gid://shopify/Order/7555375595815", "name": "#1077", "confirmation_number": "H5CZG3GZX", "ordered_at": "2026-10-26T14:19:15Z", "customer": { "id": "b797db3a-cbc3-4643-804f-adf34c7f08d7", "shopify_customer_id": "gid://shopify/Customer/9026290417959", "email": "shopper@example.com", "phone": null, "first_name": "Jane", "last_name": "Doe", "country_code": null, "locale": null, "unsubscribed": false }, "total": { "amount": "1142.89", "currency": "INR" }, "status": { "financial": "paid", "fulfillment": "unfulfilled", "cancelled_at": null, "paid_at": "2026-10-30T21:48:16Z", "flagged_as_fraud": false, "fraud_check_completed": false, "marked_fulfilled_at": null, "delivery_conditions_met": false }, "access": { "state": "active", "revoked_at": null, "available_until": null, "download_reset_at": "2026-10-30T22:19:10Z", "downloads_count": 0 }, "delivery": { "email_sent_at": "2026-10-30T22:34:30Z", "delivery_failed_at": null, "download_page_url": "https://example-store.myshopify.com/apps/filemonk/orders/3e84eb8d-e1d9-4e92-a4b2-a419c7f1122f", "source": "webhook" }, "line_items": [ { "id": "5956bb41-dc65-45d5-b7d7-25f570598468", "digital_product_id": "7ea3c05d-6f29-42b6-b24f-43260caeaa32", "title": "Watercolour Course", "sku": "b0f5fbd0-f231-470f-b3d1-a392e3136a50", "quantity": 2, "shopify_line_item_id": "gid://shopify/LineItem/18329329434919", "shopify_product_id": "gid://shopify/Product/9642107044135", "shopify_variant_id": "gid://shopify/ProductVariant/49417714893095", "attached_to_this_order_only": false, "access": { "revoked": false, "revoked_at": null }, "preorder": { "enabled": false, "launch_at": null, "released": true, "message": null }, "files": [ { "id": null, "asset": { "id": "7ea42f2a-6dbe-459c-b8a4-27b0eb823e52", "name": "price-list.csv", "type": "file" }, "download_count": 0, "watermark": { "enabled": false, "status": "not_required" }, "licence_keys": [] }, { "id": "66e2751c-9812-422c-864d-f8ce6a95c605", "asset": { "id": "96fbe30b-c819-4cb8-9666-814c0c8853f1", "name": "Beginner's Guide.pdf", "type": "file" }, "download_count": 0, "watermark": { "enabled": true, "status": "ready" }, "licence_keys": [] } ] } ], "eu_withdrawal": { "consent_required": false, "consented_at": null, "consent_text": null }, "shopify_tags": [], "imported_at": null, "deleted_at": null, "created_at": "2026-10-26T14:19:29Z", "updated_at": "2026-10-30T22:19:10Z" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "revoke access", "restore access", "disable downloads for this order", "re-enable the order", "block this order", "unblock order" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "access": {} } }, "example": { "access": { "revoked": true } }, "examples": { "revoke": { "summary": "Revoke the buyer's access", "value": { "access": { "revoked": true } } }, "restore": { "summary": "Restore access", "description": "Restoring also clears a fraud flag.", "value": { "access": { "revoked": false } } } } } } } } }, "/orders/{id}/download_logs": { "get": { "operationId": "get_orders_id_download_logs", "summary": "Download Logs", "description": "Every download recorded for one order, newest first, paginated: which file, when, from which IP, country and browser.", "tags": [ "Orders" ], "responses": { "200": { "description": "Success — one page of rows.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "downloaded_at", "order", "asset", "digital_product_id", "file", "licence_tag", "client", "cdn_provider" ], "properties": { "id": { "type": [ "string", "null" ] }, "downloaded_at": { "type": [ "string", "null" ] }, "order": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } } }, "asset": { "type": "object", "required": [ "id", "name", "type" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] } } }, "digital_product_id": { "type": [ "string", "null" ] }, "file": { "type": "object", "required": [ "filename", "content_type", "byte_size" ], "properties": { "filename": { "type": [ "string", "null" ] }, "content_type": { "type": [ "string", "null" ] }, "byte_size": { "type": [ "integer", "null" ] } } }, "licence_tag": {}, "client": { "type": "object", "required": [ "ip_address", "country_code", "user_agent", "referrer" ], "properties": { "ip_address": { "type": [ "string", "null" ] }, "country_code": {}, "user_agent": { "type": [ "string", "null" ] }, "referrer": { "type": [ "string", "null" ] } } }, "cdn_provider": { "type": [ "string", "null" ] } } } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "example": { "data": [ { "id": "a401ec79-a062-4ab0-96e6-a588931583cc", "downloaded_at": "2026-10-12T19:50:17Z", "order": { "id": "71e9bb0e-1e22-4513-af29-60aceeeb3755", "name": "#1058" }, "asset": { "id": "96fbe30b-c819-4cb8-9666-814c0c8853f1", "name": "Beginner's Guide.pdf", "type": "file" }, "digital_product_id": "7ea3c05d-6f29-42b6-b24f-43260caeaa32", "file": { "filename": "Watercolour Basics Workbook.pdf", "content_type": "application/pdf", "byte_size": 116711 }, "licence_tag": null, "client": { "ip_address": "203.0.113.7", "country_code": null, "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 16_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/16.0 Mobile/15E148 Safari/604.1", "referrer": "https://app.filemonk.io/orders/71e9bb0e-1e22-4513-af29-60aceeeb3755" }, "cdn_provider": "cloudflare" } ], "meta": { "total_count": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "download history of an order", "did the customer download", "who downloaded this order" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "description": "1-based page number." }, "example": 1, "description": "1-based page number." }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50, "description": "Rows per page, max 200." }, "example": 50, "description": "Rows per page, max 200." } ] } }, "/orders/{id}/downloads": { "get": { "operationId": "get_orders_id_downloads", "summary": "Downloads", "description": "What the buyer of an order can download right now: one row per file with its download url (null while a watermark is still being applied, or when access is revoked, expired or the download limit is reached), the watermark state and the download count. A watermarked file's url is a signed link that stops working at url_expires_at; a plain file's url is a redirect that does not expire and a link is its own address, so both have url_expires_at null.", "tags": [ "Orders" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "file_id", "asset", "url", "url_expires_at", "watermark", "download_count" ], "properties": { "file_id": { "type": [ "string", "null" ] }, "asset": { "type": "object", "required": [ "id", "name", "type", "filename", "content_type", "byte_size" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "filename": { "type": [ "string", "null" ] }, "content_type": { "type": [ "string", "null" ] }, "byte_size": { "type": [ "integer", "null" ] } } }, "url": { "type": [ "string", "null" ] }, "url_expires_at": { "type": [ "string", "null" ] }, "watermark": { "type": "object", "required": [ "enabled", "status" ], "properties": { "enabled": { "type": [ "boolean", "null" ] }, "status": { "type": [ "string", "null" ] } } }, "download_count": { "type": [ "integer", "null" ] } } } } } }, "example": { "data": [ { "file_id": "66e2751c-9812-422c-864d-f8ce6a95c605", "asset": { "id": "96fbe30b-c819-4cb8-9666-814c0c8853f1", "name": "Beginner's Guide.pdf", "type": "file", "filename": "Beginner's Guide.pdf", "content_type": "application/pdf", "byte_size": 116711 }, "url": "https://files.filemonk.io/orders/5600000000001/guide.pdf?X-Amz-Expires=3600&X-Amz-Signature=3f6c…", "url_expires_at": "2026-10-31T00:48:11Z", "watermark": { "enabled": true, "status": "ready" }, "download_count": 0 } ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "download links for an order", "resend download link", "order files", "can the customer download" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/orders/{id}/emails": { "get": { "operationId": "get_orders_id_emails", "summary": "Emails", "description": "Every email Filemonk sent for one order, newest first, paginated, with the furthest point each reached: queued, sent, delivered, opened, clicked, rejected, bounced or complained.", "tags": [ "Orders" ], "responses": { "200": { "description": "Success — one page of rows.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "kind", "to", "from", "order", "status", "timeline", "created_at" ], "properties": { "id": { "type": [ "string", "null" ] }, "kind": { "type": [ "string", "null" ] }, "to": { "type": [ "string", "null" ] }, "from": { "type": [ "string", "null" ] }, "order": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } } }, "status": { "type": [ "string", "null" ] }, "timeline": { "type": "object", "required": [ "sent_at", "delivered_at", "opened_at", "clicked_at", "bounced_at", "rejected_at", "complained_at" ], "properties": { "sent_at": { "type": [ "string", "null" ] }, "delivered_at": { "type": [ "string", "null" ] }, "opened_at": {}, "clicked_at": {}, "bounced_at": {}, "rejected_at": {}, "complained_at": {} } }, "created_at": { "type": [ "string", "null" ] } } } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "example": { "data": [ { "id": "77c81a2e-4221-4a03-b784-221de4b1bf5c", "kind": "delivery", "to": "shopper@example.com", "from": "alerts@example-store.filemonk.io", "order": { "id": "3e84eb8d-e1d9-4e92-a4b2-a419c7f1122f", "name": "#1077" }, "status": "delivered", "timeline": { "sent_at": "2026-10-30T23:02:25Z", "delivered_at": "2026-10-30T23:02:24Z", "opened_at": null, "clicked_at": null, "bounced_at": null, "rejected_at": null, "complained_at": null }, "created_at": "2026-10-30T23:02:24Z" } ], "meta": { "total_count": 12, "page": 1, "per_page": 50, "total_pages": 1 } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "was the download email delivered", "email history of an order", "did the customer open the email" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "description": "1-based page number." }, "example": 1, "description": "1-based page number." }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50, "description": "Rows per page, max 200." }, "example": 50, "description": "Rows per page, max 200." } ] } }, "/orders/{id}/files/attach": { "post": { "operationId": "post_orders_id_files_attach", "summary": "Files Attach", "description": "Attach files to this one order only (asset_ids), as the order page's Add custom files does: they appear on the buyer's download page as a line item of their own, invisible to other buyers of the same products.\n\n**Note:** No email is sent; use POST /orders/:id/send_email afterwards if the buyer should hear about it.", "tags": [ "Orders" ], "responses": { "200": { "description": "Success — the write completed; the body is the updated resource.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "shopify_order_id", "name", "confirmation_number", "ordered_at", "customer", "total", "status", "access", "delivery", "line_items", "eu_withdrawal", "shopify_tags", "imported_at", "deleted_at", "created_at", "updated_at" ], "properties": { "id": { "type": [ "string", "null" ] }, "shopify_order_id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "confirmation_number": { "type": [ "string", "null" ] }, "ordered_at": { "type": [ "string", "null" ] }, "customer": { "type": "object", "required": [ "id", "shopify_customer_id", "email", "phone", "first_name", "last_name", "country_code", "locale", "unsubscribed" ], "properties": { "id": { "type": [ "string", "null" ] }, "shopify_customer_id": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "phone": {}, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "country_code": {}, "locale": {}, "unsubscribed": { "type": [ "boolean", "null" ] } } }, "total": { "type": "object", "required": [ "amount", "currency" ], "properties": { "amount": { "type": [ "string", "null" ] }, "currency": { "type": [ "string", "null" ] } } }, "status": { "type": "object", "required": [ "financial", "fulfillment", "cancelled_at", "paid_at", "flagged_as_fraud", "fraud_check_completed", "marked_fulfilled_at", "delivery_conditions_met" ], "properties": { "financial": { "type": [ "string", "null" ] }, "fulfillment": { "type": [ "string", "null" ] }, "cancelled_at": {}, "paid_at": { "type": [ "string", "null" ] }, "flagged_as_fraud": { "type": [ "boolean", "null" ] }, "fraud_check_completed": { "type": [ "boolean", "null" ] }, "marked_fulfilled_at": {}, "delivery_conditions_met": { "type": [ "boolean", "null" ] } } }, "access": { "type": "object", "required": [ "state", "revoked_at", "available_until", "download_reset_at", "downloads_count" ], "properties": { "state": { "type": [ "string", "null" ] }, "revoked_at": {}, "available_until": {}, "download_reset_at": { "type": [ "string", "null" ] }, "downloads_count": { "type": [ "integer", "null" ] } } }, "delivery": { "type": "object", "required": [ "email_sent_at", "delivery_failed_at", "download_page_url", "source" ], "properties": { "email_sent_at": { "type": [ "string", "null" ] }, "delivery_failed_at": {}, "download_page_url": { "type": [ "string", "null" ] }, "source": { "type": [ "string", "null" ] } } }, "line_items": { "type": "array", "items": { "type": "object", "required": [ "id", "digital_product_id", "title", "sku", "quantity", "shopify_line_item_id", "shopify_product_id", "shopify_variant_id", "attached_to_this_order_only", "access", "preorder", "files" ], "properties": { "id": { "type": [ "string", "null" ] }, "digital_product_id": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "sku": { "type": [ "string", "null" ] }, "quantity": { "type": [ "integer", "null" ] }, "shopify_line_item_id": { "type": [ "string", "null" ] }, "shopify_product_id": { "type": [ "string", "null" ] }, "shopify_variant_id": { "type": [ "string", "null" ] }, "attached_to_this_order_only": { "type": [ "boolean", "null" ] }, "access": { "type": "object", "required": [ "revoked", "revoked_at" ], "properties": { "revoked": { "type": [ "boolean", "null" ] }, "revoked_at": {} } }, "preorder": { "type": "object", "required": [ "enabled", "launch_at", "released", "message" ], "properties": { "enabled": { "type": [ "boolean", "null" ] }, "launch_at": {}, "released": { "type": [ "boolean", "null" ] }, "message": {} } }, "files": { "type": "array", "items": { "type": "object", "required": [ "id", "asset", "download_count", "watermark", "licence_keys" ], "properties": { "id": {}, "asset": { "type": "object", "required": [ "id", "name", "type" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] } } }, "download_count": { "type": [ "integer", "null" ] }, "watermark": { "type": "object", "required": [ "enabled", "status" ], "properties": { "enabled": { "type": [ "boolean", "null" ] }, "status": { "type": [ "string", "null" ] } } }, "licence_keys": { "type": "array" } } } } } } }, "eu_withdrawal": { "type": "object", "required": [ "consent_required", "consented_at", "consent_text" ], "properties": { "consent_required": { "type": [ "boolean", "null" ] }, "consented_at": {}, "consent_text": {} } }, "shopify_tags": { "type": "array" }, "imported_at": {}, "deleted_at": {}, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } } }, "example": { "id": "3e84eb8d-e1d9-4e92-a4b2-a419c7f1122f", "shopify_order_id": "gid://shopify/Order/7555375595815", "name": "#1077", "confirmation_number": "H5CZG3GZX", "ordered_at": "2026-10-26T14:19:15Z", "customer": { "id": "b797db3a-cbc3-4643-804f-adf34c7f08d7", "shopify_customer_id": "gid://shopify/Customer/9026290417959", "email": "shopper@example.com", "phone": null, "first_name": "Jane", "last_name": "Doe", "country_code": null, "locale": null, "unsubscribed": false }, "total": { "amount": "1142.89", "currency": "INR" }, "status": { "financial": "paid", "fulfillment": "unfulfilled", "cancelled_at": null, "paid_at": "2026-10-30T21:48:16Z", "flagged_as_fraud": false, "fraud_check_completed": false, "marked_fulfilled_at": null, "delivery_conditions_met": false }, "access": { "state": "active", "revoked_at": null, "available_until": null, "download_reset_at": "2026-10-30T22:19:10Z", "downloads_count": 0 }, "delivery": { "email_sent_at": "2026-10-30T22:34:30Z", "delivery_failed_at": null, "download_page_url": "https://example-store.myshopify.com/apps/filemonk/orders/3e84eb8d-e1d9-4e92-a4b2-a419c7f1122f", "source": "webhook" }, "line_items": [ { "id": "5956bb41-dc65-45d5-b7d7-25f570598468", "digital_product_id": "7ea3c05d-6f29-42b6-b24f-43260caeaa32", "title": "Watercolour Course", "sku": "b0f5fbd0-f231-470f-b3d1-a392e3136a50", "quantity": 2, "shopify_line_item_id": "gid://shopify/LineItem/18329329434919", "shopify_product_id": "gid://shopify/Product/9642107044135", "shopify_variant_id": "gid://shopify/ProductVariant/49417714893095", "attached_to_this_order_only": false, "access": { "revoked": false, "revoked_at": null }, "preorder": { "enabled": false, "launch_at": null, "released": true, "message": null }, "files": [ { "id": null, "asset": { "id": "7ea42f2a-6dbe-459c-b8a4-27b0eb823e52", "name": "price-list.csv", "type": "file" }, "download_count": 0, "watermark": { "enabled": false, "status": "not_required" }, "licence_keys": [] }, { "id": "66e2751c-9812-422c-864d-f8ce6a95c605", "asset": { "id": "96fbe30b-c819-4cb8-9666-814c0c8853f1", "name": "Beginner's Guide.pdf", "type": "file" }, "download_count": 0, "watermark": { "enabled": true, "status": "ready" }, "licence_keys": [] } ] } ], "eu_withdrawal": { "consent_required": false, "consented_at": null, "consent_text": null }, "shopify_tags": [], "imported_at": null, "deleted_at": null, "created_at": "2026-10-26T14:19:29Z", "updated_at": "2026-10-30T22:19:10Z" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "add a file to this order", "attach custom file", "give this customer an extra file", "send a bonus file to one order" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "asset_ids": { "type": "array", "items": { "type": "string" } } }, "required": [ "asset_ids" ] }, "example": { "asset_ids": [ "e2b7727e-45ad-42b7-b842-cc4615205b10" ] } } } } } }, "/orders/{id}/files/detach": { "post": { "operationId": "post_orders_id_files_detach", "summary": "Files Detach", "description": "Remove files that were attached to this one order (asset_ids). Files that come from the order's digital products are not affected; revoke the line item for those. Destructive: send it first without `confirm`. Nothing changes and the 409 `confirmation_required` says what would. Tell the merchant, ask, and resend with `confirm: true` only after they agree.\n\n**Note:** Without confirm: true nothing changes: 409 confirmation_required names the files. Attach them again to undo.", "tags": [ "Orders" ], "responses": { "200": { "description": "Success — the write completed; the body is the updated resource.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "shopify_order_id", "name", "confirmation_number", "ordered_at", "customer", "total", "status", "access", "delivery", "line_items", "eu_withdrawal", "shopify_tags", "imported_at", "deleted_at", "created_at", "updated_at" ], "properties": { "id": { "type": [ "string", "null" ] }, "shopify_order_id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "confirmation_number": { "type": [ "string", "null" ] }, "ordered_at": { "type": [ "string", "null" ] }, "customer": { "type": "object", "required": [ "id", "shopify_customer_id", "email", "phone", "first_name", "last_name", "country_code", "locale", "unsubscribed" ], "properties": { "id": { "type": [ "string", "null" ] }, "shopify_customer_id": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "phone": {}, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "country_code": {}, "locale": {}, "unsubscribed": { "type": [ "boolean", "null" ] } } }, "total": { "type": "object", "required": [ "amount", "currency" ], "properties": { "amount": { "type": [ "string", "null" ] }, "currency": { "type": [ "string", "null" ] } } }, "status": { "type": "object", "required": [ "financial", "fulfillment", "cancelled_at", "paid_at", "flagged_as_fraud", "fraud_check_completed", "marked_fulfilled_at", "delivery_conditions_met" ], "properties": { "financial": { "type": [ "string", "null" ] }, "fulfillment": { "type": [ "string", "null" ] }, "cancelled_at": {}, "paid_at": { "type": [ "string", "null" ] }, "flagged_as_fraud": { "type": [ "boolean", "null" ] }, "fraud_check_completed": { "type": [ "boolean", "null" ] }, "marked_fulfilled_at": {}, "delivery_conditions_met": { "type": [ "boolean", "null" ] } } }, "access": { "type": "object", "required": [ "state", "revoked_at", "available_until", "download_reset_at", "downloads_count" ], "properties": { "state": { "type": [ "string", "null" ] }, "revoked_at": {}, "available_until": {}, "download_reset_at": { "type": [ "string", "null" ] }, "downloads_count": { "type": [ "integer", "null" ] } } }, "delivery": { "type": "object", "required": [ "email_sent_at", "delivery_failed_at", "download_page_url", "source" ], "properties": { "email_sent_at": { "type": [ "string", "null" ] }, "delivery_failed_at": {}, "download_page_url": { "type": [ "string", "null" ] }, "source": { "type": [ "string", "null" ] } } }, "line_items": { "type": "array", "items": { "type": "object", "required": [ "id", "digital_product_id", "title", "sku", "quantity", "shopify_line_item_id", "shopify_product_id", "shopify_variant_id", "attached_to_this_order_only", "access", "preorder", "files" ], "properties": { "id": { "type": [ "string", "null" ] }, "digital_product_id": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "sku": { "type": [ "string", "null" ] }, "quantity": { "type": [ "integer", "null" ] }, "shopify_line_item_id": { "type": [ "string", "null" ] }, "shopify_product_id": { "type": [ "string", "null" ] }, "shopify_variant_id": { "type": [ "string", "null" ] }, "attached_to_this_order_only": { "type": [ "boolean", "null" ] }, "access": { "type": "object", "required": [ "revoked", "revoked_at" ], "properties": { "revoked": { "type": [ "boolean", "null" ] }, "revoked_at": {} } }, "preorder": { "type": "object", "required": [ "enabled", "launch_at", "released", "message" ], "properties": { "enabled": { "type": [ "boolean", "null" ] }, "launch_at": {}, "released": { "type": [ "boolean", "null" ] }, "message": {} } }, "files": { "type": "array", "items": { "type": "object", "required": [ "id", "asset", "download_count", "watermark", "licence_keys" ], "properties": { "id": {}, "asset": { "type": "object", "required": [ "id", "name", "type" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] } } }, "download_count": { "type": [ "integer", "null" ] }, "watermark": { "type": "object", "required": [ "enabled", "status" ], "properties": { "enabled": { "type": [ "boolean", "null" ] }, "status": { "type": [ "string", "null" ] } } }, "licence_keys": { "type": "array" } } } } } } }, "eu_withdrawal": { "type": "object", "required": [ "consent_required", "consented_at", "consent_text" ], "properties": { "consent_required": { "type": [ "boolean", "null" ] }, "consented_at": {}, "consent_text": {} } }, "shopify_tags": { "type": "array" }, "imported_at": {}, "deleted_at": {}, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } } }, "example": { "id": "3e84eb8d-e1d9-4e92-a4b2-a419c7f1122f", "shopify_order_id": "gid://shopify/Order/7555375595815", "name": "#1077", "confirmation_number": "H5CZG3GZX", "ordered_at": "2026-10-26T14:19:15Z", "customer": { "id": "b797db3a-cbc3-4643-804f-adf34c7f08d7", "shopify_customer_id": "gid://shopify/Customer/9026290417959", "email": "shopper@example.com", "phone": null, "first_name": "Jane", "last_name": "Doe", "country_code": null, "locale": null, "unsubscribed": false }, "total": { "amount": "1142.89", "currency": "INR" }, "status": { "financial": "paid", "fulfillment": "unfulfilled", "cancelled_at": null, "paid_at": "2026-10-30T21:48:16Z", "flagged_as_fraud": false, "fraud_check_completed": false, "marked_fulfilled_at": null, "delivery_conditions_met": false }, "access": { "state": "active", "revoked_at": null, "available_until": null, "download_reset_at": "2026-10-30T22:19:10Z", "downloads_count": 0 }, "delivery": { "email_sent_at": "2026-10-30T22:34:30Z", "delivery_failed_at": null, "download_page_url": "https://example-store.myshopify.com/apps/filemonk/orders/3e84eb8d-e1d9-4e92-a4b2-a419c7f1122f", "source": "webhook" }, "line_items": [ { "id": "5956bb41-dc65-45d5-b7d7-25f570598468", "digital_product_id": "7ea3c05d-6f29-42b6-b24f-43260caeaa32", "title": "Watercolour Course", "sku": "b0f5fbd0-f231-470f-b3d1-a392e3136a50", "quantity": 2, "shopify_line_item_id": "gid://shopify/LineItem/18329329434919", "shopify_product_id": "gid://shopify/Product/9642107044135", "shopify_variant_id": "gid://shopify/ProductVariant/49417714893095", "attached_to_this_order_only": false, "access": { "revoked": false, "revoked_at": null }, "preorder": { "enabled": false, "launch_at": null, "released": true, "message": null }, "files": [ { "id": null, "asset": { "id": "7ea42f2a-6dbe-459c-b8a4-27b0eb823e52", "name": "price-list.csv", "type": "file" }, "download_count": 0, "watermark": { "enabled": false, "status": "not_required" }, "licence_keys": [] }, { "id": "66e2751c-9812-422c-864d-f8ce6a95c605", "asset": { "id": "96fbe30b-c819-4cb8-9666-814c0c8853f1", "name": "Beginner's Guide.pdf", "type": "file" }, "download_count": 0, "watermark": { "enabled": true, "status": "ready" }, "licence_keys": [] } ] } ], "eu_withdrawal": { "consent_required": false, "consented_at": null, "consent_text": null }, "shopify_tags": [], "imported_at": null, "deleted_at": null, "created_at": "2026-10-26T14:19:29Z", "updated_at": "2026-10-30T22:19:10Z" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "remove custom file from order", "detach file", "take a bonus file off this order" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "asset_ids": { "type": "array", "items": { "type": "string" } }, "confirm": {} }, "required": [ "asset_ids" ] }, "example": { "asset_ids": [ "e2b7727e-45ad-42b7-b842-cc4615205b10" ] } } } } } }, "/orders/{id}/fulfil": { "post": { "operationId": "post_orders_id_fulfil", "summary": "Fulfil", "description": "Mark the order's digital line items fulfilled in Shopify now, as the order page's Mark fulfilled does, whether or not automatic fulfilment is on in settings.\n\n**Note:** Calls Shopify. 409 when Shopify has nothing fulfillable yet (unpaid, on hold, closed); 502 when the fulfilment call fails.", "tags": [ "Orders" ], "responses": { "200": { "description": "Success — the write completed; the body is the updated resource.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "shopify_order_id", "name", "confirmation_number", "ordered_at", "customer", "total", "status", "access", "delivery", "line_items", "eu_withdrawal", "shopify_tags", "imported_at", "deleted_at", "created_at", "updated_at" ], "properties": { "id": { "type": [ "string", "null" ] }, "shopify_order_id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "confirmation_number": { "type": [ "string", "null" ] }, "ordered_at": { "type": [ "string", "null" ] }, "customer": { "type": "object", "required": [ "id", "shopify_customer_id", "email", "phone", "first_name", "last_name", "country_code", "locale", "unsubscribed" ], "properties": { "id": { "type": [ "string", "null" ] }, "shopify_customer_id": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "phone": {}, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "country_code": {}, "locale": {}, "unsubscribed": { "type": [ "boolean", "null" ] } } }, "total": { "type": "object", "required": [ "amount", "currency" ], "properties": { "amount": { "type": [ "string", "null" ] }, "currency": { "type": [ "string", "null" ] } } }, "status": { "type": "object", "required": [ "financial", "fulfillment", "cancelled_at", "paid_at", "flagged_as_fraud", "fraud_check_completed", "marked_fulfilled_at", "delivery_conditions_met" ], "properties": { "financial": { "type": [ "string", "null" ] }, "fulfillment": { "type": [ "string", "null" ] }, "cancelled_at": {}, "paid_at": { "type": [ "string", "null" ] }, "flagged_as_fraud": { "type": [ "boolean", "null" ] }, "fraud_check_completed": { "type": [ "boolean", "null" ] }, "marked_fulfilled_at": {}, "delivery_conditions_met": { "type": [ "boolean", "null" ] } } }, "access": { "type": "object", "required": [ "state", "revoked_at", "available_until", "download_reset_at", "downloads_count" ], "properties": { "state": { "type": [ "string", "null" ] }, "revoked_at": {}, "available_until": {}, "download_reset_at": { "type": [ "string", "null" ] }, "downloads_count": { "type": [ "integer", "null" ] } } }, "delivery": { "type": "object", "required": [ "email_sent_at", "delivery_failed_at", "download_page_url", "source" ], "properties": { "email_sent_at": { "type": [ "string", "null" ] }, "delivery_failed_at": {}, "download_page_url": { "type": [ "string", "null" ] }, "source": { "type": [ "string", "null" ] } } }, "line_items": { "type": "array", "items": { "type": "object", "required": [ "id", "digital_product_id", "title", "sku", "quantity", "shopify_line_item_id", "shopify_product_id", "shopify_variant_id", "attached_to_this_order_only", "access", "preorder", "files" ], "properties": { "id": { "type": [ "string", "null" ] }, "digital_product_id": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "sku": { "type": [ "string", "null" ] }, "quantity": { "type": [ "integer", "null" ] }, "shopify_line_item_id": { "type": [ "string", "null" ] }, "shopify_product_id": { "type": [ "string", "null" ] }, "shopify_variant_id": { "type": [ "string", "null" ] }, "attached_to_this_order_only": { "type": [ "boolean", "null" ] }, "access": { "type": "object", "required": [ "revoked", "revoked_at" ], "properties": { "revoked": { "type": [ "boolean", "null" ] }, "revoked_at": {} } }, "preorder": { "type": "object", "required": [ "enabled", "launch_at", "released", "message" ], "properties": { "enabled": { "type": [ "boolean", "null" ] }, "launch_at": {}, "released": { "type": [ "boolean", "null" ] }, "message": {} } }, "files": { "type": "array", "items": { "type": "object", "required": [ "id", "asset", "download_count", "watermark", "licence_keys" ], "properties": { "id": {}, "asset": { "type": "object", "required": [ "id", "name", "type" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] } } }, "download_count": { "type": [ "integer", "null" ] }, "watermark": { "type": "object", "required": [ "enabled", "status" ], "properties": { "enabled": { "type": [ "boolean", "null" ] }, "status": { "type": [ "string", "null" ] } } }, "licence_keys": { "type": "array" } } } } } } }, "eu_withdrawal": { "type": "object", "required": [ "consent_required", "consented_at", "consent_text" ], "properties": { "consent_required": { "type": [ "boolean", "null" ] }, "consented_at": {}, "consent_text": {} } }, "shopify_tags": { "type": "array" }, "imported_at": {}, "deleted_at": {}, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } } }, "example": { "id": "3e84eb8d-e1d9-4e92-a4b2-a419c7f1122f", "shopify_order_id": "gid://shopify/Order/7555375595815", "name": "#1077", "confirmation_number": "H5CZG3GZX", "ordered_at": "2026-10-26T14:19:15Z", "customer": { "id": "b797db3a-cbc3-4643-804f-adf34c7f08d7", "shopify_customer_id": "gid://shopify/Customer/9026290417959", "email": "shopper@example.com", "phone": null, "first_name": "Jane", "last_name": "Doe", "country_code": null, "locale": null, "unsubscribed": false }, "total": { "amount": "1142.89", "currency": "INR" }, "status": { "financial": "paid", "fulfillment": "unfulfilled", "cancelled_at": null, "paid_at": "2026-10-30T21:48:16Z", "flagged_as_fraud": false, "fraud_check_completed": false, "marked_fulfilled_at": null, "delivery_conditions_met": false }, "access": { "state": "active", "revoked_at": null, "available_until": null, "download_reset_at": "2026-10-30T22:19:10Z", "downloads_count": 0 }, "delivery": { "email_sent_at": "2026-10-30T22:34:30Z", "delivery_failed_at": null, "download_page_url": "https://example-store.myshopify.com/apps/filemonk/orders/3e84eb8d-e1d9-4e92-a4b2-a419c7f1122f", "source": "webhook" }, "line_items": [ { "id": "5956bb41-dc65-45d5-b7d7-25f570598468", "digital_product_id": "7ea3c05d-6f29-42b6-b24f-43260caeaa32", "title": "Watercolour Course", "sku": "b0f5fbd0-f231-470f-b3d1-a392e3136a50", "quantity": 2, "shopify_line_item_id": "gid://shopify/LineItem/18329329434919", "shopify_product_id": "gid://shopify/Product/9642107044135", "shopify_variant_id": "gid://shopify/ProductVariant/49417714893095", "attached_to_this_order_only": false, "access": { "revoked": false, "revoked_at": null }, "preorder": { "enabled": false, "launch_at": null, "released": true, "message": null }, "files": [ { "id": null, "asset": { "id": "7ea42f2a-6dbe-459c-b8a4-27b0eb823e52", "name": "price-list.csv", "type": "file" }, "download_count": 0, "watermark": { "enabled": false, "status": "not_required" }, "licence_keys": [] }, { "id": "66e2751c-9812-422c-864d-f8ce6a95c605", "asset": { "id": "96fbe30b-c819-4cb8-9666-814c0c8853f1", "name": "Beginner's Guide.pdf", "type": "file" }, "download_count": 0, "watermark": { "enabled": true, "status": "ready" }, "licence_keys": [] } ] } ], "eu_withdrawal": { "consent_required": false, "consented_at": null, "consent_text": null }, "shopify_tags": [], "imported_at": null, "deleted_at": null, "created_at": "2026-10-26T14:19:29Z", "updated_at": "2026-10-30T22:19:10Z" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/BadGateway" } }, "x-aliases": [ "mark fulfilled", "fulfil the digital items", "fulfill order in shopify", "close out the order" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/orders/{id}/licences/{licence_id}": { "put": { "operationId": "put_orders_id_licences_licence_id", "summary": "Licences", "description": "Swap the licence key on the order, as the order page's Reassign does: the current key goes back to the pool and key (an unassigned key of this shop) takes its place. Without key the row is left open for the automatic assigner.", "tags": [ "Orders" ], "responses": { "200": { "description": "Success — the write completed; the body is the updated resource.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "shopify_order_id", "name", "confirmation_number", "ordered_at", "customer", "total", "status", "access", "delivery", "line_items", "eu_withdrawal", "shopify_tags", "imported_at", "deleted_at", "created_at", "updated_at" ], "properties": { "id": { "type": [ "string", "null" ] }, "shopify_order_id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "confirmation_number": { "type": [ "string", "null" ] }, "ordered_at": { "type": [ "string", "null" ] }, "customer": { "type": "object", "required": [ "id", "shopify_customer_id", "email", "phone", "first_name", "last_name", "country_code", "locale", "unsubscribed" ], "properties": { "id": { "type": [ "string", "null" ] }, "shopify_customer_id": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "phone": {}, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "country_code": {}, "locale": {}, "unsubscribed": { "type": [ "boolean", "null" ] } } }, "total": { "type": "object", "required": [ "amount", "currency" ], "properties": { "amount": { "type": [ "string", "null" ] }, "currency": { "type": [ "string", "null" ] } } }, "status": { "type": "object", "required": [ "financial", "fulfillment", "cancelled_at", "paid_at", "flagged_as_fraud", "fraud_check_completed", "marked_fulfilled_at", "delivery_conditions_met" ], "properties": { "financial": { "type": [ "string", "null" ] }, "fulfillment": { "type": [ "string", "null" ] }, "cancelled_at": {}, "paid_at": { "type": [ "string", "null" ] }, "flagged_as_fraud": { "type": [ "boolean", "null" ] }, "fraud_check_completed": { "type": [ "boolean", "null" ] }, "marked_fulfilled_at": {}, "delivery_conditions_met": { "type": [ "boolean", "null" ] } } }, "access": { "type": "object", "required": [ "state", "revoked_at", "available_until", "download_reset_at", "downloads_count" ], "properties": { "state": { "type": [ "string", "null" ] }, "revoked_at": {}, "available_until": {}, "download_reset_at": { "type": [ "string", "null" ] }, "downloads_count": { "type": [ "integer", "null" ] } } }, "delivery": { "type": "object", "required": [ "email_sent_at", "delivery_failed_at", "download_page_url", "source" ], "properties": { "email_sent_at": { "type": [ "string", "null" ] }, "delivery_failed_at": {}, "download_page_url": { "type": [ "string", "null" ] }, "source": { "type": [ "string", "null" ] } } }, "line_items": { "type": "array", "items": { "type": "object", "required": [ "id", "digital_product_id", "title", "sku", "quantity", "shopify_line_item_id", "shopify_product_id", "shopify_variant_id", "attached_to_this_order_only", "access", "preorder", "files" ], "properties": { "id": { "type": [ "string", "null" ] }, "digital_product_id": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "sku": { "type": [ "string", "null" ] }, "quantity": { "type": [ "integer", "null" ] }, "shopify_line_item_id": { "type": [ "string", "null" ] }, "shopify_product_id": { "type": [ "string", "null" ] }, "shopify_variant_id": { "type": [ "string", "null" ] }, "attached_to_this_order_only": { "type": [ "boolean", "null" ] }, "access": { "type": "object", "required": [ "revoked", "revoked_at" ], "properties": { "revoked": { "type": [ "boolean", "null" ] }, "revoked_at": {} } }, "preorder": { "type": "object", "required": [ "enabled", "launch_at", "released", "message" ], "properties": { "enabled": { "type": [ "boolean", "null" ] }, "launch_at": {}, "released": { "type": [ "boolean", "null" ] }, "message": {} } }, "files": { "type": "array", "items": { "type": "object", "required": [ "id", "asset", "download_count", "watermark", "licence_keys" ], "properties": { "id": {}, "asset": { "type": "object", "required": [ "id", "name", "type" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] } } }, "download_count": { "type": [ "integer", "null" ] }, "watermark": { "type": "object", "required": [ "enabled", "status" ], "properties": { "enabled": { "type": [ "boolean", "null" ] }, "status": { "type": [ "string", "null" ] } } }, "licence_keys": { "type": "array" } } } } } } }, "eu_withdrawal": { "type": "object", "required": [ "consent_required", "consented_at", "consent_text" ], "properties": { "consent_required": { "type": [ "boolean", "null" ] }, "consented_at": {}, "consent_text": {} } }, "shopify_tags": { "type": "array" }, "imported_at": {}, "deleted_at": {}, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } } }, "example": { "id": "3e84eb8d-e1d9-4e92-a4b2-a419c7f1122f", "shopify_order_id": "gid://shopify/Order/7555375595815", "name": "#1077", "confirmation_number": "H5CZG3GZX", "ordered_at": "2026-10-26T14:19:15Z", "customer": { "id": "b797db3a-cbc3-4643-804f-adf34c7f08d7", "shopify_customer_id": "gid://shopify/Customer/9026290417959", "email": "shopper@example.com", "phone": null, "first_name": "Jane", "last_name": "Doe", "country_code": null, "locale": null, "unsubscribed": false }, "total": { "amount": "1142.89", "currency": "INR" }, "status": { "financial": "paid", "fulfillment": "unfulfilled", "cancelled_at": null, "paid_at": "2026-10-30T21:48:16Z", "flagged_as_fraud": false, "fraud_check_completed": false, "marked_fulfilled_at": null, "delivery_conditions_met": false }, "access": { "state": "active", "revoked_at": null, "available_until": null, "download_reset_at": "2026-10-30T22:19:10Z", "downloads_count": 0 }, "delivery": { "email_sent_at": "2026-10-30T22:34:30Z", "delivery_failed_at": null, "download_page_url": "https://example-store.myshopify.com/apps/filemonk/orders/3e84eb8d-e1d9-4e92-a4b2-a419c7f1122f", "source": "webhook" }, "line_items": [ { "id": "5956bb41-dc65-45d5-b7d7-25f570598468", "digital_product_id": "7ea3c05d-6f29-42b6-b24f-43260caeaa32", "title": "Watercolour Course", "sku": "b0f5fbd0-f231-470f-b3d1-a392e3136a50", "quantity": 2, "shopify_line_item_id": "gid://shopify/LineItem/18329329434919", "shopify_product_id": "gid://shopify/Product/9642107044135", "shopify_variant_id": "gid://shopify/ProductVariant/49417714893095", "attached_to_this_order_only": false, "access": { "revoked": false, "revoked_at": null }, "preorder": { "enabled": false, "launch_at": null, "released": true, "message": null }, "files": [ { "id": null, "asset": { "id": "7ea42f2a-6dbe-459c-b8a4-27b0eb823e52", "name": "price-list.csv", "type": "file" }, "download_count": 0, "watermark": { "enabled": false, "status": "not_required" }, "licence_keys": [] }, { "id": "66e2751c-9812-422c-864d-f8ce6a95c605", "asset": { "id": "96fbe30b-c819-4cb8-9666-814c0c8853f1", "name": "Beginner's Guide.pdf", "type": "file" }, "download_count": 0, "watermark": { "enabled": true, "status": "ready" }, "licence_keys": [] } ] } ], "eu_withdrawal": { "consent_required": false, "consented_at": null, "consent_text": null }, "shopify_tags": [], "imported_at": null, "deleted_at": null, "created_at": "2026-10-26T14:19:29Z", "updated_at": "2026-10-30T22:19:10Z" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "reassign licence key", "swap the key", "replace key on order", "give the customer a different key" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "licence_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": {} } }, "example": { "key": "ABCD-EFGH-IJKL-0002" } } } } }, "delete": { "operationId": "delete_orders_id_licences_licence_id", "summary": "Licences", "description": "Take a licence key off the order, as the order page's Unassign does. key_status says what happens to the key: pending returns it to the pool (default), used burns it. The file row is marked so no replacement key is assigned automatically. Destructive: send it first without `confirm`. Nothing changes and the 409 `confirmation_required` says what would. Tell the merchant, ask, and resend with `confirm: true` only after they agree.\n\n**Note:** Every key on the same file row of the order is released together, as the dashboard does. Without confirm: true nothing changes: 409 confirmation_required says which keys would go.", "tags": [ "Orders" ], "responses": { "200": { "description": "Success — the write completed; the body is the updated resource.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "shopify_order_id", "name", "confirmation_number", "ordered_at", "customer", "total", "status", "access", "delivery", "line_items", "eu_withdrawal", "shopify_tags", "imported_at", "deleted_at", "created_at", "updated_at" ], "properties": { "id": { "type": [ "string", "null" ] }, "shopify_order_id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "confirmation_number": { "type": [ "string", "null" ] }, "ordered_at": { "type": [ "string", "null" ] }, "customer": { "type": "object", "required": [ "id", "shopify_customer_id", "email", "phone", "first_name", "last_name", "country_code", "locale", "unsubscribed" ], "properties": { "id": { "type": [ "string", "null" ] }, "shopify_customer_id": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "phone": {}, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "country_code": {}, "locale": {}, "unsubscribed": { "type": [ "boolean", "null" ] } } }, "total": { "type": "object", "required": [ "amount", "currency" ], "properties": { "amount": { "type": [ "string", "null" ] }, "currency": { "type": [ "string", "null" ] } } }, "status": { "type": "object", "required": [ "financial", "fulfillment", "cancelled_at", "paid_at", "flagged_as_fraud", "fraud_check_completed", "marked_fulfilled_at", "delivery_conditions_met" ], "properties": { "financial": { "type": [ "string", "null" ] }, "fulfillment": { "type": [ "string", "null" ] }, "cancelled_at": {}, "paid_at": { "type": [ "string", "null" ] }, "flagged_as_fraud": { "type": [ "boolean", "null" ] }, "fraud_check_completed": { "type": [ "boolean", "null" ] }, "marked_fulfilled_at": {}, "delivery_conditions_met": { "type": [ "boolean", "null" ] } } }, "access": { "type": "object", "required": [ "state", "revoked_at", "available_until", "download_reset_at", "downloads_count" ], "properties": { "state": { "type": [ "string", "null" ] }, "revoked_at": {}, "available_until": {}, "download_reset_at": { "type": [ "string", "null" ] }, "downloads_count": { "type": [ "integer", "null" ] } } }, "delivery": { "type": "object", "required": [ "email_sent_at", "delivery_failed_at", "download_page_url", "source" ], "properties": { "email_sent_at": { "type": [ "string", "null" ] }, "delivery_failed_at": {}, "download_page_url": { "type": [ "string", "null" ] }, "source": { "type": [ "string", "null" ] } } }, "line_items": { "type": "array", "items": { "type": "object", "required": [ "id", "digital_product_id", "title", "sku", "quantity", "shopify_line_item_id", "shopify_product_id", "shopify_variant_id", "attached_to_this_order_only", "access", "preorder", "files" ], "properties": { "id": { "type": [ "string", "null" ] }, "digital_product_id": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "sku": { "type": [ "string", "null" ] }, "quantity": { "type": [ "integer", "null" ] }, "shopify_line_item_id": { "type": [ "string", "null" ] }, "shopify_product_id": { "type": [ "string", "null" ] }, "shopify_variant_id": { "type": [ "string", "null" ] }, "attached_to_this_order_only": { "type": [ "boolean", "null" ] }, "access": { "type": "object", "required": [ "revoked", "revoked_at" ], "properties": { "revoked": { "type": [ "boolean", "null" ] }, "revoked_at": {} } }, "preorder": { "type": "object", "required": [ "enabled", "launch_at", "released", "message" ], "properties": { "enabled": { "type": [ "boolean", "null" ] }, "launch_at": {}, "released": { "type": [ "boolean", "null" ] }, "message": {} } }, "files": { "type": "array", "items": { "type": "object", "required": [ "id", "asset", "download_count", "watermark", "licence_keys" ], "properties": { "id": {}, "asset": { "type": "object", "required": [ "id", "name", "type" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] } } }, "download_count": { "type": [ "integer", "null" ] }, "watermark": { "type": "object", "required": [ "enabled", "status" ], "properties": { "enabled": { "type": [ "boolean", "null" ] }, "status": { "type": [ "string", "null" ] } } }, "licence_keys": { "type": "array" } } } } } } }, "eu_withdrawal": { "type": "object", "required": [ "consent_required", "consented_at", "consent_text" ], "properties": { "consent_required": { "type": [ "boolean", "null" ] }, "consented_at": {}, "consent_text": {} } }, "shopify_tags": { "type": "array" }, "imported_at": {}, "deleted_at": {}, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } } }, "example": { "id": "3e84eb8d-e1d9-4e92-a4b2-a419c7f1122f", "shopify_order_id": "gid://shopify/Order/7555375595815", "name": "#1077", "confirmation_number": "H5CZG3GZX", "ordered_at": "2026-10-26T14:19:15Z", "customer": { "id": "b797db3a-cbc3-4643-804f-adf34c7f08d7", "shopify_customer_id": "gid://shopify/Customer/9026290417959", "email": "shopper@example.com", "phone": null, "first_name": "Jane", "last_name": "Doe", "country_code": null, "locale": null, "unsubscribed": false }, "total": { "amount": "1142.89", "currency": "INR" }, "status": { "financial": "paid", "fulfillment": "unfulfilled", "cancelled_at": null, "paid_at": "2026-10-30T21:48:16Z", "flagged_as_fraud": false, "fraud_check_completed": false, "marked_fulfilled_at": null, "delivery_conditions_met": false }, "access": { "state": "active", "revoked_at": null, "available_until": null, "download_reset_at": "2026-10-30T22:19:10Z", "downloads_count": 0 }, "delivery": { "email_sent_at": "2026-10-30T22:34:30Z", "delivery_failed_at": null, "download_page_url": "https://example-store.myshopify.com/apps/filemonk/orders/3e84eb8d-e1d9-4e92-a4b2-a419c7f1122f", "source": "webhook" }, "line_items": [ { "id": "5956bb41-dc65-45d5-b7d7-25f570598468", "digital_product_id": "7ea3c05d-6f29-42b6-b24f-43260caeaa32", "title": "Watercolour Course", "sku": "b0f5fbd0-f231-470f-b3d1-a392e3136a50", "quantity": 2, "shopify_line_item_id": "gid://shopify/LineItem/18329329434919", "shopify_product_id": "gid://shopify/Product/9642107044135", "shopify_variant_id": "gid://shopify/ProductVariant/49417714893095", "attached_to_this_order_only": false, "access": { "revoked": false, "revoked_at": null }, "preorder": { "enabled": false, "launch_at": null, "released": true, "message": null }, "files": [ { "id": null, "asset": { "id": "7ea42f2a-6dbe-459c-b8a4-27b0eb823e52", "name": "price-list.csv", "type": "file" }, "download_count": 0, "watermark": { "enabled": false, "status": "not_required" }, "licence_keys": [] }, { "id": "66e2751c-9812-422c-864d-f8ce6a95c605", "asset": { "id": "96fbe30b-c819-4cb8-9666-814c0c8853f1", "name": "Beginner's Guide.pdf", "type": "file" }, "download_count": 0, "watermark": { "enabled": true, "status": "ready" }, "licence_keys": [] } ] } ], "eu_withdrawal": { "consent_required": false, "consented_at": null, "consent_text": null }, "shopify_tags": [], "imported_at": null, "deleted_at": null, "created_at": "2026-10-26T14:19:29Z", "updated_at": "2026-10-30T22:19:10Z" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "unassign licence key", "remove key from order", "take back the key", "return key to pool" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "licence_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "key_status", "in": "query", "required": false, "schema": { "type": "string" }, "example": "paid" }, { "name": "confirm", "in": "query", "required": false, "schema": { "type": "string" }, "example": "string" } ] } }, "/orders/{id}/licences/assign": { "post": { "operationId": "post_orders_id_licences_assign", "summary": "Licences Assign", "description": "Place a licence key on this order by hand, as the order page's Assign key does: asset_id names the licence-key file, key a specific unassigned key, tag the pool to draw from (default: the file's own pool, as at checkout: its licence tag, or untagged keys when the file has no tag). send_email true emails the buyer afterwards.\n\n**Note:** Autogenerated-key files mint a new key. 422 when the key is taken or the pool is empty. send_email charges usage and fulfils in Shopify like any send.", "tags": [ "Orders" ], "responses": { "200": { "description": "Success — the write completed; the body is the updated resource.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "shopify_order_id", "name", "confirmation_number", "ordered_at", "customer", "total", "status", "access", "delivery", "line_items", "eu_withdrawal", "shopify_tags", "imported_at", "deleted_at", "created_at", "updated_at", "licence" ], "properties": { "id": { "type": [ "string", "null" ] }, "shopify_order_id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "confirmation_number": { "type": [ "string", "null" ] }, "ordered_at": { "type": [ "string", "null" ] }, "customer": { "type": "object", "required": [ "id", "shopify_customer_id", "email", "phone", "first_name", "last_name", "country_code", "locale", "unsubscribed" ], "properties": { "id": { "type": [ "string", "null" ] }, "shopify_customer_id": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "phone": {}, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "country_code": {}, "locale": {}, "unsubscribed": { "type": [ "boolean", "null" ] } } }, "total": { "type": "object", "required": [ "amount", "currency" ], "properties": { "amount": { "type": [ "string", "null" ] }, "currency": { "type": [ "string", "null" ] } } }, "status": { "type": "object", "required": [ "financial", "fulfillment", "cancelled_at", "paid_at", "flagged_as_fraud", "fraud_check_completed", "marked_fulfilled_at", "delivery_conditions_met" ], "properties": { "financial": { "type": [ "string", "null" ] }, "fulfillment": { "type": [ "string", "null" ] }, "cancelled_at": {}, "paid_at": { "type": [ "string", "null" ] }, "flagged_as_fraud": { "type": [ "boolean", "null" ] }, "fraud_check_completed": { "type": [ "boolean", "null" ] }, "marked_fulfilled_at": {}, "delivery_conditions_met": { "type": [ "boolean", "null" ] } } }, "access": { "type": "object", "required": [ "state", "revoked_at", "available_until", "download_reset_at", "downloads_count" ], "properties": { "state": { "type": [ "string", "null" ] }, "revoked_at": {}, "available_until": {}, "download_reset_at": { "type": [ "string", "null" ] }, "downloads_count": { "type": [ "integer", "null" ] } } }, "delivery": { "type": "object", "required": [ "email_sent_at", "delivery_failed_at", "download_page_url", "source" ], "properties": { "email_sent_at": { "type": [ "string", "null" ] }, "delivery_failed_at": {}, "download_page_url": { "type": [ "string", "null" ] }, "source": { "type": [ "string", "null" ] } } }, "line_items": { "type": "array", "items": { "type": "object", "required": [ "id", "digital_product_id", "title", "sku", "quantity", "shopify_line_item_id", "shopify_product_id", "shopify_variant_id", "attached_to_this_order_only", "access", "preorder", "files" ], "properties": { "id": { "type": [ "string", "null" ] }, "digital_product_id": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "sku": { "type": [ "string", "null" ] }, "quantity": { "type": [ "integer", "null" ] }, "shopify_line_item_id": { "type": [ "string", "null" ] }, "shopify_product_id": { "type": [ "string", "null" ] }, "shopify_variant_id": { "type": [ "string", "null" ] }, "attached_to_this_order_only": { "type": [ "boolean", "null" ] }, "access": { "type": "object", "required": [ "revoked", "revoked_at" ], "properties": { "revoked": { "type": [ "boolean", "null" ] }, "revoked_at": {} } }, "preorder": { "type": "object", "required": [ "enabled", "launch_at", "released", "message" ], "properties": { "enabled": { "type": [ "boolean", "null" ] }, "launch_at": {}, "released": { "type": [ "boolean", "null" ] }, "message": {} } }, "files": { "type": "array", "items": { "type": "object", "required": [ "id", "asset", "download_count", "watermark", "licence_keys" ], "properties": { "id": {}, "asset": { "type": "object", "required": [ "id", "name", "type" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] } } }, "download_count": { "type": [ "integer", "null" ] }, "watermark": { "type": "object", "required": [ "enabled", "status" ], "properties": { "enabled": { "type": [ "boolean", "null" ] }, "status": { "type": [ "string", "null" ] } } }, "licence_keys": { "type": "array" } } } } } } }, "eu_withdrawal": { "type": "object", "required": [ "consent_required", "consented_at", "consent_text" ], "properties": { "consent_required": { "type": [ "boolean", "null" ] }, "consented_at": {}, "consent_text": {} } }, "shopify_tags": { "type": "array" }, "imported_at": {}, "deleted_at": {}, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] }, "licence": { "type": "object", "required": [ "id", "key", "source", "status", "tags", "assigned_at", "order", "file", "created_at" ], "properties": { "id": { "type": [ "string", "null" ] }, "key": { "type": [ "string", "null" ] }, "source": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": [ "string", "null" ] } }, "assigned_at": { "type": [ "string", "null" ] }, "order": {}, "file": {}, "created_at": { "type": [ "string", "null" ] } } } } }, "example": { "id": "3e84eb8d-e1d9-4e92-a4b2-a419c7f1122f", "shopify_order_id": "gid://shopify/Order/7555375595815", "name": "#1077", "confirmation_number": "H5CZG3GZX", "ordered_at": "2026-10-26T14:19:15Z", "customer": { "id": "b797db3a-cbc3-4643-804f-adf34c7f08d7", "shopify_customer_id": "gid://shopify/Customer/9026290417959", "email": "shopper@example.com", "phone": null, "first_name": "Jane", "last_name": "Doe", "country_code": null, "locale": null, "unsubscribed": false }, "total": { "amount": "1142.89", "currency": "INR" }, "status": { "financial": "paid", "fulfillment": "unfulfilled", "cancelled_at": null, "paid_at": "2026-10-30T21:48:16Z", "flagged_as_fraud": false, "fraud_check_completed": false, "marked_fulfilled_at": null, "delivery_conditions_met": false }, "access": { "state": "active", "revoked_at": null, "available_until": null, "download_reset_at": "2026-10-30T22:19:10Z", "downloads_count": 0 }, "delivery": { "email_sent_at": "2026-10-30T22:34:30Z", "delivery_failed_at": null, "download_page_url": "https://example-store.myshopify.com/apps/filemonk/orders/3e84eb8d-e1d9-4e92-a4b2-a419c7f1122f", "source": "webhook" }, "line_items": [ { "id": "5956bb41-dc65-45d5-b7d7-25f570598468", "digital_product_id": "7ea3c05d-6f29-42b6-b24f-43260caeaa32", "title": "Watercolour Course", "sku": "b0f5fbd0-f231-470f-b3d1-a392e3136a50", "quantity": 2, "shopify_line_item_id": "gid://shopify/LineItem/18329329434919", "shopify_product_id": "gid://shopify/Product/9642107044135", "shopify_variant_id": "gid://shopify/ProductVariant/49417714893095", "attached_to_this_order_only": false, "access": { "revoked": false, "revoked_at": null }, "preorder": { "enabled": false, "launch_at": null, "released": true, "message": null }, "files": [ { "id": null, "asset": { "id": "7ea42f2a-6dbe-459c-b8a4-27b0eb823e52", "name": "price-list.csv", "type": "file" }, "download_count": 0, "watermark": { "enabled": false, "status": "not_required" }, "licence_keys": [] }, { "id": "66e2751c-9812-422c-864d-f8ce6a95c605", "asset": { "id": "96fbe30b-c819-4cb8-9666-814c0c8853f1", "name": "Beginner's Guide.pdf", "type": "file" }, "download_count": 0, "watermark": { "enabled": true, "status": "ready" }, "licence_keys": [] } ] } ], "eu_withdrawal": { "consent_required": false, "consented_at": null, "consent_text": null }, "shopify_tags": [], "imported_at": null, "deleted_at": null, "created_at": "2026-10-26T14:19:29Z", "updated_at": "2026-10-30T22:19:10Z", "licence": { "id": "bcc87d33-c87e-4f39-9cd2-e43250ebc1ed", "key": "ABCD-EFGH-0005", "source": "uploaded", "status": "assigned", "tags": [ "ebook-2026" ], "assigned_at": "2026-10-30T23:10:00Z", "order": null, "file": null, "created_at": "2026-10-30T16:48:56Z" } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "assign licence key", "give this order a key", "add a license key to the order", "customer needs a key", "assign key from tag" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "asset_id": {}, "key": {}, "tag": {}, "send_email": {} }, "required": [ "asset_id" ] }, "example": { "asset_id": "e2b7727e-45ad-42b7-b842-cc4615205b10", "tag": "ebook-2026", "send_email": true } } } } } }, "/orders/{id}/line_items/{line_item_id}": { "patch": { "operationId": "patch_orders_id_line_items_line_item_id", "summary": "Line Items", "description": "Revoke or restore access to one digital product on the order (access.revoked), as the order page's per-product toggle does. :line_item_id is line_items[].id from GET /orders/:id. Restoring one product on a revoked order turns the order back on with its other products kept off.", "tags": [ "Orders" ], "responses": { "200": { "description": "Success — the write completed; the body is the updated resource.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "shopify_order_id", "name", "confirmation_number", "ordered_at", "customer", "total", "status", "access", "delivery", "line_items", "eu_withdrawal", "shopify_tags", "imported_at", "deleted_at", "created_at", "updated_at" ], "properties": { "id": { "type": [ "string", "null" ] }, "shopify_order_id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "confirmation_number": { "type": [ "string", "null" ] }, "ordered_at": { "type": [ "string", "null" ] }, "customer": { "type": "object", "required": [ "id", "shopify_customer_id", "email", "phone", "first_name", "last_name", "country_code", "locale", "unsubscribed" ], "properties": { "id": { "type": [ "string", "null" ] }, "shopify_customer_id": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "phone": {}, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "country_code": {}, "locale": {}, "unsubscribed": { "type": [ "boolean", "null" ] } } }, "total": { "type": "object", "required": [ "amount", "currency" ], "properties": { "amount": { "type": [ "string", "null" ] }, "currency": { "type": [ "string", "null" ] } } }, "status": { "type": "object", "required": [ "financial", "fulfillment", "cancelled_at", "paid_at", "flagged_as_fraud", "fraud_check_completed", "marked_fulfilled_at", "delivery_conditions_met" ], "properties": { "financial": { "type": [ "string", "null" ] }, "fulfillment": { "type": [ "string", "null" ] }, "cancelled_at": {}, "paid_at": { "type": [ "string", "null" ] }, "flagged_as_fraud": { "type": [ "boolean", "null" ] }, "fraud_check_completed": { "type": [ "boolean", "null" ] }, "marked_fulfilled_at": {}, "delivery_conditions_met": { "type": [ "boolean", "null" ] } } }, "access": { "type": "object", "required": [ "state", "revoked_at", "available_until", "download_reset_at", "downloads_count" ], "properties": { "state": { "type": [ "string", "null" ] }, "revoked_at": {}, "available_until": {}, "download_reset_at": { "type": [ "string", "null" ] }, "downloads_count": { "type": [ "integer", "null" ] } } }, "delivery": { "type": "object", "required": [ "email_sent_at", "delivery_failed_at", "download_page_url", "source" ], "properties": { "email_sent_at": { "type": [ "string", "null" ] }, "delivery_failed_at": {}, "download_page_url": { "type": [ "string", "null" ] }, "source": { "type": [ "string", "null" ] } } }, "line_items": { "type": "array", "items": { "type": "object", "required": [ "id", "digital_product_id", "title", "sku", "quantity", "shopify_line_item_id", "shopify_product_id", "shopify_variant_id", "attached_to_this_order_only", "access", "preorder", "files" ], "properties": { "id": { "type": [ "string", "null" ] }, "digital_product_id": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "sku": { "type": [ "string", "null" ] }, "quantity": { "type": [ "integer", "null" ] }, "shopify_line_item_id": { "type": [ "string", "null" ] }, "shopify_product_id": { "type": [ "string", "null" ] }, "shopify_variant_id": { "type": [ "string", "null" ] }, "attached_to_this_order_only": { "type": [ "boolean", "null" ] }, "access": { "type": "object", "required": [ "revoked", "revoked_at" ], "properties": { "revoked": { "type": [ "boolean", "null" ] }, "revoked_at": {} } }, "preorder": { "type": "object", "required": [ "enabled", "launch_at", "released", "message" ], "properties": { "enabled": { "type": [ "boolean", "null" ] }, "launch_at": {}, "released": { "type": [ "boolean", "null" ] }, "message": {} } }, "files": { "type": "array", "items": { "type": "object", "required": [ "id", "asset", "download_count", "watermark", "licence_keys" ], "properties": { "id": {}, "asset": { "type": "object", "required": [ "id", "name", "type" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] } } }, "download_count": { "type": [ "integer", "null" ] }, "watermark": { "type": "object", "required": [ "enabled", "status" ], "properties": { "enabled": { "type": [ "boolean", "null" ] }, "status": { "type": [ "string", "null" ] } } }, "licence_keys": { "type": "array" } } } } } } }, "eu_withdrawal": { "type": "object", "required": [ "consent_required", "consented_at", "consent_text" ], "properties": { "consent_required": { "type": [ "boolean", "null" ] }, "consented_at": {}, "consent_text": {} } }, "shopify_tags": { "type": "array" }, "imported_at": {}, "deleted_at": {}, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } } }, "example": { "id": "3e84eb8d-e1d9-4e92-a4b2-a419c7f1122f", "shopify_order_id": "gid://shopify/Order/7555375595815", "name": "#1077", "confirmation_number": "H5CZG3GZX", "ordered_at": "2026-10-26T14:19:15Z", "customer": { "id": "b797db3a-cbc3-4643-804f-adf34c7f08d7", "shopify_customer_id": "gid://shopify/Customer/9026290417959", "email": "shopper@example.com", "phone": null, "first_name": "Jane", "last_name": "Doe", "country_code": null, "locale": null, "unsubscribed": false }, "total": { "amount": "1142.89", "currency": "INR" }, "status": { "financial": "paid", "fulfillment": "unfulfilled", "cancelled_at": null, "paid_at": "2026-10-30T21:48:16Z", "flagged_as_fraud": false, "fraud_check_completed": false, "marked_fulfilled_at": null, "delivery_conditions_met": false }, "access": { "state": "active", "revoked_at": null, "available_until": null, "download_reset_at": "2026-10-30T22:19:10Z", "downloads_count": 0 }, "delivery": { "email_sent_at": "2026-10-30T22:34:30Z", "delivery_failed_at": null, "download_page_url": "https://example-store.myshopify.com/apps/filemonk/orders/3e84eb8d-e1d9-4e92-a4b2-a419c7f1122f", "source": "webhook" }, "line_items": [ { "id": "5956bb41-dc65-45d5-b7d7-25f570598468", "digital_product_id": "7ea3c05d-6f29-42b6-b24f-43260caeaa32", "title": "Watercolour Course", "sku": "b0f5fbd0-f231-470f-b3d1-a392e3136a50", "quantity": 2, "shopify_line_item_id": "gid://shopify/LineItem/18329329434919", "shopify_product_id": "gid://shopify/Product/9642107044135", "shopify_variant_id": "gid://shopify/ProductVariant/49417714893095", "attached_to_this_order_only": false, "access": { "revoked": false, "revoked_at": null }, "preorder": { "enabled": false, "launch_at": null, "released": true, "message": null }, "files": [ { "id": null, "asset": { "id": "7ea42f2a-6dbe-459c-b8a4-27b0eb823e52", "name": "price-list.csv", "type": "file" }, "download_count": 0, "watermark": { "enabled": false, "status": "not_required" }, "licence_keys": [] }, { "id": "66e2751c-9812-422c-864d-f8ce6a95c605", "asset": { "id": "96fbe30b-c819-4cb8-9666-814c0c8853f1", "name": "Beginner's Guide.pdf", "type": "file" }, "download_count": 0, "watermark": { "enabled": true, "status": "ready" }, "licence_keys": [] } ] } ], "eu_withdrawal": { "consent_required": false, "consented_at": null, "consent_text": null }, "shopify_tags": [], "imported_at": null, "deleted_at": null, "created_at": "2026-10-26T14:19:29Z", "updated_at": "2026-10-30T22:19:10Z" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "revoke access to one product", "restore one line item", "block a file on this order", "re-enable one product for the customer" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "line_item_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "access": {} } }, "example": { "access": { "revoked": true } } } } } } }, "/orders/{id}/reset_downloads": { "post": { "operationId": "post_orders_id_reset_downloads", "summary": "Reset Downloads", "description": "Zero the download counters so the buyer can download again: every file on the order, or one file when file_id (line_items[].files[].id from GET /orders/:id) is given. Resetting the whole order also restarts the day limit from now.", "tags": [ "Orders" ], "responses": { "200": { "description": "Success — the write completed; the body is the updated resource.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "shopify_order_id", "name", "confirmation_number", "ordered_at", "customer", "total", "status", "access", "delivery", "line_items", "eu_withdrawal", "shopify_tags", "imported_at", "deleted_at", "created_at", "updated_at" ], "properties": { "id": { "type": [ "string", "null" ] }, "shopify_order_id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "confirmation_number": { "type": [ "string", "null" ] }, "ordered_at": { "type": [ "string", "null" ] }, "customer": { "type": "object", "required": [ "id", "shopify_customer_id", "email", "phone", "first_name", "last_name", "country_code", "locale", "unsubscribed" ], "properties": { "id": { "type": [ "string", "null" ] }, "shopify_customer_id": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "phone": {}, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "country_code": {}, "locale": {}, "unsubscribed": { "type": [ "boolean", "null" ] } } }, "total": { "type": "object", "required": [ "amount", "currency" ], "properties": { "amount": { "type": [ "string", "null" ] }, "currency": { "type": [ "string", "null" ] } } }, "status": { "type": "object", "required": [ "financial", "fulfillment", "cancelled_at", "paid_at", "flagged_as_fraud", "fraud_check_completed", "marked_fulfilled_at", "delivery_conditions_met" ], "properties": { "financial": { "type": [ "string", "null" ] }, "fulfillment": { "type": [ "string", "null" ] }, "cancelled_at": {}, "paid_at": { "type": [ "string", "null" ] }, "flagged_as_fraud": { "type": [ "boolean", "null" ] }, "fraud_check_completed": { "type": [ "boolean", "null" ] }, "marked_fulfilled_at": {}, "delivery_conditions_met": { "type": [ "boolean", "null" ] } } }, "access": { "type": "object", "required": [ "state", "revoked_at", "available_until", "download_reset_at", "downloads_count" ], "properties": { "state": { "type": [ "string", "null" ] }, "revoked_at": {}, "available_until": {}, "download_reset_at": { "type": [ "string", "null" ] }, "downloads_count": { "type": [ "integer", "null" ] } } }, "delivery": { "type": "object", "required": [ "email_sent_at", "delivery_failed_at", "download_page_url", "source" ], "properties": { "email_sent_at": { "type": [ "string", "null" ] }, "delivery_failed_at": {}, "download_page_url": { "type": [ "string", "null" ] }, "source": { "type": [ "string", "null" ] } } }, "line_items": { "type": "array", "items": { "type": "object", "required": [ "id", "digital_product_id", "title", "sku", "quantity", "shopify_line_item_id", "shopify_product_id", "shopify_variant_id", "attached_to_this_order_only", "access", "preorder", "files" ], "properties": { "id": { "type": [ "string", "null" ] }, "digital_product_id": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "sku": { "type": [ "string", "null" ] }, "quantity": { "type": [ "integer", "null" ] }, "shopify_line_item_id": { "type": [ "string", "null" ] }, "shopify_product_id": { "type": [ "string", "null" ] }, "shopify_variant_id": { "type": [ "string", "null" ] }, "attached_to_this_order_only": { "type": [ "boolean", "null" ] }, "access": { "type": "object", "required": [ "revoked", "revoked_at" ], "properties": { "revoked": { "type": [ "boolean", "null" ] }, "revoked_at": {} } }, "preorder": { "type": "object", "required": [ "enabled", "launch_at", "released", "message" ], "properties": { "enabled": { "type": [ "boolean", "null" ] }, "launch_at": {}, "released": { "type": [ "boolean", "null" ] }, "message": {} } }, "files": { "type": "array", "items": { "type": "object", "required": [ "id", "asset", "download_count", "watermark", "licence_keys" ], "properties": { "id": {}, "asset": { "type": "object", "required": [ "id", "name", "type" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] } } }, "download_count": { "type": [ "integer", "null" ] }, "watermark": { "type": "object", "required": [ "enabled", "status" ], "properties": { "enabled": { "type": [ "boolean", "null" ] }, "status": { "type": [ "string", "null" ] } } }, "licence_keys": { "type": "array" } } } } } } }, "eu_withdrawal": { "type": "object", "required": [ "consent_required", "consented_at", "consent_text" ], "properties": { "consent_required": { "type": [ "boolean", "null" ] }, "consented_at": {}, "consent_text": {} } }, "shopify_tags": { "type": "array" }, "imported_at": {}, "deleted_at": {}, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } } }, "example": { "id": "3e84eb8d-e1d9-4e92-a4b2-a419c7f1122f", "shopify_order_id": "gid://shopify/Order/7555375595815", "name": "#1077", "confirmation_number": "H5CZG3GZX", "ordered_at": "2026-10-26T14:19:15Z", "customer": { "id": "b797db3a-cbc3-4643-804f-adf34c7f08d7", "shopify_customer_id": "gid://shopify/Customer/9026290417959", "email": "shopper@example.com", "phone": null, "first_name": "Jane", "last_name": "Doe", "country_code": null, "locale": null, "unsubscribed": false }, "total": { "amount": "1142.89", "currency": "INR" }, "status": { "financial": "paid", "fulfillment": "unfulfilled", "cancelled_at": null, "paid_at": "2026-10-30T21:48:16Z", "flagged_as_fraud": false, "fraud_check_completed": false, "marked_fulfilled_at": null, "delivery_conditions_met": false }, "access": { "state": "active", "revoked_at": null, "available_until": null, "download_reset_at": "2026-10-30T22:19:10Z", "downloads_count": 0 }, "delivery": { "email_sent_at": "2026-10-30T22:34:30Z", "delivery_failed_at": null, "download_page_url": "https://example-store.myshopify.com/apps/filemonk/orders/3e84eb8d-e1d9-4e92-a4b2-a419c7f1122f", "source": "webhook" }, "line_items": [ { "id": "5956bb41-dc65-45d5-b7d7-25f570598468", "digital_product_id": "7ea3c05d-6f29-42b6-b24f-43260caeaa32", "title": "Watercolour Course", "sku": "b0f5fbd0-f231-470f-b3d1-a392e3136a50", "quantity": 2, "shopify_line_item_id": "gid://shopify/LineItem/18329329434919", "shopify_product_id": "gid://shopify/Product/9642107044135", "shopify_variant_id": "gid://shopify/ProductVariant/49417714893095", "attached_to_this_order_only": false, "access": { "revoked": false, "revoked_at": null }, "preorder": { "enabled": false, "launch_at": null, "released": true, "message": null }, "files": [ { "id": null, "asset": { "id": "7ea42f2a-6dbe-459c-b8a4-27b0eb823e52", "name": "price-list.csv", "type": "file" }, "download_count": 0, "watermark": { "enabled": false, "status": "not_required" }, "licence_keys": [] }, { "id": "66e2751c-9812-422c-864d-f8ce6a95c605", "asset": { "id": "96fbe30b-c819-4cb8-9666-814c0c8853f1", "name": "Beginner's Guide.pdf", "type": "file" }, "download_count": 0, "watermark": { "enabled": true, "status": "ready" }, "licence_keys": [] } ] } ], "eu_withdrawal": { "consent_required": false, "consented_at": null, "consent_text": null }, "shopify_tags": [], "imported_at": null, "deleted_at": null, "created_at": "2026-10-26T14:19:29Z", "updated_at": "2026-10-30T22:19:10Z" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "reset download count", "let the customer download again", "give more downloads", "customer hit the download limit", "reset downloads for one file" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "file_id": {} } }, "example": { "file_id": "66e2751c-9812-422c-864d-f8ce6a95c605" } } } } } }, "/orders/{id}/resync": { "post": { "operationId": "post_orders_id_resync", "summary": "Resync", "description": "Re-sync an order already in Filemonk from Shopify, as the Orders page's Find order does for a stored order: Filemonk fetches it again and links the files its products have now (for an order stored before its products had files). Unless send_email is false, the buyer is emailed about newly linked files. A deleted order is restored. Returns the order in full. Send it first without `confirm`. Nothing changes and the 409 `confirmation_required` says what would. Tell the merchant, ask, and resend with `confirm: true` only after they agree.\n\n**Note:** Previews first: without confirm: true nothing changes and 409 confirmation_required says what would be linked and who would be emailed. Files attached to the order on its own stay. 404 when Shopify no longer has the order; 502 when Shopify did not answer.", "tags": [ "Orders" ], "responses": { "200": { "description": "Success — the write completed; the body is the updated resource.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "shopify_order_id", "name", "confirmation_number", "ordered_at", "customer", "total", "status", "access", "delivery", "line_items", "eu_withdrawal", "shopify_tags", "imported_at", "deleted_at", "created_at", "updated_at" ], "properties": { "id": { "type": [ "string", "null" ] }, "shopify_order_id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "confirmation_number": { "type": [ "string", "null" ] }, "ordered_at": { "type": [ "string", "null" ] }, "customer": { "type": "object", "required": [ "id", "shopify_customer_id", "email", "phone", "first_name", "last_name", "country_code", "locale", "unsubscribed" ], "properties": { "id": { "type": [ "string", "null" ] }, "shopify_customer_id": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "phone": {}, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "country_code": {}, "locale": {}, "unsubscribed": { "type": [ "boolean", "null" ] } } }, "total": { "type": "object", "required": [ "amount", "currency" ], "properties": { "amount": { "type": [ "string", "null" ] }, "currency": { "type": [ "string", "null" ] } } }, "status": { "type": "object", "required": [ "financial", "fulfillment", "cancelled_at", "paid_at", "flagged_as_fraud", "fraud_check_completed", "marked_fulfilled_at", "delivery_conditions_met" ], "properties": { "financial": { "type": [ "string", "null" ] }, "fulfillment": { "type": [ "string", "null" ] }, "cancelled_at": {}, "paid_at": { "type": [ "string", "null" ] }, "flagged_as_fraud": { "type": [ "boolean", "null" ] }, "fraud_check_completed": { "type": [ "boolean", "null" ] }, "marked_fulfilled_at": {}, "delivery_conditions_met": { "type": [ "boolean", "null" ] } } }, "access": { "type": "object", "required": [ "state", "revoked_at", "available_until", "download_reset_at", "downloads_count" ], "properties": { "state": { "type": [ "string", "null" ] }, "revoked_at": {}, "available_until": {}, "download_reset_at": { "type": [ "string", "null" ] }, "downloads_count": { "type": [ "integer", "null" ] } } }, "delivery": { "type": "object", "required": [ "email_sent_at", "delivery_failed_at", "download_page_url", "source" ], "properties": { "email_sent_at": { "type": [ "string", "null" ] }, "delivery_failed_at": {}, "download_page_url": { "type": [ "string", "null" ] }, "source": { "type": [ "string", "null" ] } } }, "line_items": { "type": "array", "items": { "type": "object", "required": [ "id", "digital_product_id", "title", "sku", "quantity", "shopify_line_item_id", "shopify_product_id", "shopify_variant_id", "attached_to_this_order_only", "access", "preorder", "files" ], "properties": { "id": { "type": [ "string", "null" ] }, "digital_product_id": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "sku": { "type": [ "string", "null" ] }, "quantity": { "type": [ "integer", "null" ] }, "shopify_line_item_id": { "type": [ "string", "null" ] }, "shopify_product_id": { "type": [ "string", "null" ] }, "shopify_variant_id": { "type": [ "string", "null" ] }, "attached_to_this_order_only": { "type": [ "boolean", "null" ] }, "access": { "type": "object", "required": [ "revoked", "revoked_at" ], "properties": { "revoked": { "type": [ "boolean", "null" ] }, "revoked_at": {} } }, "preorder": { "type": "object", "required": [ "enabled", "launch_at", "released", "message" ], "properties": { "enabled": { "type": [ "boolean", "null" ] }, "launch_at": {}, "released": { "type": [ "boolean", "null" ] }, "message": {} } }, "files": { "type": "array", "items": { "type": "object", "required": [ "id", "asset", "download_count", "watermark", "licence_keys" ], "properties": { "id": {}, "asset": { "type": "object", "required": [ "id", "name", "type" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] } } }, "download_count": { "type": [ "integer", "null" ] }, "watermark": { "type": "object", "required": [ "enabled", "status" ], "properties": { "enabled": { "type": [ "boolean", "null" ] }, "status": { "type": [ "string", "null" ] } } }, "licence_keys": { "type": "array" } } } } } } }, "eu_withdrawal": { "type": "object", "required": [ "consent_required", "consented_at", "consent_text" ], "properties": { "consent_required": { "type": [ "boolean", "null" ] }, "consented_at": {}, "consent_text": {} } }, "shopify_tags": { "type": "array" }, "imported_at": {}, "deleted_at": {}, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } } }, "example": { "id": "3e84eb8d-e1d9-4e92-a4b2-a419c7f1122f", "shopify_order_id": "gid://shopify/Order/7555375595815", "name": "#1077", "confirmation_number": "H5CZG3GZX", "ordered_at": "2026-10-26T14:19:15Z", "customer": { "id": "b797db3a-cbc3-4643-804f-adf34c7f08d7", "shopify_customer_id": "gid://shopify/Customer/9026290417959", "email": "shopper@example.com", "phone": null, "first_name": "Jane", "last_name": "Doe", "country_code": null, "locale": null, "unsubscribed": false }, "total": { "amount": "1142.89", "currency": "INR" }, "status": { "financial": "paid", "fulfillment": "unfulfilled", "cancelled_at": null, "paid_at": "2026-10-30T21:48:16Z", "flagged_as_fraud": false, "fraud_check_completed": false, "marked_fulfilled_at": null, "delivery_conditions_met": false }, "access": { "state": "active", "revoked_at": null, "available_until": null, "download_reset_at": "2026-10-30T22:19:10Z", "downloads_count": 0 }, "delivery": { "email_sent_at": "2026-10-30T22:34:30Z", "delivery_failed_at": null, "download_page_url": "https://example-store.myshopify.com/apps/filemonk/orders/3e84eb8d-e1d9-4e92-a4b2-a419c7f1122f", "source": "webhook" }, "line_items": [ { "id": "5956bb41-dc65-45d5-b7d7-25f570598468", "digital_product_id": "7ea3c05d-6f29-42b6-b24f-43260caeaa32", "title": "Watercolour Course", "sku": "b0f5fbd0-f231-470f-b3d1-a392e3136a50", "quantity": 2, "shopify_line_item_id": "gid://shopify/LineItem/18329329434919", "shopify_product_id": "gid://shopify/Product/9642107044135", "shopify_variant_id": "gid://shopify/ProductVariant/49417714893095", "attached_to_this_order_only": false, "access": { "revoked": false, "revoked_at": null }, "preorder": { "enabled": false, "launch_at": null, "released": true, "message": null }, "files": [ { "id": null, "asset": { "id": "7ea42f2a-6dbe-459c-b8a4-27b0eb823e52", "name": "price-list.csv", "type": "file" }, "download_count": 0, "watermark": { "enabled": false, "status": "not_required" }, "licence_keys": [] }, { "id": "66e2751c-9812-422c-864d-f8ce6a95c605", "asset": { "id": "96fbe30b-c819-4cb8-9666-814c0c8853f1", "name": "Beginner's Guide.pdf", "type": "file" }, "download_count": 0, "watermark": { "enabled": true, "status": "ready" }, "licence_keys": [] } ] } ], "eu_withdrawal": { "consent_required": false, "consented_at": null, "consent_text": null }, "shopify_tags": [], "imported_at": null, "deleted_at": null, "created_at": "2026-10-26T14:19:29Z", "updated_at": "2026-10-30T22:19:10Z" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/BadGateway" } }, "x-aliases": [ "resync order", "refresh order from shopify", "relink files to order", "re-import order", "order has no files" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "send_email": {}, "confirm": {} } }, "example": { "send_email": true, "confirm": true } } } } } }, "/orders/{id}/send_email": { "post": { "operationId": "post_orders_id_send_email", "summary": "Send Email", "description": "Send the download email for this order again, to the buyer or to another address (to), as the order page's Send email does.\n\n**Note:** A send does everything a first delivery does: usage is charged, line items are marked fulfilled in Shopify when that setting is on, and licence keys the order is still owed are assigned. 409 when the shop's email sending is blocked.", "tags": [ "Orders" ], "responses": { "200": { "description": "Success — the write completed; the body is the updated resource.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "shopify_order_id", "name", "confirmation_number", "ordered_at", "customer", "total", "status", "access", "delivery", "line_items", "eu_withdrawal", "shopify_tags", "imported_at", "deleted_at", "created_at", "updated_at" ], "properties": { "id": { "type": [ "string", "null" ] }, "shopify_order_id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "confirmation_number": { "type": [ "string", "null" ] }, "ordered_at": { "type": [ "string", "null" ] }, "customer": { "type": "object", "required": [ "id", "shopify_customer_id", "email", "phone", "first_name", "last_name", "country_code", "locale", "unsubscribed" ], "properties": { "id": { "type": [ "string", "null" ] }, "shopify_customer_id": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "phone": {}, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "country_code": {}, "locale": {}, "unsubscribed": { "type": [ "boolean", "null" ] } } }, "total": { "type": "object", "required": [ "amount", "currency" ], "properties": { "amount": { "type": [ "string", "null" ] }, "currency": { "type": [ "string", "null" ] } } }, "status": { "type": "object", "required": [ "financial", "fulfillment", "cancelled_at", "paid_at", "flagged_as_fraud", "fraud_check_completed", "marked_fulfilled_at", "delivery_conditions_met" ], "properties": { "financial": { "type": [ "string", "null" ] }, "fulfillment": { "type": [ "string", "null" ] }, "cancelled_at": {}, "paid_at": { "type": [ "string", "null" ] }, "flagged_as_fraud": { "type": [ "boolean", "null" ] }, "fraud_check_completed": { "type": [ "boolean", "null" ] }, "marked_fulfilled_at": {}, "delivery_conditions_met": { "type": [ "boolean", "null" ] } } }, "access": { "type": "object", "required": [ "state", "revoked_at", "available_until", "download_reset_at", "downloads_count" ], "properties": { "state": { "type": [ "string", "null" ] }, "revoked_at": {}, "available_until": {}, "download_reset_at": { "type": [ "string", "null" ] }, "downloads_count": { "type": [ "integer", "null" ] } } }, "delivery": { "type": "object", "required": [ "email_sent_at", "delivery_failed_at", "download_page_url", "source" ], "properties": { "email_sent_at": { "type": [ "string", "null" ] }, "delivery_failed_at": {}, "download_page_url": { "type": [ "string", "null" ] }, "source": { "type": [ "string", "null" ] } } }, "line_items": { "type": "array", "items": { "type": "object", "required": [ "id", "digital_product_id", "title", "sku", "quantity", "shopify_line_item_id", "shopify_product_id", "shopify_variant_id", "attached_to_this_order_only", "access", "preorder", "files" ], "properties": { "id": { "type": [ "string", "null" ] }, "digital_product_id": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "sku": { "type": [ "string", "null" ] }, "quantity": { "type": [ "integer", "null" ] }, "shopify_line_item_id": { "type": [ "string", "null" ] }, "shopify_product_id": { "type": [ "string", "null" ] }, "shopify_variant_id": { "type": [ "string", "null" ] }, "attached_to_this_order_only": { "type": [ "boolean", "null" ] }, "access": { "type": "object", "required": [ "revoked", "revoked_at" ], "properties": { "revoked": { "type": [ "boolean", "null" ] }, "revoked_at": {} } }, "preorder": { "type": "object", "required": [ "enabled", "launch_at", "released", "message" ], "properties": { "enabled": { "type": [ "boolean", "null" ] }, "launch_at": {}, "released": { "type": [ "boolean", "null" ] }, "message": {} } }, "files": { "type": "array", "items": { "type": "object", "required": [ "id", "asset", "download_count", "watermark", "licence_keys" ], "properties": { "id": {}, "asset": { "type": "object", "required": [ "id", "name", "type" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] } } }, "download_count": { "type": [ "integer", "null" ] }, "watermark": { "type": "object", "required": [ "enabled", "status" ], "properties": { "enabled": { "type": [ "boolean", "null" ] }, "status": { "type": [ "string", "null" ] } } }, "licence_keys": { "type": "array" } } } } } } }, "eu_withdrawal": { "type": "object", "required": [ "consent_required", "consented_at", "consent_text" ], "properties": { "consent_required": { "type": [ "boolean", "null" ] }, "consented_at": {}, "consent_text": {} } }, "shopify_tags": { "type": "array" }, "imported_at": {}, "deleted_at": {}, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } } }, "example": { "id": "3e84eb8d-e1d9-4e92-a4b2-a419c7f1122f", "shopify_order_id": "gid://shopify/Order/7555375595815", "name": "#1077", "confirmation_number": "H5CZG3GZX", "ordered_at": "2026-10-26T14:19:15Z", "customer": { "id": "b797db3a-cbc3-4643-804f-adf34c7f08d7", "shopify_customer_id": "gid://shopify/Customer/9026290417959", "email": "shopper@example.com", "phone": null, "first_name": "Jane", "last_name": "Doe", "country_code": null, "locale": null, "unsubscribed": false }, "total": { "amount": "1142.89", "currency": "INR" }, "status": { "financial": "paid", "fulfillment": "unfulfilled", "cancelled_at": null, "paid_at": "2026-10-30T21:48:16Z", "flagged_as_fraud": false, "fraud_check_completed": false, "marked_fulfilled_at": null, "delivery_conditions_met": false }, "access": { "state": "active", "revoked_at": null, "available_until": null, "download_reset_at": "2026-10-30T22:19:10Z", "downloads_count": 0 }, "delivery": { "email_sent_at": "2026-10-30T22:34:30Z", "delivery_failed_at": null, "download_page_url": "https://example-store.myshopify.com/apps/filemonk/orders/3e84eb8d-e1d9-4e92-a4b2-a419c7f1122f", "source": "webhook" }, "line_items": [ { "id": "5956bb41-dc65-45d5-b7d7-25f570598468", "digital_product_id": "7ea3c05d-6f29-42b6-b24f-43260caeaa32", "title": "Watercolour Course", "sku": "b0f5fbd0-f231-470f-b3d1-a392e3136a50", "quantity": 2, "shopify_line_item_id": "gid://shopify/LineItem/18329329434919", "shopify_product_id": "gid://shopify/Product/9642107044135", "shopify_variant_id": "gid://shopify/ProductVariant/49417714893095", "attached_to_this_order_only": false, "access": { "revoked": false, "revoked_at": null }, "preorder": { "enabled": false, "launch_at": null, "released": true, "message": null }, "files": [ { "id": null, "asset": { "id": "7ea42f2a-6dbe-459c-b8a4-27b0eb823e52", "name": "price-list.csv", "type": "file" }, "download_count": 0, "watermark": { "enabled": false, "status": "not_required" }, "licence_keys": [] }, { "id": "66e2751c-9812-422c-864d-f8ce6a95c605", "asset": { "id": "96fbe30b-c819-4cb8-9666-814c0c8853f1", "name": "Beginner's Guide.pdf", "type": "file" }, "download_count": 0, "watermark": { "enabled": true, "status": "ready" }, "licence_keys": [] } ] } ], "eu_withdrawal": { "consent_required": false, "consented_at": null, "consent_text": null }, "shopify_tags": [], "imported_at": null, "deleted_at": null, "created_at": "2026-10-26T14:19:29Z", "updated_at": "2026-10-30T22:19:10Z" }, "examples": { "to_buyer": { "summary": "Resend to the buyer", "value": { "id": "3e84eb8d-e1d9-4e92-a4b2-a419c7f1122f", "shopify_order_id": "gid://shopify/Order/7555375595815", "name": "#1077", "confirmation_number": "H5CZG3GZX", "ordered_at": "2026-10-26T14:19:15Z", "customer": { "id": "b797db3a-cbc3-4643-804f-adf34c7f08d7", "shopify_customer_id": "gid://shopify/Customer/9026290417959", "email": "shopper@example.com", "phone": null, "first_name": "Jane", "last_name": "Doe", "country_code": null, "locale": null, "unsubscribed": false }, "total": { "amount": "1142.89", "currency": "INR" }, "status": { "financial": "paid", "fulfillment": "unfulfilled", "cancelled_at": null, "paid_at": "2026-10-30T21:48:16Z", "flagged_as_fraud": false, "fraud_check_completed": false, "marked_fulfilled_at": null, "delivery_conditions_met": false }, "access": { "state": "active", "revoked_at": null, "available_until": null, "download_reset_at": "2026-10-30T22:19:10Z", "downloads_count": 0 }, "delivery": { "email_sent_at": "2026-10-30T22:34:30Z", "delivery_failed_at": null, "download_page_url": "https://example-store.myshopify.com/apps/filemonk/orders/3e84eb8d-e1d9-4e92-a4b2-a419c7f1122f", "source": "webhook" }, "line_items": [ { "id": "5956bb41-dc65-45d5-b7d7-25f570598468", "digital_product_id": "7ea3c05d-6f29-42b6-b24f-43260caeaa32", "title": "Watercolour Course", "sku": "b0f5fbd0-f231-470f-b3d1-a392e3136a50", "quantity": 2, "shopify_line_item_id": "gid://shopify/LineItem/18329329434919", "shopify_product_id": "gid://shopify/Product/9642107044135", "shopify_variant_id": "gid://shopify/ProductVariant/49417714893095", "attached_to_this_order_only": false, "access": { "revoked": false, "revoked_at": null }, "preorder": { "enabled": false, "launch_at": null, "released": true, "message": null }, "files": [ { "id": null, "asset": { "id": "7ea42f2a-6dbe-459c-b8a4-27b0eb823e52", "name": "price-list.csv", "type": "file" }, "download_count": 0, "watermark": { "enabled": false, "status": "not_required" }, "licence_keys": [] }, { "id": "66e2751c-9812-422c-864d-f8ce6a95c605", "asset": { "id": "96fbe30b-c819-4cb8-9666-814c0c8853f1", "name": "Beginner's Guide.pdf", "type": "file" }, "download_count": 0, "watermark": { "enabled": true, "status": "ready" }, "licence_keys": [] } ] } ], "eu_withdrawal": { "consent_required": false, "consented_at": null, "consent_text": null }, "shopify_tags": [], "imported_at": null, "deleted_at": null, "created_at": "2026-10-26T14:19:29Z", "updated_at": "2026-10-30T22:19:10Z" } }, "to_other_address": { "summary": "Send to another address", "value": { "id": "3e84eb8d-e1d9-4e92-a4b2-a419c7f1122f", "shopify_order_id": "gid://shopify/Order/7555375595815", "name": "#1077", "confirmation_number": "H5CZG3GZX", "ordered_at": "2026-10-26T14:19:15Z", "customer": { "id": "b797db3a-cbc3-4643-804f-adf34c7f08d7", "shopify_customer_id": "gid://shopify/Customer/9026290417959", "email": "shopper@example.com", "phone": null, "first_name": "Jane", "last_name": "Doe", "country_code": null, "locale": null, "unsubscribed": false }, "total": { "amount": "1142.89", "currency": "INR" }, "status": { "financial": "paid", "fulfillment": "unfulfilled", "cancelled_at": null, "paid_at": "2026-10-30T21:48:16Z", "flagged_as_fraud": false, "fraud_check_completed": false, "marked_fulfilled_at": null, "delivery_conditions_met": false }, "access": { "state": "active", "revoked_at": null, "available_until": null, "download_reset_at": "2026-10-30T22:19:10Z", "downloads_count": 0 }, "delivery": { "email_sent_at": "2026-10-30T22:34:30Z", "delivery_failed_at": null, "download_page_url": "https://example-store.myshopify.com/apps/filemonk/orders/3e84eb8d-e1d9-4e92-a4b2-a419c7f1122f", "source": "webhook" }, "line_items": [ { "id": "5956bb41-dc65-45d5-b7d7-25f570598468", "digital_product_id": "7ea3c05d-6f29-42b6-b24f-43260caeaa32", "title": "Watercolour Course", "sku": "b0f5fbd0-f231-470f-b3d1-a392e3136a50", "quantity": 2, "shopify_line_item_id": "gid://shopify/LineItem/18329329434919", "shopify_product_id": "gid://shopify/Product/9642107044135", "shopify_variant_id": "gid://shopify/ProductVariant/49417714893095", "attached_to_this_order_only": false, "access": { "revoked": false, "revoked_at": null }, "preorder": { "enabled": false, "launch_at": null, "released": true, "message": null }, "files": [ { "id": null, "asset": { "id": "7ea42f2a-6dbe-459c-b8a4-27b0eb823e52", "name": "price-list.csv", "type": "file" }, "download_count": 0, "watermark": { "enabled": false, "status": "not_required" }, "licence_keys": [] }, { "id": "66e2751c-9812-422c-864d-f8ce6a95c605", "asset": { "id": "96fbe30b-c819-4cb8-9666-814c0c8853f1", "name": "Beginner's Guide.pdf", "type": "file" }, "download_count": 0, "watermark": { "enabled": true, "status": "ready" }, "licence_keys": [] } ] } ], "eu_withdrawal": { "consent_required": false, "consented_at": null, "consent_text": null }, "shopify_tags": [], "imported_at": null, "deleted_at": null, "created_at": "2026-10-26T14:19:29Z", "updated_at": "2026-10-30T22:19:10Z" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/BadGateway" } }, "x-aliases": [ "resend download email", "send the download link again", "customer did not get the email", "email the files to another address", "resend order email" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "to": {} } }, "example": { "to": "shopper@example.com" }, "examples": { "to_buyer": { "summary": "Resend to the buyer", "value": {} }, "to_other_address": { "summary": "Send to another address", "value": { "to": "accounts@example.com" } } } } } } } }, "/orders/{id}/troubleshoot": { "get": { "operationId": "get_orders_id_troubleshoot", "summary": "Troubleshoot", "description": "Why a buyer got no files, as the Orders page's troubleshooter shows: whether Shopify has the order, whether Filemonk stored it, and for every Shopify line item whether its product or variant has files in Filemonk (with counts) or is a custom product. Ends with a diagnosis and the request that fixes each finding. :id is the order name (#1042), the Shopify order gid or id, or Filemonk's order id.\n\n**Note:** Read-only; asks Shopify for the order. Start here for a 'no files' complaint, then send the next_steps request it names (each previews before it changes anything). 404 when neither Shopify nor Filemonk has the order; 502 when Shopify did not answer.", "tags": [ "Orders" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object", "required": [ "query", "shopify", "filemonk", "line_items", "diagnosis" ], "properties": { "query": { "type": [ "string", "null" ] }, "shopify": { "type": "object", "required": [ "found", "id", "name", "created_at", "email", "financial_status", "fulfillment_status", "cancelled_at", "test" ], "properties": { "found": { "type": [ "boolean", "null" ] }, "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "financial_status": { "type": [ "string", "null" ] }, "fulfillment_status": {}, "cancelled_at": {}, "test": { "type": [ "boolean", "null" ] } } }, "filemonk": { "type": "object", "required": [ "stored", "deleted", "id", "name", "access", "delivery_conditions_met", "email_sent_at", "files_count" ], "properties": { "stored": { "type": [ "boolean", "null" ] }, "deleted": { "type": [ "boolean", "null" ] }, "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "access": { "type": "object", "required": [ "state", "revoked", "expires_at" ], "properties": { "state": { "type": [ "string", "null" ] }, "revoked": { "type": [ "boolean", "null" ] }, "expires_at": {} } }, "delivery_conditions_met": { "type": [ "boolean", "null" ] }, "email_sent_at": {}, "files_count": { "type": [ "integer", "null" ] } } }, "line_items": { "type": "array", "items": { "type": "object", "required": [ "title", "variant_title", "sku", "quantity", "shopify_product_id", "shopify_variant_id", "product", "variant", "delivers_files" ], "properties": { "title": { "type": [ "string", "null" ] }, "variant_title": {}, "sku": {}, "quantity": { "type": [ "integer", "null" ] }, "shopify_product_id": { "type": [ "string", "null" ] }, "shopify_variant_id": { "type": [ "string", "null" ] }, "product": { "type": "object", "required": [ "digital_product_ids", "files_count", "custom" ], "properties": { "digital_product_ids": { "type": "array", "items": { "type": [ "string", "null" ] } }, "files_count": { "type": [ "integer", "null" ] }, "custom": { "type": [ "boolean", "null" ] } } }, "variant": {}, "delivers_files": { "type": [ "boolean", "null" ] } } } }, "diagnosis": { "type": "array", "items": { "type": "object", "required": [ "code", "finding", "next_step", "request" ], "properties": { "code": { "type": [ "string", "null" ] }, "finding": { "type": [ "string", "null" ] }, "next_step": { "type": [ "string", "null" ] }, "request": { "type": [ "string", "null" ] } } } } } }, "example": { "query": "#1042", "shopify": { "found": true, "id": "gid://shopify/Order/7555375595815", "name": "#1042", "created_at": "2026-10-28T14:02:11Z", "email": "buyer@example.com", "financial_status": "paid", "fulfillment_status": null, "cancelled_at": null, "test": false }, "filemonk": { "stored": true, "deleted": false, "id": "3f1c2b8e-5a7d-4e19-9c61-2b8d0f4a7c55", "name": "#1042", "access": { "state": "active", "revoked": false, "expires_at": null }, "delivery_conditions_met": true, "email_sent_at": null, "files_count": 0 }, "line_items": [ { "title": "Watercolour Course", "variant_title": null, "sku": null, "quantity": 1, "shopify_product_id": "gid://shopify/Product/9642107044135", "shopify_variant_id": "gid://shopify/ProductVariant/49718237560103", "product": { "digital_product_ids": [ "7ea3c05d-6f29-42b6-b24f-43260caeaa32" ], "files_count": 2, "custom": false }, "variant": null, "delivers_files": true } ], "diagnosis": [ { "code": "stored_without_files", "finding": "Filemonk stored the order before its products had files, so it holds none.", "next_step": "Re-sync it from Shopify to link the files now on its products. It previews first.", "request": "POST /orders/3f1c2b8e-5a7d-4e19-9c61-2b8d0f4a7c55/resync" } ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/BadGateway" } }, "x-aliases": [ "customer got no files", "customer did not receive download", "why was this order not delivered", "troubleshoot order", "order missing in filemonk", "diagnose order" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/orders/send_emails": { "post": { "operationId": "post_orders_send_emails", "summary": "Send Emails", "description": "Send the download email again for several orders at once, in the background, as the Orders page's bulk Send emails does. ids are order ids, Shopify order gids or ids, or order names.\n\n**Note:** Queued: the response lists the orders that will be emailed and the ids that matched nothing. Each send charges usage, fulfils in Shopify when that setting is on, and assigns owed licence keys.", "tags": [ "Orders" ], "responses": { "200": { "description": "Success — the write completed; the body is the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "202": { "description": "Accepted — the change was saved and the rest of the work (emails, Shopify sync, a bulk job) continues in the background. The body is the resource snapshot plus `queued: true`; there is nothing to poll.", "content": { "application/json": { "schema": { "type": "object", "required": [ "queued", "count", "ids", "missing" ], "properties": { "queued": { "type": [ "boolean", "null" ] }, "count": { "type": [ "integer", "null" ] }, "ids": { "type": "array", "items": { "type": [ "string", "null" ] } }, "missing": { "type": "array" } } }, "example": { "queued": true, "count": 1, "ids": [ "3e84eb8d-e1d9-4e92-a4b2-a419c7f1122f" ], "missing": [] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "resend emails to these orders", "bulk resend download emails", "email all these customers again" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string" } } }, "required": [ "ids" ] }, "example": { "ids": [ "3e84eb8d-e1d9-4e92-a4b2-a419c7f1122f" ] } } } } } }, "/settings": { "get": { "operationId": "get_settings", "summary": "Read", "description": "Every setting the dashboard's settings pages expose, grouped by page: general, email, download_page, download_limits, order_conditions, shopify_sync, watermark, customer_accounts and eu_withdrawal. Keys and tokens are never included.", "tags": [ "Settings" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object", "required": [ "general", "email", "download_page", "download_limits", "order_conditions", "shopify_sync", "watermark", "customer_accounts", "eu_withdrawal" ], "properties": { "general": { "type": "object", "required": [ "app_enabled", "default_locale", "app_locale", "multi_language_enabled", "ignore_orders_before", "branding_hidden" ], "properties": { "app_enabled": { "type": [ "boolean", "null" ] }, "default_locale": { "type": [ "string", "null" ] }, "app_locale": { "type": [ "string", "null" ] }, "multi_language_enabled": { "type": [ "boolean", "null" ] }, "ignore_orders_before": { "type": "object", "required": [ "date", "order_number" ], "properties": { "date": {}, "order_number": {} } }, "branding_hidden": { "type": [ "boolean", "null" ] } } }, "email": { "type": "object", "required": [ "enabled", "from_name", "from_address", "reply_to", "report_address", "subject", "body", "button", "footer_text", "font_family", "logo_size", "colors", "css", "product_update", "merchant_notifications", "domain" ], "properties": { "enabled": { "type": [ "boolean", "null" ] }, "from_name": { "type": [ "string", "null" ] }, "from_address": { "type": [ "string", "null" ] }, "reply_to": { "type": [ "string", "null" ] }, "report_address": { "type": [ "string", "null" ] }, "subject": { "type": [ "string", "null" ] }, "body": { "type": [ "string", "null" ] }, "button": { "type": "object", "required": [ "text", "text_color", "background_color", "border_radius" ], "properties": { "text": { "type": [ "string", "null" ] }, "text_color": { "type": [ "string", "null" ] }, "background_color": { "type": [ "string", "null" ] }, "border_radius": { "type": [ "integer", "null" ] } } }, "footer_text": { "type": [ "string", "null" ] }, "font_family": { "type": [ "string", "null" ] }, "logo_size": { "type": [ "string", "null" ] }, "colors": { "type": "object", "required": [ "text", "background" ], "properties": { "text": { "type": [ "string", "null" ] }, "background": { "type": [ "string", "null" ] } } }, "css": {}, "product_update": { "type": "object", "required": [ "subject", "body" ], "properties": { "subject": { "type": [ "string", "null" ] }, "body": { "type": [ "string", "null" ] } } }, "merchant_notifications": { "type": "object", "required": [ "promotions", "usage", "licence_exhaustion", "licence_exhaustion_threshold" ], "properties": { "promotions": { "type": [ "boolean", "null" ] }, "usage": { "type": [ "boolean", "null" ] }, "licence_exhaustion": { "type": [ "boolean", "null" ] }, "licence_exhaustion_threshold": { "type": [ "integer", "null" ] } } }, "domain": { "type": "object", "required": [ "custom_address", "name", "dkim_verified" ], "properties": { "custom_address": { "type": [ "boolean", "null" ] }, "name": { "type": [ "string", "null" ] }, "dkim_verified": { "type": [ "boolean", "null" ] } } } } }, "download_page": { "type": "object", "required": [ "host", "path_prefix", "require_login", "email_gate", "texts", "colors", "show_price", "show_image", "show_store_link", "show_orders_link", "pdf_viewer", "hide_file_extensions", "price_format", "logo_size", "css", "store_url", "default_view" ], "properties": { "host": { "type": [ "string", "null" ] }, "path_prefix": { "type": [ "string", "null" ] }, "require_login": {}, "email_gate": { "type": [ "boolean", "null" ] }, "texts": { "type": "object", "required": [ "thanks", "button", "store_link", "orders_link", "orders_index", "custom_downloads", "custom_downloads_ready", "licence_label", "licence_type_label", "licence_button", "licence_error", "login_title", "login_message", "login_button", "total_label", "files_label", "downloading", "processing", "processing_button", "preorder", "watermarking", "generic_error", "copy_button", "copied", "not_available" ], "properties": { "thanks": { "type": [ "string", "null" ] }, "button": { "type": [ "string", "null" ] }, "store_link": { "type": [ "string", "null" ] }, "orders_link": { "type": [ "string", "null" ] }, "orders_index": { "type": [ "string", "null" ] }, "custom_downloads": { "type": [ "string", "null" ] }, "custom_downloads_ready": { "type": [ "string", "null" ] }, "licence_label": { "type": [ "string", "null" ] }, "licence_type_label": { "type": [ "string", "null" ] }, "licence_button": { "type": [ "string", "null" ] }, "licence_error": { "type": [ "string", "null" ] }, "login_title": { "type": [ "string", "null" ] }, "login_message": { "type": [ "string", "null" ] }, "login_button": { "type": [ "string", "null" ] }, "total_label": { "type": [ "string", "null" ] }, "files_label": { "type": [ "string", "null" ] }, "downloading": { "type": [ "string", "null" ] }, "processing": { "type": [ "string", "null" ] }, "processing_button": { "type": [ "string", "null" ] }, "preorder": { "type": [ "string", "null" ] }, "watermarking": { "type": [ "string", "null" ] }, "generic_error": { "type": [ "string", "null" ] }, "copy_button": { "type": [ "string", "null" ] }, "copied": { "type": [ "string", "null" ] }, "not_available": { "type": [ "string", "null" ] } } }, "colors": { "type": "object", "required": [ "text", "background", "section", "button_text", "button_background" ], "properties": { "text": { "type": [ "string", "null" ] }, "background": { "type": [ "string", "null" ] }, "section": { "type": [ "string", "null" ] }, "button_text": { "type": [ "string", "null" ] }, "button_background": { "type": [ "string", "null" ] } } }, "show_price": { "type": [ "boolean", "null" ] }, "show_image": { "type": [ "boolean", "null" ] }, "show_store_link": { "type": [ "boolean", "null" ] }, "show_orders_link": { "type": [ "boolean", "null" ] }, "pdf_viewer": { "type": [ "boolean", "null" ] }, "hide_file_extensions": { "type": [ "boolean", "null" ] }, "price_format": { "type": [ "string", "null" ] }, "logo_size": { "type": [ "integer", "null" ] }, "css": {}, "store_url": { "type": [ "string", "null" ] }, "default_view": { "type": [ "string", "null" ] } } }, "download_limits": { "type": "object", "required": [ "show", "per_file_count", "days", "messages" ], "properties": { "show": { "type": [ "boolean", "null" ] }, "per_file_count": {}, "days": {}, "messages": { "type": "object", "required": [ "limit_reached", "count", "days" ], "properties": { "limit_reached": { "type": [ "string", "null" ] }, "count": { "type": [ "string", "null" ] }, "days": { "type": [ "string", "null" ] } } } } }, "order_conditions": { "type": "object", "required": [ "check_status", "status_type", "financial_status", "fulfillment_status", "shipment_status", "revoke_on_mismatch", "refunded_order_protection", "fraud_protection", "process_orders_on_update" ], "properties": { "check_status": { "type": [ "boolean", "null" ] }, "status_type": { "type": [ "string", "null" ] }, "financial_status": { "type": [ "string", "null" ] }, "fulfillment_status": { "type": [ "string", "null" ] }, "shipment_status": { "type": [ "string", "null" ] }, "revoke_on_mismatch": { "type": [ "boolean", "null" ] }, "refunded_order_protection": { "type": [ "boolean", "null" ] }, "fraud_protection": { "type": [ "boolean", "null" ] }, "process_orders_on_update": { "type": [ "boolean", "null" ] } } }, "shopify_sync": { "type": "object", "required": [ "add_order_tags", "order_tags", "mark_line_items_fulfilled", "skip_fulfillment_for_tags", "add_tracking_info" ], "properties": { "add_order_tags": { "type": [ "boolean", "null" ] }, "order_tags": { "type": [ "string", "null" ] }, "mark_line_items_fulfilled": { "type": [ "boolean", "null" ] }, "skip_fulfillment_for_tags": {}, "add_tracking_info": { "type": [ "boolean", "null" ] } } }, "watermark": { "type": "object", "required": [ "enabled", "all_files", "text", "style", "layer", "opacity", "font" ], "properties": { "enabled": { "type": [ "boolean", "null" ] }, "all_files": { "type": [ "boolean", "null" ] }, "text": { "type": [ "string", "null" ] }, "style": { "type": [ "string", "null" ] }, "layer": { "type": [ "string", "null" ] }, "opacity": { "type": [ "integer", "null" ] }, "font": { "type": "object", "required": [ "size", "color", "name" ], "properties": { "size": { "type": [ "integer", "null" ] }, "color": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } } } } }, "customer_accounts": { "type": "object", "required": [ "button_text", "product_downloads_subtitle", "order_status" ], "properties": { "button_text": { "type": [ "string", "null" ] }, "product_downloads_subtitle": { "type": [ "string", "null" ] }, "order_status": { "type": "object", "required": [ "thanks_text", "button_text", "thank_you_page_button", "order_status_page_button" ], "properties": { "thanks_text": { "type": [ "string", "null" ] }, "button_text": { "type": [ "string", "null" ] }, "thank_you_page_button": { "type": [ "boolean", "null" ] }, "order_status_page_button": { "type": [ "boolean", "null" ] } } } } }, "eu_withdrawal": { "type": "object", "required": [ "enabled", "scope", "consent_text", "button_text" ], "properties": { "enabled": { "type": [ "boolean", "null" ] }, "scope": { "type": [ "string", "null" ] }, "consent_text": { "type": [ "string", "null" ] }, "button_text": { "type": [ "string", "null" ] } } } } }, "example": { "general": { "app_enabled": true, "default_locale": "en", "app_locale": "fr", "multi_language_enabled": true, "ignore_orders_before": { "date": null, "order_number": null }, "branding_hidden": false }, "email": { "enabled": true, "from_name": "Example Store", "from_address": "alerts@filemonk.io", "reply_to": "owner@example.com", "report_address": "owner@example.com", "subject": "Your {{shop.name}} {{order.name}} content", "body": "Thanks for purchasing from {{shop.name}}! Click the button below to access the digital content for your order {{order.name}}.", "button": { "text": "Access downloads", "text_color": "#fff", "background_color": "#202223", "border_radius": 5 }, "footer_text": "Facing trouble accessing your content? Contact us right away.", "font_family": "sans-serif", "logo_size": "200", "colors": { "text": "#202223", "background": "#ffffff" }, "css": null, "product_update": { "subject": "Update to {{product_variant.title}} in your order {{order.name}}", "body": "Your most recent purchase for {{product_variant.title}} has been updated. Click the link below to access your updated content." }, "merchant_notifications": { "promotions": true, "usage": true, "licence_exhaustion": false, "licence_exhaustion_threshold": 80 }, "domain": { "custom_address": false, "name": "example-store", "dkim_verified": false } }, "download_page": { "host": "storefront", "path_prefix": "/apps/filemonk", "require_login": null, "email_gate": false, "texts": { "thanks": "Thank you for purchasing from our store! Click on any of the products below to download your content.", "button": "Download", "store_link": "Visit store", "orders_link": "My orders", "orders_index": "My orders", "custom_downloads": "Custom products", "custom_downloads_ready": "Your digital content will be available here when it's ready.", "licence_label": "Licence key", "licence_type_label": "Key", "licence_button": "View", "licence_error": "No licence key available. Contact store.", "login_title": "Customer Login Required", "login_message": "You need to be logged in with the correct account to access your digital orders. Please click the button below to log in or switch to the appropriate account.", "login_button": "Log In", "total_label": "Total", "files_label": "files", "downloading": "Downloading...", "processing": "Processing order. Please wait.", "processing_button": "Processing...", "preorder": "This product is currently in preorder and will be available for download on {{date}}.", "watermarking": "Watermarking is not complete, please wait or reload the page to check again.", "generic_error": "Something went wrong.", "copy_button": "Copy", "copied": "Copied to clipboard", "not_available": "Not Available" }, "colors": { "text": "#202223", "background": "#f6f7f7", "section": "#ffffff", "button_text": "#FFF", "button_background": "#1B76FF" }, "show_price": true, "show_image": true, "show_store_link": true, "show_orders_link": true, "pdf_viewer": false, "hide_file_extensions": false, "price_format": "{{currency_symbol}}{{amount}}", "logo_size": 100, "css": null, "store_url": "example-store.myshopify.com", "default_view": "files" }, "download_limits": { "show": false, "per_file_count": null, "days": null, "messages": { "limit_reached": "Sorry! This file is no longer available to download.", "count": "Maximum downloads per file: ", "days": "Available to download until" } }, "order_conditions": { "check_status": true, "status_type": "fulfillment", "financial_status": "", "fulfillment_status": "fulfilled", "shipment_status": "", "revoke_on_mismatch": false, "refunded_order_protection": false, "fraud_protection": false, "process_orders_on_update": false }, "shopify_sync": { "add_order_tags": false, "order_tags": "filemonk_order", "mark_line_items_fulfilled": false, "skip_fulfillment_for_tags": null, "add_tracking_info": true }, "watermark": { "enabled": true, "all_files": true, "text": "Licensed to {{order.customer_name}} ({{order.email_or_phone}}), order {{order.name}}. Please don't share this file.", "style": "center", "layer": "above", "opacity": 30, "font": { "size": 30, "color": "#ff0018", "name": "Courier New Bold" } }, "customer_accounts": { "button_text": "Download files", "product_downloads_subtitle": "Downloads available", "order_status": { "thanks_text": "Thanks for your purchase! Click the button below to access your files.", "button_text": "Access downloads", "thank_you_page_button": true, "order_status_page_button": true } }, "eu_withdrawal": { "enabled": false, "scope": "eu_only", "consent_text": "I request immediate access to this digital content and acknowledge that I lose my right of withdrawal once the download begins.", "button_text": "Confirm and download" } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "show settings", "is the download email enabled", "how many days can customers download", "what are the order conditions", "watermark settings" ] }, "patch": { "operationId": "patch_settings", "summary": "Update", "description": "Change settings, as the settings pages do: send any subset of the sections GET /settings returns (general, email, download_page, download_limits, order_conditions, shopify_sync, watermark, customer_accounts, eu_withdrawal) with only the fields to change. Answers with every setting after the save.\n\n**Note:** Deep partial: untouched fields keep their value. email.domain.dkim_verified is read-only. The same checks as the dashboard run (email copy is spam-checked, the download button text cannot be blank).", "tags": [ "Settings" ], "responses": { "200": { "description": "Success — the write completed; the body is the updated resource.", "content": { "application/json": { "schema": { "type": "object", "required": [ "general", "email", "download_page", "download_limits", "order_conditions", "shopify_sync", "watermark", "customer_accounts", "eu_withdrawal" ], "properties": { "general": { "type": "object", "required": [ "app_enabled", "default_locale", "app_locale", "multi_language_enabled", "ignore_orders_before", "branding_hidden" ], "properties": { "app_enabled": { "type": [ "boolean", "null" ] }, "default_locale": { "type": [ "string", "null" ] }, "app_locale": { "type": [ "string", "null" ] }, "multi_language_enabled": { "type": [ "boolean", "null" ] }, "ignore_orders_before": { "type": "object", "required": [ "date", "order_number" ], "properties": { "date": {}, "order_number": {} } }, "branding_hidden": { "type": [ "boolean", "null" ] } } }, "email": { "type": "object", "required": [ "enabled", "from_name", "from_address", "reply_to", "report_address", "subject", "body", "button", "footer_text", "font_family", "logo_size", "colors", "css", "product_update", "merchant_notifications", "domain" ], "properties": { "enabled": { "type": [ "boolean", "null" ] }, "from_name": { "type": [ "string", "null" ] }, "from_address": { "type": [ "string", "null" ] }, "reply_to": { "type": [ "string", "null" ] }, "report_address": { "type": [ "string", "null" ] }, "subject": { "type": [ "string", "null" ] }, "body": { "type": [ "string", "null" ] }, "button": { "type": "object", "required": [ "text", "text_color", "background_color", "border_radius" ], "properties": { "text": { "type": [ "string", "null" ] }, "text_color": { "type": [ "string", "null" ] }, "background_color": { "type": [ "string", "null" ] }, "border_radius": { "type": [ "integer", "null" ] } } }, "footer_text": { "type": [ "string", "null" ] }, "font_family": { "type": [ "string", "null" ] }, "logo_size": { "type": [ "string", "null" ] }, "colors": { "type": "object", "required": [ "text", "background" ], "properties": { "text": { "type": [ "string", "null" ] }, "background": { "type": [ "string", "null" ] } } }, "css": {}, "product_update": { "type": "object", "required": [ "subject", "body" ], "properties": { "subject": { "type": [ "string", "null" ] }, "body": { "type": [ "string", "null" ] } } }, "merchant_notifications": { "type": "object", "required": [ "promotions", "usage", "licence_exhaustion", "licence_exhaustion_threshold" ], "properties": { "promotions": { "type": [ "boolean", "null" ] }, "usage": { "type": [ "boolean", "null" ] }, "licence_exhaustion": { "type": [ "boolean", "null" ] }, "licence_exhaustion_threshold": { "type": [ "integer", "null" ] } } }, "domain": { "type": "object", "required": [ "custom_address", "name", "dkim_verified" ], "properties": { "custom_address": { "type": [ "boolean", "null" ] }, "name": { "type": [ "string", "null" ] }, "dkim_verified": { "type": [ "boolean", "null" ] } } } } }, "download_page": { "type": "object", "required": [ "host", "path_prefix", "require_login", "email_gate", "texts", "colors", "show_price", "show_image", "show_store_link", "show_orders_link", "pdf_viewer", "hide_file_extensions", "price_format", "logo_size", "css", "store_url", "default_view" ], "properties": { "host": { "type": [ "string", "null" ] }, "path_prefix": { "type": [ "string", "null" ] }, "require_login": {}, "email_gate": { "type": [ "boolean", "null" ] }, "texts": { "type": "object", "required": [ "thanks", "button", "store_link", "orders_link", "orders_index", "custom_downloads", "custom_downloads_ready", "licence_label", "licence_type_label", "licence_button", "licence_error", "login_title", "login_message", "login_button", "total_label", "files_label", "downloading", "processing", "processing_button", "preorder", "watermarking", "generic_error", "copy_button", "copied", "not_available" ], "properties": { "thanks": { "type": [ "string", "null" ] }, "button": { "type": [ "string", "null" ] }, "store_link": { "type": [ "string", "null" ] }, "orders_link": { "type": [ "string", "null" ] }, "orders_index": { "type": [ "string", "null" ] }, "custom_downloads": { "type": [ "string", "null" ] }, "custom_downloads_ready": { "type": [ "string", "null" ] }, "licence_label": { "type": [ "string", "null" ] }, "licence_type_label": { "type": [ "string", "null" ] }, "licence_button": { "type": [ "string", "null" ] }, "licence_error": { "type": [ "string", "null" ] }, "login_title": { "type": [ "string", "null" ] }, "login_message": { "type": [ "string", "null" ] }, "login_button": { "type": [ "string", "null" ] }, "total_label": { "type": [ "string", "null" ] }, "files_label": { "type": [ "string", "null" ] }, "downloading": { "type": [ "string", "null" ] }, "processing": { "type": [ "string", "null" ] }, "processing_button": { "type": [ "string", "null" ] }, "preorder": { "type": [ "string", "null" ] }, "watermarking": { "type": [ "string", "null" ] }, "generic_error": { "type": [ "string", "null" ] }, "copy_button": { "type": [ "string", "null" ] }, "copied": { "type": [ "string", "null" ] }, "not_available": { "type": [ "string", "null" ] } } }, "colors": { "type": "object", "required": [ "text", "background", "section", "button_text", "button_background" ], "properties": { "text": { "type": [ "string", "null" ] }, "background": { "type": [ "string", "null" ] }, "section": { "type": [ "string", "null" ] }, "button_text": { "type": [ "string", "null" ] }, "button_background": { "type": [ "string", "null" ] } } }, "show_price": { "type": [ "boolean", "null" ] }, "show_image": { "type": [ "boolean", "null" ] }, "show_store_link": { "type": [ "boolean", "null" ] }, "show_orders_link": { "type": [ "boolean", "null" ] }, "pdf_viewer": { "type": [ "boolean", "null" ] }, "hide_file_extensions": { "type": [ "boolean", "null" ] }, "price_format": { "type": [ "string", "null" ] }, "logo_size": { "type": [ "integer", "null" ] }, "css": {}, "store_url": { "type": [ "string", "null" ] }, "default_view": { "type": [ "string", "null" ] } } }, "download_limits": { "type": "object", "required": [ "show", "per_file_count", "days", "messages" ], "properties": { "show": { "type": [ "boolean", "null" ] }, "per_file_count": {}, "days": {}, "messages": { "type": "object", "required": [ "limit_reached", "count", "days" ], "properties": { "limit_reached": { "type": [ "string", "null" ] }, "count": { "type": [ "string", "null" ] }, "days": { "type": [ "string", "null" ] } } } } }, "order_conditions": { "type": "object", "required": [ "check_status", "status_type", "financial_status", "fulfillment_status", "shipment_status", "revoke_on_mismatch", "refunded_order_protection", "fraud_protection", "process_orders_on_update" ], "properties": { "check_status": { "type": [ "boolean", "null" ] }, "status_type": { "type": [ "string", "null" ] }, "financial_status": { "type": [ "string", "null" ] }, "fulfillment_status": { "type": [ "string", "null" ] }, "shipment_status": { "type": [ "string", "null" ] }, "revoke_on_mismatch": { "type": [ "boolean", "null" ] }, "refunded_order_protection": { "type": [ "boolean", "null" ] }, "fraud_protection": { "type": [ "boolean", "null" ] }, "process_orders_on_update": { "type": [ "boolean", "null" ] } } }, "shopify_sync": { "type": "object", "required": [ "add_order_tags", "order_tags", "mark_line_items_fulfilled", "skip_fulfillment_for_tags", "add_tracking_info" ], "properties": { "add_order_tags": { "type": [ "boolean", "null" ] }, "order_tags": { "type": [ "string", "null" ] }, "mark_line_items_fulfilled": { "type": [ "boolean", "null" ] }, "skip_fulfillment_for_tags": {}, "add_tracking_info": { "type": [ "boolean", "null" ] } } }, "watermark": { "type": "object", "required": [ "enabled", "all_files", "text", "style", "layer", "opacity", "font" ], "properties": { "enabled": { "type": [ "boolean", "null" ] }, "all_files": { "type": [ "boolean", "null" ] }, "text": { "type": [ "string", "null" ] }, "style": { "type": [ "string", "null" ] }, "layer": { "type": [ "string", "null" ] }, "opacity": { "type": [ "integer", "null" ] }, "font": { "type": "object", "required": [ "size", "color", "name" ], "properties": { "size": { "type": [ "integer", "null" ] }, "color": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } } } } }, "customer_accounts": { "type": "object", "required": [ "button_text", "product_downloads_subtitle", "order_status" ], "properties": { "button_text": { "type": [ "string", "null" ] }, "product_downloads_subtitle": { "type": [ "string", "null" ] }, "order_status": { "type": "object", "required": [ "thanks_text", "button_text", "thank_you_page_button", "order_status_page_button" ], "properties": { "thanks_text": { "type": [ "string", "null" ] }, "button_text": { "type": [ "string", "null" ] }, "thank_you_page_button": { "type": [ "boolean", "null" ] }, "order_status_page_button": { "type": [ "boolean", "null" ] } } } } }, "eu_withdrawal": { "type": "object", "required": [ "enabled", "scope", "consent_text", "button_text" ], "properties": { "enabled": { "type": [ "boolean", "null" ] }, "scope": { "type": [ "string", "null" ] }, "consent_text": { "type": [ "string", "null" ] }, "button_text": { "type": [ "string", "null" ] } } } } }, "example": { "general": { "app_enabled": true, "default_locale": "en", "app_locale": "fr", "multi_language_enabled": true, "ignore_orders_before": { "date": null, "order_number": null }, "branding_hidden": false }, "email": { "enabled": true, "from_name": "Example Store", "from_address": "alerts@filemonk.io", "reply_to": "owner@example.com", "report_address": "owner@example.com", "subject": "Your {{shop.name}} {{order.name}} content", "body": "Thanks for purchasing from {{shop.name}}! Click the button below to access the digital content for your order {{order.name}}.", "button": { "text": "Access downloads", "text_color": "#fff", "background_color": "#202223", "border_radius": 5 }, "footer_text": "Facing trouble accessing your content? Contact us right away.", "font_family": "sans-serif", "logo_size": "200", "colors": { "text": "#202223", "background": "#ffffff" }, "css": null, "product_update": { "subject": "Update to {{product_variant.title}} in your order {{order.name}}", "body": "Your most recent purchase for {{product_variant.title}} has been updated. Click the link below to access your updated content." }, "merchant_notifications": { "promotions": true, "usage": true, "licence_exhaustion": false, "licence_exhaustion_threshold": 80 }, "domain": { "custom_address": false, "name": "example-store", "dkim_verified": false } }, "download_page": { "host": "storefront", "path_prefix": "/apps/filemonk", "require_login": null, "email_gate": false, "texts": { "thanks": "Thank you for purchasing from our store! Click on any of the products below to download your content.", "button": "Download", "store_link": "Visit store", "orders_link": "My orders", "orders_index": "My orders", "custom_downloads": "Custom products", "custom_downloads_ready": "Your digital content will be available here when it's ready.", "licence_label": "Licence key", "licence_type_label": "Key", "licence_button": "View", "licence_error": "No licence key available. Contact store.", "login_title": "Customer Login Required", "login_message": "You need to be logged in with the correct account to access your digital orders. Please click the button below to log in or switch to the appropriate account.", "login_button": "Log In", "total_label": "Total", "files_label": "files", "downloading": "Downloading...", "processing": "Processing order. Please wait.", "processing_button": "Processing...", "preorder": "This product is currently in preorder and will be available for download on {{date}}.", "watermarking": "Watermarking is not complete, please wait or reload the page to check again.", "generic_error": "Something went wrong.", "copy_button": "Copy", "copied": "Copied to clipboard", "not_available": "Not Available" }, "colors": { "text": "#202223", "background": "#f6f7f7", "section": "#ffffff", "button_text": "#FFF", "button_background": "#1B76FF" }, "show_price": true, "show_image": true, "show_store_link": true, "show_orders_link": true, "pdf_viewer": false, "hide_file_extensions": false, "price_format": "{{currency_symbol}}{{amount}}", "logo_size": 100, "css": null, "store_url": "example-store.myshopify.com", "default_view": "files" }, "download_limits": { "show": false, "per_file_count": null, "days": null, "messages": { "limit_reached": "Sorry! This file is no longer available to download.", "count": "Maximum downloads per file: ", "days": "Available to download until" } }, "order_conditions": { "check_status": true, "status_type": "fulfillment", "financial_status": "", "fulfillment_status": "fulfilled", "shipment_status": "", "revoke_on_mismatch": false, "refunded_order_protection": false, "fraud_protection": false, "process_orders_on_update": false }, "shopify_sync": { "add_order_tags": false, "order_tags": "filemonk_order", "mark_line_items_fulfilled": false, "skip_fulfillment_for_tags": null, "add_tracking_info": true }, "watermark": { "enabled": true, "all_files": true, "text": "Licensed to {{order.customer_name}} ({{order.email_or_phone}}), order {{order.name}}. Please don't share this file.", "style": "center", "layer": "above", "opacity": 30, "font": { "size": 30, "color": "#ff0018", "name": "Courier New Bold" } }, "customer_accounts": { "button_text": "Download files", "product_downloads_subtitle": "Downloads available", "order_status": { "thanks_text": "Thanks for your purchase! Click the button below to access your files.", "button_text": "Access downloads", "thank_you_page_button": true, "order_status_page_button": true } }, "eu_withdrawal": { "enabled": false, "scope": "eu_only", "consent_text": "I request immediate access to this digital content and acknowledge that I lose my right of withdrawal once the download begins.", "button_text": "Confirm and download" } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "change settings", "turn off the download email", "set download limit", "enable watermarking", "change order tags", "update email subject", "set the download page colours" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "general": { "type": "object", "additionalProperties": false, "properties": { "app_enabled": { "type": [ "boolean", "null" ] }, "default_locale": { "type": "string" }, "app_locale": { "type": "string" }, "multi_language_enabled": { "type": "boolean" }, "ignore_orders_before": { "type": "object", "additionalProperties": false, "properties": { "date": { "type": [ "string", "null" ], "description": "ISO 8601 date or time." }, "order_number": { "type": [ "integer", "null" ] } } }, "branding_hidden": { "type": [ "boolean", "null" ] } } }, "email": { "type": "object", "additionalProperties": false, "properties": { "enabled": { "type": [ "boolean", "null" ] }, "from_name": { "type": [ "string", "null" ] }, "from_address": { "type": [ "string", "null" ] }, "reply_to": { "type": [ "string", "null" ] }, "report_address": { "type": [ "string", "null" ] }, "subject": { "type": [ "string", "null" ] }, "body": { "type": [ "string", "null" ] }, "button": { "type": "object", "additionalProperties": false, "properties": { "text": { "type": [ "string", "null" ] }, "text_color": { "type": [ "string", "null" ] }, "background_color": { "type": [ "string", "null" ] }, "border_radius": { "type": [ "integer", "null" ] } } }, "footer_text": { "type": [ "string", "null" ] }, "font_family": { "type": [ "string", "null" ] }, "logo_size": { "type": "string" }, "colors": { "type": "object", "additionalProperties": false, "properties": { "text": { "type": [ "string", "null" ] }, "background": { "type": [ "string", "null" ] } } }, "css": { "type": [ "string", "null" ] }, "product_update": { "type": "object", "additionalProperties": false, "properties": { "subject": { "type": [ "string", "null" ] }, "body": { "type": [ "string", "null" ] } } }, "merchant_notifications": { "type": "object", "additionalProperties": false, "properties": { "promotions": { "type": [ "boolean", "null" ] }, "usage": { "type": [ "boolean", "null" ] }, "licence_exhaustion": { "type": [ "boolean", "null" ] }, "licence_exhaustion_threshold": { "type": [ "integer", "null" ] } } }, "domain": { "type": "object", "additionalProperties": false, "properties": { "custom_address": { "type": [ "boolean", "null" ] }, "name": { "type": [ "string", "null" ] }, "dkim_verified": { "type": "boolean", "readOnly": true } } } } }, "download_page": { "type": "object", "additionalProperties": false, "properties": { "host": { "type": [ "string", "null" ], "enum": [ "filemonk", "storefront", "customer_account", null ] }, "path_prefix": { "type": [ "string", "null" ] }, "require_login": { "type": [ "boolean", "null" ] }, "email_gate": { "type": "boolean" }, "texts": { "type": "object", "additionalProperties": false, "properties": { "thanks": { "type": [ "string", "null" ] }, "button": { "type": [ "string", "null" ] }, "store_link": { "type": [ "string", "null" ] }, "orders_link": { "type": [ "string", "null" ] }, "orders_index": { "type": [ "string", "null" ] }, "custom_downloads": { "type": [ "string", "null" ] }, "custom_downloads_ready": { "type": [ "string", "null" ] }, "licence_label": { "type": "string" }, "licence_type_label": { "type": "string" }, "licence_button": { "type": [ "string", "null" ] }, "licence_error": { "type": "string" }, "login_title": { "type": [ "string", "null" ] }, "login_message": { "type": [ "string", "null" ] }, "login_button": { "type": [ "string", "null" ] }, "total_label": { "type": [ "string", "null" ] }, "files_label": { "type": [ "string", "null" ] }, "downloading": { "type": [ "string", "null" ] }, "processing": { "type": [ "string", "null" ] }, "processing_button": { "type": [ "string", "null" ] }, "preorder": { "type": [ "string", "null" ] }, "watermarking": { "type": [ "string", "null" ] }, "generic_error": { "type": [ "string", "null" ] }, "copy_button": { "type": [ "string", "null" ] }, "copied": { "type": [ "string", "null" ] }, "not_available": { "type": [ "string", "null" ] }, "gate_title": { "type": [ "string", "null" ] }, "gate_intro": { "type": [ "string", "null" ] }, "gate_order_number_label": { "type": [ "string", "null" ] }, "gate_order_number_placeholder": { "type": [ "string", "null" ] }, "gate_email_label": { "type": [ "string", "null" ] }, "gate_button": { "type": [ "string", "null" ] }, "gate_no_match": { "type": [ "string", "null" ] }, "gate_too_many_attempts": { "type": [ "string", "null" ] } } }, "colors": { "type": "object", "additionalProperties": false, "properties": { "text": { "type": [ "string", "null" ] }, "background": { "type": [ "string", "null" ] }, "section": { "type": [ "string", "null" ] }, "button_text": { "type": [ "string", "null" ] }, "button_background": { "type": [ "string", "null" ] } } }, "show_price": { "type": [ "boolean", "null" ] }, "show_image": { "type": [ "boolean", "null" ] }, "show_store_link": { "type": [ "boolean", "null" ] }, "show_orders_link": { "type": [ "boolean", "null" ] }, "pdf_viewer": { "type": "boolean" }, "hide_file_extensions": { "type": [ "boolean", "null" ] }, "price_format": { "type": [ "string", "null" ] }, "logo_size": { "type": [ "integer", "null" ] }, "css": { "type": [ "string", "null" ] }, "store_url": { "type": [ "string", "null" ] }, "default_view": { "type": [ "string", "null" ] } } }, "download_limits": { "type": "object", "additionalProperties": false, "properties": { "show": { "type": [ "boolean", "null" ], "description": "Whether the download page shows the buyer the limits. Display only: the limits apply either way." }, "per_file_count": { "type": [ "integer", "null" ], "description": "How many times each file can be downloaded per order. null means unlimited." }, "days": { "type": [ "integer", "null" ], "description": "How many days after the order the files stay downloadable. null means unlimited." }, "messages": { "type": "object", "additionalProperties": false, "properties": { "limit_reached": { "type": [ "string", "null" ] }, "count": { "type": [ "string", "null" ] }, "days": { "type": [ "string", "null" ] } } } } }, "order_conditions": { "type": "object", "additionalProperties": false, "properties": { "check_status": { "type": [ "boolean", "null" ] }, "status_type": { "type": [ "string", "null" ] }, "financial_status": { "type": [ "string", "null" ] }, "fulfillment_status": { "type": [ "string", "null" ] }, "shipment_status": { "type": [ "string", "null" ] }, "revoke_on_mismatch": { "type": [ "boolean", "null" ] }, "refunded_order_protection": { "type": [ "boolean", "null" ] }, "fraud_protection": { "type": [ "boolean", "null" ] }, "process_orders_on_update": { "type": "boolean" } } }, "shopify_sync": { "type": "object", "additionalProperties": false, "properties": { "add_order_tags": { "type": [ "boolean", "null" ] }, "order_tags": { "type": [ "string", "null" ] }, "mark_line_items_fulfilled": { "type": "boolean" }, "skip_fulfillment_for_tags": { "type": [ "string", "null" ] }, "add_tracking_info": { "type": [ "boolean", "null" ] } } }, "watermark": { "type": "object", "additionalProperties": false, "properties": { "enabled": { "type": "boolean" }, "all_files": { "type": [ "boolean", "null" ] }, "text": { "type": "string" }, "style": { "type": "string" }, "layer": { "type": "string" }, "opacity": { "type": "integer" }, "font": { "type": "object", "additionalProperties": false, "properties": { "size": { "type": "integer" }, "color": { "type": "string" }, "name": { "type": "string" } } } } }, "customer_accounts": { "type": "object", "additionalProperties": false, "properties": { "button_text": { "type": [ "string", "null" ] }, "product_downloads_subtitle": { "type": [ "string", "null" ] }, "order_status": { "type": "object", "additionalProperties": false, "properties": { "thanks_text": { "type": [ "string", "null" ] }, "button_text": { "type": [ "string", "null" ] }, "thank_you_page_button": { "type": [ "boolean", "null" ] }, "order_status_page_button": { "type": [ "boolean", "null" ] } } } } }, "eu_withdrawal": { "type": "object", "additionalProperties": false, "properties": { "enabled": { "type": "boolean" }, "scope": { "type": "string", "enum": [ "eu_only", "all_customers" ] }, "consent_text": { "type": [ "string", "null" ] }, "button_text": { "type": [ "string", "null" ] } } } } }, "example": { "email": { "subject": "Your downloads are ready", "button": { "text": "Download now" } }, "download_limits": { "per_file_count": 5 } } } } } } }, "/settings/checkout_profiles": { "get": { "operationId": "get_settings_checkout_profiles", "summary": "Checkout Profiles", "description": "List the shop's checkout and accounts configurations (Shopify checkout profiles) and which one is published, as the order status page setup shows before the merchant adds Filemonk's block. Read-only: adding the block happens in Shopify's checkout editor, which an agent can't open.\n\n**Note:** Asks Shopify; large shops page slowly (Shopify throttles this list). 502 when Shopify did not answer.", "tags": [ "Settings" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "published" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "published" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "published": { "type": [ "boolean", "null" ] } } } }, "published": { "type": [ "string", "null" ] } } }, "example": { "data": [ { "id": "gid://shopify/CheckoutProfile/1234567", "name": "Default checkout", "published": true }, { "id": "gid://shopify/CheckoutProfile/1234568", "name": "Holiday checkout", "published": false } ], "published": "Default checkout" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/BadGateway" } }, "x-aliases": [ "theme configurations", "checkout profiles", "which checkout is published", "order status page setup" ] } }, "/settings/email_domain": { "get": { "operationId": "get_settings_email_domain", "summary": "Email Domain", "description": "The custom sending domain taken from the reply-to address, whether its DKIM records are verified, and the DNS records still to add when they are not. Runs the same check as Settings > Email.", "tags": [ "Settings" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object", "required": [ "reply_to", "domain", "custom_address", "dkim" ], "properties": { "reply_to": { "type": [ "string", "null" ] }, "domain": { "type": [ "string", "null" ] }, "custom_address": { "type": [ "boolean", "null" ] }, "dkim": { "type": "object", "required": [ "verified", "records" ], "properties": { "verified": { "type": [ "boolean", "null" ] }, "records": { "type": "array" } } } } }, "example": { "reply_to": "owner@example.com", "domain": "example.com", "custom_address": false, "dkim": { "verified": false, "records": [] } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "is my email domain verified", "dkim records", "dns records for sending email", "email domain status" ] } }, "/settings/test_email": { "post": { "operationId": "post_settings_test_email", "summary": "Test Email", "description": "Send a preview of the download email to the merchant (to; default the shop's email), built from one of the shop's own orders, as the email settings page's Send test email does.\n\n**Note:** Nothing is charged and no order changes. 422 when the shop has no order to build the preview from; 409 when the shop's email sending is blocked.", "tags": [ "Settings" ], "responses": { "200": { "description": "Success — the write completed; the body is the updated resource.", "content": { "application/json": { "schema": { "type": "object", "required": [ "sent", "to" ], "properties": { "sent": { "type": [ "boolean", "null" ] }, "to": { "type": [ "string", "null" ] } } }, "example": { "sent": true, "to": "owner@example.com" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/BadGateway" } }, "x-aliases": [ "send test email", "preview the download email", "email me a test", "check the email template" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "to": {} } }, "example": { "to": "owner@example.com" } } } } } }, "/settings/texts": { "get": { "operationId": "get_settings_texts", "summary": "Texts", "description": "Read the customer-facing texts in one locale, as the settings Translate view shows them: the download email, download page, download limit messages, order status and customer account blocks, and the EU withdrawal consent. locale defaults to the shop's default language. Values are what is stored for that locale only; untranslated lists the texts not translated yet (buyers see the default language there).\n\n**Note:** Paths match GET /settings. Write them with PATCH /settings/texts; fill a whole locale with Filemonk's own translation using POST /settings/texts/setup.", "tags": [ "Settings" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object", "required": [ "locale", "default_locale", "multi_language_enabled", "shop_locales", "setup_locales", "texts", "untranslated" ], "properties": { "locale": { "type": [ "string", "null" ] }, "default_locale": { "type": [ "string", "null" ] }, "multi_language_enabled": { "type": [ "boolean", "null" ] }, "shop_locales": { "type": "array", "items": { "type": [ "string", "null" ] } }, "setup_locales": { "type": "array", "items": { "type": [ "string", "null" ] } }, "texts": { "type": "object", "required": [ "email", "download_page" ], "properties": { "email": { "type": "object", "required": [ "subject", "button" ], "properties": { "subject": { "type": [ "string", "null" ] }, "button": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": [ "string", "null" ] } } } } }, "download_page": { "type": "object", "required": [ "texts" ], "properties": { "texts": { "type": "object", "required": [ "thanks", "button" ], "properties": { "thanks": { "type": [ "string", "null" ] }, "button": {} } } } } } }, "untranslated": { "type": "array", "items": { "type": [ "string", "null" ] } } } }, "example": { "locale": "fr", "default_locale": "en", "multi_language_enabled": true, "shop_locales": [ "en", "fr" ], "setup_locales": [ "pt-BR", "zh", "da", "nl", "en", "pt-PT", "fr", "de", "it", "ja", "ko", "nb", "es", "sv", "tr", "zh-TW", "pl" ], "texts": { "email": { "subject": "Vos téléchargements sont prêts", "button": { "text": "Télécharger" } }, "download_page": { "texts": { "thanks": "Merci pour votre commande", "button": null } } }, "untranslated": [ "download_page.texts.button" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "translations", "read translated texts", "what does the download page say in french", "which texts are not translated", "email text in german" ], "parameters": [ { "name": "locale", "in": "query", "required": false, "schema": { "type": "string" }, "example": "fr" } ] }, "patch": { "operationId": "patch_settings_texts", "summary": "Texts", "description": "Change customer-facing texts in one locale, as the settings Translate view does: send locale and texts, a partial tree with the same paths GET /settings/texts returns (for example {\"email\": {\"subject\": \"…\"}, \"download_page\": {\"texts\": {\"button\": \"…\"}}}). Answers with that locale's texts after the save.\n\n**Note:** locale defaults to the shop's default language. Another locale needs multi-language on (409 multi_language_disabled). null clears a translation so buyers see the default language. The same checks as the dashboard run (email copy is spam-checked, the download button can't be blank).", "tags": [ "Settings" ], "responses": { "200": { "description": "Success — the write completed; the body is the updated resource.", "content": { "application/json": { "schema": { "type": "object", "required": [ "locale", "texts", "untranslated" ], "properties": { "locale": { "type": [ "string", "null" ] }, "texts": { "type": "object", "required": [ "email", "download_page" ], "properties": { "email": { "type": "object", "required": [ "subject", "button" ], "properties": { "subject": { "type": [ "string", "null" ] }, "button": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": [ "string", "null" ] } } } } }, "download_page": { "type": "object", "required": [ "texts" ], "properties": { "texts": { "type": "object", "required": [ "thanks", "button" ], "properties": { "thanks": { "type": [ "string", "null" ] }, "button": {} } } } } } }, "untranslated": { "type": "array", "items": { "type": [ "string", "null" ] } } } }, "example": { "locale": "fr", "texts": { "email": { "subject": "Vos téléchargements sont prêts", "button": { "text": "Télécharger" } }, "download_page": { "texts": { "thanks": "Merci pour votre commande", "button": null } } }, "untranslated": [ "download_page.texts.button" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "translate the download email", "change french texts", "set german download page text", "fix a translation" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "texts": {}, "locale": {} } }, "example": { "locale": "fr", "texts": { "email": { "subject": "Vos téléchargements sont prêts" } } } } } } } }, "/settings/texts/setup": { "post": { "operationId": "post_settings_texts_setup", "summary": "Texts Setup", "description": "Set up a language, as the settings Translate view's \"Translate\" does: fill every customer-facing text in locale with Filemonk's own translation (from_locale, default the same locale). Answers with that locale's texts after the fill. Send it first without `confirm`. Nothing changes and the 409 `confirmation_required` says what would. Tell the merchant, ask, and resend with `confirm: true` only after they agree.\n\n**Note:** Overwrites every text in that locale, including ones the merchant edited, so without confirm: true nothing changes: 409 confirmation_required says how many texts would be replaced. setup_locales on GET /settings/texts lists the languages Filemonk has a translation for.", "tags": [ "Settings" ], "responses": { "200": { "description": "Success — the write completed; the body is the updated resource.", "content": { "application/json": { "schema": { "type": "object", "required": [ "locale", "from_locale", "texts", "untranslated" ], "properties": { "locale": { "type": [ "string", "null" ] }, "from_locale": { "type": [ "string", "null" ] }, "texts": { "type": "object", "required": [ "email", "download_page" ], "properties": { "email": { "type": "object", "required": [ "subject", "button" ], "properties": { "subject": { "type": [ "string", "null" ] }, "button": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": [ "string", "null" ] } } } } }, "download_page": { "type": "object", "required": [ "texts" ], "properties": { "texts": { "type": "object", "required": [ "thanks", "button" ], "properties": { "thanks": { "type": [ "string", "null" ] }, "button": {} } } } } } }, "untranslated": { "type": "array" } } }, "example": { "locale": "fr", "from_locale": "fr", "texts": { "email": { "subject": "Vos téléchargements sont prêts", "button": { "text": "Télécharger" } }, "download_page": { "texts": { "thanks": "Merci pour votre commande", "button": null } } }, "untranslated": [] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "set up french", "translate everything to german", "add a language", "reset translations" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "locale": {}, "from_locale": {}, "confirm": {} } }, "example": { "locale": "fr", "from_locale": "fr", "confirm": true } } } } } } }, "components": { "headers": { "X-RateLimit-Limit": { "description": "Points per 60-second window (40).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Points left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time (seconds) when the current window ends.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-Auth-Token" }, "BearerAuth": { "type": "http", "scheme": "bearer" } }, "schemas": { "Error": { "type": "object", "description": "Error envelope returned by every failed request. `errors` is always an array of sentences.", "properties": { "errors": { "type": "array", "items": { "type": "string" } }, "code": { "type": "string", "description": "Machine-readable reason when there is one: `rate_limited`, `shopify_error`, `unknown_parameters`, `not_found`, ..." }, "retry_after": { "type": "integer", "description": "Seconds to wait, on 429." }, "field_errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "On a 422 that validated field by field: dotted field path => messages." }, "unknown": { "type": "array", "items": { "type": "string" }, "description": "On `unknown_parameters`: the keys the action does not take." }, "accepted": { "type": "array", "items": { "type": "string" }, "description": "On `unknown_parameters`: the keys it does take." }, "error": { "type": "string", "description": "On 429 only, kept for API v1 clients; read `errors`." }, "message": { "type": "string", "description": "On 429 only, kept for API v1 clients; read `errors`." } }, "required": [ "errors" ], "example": { "errors": [ "name is required" ] } }, "PageMeta": { "type": "object", "description": "Paging of a list (`page`, `per_page` query params).", "required": [ "total_count", "page", "per_page", "total_pages" ], "properties": { "total_count": { "type": "integer", "description": "Rows across all pages." }, "page": { "type": "integer", "description": "1-based page number." }, "per_page": { "type": "integer", "description": "Rows per page, max 200." }, "total_pages": { "type": "integer" } } } }, "responses": { "Unauthorized": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "errors": [ "Invalid API key" ] } } } }, "NotFound": { "description": "The resource does not exist for this shop, or the action path is not registered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "errors": [ "Order not found: c3d4e5f6-7a8b-4c9d-8e0f-1a2b3c4d5e6f" ] } } } }, "Conflict": { "description": "The request conflicts with the current state (an order Shopify is not ready to fulfil, a digital product that already exists). Nothing was changed; read the message, don't retry blindly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "errors": [ "This product already has a digital product" ] } } } }, "ValidationError": { "description": "The request failed validation, or sent a key the action does not take (`code: \"unknown_parameters\"` with `unknown` and `accepted`). Nothing was saved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "validation": { "value": { "errors": [ "access.download_limit_count must be an integer of at least 0" ], "field_errors": { "access.download_limit_count": [ "must be an integer of at least 0" ] } } }, "unknown_parameters": { "value": { "errors": [ "Unknown parameter for GET /orders: state. It accepts: page, per_page, search, financial_status." ], "code": "unknown_parameters", "unknown": [ "state" ], "accepted": [ "page", "per_page", "search", "financial_status" ] } } } } } }, "RateLimited": { "description": "Rate limited. Cost-weighted per API key, shared with API v1: a read costs 1 point, a write 2, 40 points per fixed 60-second window. Every response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` (Unix time the window ends); a 429 adds `Retry-After` (seconds), `retry_after`, `retryable: true` and a `next_step` in the body. A 429 did nothing: wait `retry_after` seconds, then send the same request again. The budget is per key, so every tool or script using the key shares it; prefer one list call with `per_page` over many single reads.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "errors": [ "You have exceeded the rate limit of 40 points per 60 seconds. Read requests cost 1 point(s) and write requests cost 2 point(s). Please retry after 12 second(s)." ], "code": "rate_limited", "retry_after": 12, "error": "Rate limit exceeded", "message": "You have exceeded the rate limit of 40 points per 60 seconds. Read requests cost 1 point(s) and write requests cost 2 point(s). Please retry after 12 second(s)." } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "BadGateway": { "description": "Shopify (or the email service) did not complete the request. Nothing was changed; try again shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "errors": [ "Shopify did not complete the request. Nothing was changed; try again shortly." ], "code": "shopify_error" } } } } } } }