Measura API documentation · v1
Send each logical write once, preserve its receipt, and reconcile uncertain outcomes before starting another write.
All kit writes and order edits/returns require a nonblank Idempotency-Key header of at most 255 characters. Use a unique key for each logical operation. The key is scoped to the authenticated shop and shared across these kit and order operation families. Its endpoint family, resource, method, and canonical request body must remain the same on a retry.
Authorization: Bearer apik_example_secret
Content-Type: application/json
Idempotency-Key: erp-order-1048-edit-1Kit and order operation receipts are permanent. Retrying a completed request with the same key and input returns its saved result with Idempotency-Replayed: true. Reusing the key for different input returns 409 idempotency_key_reused. A saved rejection also replays; a corrected request needs a new key after you resolve the rejection.
The fractional inventory endpoints have a separate 24-hour receipt policy. Do not apply that expiry to kit and order operations.
Order edits and returns require expectedRevision from a fresh GET /orders/{id}. Kit updates and deletions require the recipe’s exact revision. A revision conflict means the resource changed: read it again and decide whether the proposed change still applies before submitting a new logical operation with a new key.
Public order edits and returns share an order scope. Public recipe and production writes share a kit scope to enforce recipe limits and serialize production changes. These controls coordinate public API writes; Shopify Admin and other Measura workflows can still change the underlying resources.
A completed write returns data.operationId and data.operationStatus alongside its resource result. Use GET /operations/{operationId} to inspect any kit or order receipt, including recipe creation or deletion failures without a resource URL. Reads require the corresponding active add-on. Operation detail uses id and status; it can include phase, timestamps, snapshot, result, and error.
Scroll horizontally to see all columns.
| Status | Meaning | Next action |
|---|---|---|
| processing | Validation or execution is underway | Inspect status. Repeating the request returns 409 operation_in_progress with Retry-After: 2. A process crash can leave this state pending indefinitely. |
| completed | The saved result is authoritative | Use the saved result or replay the identical request with the same key. |
| rejected | Execution did not apply the operation | Inspect the saved error and correct the request before choosing a new key. The old key continues to replay its rejection. |
| requires_review | Changes may have applied | Inspect the receipt and actual Shopify state with support. Do not start the same operation under a new key. |
Phases are validating, applying, and finished. A 409 resource_in_progress means another operation owns the scope; this request had no effects and can retry its same key when the owner finishes. A 409 operation_requires_review means the outcome or its persistence is uncertain, even if the HTTP response reports failure.
After a timeout or lost reply, retry the exact request using its original key or retrieve its operation ID when available. Never generate a new key just to bypass a pending or review state. There is no transaction across Shopify, fractional inventory metadata, history, and operation storage; a failure does not imply rollback.
Uncertain operations retain ownership of their scope. There is no public force-unlock or generic resume endpoint. Contact support with the operation ID so the saved snapshot, inventory recovery records, and actual Shopify state can be reconciled before another write. Ownership does not expire automatically.
Order edits and operational returns do not collect outstanding payments or issue financial refunds. Handle payment settlement separately using the resulting totals.