Order Lifecycle & Status Updates

Order Status Lifecycle

The workflow is deliberately short. A new order item arrives as pending, you accept or reject it, and once the service is live you mark it active:

pending → accepted → active

Or, if something goes wrong:

pending  → rejected     (you cannot fulfill it)
accepted → cancelled    (cancelled after acceptance)
accepted → failed       (fulfillment did not succeed)

Two notes on the happy path:

Use completed instead of active for one-time work with no ongoing subscription. An active item can also pass through completed first if you want to record install-done and service-live as separate moments.
You do not need to send submitted_to_provider. It is an optional “received, not yet decided” acknowledgement (the dashboard’s Mark received button) for teams whose intake and acceptance are separate steps. Accepting or rejecting straight from pending records the received time automatically.

The statuses scheduled and in_progress are not part of the workflow at the moment. The API rejects moves into them with a 409. Put appointment and progress details in providerNotes and metadata on the accepted item instead — resellers see every note you add.

Status Definitions

pending

Order just created by reseller
Awaiting your review
Your action: Accept or reject

submitted_to_provider (optional)

You have acknowledged receipt but not yet decided
Set it yourself if your intake and acceptance are separate steps; skip it otherwise
Your action: Accept or reject

accepted

You’ve confirmed you can fulfill the order
Any appointment or progress detail goes in providerNotes / metadata
Your action: Deliver the service, then mark it active (or completed)

completed

One-time work finished (for example an installation with no subscription), or install-done ahead of active
Your action: None, or mark active once the subscription is live

active

Service is live and the customer is using it
Your action: None (terminal state)

rejected

You cannot fulfill the order; include a clear reason
Can be flipped to accepted if it was a mistake
Your action: None

cancelled

Order cancelled after acceptance, by you or at the reseller’s request
Your action: None (terminal state)

failed

Fulfillment could not be completed
Can be reopened to pending for another attempt
Your action: Document the reason, coordinate with the reseller

Allowed Transitions

The API enforces the lifecycle. A PATCH to a status the current status cannot move to returns 409 Conflict with Cannot transition order item from "<from>" to "<to>" — see Errors. Sending the status the item is already in is a no-op 200, not a 409.

From	May move to
`pending`	`accepted`, `rejected`, `submitted_to_provider`, `handoff`, `cancelled`
`submitted_to_provider`	`accepted`, `rejected`, `cancelled`, `failed`
`handoff`	`accepted`, `rejected`, `submitted_to_provider`, `cancelled`, `failed`
`accepted`	`active`, `completed`, `rejected`, `cancelled`, `failed`
`completed`	`active`
`rejected`	`accepted`, `pending`, `cancelled`
`failed`	`pending`
`active`, `cancelled`	— (terminal)

rejected → accepted and accepted → rejected are both allowed so a mistaken call can be corrected after the fact.

Updating Order Status

Via API

Update order item status with a PATCH request:

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. Installation Tuesday, Jan 15 between 1-5 PM.",
    "metadata": {
      "appointmentWindow": "1-5 PM",
      "technicianName": "Mike Johnson",
      "technicianPhone": "+1-555-999-8888"
    }
  }'

Required vs. Optional Fields

Always required:

status - The new status value

Recommended:

providerNotes - Human-readable update for the reseller
metadata - Additional context (account numbers, appointment details, work-order ids)

Optional:

scheduledFor - An appointment or activation date/time (ISO 8601), if one applies

Common Workflows

Workflow 1: Standard Fulfillment

Order received

Status: pendingAction: Review order details and verify service availability

Accept order

Status: accepted

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

Appointment details, when you have them, go in a follow-up PATCH that keeps status: "accepted" and updates providerNotes / metadata.

Service live

Status: active (or completed for one-time work)

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

Workflow 2: Instant Activation (No Installation)

For services that activate immediately, such as electricity switches, the two calls can follow each other straight away. active still requires accepted first, so send both:

{ "status": "accepted", "providerNotes": "Enrollment confirmed." }

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

Workflow 3: Rejection

If you cannot fulfill:

{
  "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

If an accepted order must be cancelled:

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

Status Update Best Practices

Update status promptly

Update within hours of status changes, not days. Real-time updates build trust with resellers.

Always include notes

Use providerNotes to explain what happened and what happens next. Resellers relay this info to customers.

Include reference numbers

Add account numbers, work order IDs, or tracking numbers in metadata for future reference.

Be specific about failures

If rejecting or failing an order, clearly explain why and suggest alternatives when possible.

Use metadata for automation

Structure metadata consistently so resellers can parse and use it programmatically.

Automated Status Updates

Integrate Offergrid status updates into your existing systems:

// Example: mark the item active when your CRM activates the account
async function onServiceActivated(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: 'active',
      providerNotes: `Service live. Account ${workOrder.accountNumber}`,
      metadata: {
        workOrderId: workOrder.id,
        accountNumber: workOrder.accountNumber,
      },
    }),
  });
}

Monitoring Order Progress

Track order metrics in your dashboard:

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

Next Steps

Receiving Orders

Understanding incoming orders

Fulfillment Best Practices

Tips for smooth fulfillment

API Reference

View complete API documentation

Webhooks

Automate status updates

Getting Started

Managing Offers

Order Fulfillment

Partner Management

Integration

Order Lifecycle & Status Updates

Order Status Lifecycle

Status Definitions

Allowed Transitions

Updating Order Status

Via API

Required vs. Optional Fields

Common Workflows

Workflow 1: Standard Fulfillment

Workflow 2: Instant Activation (No Installation)

Workflow 3: Rejection

Workflow 4: Cancellation After Acceptance

Status Update Best Practices

Automated Status Updates

Monitoring Order Progress

Next Steps

Receiving Orders

Fulfillment Best Practices

API Reference

Webhooks

​Order Status Lifecycle

​Status Definitions

​Allowed Transitions

​Updating Order Status

​Via API

​Required vs. Optional Fields

​Common Workflows

​Workflow 1: Standard Fulfillment

​Workflow 2: Instant Activation (No Installation)

​Workflow 3: Rejection

​Workflow 4: Cancellation After Acceptance

​Status Update Best Practices

​Automated Status Updates

​Monitoring Order Progress

​Next Steps

Receiving Orders

Fulfillment Best Practices

API Reference

Webhooks

Order Status Lifecycle

Status Definitions

Allowed Transitions

Updating Order Status

Via API

Required vs. Optional Fields

Common Workflows

Workflow 1: Standard Fulfillment

Workflow 2: Instant Activation (No Installation)

Workflow 3: Rejection

Workflow 4: Cancellation After Acceptance

Status Update Best Practices

Automated Status Updates

Monitoring Order Progress

Next Steps