{"openapi":"3.1.0","info":{"title":"Birdy Grey Cartographer API","description":"Cartographer prepares Birdy Grey products for add-to-cart and reports when they will arrive.\n\n## Endpoints\n\n- **`POST /lines`** — prepare variants for add-to-cart, including any Rush fee line.\n- **`GET /estimates`** — preview a product's delivery estimates before add-to-cart.\n- **`GET /replacements`** — check whether a variant arrives by a wedding date, and which production method to offer.\n\n## Authentication\n\nPass your API key on every request as the `x-api-key` header.","version":"0.1.0"},"servers":[{"url":"http://localhost:8080","description":"Local"},{"url":"https://api.birdystaging.com","description":"Staging"},{"url":"https://api.birdygrey.com","description":"Production"}],"paths":{"/cartographer/lines":{"post":{"operationId":"postCartographerLines","description":"Prepare one or more variants for add-to-cart, returning each product line plus any Rush fee line.","responses":{"200":{"description":"Flat list of prepared cart lines","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"number"},"lines":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"variantId":{"type":"string"},"quantity":{"type":"number"},"customAttributes":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}},"required":["key","value"]}},"appliedDiscount":{"type":"object","properties":{"valueType":{"const":"PERCENTAGE"},"value":{"type":"number"},"title":{"type":"string"},"description":{"type":"string"}},"required":["valueType","value","title","description"]}},"required":["variantId","quantity","customAttributes"]},{"type":"object","properties":{"merchandiseId":{"type":"string"},"quantity":{"type":"number"},"attributes":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}},"required":["key","value"]}}},"required":["merchandiseId","quantity","attributes"]}]},"description":"Product lines and any Rush fee lines, using the field names `format` selects."}},"required":["count","lines"]},"examples":{"rush":{"summary":"Rush Production","value":{"count":2,"lines":[{"variantId":"gid://shopify/ProductVariant/42629933989965","quantity":1,"customAttributes":[{"key":"_source","value":"EXCHANGE_PARTNER"},{"key":"_READY-TO-SHIP","value":"Expected to arrive in ~3-6 business days"},{"key":"_SHIPPING_SPEED","value":"3-6 days"},{"key":"_rush_fee_amount","value":"8"}]},{"variantId":"gid://shopify/ProductVariant/42613408202829","quantity":1,"customAttributes":[{"key":"_source","value":"EXCHANGE_PARTNER"},{"key":"_original_variant_id","value":"gid://shopify/ProductVariant/42629933989965"},{"key":"_productName","value":"Ash Crepe Dress - Dusty Rose"},{"key":"_productNameWithoutColor","value":"Ash Crepe Dress "},{"key":"_variantName","value":"M / Dusty Rose / Rush Production"},{"key":"_variantNameWithoutArrival","value":"M / Dusty Rose"}]}]}},"rushWaived":{"summary":"Rush Production, fee waived (rushWaived: true)","value":{"count":2,"lines":[{"variantId":"gid://shopify/ProductVariant/42629933989965","quantity":1,"customAttributes":[{"key":"_source","value":"EXCHANGE_PARTNER"},{"key":"_READY-TO-SHIP","value":"Expected to arrive in ~3-6 business days"},{"key":"_SHIPPING_SPEED","value":"3-6 days"},{"key":"_rush_fee_amount","value":"8"}]},{"variantId":"gid://shopify/ProductVariant/42613408202829","quantity":1,"customAttributes":[{"key":"_source","value":"EXCHANGE_PARTNER"},{"key":"_original_variant_id","value":"gid://shopify/ProductVariant/42629933989965"},{"key":"_productName","value":"Ash Crepe Dress - Dusty Rose"},{"key":"_productNameWithoutColor","value":"Ash Crepe Dress "},{"key":"_variantName","value":"M / Dusty Rose / Rush Production"},{"key":"_variantNameWithoutArrival","value":"M / Dusty Rose"}],"appliedDiscount":{"valueType":"PERCENTAGE","value":100,"title":"EXCHANGE_RUSH_WAIVED","description":"Free Rush Fees on Exchanges"}}]}}}}}},"400":{"description":"Invalid request body (failed validation)","content":{"application/json":{"example":{"success":false,"error":[{"kind":"schema","type":"object","expected":"\"source\"","received":"undefined","message":"Invalid key: Expected \"source\" but received undefined","path":[{"type":"object","origin":"key","key":"source"}]}]}}}},"404":{"description":"A requested variant GID did not resolve","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"variantId":{"type":"string"}},"required":["error","variantId"]},"example":{"error":"Variant not found: gid://shopify/ProductVariant/999999999","variantId":"gid://shopify/ProductVariant/999999999"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"source":{"type":"string","minLength":1,"maxLength":100,"description":"Stamped as the `_source` attribute on every returned line (identifies the calling system).","example":"EXCHANGE_PARTNER"},"format":{"enum":["admin","storefront"],"type":"string","description":"Output field-name convention (default 'admin'): 'admin' emits { variantId, quantity, customAttributes } for the Shopify Admin API (e.g. draftOrderCreate); 'storefront' emits { merchandiseId, quantity, attributes } for Hydrogen/Storefront add-to-cart.","example":"admin","default":"admin"},"items":{"type":"array","items":{"type":"object","properties":{"variantId":{"type":"string","pattern":"^(gid:\\/\\/shopify\\/ProductVariant\\/)?\\d+$","description":"ProductVariant identifier — either the full GID (gid://shopify/ProductVariant/<id>) or a bare numeric id, which is normalized to the GID form. Responses always emit GIDs.","example":"gid://shopify/ProductVariant/40075796250701"},"quantity":{"type":"integer","minimum":1,"maximum":100,"description":"Quantity to add (default 1). Reflected on the product line and any rush-fee line.","default":1},"rushWaived":{"type":"boolean","description":"When true, waives the rush fee (default false): in 'admin' format the rush-fee line is returned at full price with a 100% appliedDiscount; in 'storefront' format it is the $0 rush-fee variant. The caller owns eligibility; ignored for non-Rush items.","default":false}},"required":["variantId"]},"minItems":1,"maxItems":50}},"required":["source","items"]}}}}}},"/cartographer/estimates":{"get":{"operationId":"getCartographerEstimates","description":"Preview a product's delivery estimates before add-to-cart, one row per production method it offers.","responses":{"200":{"description":"Delivery estimates per offered production scenario","content":{"application/json":{"schema":{"type":"object","properties":{"productId":{"type":"string"},"count":{"type":"number"},"values":{"type":"array","items":{"type":"object","properties":{"estimatedArrival":{"type":"string"},"arrivalMessage":{"type":"string"},"shippingSpeed":{"type":"string"},"rushFee":{"anyOf":[{"type":"object","properties":{"amount":{"type":"number"},"currency":{"type":"string"}},"required":["amount","currency"]},{"type":"null"}]},"maxArrivalDays":{"type":"number","description":"Calendar days from today until the latest expected arrival, calculated at request time.","example":42},"latestArrivalDate":{"type":"string","description":"Latest expected arrival date (YYYY-MM-DD, UTC) for an order placed today.","example":"2026-07-27"}},"required":["estimatedArrival","arrivalMessage","shippingSpeed","rushFee","maxArrivalDays","latestArrivalDate"]},"description":"One row per production method the product offers. A product without a production choice returns a single Rush Production row with no fee."}},"required":["productId","count","values"]},"examples":{"standardAndRush":{"summary":"Standard + Rush (made-to-order date range)","value":{"productId":"gid://shopify/Product/6861519257677","count":2,"values":[{"estimatedArrival":"Standard Production","arrivalMessage":"Expected to arrive between 07-13-2026 and 07-27-2026","shippingSpeed":"4-6 weeks","rushFee":null,"maxArrivalDays":42,"latestArrivalDate":"2026-07-27"},{"estimatedArrival":"Rush Production","arrivalMessage":"Expected to arrive in ~3-6 business days","shippingSpeed":"3-6 days","rushFee":{"amount":8,"currency":"USD"},"maxArrivalDays":10,"latestArrivalDate":"2026-06-25"}]}},"noDeliveryWindow":{"summary":"No MTO delivery window → single arrival date","value":{"productId":"gid://shopify/Product/6861548585037","count":2,"values":[{"estimatedArrival":"Standard Production","arrivalMessage":"Expected to arrive 07-13-2026","shippingSpeed":"4 weeks","rushFee":null,"maxArrivalDays":28,"latestArrivalDate":"2026-07-13"},{"estimatedArrival":"Rush Production","arrivalMessage":"Expected to arrive in ~3-6 business days","shippingSpeed":"3-6 days","rushFee":{"amount":8,"currency":"USD"},"maxArrivalDays":10,"latestArrivalDate":"2026-06-25"}]}},"rushWaived":{"summary":"Rush fee waived (rushWaived=true)","value":{"productId":"gid://shopify/Product/6861548585037","count":2,"values":[{"estimatedArrival":"Standard Production","arrivalMessage":"Expected to arrive 07-13-2026","shippingSpeed":"4 weeks","rushFee":null,"maxArrivalDays":28,"latestArrivalDate":"2026-07-13"},{"estimatedArrival":"Rush Production","arrivalMessage":"Expected to arrive in ~3-6 business days","shippingSpeed":"3-6 days","rushFee":{"amount":0,"currency":"USD"},"maxArrivalDays":10,"latestArrivalDate":"2026-06-25"}]}},"readyToShip":{"summary":"No Estimated Arrival option (e.g. swatch) → single Rush row, no fee","value":{"productId":"gid://shopify/Product/6861485768781","count":1,"values":[{"estimatedArrival":"Rush Production","arrivalMessage":"Expected to arrive in ~3-6 business days","shippingSpeed":"3-6 days","rushFee":null,"maxArrivalDays":10,"latestArrivalDate":"2026-06-25"}]}}}}}},"400":{"description":"Invalid query (failed validation)","content":{"application/json":{"examples":{"nonNumericProductId":{"summary":"Non-numeric productId","value":{"success":false,"error":[{"kind":"validation","type":"regex","input":"abc","expected":"/^\\d+$/","message":"must be a numeric product id","path":[{"type":"object","origin":"value","key":"productId","value":"abc"}]}]}},"missingProductId":{"summary":"Missing productId","value":{"success":false,"error":[{"kind":"schema","type":"object","expected":"\"productId\"","received":"undefined","message":"Invalid key: Expected \"productId\" but received undefined","path":[{"type":"object","origin":"key","key":"productId"}]}]}},"invalidRushWaived":{"summary":"Invalid rushWaived (not 'true'/'false')","value":{"success":false,"error":[{"kind":"schema","type":"union","input":"yes","message":"Invalid type: Expected (\"true\" | \"false\") but received \"yes\"","path":[{"type":"object","origin":"value","key":"rushWaived","value":"yes"}]}]}}}}}},"404":{"description":"The requested product id did not resolve","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"productId":{"type":"string"}},"required":["error","productId"]},"example":{"error":"Product not found: gid://shopify/Product/999999999","productId":"gid://shopify/Product/999999999"}}}}},"parameters":[{"in":"query","name":"productId","schema":{"type":"string","pattern":"^\\d+$","example":"8420987371533"},"required":true,"description":"Product identifier — a bare numeric id, normalized to the GID form (gid://shopify/Product/<id>). Responses always emit GIDs."},{"in":"query","name":"rushWaived","schema":{"anyOf":[{"const":"true"},{"const":"false"}],"default":"false","example":"false"},"description":"When 'true', the Rush fee is previewed as $0 instead of the priced amount (default false). The caller owns eligibility."}]}},"/cartographer/replacements":{"get":{"operationId":"getCartographerReplacements","description":"Check whether a variant arrives by a wedding date as Standard Production or Rush Production, and which one to offer. Without a wedding date, list both methods with their arrival estimates and offer the requested variant, or its sibling when the requested one is sold out.","responses":{"200":{"description":"Both production methods for the variant, with a recommendation","content":{"application/json":{"schema":{"type":"object","properties":{"variantId":{"type":"string"},"weddingDate":{"anyOf":[{"type":"string"},{"type":"null"}]},"recommendation":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"GID of the variant to offer: Rush when Standard has under 7 days to spare and Rush is purchasable and in time; otherwise the requested variant when it is purchasable and in time; otherwise its sibling when that is; otherwise an `expedite` option; otherwise null. Without a wedding date: the requested variant when it is purchasable; otherwise its sibling when that is; otherwise null."},"options":{"type":"array","items":{"type":"object","properties":{"variantId":{"type":"string"},"sku":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Shared by the Standard and Rush Production variants of a size. Null when the variant has none.","example":"BG068BL0018003"},"requested":{"type":"boolean"},"productionMethod":{"type":"string","description":"`Standard Production` or `Rush Production`.","example":"Rush Production"},"purchasable":{"type":"boolean","description":"Whether this variant can be bought right now."},"estimatedArrival":{"type":"string","description":"Arrival copy for an order placed today.","example":"Expected to arrive in ~3-6 business days"},"latestArrivalDate":{"type":"string","description":"Latest expected arrival for an order placed today.","example":"2026-11-09"},"expeditedArrivalDate":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Rush only: arrival with upgraded shipping for an order placed today (3 business days). Null for Standard Production.","example":"2026-11-02"},"marginDays":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Calendar days from latestArrivalDate to the wedding date; negative when it arrives after. Null without a wedding date.","example":12},"fit":{"anyOf":[{"enum":["comfortable","tight","expedite","tooLate"],"type":"string"},{"type":"null"}],"description":"`comfortable` (14+ days to spare), `tight` (0–13 days), `expedite` (Rush in stock that misses the wedding with standard shipping, but the wedding is at least 3 business days away, so upgraded shipping can make it), or `tooLate`. Null without a wedding date.","example":"comfortable"}},"required":["variantId","sku","requested","productionMethod","purchasable","estimatedArrival","latestArrivalDate","expeditedArrivalDate","marginDays","fit"]},"description":"The requested variant first, then its sibling in the same size and color with the other production method when the product has one."}},"required":["variantId","weddingDate","recommendation","options"]},"examples":{"rushInTime":{"summary":"Standard misses the wedding, Rush arrives in time","value":{"variantId":"gid://shopify/ProductVariant/42630338740301","weddingDate":"2026-11-21","recommendation":"gid://shopify/ProductVariant/42630338773069","options":[{"variantId":"gid://shopify/ProductVariant/42630338740301","sku":"BG068BL0018003","requested":true,"productionMethod":"Standard Production","purchasable":true,"estimatedArrival":"Expected to arrive between 11-24-2026 and 12-08-2026","latestArrivalDate":"2026-12-08","expeditedArrivalDate":null,"marginDays":-17,"fit":"tooLate"},{"variantId":"gid://shopify/ProductVariant/42630338773069","sku":"BG068BL0018003","requested":false,"productionMethod":"Rush Production","purchasable":true,"estimatedArrival":"Expected to arrive in ~3-6 business days","latestArrivalDate":"2026-11-09","expeditedArrivalDate":"2026-11-02","marginDays":12,"fit":"tight"}]}},"rushExpedited":{"summary":"Only Rush with expedited shipping arrives in time","value":{"variantId":"gid://shopify/ProductVariant/42630338740301","weddingDate":"2026-11-04","recommendation":"gid://shopify/ProductVariant/42630338773069","options":[{"variantId":"gid://shopify/ProductVariant/42630338740301","sku":"BG068BL0018003","requested":true,"productionMethod":"Standard Production","purchasable":true,"estimatedArrival":"Expected to arrive between 11-24-2026 and 12-08-2026","latestArrivalDate":"2026-12-08","expeditedArrivalDate":null,"marginDays":-34,"fit":"tooLate"},{"variantId":"gid://shopify/ProductVariant/42630338773069","sku":"BG068BL0018003","requested":false,"productionMethod":"Rush Production","purchasable":true,"estimatedArrival":"Expected to arrive in ~3-6 business days","latestArrivalDate":"2026-11-09","expeditedArrivalDate":"2026-11-02","marginDays":-5,"fit":"expedite"}]}},"neitherInTime":{"summary":"Neither method arrives in time","value":{"variantId":"gid://shopify/ProductVariant/42630338740301","weddingDate":"2026-11-01","recommendation":null,"options":[{"variantId":"gid://shopify/ProductVariant/42630338740301","sku":"BG068BL0018003","requested":true,"productionMethod":"Standard Production","purchasable":true,"estimatedArrival":"Expected to arrive between 11-24-2026 and 12-08-2026","latestArrivalDate":"2026-12-08","expeditedArrivalDate":null,"marginDays":-37,"fit":"tooLate"},{"variantId":"gid://shopify/ProductVariant/42630338773069","sku":"BG068BL0018003","requested":false,"productionMethod":"Rush Production","purchasable":true,"estimatedArrival":"Expected to arrive in ~3-6 business days","latestArrivalDate":"2026-11-09","expeditedArrivalDate":"2026-11-02","marginDays":-8,"fit":"tooLate"}]}},"rushSoldOut":{"summary":"Rush sold out, Standard arrives in time","value":{"variantId":"gid://shopify/ProductVariant/42630338773069","weddingDate":"2026-12-31","recommendation":"gid://shopify/ProductVariant/42630338740301","options":[{"variantId":"gid://shopify/ProductVariant/42630338773069","sku":"BG068BL0018003","requested":true,"productionMethod":"Rush Production","purchasable":false,"estimatedArrival":"Expected to arrive in ~3-6 business days","latestArrivalDate":"2026-11-09","expeditedArrivalDate":"2026-11-02","marginDays":52,"fit":"comfortable"},{"variantId":"gid://shopify/ProductVariant/42630338740301","sku":"BG068BL0018003","requested":false,"productionMethod":"Standard Production","purchasable":true,"estimatedArrival":"Expected to arrive between 11-24-2026 and 12-08-2026","latestArrivalDate":"2026-12-08","expeditedArrivalDate":null,"marginDays":23,"fit":"comfortable"}]}},"noWeddingDate":{"summary":"No weddingDate: arrival estimates, recommending the requested variant","value":{"variantId":"gid://shopify/ProductVariant/42630338740301","weddingDate":null,"recommendation":"gid://shopify/ProductVariant/42630338740301","options":[{"variantId":"gid://shopify/ProductVariant/42630338740301","sku":"BG068BL0018003","requested":true,"productionMethod":"Standard Production","purchasable":true,"estimatedArrival":"Expected to arrive between 11-24-2026 and 12-08-2026","latestArrivalDate":"2026-12-08","expeditedArrivalDate":null,"marginDays":null,"fit":null},{"variantId":"gid://shopify/ProductVariant/42630338773069","sku":"BG068BL0018003","requested":false,"productionMethod":"Rush Production","purchasable":true,"estimatedArrival":"Expected to arrive in ~3-6 business days","latestArrivalDate":"2026-11-09","expeditedArrivalDate":"2026-11-02","marginDays":null,"fit":null}]}}}}}},"400":{"description":"Invalid query (failed validation)","content":{"application/json":{"example":{"success":false,"error":[{"kind":"validation","type":"regex","input":"11/21/2026","expected":"/^\\d{4}-\\d{2}-\\d{2}$/","message":"must be a date in YYYY-MM-DD format","path":[{"type":"object","origin":"value","key":"weddingDate","value":"11/21/2026"}]}]}}}},"404":{"description":"The requested variant id did not resolve","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"variantId":{"type":"string"}},"required":["error","variantId"]},"example":{"error":"Variant not found: gid://shopify/ProductVariant/999999999","variantId":"gid://shopify/ProductVariant/999999999"}}}},"422":{"description":"The variant has no production method to compare","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"variantId":{"type":"string"}},"required":["error","variantId"]},"example":{"error":"Variant has no Estimated Arrival option: gid://shopify/ProductVariant/40075796250701","variantId":"gid://shopify/ProductVariant/40075796250701"}}}}},"parameters":[{"in":"query","name":"variantId","schema":{"type":"string","pattern":"^\\d+$","example":"42630338773069"},"required":true,"description":"Variant id as a bare number. Responses return variant ids as GIDs (gid://shopify/ProductVariant/<id>)."},{"in":"query","name":"weddingDate","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-11-21"},"description":"The wedding date to check arrival against. Without it, the options carry no margin or fit, and the recommendation is the first purchasable option."}]}}},"components":{}}