Orders

Your orders, as staff see them. Money is in integer minor units; status, paymentStatus and fulfillmentStatus move independently.

Base URL: https://apiv2.venuerun.com/merchants/:merchantId/staff/orders

text

GET    /merchants/:merchantId/staff/orders
POST   /merchants/:merchantId/staff/orders
GET    /merchants/:merchantId/staff/orders/:orderId
PATCH  /merchants/:merchantId/staff/orders/:orderId
POST   /merchants/:merchantId/staff/orders/:orderId/refunds
GET    /merchants/:merchantId/staff/orders/:orderId/payments

The order object

Field	Type	Description
`id`	`string` (read-only)	Unique identifier, assigned by VenueRun.
`merchantId`	`string`
`status`	`"DRAFT" \| "SUBMITTED" \| "ACCEPTED" \| "COMPLETED" \| "CANCELED"`	Where the order is in its life. Not where the money is.
`paymentStatus`	`"UNPAID" \| "AUTHORIZED" \| "PARTIALLY_PAID" \| "PAID" \| "PARTIALLY_REFUNDED" \| "REFUNDED" \| "VOIDED"`	Where the money is.
`fulfillmentStatus`	`"PENDING" \| "IN_PROGRESS" \| "READY" \| "FULFILLED" \| "CANCELED"`	Where the food is.
`externalState`	`object \| null`	The provider's untranslated statuses, when this order came from one. Defaults to `null`.
`revision`	`integer`	Bumped on every accepted mutation, in the same transaction.
`fulfillment`	`object`
`paymentMethod`	`"card"`
`clients`	`object`	Defaults to `{}`.
`lineItems`	`object`	Defaults to `{}`.
`tip`	`object`	Defaults to `{"type":null}`.
`billingSummary`	`object \| null`	Defaults to `null`.
`testMode`	`boolean`	Defaults to `false`.

json

{
  "order": {
    "id": "hT16dlUsf9Xiwg9QPGRU",
    "merchantId": "MERCHANT_ID",
    "status": "SUBMITTED",
    "paymentStatus": "UNPAID",
    "fulfillmentStatus": "PENDING",
    "externalState": null,
    "revision": 2,
    "fulfillment": {
      "type": "PICKUP"
    },
    "paymentMethod": "card",
    "clients": {
      "42768e90-d4ff-7f34-4959-63176f262b98": {
        "clientId": "42768e90-d4ff-7f34-4959-63176f262b98",
        "name": "Guest",
        "isHost": true,
        "contact": null
      }
    },
    "lineItems": {
      "pTLpKTiGfq-xiUDLX77Hne": {
        "cartId": "pTLpKTiGfq-xiUDLX77Hne",
        "productId": "di9i6C5PPzcP7A7ZyCen",
        "title": "Staff product A1B2C3",
        "images": [],
        "quantity": 1,
        "unitPriceMinor": 1200,
        "modifiers": [],
        "taxes": [],
        "clientId": "42768e90-d4ff-7f34-4959-63176f262b98",
        "instructions": ""
      }
    },
    "tip": {
      "type": null
    },
    "billingSummary": {
      "currency": "USD",
      "lineItems": [
        {
          "cartId": "pTLpKTiGfq-xiUDLX77Hne",
          "productId": "di9i6C5PPzcP7A7ZyCen",
          "title": "Staff product A1B2C3",
          "images": [],
          "clientId": "42768e90-d4ff-7f34-4959-63176f262b98",
          "quantity": 1,
          "unitPriceMinor": 1200,
          "unitPriceWithModifiersMinor": 1200,
          "lineSubtotalMinor": 1200,
          "lineTotalMinor": 1200,
          "taxes": [],
          "taxTotalMinor": 0
        }
      ],
      "serviceFees": [
        {
          "id": "fee:platform",
          "title": "Platform Fee",
          "amountMinor": 99
        },
        {
          "id": "fee:convenience",
          "title": "Convenience Fee",
          "amountMinor": 300
        },
        {
          "id": "fee:processing",
          "title": "Processing Fee",
          "amountMinor": 78
        }
      ],
      "gratuity": null,
      "totals": {
        "subtotalMinor": 1200,
        "finalSubtotalMinor": 1200,
        "taxMinor": 0,
        "tipMinor": 0,
        "deliveryFeeMinor": 0,
        "convenienceFeeMinor": 300,
        "platformFeeMinor": 99,
        "applicationFeeMinor": 99,
        "processingFeeMinor": 78,
        "serviceFeesMinor": 477,
        "amountDueMinor": 1677
      }
    },
    "testMode": true
  }
}

List orders

GET /merchants/:merchantId/staff/orders

javascript

