{"openapi":"3.0.3","info":{"title":"Management Store Etsy Public API","version":"v1","description":"REST API for Etsy shop and order data, including manual fulfillment updates. Authenticate with Bearer API keys (mse_ prefix).\n\nv1 exposes GET endpoints (list/get orders, list shops) and write endpoints for manual fulfillment (PATCH/DELETE). Keys are created in the web app under Settings → API access.\nDefault key scopes are orders:read and shops:read. Opt in to orders:write when creating a key to update or cancel manual fulfillment.\nEach API key is tenant-scoped: it can only access shops linked to the license keys owned by the key creator.\nROOT/ADMIN users do not get system-wide access via API keys — only license-owned shops apply.\nList endpoints accept multiple query parameters at once (filters combine with AND).\nOrders: shopEtsyId accepts multiple shops: repeat ?shopEtsyId=a&shopEtsyId=b or comma-separated ?shopEtsyId=a,b. Alias query key: shop.\nNever log or commit raw API keys. Use environment variables or secret managers in production integrations.\n\nList responses use { data: T[], pagination: { page, limit, total, totalPages } }.\nSingle-resource responses use { data: T } (no pagination).\nErrors return { error: string, code?: string } with appropriate HTTP status.\n\nRate limit: 60 requests per 60s per API key."},"servers":[{"url":"https://etsy.lntech-ecommerce.com"}],"tags":[{"name":"Orders"},{"name":"Shops"}],"paths":{"/api/v1/orders":{"get":{"operationId":"listOrders","summary":"List orders","description":"Returns a paginated list of orders for shops accessible to your API key. Combine filters (shops, dates, search, fulfillment, tracking, sort). Requires the orders:read scope.\n\nRequired scope: `orders:read`.","tags":["Orders"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"page","in":"query","required":false,"description":"Page number (1-based). Default: 1.","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","required":false,"description":"Items per page (max 100). Default: 20.","schema":{"type":"integer","minimum":1,"default":20}},{"name":"shopEtsyId","in":"query","required":false,"description":"Filter one or more shops by Etsy shop ID (shopEtsyId from the response). Add multiple IDs below or use comma-separated values. Omit for all accessible shops.","style":"form","explode":true,"schema":{"type":"array","items":{"type":"string"}}},{"name":"search","in":"query","required":false,"description":"Search order ID, recipient name, or address fields.","schema":{"type":"string"}},{"name":"startDate","in":"query","required":false,"description":"Inclusive start date (YYYY-MM-DD) for orderDate filter.","schema":{"type":"string","format":"date"}},{"name":"endDate","in":"query","required":false,"description":"Inclusive end date (YYYY-MM-DD) for orderDate filter.","schema":{"type":"string","format":"date"}},{"name":"timeZone","in":"query","required":false,"description":"IANA time zone for date filters. Default: Asia/Bangkok.","schema":{"type":"string","default":"Asia/Bangkok"}},{"name":"fulfillmentStatus","in":"query","required":false,"description":"Filter by fulfillment: fulfilled, synced_to_provider, manual, pending, or failed.","schema":{"type":"string"}},{"name":"tracking","in":"query","required":false,"description":"Filter by tracking: has (with tracking number) or none.","schema":{"type":"string"}},{"name":"sortBy","in":"query","required":false,"description":"Sort field: orderDate, orderId, recipientName, totalCost, or shop. Default: orderDate.","schema":{"type":"string","default":"orderDate"}},{"name":"sortOrder","in":"query","required":false,"description":"asc or desc. Default: desc.","schema":{"type":"string","default":"desc"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Order"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/orders/{id}":{"get":{"operationId":"getOrder","summary":"Get order","description":"Returns a single order by its internal UUID (`id` from the list response), including line items and shop summary. The order must belong to a shop accessible to your API key. Requires the orders:read scope.\n\nRequired scope: `orders:read`.","tags":["Orders"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Internal order UUID from the list response `id` field (not the Etsy receipt / orderId).","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Order"}},"required":["data"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/orders/{id}/manual-fulfillment":{"post":{"operationId":"markManualFulfillment","summary":"Mark as manual fulfillment","description":"Marks an order as manually fulfilled (`fulfillmentProviderType` = manual). Idempotent if already manual. Fails with 409 if the order is already synced to a real fulfillment provider. Optional tracking (`trackingNumber`, `trackingCompany`, `trackingUrl`) may be set only in this request — there is no separate public API to update tracking later. Requires the orders:write scope.\n\nRequired scope: `orders:write`.","tags":["Orders"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Internal order UUID from the list response `id` field (not the Etsy receipt / orderId).","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ManualFulfillmentMarkResult"}},"required":["data"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManualFulfillmentMark"}}}}},"delete":{"operationId":"cancelManualFulfillment","summary":"Cancel manual fulfillment","description":"Removes manual fulfillment from an order (inverse of mark): clears `fulfillmentProviderType`, deletes stored manual tracking, and recomputes `hasTracking`. Requires the orders:write scope. The order must already be manually fulfilled.\n\nRequired scope: `orders:write`.","tags":["Orders"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Internal order UUID from the list response `id` field (not the Etsy receipt / orderId).","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ManualFulfillmentCancelResult"}},"required":["data"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/orders/{id}/base-cost":{"patch":{"operationId":"updateOrderBaseCost","summary":"Update order base cost","description":"Sets or clears the internal cost of goods (`totalBaseCost`) for an order. Pass a non-negative number in dollars, or `null` to clear. Also updates `baseCostUpdatedAt`. Requires the orders:write scope. The order must belong to a shop accessible to your API key.\n\nRequired scope: `orders:write`.","tags":["Orders"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Internal order UUID from the list response `id` field (not the Etsy receipt / orderId).","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BaseCostUpdateResult"}},"required":["data"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseCostUpdate"}}}}}},"/api/v1/shops":{"get":{"operationId":"listShops","summary":"List shops","description":"Returns a paginated list of shops accessible to your API key. Filter by status or search by name / Etsy shop ID. Requires the shops:read scope.\n\nRequired scope: `shops:read`.","tags":["Shops"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"page","in":"query","required":false,"description":"Page number (1-based). Default: 1.","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","required":false,"description":"Items per page (max 100). Default: 20.","schema":{"type":"integer","minimum":1,"default":20}},{"name":"search","in":"query","required":false,"description":"Search by shop name or Etsy shop ID.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Filter by shop status: ACTIVE only (API keys only access active shops).","schema":{"type":"string"}},{"name":"sortBy","in":"query","required":false,"description":"Sort field: shopName, shopEtsyId, lastSyncAt, or createdAt. Default: shopName.","schema":{"type":"string","default":"shopName"}},{"name":"sortOrder","in":"query","required":false,"description":"asc or desc. Default: asc.","schema":{"type":"string","default":"asc"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ShopResource"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"Bearer token with mse_ prefix."}},"schemas":{"Pagination":{"type":"object","properties":{"page":{"type":"integer","example":1,"description":"Current page number"},"limit":{"type":"integer","example":20,"description":"Items per page"},"total":{"type":"integer","example":142,"description":"Total matching records"},"totalPages":{"type":"integer","example":8,"description":"Total pages available"}},"required":["page","limit","total","totalPages"]},"Error":{"type":"object","properties":{"error":{"type":"string","example":"Unauthorized","description":"Human-readable error description"},"code":{"type":"string","example":"MISSING_API_KEY","description":"Machine-readable error code"}},"required":["error"]},"Shop":{"type":"object","nullable":true,"properties":{"id":{"type":"string","example":"shop_clx123456"},"shopName":{"type":"string","example":"My Custom Gift Shop"},"shopEtsyId":{"type":"string","example":"12345678"}},"required":["id","shopName","shopEtsyId"]},"ShopResource":{"type":"object","properties":{"id":{"type":"string","example":"shop_clx123456"},"shopName":{"type":"string","example":"My Custom Gift Shop"},"shopEtsyId":{"type":"string","example":"12345678"},"avatar":{"type":"string","nullable":true,"example":"https://i.etsystatic.com/isla/…/75x75.jpg"},"status":{"type":"string","enum":["ACTIVE","INACTIVE"],"example":"ACTIVE"},"syncStatus":{"type":"string","enum":["success","failed","pending"],"example":"success"},"lastSyncAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","shopName","shopEtsyId","avatar","status","syncStatus","lastSyncAt","createdAt","updatedAt"]},"OrderItem":{"type":"object","properties":{"id":{"type":"string","example":"item_clx987654"},"productIdentifier":{"type":"string","nullable":true,"example":"TSHIRT-XL-BLK"},"productTitle":{"type":"string","nullable":true,"example":"Personalized Family T-Shirt"},"productImageUrl":{"type":"string","nullable":true,"example":"https://img.etsystatic.com/..."},"quantity":{"type":"integer","example":2},"itemCost":{"type":"number","nullable":true,"example":24.99},"itemCostFormatted":{"type":"string","nullable":true,"example":"$24.99"},"variations":{"type":"string","nullable":true,"example":"Size: XL, Color: Black"},"personalizeNote":{"type":"string","nullable":true,"example":"Text: 'Mama Bear'"},"transactionId":{"type":"string","nullable":true,"example":"2847192847"},"listingId":{"type":"string","nullable":true,"example":"109823471"},"productId":{"type":"string","nullable":true,"example":"847291048"}},"required":["id","quantity"]},"Order":{"type":"object","properties":{"id":{"type":"string","example":"ord_clx112233"},"shopId":{"type":"string","example":"shop_clx123456"},"orderId":{"type":"string","example":"3182947102"},"orderDate":{"type":"string","format":"date-time","nullable":true},"orderUrl":{"type":"string","nullable":true},"totalCost":{"type":"number","nullable":true,"example":54.98},"totalCostFormatted":{"type":"string","nullable":true,"example":"$54.98"},"totalBaseCost":{"type":"number","nullable":true,"example":22},"baseCostUpdatedAt":{"type":"string","format":"date-time","nullable":true,"example":"2026-08-04T08:00:00.000Z"},"currencyCode":{"type":"string","example":"USD"},"itemsCost":{"type":"number","nullable":true,"example":49.98},"shippingCost":{"type":"number","nullable":true,"example":5},"taxCost":{"type":"number","nullable":true,"example":0},"discount":{"type":"number","nullable":true,"example":0},"recipientName":{"type":"string","nullable":true,"example":"Jane Doe"},"recipientEmail":{"type":"string","nullable":true},"recipientPhone":{"type":"string","nullable":true},"addressLine1":{"type":"string","nullable":true,"example":"123 Main St"},"addressLine2":{"type":"string","nullable":true},"city":{"type":"string","nullable":true,"example":"New York"},"state":{"type":"string","nullable":true,"example":"NY"},"zip":{"type":"string","nullable":true,"example":"10001"},"country":{"type":"string","nullable":true,"example":"United States"},"noteFromBuyer":{"type":"string","nullable":true},"expectedShipDate":{"type":"string","format":"date-time","nullable":true},"paymentDate":{"type":"string","format":"date-time","nullable":true},"shippingMethod":{"type":"string","nullable":true,"example":"USPS First Class"},"hasTracking":{"type":"boolean","example":true},"fulfillmentProviderType":{"type":"string","nullable":true,"example":"lenful"},"providerStatus":{"type":"string","nullable":true,"example":"processing"},"lenfulSyncStatus":{"type":"string","enum":["PENDING","SUCCESS","FAILED","PROCESSING"],"example":"SUCCESS"},"merchizeSyncStatus":{"type":"string","enum":["PENDING","SUCCESS","FAILED","PROCESSING"],"example":"PENDING"},"mangoteeSyncStatus":{"type":"string","enum":["PENDING","SUCCESS","FAILED","PROCESSING"],"example":"PENDING"},"burgerPrintsSyncStatus":{"type":"string","enum":["PENDING","SUCCESS","FAILED","PROCESSING"],"example":"PENDING"},"syncedAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"shop":{"type":"object","nullable":true,"properties":{"id":{"type":"string","example":"shop_clx123456"},"shopName":{"type":"string","example":"My Custom Gift Shop"},"shopEtsyId":{"type":"string","example":"12345678"}},"required":["id","shopName","shopEtsyId"]},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"item_clx987654"},"productIdentifier":{"type":"string","nullable":true,"example":"TSHIRT-XL-BLK"},"productTitle":{"type":"string","nullable":true,"example":"Personalized Family T-Shirt"},"productImageUrl":{"type":"string","nullable":true,"example":"https://img.etsystatic.com/..."},"quantity":{"type":"integer","example":2},"itemCost":{"type":"number","nullable":true,"example":24.99},"itemCostFormatted":{"type":"string","nullable":true,"example":"$24.99"},"variations":{"type":"string","nullable":true,"example":"Size: XL, Color: Black"},"personalizeNote":{"type":"string","nullable":true,"example":"Text: 'Mama Bear'"},"transactionId":{"type":"string","nullable":true,"example":"2847192847"},"listingId":{"type":"string","nullable":true,"example":"109823471"},"productId":{"type":"string","nullable":true,"example":"847291048"}},"required":["id","quantity"]}}},"required":["id","shopId","orderId","currencyCode","hasTracking","lenfulSyncStatus","merchizeSyncStatus","mangoteeSyncStatus","burgerPrintsSyncStatus","syncedAt","createdAt","updatedAt","items"]},"ManualFulfillmentMark":{"type":"object","properties":{"trackingNumber":{"type":"string","example":"1Z999AA10123456784","description":"Optional carrier tracking number applied after marking as manual."},"trackingCompany":{"type":"string","example":"UPS"},"trackingUrl":{"type":"string","format":"uri","example":"https://www.ups.com/track?tracknum=1Z999AA10123456784"}}},"ManualFulfillmentMarkResult":{"type":"object","properties":{"id":{"type":"string","example":"ord_clx112233"},"fulfillmentProviderType":{"type":"string","enum":["manual"],"example":"manual"},"hasTracking":{"type":"boolean","example":false},"tracking":{"type":"object","nullable":true,"properties":{"trackingNumber":{"type":"string","example":"1Z999AA10123456784"},"trackingCompany":{"type":"string","nullable":true,"example":"UPS"},"trackingUrl":{"type":"string","nullable":true,"example":"https://www.ups.com/track?tracknum=1Z999AA10123456784"}},"required":["trackingNumber","trackingCompany","trackingUrl"]},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","fulfillmentProviderType","hasTracking","tracking","updatedAt"]},"ManualFulfillmentCancelResult":{"type":"object","properties":{"id":{"type":"string","example":"ord_clx112233"},"fulfillmentProviderType":{"type":"string","nullable":true,"example":null},"hasTracking":{"type":"boolean","example":false},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","fulfillmentProviderType","hasTracking","updatedAt"]},"BaseCostUpdate":{"type":"object","properties":{"totalBaseCost":{"type":"number","nullable":true,"minimum":0,"description":"Internal cost of goods in dollars. Use null to clear base cost.","example":22}},"required":["totalBaseCost"]},"BaseCostUpdateResult":{"type":"object","properties":{"id":{"type":"string","example":"ord_clx112233"},"totalBaseCost":{"type":"number","nullable":true,"example":22},"baseCostUpdatedAt":{"type":"string","format":"date-time","nullable":true,"example":"2026-08-04T08:00:00.000Z"},"updatedAt":{"type":"string","format":"date-time","example":"2026-08-04T08:00:01.000Z"}},"required":["id","totalBaseCost","baseCostUpdatedAt","updatedAt"]}}}}