API Docs

Order Status Update

vGrubs calls you

POST{your_base_url}/orders/status

vGrubs calls this endpoint to notify your system when an order status changes. You must update the order on your side and return the updated order object in the response.

Request body

order_idstringrequired

The order ID from the original order payload.

merchant_idstringrequired

The partner's store ID.

statusstringrequired

New order status.

acceptedMerchant has accepted the order

completedOrder is ready for pickup by the driver or customer

cancelledOrder has been cancelled

prep_timenumberwhen status is accepted

Estimated prep time in minutes. Only sent when status is accepted.

Responses

200OK

successboolean

Whether the status update was applied successfully.

orderobject

The full updated order object with the new status applied.

400Bad Request

Missing or invalid fields in the request body.

401Unauthorized

Invalid or missing API key.

# vGrubs sends this request to your API. Run it against your server to test your implementation.
curl --request POST \
  --url https://api.yourplatform.com/orders/status \
  --header 'content-type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --data '{
  "order_id": "ord_12345",
  "merchant_id": "m_001",
  "status": "accepted",
  "prep_time": 15
}'

Credentials

API key

Partner name

Your API base URL

Credentials are stored only in this browser.

vGrubs sends this request to your API as events occur. Enter your public API base URL above and Try It delivers this exact payload to your server, so you can test your implementation live.

Request body

Enter your API base URL above to send the test request.

Response

200 OK

{
  "success": true,
  "order": {
    "order": {
      "id": "ord_12345",
      "type": "delivery",
      "status": "accepted",
      "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
    }
  }
}