{"metadata":{"image":[],"title":"","description":""},"api":{"url":"","auth":"required","results":{"codes":[]},"settings":"","params":[]},"next":{"description":"","pages":[]},"title":"Order Methods","type":"basic","slug":"order-methods","excerpt":"Order methods supported on the Merchant API","body":"The following methods operate on the [Order data model](doc:order).\n\n[block:html]\n{\n  \"html\": \"<div class=\\\"endpoint list\\\">\\n  <span class=\\\"method get\\\">GET</span>\\n  <span class=\\\"uri\\\">http://api.cratejoy.com/v1/orders/</span>\\n</div>\"\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"<div class=\\\"endpoint list\\\">\\n  <span class=\\\"method get\\\">GET</span>\\n  <span class=\\\"uri\\\">http://api.cratejoy.com/v1/orders/{order_id}</span>\\n</div>\"\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"<div class=\\\"endpoint list\\\">\\n  <span class=\\\"method put\\\">PUT</span>\\n  <span class=\\\"uri\\\">http://api.cratejoy.com/v1/orders/{order_id}/</span>\\n</div>\"\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"<div class=\\\"endpoint list\\\">\\n  <span class=\\\"method post\\\">POST</span>\\n  <span class=\\\"uri\\\">http://api.cratejoy.com/v1/orders/</span>\\n</div>\"\n}\n[/block]\n# List orders\n[block:html]\n{\n  \"html\": \"<div class=\\\"endpoint\\\">\\n  <span class=\\\"method get\\\">GET</span>\\n  <span class=\\\"uri\\\">http://api.cratejoy.com/v1/orders/</span>\\n</div>\"\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"$.ajax({     \\n  url: 'https://api.cratejoy.com/v1/orders/',\\n  method: 'GET'\\n});\",\n      \"language\": \"javascript\",\n      \"name\": \"List\"\n    },\n    {\n      \"code\": \"$.ajax({     \\n  url: 'https://api.cratejoy.com/v1/orders/?placed_at__gt=2017-03-15T20:00:24Z',\\n  method: 'GET'\\n})\",\n      \"language\": \"javascript\",\n      \"name\": \"Filtered List\"\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"count\\\": 1, \\n  \\\"next\\\": null, \\n  \\\"prev\\\": null, \\n  \\\"results\\\": [\\n    {\\n      \\\"card_refunded_amount\\\": 0,\\n      \\\"credit_applied\\\": 0,\\n      \\\"customer\\\": [{/*...*/}], // Customer relation property\\n      \\\"customer_id\\\": 586402305,\\n      \\\"financial_status\\\": \\\"paid\\\",\\n      \\\"fulfillment_status\\\": \\\"fulfilled\\\",\\n      \\\"gift_card_discount\\\": 0,\\n      \\\"gift_message\\\": \\\"\\\",\\n      \\\"gift_renewal_notif\\\": false,\\n      \\\"gross_shipping\\\": 0,\\n      \\\"id\\\": 730837920,\\n      \\\"is_gift\\\": true,\\n      \\\"order_gift_info\\\": {\\n\\t\\t\\t\\t\\\"gift_message\\\": \\\"I bought you a nice new sweater!\\\",\\n        \\\"gift_recipient_name\\\": \\\"Mr. Rogers\\\",\\n        \\\"gift_recipient_email\\\": \\\"fred:::at:::example.com\\\"\\n      },\\n      \\\"is_renewal\\\": false,\\n      \\\"is_test\\\": true,\\n      \\\"note\\\": null,\\n      \\\"placed_at\\\": \\\"2017-03-20T22:59:40Z\\\",\\n      \\\"products\\\": [{/*...*/}], /// Products relation property\\n      \\\"prorated_charge\\\": null,\\n      \\\"refund_applied\\\": null,\\n      \\\"refunded_amount\\\": 0,\\n      \\\"status\\\": \\\"closed\\\",\\n      \\\"store_id\\\": 644263166,\\n      \\\"sub_total\\\": 3500,\\n      \\\"total\\\": 3500,\\n      \\\"total_app_fees\\\": null,\\n      \\\"total_label_cost\\\": null,\\n      \\\"total_pending_fees\\\": null,\\n      \\\"total_price\\\": 3500,\\n      \\\"total_shipping\\\": 0,\\n      \\\"total_tax\\\": 0,\\n      \\\"transaction_fee\\\": 0,\\n      \\\"transaction_fee_status\\\": null,\\n      \\\"type\\\": \\\"order\\\",\\n      \\\"url\\\": \\\"/v1/orders/730837920/\\\"\\n    }\",\n      \"language\": \"json\",\n      \"name\": \"Response: 200 OK\"\n    }\n  ]\n}\n[/block]\n# Get an order\n[block:html]\n{\n  \"html\": \"<div class=\\\"endpoint\\\">\\n  <span class=\\\"method get\\\">GET</span>\\n  <span class=\\\"uri\\\">http://api.cratejoy.com/v1/orders/{order_id}</span>\\n</div>\"\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"$.ajax({     \\n  url: 'https://api.cratejoy.com/v1/orders/75572230/',\\n  method: 'GET'\\n});\",\n      \"language\": \"javascript\",\n      \"name\": null\n    }\n  ]\n}\n[/block]\n# Update an order\n[block:html]\n{\n  \"html\": \"<div class=\\\"endpoint\\\">\\n  <span class=\\\"method put\\\">PUT</span>\\n  <span class=\\\"uri\\\">http://api.cratejoy.com/v1/orders/{order_id}/</span>\\n</div>\"\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"$.ajax({\\n    url: 'https://api.cratejoy.com/v1/orders/75572230/',\\n   \\tmethod: 'PUT', \\n    data: {\\n      note: \\\"Drop package off at the front office\\\"\\n    }\\n});\",\n      \"language\": \"javascript\",\n      \"name\": null\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"$.ajax({\\n    url: 'https://api.cratejoy.com/v1/orders/75572230/',\\n   \\tmethod: 'PUT', \\n    data: {\\n      order_gift_info: { gift_message: \\\"Hi, I got you this gift.\\\" }\\n    }\\n});\",\n      \"language\": \"javascript\",\n      \"name\": null\n    }\n  ]\n}\n[/block]\nFor a complete list of editable properties see the [Order data model](doc:order) .\n\n# Create an order\n[block:html]\n{\n  \"html\": \"<div class=\\\"endpoint\\\">\\n  <span class=\\\"method post\\\">POST</span>\\n  <span class=\\\"uri\\\">http://api.cratejoy.com/v1/orders/</span>\\n</div>\"\n}\n[/block]\n### Create an order\n\n**Customer requirements**\n* Customer must already exist\n    * Use JSON filters to identify the customer\n    * In most cases, this will be the `id` but could using full filter syntax\n    * Filters MUST unambiguously identify ONE customer\n* Customer must have a payment method already established.\n\n**Product Requirements**\n* Include the subscription's product_instance ID\n* Include the subscription's term id or name/num_cycles. `name` indicates how often the customer is shipped a shipment, and `num_cycles` indicates the number of cycles the customer has prepaid. The term and number of cycles must be valid if the product is a subscription product. Term should not be provided for one-time products.\n\nTo prevent accidental duplicate charges, you cannot create an order for a customer who already has one from the past minute.\n\nIf you include an order_gift_info section, the order will automatically be set as a gift.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"$.ajax({\\n    url: 'https://api.cratejoy.com/v1/orders/',\\n    method: 'POST',\\n    data: {\\n      customer: {\\n        // Customer ID or Customer email address\\n        id: 586402305\\n      },\\n      ship_address_id: 8675309, // Optional\\n      cust_pay_id: 1234, // Optional\\n      coupons: ['CODE1', 'CODE2'], // Optional\\n      products: [{\\n       product_instance: {\\n          // The product instance ID\\n          id: 645769439\\n        },\\n        term: { // Only for subscription products\\n\\t\\t\\t\\t\\tnum_cycles: 1 // Prepayment term. (e.g. 3 for a 3 month prepay)\\n        },\\n        quantity: 1 // Optional; default is 1\\n      }],\\n      // Optional:\\n      order_gift_info: {\\n\\t\\t\\t\\tgift_message: 'I bought you a nice new sweater!',\\n        gift_recipient_name: 'Mr. Rogers',\\n        gift_recipient_email: 'fred@example.com'\\n        }\\n    }\\n});\",\n      \"language\": \"javascript\",\n      \"name\": \"\"\n    }\n  ]\n}\n[/block]","updates":[],"order":4,"isReference":false,"hidden":false,"sync_unique":"","link_url":"","link_external":false,"_id":"58112e72ded0340f0085d038","__v":0,"category":{"sync":{"isSync":false,"url":""},"pages":[],"title":"Merchant API Methods","slug":"merchant-api-methods","order":7,"from_sync":false,"reference":false,"_id":"58112e72ded0340f0085d032","project":"551e85be610f400d00837db7","__v":0,"version":"58112e71ded0340f0085d02a","createdAt":"2015-08-17T19:28:09.961Z"},"parentDoc":null,"createdAt":"2015-09-25T16:03:26.214Z","project":"551e85be610f400d00837db7","user":"55f2fd49b5b25021002b7dfd","version":{"version":"2.0","version_clean":"2.0.0","codename":"new designer","is_stable":true,"is_beta":false,"is_hidden":false,"is_deprecated":false,"categories":["58112e72ded0340f0085d02b","58112e72ded0340f0085d02c","58112e72ded0340f0085d02d","58112e72ded0340f0085d02e","58112e72ded0340f0085d02f","58112e72ded0340f0085d030","58112e72ded0340f0085d031","58112e72ded0340f0085d032","58112e72ded0340f0085d033","58112e72ded0340f0085d034","581137cc604d3c230048b7e4","58dc367221742d0f00a73f98","590768e54669da0f00db5c0b"],"_id":"58112e71ded0340f0085d02a","createdAt":"2016-10-26T22:30:09.862Z","project":"551e85be610f400d00837db7","releaseDate":"2016-10-26T22:30:09.862Z","__v":4},"githubsync":""}

Order Methods

Order methods supported on the Merchant API

The following methods operate on the [Order data model](doc:order). [block:html] { "html": "<div class=\"endpoint list\">\n <span class=\"method get\">GET</span>\n <span class=\"uri\">http://api.cratejoy.com/v1/orders/</span>\n</div>" } [/block] [block:html] { "html": "<div class=\"endpoint list\">\n <span class=\"method get\">GET</span>\n <span class=\"uri\">http://api.cratejoy.com/v1/orders/{order_id}</span>\n</div>" } [/block] [block:html] { "html": "<div class=\"endpoint list\">\n <span class=\"method put\">PUT</span>\n <span class=\"uri\">http://api.cratejoy.com/v1/orders/{order_id}/</span>\n</div>" } [/block] [block:html] { "html": "<div class=\"endpoint list\">\n <span class=\"method post\">POST</span>\n <span class=\"uri\">http://api.cratejoy.com/v1/orders/</span>\n</div>" } [/block] # List orders [block:html] { "html": "<div class=\"endpoint\">\n <span class=\"method get\">GET</span>\n <span class=\"uri\">http://api.cratejoy.com/v1/orders/</span>\n</div>" } [/block] [block:code] { "codes": [ { "code": "$.ajax({ \n url: 'https://api.cratejoy.com/v1/orders/',\n method: 'GET'\n});", "language": "javascript", "name": "List" }, { "code": "$.ajax({ \n url: 'https://api.cratejoy.com/v1/orders/?placed_at__gt=2017-03-15T20:00:24Z',\n method: 'GET'\n})", "language": "javascript", "name": "Filtered List" } ] } [/block] [block:code] { "codes": [ { "code": "{\n \"count\": 1, \n \"next\": null, \n \"prev\": null, \n \"results\": [\n {\n \"card_refunded_amount\": 0,\n \"credit_applied\": 0,\n \"customer\": [{/*...*/}], // Customer relation property\n \"customer_id\": 586402305,\n \"financial_status\": \"paid\",\n \"fulfillment_status\": \"fulfilled\",\n \"gift_card_discount\": 0,\n \"gift_message\": \"\",\n \"gift_renewal_notif\": false,\n \"gross_shipping\": 0,\n \"id\": 730837920,\n \"is_gift\": true,\n \"order_gift_info\": {\n\t\t\t\t\"gift_message\": \"I bought you a nice new sweater!\",\n \"gift_recipient_name\": \"Mr. Rogers\",\n \"gift_recipient_email\": \"fred@example.com\"\n },\n \"is_renewal\": false,\n \"is_test\": true,\n \"note\": null,\n \"placed_at\": \"2017-03-20T22:59:40Z\",\n \"products\": [{/*...*/}], /// Products relation property\n \"prorated_charge\": null,\n \"refund_applied\": null,\n \"refunded_amount\": 0,\n \"status\": \"closed\",\n \"store_id\": 644263166,\n \"sub_total\": 3500,\n \"total\": 3500,\n \"total_app_fees\": null,\n \"total_label_cost\": null,\n \"total_pending_fees\": null,\n \"total_price\": 3500,\n \"total_shipping\": 0,\n \"total_tax\": 0,\n \"transaction_fee\": 0,\n \"transaction_fee_status\": null,\n \"type\": \"order\",\n \"url\": \"/v1/orders/730837920/\"\n }", "language": "json", "name": "Response: 200 OK" } ] } [/block] # Get an order [block:html] { "html": "<div class=\"endpoint\">\n <span class=\"method get\">GET</span>\n <span class=\"uri\">http://api.cratejoy.com/v1/orders/{order_id}</span>\n</div>" } [/block] [block:code] { "codes": [ { "code": "$.ajax({ \n url: 'https://api.cratejoy.com/v1/orders/75572230/',\n method: 'GET'\n});", "language": "javascript", "name": null } ] } [/block] # Update an order [block:html] { "html": "<div class=\"endpoint\">\n <span class=\"method put\">PUT</span>\n <span class=\"uri\">http://api.cratejoy.com/v1/orders/{order_id}/</span>\n</div>" } [/block] [block:code] { "codes": [ { "code": "$.ajax({\n url: 'https://api.cratejoy.com/v1/orders/75572230/',\n \tmethod: 'PUT', \n data: {\n note: \"Drop package off at the front office\"\n }\n});", "language": "javascript", "name": null } ] } [/block] [block:code] { "codes": [ { "code": "$.ajax({\n url: 'https://api.cratejoy.com/v1/orders/75572230/',\n \tmethod: 'PUT', \n data: {\n order_gift_info: { gift_message: \"Hi, I got you this gift.\" }\n }\n});", "language": "javascript", "name": null } ] } [/block] For a complete list of editable properties see the [Order data model](doc:order) . # Create an order [block:html] { "html": "<div class=\"endpoint\">\n <span class=\"method post\">POST</span>\n <span class=\"uri\">http://api.cratejoy.com/v1/orders/</span>\n</div>" } [/block] ### Create an order **Customer requirements** * Customer must already exist * Use JSON filters to identify the customer * In most cases, this will be the `id` but could using full filter syntax * Filters MUST unambiguously identify ONE customer * Customer must have a payment method already established. **Product Requirements** * Include the subscription's product_instance ID * Include the subscription's term id or name/num_cycles. `name` indicates how often the customer is shipped a shipment, and `num_cycles` indicates the number of cycles the customer has prepaid. The term and number of cycles must be valid if the product is a subscription product. Term should not be provided for one-time products. To prevent accidental duplicate charges, you cannot create an order for a customer who already has one from the past minute. If you include an order_gift_info section, the order will automatically be set as a gift. [block:code] { "codes": [ { "code": "$.ajax({\n url: 'https://api.cratejoy.com/v1/orders/',\n method: 'POST',\n data: {\n customer: {\n // Customer ID or Customer email address\n id: 586402305\n },\n ship_address_id: 8675309, // Optional\n cust_pay_id: 1234, // Optional\n coupons: ['CODE1', 'CODE2'], // Optional\n products: [{\n product_instance: {\n // The product instance ID\n id: 645769439\n },\n term: { // Only for subscription products\n\t\t\t\t\tnum_cycles: 1 // Prepayment term. (e.g. 3 for a 3 month prepay)\n },\n quantity: 1 // Optional; default is 1\n }],\n // Optional:\n order_gift_info: {\n\t\t\t\tgift_message: 'I bought you a nice new sweater!',\n gift_recipient_name: 'Mr. Rogers',\n gift_recipient_email: 'fred@example.com'\n }\n }\n});", "language": "javascript", "name": "" } ] } [/block]