{"openapi":"3.1.0","info":{"version":"0.3.1","title":"Roastify API","description":"Roastify's API for merchants and developers to integrate their apps, ecommerce platforms, and backends with Roastify. This API is currently in beta and is subject to change. If you have any questions or would like to request access, please contact us at support@roastify.app","contact":{"name":"Roastify","url":"https://roastify.app","email":"support@roastify.app"},"termsOfService":"https://www.roastify.app/policies/terms-conditions"},"tags":[{"name":"Catalog","description":"View the Roastify catalog, including products and coffee blends"},{"name":"Orders","description":"Create and manage orders"},{"name":"Transactions","description":"View transactions for fulfilled orders"},{"name":"Variants","description":"Get variant information for Roastify products and blends."},{"name":"Products","description":"Get products by ID or all products in your Roastify Merchant account"},{"name":"Stock","description":"Get stock levels for Roastify products and SKUs"},{"name":"Artwork","description":"Create and edit artwork using previously saved designs."}],"security":[{"ApiKeyAuth":[]}],"servers":[{"url":"https://api.roastify.app","description":"Production API V1"}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"The API key to authenticate requests provided by Roastify. A Base or Pro plan is required to use the API."}},"schemas":{},"parameters":{}},"paths":{"/v1/catalog/products":{"get":{"tags":["Catalog"],"summary":"Get All Catalog Products","operationId":"getCatalogProducts","description":"Get all available products in the Roastify Catalog","responses":{"200":{"description":"Get all available products in the Roastify Catalog","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"clyd67824rn3f78g0f8j9","description":"The id of the product"},"title":{"type":"string","example":"12oz Coffee Box","description":"The title of the product"},"description":{"type":"string","description":"The description of the product"},"imageUrl":{"type":"string","example":"https://storage.roastify.app/mockup-images/a045d749-8372-44a0-aga3-098688ab6ad2.jpeg","description":"The image url of the product (HTTPS only with valid image extension)"},"productType":{"type":"string","example":"12ozCoffeeBox","description":"The type of the product"},"productCategory":{"type":"string","example":"Coffee","description":"The category of the product"},"dielineTemplateUrl":{"type":"string","nullable":true,"example":"https://acme.com/12oz-coffee-bag-dieline.png","description":"The dieline template for the particular product. The dieline is used as a template for creating packaging designs. Must be HTTPS."},"variants":{"type":"number","example":8,"description":"The number of variants for the product"},"plan":{"type":"string","example":"pro","description":"The plan that is required to purchase the product"}},"required":["id","title","description","imageUrl","productType","productCategory","dielineTemplateUrl","variants","plan"]}}}}},"400":{"description":"Returns an error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"404":{"description":"No Catalog Products Found","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"422":{"description":"Data Validation Error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}}}}},"/v1/catalog/products/{id}":{"get":{"tags":["Catalog"],"summary":"Get Product by ID","operationId":"getCatalogProductById","description":"Get a catalog product by ID","parameters":[{"schema":{"type":"string","minLength":1,"description":"The Id of the resource","example":"clyd67824rn3f78g0f8j9"},"required":true,"description":"The Id of the resource","name":"id","in":"path"}],"responses":{"200":{"description":"Get a product by Id in the catalog","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","example":"clyd67824rn3f78g0f8j9","description":"The id of the product"},"title":{"type":"string","example":"12oz Coffee Box","description":"The title of the product"},"description":{"type":"string","description":"The description of the product"},"imageUrl":{"type":"string","example":"https://storage.roastify.app/mockup-images/a045d749-8372-44a0-aga3-098688ab6ad2.jpeg","description":"The image url of the product (HTTPS only with valid image extension)"},"productType":{"type":"string","example":"12ozCoffeeBox","description":"The type of the product"},"productCategory":{"type":"string","example":"Coffee","description":"The category of the product"},"dielineTemplateUrl":{"type":"string","nullable":true,"example":"https://acme.com/12oz-coffee-bag-dieline.png","description":"The dieline template for the particular product. The dieline is used as a template for creating packaging designs. Must be HTTPS."},"variants":{"type":"number","example":8,"description":"The number of variants for the product"},"plan":{"type":"string","example":"pro","description":"The plan that is required to purchase the product"}},"required":["id","title","description","imageUrl","productType","productCategory","dielineTemplateUrl","variants","plan"]}}}},"400":{"description":"Returns an error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"404":{"description":"Product Not Found","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"422":{"description":"Data Validation Error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}}}}},"/v1/catalog/blends":{"get":{"tags":["Catalog"],"summary":"Get All Coffee Blends","operationId":"getAllBlends","description":"Get all availalbe blends in the catalog. This does not include custom blends or discontinued blends","responses":{"200":{"description":"Get all availalbe blends in the catalog","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"clyd67824rn3f78g0f8j9","description":"The id of the blend"},"name":{"type":"string","example":"12oz Coffee Bag","description":"The name of the blend"},"description":{"type":"string","description":"The description of the blend"},"isDecaf":{"type":"boolean","example":false,"description":"Is the blend decaf"},"roastLevel":{"type":"string","example":"Medium","description":"The roast level of the blend"}},"required":["id","name","description","isDecaf","roastLevel"]}}}}},"400":{"description":"Returns an error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"404":{"description":"No Blends Found","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"422":{"description":"Data Validation Error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}}}}},"/v1/catalog/blends/{id}":{"get":{"tags":["Catalog"],"summary":"Get Coffee Blend by ID","operationId":"getBlendById","description":"Get a coffee blend by Id","parameters":[{"schema":{"type":"string","minLength":1,"description":"The Id of the resource","example":"clyd67824rn3f78g0f8j9"},"required":true,"description":"The Id of the resource","name":"id","in":"path"}],"responses":{"200":{"description":"Get a blend by Id","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","example":"clyd67824rn3f78g0f8j9","description":"The id of the blend"},"name":{"type":"string","example":"12oz Coffee Bag","description":"The name of the blend"},"description":{"type":"string","description":"The description of the blend"},"isDecaf":{"type":"boolean","example":false,"description":"Is the blend decaf"},"roastLevel":{"type":"string","example":"Medium","description":"The roast level of the blend"}},"required":["id","name","description","isDecaf","roastLevel"]}}}},"400":{"description":"Returns an error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"404":{"description":"Blend Not Found","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"422":{"description":"Data Validation Error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}}}}},"/v1/variants/{sku}":{"get":{"tags":["Variants"],"summary":"Get Variant by SKU","operationId":"getVariantBySKU","description":"Get a variant by SKU","parameters":[{"schema":{"type":"string","minLength":1,"description":"The SKU of the resource","example":"COF-WHB-12O-FHV-BOX"},"required":true,"description":"The SKU of the resource","name":"sku","in":"path"}],"responses":{"200":{"description":"Get a variant by SKU","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","example":"clyd67824rn3f78g0f8j9","description":"The id of the variant"},"title":{"type":"string","example":"Whole Bean","description":"The title of the variant"},"size":{"type":"string","description":"The size of the variant","example":"12oz"},"retailPrice":{"type":"number","description":"The retail price of the variant (in cents)","example":1200},"sku":{"type":"string","example":"COF-GND-12O-COL-BOX","description":"The SKU of the variant"},"inStock":{"type":"boolean","description":"Whether the variant is in stock","example":true},"stockQty":{"type":"number","description":"The quantity of the variant in stock. 999 for unlimited","example":999},"plan":{"type":"string","example":"pro","description":"The plan that is required to purchase the product"}},"required":["id","title","size","retailPrice","sku","inStock","stockQty","plan"]}}}},"400":{"description":"Returns an error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"404":{"description":"Variant Not Found","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"422":{"description":"Data Validation Error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}}}}},"/v1/variants/product/{id}":{"get":{"tags":["Variants"],"summary":"Get Variants by Product ID","operationId":"getAllVariantsByProductId","description":"Get all variants for a product by using the product's Id","parameters":[{"schema":{"type":"string","minLength":1,"description":"The Id of the resource","example":"clyd67824rn3f78g0f8j9"},"required":true,"description":"The Id of the resource","name":"id","in":"path"}],"responses":{"200":{"description":"Get a variant by Id","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"clyd67824rn3f78g0f8j9","description":"The id of the variant"},"title":{"type":"string","example":"Whole Bean","description":"The title of the variant"},"size":{"type":"string","description":"The size of the variant","example":"12oz"},"retailPrice":{"type":"number","description":"The retail price of the variant (in cents)","example":1200},"sku":{"type":"string","example":"COF-GND-12O-COL-BOX","description":"The SKU of the variant"},"inStock":{"type":"boolean","description":"Whether the variant is in stock","example":true},"stockQty":{"type":"number","description":"The quantity of the variant in stock. 999 for unlimited","example":999},"plan":{"type":"string","example":"pro","description":"The plan that is required to purchase the product"}},"required":["id","title","size","retailPrice","sku","inStock","stockQty","plan"]}}}}},"400":{"description":"Returns an error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"404":{"description":"Product or Variants Not Found","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"422":{"description":"Data Validation Error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}}}}},"/v1/variants/blend/{id}":{"get":{"tags":["Variants"],"summary":"Get Variants by Blend ID","operationId":"getAllVariantsByBlendId","description":"Get all variants for a blend by using the blend's Id","parameters":[{"schema":{"type":"string","minLength":1,"description":"The Id of the resource","example":"clyd67824rn3f78g0f8j9"},"required":true,"description":"The Id of the resource","name":"id","in":"path"}],"responses":{"200":{"description":"All variants for a blend","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"clyd67824rn3f78g0f8j9","description":"The id of the variant"},"title":{"type":"string","example":"Whole Bean","description":"The title of the variant"},"size":{"type":"string","description":"The size of the variant","example":"12oz"},"retailPrice":{"type":"number","description":"The retail price of the variant (in cents)","example":1200},"sku":{"type":"string","example":"COF-GND-12O-COL-BOX","description":"The SKU of the variant"},"inStock":{"type":"boolean","description":"Whether the variant is in stock","example":true},"stockQty":{"type":"number","description":"The quantity of the variant in stock. 999 for unlimited","example":999},"plan":{"type":"string","example":"pro","description":"The plan that is required to purchase the product"}},"required":["id","title","size","retailPrice","sku","inStock","stockQty","plan"]}}}}},"400":{"description":"Returns an error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"404":{"description":"Blend or Variants Not Found","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"422":{"description":"Data Validation Error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}}}}},"/v1/stock":{"get":{"tags":["Stock"],"summary":"Get Stock List","operationId":"getStockList","description":"Get the stock status and quantity of all available variants","responses":{"200":{"description":"Returns the stock list","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string","example":"COF-GND-12O-FHV-BOX","description":"The SKU of the variant"},"stockQty":{"type":"number","example":100,"description":"The stock quantity of the variant. If the quantity is 999, it means the stock is considered unlimited."},"inStock":{"type":"boolean","example":true,"description":"Boolean indicating whether the variant is in stock"}},"required":["sku","stockQty","inStock"]}}}}},"400":{"description":"Returns an error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"422":{"description":"Data Validation Error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}}}}},"/v1/stock/{sku}":{"get":{"tags":["Stock"],"summary":"Get Stock By SKU","operationId":"getStockBySku","description":"Get the stock status and quantity of a variant by SKU","parameters":[{"schema":{"type":"string","minLength":1,"description":"The SKU of the resource","example":"COF-WHB-12O-FHV-BOX"},"required":true,"description":"The SKU of the resource","name":"sku","in":"path"}],"responses":{"200":{"description":"Returns the stock status and quantity of a variant","content":{"application/json":{"schema":{"type":"object","properties":{"sku":{"type":"string","example":"COF-GND-12O-FHV-BOX","description":"The SKU of the variant"},"stockQty":{"type":"number","example":100,"description":"The stock quantity of the variant. If the quantity is 999, it means the stock is considered unlimited."},"inStock":{"type":"boolean","example":true,"description":"Boolean indicating whether the variant is in stock"}},"required":["sku","stockQty","inStock"]}}}},"400":{"description":"Returns an error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"422":{"description":"Data Validation Error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}}}}},"/v1/orders":{"post":{"tags":["Orders"],"summary":"Create Order","operationId":"createOrder","description":"Create a new fulfillment order. This will automatically create a new order in Roastify with a 'Created' status.","parameters":[{"schema":{"type":"string","description":"The idempotency key to use for the request (V4 UUID recommended)","example":"123e4567-e89b-12d3-a456-426614174000"},"required":false,"description":"The idempotency key to use for the request (V4 UUID recommended)","name":"Idempotency-Key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"externalSourceId":{"type":"string","nullable":true,"description":"Your external source ID. This is an optional field that can be used to map orders from your system to Roastify.","example":"your-order-123"},"toAddress":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"Recipient name"},"company":{"type":"string","nullable":true,"description":"Company name"},"street1":{"type":"string","minLength":1,"description":"Address line 1"},"street2":{"type":"string","nullable":true,"description":"Address line 2"},"city":{"type":"string","minLength":1,"description":"City"},"state":{"type":"string","minLength":1,"description":"State"},"country":{"type":"string","minLength":1,"description":"Country"},"zip":{"type":"string","minLength":1,"description":"ZIP code"},"phone":{"type":"string","nullable":true,"description":"Phone number"},"email":{"type":"string","minLength":1,"description":"Email address"}},"required":["name","street1","city","state","country","zip","email"],"description":"Recipient information"},"returnAddress":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"Return address name"},"company":{"type":"string","nullable":true,"description":"Company name"},"street1":{"type":"string","minLength":1,"description":"Address line 1"},"street2":{"type":"string","nullable":true,"description":"Address line 2"},"city":{"type":"string","minLength":1,"description":"City"},"state":{"type":"string","minLength":1,"description":"State"},"country":{"type":"string","minLength":1,"description":"Country"},"zip":{"type":"string","minLength":1,"description":"ZIP code"},"phone":{"type":"string","nullable":true,"description":"Phone number"},"email":{"type":"string","minLength":1,"description":"Email address"}},"required":["name","street1","city","state","country","zip","email"],"description":"Optional return address. If not provided, uses the Roastify default distribution center address."},"shipping":{"type":"object","properties":{"carrier":{"type":"string","minLength":1,"description":"Shipping carrier","example":"USPS"},"priority":{"type":"string","minLength":1,"description":"Shipping priority","example":"Priority"}},"required":["carrier","priority"],"description":"Optional shipping information. This is only required for API users with custom shipping integrations with Roastify. Carrier and Priority need to be `camelCase` or `PascalCase`.","example":{"carrier":"USPS","priority":"GroundAdvantage"}},"items":{"type":"array","items":{"type":"object","properties":{"externalSourceId":{"type":"string","nullable":true,"description":"Your external source ID for this line item. This is an optional field that can be used to map line items from your system to Roastify.","example":"your-line-item-456"},"sku":{"type":"string","minLength":1,"example":"COF-WHB-12O-COL-BOX","description":"SKU is required and tells Roastify the specific product and coffee blend of your line item."},"artworkUrl":{"type":"string","example":"https://storage.roastify.app/mockup-images/a045d749-8372-44a0-aga3-098688ab6ad2.jpeg","description":"HTTPS URL to the line item's print-ready artwork. The fetched file must be a JPEG or PNG and its dimensions must match the selected product's artwork specifications exactly."},"quantity":{"type":"number","minimum":1,"example":3,"description":"Must be a number greater than 0"}},"required":["sku","artworkUrl","quantity"]},"minItems":1,"description":"List of items in the order"}},"required":["toAddress","items"]}}}},"responses":{"201":{"description":"Succesful order. Returns the orderId of the new order","content":{"application/json":{"schema":{"type":"object","properties":{"orderId":{"type":"string"}},"required":["orderId"]}}}},"400":{"description":"Returns an error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"422":{"description":"Data Validation Error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}}}},"get":{"tags":["Orders"],"summary":"Get All Orders","operationId":"getOrders","description":"Get all fulfillment orders for a service integration store.","parameters":[{"schema":{"type":"string","description":"The cursor to start from. This is the orderId of the last order in the previous page. This can also be found in the `endCursor` property of the previous page's response.","example":"5a441254-e4b7-43af-98a3-e9012cff7feb"},"required":false,"description":"The cursor to start from. This is the orderId of the last order in the previous page. This can also be found in the `endCursor` property of the previous page's response.","name":"cursor","in":"query"},{"schema":{"type":"string","description":"The number of results to return. Defaults to 20 and maximum is 100","example":"10"},"required":false,"description":"The number of results to return. Defaults to 20 and maximum is 100","name":"pageSize","in":"query"}],"responses":{"200":{"description":"Get all fulfillment orders","content":{"application/json":{"schema":{"type":"object","properties":{"orders":{"type":"array","items":{"type":"object","properties":{"orderId":{"type":"string","description":"Object ID"},"createdAt":{"type":"string","description":"Created at"},"updatedAt":{"type":"string","description":"Updated at"},"orderStatus":{"type":"string","enum":["Created","Picked","Printed","Packaged","Shipped","Canceled","CancelationRequested","Declined"],"example":"Created","description":"Order status"},"isTest":{"type":"boolean","description":"Whether this is a test order","example":false},"externalSourceId":{"type":"string","nullable":true,"description":"Your external source ID. This is an optional field that can be used to map orders from your system to Roastify.","example":"your-order-123"},"toAddress":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"Recipient name"},"company":{"type":"string","nullable":true,"description":"Company name"},"street1":{"type":"string","minLength":1,"description":"Address line 1"},"street2":{"type":"string","nullable":true,"description":"Address line 2"},"city":{"type":"string","minLength":1,"description":"City"},"state":{"type":"string","minLength":1,"description":"State"},"country":{"type":"string","minLength":1,"description":"Country"},"zip":{"type":"string","minLength":1,"description":"ZIP code"},"phone":{"type":"string","nullable":true,"description":"Phone number"},"email":{"type":"string","minLength":1,"description":"Email address"}},"required":["name","street1","city","state","country","zip","email"],"description":"Recipient information"},"returnAddress":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"Return address name"},"company":{"type":"string","nullable":true,"description":"Company name"},"street1":{"type":"string","minLength":1,"description":"Address line 1"},"street2":{"type":"string","nullable":true,"description":"Address line 2"},"city":{"type":"string","minLength":1,"description":"City"},"state":{"type":"string","minLength":1,"description":"State"},"country":{"type":"string","minLength":1,"description":"Country"},"zip":{"type":"string","minLength":1,"description":"ZIP code"},"phone":{"type":"string","nullable":true,"description":"Phone number"},"email":{"type":"string","minLength":1,"description":"Email address"}},"required":["name","street1","city","state","country","zip","email"],"description":"Optional return address. If not provided, uses the Roastify default distribution center address."},"shipping":{"type":"object","properties":{"carrier":{"type":"string","minLength":1,"description":"Shipping carrier","example":"USPS"},"priority":{"type":"string","minLength":1,"description":"Shipping priority","example":"Priority"}},"required":["carrier","priority"],"description":"Optional shipping information. This is only required for API users with custom shipping integrations with Roastify. Carrier and Priority need to be `camelCase` or `PascalCase`.","example":{"carrier":"USPS","priority":"GroundAdvantage"}},"items":{"type":"array","items":{"type":"object","properties":{"externalSourceId":{"type":"string","nullable":true,"description":"Your external source ID for this line item. This is an optional field that can be used to map line items from your system to Roastify.","example":"your-line-item-456"},"sku":{"type":"string","minLength":1,"example":"COF-WHB-12O-COL-BOX","description":"SKU is required and tells Roastify the specific product and coffee blend of your line item."},"artworkUrl":{"type":"string","example":"https://storage.roastify.app/mockup-images/a045d749-8372-44a0-aga3-098688ab6ad2.jpeg","description":"HTTPS URL to the line item's print-ready artwork. The fetched file must be a JPEG or PNG and its dimensions must match the selected product's artwork specifications exactly."},"quantity":{"type":"number","minimum":1,"example":3,"description":"Must be a number greater than 0"}},"required":["sku","artworkUrl","quantity"]},"minItems":1,"description":"List of items in the order"}},"required":["orderId","createdAt","updatedAt","orderStatus","isTest","toAddress","items"]}},"pageInfo":{"type":"object","properties":{"endCursor":{"type":"string","nullable":true},"hasNextPage":{"type":"boolean"}},"required":["hasNextPage"]}},"required":["orders","pageInfo"]}}}},"400":{"description":"Returns an error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"422":{"description":"Data Validation Error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}}}}},"/v1/orders/{orderId}":{"get":{"tags":["Orders"],"summary":"Get Order","operationId":"getOrder","description":"Get an order by orderId","parameters":[{"schema":{"type":"string","minLength":1,"description":"The Id of the order","example":"1ef87e47-266e-466f-ab06-a64994aefbb0"},"required":true,"description":"The Id of the order","name":"orderId","in":"path"}],"responses":{"200":{"description":"Get an order by orderId","content":{"application/json":{"schema":{"type":"object","properties":{"orderId":{"type":"string","description":"Object ID"},"createdAt":{"type":"string","description":"Created at"},"updatedAt":{"type":"string","description":"Updated at"},"orderStatus":{"type":"string","enum":["Created","Picked","Printed","Packaged","Shipped","Canceled","CancelationRequested","Declined"],"example":"Created","description":"Order status"},"isTest":{"type":"boolean","description":"Whether this is a test order","example":false},"externalSourceId":{"type":"string","nullable":true,"description":"Your external source ID. This is an optional field that can be used to map orders from your system to Roastify.","example":"your-order-123"},"toAddress":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"Recipient name"},"company":{"type":"string","nullable":true,"description":"Company name"},"street1":{"type":"string","minLength":1,"description":"Address line 1"},"street2":{"type":"string","nullable":true,"description":"Address line 2"},"city":{"type":"string","minLength":1,"description":"City"},"state":{"type":"string","minLength":1,"description":"State"},"country":{"type":"string","minLength":1,"description":"Country"},"zip":{"type":"string","minLength":1,"description":"ZIP code"},"phone":{"type":"string","nullable":true,"description":"Phone number"},"email":{"type":"string","minLength":1,"description":"Email address"}},"required":["name","street1","city","state","country","zip","email"],"description":"Recipient information"},"returnAddress":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"Return address name"},"company":{"type":"string","nullable":true,"description":"Company name"},"street1":{"type":"string","minLength":1,"description":"Address line 1"},"street2":{"type":"string","nullable":true,"description":"Address line 2"},"city":{"type":"string","minLength":1,"description":"City"},"state":{"type":"string","minLength":1,"description":"State"},"country":{"type":"string","minLength":1,"description":"Country"},"zip":{"type":"string","minLength":1,"description":"ZIP code"},"phone":{"type":"string","nullable":true,"description":"Phone number"},"email":{"type":"string","minLength":1,"description":"Email address"}},"required":["name","street1","city","state","country","zip","email"],"description":"Optional return address. If not provided, uses the Roastify default distribution center address."},"shipping":{"type":"object","properties":{"carrier":{"type":"string","minLength":1,"description":"Shipping carrier","example":"USPS"},"priority":{"type":"string","minLength":1,"description":"Shipping priority","example":"Priority"}},"required":["carrier","priority"],"description":"Optional shipping information. This is only required for API users with custom shipping integrations with Roastify. Carrier and Priority need to be `camelCase` or `PascalCase`.","example":{"carrier":"USPS","priority":"GroundAdvantage"}},"items":{"type":"array","items":{"type":"object","properties":{"externalSourceId":{"type":"string","nullable":true,"description":"Your external source ID for this line item. This is an optional field that can be used to map line items from your system to Roastify.","example":"your-line-item-456"},"sku":{"type":"string","minLength":1,"example":"COF-WHB-12O-COL-BOX","description":"SKU is required and tells Roastify the specific product and coffee blend of your line item."},"artworkUrl":{"type":"string","example":"https://storage.roastify.app/mockup-images/a045d749-8372-44a0-aga3-098688ab6ad2.jpeg","description":"HTTPS URL to the line item's print-ready artwork. The fetched file must be a JPEG or PNG and its dimensions must match the selected product's artwork specifications exactly."},"quantity":{"type":"number","minimum":1,"example":3,"description":"Must be a number greater than 0"}},"required":["sku","artworkUrl","quantity"]},"minItems":1,"description":"List of items in the order"}},"required":["orderId","createdAt","updatedAt","orderStatus","isTest","toAddress","items"]}}}},"400":{"description":"Returns an error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"422":{"description":"Data Validation Error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}}}},"put":{"tags":["Orders"],"summary":"Update Order","operationId":"updateOrder","description":"Update an Order by orderId. Orders can only be updated if they are in the 'Created' status.","parameters":[{"schema":{"type":"string","minLength":1,"description":"The Id of the order","example":"1ef87e47-266e-466f-ab06-a64994aefbb0"},"required":true,"description":"The Id of the order","name":"orderId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"externalSourceId":{"type":"string","nullable":true,"description":"Your external source ID. This is an optional field that can be used to map orders from your system to Roastify.","example":"your-order-123"},"toAddress":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"Recipient name"},"company":{"type":"string","nullable":true,"description":"Company name"},"street1":{"type":"string","minLength":1,"description":"Address line 1"},"street2":{"type":"string","nullable":true,"description":"Address line 2"},"city":{"type":"string","minLength":1,"description":"City"},"state":{"type":"string","minLength":1,"description":"State"},"country":{"type":"string","minLength":1,"description":"Country"},"zip":{"type":"string","minLength":1,"description":"ZIP code"},"phone":{"type":"string","nullable":true,"description":"Phone number"},"email":{"type":"string","minLength":1,"description":"Email address"}},"required":["name","street1","city","state","country","zip","email"],"description":"Recipient information"},"returnAddress":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"Return address name"},"company":{"type":"string","nullable":true,"description":"Company name"},"street1":{"type":"string","minLength":1,"description":"Address line 1"},"street2":{"type":"string","nullable":true,"description":"Address line 2"},"city":{"type":"string","minLength":1,"description":"City"},"state":{"type":"string","minLength":1,"description":"State"},"country":{"type":"string","minLength":1,"description":"Country"},"zip":{"type":"string","minLength":1,"description":"ZIP code"},"phone":{"type":"string","nullable":true,"description":"Phone number"},"email":{"type":"string","minLength":1,"description":"Email address"}},"required":["name","street1","city","state","country","zip","email"],"description":"Optional return address. If not provided, uses the Roastify default distribution center address."},"shipping":{"type":"object","properties":{"carrier":{"type":"string","minLength":1,"description":"Shipping carrier","example":"USPS"},"priority":{"type":"string","minLength":1,"description":"Shipping priority","example":"Priority"}},"required":["carrier","priority"],"description":"Optional shipping information. This is only required for API users with custom shipping integrations with Roastify. Carrier and Priority need to be `camelCase` or `PascalCase`.","example":{"carrier":"USPS","priority":"GroundAdvantage"}},"items":{"type":"array","items":{"type":"object","properties":{"externalSourceId":{"type":"string","nullable":true,"description":"Your external source ID for this line item. This is an optional field that can be used to map line items from your system to Roastify.","example":"your-line-item-456"},"sku":{"type":"string","minLength":1,"example":"COF-WHB-12O-COL-BOX","description":"SKU is required and tells Roastify the specific product and coffee blend of your line item."},"artworkUrl":{"type":"string","example":"https://storage.roastify.app/mockup-images/a045d749-8372-44a0-aga3-098688ab6ad2.jpeg","description":"HTTPS URL to the line item's print-ready artwork. The fetched file must be a JPEG or PNG and its dimensions must match the selected product's artwork specifications exactly."},"quantity":{"type":"number","minimum":1,"example":3,"description":"Must be a number greater than 0"}},"required":["sku","artworkUrl","quantity"]},"minItems":1,"description":"List of items in the order"}},"required":["toAddress","items"]}}}},"responses":{"202":{"description":"Order updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"orderId":{"type":"string"}},"required":["orderId"]}}}},"400":{"description":"Returns an error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"422":{"description":"Data Validation Error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}}}}},"/v1/orders/{orderId}/cancel":{"put":{"tags":["Orders"],"summary":"Cancel Order","operationId":"cancelOrder","description":"Cancel an order by orderId. Orders can only be canceled if they are in the 'Created' status. If order fulfillment has begun and the order no longer carries the 'Created' status, this request will be rejected.","parameters":[{"schema":{"type":"string","minLength":1,"description":"The Id of the order","example":"1ef87e47-266e-466f-ab06-a64994aefbb0"},"required":true,"description":"The Id of the order","name":"orderId","in":"path"}],"responses":{"200":{"description":"Order canceled successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Order canceled successfully"}},"required":["message"]}}}},"400":{"description":"Returns an error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"422":{"description":"Data Validation Error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}}}}},"/v1/orders/{orderId}/events":{"get":{"tags":["Orders"],"summary":"Get Order Events","operationId":"getOrderEvents","description":"Get all order events by orderId","parameters":[{"schema":{"type":"string","minLength":1,"description":"The Id of the order","example":"1ef87e47-266e-466f-ab06-a64994aefbb0"},"required":true,"description":"The Id of the order","name":"orderId","in":"path"}],"responses":{"200":{"description":"Get all fulfillment order events by order Id","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["Created","Picked","Printed","Packaged","Shipped","Canceled","CancelationRequested","Declined"],"example":"Created","description":"Current order status"},"events":{"type":"array","items":{"type":"object","properties":{"time":{"type":"string","example":"2020-01-01T00:00:00Z","description":"Time that the event occurred"},"action":{"type":"string","example":"Created","description":"Action associated with the event"},"affected_items":{"type":"array","items":{"type":"string"},"description":"List of affected item internal IDs","example":["65cdd8c2a037fhna9c08471f","62cdd3c6a037fhna9c084fnf"]},"affected_items_details":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Internal line item ID","example":"65cdd8c2a037fhna9c08471f"},"externalSourceId":{"type":"string","nullable":true,"description":"Your external source ID for this line item","example":"your-line-item-123"},"sku":{"type":"string","description":"Product SKU","example":"COF-WHB-12O-COL-BOX"},"quantity":{"type":"number","description":"Quantity of the line item","example":2}},"required":["id","sku","quantity"]},"description":"Detailed information about affected line items including externalSourceId and SKU"}},"required":["time","action","affected_items","affected_items_details"]}}},"required":["status","events"],"description":"Order events"}}}},"400":{"description":"Returns an error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"422":{"description":"Data Validation Error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}}}}},"/v1/orders/{orderId}/shipping":{"get":{"tags":["Orders"],"summary":"Get Order Shipping","operationId":"getOrderShipping","description":"Get order shipping details by orderId","parameters":[{"schema":{"type":"string","minLength":1,"description":"The Id of the order","example":"1ef87e47-266e-466f-ab06-a64994aefbb0"},"required":true,"description":"The Id of the order","name":"orderId","in":"path"}],"responses":{"200":{"description":"Get order shipping details by order Id","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"processed","description":"Current shipping status"},"trackingNumber":{"type":"string","example":"92346903470341000400704020","description":"Tracking number"},"trackingUrl":{"type":"string","example":"https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=92346903470341000400704020","description":"Tracking URL (HTTPS only)"},"estimatedDelivery":{"type":"string","example":"2020-01-01T00:00:00Z","description":"Estimated delivery date in ISO string format"},"shippingCarrier":{"type":"string","example":"USPS","description":"Shipping carrier"},"shippingService":{"type":"string","example":"First","description":"Shipping service"}},"required":["status","trackingNumber","trackingUrl","estimatedDelivery","shippingCarrier","shippingService"],"description":"Order shipping details"}}}},"400":{"description":"Returns an error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"422":{"description":"Data Validation Error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}}}}},"/v1/orders/{orderId}/simulate":{"put":{"tags":["Orders"],"summary":"Simulate Order Status","operationId":"simulateOrderStatus","description":"Simulate order status progression for test orders. This endpoint is only available when using a Test API key. It allows you to manually progress a test order through fulfillment statuses, triggering real webhooks at each stage. Mock shipping labels are created at 'Packaged' status and mock transactions at 'Shipped' status.","parameters":[{"schema":{"type":"string","minLength":1,"description":"The Id of the order","example":"1ef87e47-266e-466f-ab06-a64994aefbb0"},"required":true,"description":"The Id of the order","name":"orderId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"targetStatus":{"type":"string","enum":["Picked","Printed","Packaged","Shipped","Canceled"],"description":"The target status to transition the order to","example":"Picked"}},"required":["targetStatus"]}}}},"responses":{"200":{"description":"Order status simulated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"orderId":{"type":"string"},"previousStatus":{"type":"string"},"newStatus":{"type":"string"},"message":{"type":"string"}},"required":["orderId","previousStatus","newStatus","message"]}}}},"400":{"description":"Invalid status transition or order not eligible","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"403":{"description":"Forbidden - Test API key required","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"404":{"description":"Order not found","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"422":{"description":"Data Validation Error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}}}}},"/v1/transactions/{orderId}":{"get":{"tags":["Transactions"],"summary":"Get Transaction By Order ID","operationId":"getTransactionByOrderId","description":"Get a transaction by order ID. Every order that has been paid has a transaction associated with it. This endpoint returns the transaction details for a given order ID.","parameters":[{"schema":{"type":"string","minLength":1,"description":"The Id of the order","example":"1ef87e47-266e-466f-ab06-a64994aefbb0"},"required":true,"description":"The Id of the order","name":"orderId","in":"path"}],"responses":{"200":{"description":"Get a transaction by order ID","content":{"application/json":{"schema":{"type":"object","properties":{"createdAt":{"type":"string","description":"The date the transaction was created","example":"2021-08-25T20:00:00.000Z"},"orderId":{"type":"string","description":"The order ID associated with the transaction","example":"65df6d09eb81B03ab600782c"},"amount":{"type":"number","description":"The amount of the transaction in cents. Ex: 1000 = $10.00","example":1000},"currency":{"type":"string","description":"The currency of the transaction","example":"USD"},"paymentStatus":{"type":"string","nullable":true,"description":"The payment status of the transaction","example":"paid"},"paymentMethod":{"type":"string","nullable":true,"description":"The payment method used for the transaction","example":"card"},"type":{"type":"string","enum":["balanceTransaction","paymentIntent","subscription"],"description":"Enum for the type of transaction, either `balanceTransaction` or `paymentIntent`. BalanceTransaction is used for adjusting the customer's balance. PaymentIntent is used for processing payments using the customer's default payment method.","example":"balanceTransaction"}},"required":["createdAt","orderId","amount","currency","paymentStatus","paymentMethod","type"]}}}},"400":{"description":"Returns an error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"404":{"description":"Transaction not found","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"422":{"description":"Data Validation Error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}}}}},"/v1/artwork/new":{"post":{"tags":["Artwork"],"summary":"Create New Artwork","operationId":"createNewArtwork","description":"Create new artwork providing a product ID. The product ID can be found on the product page in the Roastify Merchant app. `Fields` is an array of field names from a previously designed product. ","parameters":[{"schema":{"type":"string","description":"The idempotency key to use for the request (V4 UUID recommended)","example":"123e4567-e89b-12d3-a456-426614174000"},"required":false,"description":"The idempotency key to use for the request (V4 UUID recommended)","name":"Idempotency-Key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"productId":{"type":"string","example":"cmb04pd9m4005k6049b3elq6d","description":"The ID of the product to update"},"fields":{"type":"array","items":{"type":"object","properties":{"fieldId":{"type":"string","example":"placeholder_title","description":"The ID of the field to update. This is the ID of the field in the product design."},"type":{"type":"string","enum":["text","image"],"example":"text","description":"The type of the field. Currently only 'text' and 'image' are supported."},"value":{"type":"string","example":"Happy Birthday!","description":"The value of the field. This is the value that will be used to update the field. If the type is 'image', the value should be the URL of the image. If the type is 'text', the value should be the text to be displayed."}},"required":["fieldId","type","value"]}}},"required":["productId","fields"]}}}},"responses":{"202":{"description":"Artwork generation job started successfully. Use the job ID to check the status of the job.","content":{"application/json":{"schema":{"type":"object","properties":{"jobId":{"type":"string","example":"run_01234567890abcdef","description":"The job ID for tracking artwork generation progress"},"status":{"type":"string","enum":["PENDING_VERSION","WAITING_FOR_DEPLOY","QUEUED","EXECUTING","REATTEMPTING","FROZEN","COMPLETED","CANCELED","FAILED","CRASHED","INTERRUPTED","SYSTEM_FAILURE","DELAYED","EXPIRED","TIMED_OUT"],"example":"QUEUED","description":"The current status of the artwork generation job"}},"required":["jobId","status"]}}}},"400":{"description":"Returns an error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"422":{"description":"Data Validation Error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}}}}},"/v1/artwork/status/{jobId}":{"get":{"tags":["Artwork"],"summary":"Get Artwork Generation Status","operationId":"getArtworkStatus","description":"Check the status of an artwork generation job using the job ID returned from the create endpoint.","parameters":[{"schema":{"type":"string","example":"run_01234567890abcdef","description":"The job ID returned from the create artwork endpoint"},"required":true,"description":"The job ID returned from the create artwork endpoint","name":"jobId","in":"path"}],"responses":{"200":{"description":"Artwork generation status retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"jobId":{"type":"string","example":"run_01234567890abcdef","description":"The job ID"},"status":{"type":"string","enum":["PENDING_VERSION","WAITING_FOR_DEPLOY","QUEUED","EXECUTING","REATTEMPTING","FROZEN","COMPLETED","CANCELED","FAILED","CRASHED","INTERRUPTED","SYSTEM_FAILURE","DELAYED","EXPIRED","TIMED_OUT"],"example":"COMPLETED","description":"The current status of the job"},"artworkUrl":{"type":"string","example":"https://roastify-artwork.s3.us-east-1.amazonaws.com/outreach/01_artwork/1716537600000.jpeg","description":"The URL of the generated artwork (only present when status is COMPLETED). Must be HTTPS with valid image extension."},"error":{"type":"string","example":"Failed to generate artwork","description":"Error message (only present when status is FAILED)"}},"required":["jobId","status"]}}}},"404":{"description":"Job not found","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}}}}},"/v1/products":{"get":{"tags":["Products"],"summary":"Get All User Products","operationId":"getAllUserProducts","description":"Get all products in your Roastify Merchant account","parameters":[{"schema":{"type":"string","description":"The cursor to start from. This is the productId of the last product in the previous page. This can also be found in the `endCursor` property of the previous page's response.","example":"clyd67824rn3f78g0f8j9"},"required":false,"description":"The cursor to start from. This is the productId of the last product in the previous page. This can also be found in the `endCursor` property of the previous page's response.","name":"cursor","in":"query"},{"schema":{"type":"string","description":"The number of results to return. Defaults to 20 and maximum is 100","example":"10"},"required":false,"description":"The number of results to return. Defaults to 20 and maximum is 100","name":"pageSize","in":"query"}],"responses":{"200":{"description":"Returns all products in your Roastify Merchant account (paginated)","content":{"application/json":{"schema":{"type":"object","properties":{"products":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"clyd67824rn3f78g0f8j9","description":"The ID of the product"},"createdAt":{"type":"string","example":"2024-02-19T17:09:28.925Z","description":"The date and time the product was created in ISO format"},"title":{"type":"string","example":"12oz Coffee Box","description":"The title of the product"},"description":{"type":"string","description":"The description of the product"},"imageUrl":{"type":"string","example":"https://storage.roastify.app/mockup-images/a045d749-8372-44a0-aga3-098688ab6ad2.jpeg","description":"The artwork URL of the product (HTTPS only with valid image extension)"},"productType":{"type":"string","enum":["SampleBox","IndSample2oz","CoffeeBag12oz","CoffeeBox12oz","CoffeeBag5lb","Pods","InstantCoffee","Tubes"],"example":"CoffeeBox12oz","description":"The Catalog Product Type"},"images":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","example":"https://storage.roastify.app/mockup-images/a045d749-8372-44a0-aga3-098688ab6ad2.jpeg","description":"The URL of the image (HTTPS only with valid image extension)"}},"required":["url"]}},"variants":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"clyd67824rn3f78g0f8j9","description":"The id of the variant"},"title":{"type":"string","example":"Whole Bean","description":"The title of the variant"},"size":{"type":"string","description":"The size of the variant","example":"12oz"},"retailPrice":{"type":"number","description":"The retail price of the variant (in cents)","example":1200},"sku":{"type":"string","example":"COF-GND-12O-COL-BOX","description":"The SKU of the variant"},"inStock":{"type":"boolean","description":"Whether the variant is in stock","example":true},"stockQty":{"type":"number","description":"The quantity of the variant in stock. 999 for unlimited","example":999},"plan":{"type":"string","example":"pro","description":"The plan that is required to purchase the product"}},"required":["id","title","size","retailPrice","sku","inStock","stockQty","plan"]}}},"required":["id","createdAt","title","description","imageUrl"]}},"pageInfo":{"type":"object","properties":{"endCursor":{"type":"string","nullable":true},"hasNextPage":{"type":"boolean"}},"required":["hasNextPage"]}},"required":["products","pageInfo"]}}}},"400":{"description":"Returns an error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"404":{"description":"No Products Found","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"422":{"description":"Data Validation Error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}}}}},"/v1/products/{id}":{"get":{"tags":["Products"],"summary":"Get Product By ID","operationId":"getProductById","description":"Get a product by ID in your Roastify Merchant account","parameters":[{"schema":{"type":"string","example":"clyd67824rn3f78g0f8j9","description":"The ID of the product"},"required":true,"description":"The ID of the product","name":"id","in":"path"}],"responses":{"200":{"description":"Returns a product by ID in your Roastify Merchant account","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","example":"clyd67824rn3f78g0f8j9","description":"The ID of the product"},"createdAt":{"type":"string","example":"2024-02-19T17:09:28.925Z","description":"The date and time the product was created in ISO format"},"title":{"type":"string","example":"12oz Coffee Box","description":"The title of the product"},"description":{"type":"string","description":"The description of the product"},"imageUrl":{"type":"string","example":"https://storage.roastify.app/mockup-images/a045d749-8372-44a0-aga3-098688ab6ad2.jpeg","description":"The artwork URL of the product (HTTPS only with valid image extension)"},"productType":{"type":"string","enum":["SampleBox","IndSample2oz","CoffeeBag12oz","CoffeeBox12oz","CoffeeBag5lb","Pods","InstantCoffee","Tubes"],"example":"CoffeeBox12oz","description":"The Catalog Product Type"},"images":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","example":"https://storage.roastify.app/mockup-images/a045d749-8372-44a0-aga3-098688ab6ad2.jpeg","description":"The URL of the image (HTTPS only with valid image extension)"}},"required":["url"]}},"variants":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"clyd67824rn3f78g0f8j9","description":"The id of the variant"},"title":{"type":"string","example":"Whole Bean","description":"The title of the variant"},"size":{"type":"string","description":"The size of the variant","example":"12oz"},"retailPrice":{"type":"number","description":"The retail price of the variant (in cents)","example":1200},"sku":{"type":"string","example":"COF-GND-12O-COL-BOX","description":"The SKU of the variant"},"inStock":{"type":"boolean","description":"Whether the variant is in stock","example":true},"stockQty":{"type":"number","description":"The quantity of the variant in stock. 999 for unlimited","example":999},"plan":{"type":"string","example":"pro","description":"The plan that is required to purchase the product"}},"required":["id","title","size","retailPrice","sku","inStock","stockQty","plan"]}}},"required":["id","createdAt","title","description","imageUrl"]}}}},"400":{"description":"Returns an error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"404":{"description":"No Product Found","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"422":{"description":"Data Validation Error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"}},"required":["code","message"]}}}}}}}}}