const merchantId = process.env.VENUERUN_MERCHANT_ID;
const response = await fetch(`https://apiv2.venuerun.com/merchants/${merchantId}/staff/orders?testMode`, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.VENUERUN_API_KEY}`,
  },
});

Response:

json

{
  "testMode": true,
  "length": 1,
  "nextCursor": "zTzg16jbzKlDjnq4QqoZ",
  "data": [
    {
      "order": {
        "id": "hT16dlUsf9Xiwg9QPGRU",
        "merchantId": "MERCHANT_ID",
        "status": "SUBMITTED",
        "paymentStatus": "UNPAID",
        "fulfillmentStatus": "PENDING",
        "externalState": null,
        "revision": 2,
        "fulfillment": {
          "type": "PICKUP"
        },
        "paymentMethod": "card",
        "clients": {
          "42768e90-d4ff-7f34-4959-63176f262b98": {
            "clientId": "42768e90-d4ff-7f34-4959-63176f262b98",
            "name": "Guest",
            "isHost": true,
            "contact": null
          }
        },
        "lineItems": {
          "pTLpKTiGfq-xiUDLX77Hne": {
            "cartId": "pTLpKTiGfq-xiUDLX77Hne",
            "productId": "di9i6C5PPzcP7A7ZyCen",
            "title": "Staff product A1B2C3",
            "images": [],
            "quantity": 1,
            "unitPriceMinor": 1200,
            "modifiers": [],
            "taxes": [],
            "clientId": "42768e90-d4ff-7f34-4959-63176f262b98",
            "instructions": ""
          }
        },
        "tip": {
          "type": null
        },
        "billingSummary": {
          "currency": "USD",
          "lineItems": [
            {
              "cartId": "pTLpKTiGfq-xiUDLX77Hne",
              "productId": "di9i6C5PPzcP7A7ZyCen",
              "title": "Staff product A1B2C3",
              "images": [],
              "clientId": "42768e90-d4ff-7f34-4959-63176f262b98",
              "quantity": 1,
              "unitPriceMinor": 1200,
              "unitPriceWithModifiersMinor": 1200,
              "lineSubtotalMinor": 1200,
              "lineTotalMinor": 1200,
              "taxes": [],
              "taxTotalMinor": 0
            }
          ],
          "serviceFees": [
            {
              "id": "fee:platform",
              "title": "Platform Fee",
              "amountMinor": 99
            },
            {
              "id": "fee:convenience",
              "title": "Convenience Fee",
              "amountMinor": 300
            },
            {
              "id": "fee:processing",
              "title": "Processing Fee",
              "amountMinor": 78
            }
          ],
          "gratuity": null,
          "totals": {
            "subtotalMinor": 1200,
            "finalSubtotalMinor": 1200,
            "taxMinor": 0,
            "tipMinor": 0,
            "deliveryFeeMinor": 0,
            "convenienceFeeMinor": 300,
            "platformFeeMinor": 99,
            "applicationFeeMinor": 99,
            "processingFeeMinor": 78,
            "serviceFeesMinor": 477,
            "amountDueMinor": 1677
          }
        },
        "testMode": true
      }
    }
  ]
}

Create a order

POST /merchants/:merchantId/staff/orders

No recorded example yet — the test suite does not call this endpoint.

javascript

const merchantId = process.env.VENUERUN_MERCHANT_ID;
const response = await fetch(`https://apiv2.venuerun.com/merchants/${merchantId}/staff/orders`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VENUERUN_API_KEY}`,
  },
});

Retrieve a order

GET /merchants/:merchantId/staff/orders/:orderId

javascript

const merchantId = process.env.VENUERUN_MERCHANT_ID;
const response = await fetch(`https://apiv2.venuerun.com/merchants/${merchantId}/staff/orders/cnBxb3Y9pL1h9EHxmFfI?testMode`, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.VENUERUN_API_KEY}`,
  },
});

Response:

json

{
  "order": {
    "id": "cnBxb3Y9pL1h9EHxmFfI",
    "merchantId": "MERCHANT_ID",
    "status": "SUBMITTED",
    "paymentStatus": "UNPAID",
    "fulfillmentStatus": "PENDING",
    "externalState": null,
    "revision": 2,
    "fulfillment": {
      "type": "PICKUP"
    },
    "paymentMethod": "card",
    "clients": {
      "39ffdc28-4778-4dcc-8682-808679ae7e5d": {
        "clientId": "39ffdc28-4778-4dcc-8682-808679ae7e5d",
        "name": "Guest",
        "isHost": true,
        "contact": null
      }
    },
    "lineItems": {
      "pTLpKTiGfq-xiUDLX77Hne": {
        "cartId": "pTLpKTiGfq-xiUDLX77Hne",
        "productId": "NU2GUCm99Woo1ImXWhHa",
        "title": "Staff product A1B2C3",
        "images": [],
        "quantity": 1,
        "unitPriceMinor": 1200,
        "modifiers": [],
        "taxes": [],
        "clientId": "39ffdc28-4778-4dcc-8682-808679ae7e5d",
        "instructions": ""
      }
    },
    "tip": {
      "type": null
    },
    "billingSummary": {
      "currency": "USD",
      "lineItems": [
        {
          "cartId": "pTLpKTiGfq-xiUDLX77Hne",
          "productId": "NU2GUCm99Woo1ImXWhHa",
          "title": "Staff product A1B2C3",
          "images": [],
          "clientId": "39ffdc28-4778-4dcc-8682-808679ae7e5d",
          "quantity": 1,
          "unitPriceMinor": 1200,
          "unitPriceWithModifiersMinor": 1200,
          "lineSubtotalMinor": 1200,
          "lineTotalMinor": 1200,
          "taxes": [],
          "taxTotalMinor": 0
        }
      ],
      "serviceFees": [
        {
          "id": "fee:platform",
          "title": "Platform Fee",
          "amountMinor": 99
        },
        {
          "id": "fee:convenience",
          "title": "Convenience Fee",
          "amountMinor": 300
        },
        {
          "id": "fee:processing",
          "title": "Processing Fee",
          "amountMinor": 78
        }
      ],
      "gratuity": null,
      "totals": {
        "subtotalMinor": 1200,
        "finalSubtotalMinor": 1200,
        "taxMinor": 0,
        "tipMinor": 0,
        "deliveryFeeMinor": 0,
        "convenienceFeeMinor": 300,
        "platformFeeMinor": 99,
        "applicationFeeMinor": 99,
        "processingFeeMinor": 78,
        "serviceFeesMinor": 477,
        "amountDueMinor": 1677
      }
    },
    "testMode": true
  }
}

Update a order

PATCH /merchants/:merchantId/staff/orders/:orderId

javascript

const merchantId = process.env.VENUERUN_MERCHANT_ID;
const response = await fetch(`https://apiv2.venuerun.com/merchants/${merchantId}/staff/orders/MQTc6iGes4Ox72z1qEBA?testMode`, {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.VENUERUN_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "fulfillmentStatus": "IN_PROGRESS"
  }),
});

