{"metadata":{"image":[],"title":"","description":""},"api":{"url":"/orders/schema.json","auth":"optional","results":{"codes":[{"name":"","code":"[\n  {\n    \"field\": \"order_id\",\n    \"required\": false,\n    \"readonly\": true,\n    \"name\": \"Order ID\",\n    \"description\": \"The ID of the order.\"\n  },\n  ...\n]","language":"json","status":200}]},"settings":"","examples":{"codes":[{"code":"curl https://tophatter.com/merchant_api/v1/orders/schema.json","language":"curl"},{"language":"ruby","code":"TophatterMerchant::Order.schema"},{"language":"php","code":"OrderApi::getSchema();"},{"language":"java","code":"List<Schema> schema = OrderApi.getSchema();"}]},"method":"get","params":[]},"next":{"description":"","pages":[]},"title":"Order Definition","type":"basic","slug":"order-schema","excerpt":"","body":"Orders returned by the Tophatter Merchant API have the following fields:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Field\",\n    \"h-1\": \"Name\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"`order_id`\",\n    \"2-0\": \"`carrier`\",\n    \"3-0\": \"`tracking_number`\",\n    \"6-0\": \"`product_name`\",\n    \"7-0\": \"`product_identifier`\",\n    \"9-0\": \"`variation_identifier`\",\n    \"11-0\": \"`customer_id`\",\n    \"0-1\": \"The ID of the order.\",\n    \"2-1\": \"The carrier (USPS, China EMS, etc) used to ship this order. The list of accepted carries can be found [here](doc:carriers).\",\n    \"3-1\": \"The tracking number provided by the carrier when this order was shipped.\",\n    \"6-1\": \"The name of the product.\",\n    \"7-1\": \"The unique id of the product.\",\n    \"9-1\": \"The unique id of the product variation selected by the customer during the checkout process.\",\n    \"11-1\": \"The unique ID of the customer.\",\n    \"12-0\": \"`customer_name`\",\n    \"12-1\": \"The full name of the customer.\",\n    \"13-0\": \"`address1`\",\n    \"14-0\": \"`address2`\",\n    \"15-0\": \"`city`\",\n    \"16-0\": \"`state`\",\n    \"17-0\": \"`postal_code`\",\n    \"18-0\": \"`country`\",\n    \"1-0\": \"`status`\",\n    \"1-1\": \"The status of the order. The status will be one of: `refunded`, `shipped` (already fulfilled), or `paid` (ready to fulfill).\",\n    \"13-1\": \"Shipping address line 1.\",\n    \"14-1\": \"Shipping address line 2.\",\n    \"15-1\": \"Shipping address city.\",\n    \"16-1\": \"Shipping address state.\",\n    \"17-1\": \"Shipping address postal code.\",\n    \"18-1\": \"Shipping address country.\",\n    \"0-2\": \"\",\n    \"1-2\": \"\",\n    \"2-2\": \"\",\n    \"3-2\": \"\",\n    \"6-2\": \"\",\n    \"7-2\": \"\",\n    \"9-2\": \"\",\n    \"11-2\": \"\",\n    \"12-2\": \"\",\n    \"13-2\": \"Shipping address line 1.\",\n    \"14-2\": \"Shipping address line 2.\",\n    \"15-2\": \"Shipping address city.\",\n    \"16-2\": \"Shipping address state.\",\n    \"17-2\": \"Shipping address postal code.\",\n    \"18-2\": \"Shipping address country.\",\n    \"21-0\": \"`disbursement_amount`\",\n    \"22-0\": \"`seller_fees_amount`\",\n    \"23-0\": \"`seller_fees`\",\n    \"21-1\": \"The total amount that will be paid out (disbursed) to the seller for this order.\",\n    \"22-1\": \"The total amount of the fees charged to the seller for this order.\",\n    \"23-1\": \"The breakdown of the fees charged to the seller for this order.\",\n    \"21-2\": \"The total amount that will be paid out (disbursed) to the seller for this order.\",\n    \"22-2\": \"The total amount of the fees charged to the seller for this order.\",\n    \"23-2\": \"The breakdown of the fees charged to the seller for this order.\",\n    \"19-0\": \"`available_refunds`\",\n    \"19-1\": \"The partial refunds available for this order. When you wish to partially refund an order you must specify on or more of these fees to refund. See the [refund an order](doc:refund-an-order) documentation for more info.\",\n    \"19-2\": \"The partial refunds available for this order. When you wish to partially refund an order you must specify on or more of these fees to refund. See the [refund an order](doc:refund-an-order) documentation for more info.\",\n    \"20-0\": \"`refund_amount`\",\n    \"20-1\": \"The amount refunded to the customer for this order.\",\n    \"20-2\": \"The amount refunded to the customer for this order.\",\n    \"26-0\": \"`created_at`\",\n    \"28-0\": \"`fulfillment_due_date`\",\n    \"26-1\": \"The date and time the order was created in PDT (UTC -7).\",\n    \"28-1\": \"The date by which this order must be fulfilled. If the order is not fulfilled by this date then it is considered late and the customer will be refunded upon request.\",\n    \"26-2\": \"The date and time the order refunded to the customer.\",\n    \"28-2\": \"The date and time the order was created.\",\n    \"8-0\": \"`product_internal_id`\",\n    \"8-1\": \"Tophatter's internal identifier for the product.\",\n    \"10-0\": \"`variation_internal_id`\",\n    \"10-1\": \"Tophatter's internal identifier for the product variation chosen by the customer during the checkout process.\",\n    \"10-2\": \"\",\n    \"8-2\": \"\",\n    \"24-0\": \"`upsells`\",\n    \"24-1\": \"The upsells for this product that were purchased by the customer.\",\n    \"24-2\": \"Shows the type of upsells a product lists, such as Buy one get one and additional accessory\",\n    \"27-0\": \"`paid_at`\",\n    \"27-1\": \"The date and time the order was paid by the customer in PDT (UTC -7).\",\n    \"27-2\": \"The date and time the order was paid by the customer.\",\n    \"29-0\": \"`refunded_at`\",\n    \"29-1\": \"The date and time the order was refunded to the customer in PDT (UTC -7). If the order has not been refunded this field will be `null`.\",\n    \"29-2\": \"The date and time order was canceled by the customer.\",\n    \"5-0\": \"`fulfillment_partner`\",\n    \"5-1\": \"The 3PL or warehouse partner being used to fulfill this order. Example: `noram`.\",\n    \"5-2\": \"\",\n    \"4-0\": \"`service_type`\",\n    \"4-1\": \"The granularity of tracking updates the carrier will provide for this tracking number. The list of supported service types per carrier can be found [here](doc:carrier-service-types). The full set of service types can be found [here](doc:service-types).\",\n    \"25-0\": \"`product_quantity`\",\n    \"25-1\": \"The quantity of product for this order. If a buyer purchased Buy One Get One same price then the `product_quantity` for the order will be 2.\",\n    \"30-0\": \"`canceled_at`\",\n    \"30-1\": \"The date and time order was canceled by the customer in PDT (UTC -7). If the order has not been canceled this field will be `null`.\"\n  },\n  \"cols\": 2,\n  \"rows\": 31\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Examples\"\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \" {  \\n    \\\"order_id\\\": 59010920,\\n    \\\"status\\\": \\\"paid\\\",\\n    \\\"carrier\\\": null,\\n   \\t\\\"service_type\\\": null,\\n    \\\"tracking_number\\\": null,\\n    \\\"product_name\\\": \\\"Nintendo Switch - Neon Blue and Red Joy-Con\\\",\\n    \\\"product_identifier\\\": \\\"B01MUAGZ49\\\",\\n    \\\"product_internal_id\\\": 9871345,\\n    \\\"variation_identifier\\\": \\\"B01MUAGZ49\\\",\\n    \\\"variation_internal_id\\\": 85741897,\\n    \\\"customer_id\\\": 19724374,\\n    \\\"customer_name\\\": \\\"John Doe\\\",\\n    \\\"address1\\\": \\\"123 Main Street\\\",\\n    \\\"address2\\\": \\\"Apartment 42\\\",\\n    \\\"city\\\": \\\"Denver\\\",\\n    \\\"state\\\": \\\"CO\\\",\\n    \\\"postal_code\\\": \\\"80219\\\",\\n    \\\"country\\\": \\\"USA\\\",\\n    \\\"available_refunds\\\": {  \\n       \\\"buyer_fee\\\": 275.0\\n    },\\n    \\\"refund_amount\\\": 0,\\n    \\\"disbursement_amount\\\": \\\"239.22\\\",\\n    \\\"seller_fees_amount\\\": 35.78,\\n    \\\"seller_fees\\\": [  \\n       {  \\n          \\\"type\\\": \\\"commission_fee\\\",\\n          \\\"amount\\\": 27.5\\n       },\\n       {  \\n          \\\"type\\\": \\\"processing_fee\\\",\\n          \\\"amount\\\": 8.28\\n       }\\n    ],\\n   \\t\\\"upsells\\\": [],\\n   \\t\\\"product_quantity\\\":1,\\n    \\\"created_at\\\": \\\"2018-03-29T17:04:17-07:00\\\",\\n   \\t\\\"updated_at\\\": \\\"2018-09-26T11:05:09-07:00\\\",\\n    \\\"paid_at\\\": \\\"2018-03-29T17:04:20-07:00\\\",\\n    \\\"fulfillment_due_date\\\": \\\"2018-04-04\\\",\\n    \\\"refunded_at\\\": null,\\n    \\\"canceled_at\\\": null\\n }\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Order Statuses\"\n}\n[/block]\nOrders will have one of the following statuses:\n\n- `refunded`: The order has been refunded.\n- `shipped`: The order has been fulfilled.\n- `paid`: The order is waiting to be fulfilled.","updates":[],"order":0,"isReference":false,"hidden":false,"sync_unique":"","link_url":"","link_external":false,"_id":"56a99246318e6c1700a19d06","parentDoc":null,"__v":13,"githubsync":"","project":"567f0c06143cc60d00c1fdbe","user":"567f0baca74a1c0d003e1fba","version":{"version":"1","version_clean":"1.0.0","codename":"","is_stable":true,"is_beta":false,"is_hidden":false,"is_deprecated":false,"categories":["567f0c07143cc60d00c1fdc2","56a9783109cb9c0d00f0c7d3","56a97837f834950d0037b363","56a9783b2d8fd90d0036eed6","56a979912d8fd90d0036eed8","5834b5691a80690f00d31faf","5834b5e4f775120f00c45f9d","5bf1a1473031e4005075ae14","5c64c200244bda003204b97f","6036b3ce32fcbe02eb8d7011","60f505090c9c97000f61acce"],"_id":"567f0c06143cc60d00c1fdc1","__v":11,"createdAt":"2015-12-26T21:52:06.734Z","releaseDate":"2015-12-26T21:52:06.734Z","project":"567f0c06143cc60d00c1fdbe"},"category":{"sync":{"isSync":false,"url":""},"pages":["56a99246318e6c1700a19d06","56a9924c257fbc0d00d4763a","56a9926bf834950d0037b381","56a99273257fbc0d00d4763c","56a992863b04f20d00ecca87","56a9928df834950d0037b383","56a992aff834950d0037b385","56a992d413a69a0d00a778de","56a9f82aca491e0d00eb8b12","56a9f959257fbc0d00d476c2"],"title":"Orders","slug":"orders","order":3,"from_sync":false,"reference":false,"_id":"56a9783b2d8fd90d0036eed6","version":"567f0c06143cc60d00c1fdc1","__v":10,"createdAt":"2016-01-28T02:08:59.138Z","project":"567f0c06143cc60d00c1fdbe"},"createdAt":"2016-01-28T04:00:06.545Z"}

