Order Lifecycle & Status Updates

​

Order Status Lifecycle

pending → submitted_to_provider → accepted → scheduled →
in_progress → completed → active

pending → rejected
accepted → cancelled
in_progress → failed

​

Status Definitions

​

Initial States

• Order just created by reseller
• Awaiting provider review
• Your action: Review and accept or reject

• Order sent to your fulfillment system
• Awaiting confirmation
• Your action: Confirm receipt and accept or reject

​

Accepted States

• You’ve confirmed you can fulfill the order
• Customer info verified
• Your action: Schedule installation or activation

• Installation or activation date set
• Customer has been contacted
• Your action: Complete the installation on schedule

• Installation or setup actively happening
• Technician on-site or service being activated
• Your action: Complete installation and activate service

​

Completion States

• Installation finished successfully
• Service activated and tested
• Your action: None (terminal state)

• Service is live and active
• Ongoing service subscription
• Your action: Monitor for issues, provide support

​

Failure States

• Unable to fulfill the order
• Clear reason provided
• Your action: None (terminal state)

• Order cancelled after acceptance
• By provider or reseller request
• Your action: None (terminal state)

• Installation or activation failed
• Technical or logistical issues
• Your action: Document reason, coordinate with reseller on resolution

​

Updating Order Status

​

Via API

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": "scheduled",
    "providerNotes": "Installation scheduled for Tuesday, Jan 15 between 1-5 PM",
    "scheduledFor": "2025-01-15T13:00:00Z",
    "metadata": {
      "technicianName": "Mike Johnson",
      "technicianPhone": "+1-555-999-8888"
    }
  }'

​

Required vs. Optional Fields

• status - The new status value

• providerNotes - Human-readable update for reseller
• scheduledFor - When status is scheduled
• metadata - Additional context (tracking numbers, appointment details)

​

Common Workflows

​

Workflow 1: Standard Installation

{
  "status": "accepted",
  "providerNotes": "Order accepted. Customer will be contacted within 24 hours to schedule installation."
}

{
  "status": "scheduled",
  "providerNotes": "Installation scheduled for Jan 15, 1-5 PM",
  "scheduledFor": "2025-01-15T13:00:00Z",
  "metadata": {
    "appointmentWindow": "1-5 PM",
    "technicianName": "Mike Johnson"
  }
}

{
  "status": "in_progress",
  "providerNotes": "Technician on-site, installation in progress"
}

{
  "status": "active",
  "providerNotes": "Service activated successfully. Customer account #12345",
  "metadata": {
    "accountNumber": "12345",
    "activationDate": "2025-01-15"
  }
}

​

Workflow 2: Instant Activation (No Installation)

pending → accepted → active

{
  "status": "active",
  "providerNotes": "Policy activated immediately. Policy #POL-98765",
  "metadata": {
    "policyNumber": "POL-98765",
    "effectiveDate": "2025-01-02"
  }
}

​

Workflow 3: Rejection

{
  "status": "rejected",
  "providerNotes": "Service not available at this address. Building does not have fiber infrastructure. Cable internet available as alternative."
}

​

Workflow 4: Cancellation After Acceptance

{
  "status": "cancelled",
  "providerNotes": "Customer requested cancellation before installation. No fees charged."
}

​

Status Update Best Practices

​

Automated Status Updates

// Example: Update status when your CRM changes
async function onInstallationScheduled(workOrder) {
  await fetch(`https://api.offergrid.io/provider/orders/${workOrder.offergridItemId}/status`, {
    method: 'PATCH',
    headers: {
      'x-api-key': process.env.OFFERGRID_API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      status: 'scheduled',
      providerNotes: `Installation scheduled for ${workOrder.appointmentDate}`,
      scheduledFor: workOrder.appointmentDate,
      metadata: {
        workOrderId: workOrder.id,
        technicianId: workOrder.technicianId,
      },
    }),
  });
}

​

Monitoring Order Progress

• Acceptance rate: % of orders accepted vs. rejected
• Time to accept: How quickly you respond to new orders
• Completion rate: % of accepted orders successfully completed
• Average fulfillment time: Days from acceptance to activation

​

Next Steps