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. If your offer is set to finish on your own site (lead_gen with a signup template), a reseller placing it from their dashboard creates an order item in status Handed off, exactly as the consumer shop does. The reseller hands the customer a prefilled link to your site; the item id travels as og_click / click_id so your postback can map the signup back to it. You receive the usual email, in-app notice and order.item.created webhook (with "status": "handoff" in the payload). Once the customer completes signup on your side, accept the item against the order; reject it if they never do.

Training Orders

A reseller can mark an order as a training order when they place it, to practice the ordering flow or run a demo. You receive it exactly like a live order — same dashboard entry, same email, same webhook, same status transitions — so your team can rehearse fulfillment end to end. What tells you it is practice:

The dashboard shows a Training badge on the order and a notice at the top of the order page.
Email subjects are prefixed [Training]; in-app notifications are prefixed Training:.
Webhook deliveries carry "training": true inside data and an X-Offergrid-Training: true header. Live deliveries carry "training": false and no header, so route on either before you create anything downstream.

Training orders never count toward your dashboard metrics or commission, and the reseller can delete them when the session is over.

Deleted Orders

A reseller can delete an order (training or live) from their dashboard. The order disappears from your list and you receive an in-app notice naming the reseller and the offers; no email or webhook is sent for a deletion. An order on which commission has already been paid out cannot be deleted, only cancelled.

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

Training Orders

Deleted Orders

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

​Partner-Signup (Handoff) Items

​Training Orders

​Deleted Orders

​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

Partner-Signup (Handoff) Items

Training Orders

Deleted Orders

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