POST New Orders
This route submits a new Direct Mail order and places it in User’s shopping cart. An order is consisted of one or more jobs. Each job is constructed by series of UUIDs and shipping data. Ship_from address is required when a job is drop-shipped.
All files must be identified by appropriate file-reason code. For more details about files and file reason codes please see Services/File Services section.
Resource URI
POST /orders
Input Parameters
@param order_id {String} order_id specified by the API user. (Required)
@param is_test_order {boolean} allows the user to submit test orders. Orders with is_test_order set to TRUE will not go to production. (Optional and default is set to FALSE)
@param coupon_code {string} allows user to pass a coupon-code that will apply to any resources qualified in the order based on coupon rules. Only one coupon per order is allowed (Optional)
@param skip_conformation {boolean} By setting this flag to TRUE the system will bypass conformation. If the flag is set to FALSE, an e-mail containing a HTML preview link is emailed to the authenticated user. (Optional and default set to FALSE)
@param job_name {string} Job name. (Required)
@param product_uuid {uuid} UUID of product. (Required)
@param runsize_uuid {uuid} UUID of runsize option. (Required)
@param turnaroundtime_uuid {uuid} UUID of product. (Optional - If not submitted, shortest free tunraround time will be selected)
@param colorspec_uuid {uuid} UUID of colorspec option. (Required)
@param option_uuids {uuid} array of option UUIDs to specify any options that may be required or optional. (Required field but can be empty array)
@param dropship {boolean} flag to identify if the job is being drop shipped. (Required)
@param skip_files {boolean} allows order submission without files. Files can be submitted later when the order comes in with this falg set to TRUE. (Optional)
@param files {string} URI to location of files or UUID of files POST-ed to 4over server. If skip_files is set to TRUE this parameter can be omitted. (Optional)
@param company {string} Ship_to Company Name. (Required if firstname and lastname are not provided)
@param firstname {string} Ship_to First Name. (Required if company is not provided)
@param lastname {string} Ship_to Last Name. (Required if company is not provided)
@param email {string} Ship_to Email. (optional)
@param phone {string} Ship_to Phone Number. (Required)
@param address {string} Ship_to address line. (Required)
@param address2 {string} Ship_to address2 line. (Optional)
@param city {string} Ship_to city. (Required)
@param state {string} Ship_to state. (Required)
@param zipcode {string} Ship-to zipcode. (Required)
@param country {string} Ship_to country. (Required)
@param company {string} Ship_from Company Name. (Required if ship-from present and firstname and lastname are not provided)
@param firstname {string} Ship_from First Name. (Required if ship-from present and company is not provided)
@param lastname {string} Ship_from Last Name. (Required if ship-from present and company is not provided)
@param email {string} Ship_from Email. (optional if ship-from is present)
@param phone {string} Ship_from Phone Number. (Required if ship-from is present)
@param address {string} Ship_from address line. (Required if ship-from is present)
@param address2 {string} Ship_from address2 line. (optional if ship-from is present)
@param city {string} Ship_from city. (Required if ship-from is present)
@param state {string} Ship_from state. (Required if ship-from is present)
@param zipcode {string} Ship_from zipcode. (Required if ship-from is present)
@param country {string} Ship_from country. (Required if ship-from is present)
@param ship_from_facility {string} Facility code of the production facility where the job will be shipped from. (RECOMMENDED to leave this parameter blank. Blank facility-code means to assign the closets facility to the Ship-to address that can produce the product/options combination)
@param direct_mailing {array} crid should be random number of 3-12 digits range, address_validation_level => none, CASS, NCOA.
@param product_type {string} product_type should be direct_mail, if placing direct mail order.
@param shipper {array} {"shipping_method":"MAILING - No Shipment", "shipping_code": "MAILING"}, if placing direct mail order.
Sample Request URI
html
https://api.4over.com/orders
Sample Request Body
NOTE:
Group-Shipping is available for same type products with the same stock, colorspec, coating and runsize. The base price route provides a “can_group_ship” flag to let users know what products are qualifid for group-shipping.
In sample request bellow “job001-001” and “job001-002” are grouped together for group-shipping and “job002-001”, “job002-002” and “job002-003” are groupped as a separate group-shipping job.
JSON
{
"order_id": "direct-mail-072624",
"skip_confirmation": "true",
"is_test_order": "true",
"jobs": [
{
"job_name": "direct-mail-4",
"product_uuid": "f80f1f73-2b5f-44ce-8d93-195852e8570b",
"runsize_uuid": "6237a36b-b046-4ef6-8fed-6cb9c22a5ece",
"turnaround_uuid": "ad290b77-c9d5-476c-b847-9ad4d25ae14e",
"colorspec_uuid":"32d3c223-f82c-492b-b915-ba065a00862f",
"product_type": "direct_mail",
"dropship": true,
"ship_to": {
"company": null,
"firstname": "Test",
"lastname": "Admin",
"email": "testuser@user.com",
"phone": "18777822737",
"address": "3700 OAKCLIFF RD",
"address2": "",
"city": "ATLANTA",
"state": "GA",
"zipcode": "30340-3405",
"country": "US"
},
"ship_from": {
"company": "4over",
"firstname": "",
"lastname": "",
"email": "",
"address": "4621 Sperry Street",
"address2": "",
"city": "Los Angeles",
"state": "CA",
"zipcode": "90039",
"country": "US",
"phone": "555-555-5555"
},
"shipper": {
"shipping_method": "MAILING - No Shipment",
"shipping_code": "MAILING"
},
"files": {
"fr": "c55a12e5-a8b4-4195-9dba-41bdd4f1eb56",
"vdf":"https://8b887e04-4eb5-46f4-b35f-e466e7723fbe.s3.us-west-1.amazonaws.com/OriginalMailingAddress-IcV3yPNZKIqD4CsUDuVf6Kt3uKijwZKR.csv"
},
"option_uuids": [
"2e53e1ae-5a15-42a2-8661-c1f8663f00bc",
"a1d764a6-1355-4b37-afbd-cf186e4c01a7",
"991b850a-6643-48d3-afa6-bcda4cf58c85",
"1abab393-e3e7-4af3-ad86-9ffa71c18d29",
"6f4fd47a-f70f-4f3d-84f8-a78ef9a62a5a",
"af66174e-4aa4-41ab-8fea-5dc8d7acbf65",
"1e8116af-acfc-44b1-83dc-8181aa338834",
"d3cc0d54-e72f-41ce-80c5-e8486bf2cdb8",
"6ffd6a6d-cd1d-47db-abab-670a2a6c8628"
],
"direct_mailing": {
"crid":"325235",
"address_validation_level": "none"
},
"bypass_address_validation": "true"
}
],
"payment": {
"profile_token": "XXXXXXXXX"
}
}
Sample Response
JSON
{
"order_status": "Success",
"customer_order_id": "direct-mail-072624",
"job_ids": {
"X4674081817-001": {
"customer_job_id": "direct-mail-4",
"status": 200,
"messages": []
}
},
"payment_response": {
"payment_uuid": "2e8201a0-8fe3-422b-a554-3434isds",
"payment_provider": {
"payment_provider_uuid": "a026b55c-4e33-4a35-80eb-sjdhj3hj",
"payment_provider": "DummyProvider",
"created_at": "2023-08-16 18:22:32.340083-07",
"updated_at": "2023-08-16 18:22:32.340083-07",
"deleted_at": null
},
"requested_amount": "138.95",
"requested_refund_amount": null,
"requested_currency": {
"currency_code": "USD",
"currency": "United States dollar",
"currency_number": "840",
"created_at": "2013-09-30 09:27:22.689216-07",
"updated_at": null,
"deleted_at": null
},
"request_transaction_code": null,
"request_data": "",
"requested_at": "2024-10-01T15:37:03+00:00",
"response_transaction_code": "55450a80-677e-470f-ac61-uausahgsva",
"response_data": null,
"responded_at": "2024-10-01T15:37:03+00:00",
"authorization_code": null,
"authorized_at": "2024-10-01T15:37:03+00:00",
"authorized_payment_amount": "138.95",
"authorized_refund_amount": 0,
"authorized_currency": {
"currency_code": "USD",
"currency": "United States dollar",
"currency_number": "840",
"created_at": "2013-09-30 09:27:22.689216-07",
"updated_at": null,
"deleted_at": null
},
"paying_organization": {
"organization_uuid": "bf972465-d0b2-4767-b350-wewsd3r3443dd",
"organization_name": "4over-test",
"organization_description": "4over-test",
"job_code_prefix": "Z",
"is_public_organization": true,
"primary_contact_user": {
"user_uuid": "6bc4fd59-839d-41ce-a32c-34fefd45f",
"first_name": "Test",
"last_name": "api",
"email": "v-testuser@4over.com",
"user_notes": "",
"created_at": "2022-03-03 12:55:01.328992-08",
"updated_at": "2022-03-03 12:55:01.328992-08",
"deleted_at": "",
"organizations": "https://sandbox-api.4over.com/users/6bc4fd59-839d-41ce-a32c-0acb04073ccf/organizations",
"logins": "https://sandbox-api.4over.com/users/6bc4fd59-839d-41ce-a32c-wasdda4da2b1/logins",
"token": "0911bdb7f48c0d0f58a9de3b19877faad0581856",
"timestamp": "0.92753600 1727797023",
"current_organization_uuid": "bf972465-d0b2-4767-b350-sdshjh33443"
},
"parent_organization": {
"organization_uuid": "d6d4e03e-7e88-4f69-9664-wasdda4da2b1",
"organization_name": "API",
"organization_description": "API Subsciber Organizations",
"job_code_prefix": "",
"is_public_organization": true,
"primary_contact_user": ""
}
},
"paying_user": {
"user_uuid": "6as4fd59-839d-41ce-a32c-asxasfdasas",
"first_name": "4overqasource",
"last_name": "api",
"email": "v-testest@4over.com",
"user_notes": "",
"created_at": "2022-03-03 12:55:01.328992-08",
"updated_at": "2022-03-03 12:55:01.328992-08",
"deleted_at": "",
"organizations": "https://sandbox-api.4over.com/users/6as4fd59-839d-41ce-a32c-wasdda4da2b1/organizations",
"logins": "https://sandbox-api.4over.com/users/6as4fd59-839d-41ce-a32c-wasdda4da2b1/logins",
"token": "1c2777fcb8dbecd63202ccca0e5cc23afd158a5f",
"timestamp": "0.92760100 1727797023",
"current_organization_uuid": "bf972465-d0b2-4767-b350-c3728c8cd6f5"
},
"created_at": "2024-10-01T15:37:03+00:00",
"updated_at": null,
"deleted_at": null
},
"payment_type": "authnet",
"errors": []
}
**If there are any failed jobs, the response will show either “Warning” or “Failed” for “order_status” and will appear as shown below:
If “order_status” is Warning or Failed, you have jobs that did not go through. Jobs in the “job_ids” array are the Successful jobs and do not need to get sent again. Any jobs in the “errors” array DO need to get fixed and resent to the order API.
{
"order_status": "Warning",
"job_ids": [
{
"internal_id": "X6327136040-001",
"customer_job_id": "93cc6db6-acd7-11e6-8635-0242ac110003-corporate"
}
],
....
....
"errors": [
{
"customer_order_id": "123456",
"customer_job_id": "YOUR_JOB_ID",
"internal_id": "Z12345678",
"message": "ERROR MESSAGE WILL GO HERE",
"job_status": "Failed"
}
]
}