Skip to content

Add order

POST /v1/push_order

Creates a new order. Returns a receipt_id on success.

Request

Send username, password and secretkey along with a data object. See Making requests.

{
  "username": "YOUR_USERNAME",
  "password": "YOUR_PASSWORD",
  "secretkey": "YOUR_SECRET_KEY",
  "data": {
    "xid": "23542123",
    "ship_deadline": "2026-12-23 21:56:51",
    "isgift": "1",
    "gift_to": "John Doe",
    "gift_from": "Tom Doe",
    "message": "Happy Birthday John",
    "track_url": "https://www.example.com/?tracking=123456",
    "invoice": "https://www.example.com/invoice.html",
    "billing_address": {
      "company": "Acme Inc.",
      "name": "John Doe",
      "address": "123 Main Street",
      "address2": "Suite 100",
      "city": "Los Angeles",
      "zip": "90001",
      "state": "CA",
      "country": "US",
      "phone": "123-456-789",
      "email": "billing@example.com"
    },
    "shipping_address": {
      "company": "Acme Inc.",
      "name": "John Doe",
      "address": "123 Main Street",
      "address2": "Suite 100",
      "city": "Los Angeles",
      "zip": "90001",
      "state": "CA",
      "country": "US",
      "phone": "987-654-321",
      "email": "shipping@example.com"
    },
    "order_info": [
      {
        "type": "Canvas",
        "width": "18",
        "height": "24",
        "quantity": "1",
        "thumb_img": "https://www.example.com/img/preview_1.jpg",
        "large_img": "https://www.example.com/img/large_1.jpg",
        "item_cost": "18.00",
        "title": "My Canvas Print",
        "sku": "MYSKU"
      },
      {
        "type": "Paper",
        "width": "18",
        "height": "24",
        "quantity": "3",
        "thumb_img": "https://www.example.com/img/preview_2.jpg",
        "large_img": "https://www.example.com/img/large_2.jpg",
        "item_cost": "18.00",
        "title": "My Framed Print",
        "frame": "Black Frame",
        "top_mat": "White Mat",
        "media_width": "22",
        "media_height": "28",
        "sku": "MYSKU",
        "notes": "Any additional order notes"
      }
    ],
    "shipping": {
      "account": "124962153",
      "carrier": "FEDEX",
      "service": "FEDEX_GROUND",
      "packaging": "YOUR_PACKAGING",
      "notes": "please ship before christmas",
      "shipping_cost": "12.34"
    }
  }
}

# Save the request body above as request.json
curl -X POST https://gatewaybeta.marcofinearts.com/v1/push_order \
  -H "Content-Type: application/json" \
  -d @request.json

data fields

Field Required Validation Notes
xid Yes Must be unique — the same xid can't be submitted twice. Your (merchant) order number.
ship_deadline No YYYY-MM-DD HH:MM:SS, not in the past Validated only when passed.
isgift No 0 or 1
gift_to Conditional Required if isgift is 1.
gift_from Conditional Required if isgift is 1.
message Conditional Required if isgift is 1.
track_url No Valid URL
invoice No Valid URL
billing_address Yes Object Billing address — fields below.
billing_address.company Conditional Required if name is empty.
billing_address.name Conditional Required if company is empty.
billing_address.address Yes
billing_address.address2 No
billing_address.city Yes
billing_address.zip Yes
billing_address.state Yes State/province code Validated only when country is US or CA.
billing_address.country Yes ISO 3166-1 alpha-2 code
billing_address.phone No
billing_address.email No
shipping_address Yes Object Shipping address — fields below.
shipping_address.company Conditional Required if name is empty.
shipping_address.name Conditional Required if company is empty.
shipping_address.address Yes
shipping_address.address2 No
shipping_address.city Yes
shipping_address.zip Yes
shipping_address.state Yes State/province code Validated only when country is US or CA.
shipping_address.country Yes ISO 3166-1 alpha-2 code
shipping_address.phone No
shipping_address.email No
order_info Yes Array One object per order item.
order_info[].type Yes Product type, e.g. Canvas, Paper.
order_info[].width Yes Numeric Print width.
order_info[].height Yes Numeric Print height.
order_info[].media_width No Numeric Glass width.
order_info[].media_height No Numeric Glass height.
order_info[].quantity Yes Numeric
order_info[].thumb_img No Valid URL
order_info[].large_img Yes Valid URL Print-ready image.
order_info[].item_cost Yes Numeric Zero allowed.
order_info[].finishing No Type of finishing.
order_info[].edge_finishing No Edge finishing options.
order_info[].frame No Framing type.
order_info[].top_mat No Top mat name.
order_info[].middle_mat No Middle mat name.
order_info[].bottom_mat No Bottom mat name.
order_info[].title No Product title.
order_info[].product_description No
order_info[].color_scheme No
order_info[].basic_editing No
order_info[].sku No Product SKU.
order_info[].personalization No Personalization notes.
order_info[].notes No Extra notes for this item.
shipping Yes Object
shipping.account No Your shipping account number.
shipping.carrier Yes Valid carrier
shipping.service Yes Valid method code for the carrier
shipping.packaging No
shipping.notes No Extra shipping notes.
shipping.shipping_cost No Numeric

Response

{
  "res": "success",
  "receipt_id": "123456"
}

{
  "res": "error",
  "code": "000",
  "message": "Error message."
}

Error codes

Code Error Description
101 Authentication failed Your account is invalid or does not have API access. Check username, password and secretkey.
102 Missing field One or more required fields are missing.
103 Invalid URL One or more fields contain an invalid URL.
104 Invalid data type One or more fields must be numeric.
105 Invalid data type One or more fields must be integers.
106 Invalid format Date format must be YYYY-MM-DD HH:MM:SS.
107 Invalid data Date must be at least 5 days from today.
108 Invalid format Date format must be YYYY-MM-DD HH:MM:SS.
109 Invalid country Must be an ISO 3166-1 alpha-2 code.
110 Invalid state Invalid state code for US or Canada.
111 Invalid carrier Invalid shipping carrier. See shipping methods.
113 Invalid service type Invalid shipping method for the given carrier. See shipping methods.
121 Duplicate order An order with this xid already exists.