This is especially important for products that must be provisioned through an external API, such as software licences, gift cards, downloadable assets or travel eSIMs.

A typical workflow looks like this:

1. Shopify sends an orders/paid webhook.

2. A server receives the order.

3. The server calls an external provider API.

4. The digital product is created.

5. The customer receives the product by email.

The dangerous assumption is that the webhook will only be processed once.

The duplicate provisioning problem

Imagine the external provider successfully creates the product, but the response times out before our server receives it.

Our application may return an error to Shopify. The webhook is delivered again, and the second execution creates another product for the same order.

The customer may receive two products, while the merchant pays the supplier twice.

To prevent this, the workflow needs to be idempotent.

Creating a stable provisioning key

The Shopify webhook ID is useful for detecting repeated webhook deliveries, but the safest business-level key should also represent the resource being created.

For example:

const provisioningKey = `${order.id}:${lineItem.id}:${unitNumber}`;

This means that each unit of each line item has its own permanent provisioning identifier.

If an order contains three digital products, the workflow creates three different keys:

ORDER_ID:LINE_ITEM_ID:1
ORDER_ID:LINE_ITEM_ID:2
ORDER_ID:LINE_ITEM_ID:3

Why a simple KV lookup may not be enough

A basic implementation might first check whether a key exists and then save it:

const existing = await env.PROCESSED_JOBS.get(provisioningKey);

if (existing) {
  return new Response("Already processed", { status: 200 });
}

await env.PROCESSED_JOBS.put(provisioningKey, "processing");

The problem is concurrency.

Two Worker executions could read the missing value at approximately the same time. Both executions would then continue and call the external provider.

For operations that must happen exactly once, the reservation should be atomic.

Reserving the job with Cloudflare D1

A D1 table can use the provisioning key as its primary key:

CREATE TABLE provisioning_jobs (
  provisioning_key TEXT PRIMARY KEY,
  shopify_order_id TEXT NOT NULL,
  shopify_line_item_id TEXT NOT NULL,
  status TEXT NOT NULL,
  provider_reference TEXT,
  error_message TEXT,
  created_at TEXT DEFAULT CURRENT_TIMESTAMP,
  updated_at TEXT DEFAULT CURRENT_TIMESTAMP
);

The Worker can attempt to insert the job before calling the provider:

const result = await env.DB.prepare(`
  INSERT INTO provisioning_jobs (
    provisioning_key,
    shopify_order_id,
    shopify_line_item_id,
    status
  )
  VALUES (?, ?, ?, 'pending')
  ON CONFLICT(provisioning_key) DO NOTHING
`)
  .bind(
    provisioningKey,
    String(order.id),
    String(lineItem.id)
  )
  .run();

if (result.meta.changes === 0) {
  return new Response("Job already exists", { status: 200 });
}

Only one execution should successfully insert the key. Other executions see that the job already exists and stop before provisioning another product.

Separate webhook reception from provisioning

The webhook handler should remain small and fast:

export default {
  async fetch(request, env) {
    if (request.method !== "POST") {
      return new Response("Method not allowed", { status: 405 });
    }

    const order = await request.json();

    for (const lineItem of order.line_items ?? []) {
      for (let unit = 1; unit <= lineItem.quantity; unit++) {
        const provisioningKey =
          `${order.id}:${lineItem.id}:${unit}`;

        const result = await env.DB.prepare(`
          INSERT INTO provisioning_jobs (
            provisioning_key,
            shopify_order_id,
            shopify_line_item_id,
            status
          )
          VALUES (?, ?, ?, 'pending')
          ON CONFLICT(provisioning_key) DO NOTHING
        `)
          .bind(
            provisioningKey,
            String(order.id),
            String(lineItem.id)
          )
          .run();

        if (result.meta.changes > 0) {
          await env.PROVISIONING_QUEUE.send({
            provisioningKey,
            orderId: String(order.id),
            lineItemId: String(lineItem.id)
          });
        }
      }
    }

    return new Response("Accepted", { status: 200 });
  }
};

A queue consumer can then call the provider API, save the result and trigger email delivery.

Use a state machine

Each provisioning job should have an explicit status:

pending
provisioning
provisioned
email_pending
completed
failed
manual_review

Provisioning and email delivery should be treated as separate operations.

If the product has already been created but the email fails, the workflow should retry the email without calling the provider again.

Handling an unknown provider result

The hardest scenario occurs when the provider successfully creates the product but its response is lost.

The best solution is for the provider to support an idempotency key or searchable external reference.

Send the same provisioning key with every request:

body: JSON.stringify({
  externalReference: provisioningKey,
  productId,
  quantity: 1
})

Before retrying an uncertain request, query the provider using that external reference. If the product already exists, save the existing result instead of creating another one.

When the provider offers neither idempotency nor reference lookup, automatic retries can be dangerous. Jobs with uncertain outcomes should be moved to manual_review.

Final architecture

A robust digital fulfilment pipeline looks like this:

Shopify webhook
      ↓
Verify webhook
      ↓
Reserve unique provisioning job
      ↓
Queue the job
      ↓
Call provider API
      ↓
Store product details
      ↓
Send customer email
      ↓
Mark job as completed

This architecture is useful for any paid digital product where duplicate delivery creates a real cost.

At PuraSIM, we are exploring this type of architecture for automating travel eSIM fulfilment while keeping provisioning and customer communication independently retryable.