{"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\": \"`refunded_at`\",\n    \"28-0\": \"`created_at`\",\n    \"26-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    \"28-1\": \"The date and time the order was created in PDT (UTC -7).\",\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\": \"`canceled_at`\",\n    \"29-1\": \"The date and time order was canceled by the customer in PDT (UTC -7).\",\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  },\n  \"cols\": 2,\n  \"rows\": 30\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    \\\"refunded_at\\\": null,\\n    \\\"paid_at\\\": \\\"2018-03-29T17:04:20-07:00\\\",\\n    \\\"created_at\\\": \\\"2018-03-29T17:04:17-07:00\\\",\\n   \\t\\\"updated_at\\\": \\\"2018-09-26T11:05:09-07:00\\\",\\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"],"_id":"567f0c06143cc60d00c1fdc1","__v":9,"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

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": "`refunded_at`", "28-0": "`created_at`", "26-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`.", "28-1": "The date and time the order was created in PDT (UTC -7).", "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": "`canceled_at`", "29-1": "The date and time order was canceled by the customer in PDT (UTC -7).", "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." }, "cols": 2, "rows": 30 } [/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 \"refunded_at\": null,\n \"paid_at\": \"2018-03-29T17:04:20-07:00\",\n \"created_at\": \"2018-03-29T17:04:17-07:00\",\n \t\"updated_at\": \"2018-09-26T11:05:09-07:00\",\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.