Shopify | Post-Order Webhook

Twikit provides a webhook endpoint that receives Shopify post-order notifications and automatically creates Twikit orders from saved product configurations. When a customer places an order on your Shopify store after customizing products with Twikit, the order is processed asynchronously in our system.

Setup

Get your webhook URL

Your organization-specific webhook URL follows this format:

https://api-gateway.twikit.com/product/order/api/v1/{organizationId}/shopify/orders

Replace {organizationId} with the organization ID provided by Twikit.

Configure the Shopify webhook

In your Shopify admin:

Go to Settings > Notifications > Webhooks
Click Create webhook
Select event: Order creation
Format: JSON
URL: your webhook URL from step 1

Line item requirements

Each customized line item in the Shopify order must include a _twikitConfigurationUuid property. This is the configuration UUID returned by Twikit when the customer saved their product customization.

The property must be set in the line item's properties array:

{
  "line_items": [
    {
      "properties": [
        {
          "name": "_twikitConfigurationUuid",
          "value": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        }
      ],
      "quantity": 1
    }
  ]
}

The underscore prefix (_) ensures the property is hidden from the customer in the Shopify storefront.

Behavior

Scenario	Result
Line item has `_twikitConfigurationUuid`	Included in the Twikit order
Line item without the property	Skipped (non-customized products are ignored)
`quantity > 1` on a line item	Creates that many order products with the same configuration
All line items lack the property	Returns `400 Bad Request`
Invalid or unknown configuration UUID	Returns `400 Bad Request`
Duplicate Shopify order (same order ID)	Returns `200` with existing order ID (no duplicate created)
Valid order	Returns `200 { "status": "accepted" }`

Error responses

Status	Meaning
`200`	Order accepted (or already exists)
`400`	Validation failed — missing configurations, invalid UUIDs, or no Twikit line items
`404`	Organization not found

Important notes

The webhook must receive a 200 response within Shopify's timeout window (~5 seconds). Order creation happens asynchronously after the response.
All configurations in a single order must belong to the same Twikit project.
The Shopify order id is stored as the external ID on the Twikit order for traceability.