API Usage

Products

Variations

Orders

Campaigns

Statistics

Attributes

Labels

Order Definition

Orders returned by the Tophatter Merchant API have the following fields: [block:parameters] { "data": { "h-0": "Field", "h-1": "Name", "h-2": "Description", "0-0": "`order_id`", "2-0": "`carrier`", "3-0": "`tracking_number`", "6-0": "`product_name`", "7-0": "`product_identifier`", "9-0": "`variation_identifier`", "11-0": "`customer_id`", "0-1": "The ID of the order.", "2-1": "The carrier (USPS, China EMS, etc) used to ship this order. The list of accepted carries can be found [here](doc:carriers).", "3-1": "The tracking number provided by the carrier when this order was shipped.", "6-1": "The name of the product.", "7-1": "The unique id of the product.", "9-1": "The unique id of the product variation selected by the customer during the checkout process.", "11-1": "The unique ID of the customer.", "12-0": "`customer_name`", "12-1": "The full name of the customer.", "13-0": "`address1`", "14-0": "`address2`", "15-0": "`city`", "16-0": "`state`", "17-0": "`postal_code`", "18-0": "`country`", "1-0": "`status`", "1-1": "The status of the order. The status will be one of: `refunded`, `shipped` (already fulfilled), or `paid` (ready to fulfill).", "13-1": "Shipping address line 1.", "14-1": "Shipping address line 2.", "15-1": "Shipping address city.", "16-1": "Shipping address state.", "17-1": "Shipping address postal code.", "18-1": "Shipping address country.", "0-2": "", "1-2": "", "2-2": "", "3-2": "", "6-2": "", "7-2": "", "9-2": "", "11-2": "", "12-2": "", "13-2": "Shipping address line 1.", "14-2": "Shipping address line 2.", "15-2": "Shipping address city.", "16-2": "Shipping address state.", "17-2": "Shipping address postal code.", "18-2": "Shipping address country.", "21-0": "`disbursement_amount`", "22-0": "`seller_fees_amount`", "23-0": "`seller_fees`", "21-1": "The total amount that will be paid out (disbursed) to the seller for this order.", "22-1": "The total amount of the fees charged to the seller for this order.", "23-1": "The breakdown of the fees charged to the seller for this order.", "21-2": "The total amount that will be paid out (disbursed) to the seller for this order.", "22-2": "The total amount of the fees charged to the seller for this order.", "23-2": "The breakdown of the fees charged to the seller for this order.", "19-0": "`available_refunds`", "19-1": "The partial refunds available for this order. When you wish to partially refund an order you must specify on or more of these fees to refund. See the [refund an order](doc:refund-an-order) documentation for more info.", "19-2": "The partial refunds available for this order. When you wish to partially refund an order you must specify on or more of these fees to refund. See the [refund an order](doc:refund-an-order) documentation for more info.", "20-0": "`refund_amount`", "20-1": "The amount refunded to the customer for this order.", "20-2": "The amount refunded to the customer for this order.", "26-0": "`created_at`", "28-0": "`fulfillment_due_date`", "26-1": "The date and time the order was created in PDT (UTC -7).", "28-1": "The date by which this order must be fulfilled. If the order is not fulfilled by this date then it is considered late and the customer will be refunded upon request.", "26-2": "The date and time the order refunded to the customer.", "28-2": "The date and time the order was created.", "8-0": "`product_internal_id`", "8-1": "Tophatter's internal identifier for the product.", "10-0": "`variation_internal_id`", "10-1": "Tophatter's internal identifier for the product variation chosen by the customer during the checkout process.", "10-2": "", "8-2": "", "24-0": "`upsells`", "24-1": "The upsells for this product that were purchased by the customer.", "24-2": "Shows the type of upsells a product lists, such as Buy one get one and additional accessory", "27-0": "`paid_at`", "27-1": "The date and time the order was paid by the customer in PDT (UTC -7).", "27-2": "The date and time the order was paid by the customer.", "29-0": "`refunded_at`", "29-1": "The date and time the order was refunded to the customer in PDT (UTC -7). If the order has not been refunded this field will be `null`.", "29-2": "The date and time order was canceled by the customer.", "5-0": "`fulfillment_partner`", "5-1": "The 3PL or warehouse partner being used to fulfill this order. Example: `noram`.", "5-2": "", "4-0": "`service_type`", "4-1": "The granularity of tracking updates the carrier will provide for this tracking number. The list of supported service types per carrier can be found [here](doc:carrier-service-types). The full set of service types can be found [here](doc:service-types).", "25-0": "`product_quantity`", "25-1": "The quantity of product for this order. If a buyer purchased Buy One Get One same price then the `product_quantity` for the order will be 2.", "30-0": "`canceled_at`", "30-1": "The date and time order was canceled by the customer in PDT (UTC -7). If the order has not been canceled this field will be `null`." }, "cols": 2, "rows": 31 } [/block] [block:api-header] { "title": "Examples" } [/block] [block:code] { "codes": [ { "code": " { \n \"order_id\": 59010920,\n \"status\": \"paid\",\n \"carrier\": null,\n \t\"service_type\": null,\n \"tracking_number\": null,\n \"product_name\": \"Nintendo Switch - Neon Blue and Red Joy-Con\",\n \"product_identifier\": \"B01MUAGZ49\",\n \"product_internal_id\": 9871345,\n \"variation_identifier\": \"B01MUAGZ49\",\n \"variation_internal_id\": 85741897,\n \"customer_id\": 19724374,\n \"customer_name\": \"John Doe\",\n \"address1\": \"123 Main Street\",\n \"address2\": \"Apartment 42\",\n \"city\": \"Denver\",\n \"state\": \"CO\",\n \"postal_code\": \"80219\",\n \"country\": \"USA\",\n \"available_refunds\": { \n \"buyer_fee\": 275.0\n },\n \"refund_amount\": 0,\n \"disbursement_amount\": \"239.22\",\n \"seller_fees_amount\": 35.78,\n \"seller_fees\": [ \n { \n \"type\": \"commission_fee\",\n \"amount\": 27.5\n },\n { \n \"type\": \"processing_fee\",\n \"amount\": 8.28\n }\n ],\n \t\"upsells\": [],\n \t\"product_quantity\":1,\n \"created_at\": \"2018-03-29T17:04:17-07:00\",\n \t\"updated_at\": \"2018-09-26T11:05:09-07:00\",\n \"paid_at\": \"2018-03-29T17:04:20-07:00\",\n \"fulfillment_due_date\": \"2018-04-04\",\n \"refunded_at\": null,\n \"canceled_at\": null\n }", "language": "json" } ] } [/block] [block:api-header] { "title": "Order Statuses" } [/block] Orders will have one of the following statuses: - `refunded`: The order has been refunded. - `shipped`: The order has been fulfilled. - `paid`: The order is waiting to be fulfilled.