API Docs

Send New Order

You call vGrubs

POSThttps://sandbox.vgrubs.com/partner/orders/{partner-name}

{partner-name} Your partner identifier, provisioned by vGrubs during onboarding. The webhook path is unique per partner.

When a customer places an order on your platform, you push it to the vGrubs webhook endpoint. vGrubs defines this path and shares it with you during onboarding. It is unique per partner.

vGrubs responds with HTTP 200 OK to confirm receipt. If you do not receive a 200, retry with exponential backoff.

The status field in the order payload must always be new on the initial push.

All monetary values are in cents (e.g. 3600 = $36.00). Timestamps are ISO 8601. Phone numbers use E.164 format.

The production URL is provided by vGrubs once the integration is fully tested and ready to go live.

Request body

orderobjectrequired

Core order details.

merchantobjectrequired

The store the order belongs to.

customerobjectrequired

Customer contact details.

itemsarrayrequired

Ordered items.

deliveryobject

Delivery details for delivery orders.

paymentobjectrequired

Payment details.

chargesobjectrequired

Order totals. All values in cents (e.g. 3600 = $36.00).

timestampsobjectrequired

Order lifecycle timestamps, ISO 8601.

Responses

200OK

Order received and accepted for processing.

successboolean

Whether the order was received successfully.

400Bad Request

Missing or invalid fields in the order payload.

401Unauthorized

Invalid or missing x-api-key header.

curl --request POST \
  --url https://sandbox.vgrubs.com/partner/orders/your-partner-name \
  --header 'content-type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --data '{
  "order": {
    "id": "ord_12345",
    "type": "delivery",
    "status": "new",
    "notes": "Leave at door",
    "paid": true,
    "asap": false,
    "add_disposable_items": true,
    "prep_time_minutes": 25
  },
  "merchant": {
    "id": "m_001",
    "name": "VGrubs Downtown"
  },
  "customer": {
    "name": "John Doe",
    "email": "[email protected]",
    "phone_number": "+14155552671",
    "phone_code": "1234"
  },
  "items": [
    {
      "id": "item_1",
      "name": "Cheeseburger",
      "quantity": 2,
      "base_price": 1250,
      "price": 2500,
      "instructions": "No onions",
      "options": [
        {
          "id": "opt_1",
          "name": "Extra cheese",
          "quantity": 2,
          "base_price": 150,
          "price": 300,
          "modifier_name": "Add-ons",
          "options": []
        }
      ]
    }
  ],
  "delivery": {
    "type": "provider",
    "status": "arriving",
    "notes": "Call on arrival",
    "address": {
      "country": "US",
      "street": "123 Main St",
      "city": "New York",
      "state": "NY",
      "zipcode": "10001",
      "unit_number": "Apt 4B",
      "latitude": 40.7128,
      "longitude": -74.006
    },
    "courier": {
      "name": "Mike Rider",
      "photo_url": "https://example.com/courier.jpg",
      "phone_number": "+14155550199",
      "status": "assigned"
    }
  },
  "payment": {
    "method": "card"
  },
  "charges": {
    "subtotal": 2800,
    "tax": 280,
    "tips": 300,
    "discount": 100,
    "delivery_fee": 200,
    "service_fee": 120,
    "total": 3600
  },
  "timestamps": {
    "placed_at": "2026-04-21T11:30:00.000Z",
    "accepted_at": "2026-04-21T11:32:00.000Z",
    "cancelled_at": null,
    "completed_at": null,
    "pickup_at": "2026-04-21T11:55:00.000Z",
    "delivery_at": null,
    "scheduled_for": null
  }
}'

Credentials

API key

Partner name

Credentials are stored only in this browser.

Request body

{
  "order": {
    "id": "ord_12345",
    "type": "delivery",
    "status": "new",
    "notes": "Leave at door",
    "paid": true,
    "asap": false,
    "add_disposable_items": true,
    "prep_time_minutes": 25
  },
  "merchant": {
    "id": "m_001",
    "name": "VGrubs Downtown"
  },
  "customer": {
    "name": "John Doe",
    "email": "john@example.com",
    "phone_number": "+14155552671",
    "phone_code": "1234"
  },
  "items": [
    {
      "id": "item_1",
      "name": "Cheeseburger",
      "quantity": 2,
      "base_price": 1250,
      "price": 2500,
      "instructions": "No onions",
      "options": [
        {
          "id": "opt_1",
          "name": "Extra cheese",
          "quantity": 2,
          "base_price": 150,
          "price": 300,
          "modifier_name": "Add-ons",
          "options": []
        }
      ]
    }
  ],
  "delivery": {
    "type": "provider",
    "status": "arriving",
    "notes": "Call on arrival",
    "address": {
      "country": "US",
      "street": "123 Main St",
      "city": "New York",
      "state": "NY",
      "zipcode": "10001",
      "unit_number": "Apt 4B",
      "latitude": 40.7128,
      "longitude": -74.006
    },
    "courier": {
      "name": "Mike Rider",
      "photo_url": "https://example.com/courier.jpg",
      "phone_number": "+14155550199",
      "status": "assigned"
    }
  },
  "payment": {
    "method": "card"
  },
  "charges": {
    "subtotal": 2800,
    "tax": 280,
    "tips": 300,
    "discount": 100,
    "delivery_fee": 200,
    "service_fee": 120,
    "total": 3600
  },
  "timestamps": {
    "placed_at": "2026-04-21T11:30:00.000Z",
    "accepted_at": "2026-04-21T11:32:00.000Z",
    "cancelled_at": null,
    "completed_at": null,
    "pickup_at": "2026-04-21T11:55:00.000Z",
    "delivery_at": null,
    "scheduled_for": null
  }
}

Response

200 OK

{
  "success": true
}