Making requests¶

Every method works the same way:

HTTP method: POST
URL: {base_url}/{method_name}. See Endpoints.
Header: Content-Type: application/json
Body: a JSON object with your credentials and a data object

{
  "username": "YOUR_USERNAME",
  "password": "YOUR_PASSWORD",
  "secretkey": "YOUR_SECRET_KEY",
  "data": {
    "xid": "23542123"
  }
}

The fields inside data depend on the method. Each method's page lists them.

Responses¶

Responses are JSON. The res field tells you whether the call succeeded.

SuccessError

{
  "res": "success"
}

Some methods return extra fields alongside res, such as receipt_id from Add order.

{
  "res": "error",
  "code": "901",
  "message": "Invalid Login Details. Please Verify again."
}

See Errors.

Tip

Always check res in the response body. An error can come back with HTTP status 200.

Examples¶

These examples call Get status on the development environment.

cURLPHPPythonJavaScript (Node.js)

curl -X POST https://gatewaybeta.marcofinearts.com/v1/get_status \
  -H "Content-Type: application/json" \
  -d '{
    "username": "YOUR_USERNAME",
    "password": "YOUR_PASSWORD",
    "secretkey": "YOUR_SECRET_KEY",
    "data": { "xid": "23542123" }
  }'

<?php
$payload = [
    'username'  => 'YOUR_USERNAME',
    'password'  => 'YOUR_PASSWORD',
    'secretkey' => 'YOUR_SECRET_KEY',
    'data'      => ['xid' => '23542123'],
];

$ch = curl_init('https://gatewaybeta.marcofinearts.com/v1/get_status');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS     => json_encode($payload),
    CURLOPT_RETURNTRANSFER => true,
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

if ($response['res'] === 'success') {
    echo $response['order_status'];
} else {
    echo "Error {$response['code']}: {$response['message']}";
}

import requests

payload = {
    "username": "YOUR_USERNAME",
    "password": "YOUR_PASSWORD",
    "secretkey": "YOUR_SECRET_KEY",
    "data": {"xid": "23542123"},
}

r = requests.post("https://gatewaybeta.marcofinearts.com/v1/get_status", json=payload, timeout=30)
response = r.json()

if response["res"] == "success":
    print(response["order_status"])
else:
    print(f"Error {response['code']}: {response['message']}")

const payload = {
  username: "YOUR_USERNAME",
  password: "YOUR_PASSWORD",
  secretkey: "YOUR_SECRET_KEY",
  data: { xid: "23542123" },
};

const r = await fetch("https://gatewaybeta.marcofinearts.com/v1/get_status", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(payload),
});
const response = await r.json();

if (response.res === "success") {
  console.log(response.order_status);
} else {
  console.error(`Error ${response.code}: ${response.message}`);
}

Identifying orders¶

Methods that act on an existing order accept either of these IDs in data:

Field	Description
`xid`	Your own order number, sent as `xid` when you created the order.
`order_id`	The Marco Fine Arts order ID.

Dates¶

Dates use the format YYYY-MM-DD HH:MM:SS, for example 2026-12-23 21:56:51.