Receiving Orders

Overview

When resellers place orders for your services, you’ll receive structured order data with all the information needed to fulfill the customer request.

How You Receive Orders

Dashboard Notifications

View all incoming orders in your provider dashboard:

Navigate to Orders in the sidebar
See new orders marked as pending or submitted_to_provider
Click on an order to view full details
Take action (accept, reject, schedule)

API Polling

Retrieve orders programmatically:

curl -X GET "https://api.offergrid.io/provider/orders?status=pending" \
  -H "x-api-key: YOUR_API_KEY"

Filter by status to get orders that need attention:

pending - Newly submitted, awaiting acceptance
submitted_to_provider - Sent to your fulfillment system
accepted - Accepted and in progress

Webhook Notifications

Set up webhooks to receive real-time notifications when new orders arrive:

{
  "event": "order.created",
  "orderId": "ord-123-abc",
  "itemId": "item-456-def",
  "offerId": "off-789-ghi",
  "timestamp": "2025-01-02T10:00:00Z"
}

See Webhooks for setup instructions.

Order Structure

Each order contains:

Order Item Details

{
  "id": "item-456-def",
  "orderId": "ord-123-abc",
  "offerId": "off-789-ghi",
  "offerName": "High-Speed Internet 1000 Mbps",
  "status": "pending",
  "createdAt": "2025-01-02T10:00:00Z"
}

Customer Information

{
  "customerInfo": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@example.com",
    "phone": "+1-555-123-4567"
  }
}

Service Address

{
  "serviceAddress": {
    "street": "123 Main St",
    "city": "San Francisco",
    "state": "CA",
    "zipCode": "94102",
    "country": "US"
  }
}

Additional Details

{
  "notes": "Customer prefers afternoon installations",
  "metadata": {
    "referralSource": "property-listing",
    "unitNumber": "4B",
    "moveInDate": "2025-01-15"
  }
}

Every order that reaches you from a public checkout (the Offergrid shop, or a reseller’s shareable link) carries the customer’s contact-consent decisions, recorded at the moment they were made. Orders placed on a customer’s behalf by a reseller in their dashboard carry the reseller’s attestation instead.

Kind	Meaning	Required?
`order_contact`	You (and Offergrid) may contact the customer about this order by phone, text, and email.	Yes — the order cannot be placed without it
`marketing_calls_texts`	TCPA prior express written consent: you may call and text the customer with offers, including by autodialer and prerecorded or artificial voice.	No — optional, unchecked by default, never a condition of purchase

Each record includes the exact disclosure text the customer saw (with your team named in it), the phone number it binds to in E.164, the email, the timestamp, the channel, and — if withdrawn later — when and how.

No marketing_calls_texts record, or one with granted: false, means contact about the order only. Do not place autodialed or prerecorded marketing calls or texts to that number.

Where to find it:

Dashboard — the Contact consent card on each order.
API — GET /provider/orders/{itemId} returns order.consents[], filtered to the records that name your team.
Webhooks — subscribe to order.consent_recorded and order.consent_revoked; see Webhooks.

Revocation

A customer can withdraw consent by replying STOP to any text, through offergrid.io/opt-out, or by telling you directly. When it comes through Offergrid you receive order.consent_revoked. When it comes to you directly, report it back so the shared record stays true:

curl -X POST "https://api.offergrid.io/provider/customers/{customerId}/consent/revoke" \
  -H "x-api-key: YOUR_API_KEY"

This revokes every consent naming your team for that customer and flags them unsubscribed for you; consent they gave to other providers is unaffected. Honour a revocation within ten business days.

Order Workflow

When you receive an order:

Review Order Details

Check customer information, service address, and any special notes from the reseller

Verify Availability

Confirm that the service is available at the customer’s location

Accept or Reject

Update the order status to accepted if you can fulfill it, or rejected if not

Schedule Fulfillment

If accepted, schedule installation or activation and update status to scheduled

Complete Installation

After successful installation, update status to completed or active

Accepting Orders

To accept an order:

curl -X PATCH "https://api.offergrid.io/provider/orders/ITEM_ID/status" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "accepted",
    "providerNotes": "Order accepted. We will contact customer to schedule installation."
  }'

Include helpful notes in providerNotes to keep resellers informed about next steps.

Rejecting Orders

If you cannot fulfill an order, reject it with a clear reason:

curl -X PATCH "https://api.offergrid.io/provider/orders/ITEM_ID/status" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "rejected",
    "providerNotes": "Service not available at this address. Building does not have fiber infrastructure."
  }'

Common rejection reasons:

Service not available at location
Address outside service area
Technical limitations (building wiring, line of sight)
Credit check failure
Duplicate order

Order Filtering

Filter orders by status to focus on what needs attention:

# Get pending orders
GET /provider/orders?status=pending

# Get orders needing scheduling
GET /provider/orders?status=accepted

# Get active services
GET /provider/orders?status=active

Best Practices

Respond quickly

Accept or reject orders within 24 hours. Fast response times improve reseller satisfaction and customer experience.

Verify addresses carefully

Double-check service addresses before accepting. Address errors are a common cause of fulfillment delays.

Provide clear rejection reasons

When rejecting, explain why so resellers can address issues or find alternative solutions.

Include next steps

When accepting, tell resellers what happens next and when to expect follow-up.

Set up automated notifications

Use webhooks to integrate orders into your fulfillment systems automatically.

Monitor order volume

Track incoming order patterns to forecast capacity needs and staffing.

Automated Order Processing

For high-volume providers, consider automating order acceptance:

// Example: Auto-accept if service is available
async function processNewOrder(orderId: string) {
  const order = await getOrderDetails(orderId);
  const available = await checkServiceAvailability(order.serviceAddress);

  if (available) {
    await updateOrderStatus(orderId, {
      status: 'accepted',
      providerNotes: 'Auto-accepted. Customer will be contacted within 24 hours.',
    });

    // Trigger internal fulfillment workflow
    await scheduleInstallation(order);
  } else {
    await updateOrderStatus(orderId, {
      status: 'rejected',
      providerNotes: 'Service not available at this location.',
    });
  }
}

Next Steps

Order Workflow

Understanding the complete fulfillment lifecycle

Fulfillment Best Practices

Tips for smooth order fulfillment

Webhooks

Set up real-time order notifications

API Reference

View complete API documentation

Getting Started

Managing Offers

Order Fulfillment

Partner Management

Integration

Overview

How You Receive Orders

Dashboard Notifications

API Polling

Webhook Notifications

Order Structure

Order Item Details

Customer Information

Service Address

Additional Details

Revocation

Order Workflow

Accepting Orders

Rejecting Orders

Order Filtering

Best Practices

Automated Order Processing

Next Steps

Order Workflow

Fulfillment Best Practices

Webhooks

API Reference

​Overview

​How You Receive Orders

​Dashboard Notifications

​API Polling

​Webhook Notifications

​Order Structure

​Order Item Details

​Customer Information

​Service Address

​Additional Details

​Contact Consent

​Revocation

​Order Workflow

​Accepting Orders

​Rejecting Orders

​Order Filtering

​Best Practices

​Automated Order Processing

​Next Steps

Order Workflow

Fulfillment Best Practices

Webhooks

API Reference

Overview

How You Receive Orders

Dashboard Notifications

API Polling

Webhook Notifications

Order Structure

Order Item Details

Customer Information

Service Address

Additional Details

Contact Consent

Revocation

Order Workflow

Accepting Orders

Rejecting Orders

Order Filtering

Best Practices

Automated Order Processing

Next Steps