Response:

json

{
  "order": {
    "id": "MQTc6iGes4Ox72z1qEBA",
    "merchantId": "MERCHANT_ID",
    "status": "SUBMITTED",
    "paymentStatus": "UNPAID",
    "fulfillmentStatus": "IN_PROGRESS",
    "externalState": null,
    "revision": 3,
    "fulfillment": {
      "type": "PICKUP"
    },
    "paymentMethod": "card",
    "clients": {
      "25aedf07-d618-9ff7-1fcc-c0c568dfd00a": {
        "clientId": "25aedf07-d618-9ff7-1fcc-c0c568dfd00a",
        "name": "Guest",
        "isHost": true,
        "contact": null
      }
    },
    "lineItems": {
      "ykcJQRjcBATizUcccrhKfU": {
        "cartId": "ykcJQRjcBATizUcccrhKfU",
        "productId": "HJ4BhB9h6fZm1kDhNbKg",
        "title": "Staff product A1B2C3",
        "images": [],
        "quantity": 1,
        "unitPriceMinor": 1200,
        "modifiers": [],
        "taxes": [],
        "clientId": "25aedf07-d618-9ff7-1fcc-c0c568dfd00a",
        "instructions": ""
      }
    },
    "tip": {
      "type": null
    },
    "billingSummary": {
      "currency": "USD",
      "lineItems": [
        {
          "cartId": "ykcJQRjcBATizUcccrhKfU",
          "productId": "HJ4BhB9h6fZm1kDhNbKg",
          "title": "Staff product A1B2C3",
          "images": [],
          "clientId": "25aedf07-d618-9ff7-1fcc-c0c568dfd00a",
          "quantity": 1,
          "unitPriceMinor": 1200,
          "unitPriceWithModifiersMinor": 1200,
          "lineSubtotalMinor": 1200,
          "lineTotalMinor": 1200,
          "taxes": [],
          "taxTotalMinor": 0
        }
      ],
      "serviceFees": [
        {
          "id": "fee:platform",
          "title": "Platform Fee",
          "amountMinor": 99
        },
        {
          "id": "fee:convenience",
          "title": "Convenience Fee",
          "amountMinor": 300
        },
        {
          "id": "fee:processing",
          "title": "Processing Fee",
          "amountMinor": 78
        }
      ],
      "gratuity": null,
      "totals": {
        "subtotalMinor": 1200,
        "finalSubtotalMinor": 1200,
        "taxMinor": 0,
        "tipMinor": 0,
        "deliveryFeeMinor": 0,
        "convenienceFeeMinor": 300,
        "platformFeeMinor": 99,
        "applicationFeeMinor": 99,
        "processingFeeMinor": 78,
        "serviceFeesMinor": 477,
        "amountDueMinor": 1677
      }
    },
    "testMode": true
  }
}

POST refunds

POST /merchants/:merchantId/staff/orders/:orderId/refunds

No recorded example yet — the test suite does not call this endpoint.

javascript

const merchantId = process.env.VENUERUN_MERCHANT_ID;
const response = await fetch(`https://apiv2.venuerun.com/merchants/${merchantId}/staff/orders/ORDER_ID/refunds`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VENUERUN_API_KEY}`,
  },
});

GET payments

GET /merchants/:merchantId/staff/orders/:orderId/payments

No recorded example yet — the test suite does not call this endpoint.

javascript

const merchantId = process.env.VENUERUN_MERCHANT_ID;
const response = await fetch(`https://apiv2.venuerun.com/merchants/${merchantId}/staff/orders/ORDER_ID/payments`, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.VENUERUN_API_KEY}`,
  },
});